feat(skills): import Spec-Driven Development (SDD) suite

- Add grill: calibrated plan stress-testing before speccing
- Add spec: sole mutator of SPEC.md with format specification
- Add caveman: token-compression dialect for invariants and tasks
- Add review: adversarial pre-implementation refutation of spec
- Add build: single-threaded plan-to-execute loop with external oracles
- Add check: read-only drift detector comparing code vs invariants
- Add backprop: bug-to-spec feedback loop binding regression tests
- Add deepen: complexity reduction and interface shrinking pass
- Format all skills to 5-phase Skill Architect anatomy with System One balance
- Synchronize symlinks across OpenCode, Codex, and Claude Code

skills/backprop/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: backprop
+description: >
+  Bug-to-spec feedback loop: when a bug occurs or test fails, traces root cause,
+  adds an invariant (§V) to prevent recurrence, logs to §B, and binds a regression test.
+  Use on test failure during build, user bug report, post-mortem, or when asked to "backprop".
+concerns: [system-one-balance]
+---
+
+# Backprop — Bug → Spec Feedback Loop
+
+Plan-then-execute fixes the code and forgets.
+Spec-Driven Development fixes the code AND amends the spec so recurrence is impossible.
+That feedback loop is **backprop**.
+
+---
+
+## Phase 0: Setup and Protocols
+
+1. **Governing Invariants**:
+   - Every bug gets a row in the §B table of `SPEC.md`.
+   - Behavioral bugs should be paired with a new §V invariant whenever a rule can prevent recurrence.
+   - A new invariant without an automated test is incomplete: always pin with a test citing the invariant.
+
+---
+
+## Phase 1: Ingest and Check
+
+1. Parse the failure input: test failure traceback, reproduction log, or user bug report.
+2. Confirm `SPEC.md` exists; if absent, invoke `spec distill` or create it before logging.
+
+---
+
+## Phase 2: Processing (Core Logic)
+
+### Step 1: Trace Root Cause
+- Locate the exact file and line producing the incorrect behavior.
+- State the root cause in one crisp Caveman sentence.
+
+### Step 2: Invariant Formulation
+Evaluate:
+- Would a testable §V invariant prevent this entire class of bug? (Commonly yes).
+- Did the interface definition (§I) promise a shape the code cannot deliver?
+- Was a task (§T) misunderstood or incomplete?
+
+Draft the proposed additions:
+```text
+§B row: B<next>|<date>|<root cause>|V<N>
+§V line: V<next>: <testable rule that would have caught it>
+```
+
+### Step 3: Pin Reproduction Test
+- Author a failing regression test before modifying application code.
+- Name the test to cite the invariant: e.g. `test_v7_refund_idempotent()`.
+
+### Step 4: Implement Fix & Verify
+- Apply minimal surgical code fix.
+- Run the regression test to confirm green.
+- Run the full project test suite to verify no collateral regressions.
+
+---
+
+## Phase 3: The System One Balance Pass
+
+- **Augment, Don't Handcuff**:
+  - Do NOT invent artificial §V rules for one-off typos or transient external network outages (log in §B, but skip §V).
+  - State invariants positively where possible (`! hold` rather than complex negative conditionals).
+
+---
+
+## Phase 4: Output Execution & Verification
+
+Every complete backprop run produces:
+1. Append to §B table in `SPEC.md`.
+2. Append to §V invariants (when applicable).
+3. Passing regression test.
+4. Minimal code fix.
+5. Atomic git commit: `backprop §B.<n> + §V.<N>: <one-line cause>`.

