@ai-agent-lead/skills 1.0.0

package/skills/SKILL-TEMPLATE.md

@@ -0,0 +1,120 @@
+# SKILL.md template
+
+Canonical scaffold for every skill in this set. Copy the body below into a new `<skill-name>/SKILL.md`, fill it in, then prune sections that genuinely don't apply (rather than leaving placeholders).
+
+The order is load-bearing. Claude scans top-to-bottom — `When to use` / `When to skip` should hit early so routing is decided before the reader gets to the body.
+
+## Naming and placement
+
+- File path: `skills/<skill-name>/SKILL.md` (lowercase, hyphenated directory).
+- Supporting reference docs in the same directory go UPPERCASE (`MOTIVATION.md`, `DEEPENING.md`, etc.).
+- Templates that callers fill in go in `<skill-name>/templates/` and stay lowercase (`feature-template.md`).
+- Format docs that more than one skill consumes belong in [`skills/formats/`](formats/), not in any one skill's directory.
+
+## Frontmatter rules
+
+```yaml
+---
+name: <kebab-case>
+description: <one paragraph: trigger phrases AND skip conditions AND adjacent skills>
+---
+```
+
+The `description` is the routing signal. It should:
+- Name what the skill does in one clause.
+- List trigger phrases ("Use when…", "Triggered by phrases like…").
+- List skip conditions ("Skip for…", "Use … instead when…").
+- Name 1–3 adjacent skills (upstream / downstream / lateral) so Claude can de-conflict.
+
+A `description` that names only the happy path will route falsely. Always name what to skip.
+
+## Canonical body shape
+
+```md
+# <Title>
+
+<Optional 1–2 sentences naming what the skill does and the *one* discipline at its core. Keep it tight — the description already covered the hook.>
+
+## Why this skill exists  (optional — include for skills that teach a discipline; skip for orchestration / utility skills)
+
+<2–4 sentences. Name the failure mode this skill prevents. Concrete > abstract.>
+
+## When to use
+
+- <trigger condition>
+- <trigger phrase>
+- <upstream signal — "<adjacent-skill> handed off"; "the user has <artifact>">
+
+## When to skip
+
+- <case where a different skill is the right answer; name that skill>
+- <case where no skill is needed at all — "just fix it">
+
+## Phases  (or **Process**, or **Workflow** — pick one and stick to it)
+
+### 1. <Phase name — verb-leading>
+
+<What happens in this phase. The output of the phase is named: a file, a finding, a decision.>
+
+### 2. <Phase name>
+
+<...>
+
+## Anti-patterns
+
+- **<Name of the failure mode>.** <One sentence on what it looks like in practice and why it's wrong.>
+- ...
+
+## Pairing with other skills
+
+- **`<upstream-skill>`** — runs before. <One line on what hand-off looks like.>
+- **`<downstream-skill>`** — runs after. <One line.>
+- **`<lateral-skill>`** — applies alongside. <One line.>
+
+## Done when
+
+- <Verifiable condition — not "the skill was applied" but "the artifact exists / the named region is identified / the green test pins the bug">.
+- ...
+
+## Handoff  (optional — include when the skill clearly feeds into another)
+
+<One sentence per branch. "If <condition> → run `<next-skill>`."> 
+```
+
+## Section requirements
+
+| Section | Required | Notes |
+| --- | --- | --- |
+| Frontmatter (`name`, `description`) | yes | `description` must name skip conditions, not only trigger phrases. |
+| Title (`# <Title>`) | yes | |
+| Why this skill exists | optional | Include for *teaching* skills (discipline being taught). Skip for *orchestration* and *utility* skills. |
+| When to use | yes | Body section, not just frontmatter. Frontmatter alone is too easy to skim past. |
+| When to skip | yes | Body section. Mirror the description — explicit, not implied. |
+| Phases / Process / Workflow | yes | Pick one heading. Don't mix. |
+| Anti-patterns | recommended | Skip only if the skill is so simple there are none. |
+| Pairing with other skills | yes | At minimum name 1 upstream and 1 downstream. |
+| Done when | yes | Verifiable conditions, not vibes. |
+| Handoff | optional | Use when the skill cleanly feeds into another; otherwise the Pairing section covers it. |
+
+## Voice and length
+
+- **Body length matches role**, not importance. Teaching skills run long (debug, security-review, tdd). Orchestration / utility / lens skills run short (tdd-rounds, simplify, code-hygiene). Don't pad an orchestration skill to match a teaching skill — it adds noise.
+- **No hedging.** "Sometimes consider maybe doing X" is dead text. Pick a recommendation.
+- **No corporate voice.** Direct sentences. The reader is a fast-reading senior engineer or an LLM, not an executive.
+- **Cite paths**: `path:line` or `[link](relative/path.md)`. Don't say "see the auth module"; say `src/auth/session.go:42`.
+
+## Vocabulary
+
+- Architecture terms come from [`LANGUAGE.md`](LANGUAGE.md) — don't redefine. Link instead.
+- Domain terms come from `docs/CONTEXT.md` (the consuming repo's glossary, not this skill set's).
+- Format references for ADRs / CONTEXT.md live in [`formats/`](formats/) — link, don't inline.
+
+## Adding the skill to the index
+
+Once `SKILL.md` is written:
+
+1. Add a row to README.md's "by trigger phase" index (under the right role group).
+2. Add a row to README.md's "by role" table.
+3. Add an entry to [`TRIGGERS.md`](TRIGGERS.md) — list the trigger phrases that should route to it.
+4. If the skill participates in a canonical workflow, update [`WORKFLOWS.md`](WORKFLOWS.md).
+5. If the skill produces a `docs/` artifact, add a row to the "Artifacts accumulate in `docs/`" table at the bottom of WORKFLOWS.md.

