Managing Artifacts Skill

Managing Artifacts

<ROLE> Artifact Organization Specialist. Your reputation depends on keeping projects clean and artifacts findable. Littering project directories with generated files is a cardinal sin. </ROLE> <CRITICAL> ALL generated documents, reports, plans, and artifacts MUST be stored outside project directories. This prevents littering projects with generated files and keeps artifacts organized centrally. </CRITICAL>

Invariant Principles

Never litter projects: Generated artifacts go to ~/.local/spellbook/, never project directories
Respect shared repos: Multi-contributor projects use fallback paths to avoid polluting the repo
Consistent encoding: Always use project-encoded paths for organization

<analysis> Before writing any artifact, determine: - What type of artifact is this? (plan, audit, report, etc.) - What is the project-encoded path? - Is this a multi-contributor project requiring fallback location? </analysis> <reflection> After artifact operations, verify: - File was written to correct spellbook directory, not project directory - Path follows naming conventions (YYYY-MM-DD prefix, etc.) - User was informed of file location </reflection>

Standard Directory Structure

~/.local/spellbook/
├── docs/<project-encoded>/        # All generated docs for a project
│   ├── encyclopedia.md            # Project overview for agent onboarding (deprecated)
│   ├── plans/                     # Design docs and implementation plans
│   │   ├── YYYY-MM-DD-feature-design.md
│   │   └── YYYY-MM-DD-feature-impl.md
│   ├── audits/                    # Test audits, code reviews, etc.
│   │   └── auditing-green-mirage-YYYY-MM-DD-HHMMSS.md
│   ├── understanding/             # Feature understanding documents
│   │   └── understanding-feature-YYYYMMDD-HHMMSS.md
│   └── reports/                   # Analysis reports, summaries
│       └── simplify-report-YYYY-MM-DD.md
├── distilled/<project-encoded>/   # Emergency session preservation
│   └── session-YYYYMMDD-HHMMSS.md
└── logs/                          # Operation logs
    └── review-pr-comments-YYYYMMDD.log

Project Encoded Path Generation

# Find outermost git repo (handles nested repos like submodules/vendor)
_outer_git_root() {
  local root=$(git rev-parse --show-toplevel 2>/dev/null)
  [ -z "$root" ] && { echo "NO_GIT_REPO"; return 1; }
  local parent
  while parent=$(git -C "$(dirname "$root")" rev-parse --show-toplevel 2>/dev/null) && [ "$parent" != "$root" ]; do
    root="$parent"
  done
  echo "$root"
}
PROJECT_ROOT=$(_outer_git_root)
PROJECT_ENCODED=$(echo "$PROJECT_ROOT" | sed 's|^/||' | tr '/' '-')
# Result: "Users-alice-Development-myproject"

If NO_GIT_REPO: Ask user to init, or use fallback: ~/.local/spellbook/docs/_no-repo/$(basename "$PWD")/

NEVER Write To

| Path | Why | |------|-----| | <project>/docs/ | Project docs are for project documentation | | <project>/plans/ | Reserved for project planning | | <project>/reports/ | Reserved for project reports | | <project>/*.md | Except CLAUDE.md when explicitly requested |

Project-Specific CLAUDE.md

Fallback Lookup

If project has no CLAUDE.md, check: ~/.local/spellbook/docs/<project-encoded>/CLAUDE.md

Open Source Project Handling

<RULE> For multi-contributor projects, NEVER add instructions to `<project>/CLAUDE.md`. Write to `~/.local/spellbook/docs/<project-encoded>/CLAUDE.md` instead. </RULE>

Detection (any of):

Has upstream git remote
Multiple authors (git shortlog -sn | wc -l > 1)
Has CONTRIBUTING.md
Is a fork

When user asks to "add X to CLAUDE.md" for such a project:

Detect if open source/multi-contributor
Write to fallback location instead
Inform user: "This appears to be a shared repository. Added to ~/.local/spellbook/docs/..."

Quick Reference

| Artifact Type | Location | |--------------|----------| | Design docs | ~/.local/spellbook/docs/<project>/plans/YYYY-MM-DD-feature-design.md | | Impl plans | ~/.local/spellbook/docs/<project>/plans/YYYY-MM-DD-feature-impl.md | | Audits | ~/.local/spellbook/docs/<project>/audits/ | | Reports | ~/.local/spellbook/docs/<project>/reports/ | | Encyclopedia (deprecated) | ~/.local/spellbook/docs/<project>/encyclopedia.md | | Session distill | ~/.local/spellbook/distilled/<project>/ | | Logs | ~/.local/spellbook/logs/ |

<FORBIDDEN> - Writing generated artifacts to project directories - Creating docs/, plans/, reports/ folders inside projects - Adding instructions to CLAUDE.md in multi-contributor repos - Using relative paths instead of project-encoded paths - Skipping the open source detection check </FORBIDDEN>

<FINAL_EMPHASIS> Every artifact you generate belongs in ~/.local/spellbook/, not in the project. A clean project is a professional project. There is no excuse for littering — not haste, not convenience, not ambiguity. </FINAL_EMPHASIS>

Agent Skills: Managing Artifacts

Install this agent skill to your local

Skill Files