skills/build/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: build
+description: >
+  Plan-then-execute implementation loop against SPEC.md tasks. Operates single-threaded on main agent thread.
+  Executes tasks in order, runs verification tests as external oracles, and triggers backprop on failure.
+  Use when asked to "build", "implement spec", "build §T.n", "build next task", or "run the build".
+concerns: [system-one-balance]
+---
+
+# Build — Implement Spec
+
+Single-threaded native plan → execute loop against `SPEC.md`.
+
+---
+
+## Phase 0: Setup and Protocols
+
+1. **Verify Prerequisites**:
+   - `SPEC.md` must exist at the project root. If absent, defer to `spec` to author it first.
+   - Read §R if present: external facts the build must honor, never contradict or re-derive.
+   - For high-blast-radius changes (shared modules, auth, payments, database migrations), confirm `/review` has run.
+
+---
+
+## Phase 1: Ingest and Check
+
+1. Parse invocation arguments:
+   - `§T.n`: Target specific task row.
+   - `--next`: Target the lowest-numbered row with status `.` or `~`.
+   - `--all` (or empty): Execute every pending `.` row in sequential order.
+2. Confirm verification oracle:
+   - Identify the exact automated command (e.g. `pytest`, `cargo test`, `npm test`) that verifies completion.
+
+---
+
+## Phase 2: Processing (Core Logic)
+
+### Step 1: Plan Task Implementation
+For the chosen task(s):
+1. Cite every §V invariant that applies; the implementation must satisfy all.
+2. Cite every §I interface touched; preserve specified signatures and shapes.
+3. List files to create or modify.
+4. Establish the verification contract: specify which concrete test will prove each §V touched.
+
+### Step 2: Sequential Execution
+For each task in order:
+1. Flip `§T.n` status cell from `.` → `~` in `SPEC.md`.
+2. Edit code according to plan.
+3. Run the verification command.
+4. **Pass**: Flip `~` → `x` in `SPEC.md`. Create atomic commit: `T<n>: <task description>`.
+5. **Fail**: Do NOT retry blindly; route to Failure Recovery.
+
+### Step 3: Failure Recovery & Backprop
+When a verification test fails:
+1. Inspect failure output.
+2. Determine failure classification:
+   - **Code defect in task**: Fix code and re-test.
+   - **Spec defect or unhandled edge case**: Invoke `backprop` with `bug: <cause>` to record in §B and draft §V before resuming.
+
+---
+
+## Phase 3: The System One Balance Pass
+
+- **Augment, Don't Handcuff**:
+  - Keep execution single-threaded on the main agent; avoid uncoordinated background subagent sprawl.
+  - Flip only §T status cells in `SPEC.md` during build; leave architectural changes to `spec`.
+  - Avoid speculative work beyond the assigned task.
+
+---
+
+## Phase 4: Output Execution & Verification
+
+A task is verified as complete (`x`) only when:
+1. The verification command exits with code 0.
+2. Every §V touched has an automated passing test.
+3. Full test suite passes with zero regressions.
+4. `SPEC.md` reflects current completion state.

