cavekit-opencode 1.0.0

package/AGENTS.md

@@ -0,0 +1,27 @@
+# cavekit — spec-driven development
+
+cavekit commands available: `/ck-spec`, `/ck-build`, `/ck-check`.
+
+## FORMAT
+
+SPEC.md lives at repo root. Sections: §G GOAL, §C CONSTRAINTS, §I INTERFACES, §V INVARIANTS, §T TASKS, §B BUGS. Reference `FORMAT.md` for full schema.
+
+## BACKPROP PROTOCOL
+
+When test fails during `/ck-build`:
+1. Read failure.
+2. Classify: code bug / spec wrong / edge case.
+3. If spec wrong → `/ck-spec bug: <cause>` updates §V + §B.
+4. If code bug → fix, re-run. No spec change.
+5. Never silently fix root cause without considering §B entry.
+
+## CAVEMAN ENCODING
+
+Apply to all SPEC.md content: drop articles/filler, use fragments, preserve code verbatim.
+Reference symbols from FORMAT.md (→, ∴, ∀, !, ⊥, ≠, ≤, ≥).
+
+## COMMANDS
+
+- `/ck-spec` — create/amend/backprop SPEC.md. Sole mutator.
+- `/ck-build` — plan-execute against spec. Auto-backprops on failure.
+- `/ck-check` — drift report. Read-only.

package/FORMAT.md

@@ -0,0 +1,119 @@
+# SPEC.md FORMAT
+
+Single file. Project root. Every cavekit command reads it.
+
+## SECTIONS
+
+Fixed order. Fixed headers. Addressable.
+
+```
+# SPEC
+
+## §G GOAL
+one line. what code must do.
+
+## §C CONSTRAINTS
+- bullet. non-negotiable boundary.
+- bullet. tech/lang/lib locked in.
+
+## §I INTERFACES
+external surface. what world sees.
+- cmd: `foo bar` → stdout JSON
+- api: POST /x → 200 {id}
+- file: `config.yaml` schema …
+- env: `FOO_KEY` required
+
+## §V INVARIANTS
+numbered. testable. each ! MUST hold.
+V1: ∀ req → auth check before handler
+V2: token expiry ≤ ⊥ allowed
+V3: DB write ! in transaction
+
+## §T TASKS
+pipe table. ids monotonic (never reused). status: `x` done / `~` wip / `.` todo.
+id|status|task|cites
+T1|.|scaffold repo|-
+T2|.|impl §I.api POST /x|V2
+T3|x|add §V.1 middleware|V1,I.api
+
+## §B BUGS
+pipe table. backprop log. each row = bug + invariant that catches recurrence.
+id|date|cause|fix
+B1|2026-04-20|token `<` not `≤`|V2
+B2|2026-04-21|race on write|V3
+```
+
+**Table cell rules**: literal `|` → escape as `\|`. Backticks OK. Cells trimmed. Empty = `-`.
+
+## ADDRESSING
+
+`§<S>.<n>` = section.item. `§V.2` = invariants section, item 2.
+Commands, commits, PRs all reference by §. Zero ambiguity.
+
+## CAVEMAN ENCODING
+
+Default for every section. Rules:
+
+- Drop articles (a, an, the). Drop filler.
+- Drop aux verbs (is, are, was) where fragment works.
+- Short synonyms (fix > implement).
+- Fragments fine.
+
+**Preserve verbatim**: code, paths, identifiers, URLs, numbers, error strings, SQL, regex.
+
+**Symbols** (save tokens, machine-readable):
+
+```
+→   leads to / becomes / triggers
+∴   therefore / fix
+∀   for all / every
+∃   exists / some
+!   must
+?   may / optional
+⊥   never / impossible / forbidden
+≠   not equal / differs from
+∈   in / member of
+∉   not in
+≤   at most
+≥   at least
+&   and
+|   or
+```
+
+**Bad** (prose):
+
+> The authentication middleware must verify the token expiry on every request before allowing the handler to execute.
+
+**Good** (caveman):
+
+> V1: ∀ req → auth check before handler
+
+**Bad** (prose bug note):
+
+> Fixed a bug where token expiry comparison used strict less-than instead of less-than-or-equal, causing tokens to be rejected exactly at their expiry timestamp.
+
+**Good** (caveman):
+
+> B1: token `<` not `<=` ∴ tokens rejected @ expiry. §V.2 now ! `≤`.
+
+## WHY CAVEMAN FOR SPECS
+
+Spec loaded every invocation. 75% fewer tokens = 75% fewer dollars & faster reads.
+Human skims fast too. Symbols unambiguous.
+
+## ONE FILE RULE
+
+Big project → more sections, not more files. grep ceremony kills agent speed.
+If SPEC.md > 500 lines, compact §B (old bugs drop oldest) before splitting.
+
+## WRITES
+
+| command | writes | section |
+|---|---|---|
+| `/ck-spec new` | creates | all |
+| `/ck-spec amend` | edits | chosen |
+| `/ck-spec bug` | appends | §B + §V |
+| `/ck-build` | flips | §T status cell `.` → `~` → `x` |
+| `/ck-check` | — | read only |
+
+That's the whole format.

