feat: refresh shared skills catalog
This commit is contained in:
vasily committed
1 parent
98bb35e6fb
commit
418792d1ec
49 files changed
+2273
-2390
No files matched your search
+21
-83
@@ -1,91 +1,29 @@
|
||||
---
|
||||
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]
|
||||
Create, distill, or amend SPEC.md when explicitly requested or when continuing an already-selected spec workflow.
|
||||
scope: global
|
||||
---
|
||||
|
||||
# Spec — SPEC.md Mutator
|
||||
# Specification
|
||||
|
||||
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.
|
||||
Use a repository's specification convention first, otherwise
|
||||
[the canonical format](references/format.md). Keep statements concise and precise;
|
||||
[caveman](../caveman/SKILL.md) is an optional compact notation, not a requirement.
|
||||
|
||||
---
|
||||
1. Infer the requested operation from the conversation and project state. Ask only
|
||||
if several materially different operations remain plausible.
|
||||
2. For a new spec, record the goal, constraints, external interfaces, testable
|
||||
invariants, and tasks. Include sourced research only when it was actually done.
|
||||
3. For a distillation, derive behavior from code and tests. Mark inferred intent
|
||||
and uncertainties; do not turn every TODO into an authorized implementation task.
|
||||
4. For amendments, edit the relevant sections and preserve unrelated content and
|
||||
stable IDs. Show the resulting diff; no extra approval step for an authorized edit.
|
||||
5. Check section shape and references. Report the result; suggest another workflow
|
||||
only when it helps the user's next requested action.
|
||||
|
||||
## 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.
|
||||
Ownership: `spec` owns goals, constraints, interfaces, research, task definitions,
|
||||
and general invariants. `build` may update task statuses; `backprop` may append bug
|
||||
records and amend bug-related invariants. Neither requires invoking `spec` merely
|
||||
to write its own section. Saving a spec does not start implementation without user
|
||||
intent. Follow [shared workflow](../../protocols/workflow.md).
|
||||
@@ -1,13 +1,13 @@
|
||||
# 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.
|
||||
`SPEC.md` is the single source of truth for Spec-Driven Development (SDD). Use concise plain English or the project's adopted compact notation.
|
||||
|
||||
---
|
||||
|
||||
## 1. Document Sections
|
||||
|
||||
### §G — Goal
|
||||
One single line in Caveman dialect stating the product intent.
|
||||
A concise statement of product intent.
|
||||
```markdown
|
||||
# §G
|
||||
build distributed rate limiter with sliding-window Redis Lua script.
|
||||
@@ -37,8 +37,8 @@ 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
|
||||
R1|dependency version|verified version-specific constraint|<primary-source-url>
|
||||
R2|transaction behavior|verified atomicity guarantee|<primary-source-url>
|
||||
```
|
||||
|
||||
### §V — Invariants
|
||||
@@ -73,7 +73,8 @@ B1|2026-04-20|lua script script error on empty redis key|V1
|
||||
---
|
||||
|
||||
## 2. Sectioned Ownership
|
||||
- `spec` is the sole mutator of `SPEC.md`.
|
||||
- `spec` owns goals, constraints, interfaces, research, task definitions, and general invariants.
|
||||
- `build` flips only task status (`.` → `~` → `x`).
|
||||
- `check` is strictly read-only.
|
||||
- `backprop` appends `§B` rows and drafts `§V` lines.
|
||||
- `backprop` appends `§B` rows and amends bug-related `§V` invariants.
|
||||
- Each owner may edit its sections within the authorized task without a separate handoff.
|
||||
Reference in new issue
Block a user