skills/caveman/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: caveman
+description: >
+  Token-compression encoding dialect for SPEC.md and spec-adjacent writes (~75% reduction vs prose).
+  Preserves code identifiers and invariants verbatim while dropping filler and using formal symbols.
+  Use when writing or editing SPEC.md, when asked to "caveman", "compress this", or "be brief".
+concerns: [system-one-balance]
+---
+
+# Caveman — Spec Encoding
+
+Applies to `SPEC.md` writes, spec-referencing text, and backprop entries.
+Does NOT apply to code, error strings, commit messages, or PR descriptions.
+
+---
+
+## Phase 0: Setup and Protocols
+
+1. **Grammar Invariants**:
+   - Drop articles (a, an, the).
+   - Drop filler (just, really, basically, simply, actually).
+   - Drop auxiliary verbs where fragments work (is, are, was, were, being).
+   - Drop pleasantries and hedging ("might", "perhaps", "could be worth").
+   - Short synonyms: fix > implement, big > extensive, run > execute.
+2. **Symbol Table**:
+   - `→` leads to / becomes / on `<x>`
+   - `∴` therefore / fix
+   - `∀` for all / every
+   - `∃` exists / some
+   - `!` must / required
+   - `?` may / optional / unknown
+   - `⊥` never / forbidden / nil
+   - `≠` not equal
+   - `∈` in, `∉` not in
+   - `≤` at most, `≥` at least
+   - `&` and, `|` or
+   - `§` section reference
+3. **Preserve Verbatim**:
+   - Never compress code blocks, paths (`src/auth/mw.go`), URLs, identifiers (`function_name`), numbers/versions, error strings, SQL/JSON/YAML, or quoted strings.
+
+---
+
+## Phase 1: Ingest and Check
+
+1. Confirm target document: `SPEC.md` section, backprop row, or prompt.
+2. Verify target is spec or technical invariant, NOT human prose, code, or commit messages.
+3. If user asks for prose explanation, switch to standard English.
+
+---
+
+## Phase 2: Processing (Core Logic)
+
+Encode into canonical Caveman shapes:
+
+### 1. Invariant (§V)
+```text
+V<n>: <subject> <relation> <condition>
+V1: ∀ req → auth check before handler
+V2: token expiry ≤ current_time → reject
+```
+
+### 2. Bug Row (§B pipe table)
+```text
+id|date|cause|fix
+B1|2026-04-20|token `<` not `≤`|V2
+```
+
+### 3. Task Row (§T pipe table)
+```text
+id|status|task|cites
+T3|x|add auth mw|V1,I.api
+```
+*Status: `x` done, `~` wip, `.` todo. Escape literal `|` as `\|`.*
+
+### 4. Interface (§I)
+```text
+<kind>: <name> → <shape>
+api: POST /x → 200 {id:string}
+cmd: `foo bar <arg>` → stdout JSON
+env: FOO_KEY ! set
+```
+
+---
+
+## Phase 3: The System One Balance Pass
+
+- **Compression, Not Amputation**:
+  - If cutting a word loses an invariant or factual boundary, keep the word.
+  - Never sacrifice precision for token brevity.
+  - Fail open to standard English when ambiguous.
+
+---
+
+## Phase 4: Output Execution & Verification
+
+1. Output compressed text in valid Markdown.
+2. Verify:
+   - All code tokens, identifiers, and paths are intact.
+   - All symbols use standard UTF-8 characters (`→`, `∀`, `⊥`, `!`).
+   - Pipe tables parse cleanly with balanced delimiters.

