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,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