@codepassion/skills 1.2.0 → 1.4.0

package/skills/c9n-spec/templates/AGENTS.md

@@ -0,0 +1,179 @@
+# AGENTS.md
+
+AI-assisted development context for the **{{PROJECT_NAME}}** repo.
+
+> This is the canonical agent file. `CLAUDE.md` is a one-line pointer to it. Codex, Cursor,
+> OpenCode, and Claude Code all read this file.
+
+## Spec-Driven Development Protocol (read first)
+
+This repo follows a spec-driven, ISO/IEC 29110-aligned documentation system (Software
+Implementation work products). This section is the **canonical source** — agents MUST follow it.
+The repo is authoritative.
+
+### Doc map
+
+| File                                           | ISO 29110 work product     | Holds                                                                        |
+| ---------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------- |
+| `AGENTS.md` / `CLAUDE.md`                       | — (agent protocol)         | This protocol + stack + patterns                                             |
+| [`CONTEXT.md`](CONTEXT.md)                       | Domain glossary            | Ubiquitous language only — no implementation                                 |
+| [`DESIGN.md`](DESIGN.md)                         | — (visual design system)   | UI design language: color/type/component **intent & rules** (values in code) |
+| [`docs/SRS.md`](docs/SRS.md)                     | Requirements Specification | Master registry: features + requirement IDs + system NFRs                    |
+| [`docs/architecture.md`](docs/architecture.md)   | Software Design            | System map, module boundaries, data model, integrations                      |
+| [`docs/traceability.md`](docs/traceability.md)   | Traceability Record        | Master index: requirement → design → test                                    |
+| [`docs/test-plan.md`](docs/test-plan.md)         | Test Cases & Procedures    | Master test strategy                                                         |
+| `docs/adr/NNNN-*.md`                            | Architecture Decisions     | One ADR per hard-to-reverse decision                                         |
+| `docs/features/<name>.md`                       | Per-feature deep doc       | Sections: Requirements · Design · Test Plan · Test Cases · Traceability      |
+
+**Master-then-split (two levels):** a feature starts as a section in the master files →
+graduates to its own `docs/features/<name>.md` when it outgrows the section → graduates to a
+folder `docs/features/<name>/` (one file per section) only when a _section_ outgrows one file.
+Default to the smallest form that fits.
+
+**Feature ID:** every functional feature has a unique **short-code** — a 2–4 letter
+human-readable mnemonic (`PAY`, `INV`, `AUTH`). The short-code _is_ the feature ID; it prefixes
+all the feature's child IDs. Short-codes are **append-only** — pick a fresh, unused one for a new
+feature (check `docs/SRS.md`), and never reuse one even after a feature is removed. `docs/SRS.md`
+is the authoritative registry.
+
+**Child IDs:** feature-prefixed, append-only — `PAY-REQ-001` (requirement), `PAY-TC-001` (test
+case). Never reuse or renumber.
+
+**"Design" disambiguation:** `DESIGN.md` = **visual** design (UI). The `## Design` sections in
+`docs/features/*.md` and `docs/architecture.md` = **software** design (engineering). Different
+layers — don't conflate them.
+
+### Approval gates (no code before blueprint)
+
+A new feature passes three sequential gates, each needing the owner's sign-off:
+
+1. **SRS approved** — the _what_ (requirements + acceptance criteria).
+2. **Design + Test Plan approved** — the _how_ + how we'll prove it.
+3. **Code** — only now. The PR links the approved docs.
+
+### Definition of Ready (before touching code)
+
+1. Read [`CONTEXT.md`](CONTEXT.md) (glossary) and [`docs/architecture.md`](docs/architecture.md) (system map).
+2. Identify the feature; read its `docs/features/<name>.md` (or its master SRS section).
+3. For **UI work**, also read [`DESIGN.md`](DESIGN.md) first.
+4. For a **new feature**, Gate 1 **and** Gate 2 must already be approved. **No production code
+   before Gate 2 sign-off.**
+
+### Definition of Done (before opening the PR)
+
+Apply the **behavior-change rule**: update docs **iff** the change alters observable behavior, a
+requirement, an interface, or a test outcome.
+
+| Change kind                                  | Doc action                                                     |
+| -------------------------------------------- | -------------------------------------------------------------- |
+| New/changed requirement                      | Update SRS + traceability + test cases                         |
+| Behavior/architecture change                 | Update design (+ ADR if hard-to-reverse) + affected test cases |
+| Bug fix toward spec                          | Add a regression test case                                     |
+| Visual _intent_ change                       | Update `DESIGN.md`                                             |
+| Token _value_ change in Tailwind/CSS         | No doc update (`DESIGN.md` references values, never copies)    |
+| Refactor / rename / dep-bump / typo / format | No doc update (code-only PR)                                   |
+
+The `.github/pull_request_template.md` checklist is the merge gate.
+
+### Reverse-documentation policy
+
+Existing shipped modules each get an **as-built stub** in `docs/features/` (reverse-documented
+from code, **not grilled** — requirements describe current behavior at low confidence, no test
+cases). When a module is next touched, **deepen its stub** to the full chain (acceptance criteria
++ Test Cases + Traceability) for the part you change — don't try to deepen the whole stub at once.
+New features still get the full chain up front via the gates.
+
+## C9N engineering conventions (referenced, not duplicated)
+
+These follow the Code Passion skill family — the single source of truth. Don't restate the rules
+here; consult the skill:
+
+| Topic            | Skill                       |
+| ---------------- | --------------------------- |
+| Commit messages  | `c9n-commit-messages`       |
+| Git branching    | `c9n-git-branching`         |
+| Pull requests    | `c9n-pull-requests`         |
+| Code review      | `c9n-code-review`           |
+| Clean Code (TS)  | `c9n-clean-code-typescript` |
+| ESLint / types   | `c9n-typescript-eslint`     |
+| Formatting       | `c9n-code-formatting`       |
+| SemVer / deploy  | `c9n-semver-deployment`     |
+
+Install: `npx @codepassion/skills install claude`.
+
+## Tech Stack
+
+C9N defaults — trim rows this project doesn't use.
+
+| Layer      | Technology                                       |
+| ---------- | ------------------------------------------------ |
+| Runtime    | Bun                                              |
+| API        | ElysiaJS                                         |
+| Frontend   | Next.js / React (or Astro)                       |
+| Database   | PostgreSQL via Drizzle ORM                       |
+| Storage    | Supabase Storage + Auth                          |
+| Build      | Turborepo (monorepo)                             |
+| Validation | Zod (shared with Drizzle via drizzle-zod)        |
+| Lint       | ESLint + Prettier (no semicolons, double quotes) |
+| Commits    | Conventional Commits (commitlint + Husky)        |
+
+## Project Structure
+
+<!-- Describe the actual repo layout here. C9N monorepo default: -->
+
+```text
+{{PROJECT_NAME}}/
+  apps/
+    api/        -- backend (if any)
+    web/        -- frontend (if any)
+  packages/
+    database/   -- Drizzle ORM schemas + client
+    ...
+```
+
+<!-- =========================================================================
+     API MODULE PATTERNS — delete this whole section for a web-only repo.
+     ========================================================================= -->
+
+## API Module Structure (delete if no backend)
+
+Each feature lives under `apps/api/src/modules/<feature>/`:
+
+```text
+modules/<feature>/
+  models/      -- Zod schemas + types as namespace exports
+  use-cases/   -- Business logic as abstract static classes
+  services/    -- External API / infrastructure integrations
+  models.ts    -- Barrel export
+  use-cases.ts -- Barrel export
+  constants.ts -- Shared constants
+  types.ts     -- Shared TS interfaces
+  index.ts     -- Elysia route definitions
+```
+
+### Key patterns
+
+- **Models** — Zod `namespace` pattern; error messages as `z.literal()` so they're both
+  type-safe constants and response schema.
+- **Use cases** — `abstract class` with a public `static execute(...)`; private `static` helpers
+  hold the how. `execute()` reads like a table of contents (each line a clear step), no inline
+  env-extraction/conditional-throw/DB-query.
+- **Services** — same abstract-static shape, wrapping external integrations.
+- **Routes** — `new Elysia({ prefix })`; `throw status(404, "...")` for HTTP errors.
+- **Enum value objects** — `as const satisfies Record<string, T>` for type-safe dot access.
+
+<!-- ===================== END deletable API section ===================== -->
+
+## Environment Variables
+
+<!-- List required env vars and which module/package consumes each. -->
+
+| Variable       | Used by |
+| -------------- | ------- |
+| `DATABASE_URL` | …       |
+
+## Code Style
+
+Per `c9n-code-formatting` + `c9n-typescript-eslint`: no semicolons, double quotes, no trailing
+commas. Barrel exports per subdirectory. Use the project's error-reporting path (e.g.
+`Sentry.captureException`) — no `console.error`/`console.log` for errors.

