From 5a19e1cd9d85a15880c408714f08026cadc7b685 Mon Sep 17 00:00:00 2001 From: vasily Date: Tue, 13 Oct 2026 16:45:12 +0800 Subject: [PATCH] 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 | 78 ++++++++++++++++++++++++ skills/build/SKILL.md | 77 ++++++++++++++++++++++++ skills/caveman/SKILL.md | 100 +++++++++++++++++++++++++++++++ skills/check/SKILL.md | 98 ++++++++++++++++++++++++++++++ skills/deepen/SKILL.md | 78 ++++++++++++++++++++++++ skills/grill/SKILL.md | 83 +++++++++++++++++++++++++ skills/review/SKILL.md | 88 +++++++++++++++++++++++++++ skills/spec/SKILL.md | 91 ++++++++++++++++++++++++++++ skills/spec/references/format.md | 79 ++++++++++++++++++++++++ 9 files changed, 772 insertions(+) create mode 100644 skills/backprop/SKILL.md create mode 100644 skills/build/SKILL.md create mode 100644 skills/caveman/SKILL.md create mode 100644 skills/check/SKILL.md create mode 100644 skills/deepen/SKILL.md create mode 100644 skills/grill/SKILL.md create mode 100644 skills/review/SKILL.md create mode 100644 skills/spec/SKILL.md create mode 100644 skills/spec/references/format.md diff --git a/skills/backprop/SKILL.md b/skills/backprop/SKILL.md new file mode 100644 index 0000000..d11a77a --- /dev/null +++ b/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|||V +§V line: V: +``` + +### 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. + §V.: `. diff --git a/skills/build/SKILL.md b/skills/build/SKILL.md new file mode 100644 index 0000000..9dfdb88 --- /dev/null +++ b/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: `. +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: ` 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. diff --git a/skills/caveman/SKILL.md b/skills/caveman/SKILL.md new file mode 100644 index 0000000..661735b --- /dev/null +++ b/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 `` + - `∴` 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: +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 +: → +api: POST /x → 200 {id:string} +cmd: `foo bar ` → 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. diff --git a/skills/check/SKILL.md b/skills/check/SKILL.md new file mode 100644 index 0000000..fc90d14 --- /dev/null +++ b/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` 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` 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: ` or fix code at cited lines. + - MISSING: Invoke `build §T.n` or `spec amend §T`. + - STALE: Invoke `spec amend §T` to reset status. +``` diff --git a/skills/deepen/SKILL.md b/skills/deepen/SKILL.md new file mode 100644 index 0000000..20d7c3a --- /dev/null +++ b/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`. diff --git a/skills/grill/SKILL.md b/skills/grill/SKILL.md new file mode 100644 index 0000000..1a39953 --- /dev/null +++ b/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] +``` diff --git a/skills/review/SKILL.md b/skills/review/SKILL.md new file mode 100644 index 0000000..627f3d8 --- /dev/null +++ b/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: + +### NOTE +- [N1] Finding [unverified] — suggestion. + +### Gate +- **Verdict**: [GO | NO-GO] +- **Next Step**: [If NO-GO: resolve BLOCKs via spec; If GO: proceed to /build] +``` diff --git a/skills/spec/SKILL.md b/skills/spec/SKILL.md new file mode 100644 index 0000000..8945dbe --- /dev/null +++ b/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`. +3. Append row to §B table: `B|||V`. +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. diff --git a/skills/spec/references/format.md b/skills/spec/references/format.md new file mode 100644 index 0000000..913d934 --- /dev/null +++ b/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=` → 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`) or Interfaces (`I.`) 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.