Experimental — agent-oriented extensions. These skills are outside codegraph's core scope as a code intelligence engine. They orchestrate multi-step workflows that make decisions, modify code, and run automated pipelines — capabilities that go beyond codegraph's primary role of exposing dependency data to AI agents via MCP. Use them as reference implementations and starting points, not as production-grade automation. They may produce incorrect changes, miss edge cases, or behave unexpectedly on codebases with unusual structures. Always review their output before committing.

This directory contains example Claude Code skills that use codegraph to power autonomous codebase cleanup — based on the Titan Paradigm.

A single AI agent cannot hold an entire large codebase in context. The Titan Paradigm solves this with a phased approach where each phase:

1. Runs targeted codegraph queries (not raw file reads)
2. Writes structured artifacts to .codegraph/titan/
3. Next phase reads only those artifacts — not the original sources

/titan-run (orchestrator — runs everything below end-to-end via sub-agents)
      │
      ├─→ /titan-recon → titan-state.json + GLOBAL_ARCH.md
      │
      ├─→ /titan-gauntlet → gauntlet.ndjson (loops until complete)
      │
      ├─→ /titan-sync → sync.json (execution plan)
      │
      ├─→ /titan-forge → code changes + commits (loops phases)
      │       │
      │       └─→ /titan-gate (validates each commit)
      │
      ├─→ /titan-grind → adopts dead helpers from forge (Phase 4.5)
      │
      └─→ /titan-close → PRs + titan-report.md

/titan-reset (escape hatch: clean up everything)

Copy the skill directories into your project's .claude/skills/ directory:

# From your project root (assuming codegraph is installed)
mkdir -p .claude/skills
cp -r node_modules/@optave/codegraph/docs/examples/claude-code-skills/titan-* .claude/skills/

Then install codegraph if you haven't:

npm install -g @optave/codegraph
codegraph build .

/titan-run             # Runs the entire pipeline hands-free

The orchestrator dispatches each phase to a sub-agent with a fresh context window. Gauntlet and forge are looped automatically until complete. You can also resume from a specific phase:

/titan-run --start-from gauntlet          # Skip recon, resume gauntlet
/titan-run --start-from forge --yes       # Skip to forge, auto-confirm
/titan-run --gauntlet-batch-size 10       # Larger batches (if context allows)

/titan-recon           # Map the codebase, produce priority queue + embeddings
/titan-gauntlet 5      # Audit top targets in batches of 5
/titan-sync            # Plan shared abstractions and execution order
/titan-forge            # Execute next phase (re-run for each phase)
                       # (calls /titan-gate automatically per commit)

If GAUNTLET or FORGE runs out of context, just re-invoke — they resume from where they left off.

• /titan-recon always works standalone (builds graph fresh)
• /titan-gauntlet falls back to codegraph triage if no RECON artifact exists
• /titan-sync requires GAUNTLET artifacts (warns if missing)
• /titan-gate works with or without prior artifacts (uses default thresholds)
• /titan-reset cleans up everything — use when you want to start over

/titan-recon              # Once: map the codebase
/titan-gauntlet           # Once (or multiple sessions): audit everything
/titan-sync               # Once: plan the work

# Then for each phase:
/titan-forge               # Executes one phase, validates, commits
/titan-forge               # Re-run for next phase
/titan-forge               # ...until all phases complete

All artifacts are written to .codegraph/titan/ (11 files, no redundancy), plus the final report committed separately to generated/titan/:

NDJSON format (one JSON object per line) means partial results survive crashes mid-batch.

Tip: Add .codegraph/titan/ to .gitignore — these are ephemeral analysis artifacts. The final report (generated/titan/) is tracked in git.

Codegraph snapshots provide instant graph database backup/restore:

1. JSON over tables. All codegraph commands use --json for compact output.
2. Batch processing with resume. GAUNTLET processes 5 targets at a time (configurable), writes to NDJSON, stops at ~80% context. Re-invoking resumes automatically.
3. Artifact bridging. Each phase reads compact JSON artifacts, not raw source files.
4. codegraph batch <command> queries multiple targets in one call (e.g., batch complexity t1 t2 t3).
5. --above-threshold returns only functions exceeding thresholds — skip the noise.
6. No-test filtering. All commands use -T to exclude test files.

Run each /titan-* skill in a separate conversation if needed:

• Artifacts on disk bridge between conversations
• titan-state.json tracks progress, pending batches, and file audit status
• No context is lost because each phase's output is self-contained

Edit the Rule 1 threshold table in .claude/skills/titan-gauntlet/SKILL.md:

| Metric | Warn | Fail | Why |
|--------|------|------|-----|
| cognitive | > 15 | > 30 | How hard to understand |
| cyclomatic | > 10 | > 20 | How many paths to test |
| maxNesting | > 3 | > 5 | Flatten with guards |
| halstead.effort | > 5000 | > 15000 | Information-theoretic density |
| halstead.bugs | > 0.5 | > 1.0 | Estimated defect count |
| mi | < 50 | < 20 | Composite health |
| loc.sloc | > 50 | > 100 | Too long — split |

Adjust for your codebase — stricter for greenfield, more lenient for legacy code.

All skills enforce worktree isolation as their first step. If invoked from the main checkout, they stop and ask for /worktree. This prevents:

• Titan artifacts from polluting the main checkout
• Concurrent sessions from interfering
• Accidental commits of analysis artifacts

• Titan Paradigm Use Case — the full rationale and codegraph command mapping
• AI Agent Guide — general guide for using codegraph with AI agents
• MCP Examples — using codegraph via MCP for programmatic agent access
• Claude Code Hooks — automated hooks that complement these skills