package/skills/c9n-spec/templates/CLAUDE.md

@@ -0,0 +1,6 @@
+# {{PROJECT_NAME}}
+
+The canonical agent context for this repo is **AGENTS.md** (cross-tool standard). The import
+below pulls it into Claude Code's memory so the spec-driven protocol auto-loads.
+
+@AGENTS.md

package/skills/c9n-spec/templates/CONTEXT.md

@@ -0,0 +1,53 @@
+# {{PROJECT_NAME}} — Domain Glossary & Project Context
+
+> **Glossary only — no implementation detail.** This file is the ubiquitous language of the
+> project: what each term *means*. Code, schemas, and decisions live elsewhere (`docs/`). Keep it
+> a dictionary, not a spec. Produced/maintained via `/grill-with-docs`.
+
+## Actors
+
+<!-- Who interacts with the system, and how they authenticate / what they can do. -->
+
+### <Actor>
+
+- …
+
+## Core Entities
+
+<!-- The nouns of the domain. For each: code term, customer-facing term, definition,
+     statuses/lifecycle, key fields. Example shape below — replace it. -->
+
+### <Entity> (<local-language term if any>)
+
+- **Code term:** `<table_name>` (database), `/<route>` (API)
+- **Customer-facing term:** "…"
+- **Definition:** …
+- **Statuses:** … → … → …
+- **Lifecycle:** … → … → …
+
+## External Integrations
+
+<!-- Third-party services and what they do for the domain — not how they're wired. -->
+
+### <Service>
+
+- …
+
+## Data Model (Key Relationships)
+
+```
+<Entity A> → <Entity B> (1:N)
+…
+```
+
+## Key Business Decisions
+
+<!-- Domain rules a newcomer would get wrong. One line each. -->
+
+- …
+
+## Glossary Hygiene
+
+- When output names a domain concept, use the term **as defined here** — don't drift to synonyms.
+- If a needed concept isn't here yet: either you're inventing language the project doesn't use
+  (reconsider) or there's a real gap (resolve it via `/grill-with-docs`).

