mirror of
https://github.com/JuliusBrussee/cavekit.git
synced 2026-09-14 16:32:40 +08:00
feat: mirror commands into skills/ for npx skills install path
Add skills/spec, skills/build, skills/check as SKILL.md files mirroring the corresponding command prompts. Each has a description frontmatter that triggers auto-activation when the user asks to write a spec, run a build, or check drift. Keeps commands/ intact for the plugin-install slash-command path; the two are kept in sync at the prose level. `npx skills add JuliusBrussee/cavekit` now installs all five skills (spec, build, check, caveman, backprop). The three /ck: slash commands remain available via plugin marketplace install. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Julius Brussee
@@ -34,17 +34,20 @@ That's the whole pitch.
|
||||
|
||||
## install
|
||||
|
||||
One line, via the `skills` CLI — installs commands and skills together:
|
||||
One line, via the `skills` CLI:
|
||||
|
||||
```bash
|
||||
npx skills add JuliusBrussee/cavekit
|
||||
```
|
||||
|
||||
Drops `/ck:spec`, `/ck:build`, `/ck:check` into `~/.claude/commands/` and
|
||||
the `caveman` + `backprop` skills into `~/.claude/skills/`. Claude Code
|
||||
Installs five skills into `~/.claude/skills/`: `spec`, `build`, `check`
|
||||
(the workflow) plus `caveman` and `backprop` (the utilities). Claude
|
||||
activates each when its trigger context matches — e.g. "write a spec
|
||||
for…" invokes `spec`, "build the next task" invokes `build`. Claude Code
|
||||
picks them up on next launch.
|
||||
|
||||
Or via the Claude Code marketplace:
|
||||
Or via the Claude Code marketplace (also adds `/ck:spec`, `/ck:build`,
|
||||
`/ck:check` slash commands):
|
||||
|
||||
```bash
|
||||
/plugin marketplace add juliusbrussee/cavekit
|
||||
@@ -66,8 +69,11 @@ See [`FORMAT.md`](./FORMAT.md). Fixed sections: §G goal, §C constraints,
|
||||
|
||||
```
|
||||
FORMAT.md spec schema + caveman encoding rules
|
||||
commands/ three markdown command prompts
|
||||
skills/caveman encoding skill
|
||||
commands/ three slash-command entry points (/ck:spec, /ck:build, /ck:check)
|
||||
skills/spec spec mutator (mirrors commands/spec.md as a skill)
|
||||
skills/build plan-execute skill (mirrors commands/build.md)
|
||||
skills/check drift report skill (mirrors commands/check.md)
|
||||
skills/caveman encoding utility
|
||||
skills/backprop bug → spec protocol (six steps)
|
||||
```
|
||||
|
||||
|
||||
@@ -0,0 +1,76 @@
|
||||
---
|
||||
name: build
|
||||
description: |
|
||||
Plan-then-execute implementation against SPEC.md. Native single-thread
|
||||
loop, no sub-agents. On test or build failure, auto-invokes the backprop
|
||||
skill before retrying — a failed verification always considers whether
|
||||
a new §V invariant would prevent recurrence. Triggers when the user asks
|
||||
to build, implement, execute the spec, or tackle a specific §T task
|
||||
(`build §T.3`, `build --next`, `implement next task`, `run the build`).
|
||||
Expects SPEC.md to exist; if not, defers to the spec skill.
|
||||
---
|
||||
|
||||
# build — implement spec
|
||||
|
||||
Single-thread native plan→execute. You are main Claude. No swarm.
|
||||
|
||||
## LOAD
|
||||
|
||||
1. Read `SPEC.md`. If missing → tell user to invoke the spec skill first. Stop.
|
||||
2. Read `FORMAT.md` once if not loaded.
|
||||
3. Parse invocation args:
|
||||
- `§T.n` → that task only
|
||||
- `--next` → lowest-numbered row with status `.` or `~`
|
||||
- `--all` or empty → every `.` row in §T order
|
||||
|
||||
## PLAN
|
||||
|
||||
Native plan mode. For chosen task(s):
|
||||
|
||||
1. Cite every §V invariant that applies. Plan must respect all.
|
||||
2. Cite every §I interface touched. Plan must preserve shape.
|
||||
3. List files to create / edit.
|
||||
4. List tests to add or update (one per invariant touched).
|
||||
5. Name verification command (test, build, lint).
|
||||
|
||||
Show plan. Wait for user OK unless auto mode.
|
||||
|
||||
## EXECUTE
|
||||
|
||||
Per task in order:
|
||||
|
||||
1. Flip §T.n status cell `.` → `~`. Just write to SPEC.md.
|
||||
2. Edit code per plan.
|
||||
3. Run verification command.
|
||||
4. **Pass** → flip `~` → `x`. Next task.
|
||||
5. **Fail** → invoke backprop skill. Do NOT retry blindly.
|
||||
|
||||
## FAIL → BACKPROP
|
||||
|
||||
On test/build failure:
|
||||
|
||||
1. Read failure output.
|
||||
2. Ask: is failure (a) my code bug, (b) spec wrong, or (c) unspecified edge case?
|
||||
3. If (a) → fix code, re-run. No spec change.
|
||||
4. If (b) or (c) → invoke spec skill with `bug: <cause>` first, let it update §V and §B, then resume build against updated spec.
|
||||
|
||||
Rule: never silently fix root-cause without considering backprop. §B is the memory that stops recurrence.
|
||||
|
||||
## WRITE POLICY
|
||||
|
||||
- Only flip §T status. No other SPEC.md edits from build.
|
||||
- Other spec edits → invoke spec skill.
|
||||
- Commit after each §T completes. Message: `T<n>: <goal line>` + §V cites.
|
||||
|
||||
## VERIFICATION
|
||||
|
||||
Task `x` only if:
|
||||
- Verification command exits 0.
|
||||
- New test(s) added per plan.
|
||||
- No §V invariant regressed (run full test suite at end).
|
||||
|
||||
## NON-GOALS
|
||||
|
||||
- No sub-agents. No parallel workers. Main thread only.
|
||||
- No progress dashboards. `cat SPEC.md | grep §T` is the dashboard.
|
||||
- No speculative work beyond chosen task scope.
|
||||
@@ -0,0 +1,89 @@
|
||||
---
|
||||
name: check
|
||||
description: |
|
||||
Read-only drift detector. Diffs SPEC.md against current code and reports
|
||||
violations grouped by severity. Writes nothing — suggests remedies via
|
||||
the spec or build skills but never invokes them. Triggers when the user
|
||||
asks to check drift, audit the spec, verify invariants, or ask whether
|
||||
code still matches the spec. Phrasings: "check drift", "audit the spec",
|
||||
"does the code still match §V", "check invariants", "spec vs code".
|
||||
---
|
||||
|
||||
# check — drift report
|
||||
|
||||
Pure diagnostic. Reports violations. Writes nothing. User decides remedy.
|
||||
|
||||
## LOAD
|
||||
|
||||
1. Read `SPEC.md`. If missing → "no spec, nothing to check." Stop.
|
||||
2. Parse invocation args:
|
||||
- `§V` → check invariants only (default)
|
||||
- `§I` → check interfaces
|
||||
- `§T` → audit task status vs code
|
||||
- `--all` → all three
|
||||
|
||||
## CHECK §V — invariants
|
||||
|
||||
For each V<n>:
|
||||
|
||||
1. Translate invariant into verifiable claim about code.
|
||||
2. Grep / read relevant files.
|
||||
3. Classify: **HOLD** / **VIOLATE** / **UNVERIFIABLE**.
|
||||
4. Record address + file:line evidence.
|
||||
|
||||
## CHECK §I — interfaces
|
||||
|
||||
For each I item:
|
||||
|
||||
1. Locate implementation.
|
||||
2. Classify:
|
||||
- **MATCH** — shape in code = shape in spec.
|
||||
- **DRIFT** — impl exists, shape differs.
|
||||
- **MISSING** — impl absent.
|
||||
- **EXTRA** — code exposes surface not in §I.
|
||||
|
||||
## CHECK §T — tasks
|
||||
|
||||
For each T<n>:
|
||||
|
||||
1. If `x`: verify claimed work present.
|
||||
2. If `~`: note as in-progress.
|
||||
3. If `.`: note as pending.
|
||||
4. Flag `x` rows with no evidence as **STALE**.
|
||||
|
||||
## REPORT
|
||||
|
||||
Caveman. Grouped by severity.
|
||||
|
||||
```
|
||||
## §V drift
|
||||
V2 VIOLATE: auth/mw.go:47 uses `<` not `≤`. see §B.1.
|
||||
V5 UNVERIFIABLE: no test covers ∀ req path.
|
||||
|
||||
## §I drift
|
||||
I.api DRIFT: POST /x returns `{result}` not `{id}`. route.go:112.
|
||||
I.cmd MISSING: `foo bar` absent from cli/*.go.
|
||||
|
||||
## §T drift
|
||||
T3 STALE: status `x`, no middleware file exists.
|
||||
|
||||
## summary
|
||||
2 violate. 1 missing. 1 stale. 1 unverifiable.
|
||||
next: spec skill with `bug:` or fix code at cited lines.
|
||||
```
|
||||
|
||||
## REMEDY HINTS (not actions)
|
||||
|
||||
End report with one-line hint per class:
|
||||
- VIOLATE / DRIFT → invoke spec skill `bug: <V.n>` or fix code.
|
||||
- MISSING → invoke build skill on `§T.n` if task exists; else spec skill `amend §T`.
|
||||
- STALE → spec skill `amend §T` to uncheck.
|
||||
- EXTRA → spec skill `amend §I` to document, or delete code.
|
||||
|
||||
Never invoke fixes. Report only.
|
||||
|
||||
## NON-GOALS
|
||||
|
||||
- Zero writes. No SPEC.md edits. No code edits.
|
||||
- No sub-agents. Main thread reads.
|
||||
- No scores, no grades. Binary per item: holds or drifts.
|
||||
@@ -0,0 +1,82 @@
|
||||
---
|
||||
name: spec
|
||||
description: |
|
||||
Create, amend, or backprop bugs into SPEC.md at repo root. Sole mutator
|
||||
of the project spec. Triggers when the user asks to write a spec, start
|
||||
a new spec, distill a spec from existing code, add invariants, amend
|
||||
sections (§G, §C, §I, §V, §T, §B), or record a bug via backprop.
|
||||
Common phrasings: "write the spec for...", "new spec", "bug: ...",
|
||||
"amend §V.3", "distill spec from code", "spec this idea". Reads and
|
||||
follows FORMAT.md for the caveman encoding rules and pipe-table shape
|
||||
of §T and §B.
|
||||
---
|
||||
|
||||
# spec — spec mutator
|
||||
|
||||
Read `FORMAT.md` at repo root if not already loaded. Caveman skill applies to all writes here.
|
||||
|
||||
## DISPATCH
|
||||
|
||||
Inspect user request and project state:
|
||||
|
||||
1. No `SPEC.md` at repo root AND args describe idea → **NEW**
|
||||
2. No `SPEC.md` AND `from-code` in args → **DISTILL**
|
||||
3. `SPEC.md` exists AND args start `bug:` → **BACKPROP**
|
||||
4. `SPEC.md` exists AND args start `amend` → **AMEND**
|
||||
5. `SPEC.md` exists, no args → ask user which mode
|
||||
|
||||
## NEW — idea → spec
|
||||
|
||||
Input: user idea.
|
||||
|
||||
Steps:
|
||||
1. Extract goal (1 line, caveman). → §G.
|
||||
2. List constraints user stated or implied. → §C.
|
||||
3. List external surfaces user named. → §I.
|
||||
4. Propose initial invariants. → §V (numbered V1…).
|
||||
5. Break goal into ordered tasks. → §T pipe table, all status `.`, ids T1…
|
||||
6. §B section with header row only (`id|date|cause|fix`).
|
||||
|
||||
Write to `SPEC.md`. Show user full file. Ask: "spec OK? suggest edits or invoke build."
|
||||
|
||||
## DISTILL — code → spec
|
||||
|
||||
Walk repo. Produce §G (infer from README/package.json/main entry), §C (infer from stack), §I (enumerate public APIs/CLIs/configs), §V (derive from tests and assertions), §T (one task per known TODO or missing test), §B (empty).
|
||||
|
||||
Caveman everywhere. Flag uncertain items with `?` in text so user can confirm.
|
||||
|
||||
## BACKPROP — bug → §B + §V
|
||||
|
||||
Input: `bug: <description>`.
|
||||
|
||||
Steps:
|
||||
1. Parse bug description.
|
||||
2. Find root cause (read relevant code).
|
||||
3. Decide: would a new invariant catch recurrence? If yes → draft `V<next>`.
|
||||
4. Append §B row: `B<next>|<date>|<cause>|V<N>`.
|
||||
5. Append new invariant to §V.
|
||||
6. If fix also changes behavior → add/update §T rows.
|
||||
7. Show diff. Apply only on user OK.
|
||||
|
||||
Rule: every bug gets a §B entry. Invariant optional but preferred.
|
||||
|
||||
## AMEND — targeted edit
|
||||
|
||||
Input: `amend §V.3` or `amend §T` etc.
|
||||
|
||||
Read that section. Show current. Ask user what changes. Write. Show diff.
|
||||
|
||||
Never silently rewrite sections user did not name.
|
||||
|
||||
## OUTPUT RULES
|
||||
|
||||
- Caveman format per `FORMAT.md`.
|
||||
- Preserve identifiers, paths, code verbatim.
|
||||
- Numbering monotonic — never reuse §V.N or §B.N.
|
||||
- §T row `cites` column ! list §V/§I deps: `T5|.|impl auth mw|V2,I.api`.
|
||||
|
||||
## NON-GOALS
|
||||
|
||||
- No sub-agents. Main thread writes.
|
||||
- No dashboards, no logs, no state files beyond SPEC.md itself.
|
||||
- No auto-build after spec. User invokes build explicitly.
|
||||
Reference in New Issue
Block a user