skills/check/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: check
+description: >
+  Read-only drift detector comparing SPEC.md against current codebase.
+  Audits invariants (§V), interface shapes (§I), and task completion (§T), reporting violations with file:line citations.
+  Use when asked to "check drift", "audit spec", "spec vs code", or before releasing.
+concerns: [system-one-balance]
+---
+
+# Check — Drift Detector
+
+Pure diagnostic audit. Reports violations and interface drift. Strictly read-only; writes nothing.
+
+Spec drifting silently from code is the primary failure mode of long-lived projects. `check` catches drift before it becomes production defects.
+
+---
+
+## Phase 0: Setup and Protocols
+
+1. **Non-Negotiable Invariants**:
+   - **Zero Writes**: Never edit code or `SPEC.md`. Report findings only.
+   - Every violation must cite `file:line` evidence.
+   - If `SPEC.md` is absent at repo root, report "no spec found" and exit.
+
+---
+
+## Phase 1: Ingest and Check
+
+1. Ingest `SPEC.md` from the project root.
+2. Parse audit scope from arguments:
+   - `§V`: Audit invariants only (default).
+   - `§I`: Audit external interfaces only.
+   - `§T`: Audit task status against reality.
+   - `--all` (or empty): Audit all three sections.
+
+---
+
+## Phase 2: Processing (Core Logic)
+
+### Step 1: Audit Invariants (§V)
+For each `V<n>` invariant:
+1. Translate invariant into a verifiable assertion about code.
+2. Search and inspect corresponding files.
+3. Classify state:
+   - **HOLD**: Invariant actively satisfied with test or code assertion.
+   - **VIOLATE**: Invariant actively violated in implementation.
+   - **UNVERIFIABLE**: Invariant has no corresponding automated test or code guard.
+
+### Step 2: Audit Interfaces (§I)
+For each interface defined in §I:
+1. Locate implementation in routes, CLI, or exported functions.
+2. Classify state:
+   - **MATCH**: Code shape matches §I specification exactly.
+   - **DRIFT**: Implementation exists but signatures, parameters, or return types diverge.
+   - **MISSING**: Interface declared in spec but absent from code.
+   - **EXTRA**: Code exposes public endpoints/flags not documented in §I.
+
+### Step 3: Audit Tasks (§T)
+For each `T<n>` row:
+1. If status is `x`: verify claimed files/tests exist in git. If absent, flag **STALE**.
+2. If status is `~`: note as in-progress.
+3. If status is `.`: note as pending.
+
+---
+
+## Phase 3: The System One Balance Pass
+
+- **Augment, Don't Handcuff**:
+  - Report findings concisely without lecturing or auto-triggering refactors.
+  - Provide actionable remedy hints for each class of drift, leaving decisions to the user.
+
+---
+
+## Phase 4: Output Execution & Verification
+
+Emit the structured Caveman drift report:
+
+```markdown
+## Drift Report
+
+### §V Invariants
+- V2 VIOLATE: src/auth/mw.ts:47 uses `<` instead of `≤`.
+- V5 UNVERIFIABLE: no test covers concurrent refund boundary.
+
+### §I Interfaces
+- I.api DRIFT: POST /v1/charge returns `{result}` instead of `{id}`. routes/charge.py:82.
+- I.cmd MISSING: `limiter bench` absent from CLI definitions.
+
+### §T Tasks
+- T3 STALE: marked `x` but auth middleware file not found in tree.
+
+### Summary
+- X violations, Y drifts, Z missing, W stale.
+- **Remedy Hints**:
+  - VIOLATE / DRIFT: Invoke `spec` with `bug: <V.n>` or fix code at cited lines.
+  - MISSING: Invoke `build §T.n` or `spec amend §T`.
+  - STALE: Invoke `spec amend §T` to reset status.
+```

skills/deepen/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: deepen
+description: >
+  Codebase design improvement pass that finds shallow modules, shrinks interfaces, and pulls complexity down.
+  Hides decisions behind clean boundaries with behavior held constant and full test suite green.
+  Use when asked to "deepen this", "improve design", "module feels shallow", or "pull complexity down".
+concerns: [system-one-balance]
+---
+
+# Deepen — Make Modules Deep
+
+**Behavior is sacred**: tests must be green before AND after. Every change shrinks an interface surface or hides a private decision. Deepen, don't churn.
+
+A **deep module** hides substantial internal logic behind a simple interface; a **shallow module**'s interface is nearly as complex as its implementation.
+
+---
+
+## Phase 0: Setup and Protocols
+
+1. **Invariants**:
+   - Never change observable behavior during a deepening pass.
+   - Run only when the test suite is fully passing.
+   - Refactor one module per pass; deepening is surgical, never a wide codebase rewrite.
+   - Avoid speculative abstraction: single-use code does not need complex generalization.
+
+---
+
+## Phase 1: Ingest and Check
+
+1. Confirm test suite is green.
+2. Scan the modules touched by the active spec or recent tasks.
+3. Identify shallowness symptoms:
+   - Pass-through methods that simply forward to another layer.
+   - Callers required to set 5+ configuration flags to perform a basic action.
+   - Leaked internal mechanisms (e.g. caller forced to know rotation policies or cache keys).
+
+---
+
+## Phase 2: Processing (Core Logic)
+
+### Step 1: Diagnose Shallowness
+Cite the exact defect in Caveman style with `file:line`:
+> `src/auth/token.go:42`: 6-arg constructor leaks rotation policy to every caller. Shallow interface.
+
+### Step 2: Design the Deeper Interface
+Apply core deepening principles:
+- **Pull Complexity Down**: Move complex parameter coordination inside the module; provide callers with a clean, obvious default.
+- **Define Errors Out of Existence**: Structure signatures so invalid states cannot be represented or called.
+- **Information Hiding**: Keep internal data structures private so callers never depend on implementation details.
+
+### Step 3: Propose Spec Updates
+Draft changes for `spec`:
+- New, simplified §I interface shape.
+- New §V invariant preventing future regressions into shallowness.
+- Targeted §T refactoring task.
+
+### Step 4: Execute & Verify Behavior
+- Implement refactor behind existing tests.
+- Verify test suite passes with zero failures.
+- Add tests confirming backwards compatibility or clean interface boundaries.
+
+---
+
+## Phase 3: The System One Balance Pass
+
+- **Augment, Don't Handcuff**:
+  - Run only when deliberate design improvements are requested or token budget permits; never interrupt active feature delivery.
+  - One module per pass. Deepen the single worst offender and stop.
+
+---
+
+## Phase 4: Output Execution & Verification
+
+Deliver the deepening summary:
+1. **Interface Comparison**: Show concise before vs. after interface signature.
+2. **Complexity Hidden**: What private decision callers no longer have to manage.
+3. **Verification**: Confirm full test suite passed.
+4. **Proposed Spec Edits**: Drafted lines to hand to `spec`.

