# Codebase Context Skill

Context engineering middleware for Claude Code. Builds intelligent, token-efficient context for every user query by indexing the codebase locally and maintaining session state as MD files.

## Skills Tree (Start Here)

**Agents**: Read `SKILLS-TREE.md` first — it's the master index (~2.5K tokens) with all 23 skills, 6 categories, tags, dependencies, and token estimates. Only drill into `skills/<name>/SKILL.md` for the specific skill you need.

**Programmatic access**: Parse `manifest.json` for machine-readable skill/agent definitions (SDK, orchestrators, CI/CD).

**Agent lookup**: See `AGENTS-INDEX.md` for the 6 available agents with tool restrictions and parallel safety.

## Slash Commands

### Context Management
| Command | Purpose |
|---------|---------|
| `/ccs-init` | Deep-research the codebase, generate project-map, architecture, file-index, conventions |
| `/ccs-status` | Show what's indexed, staleness, file counts, token savings |
| `/ccs-refresh` | Rebuild index (full, incremental, or session-based per user preference) |
| `/ccs-query` | Preview which files would be selected for a given query |

### Workflow
| Command | Purpose |
|---------|---------|
| `/ccs-plan` | Plan a task with full dependency-aware context |
| `/ccs-build` | Create/implement with tracked context and commit-style logging |
| `/ccs-refactor` | Scope a refactor — identify all affected files and dependencies |
| `/ccs-fix` | Fix bugs with dependency tracking, root-cause analysis, and verification |
| `/ccs-team` | Spawn an agent team for complex multi-part tasks |

### Testing & Quality
| Command | Purpose |
|---------|---------|
| `/ccs-test` | Run tests, track results, suggest fixes, auto-fix failing tests |
| `/ccs-audit` | Audit code for security, performance, patterns, accessibility, dead code |
| `/ccs-review` | Code review with context — style, logic, security, performance checks |

### Research & Docs
| Command | Purpose |
|---------|---------|
| `/ccs-research` | Search official docs, resolve errors, check dependency health, find best practices |

### Setup
| Command | Purpose |
|---------|---------|
| `/ccs-connect` | Set up MCP server — creates/updates .mcp.json, configures remote tools endpoint, verifies connection |

### Git Workflow
| Command | Purpose |
|---------|---------|
| `/ccs-branch` | Create/switch branches with auto-generated context reference files |
| `/ccs-pr` | Prepare PR with full context — title, summary, blast radius, review areas |
| `/ccs-merge` | Merge with dependency checking — conflict prediction, resolution context |
| `/ccs-diff` | Smart diff with impact analysis — dependency chains, blast radius, categorization |
| `/ccs-sync` | Pull/rebase/push with conflict context and resolution recommendations |
| `/ccs-stash` | Stash with tracked context — remembers what you were working on |
| `/ccs-log` | Smart commit history — groups by branch, cross-references with task.md |

### Operations
| Command | Purpose |
|---------|---------|
| `/ccs-deploy` | Pre-deployment checklist — tests, build, env vars, dependencies, breaking changes |
| `/ccs-track` | View/manage session task log, see all changes made this session |

## Model Strategy
- **Haiku 4.5**: File scanning, index lookup, status checks, query preview, session tracking, stash, log
- **Sonnet 4.6**: Building features, fixing bugs, running tests, branch management, sync (standard coding execution)
- **Opus 4.6**: Initialization, planning, refactoring, auditing, code review, research, deployment, PR preparation, merge analysis, diff impact analysis (deep reasoning, architecture, complex analysis)

## Context Files (generated in `.ccs/`)
- `project-map.md` — File structure + dependency graph
- `architecture.md` — Tech stack, patterns, entry points, data flow
- `file-index.md` — Files ranked by importance/centrality
- `conventions.md` — Coding style, naming, testing patterns
- `task.md` — Session task log with commit-style entries
- `preferences.json` — User preferences (refresh mode, etc.)
- `branches/<name>.md` — Per-branch reference: purpose, changed files, diffs, dependencies
- `pulls/<name>.md` — PR documentation: summary, blast radius, review areas
- `merge-history.md` — Append-only merge log with conflict resolutions
- `commit-log.md` — Summarized commit history with task cross-references
- `team-board.md` — Multi-agent team task board with role assignments and integration log

## Key Directories
```
codebase-context-skill/
├── skills/          # All slash command definitions
├── agents/          # Subagent definitions
├── references/      # Strategy docs, quality standards, and feature docs
├── templates/       # MD templates for generated files
└── hooks/           # Claude Code hooks (session orient, auto-commit, validate, capture)
```