package/skills/c9n-spec/templates/DESIGN.md

@@ -0,0 +1,73 @@
+# DESIGN.md — {{PROJECT_NAME}} Visual Design System
+
+Visual design language for AI-assisted UI generation. This governs the **web app**.
+
+> **This file is intent + rules, not a token dump.** Raw token _values_ live in code and are the
+> source of truth — never copy them here (they would drift). This file documents what code can't
+> express: when to use what, and why.
+
+## Source of truth (read these for values)
+
+| What                                | File                                  |
+| ----------------------------------- | ------------------------------------- |
+| Palette, breakpoints, fonts, radius | `<tailwind.config.*>`                 |
+| Semantic tokens (light/dark CSS)    | `<globals.css>`                       |
+| shadcn config                       | `<components.json>`                   |
+| Component inventory                 | `<src/components/>`                   |
+
+When generating UI, read the files above for exact values. Use this document for the rules below.
+
+---
+
+## Brand intent
+
+<!-- One paragraph: what the product is, the feeling, the guiding aesthetic principle. -->
+
+Guiding principles:
+
+- **<Principle>** — …
+
+## Color usage rules
+
+- **Semantic first.** Build with semantic tokens (`background`, `foreground`, `primary`, `muted`,
+  `accent`, `border`, `ring`) so light/dark mode works automatically. Reach for raw primitives
+  only for brand moments the semantic set can't express.
+- **<Accent> = brand accent.** Primary CTAs, active states, key numbers. Used sparingly.
+- **Destructive is functional, not decorative** — errors and irreversible actions only.
+
+## Typography rules
+
+- **<Display face> for headings, <body face> for everything else.** Map new headings to an
+  existing tier; don't re-roll heading styles.
+- **<Locale> note** — every text style must render the primary language cleanly; verify with real
+  content, not Latin placeholder.
+
+## Layout & spacing
+
+- **Mobile-first** against the project breakpoints.
+- Use the grid utilities for gutters/rhythm rather than ad-hoc padding.
+- Radius is consistent — derive from the `--radius` token.
+
+## Components
+
+- **shadcn is the base layer.** Extend primitives; don't fork them. Domain components compose them.
+- **Match the existing component vocabulary** before inventing a new one — check the inventory.
+
+## Dark mode
+
+Class-based. Both themes fully defined in code. Always build with semantic tokens; never hardcode
+a hex that only works in one theme.
+
+---
+
+## Maintenance (behavior-change rule for design)
+
+| Change                                                            | Action      |
+| ----------------------------------------------------------------- | ----------- |
+| **Visual _intent_** changes (accent role, type-pairing, aesthetic) | Update this file |
+| A **token _value_** changes in config/CSS                          | Code-only — no update here |
+| New reusable component pattern with usage rules                    | Add a line under Components |
+
+This file is a standing reference (like `CONTEXT.md`), not a gated per-feature work product. It is
+**visual** design only; **software** design lives in `docs/architecture.md` and the `## Design`
+sections of `docs/features/*.md`. See `AGENTS.md › Spec-Driven Development Protocol`.