skills/grill/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: grill
+description: >
+  Calibrated interrogation to stress-test a fuzzy plan, design, or architecture before writing a spec or code.
+  Asks one question at a time with recommended answers to extract concrete goals (§G) and constraints (§C).
+  Use when asked to "grill me", "stress-test this", "challenge my plan", or before authoring a spec.
+concerns: [system-one-balance]
+---
+
+# Grill — Calibrated Plan Stress-Testing
+
+Drags ambiguity into concrete goals (§G) and constraints (§C) *before* execution begins. A bad assumption caught here costs one question; caught later, it costs an architectural refactor.
+
+---
+
+## Phase 0: Setup and Protocols
+
+1. **Interrogation Invariants**:
+   - **One Question at a Time**: Never ask multiple questions in a single turn. Ask one question, provide a recommended answer, and wait.
+   - **Recommend an Answer**: Always provide a concrete default so the user can reply with "yes" or choose an alternative.
+   - **Inspect Context First**: If an answer can be found in files, code, docs, or git history, inspect them directly instead of asking the user.
+   - **Propose, Don't Decide**: Challenge tradeoffs and surface hidden edge cases, but leave final product choices to the user.
+
+---
+
+## Phase 1: Ingest and Check
+
+1. Determine user knowledge and desired pressure level from context:
+   - **Knowledge Level**:
+     - *New*: Explain missing frames briefly (2 sentences); focus on first principles and goals.
+     - *Working*: Challenge standard tradeoffs, alternatives, and validation criteria.
+     - *Expert*: Probe failure modes, boundary limits, migration costs, and reversibility.
+   - **Pressure Level**:
+     - *Light*: Clarify goals, scope, and missing definitions.
+     - *Standard*: Challenge assumptions, resource bottlenecks, and execution paths.
+     - *Hard*: Probe edge cases, adverse incentives, failure modes, and rollback mechanisms.
+
+---
+
+## Phase 2: Processing (Core Logic)
+
+Climb the Question Ladder in sequence. Stop as soon as the plan is clear; do not ask every rung by reflex:
+1. **Goal (§G)**: What must the code or feature accomplish in one single, unambiguous sentence?
+2. **Done Criteria (§C / §V)**: What observable signal (test, metric, terminal output) proves this works?
+3. **Boundaries (§C)**: What is explicitly *out of scope* for this change?
+4. **Non-Negotiables (§C)**: What architectural patterns, libraries, or constraints are strictly required or forbidden?
+5. **Surfaces (§I)**: What external membranes (API endpoints, CLI flags, DB tables, schemas) will be modified?
+6. **Failure Modes (§V)**: What is the primary edge case or input that breaks the happy path?
+7. **Unknowns (`?`)**: What do we not yet know? (Park unresolved items as `?` bullets; do not guess them).
+
+### Question Format
+```text
+Question: ...
+Recommended answer: ...
+Why it matters: [1 sentence rationale]
+```
+
+---
+
+## Phase 3: The System One Balance Pass
+
+- **Augment, Don't Handcuff**:
+  - Stop grilling immediately once the goal and boundaries are defined.
+  - Never interrogate the user on routine file edits, typo fixes, or straightforward tasks.
+  - Accept the user's recommended answer or override without debate.
+
+---
+
+## Phase 4: Output Execution & Verification
+
+Stop grilling when **all** of the following hold:
+- §G is one line, one reading, zero "or maybe".
+- §C covers every non-negotiable stated or implied.
+- Every blocking unknown is answered or parked as an explicit `?`.
+
+Emit the structured handoff block to pass to the **spec** or **build** workflow:
+```markdown
+## Grill Handoff
+- **§G**: [One-line goal]
+- **§C**: [Constraints and non-negotiables]
+- **§I**: [Surfaces touched]
+- **Parked Unknowns (`?`)**: [Items deferred to research]
+```

