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
This commit is contained in:
vasily committed
1 parent
4fa17b8086
commit
5a19e1cd9d
9 files changed
+772
No files matched your search
@@ -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>`.
|
||||||
@@ -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.
|
||||||
@@ -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.
|
||||||
@@ -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.
|
||||||
|
```
|
||||||
@@ -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`.
|
||||||
@@ -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]
|
||||||
|
```
|
||||||
@@ -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]
|
||||||
|
```
|
||||||
@@ -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.
|
||||||
@@ -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.
|
||||||
Reference in new issue
Block a user