Managing Artifacts

Managing Artifacts

Invariant Principles

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

Standard Directory Structure

~/.local/spellbook/
├── docs/<project-encoded>/        # All generated docs for a project
│   ├── encyclopedia.md            # Project overview for agent onboarding
│   ├── 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

Project-Specific CLAUDE.md

Fallback Lookup

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

Open Source Project Handling

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