/tune-repo

Make agents deeply effective in this repository.

Role

Staff engineer onboarding a new team member who happens to be an AI. Build the complete context an agent needs to work autonomously: what the project is, how it's built, what to watch out for, and how to ship.

Objective

Transform a repository from "generic Claude Code target" to "finely tuned agent workspace" where autonomous skills (/build, /autopilot, /pr-fix) operate with full project awareness.

Philosophy

CLAUDE.md is the constitution, not the encyclopedia. Keep it token-cheap.
Policy in tracked files. State in memory. Procedures in skills.
Granular summaries (Glance) feed system-level understanding (Cartographer).
Document invariants, not obvious mechanics.
Every gotcha captured now saves 10 agent iterations later.

Preconditions

Verify the repo is ready:

git rev-parse --is-inside-work-tree  # Must be a git repo
git remote get-url origin            # Need remote context

Read what already exists — don't overwrite good work:

# Check for existing docs
ls CLAUDE.md AGENTS.md docs/CODEBASE_MAP.md docs/adr/ 2>/dev/null || true

Workflow

Phase 1: Glance Scan (Fast, Cheap)

Generate bottom-up per-directory summaries. This gives agents granular navigation context.

# Check if glance is available
which glance

# Run glance on the repo root
glance

Glance produces .glance.md in each directory. These are cheap to generate (uses Gemini Flash) and provide fine-grained "what's in this folder" context. Glance skips directories that already have a .glance.md by default — intelligent regeneration is built in, so never pass -force.

If glance is not installed: Skip this phase. Cartographer works without it — just slower and more expensive since Sonnet subagents read raw files.

Phase 2: Cartographer (Comprehensive, Top-Down)

Invoke /cartographer to produce docs/CODEBASE_MAP.md.

Cartographer's Sonnet subagents will naturally discover and leverage the glance.md files from Phase 1, reducing the raw code they need to parse.

If docs/CODEBASE_MAP.md exists and is recent: Run Cartographer in update mode (it detects changes since last_mapped and only re-scans modified modules).

Output: System overview, architecture diagrams, module guide, data flow, conventions, gotchas, navigation guide.

Phase 3: CLAUDE.md Audit + Update

Read the current CLAUDE.md (if any). Read the Cartographer output. Synthesize.

CLAUDE.md must cover — and ONLY cover — these sections:

What This Is — 2-3 sentences. Purpose, users, business context.
Essential Commands — dev, build, test, lint, deploy. Copy-pasteable.
Architecture — High-level module diagram or description. Link to CODEBASE_MAP.md for details.
Tech Stack — Languages, frameworks, databases, key dependencies with versions.
Quality Gates — What CI enforces: coverage thresholds, lint rules, type strictness. The exact commands.
Gotchas — Things that trip agents up. Earned-by-pain knowledge. Be specific.
Environment — Required env vars, secrets, external services.
Deployment — How code gets to production.

Hard constraint: 200 lines max. Every line must earn its place. Link to docs/ for details. If CLAUDE.md exceeds 200 lines, you're writing an encyclopedia, not a constitution.

Preserve existing content that's accurate. Don't rewrite good prose — merge new findings.

Phase 4: AGENTS.md Scaffold

AGENTS.md is the operational playbook for AI agents. It covers what CLAUDE.md doesn't: how to work here.

Sections:

Commit Conventions — Message format, scope, conventional commits style.
Testing Guidelines — Framework, patterns, coverage targets, test location conventions.
PR Guidelines — Required sections, review expectations, merge strategy.
Coding Style — Beyond linting: naming patterns, module boundaries, abstraction philosophy.
Issue Workflow — Labels, status transitions, how to pick work.
Definition of Done — What "complete" means for an issue in this repo.
Security Boundaries — What agents must never touch without human approval.

If AGENTS.md already exists: Audit it against current reality. Fill gaps, correct drift.

If it doesn't exist: Create it. Pull conventions from git history (commit messages, PR descriptions) and existing CI config.

Phase 5: ADR Inventory

Scan for undocumented architectural decisions:

# Check existing ADRs
ls docs/adr/ 2>/dev/null || mkdir -p docs/adr

# Look for decision signals in git history
git log --oneline --all --grep="decision\|migrate\|replace\|switch\|deprecat" | head -20

# Look for decision signals in code
# (framework choices, database selection, auth strategy, API design)

For each significant decision found without an existing ADR:

# docs/adr/NNN-title.md

# NNN. Decision Title

Date: YYYY-MM-DD

## Status
Accepted

## Context
[Why was this decision needed?]

## Decision
[What was decided?]

## Consequences
[What are the implications — good and bad?]

Focus on decisions that would confuse a new agent:

Why this framework/library over alternatives?
Why this data model shape?
Why this deployment strategy?
Why this testing approach?

Limit: 5 ADRs max per tune-repo run. Don't boil the ocean. Capture the most impactful decisions.

Phase 6: Memory Seeding

Extract project-specific gotchas into the auto-memory file:

~/.claude/projects/<escaped-repo-path>/memory/MEMORY.md

Good memory entries:

CLI quirks specific to this project's toolchain
API/service gotchas discovered in git history or issue tracker
Flaky tests and their root causes
Environment setup footguns
Things that look wrong but are intentional

Bad memory entries:

Anything already in CLAUDE.md (don't duplicate)
Generic language/framework knowledge
Temporary state (current branch, active PR)

Phase 7.5: Guardrail Discovery

Analyze Cartographer output and codebase for architectural invariants worth enforcing as lint rules. Look for:

Import boundaries — Are there modules that should only be accessed through a facade? (e.g., DB through repository, API through client)
Auth patterns — Do handlers/routes consistently call an auth check? Any that don't?
Data access layers — Is there a clear separation (controller → service → repository)? Violations?
API conventions — Consistent route prefixes, response shapes, error formats?
Deprecated patterns — Old imports, legacy APIs, patterns being migrated away from?
Naming conventions — Beyond basic linting: domain-specific naming rules?

For each pattern found, output a recommendation:

Guardrail candidates:
- /guardrail "all DB access must go through repository layer" (3 violations found)
- /guardrail "API routes must use /api/v1 prefix" (0 violations — already clean, protect it)
- /guardrail "no direct fetch() — use apiClient wrapper" (7 violations found)

Do NOT generate rules here. /guardrail owns rule generation. This phase only discovers and recommends.

Phase 8: Skill Gap Analysis

Assess whether this repo needs project-specific skills:

Does it have a unique build/deploy pipeline that /build doesn't cover?
Does it use a CLI tool that agents invoke frequently? (e.g., Cerberus uses opencode)
Are there repetitive multi-step workflows specific to this domain?

If yes: document the gap as a recommendation. Don't build the skill in this run — that's a separate task.

# Report recommendation
echo "Skill gap: This repo could benefit from a custom /deploy-$REPO skill for [reason]"

Anti-Patterns

Writing CLAUDE.md as a novel (>200 lines = too long)
Overwriting accurate existing docs with generated prose
Creating ADRs for obvious decisions ("we use TypeScript because the project is TypeScript")
Seeding memory with speculative information (verify against actual code/tests)
Running Cartographer on a repo that was just mapped with no changes
Generating AGENTS.md conventions that contradict what git history shows

Output

Report:

Glance: directories scanned, summaries generated
Cartographer: CODEBASE_MAP.md created/updated
CLAUDE.md: sections added/updated, final line count
AGENTS.md: created or audited, sections covered
ADRs: new ADRs created (list titles)
Memory: entries seeded (list topics)
Guardrail candidates: patterns recommended for /guardrail
Skill gaps: recommendations (if any)