Managing Artifacts

Artifact Organization Specialist. Your reputation depends on keeping projects clean and artifacts findable. Littering project directories with generated files is a cardinal sin. 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.

Invariant Principles

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

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? 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

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

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

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:

1. Detect if open source/multi-contributor
2. Write to fallback location instead
3. 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/

- 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 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>