package/skills/c9n-spec/templates/docs/SRS.md

@@ -0,0 +1,37 @@
+# Software Requirements Specification (SRS) — Master Registry
+
+ISO/IEC 29110 Requirements Specification work product. This is the **registry** of all features
+and their requirement IDs. A feature starts as a section here; when it outgrows a section it
+graduates to a single file `docs/features/<name>.md` (with a one-line pointer below); only when a
+section within that file outgrows one file does it split into a `docs/features/<name>/` folder.
+
+This registry is also the authoritative list of **feature IDs**: each feature's `Short-code` is
+its unique ID (2–4 letter mnemonic) and prefixes all its requirement/test IDs. Short-codes are
+append-only — a new feature picks a fresh, unused code; never reuse one. See
+[`AGENTS.md`](../AGENTS.md) for the full ID convention and approval gates.
+
+---
+
+## Feature registry
+
+| Feature | Short-code | Status | SRS location |
+| ------- | ---------- | ------ | ------------ |
+| <Example feature> | `EX` | Draft → SRS in progress | _(this file)_ |
+
+> **As-built stubs** are reverse-documented from code, not grilled — requirements describe current
+> behavior at low confidence and carry no test cases yet. Deepen a stub to the full chain
+> (acceptance criteria + Test Cases + Traceability) when its module is next touched.
+
+---
+
+## Non-functional requirements (system-wide)
+
+Each NFR is tagged **[verified]** (confirmed against the code as-built) or **[target]** (the
+intended rule, not yet fully enforced — gap noted). Don't promote a target to verified without
+checking the code.
+
+| ID            | Requirement | State |
+| ------------- | ----------- | ----- |
+| `SYS-NFR-001` | <e.g. errors reported via the central error path; no console.* for errors> | **[target]** |
+
+Append new system-wide NFRs here; never renumber existing ones.