## STRICT RULES — Read Before Any Action

### NEVER modify or delete these paths:
- `ops/sessions/**` — Session records are **immutable** once written by `session-capture.sh`. A completed session is a permanent record. Never edit, overwrite, truncate, or delete session JSON files.
- `.claude/skills/ccs-*/**` — Installed skill plugin files. Never modify in-place. To update, reinstall from source.
- `hooks/scripts/**` and `hooks/hooks.json` — Hook scripts and manifest. Never modify as part of a build, refactor, or "cleanup" task.

### NEVER bulk-refactor these paths:
- `references/**` — System documentation. Individual file edits are allowed. **No bulk rename, mass delete, or wholesale replacement.** Scoped read/write/modify only — one file at a time.
- `skills/**` — Skill definitions. Targeted single-skill edits only. Never refactor all skills at once.
- `agents/**` — Agent definitions. Same rule as skills.

### When you see these paths, stop and scope your action:
- If asked to "refactor the skill plugin" or "clean up references" — **refuse**. Ask for a specific scoped change instead.
- If asked to delete sessions — **refuse unconditionally**.
- If a task would touch `references/` as a side-effect — only modify the specific file relevant to the task.

These rules are enforced by `hooks/scripts/path-guard.sh` (PreToolUse hook) which will block violations at runtime. The CLAUDE.md rules apply in addition to the runtime guard.

## Principles
1. **Never explore unnecessarily** — index first, read only what matters
2. **Local tools first** — Glob + Grep + Read before any API calls
3. **Everything persists locally** — MD files maintain context across the session
4. **Token guardrails** — smaller models for scanning, larger for thinking
5. **Commit-style tracking** — every change logged like a git commit locally
6. **Session rhythm** — Orient → Work → Persist cycle prevents context loss
7. **Processing pipeline** — Capture → Process → Connect → Verify for knowledge work
8. **Graph compounds quality** — well-connected notes are worth more than many orphaned ones
9. **Complexity at pain points** — activate features only when friction proves they're needed

## Hooks System (`hooks/`)

Automated lifecycle hooks for session management:

| Hook | Trigger | What It Does |
|------|---------|-------------|
| `path-guard.sh` | **PreToolUse** (Write/Edit/MultiEdit/Bash) | **Blocks** writes to immutable paths (ops/sessions/, installed skills, hook scripts). **Warns** on guarded paths (references/, skills/, agents/). |
| `session-orient.sh` | SessionStart | Injects workspace tree, goals, conditions, maintenance signals |
| `write-validate.sh` | PostToolUse (Write) | Validates YAML frontmatter on note files |
| `auto-commit.sh` | PostToolUse (Write, async) | Auto-commits changes to git after writes |
| `session-capture.sh` | Stop | Saves session state to ops/sessions/, commits artifacts |

Hooks only activate in CCS-enabled projects (detected via `.ccs` marker).

## Knowledge System Features (`references/`)

| Reference | Purpose |
|-----------|---------|
| `session-rhythm.md` | Orient-Work-Persist cycle, handoff protocol, anti-patterns |
| `processing-pipeline.md` | 4-phase pipeline: Capture → Process → Connect → Verify |
| `graph-analysis.md` | Query vault as graph DB using ripgrep — traversal, synthesis, density |
| `maintenance.md` | Condition-based health checks, reweaving, invariants |
| `self-evolution.md` | Friction-driven module adoption, observation/tension capture, lifecycle |
| `atomic-notes.md` | Prose-as-title pattern, composability test, schema |
| `topic-maps.md` | Navigation hubs, lifecycle, health metrics |
| `wiki-links.md` | Link philosophy, propositional semantics, dangling link policy |
| `self-space.md` | Agent identity/memory separate from user knowledge |
| `guardrails.md` | Privacy, transparency, autonomy — non-negotiable boundaries |

## Agents (`agents/`)

| Agent | Role |
|-------|------|
| `context-builder.md` | Deep codebase analysis, generates .ccs/ index files |
| `test-runner.md` | Runs tests, tracks results, auto-fixes failures |
| `code-auditor.md` | Security, performance, dead code, accessibility audits |
| `git-tracker.md` | Git workflow — branches, PRs, merges, diffs, sync |
| `knowledge-guide.md` | Proactive methodology guidance, note quality, connection suggestions |
| `team-lead.md` | Multi-agent team coordination, task decomposition, parallel dispatch |