package/skills/TRIGGERS.md

@@ -0,0 +1,64 @@
+# Trigger index
+
+Flat lookup from user phrases / situations → skill. The canonical source of trigger phrases is each skill's `description:` frontmatter; this file aggregates them so collisions and gaps are visible.
+
+If a phrase appears in multiple rows, the disambiguation column names how to choose.
+
+## Planning & investigation
+
+| Phrase / situation | Routes to | Disambiguator |
+| --- | --- | --- |
+| "investigate", "research", "give me a proposal", "what are our options", "how would we approach", "let's explore", "should we…" | [`investigate`](investigate/SKILL.md) | Direction not yet chosen. If a direction *is* chosen and you want to stress-test it → `grill-plan`. |
+| "new project", "initialize", "bootstrap", "start new repo" | [`bootstrap`](bootstrap/SKILL.md) | Only for project start. |
+| "before any non-trivial feature", "let's spec this out", "write a feature doc" | [`feature-doc`](feature-doc/SKILL.md) | Skip for typo / dep bump / pure refactor. |
+| "grill me on this", "stress-test this plan", "walk me through this", "is this consistent with our model" | [`grill-plan`](grill-plan/SKILL.md) | A plan exists; you want it pressure-tested. |
+| "benchmark", "performance test", "measure latency", "profile" | [`bench`](bench/SKILL.md) | Performance verification. |
+| "is the naming right?", "does this match our glossary?", "audit terminology", "sync check", "context audit" | [`sync-check`](sync-check/SKILL.md) | Before `pr-review` or after refactor. |
+
+## Design & architecture
+
+| Phrase / situation | Routes to | Disambiguator |
+| --- | --- | --- |
+| "system architecture", "module boundaries", "service boundaries", "how should I structure this system", "draw the architecture", "topology" | [`system-design`](system-design/SKILL.md) | Greenfield, multi-module. For single-module work → `design`. For reorganising an existing codebase → `improve-codebase-architecture`. |
+| "how should I structure this", "deep modules", "testability", "API design", "design this module" | [`design`](design/SKILL.md) | Single module / public API, NEW code. For existing code → `improve-codebase-architecture`. |
+| "improve architecture", "find refactoring opportunities", "consolidate", "deepen these modules", "make this more testable" | [`improve-codebase-architecture`](improve-codebase-architecture/SKILL.md) | EXISTING code, cross-module. For local single-module refactor → `design` or just refactor inline. |
+| "simpler", "boring", "naming", "YAGNI", "premature abstraction", "over-engineered", "clean this up at line level" | [`code-hygiene`](code-hygiene/SKILL.md) | Lens, not phase — applies during simplify, pr-review, or whenever you re-read code. |
+| "I'm lost", "give me higher-level context", "zoom out", "I don't know this area" | [`zoom-out`](zoom-out/SKILL.md) | User-invoked utility (`disable-model-invocation`). |
+
+## Implementation
+
+| Phrase / situation | Routes to | Disambiguator |
+| --- | --- | --- |
+| "it's broken", "this is failing", "intermittent", "flaky", "regression", "not sure why", "production issue", "doesn't work in <env>" | [`debug`](debug/SKILL.md) | Root cause not obvious. If the trace points directly at the fix → skip `debug`, run `tdd`. |
+| "TDD", "test-first", "red-green-refactor", "implement this feature", "fix this bug" | [`tdd`](tdd/SKILL.md) | Default for code-writing. |
+| "drive the sub-agent team", "multi-round TDD", "orchestrate rounds", "Builder agents", ≥10 ACs, multi-package | [`tdd-rounds`](tdd-rounds/SKILL.md) | Single-AC fix or single-package feature → just `tdd`. |
+| "simplify pass", "tighten this", "clean up before commit", "end-of-round sweep" | [`simplify`](simplify/SKILL.md) | Runs after `tdd` reaches green; before PR. |
+
+## Pre-merge gates & review
+
+| Phrase / situation | Routes to | Disambiguator |
+| --- | --- | --- |
+| "shipping", "ready to merge", "before deploy", "production readiness", "prod-ready" | [`prod-ready`](prod-ready/SKILL.md) | Author's pre-merge checklist. Skip for pure docs / test-only / one-line bug fix without infra impact. |
+| "security review", "threat model", "STRIDE", "auth flow", "permissions", "secrets", "PII", "public API", "external surface", "abuse", "hardening" | [`security-review`](security-review/SKILL.md) | Surface-changing work only. Non-surface-changing diffs use `prod-ready` Section 3 alone. |
+| "review this PR", "look over the diff", "check this change", "give feedback on" | [`pr-review`](pr-review/SKILL.md) | Reviewing someone else's PR (or self-review). Pairs with `prod-ready` (author side) and `security-review` (escalation). |
+| "smoke test", "real API", "live verify", "before tag", "end-to-end against actual <vendor>" | [`verify-real-deps`](verify-real-deps/SKILL.md) | After `prod-ready` clean, before tagging. Skip if no third-party API or staging is fully owned. |
+
+## Routing collisions worth knowing
+
+Some phrases overlap. Pick by the disambiguator:
+
+- **"design"** alone — almost always [`design`](design/SKILL.md). If the user means "system design", that phrase routes to [`system-design`](system-design/SKILL.md).
+- **"refactor"** — [`improve-codebase-architecture`](improve-codebase-architecture/SKILL.md) for cross-module; [`design`](design/SKILL.md) or just inline edits for one-module shape; [`simplify`](simplify/SKILL.md) for end-of-round line-level cleanup.
+- **"clean up"** — [`code-hygiene`](code-hygiene/SKILL.md) as a lens; [`simplify`](simplify/SKILL.md) as the end-of-round action; [`improve-codebase-architecture`](improve-codebase-architecture/SKILL.md) if the cleanup is structural.
+- **"test"** — [`tdd`](tdd/SKILL.md) for writing tests against new behavior; [`debug`](debug/SKILL.md) when the test you'd write isn't obvious yet (root cause unclear); [`simplify`](simplify/SKILL.md)'s lens 4 for assessing existing tests.
+- **"ship"** — [`prod-ready`](prod-ready/SKILL.md) for the gate; [`verify-real-deps`](verify-real-deps/SKILL.md) for tagged release with third-party APIs.
+
+## When NO skill fires
+
+Some tasks don't need a skill:
+
+- Typo fixes, one-line config tweaks, dependency bumps with no API change.
+- Mechanical renames where the desired result is unambiguous.
+- Reading code to answer a question (no artifact, no decision).
+
+If the user invokes a skill on these, surface that the overhead exceeds the value and offer to just do the change.

