codemap

Voice, tone, and format for the public Codemap docs (`apps/docs`, built with Blume). Use when authoring or editing apps/docs prose — landing, guides, concepts, recipes, reference, generated API — or deciding headline grammar, benefit framing, peer framing, or anti-pitch wording.

Repo-wide docs framework — what `docs/`, `docs/plans/`, `docs/research/`, `.agents/`, or any other doc-bearing surface in this repo looks like, what lifecycle each doc follows, and how to keep cross-references intact when slimming or moving content. Use when authoring or editing any `docs/**`, `docs/plans/**`, `docs/research/**`, `.agents/rules/**`, `.agents/skills/**`, or any new doc-bearing folder. Defines the lifecycle types (Reference / Roadmap / Plan / Audit / Research), the existence test every doc must pass, the closing-state lifecycles (delete + lift; never "Slim & keep in plans/"), the substrate variants (single `audit.md` vs `audits/<topic>.md`; conditional `glossary.md`), the surface tiers (repo-wide / per-tooling-area), and the cross-reference preservation discipline (grep before slim; preserve rule numbers cited from source). The Tier-2 priming layer at `.agents/rules/docs-governance.md` cites this skill and extends with codemap-specific bits only.

Bring a branch to pristine, maximum production readiness without changing PR intent — spawn parallel Task subagents (never inline review), fix in-bounds findings, loop autonomously until clean or pass cap, then report once. Use after a tracer-bullet commit (lite), before PR is done (full), on "harden", "harden-pr", "pristine", "review until clean", "production-ready pass", or "harden-pr reconcile". Invoking this skill authorizes one harden commit at cycle end. NEVER stop mid-loop to ask about commits, babysit, or the next pass. NEVER redesign the feature or change observable runtime behavior.

The product north-star — four Codemap tenets (structural over semantic, predicate-as-API, local-first / agent-native surfaces, honest scope). Use when making a design, API, or architecture decision, evaluating a trade-off, justifying a feature, or writing/reviewing a docs/plans entry.

Keep apps/docs in sync with merged product changes. On each run, audit recently merged PRs against docs content, update only drifted pages, regenerate API MDX when public exports/JSDoc drifted, verify with blume validate/check/build/audit, and open or update a docs/* PR — or report a clean no-op.

Delta-driven dependency upgrades — a script gathers the evidence, you read the artifact and judge. Use when the user asks to upgrade, bump, or CVE-audit dependencies.

Full tier assignments, pairing conventions, and authoring checklist for .agents/ rules and skills. Use when creating or reviewing a rule or skill, deciding Tier 1 vs 2 vs 3, or auditing attachment cost.

Which user-only agent workflow to run — grilling, docs-aware grilling, teaching, or meta authoring help.

Prose depth for comments, JSDoc, and docs — concise comments, preserve existing source comments.

Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression.

Operationalises the docs-governance lifecycle on demand — produces a per-file Tier-A (keep verbatim) / Tier-B (slim + keep) / Tier-C (delete + lift) classification with evidence and an executable plan, then carries out the user's chosen actions. Use when the user says "clean up stale docs", "doc sweep", "audit docs lifecycle", "compact audits", "are these audits / plans still earning their keep", "delete tombstones", "doc janitor", "what's gone stale in docs/", "promote / lift / retire <doc>", or asks to enforce the existence test against any `docs/**` or `.agents/**` surface. NEVER deletes a file without surfacing the classification + evidence + cross-reference impact for user approval first.

Build and sharpen the project's domain terminology inline or via a batch glossary scan. Use when pinning down ubiquitous language, recording a domain decision, grill-with-docs crystallises a term, or refreshing docs/glossary.md.

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

Grill a plan or design and update repo docs as decisions crystallise. Invokes grilling + domain-modeling inline; user-invoked only.

Relentlessly grill plans until shared understanding. Use when stress-testing a design or another skill delegates grilling.

Find deepening opportunities in the codebase, informed by the domain language in docs/glossary.md and the architecture in docs/architecture.md. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.

Triage and fact-check PR review comments against the actual codebase, project rules, and skills. Use when the user asks to address PR comments, respond to reviewer feedback, check if a comment is correct, fact-check a reviewer's claim, decide which comments to push back on, or sort hallucinated suggestions from real ones. Triggers on phrases like "check PR comments", "are these comments right", "review the PR feedback", "address comments on

Test-driven development with vertical tracer-bullet slices. Use when building test-first, red-green-refactor, or when the user mentions TDD.

Structured multi-session teaching — missions, lessons, retrieval practice.

Codemap feature layers and worked tracer-bullet examples — vertical slices for new source extensions, SQLite schema changes, and CLI flags. Use when planning a feature as a tracer bullet and deciding slice boundaries across CLI/parser/db/test/docs layers.

Per-file verification checklist — lint-staged and package.json scripts after each milestone.

Codemap repo hybrid deltas for .agents/ — tiers, rule-skill pairing, repo exemplars. Use when creating or reviewing rules/skills in this repo. Read writing-great-skills first for skill vocabulary and authoring principles.

Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable.

Audit a PR's structural choices against architecture-priming, the repo's own architecture.md, and any nested boundary configs. Use when the user says "audit this PR's architecture", "check the boundaries", "is this PR clean structurally", "post-merge review of

Query codebase structure via SQLite instead of scanning files. Use when exploring code, finding where symbols are defined, tracing who imports what, listing components / hooks / CSS variables / deprecated symbols, walking dependency or call graphs, or auditing structural changes on a PR.