package/skills/c9n-spec/templates/docs/adr/0001-spec-driven-iso29110-docs.md

@@ -0,0 +1,44 @@
+# ADR 0001 — Spec-Driven, ISO/IEC 29110-Aligned, Agent-Readable Documentation
+
+- **Status:** Accepted
+- **Date:** {{DATE}}
+- **Deciders:** {{DECIDER}}
+
+## Context
+
+AI agents (and humans) repeatedly lose context on a codebase: unstructured prompts, specs living
+disconnected from code, and no gate between "idea" and "production code." We want spec-driven
+development — approve a blueprint before code — with a recognized standard behind it. As a small
+team (VSE), **ISO/IEC 29110** (Basic Profile, Software Implementation process) fits exactly.
+
+## Decision
+
+Adopt a repo-resident `docs/` system as the single source of truth:
+
+- Authoritative work products in `docs/` (PR-reviewed alongside code).
+- ISO 29110 SI work products only: SRS, Architecture, Traceability, Test Cases. PM work products
+  stay in the issue tracker / project tools.
+- Master-then-split organization; feature-prefixed append-only IDs (`PAY-REQ-001`).
+- Three sequential approval gates (SRS → Design + Test Plan → Code).
+- Enforcement by convention: Definition of Ready / Definition of Done in `AGENTS.md`, with the PR
+  template checklist as the merge gate. No hooks initially.
+- Behavior-change rule decides when a change must update docs.
+- Reverse-documentation: every existing module gets an **as-built stub** (requirements only, low
+  confidence, no test cases), deepened to the full chain when the module is next touched.
+
+## Consequences
+
+**Positive:** Specs and code never drift (same PR); agents have a deterministic read-before
+target; traceability satisfies the standard; predictable, low-hallucination changes.
+
+**Negative / trade-offs considered:**
+
+- Convention over hooks → relies on discipline + PR checklist (chosen for flexibility; hooks
+  remain a later backstop).
+- Per-feature deep docs are lazy → the as-is system is only shallowly mapped until touched
+  (accepted to avoid documenting frozen code).
+
+## Alternatives rejected
+
+- Specs living outside the repo (drift from code, invisible in PRs).
+- Full deep reverse-scan of all modules up front (weeks documenting stable code).

package/skills/c9n-spec/templates/docs/adr/_TEMPLATE.md

@@ -0,0 +1,26 @@
+# ADR NNNN — <Short title of the decision>
+
+- **Status:** Proposed | Accepted | Superseded by ADR-XXXX
+- **Date:** YYYY-MM-DD
+- **Deciders:** <names>
+
+> Only write an ADR when **all three** hold: (1) hard to reverse, (2) surprising without context,
+> (3) the result of a real trade-off with genuine alternatives. Otherwise skip it.
+
+## Context
+
+<!-- The forces at play: what problem, what constraints, what made this a real decision. -->
+
+## Decision
+
+<!-- What we chose, stated plainly. -->
+
+## Consequences
+
+**Positive:** …
+
+**Negative / trade-offs considered:** …
+
+## Alternatives rejected
+
+- <Alternative> — <why not>.

package/skills/c9n-spec/templates/docs/agents/domain.md