package/INSTALL.md

@@ -0,0 +1,50 @@
+# Install cavekit for OpenCode
+
+## One-liner
+
+```sh
+# Install commands globally (available in any project)
+cp -r commands/* ~/.config/opencode/commands/
+
+# Install skills globally
+cp -r skills/* ~/.config/opencode/skills/
+
+# Or per-project (replace ~/.config/opencode with .opencode in your project root)
+cp -r commands/* .opencode/commands/
+cp -r skills/* .opencode/skills/
+
+# Copy AGENTS.md to your project root (optional, embeds backprop+caveman rules)
+cp AGENTS.md /path/to/your/project/
+```
+
+## Using the install script
+
+```sh
+./install.sh                  # install globally
+./install.sh /path/to/project # install per-project
+```
+
+## What you get
+
+| File | Location | Purpose |
+|------|----------|---------|
+| `commands/ck-spec.md` | `~/.config/opencode/commands/` | `/ck-spec` — create/amend/backprop SPEC.md |
+| `commands/ck-build.md` | `~/.config/opencode/commands/` | `/ck-build` — plan-execute against spec |
+| `commands/ck-check.md` | `~/.config/opencode/commands/` | `/ck-check` — drift detection |
+| `skills/ck-spec/SKILL.md` | `~/.config/opencode/skills/` | Auto-trigger on "write a spec" |
+| `skills/ck-build/SKILL.md` | `~/.config/opencode/skills/` | Auto-trigger on "build next task" |
+| `skills/ck-check/SKILL.md` | `~/.config/opencode/skills/` | Auto-trigger on "check spec drift" |
+| `FORMAT.md` | project root | SPEC.md schema reference |
+| `AGENTS.md` | project root | Backprop protocol + caveman encoding rules |
+
+## Dependencies
+
+- [caveman](https://github.com/JuliusBrussee/caveman) plugin for OpenCode (optional, recommended)
+- OpenCode >= 1.15
+
+## Uninstall
+
+```sh
+rm ~/.config/opencode/commands/ck-*.md
+rm -rf ~/.config/opencode/skills/ck-*/
+```

package/README.md

@@ -0,0 +1,96 @@
+# cavekit-opencode
+
+Spec-driven development commands for OpenCode. Port of [cavekit v4](https://github.com/JuliusBrussee/cavekit) — compressed spec, plan-execute loop, drift detection.
+
+**One spec to rule them all. Three commands. Zero sub-agents.**
+
+## Commands
+
+| Command | Job |
+|---------|-----|
+| `/ck-spec` | Create / amend / backprop `SPEC.md`. Sole mutator. |
+| `/ck-build` | Plan-then-execute against spec. Auto-backprops on failure. |
+| `/ck-check` | Read-only drift report. Lists §V / §I / §T violations. |
+
+## How it works
+
+```
+SPEC.md at repo root       ← durable artifact surviving context resets
+├── §G GOAL                one-line intent
+├── §C CONSTRAINTS          non-negotiable boundaries
+├── §I INTERFACES           external surfaces (api, cmd, file, env)
+├── §V INVARIANTS           numbered testable rules (! MUST hold)
+├── §T TASKS                pipe table — x/~/. status
+└── §B BUGS                 backprop log — bug → invariant
+
+/ck-spec new     → creates SPEC.md
+/ck-build        → reads §T, plans, edits, verifies
+                 → failure triggers backprop → §B + §V update
+/ck-check        → reads SPEC.md, diffs against code, reports drift
+```
+
+Every test failure becomes a §B entry. Classes of bug become §V invariants the spec never forgets.
+
+## Install
+
+### Via opencode.json (recommended)
+
+```json
+{
+  "plugin": ["cavekit-opencode"]
+}
+```
+
+The plugin auto-installs commands and skills into your opencode config on load.
+
+**Prerequisite**: `npm install -g cavekit-opencode` or add to your project:
+
+```sh
+npm install cavekit-opencode   # project-level
+npm install -g cavekit-opencode # global
+```
+
+### Manual install
+
+```sh
+git clone https://github.com/gggiiia/cavekit-opencode.git
+cd cavekit-opencode
+cp commands/ck-*.md ~/.config/opencode/commands/
+cp -r skills/ck-* ~/.config/opencode/skills/
+cp FORMAT.md /path/to/your/project/
+```
+
+Or use the install script: `bash install.sh [project-path]`
+
+### Dependencies
+
+- [caveman](https://github.com/JuliusBrussee/caveman) plugin for OpenCode (recommended)
+- OpenCode >= 1.15
+
+## Files
+
+```
+commands/
+├── ck-spec.md           spec mutator
+├── ck-build.md          plan-execute loop
+└── ck-check.md          drift detector
+skills/
+├── ck-spec/SKILL.md     discovery-triggered spec
+├── ck-build/SKILL.md    discovery-triggered build
+└── ck-check/SKILL.md    discovery-triggered check
+FORMAT.md                SPEC.md schema + caveman encoding rules
+AGENTS.md                always-on backprop protocol + encoding rules
+install.sh               installer
+```
+
+## Why cavekit?
+
+The spec is the only artifact that earns its tokens. Everything else that costs tokens must either save more tokens later, or the user's attention, or it gets cut.
+
+- **Caveman encoding** — 75% fewer tokens than prose specs.
+- **Backprop reflex** — test failures auto-commit as §B entries.
+- **One file** — `cat SPEC.md` is the dashboard.
+
+## License
+
+MIT

package/commands/ck-build.md

@@ -0,0 +1,68 @@
+---
+description: Plan-then-execute against SPEC.md. Single-thread native loop.
+---
+
+# /ck-build — implement spec
+
+Single-thread native plan→execute. No sub-agents.
+
+## LOAD
+
+1. Read `SPEC.md`. If missing → tell user run `/ck-spec` first. Stop.
+2. Read `FORMAT.md` once if not loaded.
+3. Parse `$ARGUMENTS`:
+   - `§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 `.` → `~`. No commit — just write SPEC.md.
+2. Edit code per plan.
+3. Run verification command.
+4. **Pass** → flip `~` → `x`. Next task.
+5. **Fail** → invoke backprop. Do NOT retry blindly.
+
+## FAIL → BACKPROP
+
+On test/build failure:
+
+1. Read failure output: !`$TEST_COMMAND` or last run 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) → run `/ck-spec 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 memory that stops recurrence.
+
+## WRITE POLICY
+
+- Only flip §T status. No other SPEC.md edits.
+- Other spec edits → `/ck-spec`.
+- 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 (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 dashboard.
+- No speculative work beyond chosen task scope.

package/commands/ck-check.md

@@ -0,0 +1,82 @@
+---
+description: Drift detector. Diffs SPEC.md against code. Read-only, zero writes.
+---
+
+# /ck-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 `$ARGUMENTS`:
+   - `§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: `/ck-spec bug:` or fix code at cited lines.
+```
+
+## REMEDY HINTS (not actions)
+
+End report with one-line hint per class:
+- VIOLATE / DRIFT → `/ck-spec bug: <V.n>` or fix code.
+- MISSING → `/ck-build §T.n` if task exists; else `/ck-spec amend §T`.
+- STALE → `/ck-spec amend §T` to uncheck.
+- EXTRA → `/ck-spec 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.

package/commands/ck-spec.md

@@ -0,0 +1,72 @@
+---
+description: Create, amend, or backprop bug into SPEC.md. Sole mutator of spec.
+---
+
+# /ck-spec — spec mutator
+
+Read `FORMAT.md` at repo root if not already loaded. Caveman rules apply.
+
+## DISPATCH
+
+Inspect `$ARGUMENTS` 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 in args.
+
+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, status `.`, ids T1…
+6. §B section with header row only (`id|date|cause|fix`).
+
+Write `SPEC.md`. Show user full file. Ask: "spec OK? suggest edits or `/ck-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 `?` so user can confirm.
+
+## BACKPROP — bug → §B + §V
+
+Input: `bug: <description>`.
+
+1. Parse bug description.
+2. Find root cause (read relevant code).
+3. Decide: would 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 §B entry. Invariant optional but preferred.
+
+## AMEND — targeted edit
+
+Input: `amend §V.3` or `amend §T` etc.
+
+Read that section. Show current. Ask user 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.
+- No auto-build after /ck-spec. User invokes `/ck-build` explicitly.

package/install.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TARGET="${1:-global}"
+
+if [ "$TARGET" = "global" ]; then
+  CMD_DIR="$HOME/.config/opencode/commands"
+  SKILL_DIR="$HOME/.config/opencode/skills"
+else
+  CMD_DIR="$TARGET/.opencode/commands"
+  SKILL_DIR="$TARGET/.opencode/skills"
+fi
+
+mkdir -p "$CMD_DIR" "$SKILL_DIR"
+
+cp "$SCRIPT_DIR/commands/ck-spec.md"   "$CMD_DIR/"
+cp "$SCRIPT_DIR/commands/ck-build.md"  "$CMD_DIR/"
+cp "$SCRIPT_DIR/commands/ck-check.md"  "$CMD_DIR/"
+cp -r "$SCRIPT_DIR/skills/ck-spec"     "$SKILL_DIR/"
+cp -r "$SCRIPT_DIR/skills/ck-build"    "$SKILL_DIR/"
+cp -r "$SCRIPT_DIR/skills/ck-check"    "$SKILL_DIR/"
+
+echo "cavekit installed to:"
+echo "  commands → $CMD_DIR/ck-*.md"
+echo "  skills  → $SKILL_DIR/ck-*/"
+echo ""
+echo "Copy FORMAT.md and/or AGENTS.md to your project root as needed."

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "cavekit-opencode",
+  "version": "1.0.0",
+  "description": "Spec-driven development commands for OpenCode — compressed spec, plan-execute loop, drift detection.",
+  "type": "module",
+  "main": "plugin.js",
+  "exports": {
+    ".": "./plugin.js"
+  },
+  "license": "MIT",
+  "author": "gggiiia",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gggiiia/cavekit-opencode.git"
+  },
+  "files": [
+    "plugin.js",
+    "commands/",
+    "skills/",
+    "FORMAT.md",
+    "AGENTS.md",
+    "INSTALL.md",
+    "install.sh"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "cavekit",
+    "caveman",
+    "spec-driven-development",
+    "sdd"
+  ]
+}

package/plugin.js

@@ -0,0 +1,43 @@
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { mkdirSync, readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import os from 'node:os';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+function opencodeConfigDir() {
+  if (process.env.XDG_CONFIG_HOME) {
+    return join(process.env.XDG_CONFIG_HOME, 'opencode');
+  }
+  return join(os.homedir(), '.config', 'opencode');
+}
+
+function copyDir(src, dst) {
+  if (!existsSync(src)) return;
+  mkdirSync(dst, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    const s = join(src, entry);
+    const d = join(dst, entry);
+    if (statSync(s).isDirectory()) {
+      copyDir(s, d);
+    } else {
+      writeFileSync(d, readFileSync(s, 'utf8'));
+    }
+  }
+}
+
+function installFiles() {
+  const configDir = opencodeConfigDir();
+
+  const cmdDir = join(configDir, 'commands');
+  copyDir(join(here, 'commands'), cmdDir);
+
+  const skillDir = join(configDir, 'skills');
+  copyDir(join(here, 'skills'), skillDir);
+}
+
+export default async () => {
+  installFiles();
+
+  return {};
+};

package/skills/ck-build/SKILL.md

@@ -0,0 +1,24 @@
+---
+description: |
+  Build against SPEC.md — plan-then-execute per task.
+  Trigger: "build next task", "implement spec", "build task", "run build".
+---
+
+## ck-build — plan-execute loop
+
+You are running the build skill. Read `SPEC.md`. Read `FORMAT.md` if not loaded.
+
+Dispatch on intent:
+- **Single task** → plan respecting cited §V/§I, execute, verify.
+- **Next task** → lowest-numbered `.` or `~` row.
+- **All tasks** → every `.` row in §T order.
+
+Per task:
+1. Flip status `.` → `~` in SPEC.md.
+2. Edit code per plan.
+3. Run verification command.
+4. Pass → flip `~` → `x`. Fail → backprop.
+
+On failure: classify (code bug / spec wrong / edge case). If spec-related, backprop via /ck-spec then resume. Never silently fix without considering §B.
+
+Write policy: only flip §T status. No other edits to SPEC.md.

package/skills/ck-check/SKILL.md

@@ -0,0 +1,18 @@
+---
+description: |
+  Check SPEC.md drift against code.
+  Trigger: "check spec", "drift report", "spec drift", "audit spec".
+---
+
+## ck-check — drift report
+
+You are running the check skill. Read `SPEC.md`. If missing → "no spec".
+
+Check requested sections (§V only by default):
+- **§V** → each invariant: verify in code. Classify HOLD / VIOLATE / UNVERIFIABLE.
+- **§I** → each interface: locate impl. Classify MATCH / DRIFT / MISSING / EXTRA.
+- **§T** → each task: verify `x` rows, note `~`/`.` status.
+
+Report in caveman format. Group by severity. End with one-line remedy hints.
+
+Zero writes. No code edits. No SPEC.md edits.

package/skills/ck-spec/SKILL.md

@@ -0,0 +1,22 @@
+---
+description: |
+  Write or update SPEC.md — spec-driven development format.
+  Trigger: "write a spec", "create spec", "amend spec", "backprop bug", "distill spec from code".
+---
+
+## ck-spec — spec mutator
+
+You are running the spec skill. Load `FORMAT.md` at repo root. Read `SPEC.md` if exists.
+
+Dispatch on intent:
+- **New spec** → extract goal/constraints/interfaces/invariants/tasks. Write `SPEC.md`.
+- **Distill from code** → walk repo, infer sections flagging `?` for uncertainty.
+- **Backprop bug** → find root cause, append §B row, propose §V invariant.
+- **Amend** → targeted edit of one spec section.
+
+Rules:
+- Caveman format per FORMAT.md.
+- Preserve identifiers, paths, code verbatim.
+- Numbering monotonic — never reuse §V.N or §B.N.
+- Show diff. Apply on user OK.
+- Never auto-build after spec change. User calls /ck-build.