91 lines
3.7 KiB
Markdown
91 lines
3.7 KiB
Markdown
|
---
|
||
|
|
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.
|