@@ -0,0 +1,43 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the
+codebase.
+
+This repo is **single-context**: one `CONTEXT.md` + `docs/adr/` at the root.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root — the ubiquitous-language glossary.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in.
+
+> Note: this repo also runs a spec-driven, ISO/IEC 29110-aligned doc system (see `AGENTS.md`). For
+> feature work, also consult `docs/SRS.md`, `docs/architecture.md`, and the relevant
+> `docs/features/<name>.md` per the protocol in `AGENTS.md`.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest
+creating them upfront. The producer skill (`/grill-with-docs`) creates them lazily when terms or
+decisions actually get resolved.
+
+## File structure
+
+```text
+/
+├── CONTEXT.md
+├── docs/adr/
+│   └── 0001-spec-driven-iso29110-docs.md
+└── apps/, packages/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (an issue title, a refactor proposal, a hypothesis, a test
+name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing
+language the project doesn't use (reconsider) or there's a real gap (note it for `/grill-with-docs`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0001 (spec-driven ISO 29110 docs) — but worth reopening because…_

package/skills/c9n-spec/templates/docs/agents/issue-tracker.md

@@ -0,0 +1,22 @@
+# Issue tracker: GitHub
+
+Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.

package/skills/c9n-spec/templates/docs/agents/triage-labels.md

@@ -0,0 +1,27 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual
+label strings used in this repo's issue tracker.
+
+| Canonical role    | Label in our tracker | Meaning                                  |
+| ----------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`    | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`      | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent` | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human` | `ready-for-human`    | Requires human implementation            |
+| `wontfix`         | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label
+string from this table. Edit the right-hand column to match whatever vocabulary you actually use.
+
+## Label provisioning
+
+Create the labels on first use:
+
+```bash
+gh label create needs-triage    --description "Maintainer needs to evaluate" --color FBCA04
+gh label create needs-info      --description "Waiting on reporter"          --color D4C5F9
+gh label create ready-for-agent --description "Fully specified, AFK-ready"    --color 0E8A16
+gh label create ready-for-human --description "Needs human implementation"    --color 1D76DB
+gh label create wontfix         --description "Will not be actioned"          --color CCCCCC
+```

package/skills/c9n-spec/templates/docs/architecture.md

@@ -0,0 +1,50 @@
+# Software Architecture — {{PROJECT_NAME}}
+
+ISO/IEC 29110 Software Design work product (system level). This is the **as-is map** of the
+shipped system: module boundaries, data model, and integration points. Per-feature design detail
+lives in the `## Design` section of `docs/features/<name>.md`. Decisions with lasting consequences
+are recorded as ADRs in `docs/adr/`.
+
+---
+
+## System context
+
+<!-- One paragraph: runtime, apps, datastore, external integrations. Then a context diagram. -->
+
+```
+<Actor> ─→ <Frontend> ─→ <API> ─→ <Database>
+                            ├─→ <Integration A>
+                            └─→ <Integration B>
+```
+
+## Module map
+
+| Module | Prefix / location | Responsibility |
+| ------ | ----------------- | -------------- |
+| `<module>` | `/<route>` | … |
+
+## Module conventions
+
+<!-- The shape every module follows. C9N API default: models/ (Zod namespaces) ·
+     use-cases/ (abstract static classes, execute() as a table of contents) ·
+     services/ (external integrations) · barrel exports · index.ts (routes).
+     See AGENTS.md for the full pattern. -->
+
+## Data model (key relationships)
+
+```
+<Entity A> → <Entity B> (1:N)
+…
+```
+
+## Integration boundaries
+
+| Integration | Direction | Notes |
+| ----------- | --------- | ----- |
+| <Service>   | out / in  | …     |
+
+## Per-feature design
+
+Per-feature design lives in the `## Design` section of each `docs/features/<name>.md`. The
+complete, authoritative list of features (with short-codes and links) is the registry in
+[`SRS.md`](SRS.md) — not duplicated here.

package/skills/c9n-spec/templates/docs/features/_TEMPLATE.md

