Skip to content

CLAUDE.md

Latest commit

 

History

History
61 lines (49 loc) · 4.26 KB

CLAUDE.md

File metadata and controls

61 lines (49 loc) · 4.26 KB
Raw

Capsule Kit v4.0

Context memory for Claude Code. Capsule (SQLite) stores session state automatically via JS hooks. No manual logging needed.

RULES

  1. Directory structure: NEVER create files in .claude/. Create in source dirs: tools/, hooks/, scripts/. The .claude/ directory is generated by install.
  2. Tool enforcement (enforced by PreToolUse hook):
    • Dependencies/imports: bash $HOME/.claude/cck/tools/query-deps/query-deps.sh <file>
    • Impact of changes: bash $HOME/.claude/cck/tools/impact-analysis/impact-analysis.sh <file>
    • Circular deps: bash $HOME/.claude/cck/tools/find-circular/find-circular.sh
    • Dead code: bash $HOME/.claude/cck/tools/find-dead-code/find-dead-code.sh
    • File search: Glob -- Code search: Grep
    • Large files (>50KB): $HOME/.claude/bin/progressive-reader --path <file> --list
    • Capsule context: bash $HOME/.claude/cck/tools/context-query/context-query.sh <command> [args]
      • Read: search <term>, files, agents, sessions, recent, stats
      • Write: save <ns> <title> <summary> [type], update <search> <new-summary>
    • NEVER use Task/Explore for dependency queries, file search, or code search.
  3. Agent routing: Use specialized agents via Task tool. Spawn in PARALLEL when independent.
    • Errors/bugs: error-detective | Debugging: debugger | Code review: code-reviewer
    • Refactoring: refactoring-specialist | Architecture: architecture-explorer
    • Security: security-engineer | Database: database-navigator | Git: git-workflow-manager
    • Production: devops-sre | Design: brainstorm-coordinator
    • Full list: 18 agents -- see docs/AGENT_ROUTING_GUIDE.md
  4. Skills: /workflow (complex tasks), /debug (errors/bugs), /deep-context (understand codebase), /code-review (pre-commit). Auto-activate on keywords.

Context System (Capsule)

Context is handled automatically. Hooks capture everything:

  • session-start.js: Injects last session summary, top discoveries, recent files, team activity (crew mode)
  • post-tool-use.js: Captures Read/Write/Edit operations and Task (sub-agent) invocations
  • session-end.js: Saves session summary with file/agent counts
  • pre-compact.js: Saves session continuity document before auto-compact
  • post-compact.js: Restores session continuity after auto-compact
  • pre-tool-use-read.sh: Large file blocking (>50KB), recent-read warnings, capsule context suggestions
  • pre-tool-use-task.sh: Dependency enforcement, file search suggestions, context-librarian suggestions
  • subagent-start.js: Injects crew context and relevant discoveries into subagent sessions
  • teammate-idle.js: Saves teammate state and triggers handoff context capture
  • worktree-lifecycle.js: Registers/deregisters worktrees, updates crew state (WorktreeCreate + WorktreeRemove)
  • stop-failure.js: Captures failure context and saves diagnostics for next session
  • stop.sh: Quality check after responses

Crew mode: Capsule is crew-aware. Shared capsule.db with teammate-scoped namespaces. See docs/AGENT_TEAMS_WORKTREE_MODE.md.

Wikilink Layer

Prose summaries written by hooks (handoffs, decisions, bug findings, agent invocations) are scanned for [[refs]] on save. Each resolved reference auto-creates an ALIAS record under <source>/aliases, scoped to the current project namespace (no cross-project bleed). Resolution is eager-only: a [[target]] whose record does not yet exist is dropped and does not auto-heal when the target appears later.

Query the graph:

  • bash $HOME/.claude/cck/tools/context-query/context-query.sh backlinks <title-or-path> — slash arg = path, else title. Returns LINKED (hard ALIAS records) + MENTIONED (FTS soft references).

Manual context-query save also runs wikilink extraction, so [[refs]] in saved summaries link the same way hook saves do.

Docs

  • docs/TOOL_ENFORCEMENT_REFERENCE.md -- Tool selection rules, progressive-reader workflows
  • docs/AGENT_ROUTING_GUIDE.md -- All 18 agents, routing rules, parallel spawning
  • docs/BEST_PRACTICES.md -- Anti-patterns, success metrics
  • docs/SUPER_CLAUDE_SYSTEM_ARCHITECTURE.md -- System design
  • docs/SKILLS_ORCHESTRATION_ARCHITECTURE.md -- Skills + hooks design
  • docs/CAPSULE_DEGRADATION_RCA.md -- Why v2 failed, what v3 fixes