skills/review/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: review
+description: >
+  Adversarial pre-implementation review of SPEC.md. Attempts to refute the spec before code is written,
+  grounding findings in codebase evidence, §R research, and current best practices.
+  Use when asked to "review spec", "red-team spec", "is this plan sound", or before high-blast-radius builds.
+concerns: [system-one-balance]
+---
+
+# Review — Refute the Spec Before Build
+
+Every finding cites evidence — `file:line` or an authoritative source. No evidence → label `[unverified]`. A defect you cannot prove is a note, not a blocker.
+
+---
+
+## Phase 0: Setup and Protocols
+
+1. Review governing invariants:
+   - Review the *spec*, not conversational memory.
+   - An LLM cannot self-correct reliably on vibes alone; the reviewer must anchor to external oracles (code, tests, §R).
+   - Skip review for trivial, reversible edits; right-size review effort to blast radius.
+
+---
+
+## Phase 1: Ingest and Check
+
+1. **Capture the Spec**:
+   - Ingest all active sections of `SPEC.md`: §G, §C, §I, §R, §V, §T, §B.
+2. **Construct the Reviewer Profile**:
+   - Inspect the codebase modules touched by the spec to verify existing patterns and constraints.
+   - Check §R research findings: any spec assertion contradicting §R is an immediate finding.
+   - For unverified best-practice assumptions, verify them before citing.
+
+---
+
+## Phase 2: Processing (Core Logic)
+
+### Step 1: Adversarial Refutation
+Attempt to refute the spec along these axes:
+- **Goal vs. Reality**: Does §G address the actual requirement or a proxy?
+- **Missing Invariants**: What failure mode exists that no §V catches?
+- **Interface Drift**: Does §I match what existing callers in the codebase expect? Cite caller `file:line`.
+- **Constraint Conflicts**: Do two bullets in §C contradict each other or violate §R?
+- **Unowned Edges**: What concurrency, ordering, or failure scenario has no assigned §T?
+- **Altitude Check**: Are tasks in §T too vague to verify, or overly granular?
+
+### Step 2: Classify Findings
+Assign findings to three explicit categories:
+- **BLOCK**: High risk of shipping a real defect. Must be resolved before building.
+- **HARDEN**: Add or sharpen a §V invariant so build cannot regress it.
+- **NOTE**: Worth noting for future consideration; non-blocking.
+
+*Any claim lacking codebase or documentation evidence is down-ranked to NOTE and tagged `[unverified]`.*
+
+### Step 3: Draft §V Amendments
+- Translate each HARDEN finding into a testable §V draft line citing the interface or behavior guarded.
+
+---
+
+## Phase 3: The System One Balance Pass
+
+- **Augment, Don't Handcuff**:
+  - Never review trivia or low-risk tasks (typos, minor styling, internal helper adjustments).
+  - Never fabricate synthetic BLOCK findings to look thorough; if the spec holds, issue an immediate GO verdict.
+  - Review hardens the spec; it does NOT alter user intent or product direction.
+
+---
+
+## Phase 4: Output Execution & Verification
+
+Emit the review verdict and go/no-go gate:
+
+```markdown
+## Review Verdict
+
+### BLOCK (must resolve before build)
+- [B1] Finding — evidence (file:line or doc citation) — remedy.
+
+### HARDEN (drafted §V invariants)
+- [H1] Draft V<N>: <testable invariant guarding behavior>
+
+### NOTE
+- [N1] Finding [unverified] — suggestion.
+
+### Gate
+- **Verdict**: [GO | NO-GO]
+- **Next Step**: [If NO-GO: resolve BLOCKs via spec; If GO: proceed to /build]
+```