package/skills/WORKFLOWS.md

@@ -0,0 +1,369 @@
+# Workflows
+
+How the 16 skills compose into the common paths users actually walk.
+
+The skills aren't a flat menu — they form a workflow with branching. This file maps the canonical paths so you can see where to enter, what to expect, and what produces what.
+
+For routing by trigger phrase, see [TRIGGERS.md](./TRIGGERS.md). For the cross-skill graph, see the relationship map in [README.md](./README.md#skill-relationship-map).
+
+## Decision tree — where to start
+
+```
+Got a task? Pick by what you have in front of you:
+
+┌─────────────────────────────────────┬──────────────────────────────────┐
+│ Typo / dep bump / one-liner config  │ just fix it — no skill needed    │
+├─────────────────────────────────────┼──────────────────────────────────┤
+│ Bug fix — root cause obvious        │ /tdd  (Workflow 5a)              │
+├─────────────────────────────────────┼──────────────────────────────────┤
+│ Bug — root cause unclear/intermittent│ /debug → /tdd  (Workflow 5b)    │
+├─────────────────────────────────────┼──────────────────────────────────┤
+│ New SYSTEM (multi-module) greenfield│ /system-design  (Workflow 6)     │
+├─────────────────────────────────────┼──────────────────────────────────┤
+│ New feature in existing system      │ /feature-doc  (Workflow 1 or 2)  │
+├─────────────────────────────────────┼──────────────────────────────────┤
+│ New feature, direction unclear      │ /investigate  (Workflow 3)       │
+├─────────────────────────────────────┼──────────────────────────────────┤
+│ Refactor existing code              │ /improve-codebase-architecture   │
+│                                     │                  (Workflow 4)    │
+├─────────────────────────────────────┼──────────────────────────────────┤
+│ Reviewing someone else's PR         │ /pr-review  (utility)            │
+├─────────────────────────────────────┼──────────────────────────────────┤
+│ Surface-changing work (auth, public │ /security-review (gate, runs     │
+│   API, sensitive data, new entry pt)│  alongside Workflow 1/2/6)       │
+├─────────────────────────────────────┼──────────────────────────────────┤
+│ Lost in unfamiliar area, mid-task   │ /zoom-out  (utility, anytime)    │
+└─────────────────────────────────────┴──────────────────────────────────┘
+```
+
+---
+
+## Workflow 1 — Standard greenfield feature
+
+For a single-package feature with a manageable acceptance-criteria count.
+
+```
+   [user has a clear idea]
+            │
+            ▼
+       feature-doc  ──── produces: docs/features/<name>.md
+            │             (Problem, User Story, ACs, Non-Goals)
+            │
+            ▼
+   [doc reviewed; ACs stable]
+            │
+            ├─── Surface-changing? (new entry point, identity flow,
+            │     authz, sensitive data, external dep)
+            │       └─► security-review  ──── runs alongside design/tdd;
+            │             produces: feature-doc Security section
+            │             or docs/security/<feature>.md
+            │
+            ▼
+       (optional) design ──── new module shape; optional sibling
+            │                 docs/features/<name>.design.md if non-trivial
+            │
+            ▼
+          tdd  ──── red → green → refactor, per AC
+            │
+            ▼
+       simplify  ──── end-of-slice sweep (reuse / quality /
+            │         efficiency / test relevance)
+            │
+            ▼
+       prod-ready  ──── 7-section checklist
+            │
+            ▼
+       (optional) pr-review  ── self-check against the diff before opening
+            │
+            ▼
+       [PR / merge]
+```
+
+---
+
+## Workflow 2 — Large feature *(≥ 10 ACs or multi-package)*
+
+```
+   feature-doc  (lists many ACs)
+        │
+        ▼
+   tdd-rounds  ──── parent plans rounds, dispatches Builders
+        │
+        ▼
+   ┌──────── Round N ────────┐
+   │   Parent writes brief    │  ◄─── self-contained, references docs/STATE.md
+   │              │           │
+   │              ▼           │
+   │   Builder is dispatched  │
+   │   Builder runs IN ORDER: │
+   │     • design  (if new pkg)
+   │     • tdd     (mandatory every round)
+   │     • simplify (end of round)
+   │     • prod-ready (final round only)
+   │              │           │
+   │              ▼           │
+   │   Builder commits per AC slice (R<N>: prefix)
+   │              │           │
+   │              ▼           │
+   │   Builder returns report │
+   │              │           │
+   │              ▼           │
+   │   Parent reviews diff,   │
+   │   runs tests independently,
+   │   appends to STATE.md    │
+   └──────────┬───────────────┘
+              │
+              ▼
+   [parent runs improve-codebase-architecture ONCE mid-project]
+              │
+              ▼
+   [continue rounds until all ACs green]
+              │
+              ▼
+   verify-real-deps  ──── parent, against real upstream
+              │             produces: docs/known-issues.md
+              │
+              ▼
+   [bug ledger entries → fix-rounds via tdd-rounds → loop]
+              │
+              ▼
+       [tag vN.0]
+```
+
+---
+
+## Workflow 3 — Investigation before commitment
+
+For non-trivial structural decisions: new dependency, framework choice, cross-cutting refactor.
+
+```
+   [user has structural decision pending]
+            │
+            ▼
+       investigate  ──── 5 phases:
+            │             1. Survey current state (cite path:line)
+            │             2. Map 2-3 options
+            │             3. Recommend with reasoning
+            │             4. Checkpoint questions
+            │             5. (Optional) independent review
+            │
+            │             produces: docs/research/<topic>.md
+            ▼
+   [user picks an option]
+            │
+            ├─── Hard to reverse / load-bearing? ─────► grill-plan ───► ADR
+            │                                              │
+            │                                              ▼
+            │                                       docs/adr/<n>-<topic>.md
+            │
+            ▼
+       feature-doc  (capture chosen direction as a contract)
+            │
+            ▼
+       [→ Workflow 1 or 2]
+```
+
+---
+
+## Workflow 4 — Refactoring existing code
+
+```
+   [user wants to improve architecture]
+            │
+            ▼
+       (optional) zoom-out  ──── if unfamiliar with the area
+            │                    map of relevant modules + callers
+            │
+            ▼
+       improve-codebase-architecture
+            │
+            ├─ explore (with Explore subagent)
+            ├─ apply DELETION TEST to suspect modules
+            ├─ present numbered candidate list
+            ▼
+       [user picks one candidate]
+            │
+            ▼
+       [grilling loop — design deepened module's interface]
+            │
+            ├─ updates CONTEXT.md inline if new term
+            └─ offers ADR if user rejects with load-bearing reason
+            ▼
+       tdd  (or tdd-rounds if cross-package)
+            │     refactor rounds: ACs are "all existing tests still green"
+            ▼
+       prod-ready
+            │
+            ▼
+       [PR]
+
+   If user wants more candidates, run improve-codebase-architecture again.
+   Don't batch multiple candidates in one pass.
+```
+
+---
+
+## Workflow 5a — Bug fix, root cause obvious
+
+When the symptom and stack trace point at the bug directly.
+
+```
+   [bug report — root cause clear from message/trace]
+            │
+            ├─── Trivial (typo, config) ────► just fix it (no skills)
+            │
+            ▼ (real bug, but cause is known)
+          tdd  ──── 1. Failing test reproducing the bug
+            │       2. Fix
+            │       3. Refactor with the test as safety net
+            │
+            ▼
+   [touches infra / auth / DB / API surface?]
+            │
+            ├─── YES, surface-changing ──► security-review  ──► prod-ready
+            │
+            ├─── YES, infra/DB/ops ──────► prod-ready
+            │
+            └─── NO ─────────────────────► [skip prod-ready]
+            │
+            ▼
+       [PR]
+```
+
+## Workflow 5b — Bug fix, root cause unclear
+
+When the bug is intermittent, environment-specific, a regression, or you don't yet know what to assert.
+
+```
+   [bug report — symptom present, root cause not obvious]
+            │
+            ▼
+       (optional) zoom-out  ──── if unfamiliar with the area
+            │
+            ▼
+        debug  ──── 1. Reproduce (minimum reliable repro)
+            │       2. Isolate (bisect / log / trace)
+            │       3. Hypothesis test (one variable at a time)
+            │       4. Name root cause (distinct from symptom)
+            │
+            │       optional: docs/research/<bug-slug>.md
+            │
+            ▼
+   [root cause named, blast radius known]
+            │
+            ▼
+          tdd  ──── failing test from the reproduction →
+            │       fix at the named region → refactor
+            │
+            ▼
+   [touches surface / infra / auth?]
+            │
+            ├─── YES, surface-changing ──► security-review  ──► prod-ready
+            │
+            ├─── YES, infra/DB/ops ──────► prod-ready
+            │
+            └─── NO ─────────────────────► [skip prod-ready]
+            │
+            ▼
+       [PR]
+```
+
+---
+
+## Workflow 6 — Greenfield system *(new multi-module project from scratch)*
+
+```
+   [user starts a new system]
+            │
+            ▼
+       (optional) investigate  ──── if direction itself is unclear
+            │                       (architecture style, framework choice)
+            │
+            ▼
+       system-design  ──── name modules, set dependencies, identify seams
+            │                produces: docs/architecture.md (system map)
+            │
+            ▼
+   [topology stable]
+            │
+            ├── For each module with a public interface  ──► design
+            │
+            └── For any hard-to-reverse topology decision ──► grill-plan ──► ADR
+            │
+            ▼
+       feature-doc  (first feature using the topology)
+            │
+            ▼
+       [→ Workflow 1 or 2 per feature]
+```
+
+This workflow runs **once per system**, not per feature. After it, each feature follows its own Workflow 1 or 2 within the established topology.
+
+---
+
+## Utility — `/zoom-out`
+
+```
+   [user feels lost in unfamiliar code, mid-task]
+            │
+            ▼
+       /zoom-out  ──── user-invoked only (disable-model-invocation: true)
+            │
+            ▼
+   [Claude maps the relevant modules + callers
+    using docs/CONTEXT.md vocabulary]
+            │
+            ▼
+   [user returns to original workflow with better context]
+```
+
+---
+
+## Cross-workflow patterns
+
+A few things that happen across all workflows:
+
+1. **`zoom-out` can interrupt any workflow.** Slash command, user-only — pulls Claude up an abstraction layer when the user is lost. Doesn't change which workflow they're in.
+
+2. **`grill-plan` is reusable as a sub-step.** Workflow 3 calls it explicitly; Workflow 4's grilling loop borrows the same discipline. It's also valid as a standalone skill if the user has a plan they want to stress-test. Has a **bootstrap mode** for greenfield repos with no `CONTEXT.md` / ADRs yet — the session creates them lazily.
+
+3. **`design` doesn't have a workflow of its own** — it's a sub-step inside Workflow 1, 2, and 4. Always paired with `tdd` (or implicitly with `tdd-rounds`). Optional sibling artifact `docs/features/<name>.design.md` when the module shape is non-trivial.
+
+4. **`code-hygiene` is a lens, not a phase.** Apply it during the simplify sweep that follows TDD green, during `pr-review`, or whenever you re-read code and pause to understand it. Especially relevant in Workflows 1, 2, 4, and 5.
+
+5. **`debug` runs *before* `tdd` for non-trivial bugs.** Workflow 5b makes this explicit. The reproduction from `debug` becomes the failing test for `tdd`. Skip for bugs whose root cause is obvious from the trace (Workflow 5a).
+
+6. **`security-review` is a gate, not a workflow.** Fires when a change is **surface-changing** — new entry point, identity / session / token flow, authorization logic, sensitive-data path, new external dependency, secrets handling. Runs alongside `design` and `tdd` in Workflows 1, 2, 4, 5a, 5b, 6 whenever those criteria hit. Not a substitute for `prod-ready` Section 3 — both run when the surface changes.
+
+7. **`pr-review` is a utility workflow.** Runs when reviewing someone else's PR. Also runs (lighter form) as a self-check before opening the PR. The `tdd-rounds` parent's per-round verification borrows from it.
+
+8. **`prod-ready` is the universal pre-merge gate** for Workflows 1, 2, 4, and sometimes 5. Single exit ramp before opening a PR.
+
+9. **`verify-real-deps` fires whenever a workflow ends in a tagged release that touches a third-party API.** Most commonly that's Workflow 2 (large feature → tag), but it also applies when Workflow 1, 4, or 6 culminates in a release whose code path talks to an upstream you don't control. It does **not** fire for pure-internal services with database-only state, or for continuous-deploy environments that don't tag.
+
+10. **`system-design` runs once per system, not per feature.** It's the greenfield precursor to Workflows 1 and 2. Once the topology is set, individual features run their own Workflow 1 or 2 inside it.
+
+11. **Vocabulary is shared.** All architecture-talking skills (`design`, `system-design`, `improve-codebase-architecture`, `pr-review`, `grill-plan`) read from [`skills/LANGUAGE.md`](./LANGUAGE.md). Format references (ADRs, CONTEXT.md) live in [`skills/formats/`](./formats/). Domain vocabulary (Customer, Order, etc.) lives in `docs/CONTEXT.md`. Keep them distinct.
+
+13. **Bootstrap mode for greenfield repos** is documented in one place — [`grill-plan/BOOTSTRAP.md`](./grill-plan/BOOTSTRAP.md). `feature-doc` and `system-design` defer there rather than re-explaining the rules.
+
+14. **`simplify` is the end-of-slice / end-of-round sweep.** Runs after every `tdd` slice goes green; in `tdd-rounds`, lands as its own commit per [`tdd-rounds/COMMITS.md` rule 4](./tdd-rounds/COMMITS.md). Applies the `code-hygiene` lens to the changed files, plus a test-relevance check. Distinct from `code-hygiene` (the lens) and from `improve-codebase-architecture` (the structural escalation when simplify finds bigger issues).
+
+12. **Artifacts accumulate in `docs/`:**
+
+    | Location | Produced by | Type |
+    |---|---|---|
+    | `docs/features/<name>.md` | `feature-doc` | One per feature |
+    | `docs/features/<name>.design.md` | `design` (optional) | One per feature with non-trivial module shape |
+    | `docs/research/<topic>.md` | `investigate`, `debug` (optional) | One per investigation or non-trivial bug |
+    | `docs/adr/<n>-<topic>.md` | `grill-plan`, `improve-codebase-architecture` | One per architectural decision |
+    | `docs/CONTEXT.md` | `grill-plan`, `improve-codebase-architecture` (inline updates) | One per repo / context |
+    | `docs/architecture.md` | `system-design` | One per system (the system map) |
+    | `docs/STATE.md` | `tdd-rounds` parent (append-only) | One per multi-round project |
+    | `docs/security/<feature>.md` | `security-review` (high-stakes only) | One per surface-changing feature where a feature-doc section isn't enough |
+    | `docs/benchmarks/<feature>.md` | `bench` | One per performance-critical feature |
+    | `docs/known-issues.md` | `verify-real-deps` | One per repo (post-mortem record) |
+    All `docs/` files are created **lazily** — they don't have to pre-exist for a workflow to run. The skill creates them on first use.
+s/known-issues.md` | `verify-real-deps` | One per repo (post-mortem record) |
+
+    All `docs/` files are created **lazily** — they don't have to pre-exist for a workflow to run. The skill creates them on first use.

package/skills/bench/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: bench
+description: Performance benchmarking discipline. Measures latency, throughput, and records baseline environments. Triggered by phrases like "benchmark", "performance test", "measure latency".
+complexity: medium
+expected_duration: 30 minutes
+---
+
+# Benchmark
+
+Turns "it feels faster" into "p99 reduced by 40ms under 200 RPS." Benchmarking provides the empirical evidence required to validate performance ACs.
+
+## Why this skill exists
+
+Performance claims are often "vibes-based" or measured on a developer's machine without a recorded baseline. This skill ensures performance data is reproducible and comparable.
+
+## When to use
+
+- Verifying performance-related Acceptance Criteria in a feature doc.
+- Identifying regressions or improvements after a major refactor.
+- Profiling hot paths to guide optimization.
+
+## Process
+
+### 1. Establish Baseline
+
+Measure the performance of the code *before* the change. Record the environment (hardware, load, concurrency).
+
+### 2. Execute Benchmark
+
+Run the same test against the changed code. Ensure identical environment conditions.
+
+### 3. Record Findings
+
+Create a report in `docs/benchmarks/<feature>.md` using the template.
+
+## Done when
+
+- A benchmark report exists in `docs/benchmarks/`.
+- Baseline and current measurements are clearly compared.
+- The environment and load profile are documented.

package/skills/bench/templates/benchmark-report.md

@@ -0,0 +1,26 @@
+# Benchmark Report
+
+**Feature:** <feature>
+**Date:** YYYY-MM-DD
+
+## Environment
+- **Hardware:** <e.g., Apple M1 Max, 64GB RAM>
+- **OS/Runtime:** <e.g., macOS 14.4, Node v20.11.0>
+- **Network:** <e.g., localhost / AWS VPC>
+
+## Load Profile
+- **Concurrency:** <number of concurrent users/threads>
+- **Duration:** <test duration>
+- **Request Type:** <e.g., POST /api/orders>
+
+## Comparison
+
+| Metric | Baseline (vN.X) | Current (vN.Y) | Change |
+| --- | --- | --- | --- |
+| Avg Latency | | | |
+| p95 Latency | | | |
+| p99 Latency | | | |
+| Throughput | | | |
+
+## Analysis
+<Describe the result. Did it meet the AC? Any surprising bottlenecks?>

package/skills/bootstrap/BOOTSTRAP.md

@@ -0,0 +1,13 @@
+# Bootstrap mode — the canonical rules for greenfield repos
+
+This document is the **single source of truth** for how greenfield repos onboard their vocabulary and decision record. `feature-doc`, `system-design`, and `improve-codebase-architecture` all defer here when their inputs would normally come from `CONTEXT.md` / `docs/adr/` but those don't exist yet.
+
+## The rules
+
+1. **No file is required to pre-exist.** [`docs/CONTEXT.md`](../../docs/CONTEXT.md), [`docs/adr/`](../../docs/adr/), and [`docs/CONTEXT-MAP.md`](../../docs/CONTEXT-MAP.md) are all created **lazily** — only when the first term is resolved or the first ADR is needed.
+2. **Resolve 3–7 core domain terms first** for the plan being discussed. Not exhaustive — the terms most load-bearing for the decisions in scope. Format per [`../formats/CONTEXT-FORMAT.md`](../formats/CONTEXT-FORMAT.md).
+3. **Capture ADRs only when all three criteria hold** (hard-to-reverse / surprising / real trade-off). Format per [`../formats/ADR-FORMAT.md`](../formats/ADR-FORMAT.md).
+4. **Grilling is shorter in bootstrap mode** — there's less existing model to stress-test against. Output is fewer challenges, more *terminology and decision capture*.
+5. **If nothing remains to grill** after bootstrapping (plan is fully exploratory), stop and hand off to [`investigate`](../investigate/SKILL.md) — `grill-plan` is for stress-testing, not exploring.
+
+Other skills should link here rather than re-explaining bootstrap.