@@ -0,0 +1,34 @@
+# <Feature Name> (`<SHORT-CODE>`)
+
+> Per-feature deep doc. Short-code is the feature ID and prefixes every child ID
+> (`<SHORT-CODE>-REQ-001`, `<SHORT-CODE>-TC-001`) — append-only, never renumber. Register the
+> feature + short-code in [`../SRS.md`](../SRS.md). See [`../../AGENTS.md`](../../AGENTS.md) for
+> the protocol and approval gates.
+
+## 1. Requirements
+
+<!-- The _what_. Acceptance-criteria-grade once Gate 1 is approved. -->
+
+| ID                  | Requirement | Acceptance criteria |
+| ------------------- | ----------- | ------------------- |
+| `<SHORT-CODE>-REQ-001` | …           | …                   |
+
+## 2. Design
+
+<!-- The _how_ (software design). Module(s), data flow, key decisions. Link ADRs if any. -->
+
+## 3. Test Plan
+
+<!-- How we prove it: levels, scope, what's unit vs integration vs E2E. -->
+
+## 4. Test Cases
+
+| ID                 | Scenario | Input | Expected | Traces to |
+| ------------------ | -------- | ----- | -------- | --------- |
+| `<SHORT-CODE>-TC-001` | …        | …     | …        | `<SHORT-CODE>-REQ-001` |
+
+## 5. Traceability
+
+| Requirement         | Design element | Test cases |
+| ------------------- | -------------- | ---------- |
+| `<SHORT-CODE>-REQ-001` | § 2 <section>  | `<SHORT-CODE>-TC-001` |

package/skills/c9n-spec/templates/docs/test-plan.md

@@ -0,0 +1,30 @@
+# Test Plan — Master Strategy
+
+ISO/IEC 29110 Test Cases & Procedures work product (system level). Defines how the system is
+proven. Per-feature cases live in the `## Test Cases` section of `docs/features/<name>.md`.
+
+---
+
+## Test levels
+
+| Level        | Scope                                 | Where               |
+| ------------ | ------------------------------------- | ------------------- |
+| Unit         | Use cases / services in isolation     | <app> test suite    |
+| Integration  | Route → use case → DB, external mocks | <app> test suite    |
+| Manual / E2E | End-to-end user flows                 | Documented per feature |
+
+## Conventions
+
+- Test case IDs: `<FEATURE>-TC-NNN`, append-only (see [`AGENTS.md`](../AGENTS.md)).
+- Each test case names: scenario, input, expected, and the requirement it traces to.
+- A bug fix toward spec adds a **regression** test case rather than editing the SRS.
+
+## Per-feature plans
+
+> **Characterization baselines.** As-built modules carry 🧪 _characterization_ cases — derived
+> from the code to lock in **current behavior** for regression, not grilled specs. Promote a
+> module to a grilled spec (acceptance criteria) when it is next deliberately changed.
+
+| Feature   | Plan                                            | Cases                                          |
+| --------- | ----------------------------------------------- | ---------------------------------------------- |
+| <Example> | [`features/<name>.md § 3`](features/<name>.md#3-test-plan) | [`§ 4`](features/<name>.md#4-test-cases) |

package/skills/c9n-spec/templates/docs/traceability.md

@@ -0,0 +1,27 @@
+# Traceability Record — Master Index
+
+ISO/IEC 29110 Traceability Record. Bidirectional links from each requirement to its design element
+and test cases. Per-feature matrices live in the `## Traceability` section of
+`docs/features/<name>.md`; this file indexes them and holds system-wide links.
+
+Every behavior-changing requirement MUST appear here with at least one test case.
+
+---
+
+## Per-feature traceability
+
+| Feature | Matrix |
+| ------- | ------ |
+| <Example> | [`features/<name>.md § 5`](features/<name>.md#5-traceability) |
+
+> 🧪 = **characterization baseline** (cases lock current behavior). Promote to a grilled spec when
+> the module is next deliberately changed.
+
+## How to read a matrix
+
+| Requirement   | Design element             | Test cases                 |
+| ------------- | -------------------------- | -------------------------- |
+| `EX-REQ-001`  | `<name>.md § 2 <section>`  | `EX-TC-001`, `EX-TC-002`   |
+
+- **Forward:** requirement → which design implements it → which tests prove it.
+- **Backward:** a failing `EX-TC-006` → the requirement it guards (`EX-REQ-003`).