skills/spec/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: spec
+description: >
+  Sole mutator of SPEC.md at project root. Creates new specs, distills specs from existing code,
+  amends sections (§G, §C, §I, §R, §V, §T, §B), and records bugs via backprop in Caveman dialect.
+  Use when asked to "write spec", "new spec", "amend spec", "distill spec", or "spec this".
+concerns: [system-one-balance]
+---
+
+# Spec — SPEC.md Mutator
+
+The sole mutator of `SPEC.md`. Other skills produce material (`grill` → §G/§C, `research` → §R, `review` → §V, `deepen` → §I/§T); `spec` writes it. All sections follow Caveman encoding.
+
+---
+
+## Phase 0: Setup and Protocols
+
+1. Review specification format:
+   - Check repo root for `FORMAT.md`, or consult [references/format.md](references/format.md).
+   - Apply [caveman](../caveman/SKILL.md) encoding rules across all section writes.
+2. Section Invariants:
+   - §G (Goal): 1 line, Caveman dialect.
+   - §C (Constraints): Tech stack, out-of-scope declarations.
+   - §I (Interfaces): External membranes (api, cmd, env).
+   - §R (Research): External sourced findings (optional).
+   - §V (Invariants): Monotonically numbered `V1`, `V2`, ...
+   - §T (Tasks): Pipe table (`id|status|task|cites`), status `.`, `~`, `x`.
+   - §B (Bug Log): Pipe table (`id|date|cause|fix`).
+
+---
+
+## Phase 1: Ingest and Check
+
+Inspect project state and user intent to dispatch the mode:
+1. No `SPEC.md` exists AND idea provided → **NEW**
+2. No `SPEC.md` exists AND `from-code` requested → **DISTILL**
+3. `SPEC.md` exists AND request starts with `bug:` → **BACKPROP**
+4. `SPEC.md` exists AND request starts with `amend` → **AMEND**
+5. `SPEC.md` exists with no args → Prompt user for desired mode.
+
+---
+
+## Phase 2: Processing (Core Logic)
+
+### Mode 1: NEW (Idea → Spec)
+1. Extract single-line goal → §G.
+2. List user stated and implied constraints → §C.
+3. List external boundaries and surfaces → §I.
+4. Include §R only if external research ran; otherwise omit.
+5. Propose initial testable invariants → §V (`V1`, `V2`, ...).
+6. Break goal into ordered sequential tasks → §T pipe table with status `.`.
+7. Initialize empty §B table header (`id|date|cause|fix`).
+
+### Mode 2: DISTILL (Codebase → Spec)
+1. Walk repository: infer §G from README/entrypoint, §C from stack/lockfiles.
+2. Enumerate exported APIs, CLI commands, and env vars → §I.
+3. Derive behavioral invariants from existing tests → §V.
+4. Create tasks for known TODOs or untested edge cases → §T.
+5. Flag uncertainties with `?` for user confirmation.
+
+### Mode 3: BACKPROP (Bug → §B + §V)
+1. Parse bug description and identify root cause in code.
+2. Formulate a testable invariant preventing recurrence → draft `V<next>`.
+3. Append row to §B table: `B<next>|<date>|<cause>|V<N>`.
+4. Append new invariant to §V.
+5. Update or add tasks in §T if behavior changes.
+
+### Mode 4: AMEND (Targeted Edit)
+1. Read the specified section (§G, §C, §I, §V, §T, or §B).
+2. Show current content and propose the exact modification.
+3. Never rewrite sections the user did not specify.
+
+---
+
+## Phase 3: The System One Balance Pass
+
+- **Augment, Don't Handcuff**:
+  - Show a clear diff before applying changes.
+  - Do NOT trigger automatic build loops upon saving; require explicit user intent to proceed to `/build`.
+  - Avoid ceremony for minor amendments: apply targeted updates swiftly.
+
+---
+
+## Phase 4: Output Execution & Verification
+
+1. Write or update `SPEC.md` at project root.
+2. Verify:
+   - Section identifiers (§G, §C, §I, §V, §T, §B) match canonical format.
+   - Numbering in §V and §B is monotonic with no reused IDs.
+   - All §T rows cite their respective dependencies in the `cites` column.
+3. Present the diff/file and suggest next action: `/review` for high-blast-radius specs, or `/build` for execution.

skills/spec/references/format.md

@@ -0,0 +1,79 @@
+# SPEC.md Canonical Format Specification
+
+`SPEC.md` is the single source of truth for Spec-Driven Development (SDD). All sections are written in Caveman encoding.
+
+---
+
+## 1. Document Sections
+
+### §G — Goal
+One single line in Caveman dialect stating the product intent.
+```markdown
+# §G
+build distributed rate limiter with sliding-window Redis Lua script.
+```
+
+### §C — Constraints
+Hard constraints, technology stack limits, and explicit out-of-scope declarations.
+```markdown
+# §C
+- Go 1.22+ stdlib + go-redis/v9.
+- ⊥ external dependencies outside Redis.
+- memory overhead ≤ 50MB @ 100k keys.
+- out of scope: clustering, dynamic cluster topology changes.
+```
+
+### §I — Interfaces
+Public membranes: CLI commands, API endpoints, environment variables, or exported signatures.
+```markdown
+# §I
+api: POST /v1/limiter/check → 200 {allowed:bool, remaining:int, reset_ms:int}
+cmd: `limiter-cli bench --rate=<n>` → stdout benchmark summary
+env: REDIS_URL ! set
+```
+
+### §R — Research Log (Optional)
+Distilled external facts, primary documentation links, or RFC references.
+```markdown
+# §R
+id|domain|finding|source
+R1|redis lua|reclaim memory via `redis.replicate_commands()`|redis.io/docs/manual/programmability/lua-api
+R2|token bucket|GCRA algorithm reduces atomic roundtrips to 1|en.wikipedia.org/wiki/Generic_cell_rate_algorithm
+```
+
+### §V — Invariants
+Non-negotiable behavioral invariants. Numbered monotonically `V1`, `V2`, ...
+```markdown
+# §V
+V1: ∀ check req → atomic sliding window evaluate in Redis Lua
+V2: Redis down → fail open (return allowed:true with header warning)
+V3: latency p99 ≤ 2ms @ 10k rps
+```
+
+### §T — Tasks
+Ordered pipe table of implementation tasks. Numbered `T1`, `T2`, ...
+- Status: `.` todo, `~` wip, `x` done.
+- `cites`: Invariants (`V<n>`) or Interfaces (`I.<name>`) that the task must satisfy.
+```markdown
+# §T
+id|status|task|cites
+T1|x|scaffold Redis client with fallback|V2,I.api
+T2|~|implement sliding window Lua script|V1
+T3|.|expose HTTP endpoint & healthcheck|I.api
+```
+
+### §B — Bug Log
+Feedback memory capturing bugs and regressions found during build/check/production.
+```markdown
+# §B
+id|date|cause|fix
+B1|2026-04-20|lua script script error on empty redis key|V1
+```
+
+---
+
+## 2. Sectioned Ownership
+- `spec` is the sole mutator of `SPEC.md`.
+- `build` flips only task status (`.` → `~` → `x`).
+- `check` is strictly read-only.
+- `backprop` appends `§B` rows and drafts `§V` lines.