cavekit-opencode 1.0.0 → 1.1.0

package/README.md

@@ -12,6 +12,21 @@ Spec-driven development commands for OpenCode. Port of [cavekit v4](https://gith
 | `/ck-build` | Plan-then-execute against spec. Auto-backprops on failure. |
 | `/ck-check` | Read-only drift report. Lists §V / §I / §T violations. |
 
+## Agent
+
+`@cavekit` subagent orchestrates the full cycle:
+
+```
+> @cavekit build a CLI that converts markdown to PDF
+→ creates SPEC.md
+→ shows you the spec
+→ asks for approval
+→ plans first task
+→ shows you the plan
+→ implements, verifies, reports
+→ repeats until all tasks done
+```
+
 ## How it works
 
 ```
@@ -57,6 +72,7 @@ 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 agents/cavekit.md ~/.config/opencode/agents/
 cp FORMAT.md /path/to/your/project/
 ```
 
@@ -67,6 +83,24 @@ Or use the install script: `bash install.sh [project-path]`
 - [caveman](https://github.com/JuliusBrussee/caveman) plugin for OpenCode (recommended)
 - OpenCode >= 1.15
 
+## Usage
+
+### `@cavekit` subagent (recommended)
+
+```
+@cavekit build an auth service with JWT tokens
+```
+
+Agent creates SPEC.md, shows you the spec, asks for approval, plans the first task, shows the plan, implements, verifies, and repeats until done.
+
+### Slash commands
+
+```
+/ck-spec "auth service with JWT"
+/ck-build --next
+/ck-check --all
+```
+
 ## Files
 
 ```
@@ -78,6 +112,8 @@ skills/
 ├── ck-spec/SKILL.md     discovery-triggered spec
 ├── ck-build/SKILL.md    discovery-triggered build
 └── ck-check/SKILL.md    discovery-triggered check
+agents/
+└── cavekit.md           @cavekit subagent — full cycle orchestrator
 FORMAT.md                SPEC.md schema + caveman encoding rules
 AGENTS.md                always-on backprop protocol + encoding rules
 install.sh               installer

package/agents/cavekit.md

@@ -0,0 +1,54 @@
+---
+description: >
+  Spec-driven development orchestrator. Takes ideas → creates SPEC.md →
+  shows plan → executes build cycle with verification. One-stop for
+  full feature development with cavekit.
+mode: subagent
+---
+
+# cavekit — spec-driven development agent
+
+You orchestrate the full cavekit cycle. User provides idea or feature request. You drive SPEC.md creation, planning, and build execution.
+
+## Workflow
+
+### 1. DISCOVER
+- Read `SPEC.md` if exists → understand current project state.
+- Read `FORMAT.md` at repo root for spec schema.
+- If neither exists, ask: "no spec yet — want me to create one from code or from your idea?"
+
+### 2. SPEC
+- Convert user idea → SPEC.md (§G, §C, §I, §V, §T, §B).
+- Caveman format per FORMAT.md. Preserve identifiers, paths, code verbatim.
+- Show user the full spec. **Wait for explicit approval**: "spec OK? suggestions? or start build?"
+
+### 3. PLAN
+- Read §T. Pick first `.` task (or user-specified task).
+- Plan: which §V invariants apply, which §I interfaces touched, which files change, what tests needed.
+- Show plan. **Wait for explicit OK** before executing.
+
+### 4. BUILD
+- Execute per /ck-build rules:
+  1. Flip task `.` → `~` in SPEC.md.
+  2. Implement code + tests.
+  3. Run verification.
+  4. Pass → flip `~` → `x`. Commit: `T<n>: <goal> | § <cites>`.
+  5. Fail → classify: code bug (fix) or spec wrong (/ck-spec bug: ... then resume).
+
+### 5. REPORT
+- After each task: show updated §T table.
+- Show summary: "T1 done. 5 tasks total, 1 done, 4 pending. Next: T2."
+- Ask: "proceed to next task? or review?"
+
+## Rules
+
+- Never skip the plan verification step. User must approve before execution.
+- Never edit SPEC.md except §T status flips during build.
+- Other spec edits via /ck-spec workflow (amend, bug).
+- Caveman output to save tokens. Code/security: write normal.
+
+## Refusals
+
+- No SPEC.md and user gives vague idea → ask clarifying questions.
+- Spec > 500 lines → suggest §B compaction.
+- User asks for something outside spec → /ck-spec amend §T first.

package/install.sh

@@ -21,8 +21,16 @@ 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/"
 
+AGENT_DIR="${TARGET}/../agents"
+if [ "$TARGET" = "global" ]; then
+  AGENT_DIR="$HOME/.config/opencode/agents"
+else
+  AGENT_DIR="$TARGET/.opencode/agents"
+fi
+mkdir -p "$AGENT_DIR"
+cp "$SCRIPT_DIR/agents/cavekit.md" "$AGENT_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."
+echo "  agent   → $AGENT_DIR/cavekit.md"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cavekit-opencode",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Spec-driven development commands for OpenCode — compressed spec, plan-execute loop, drift detection.",
   "type": "module",
   "main": "plugin.js",
@@ -17,6 +17,7 @@
     "plugin.js",
     "commands/",
     "skills/",
+    "agents/",
     "FORMAT.md",
     "AGENTS.md",
     "INSTALL.md",

package/plugin.js

@@ -34,6 +34,9 @@ function installFiles() {
 
   const skillDir = join(configDir, 'skills');
   copyDir(join(here, 'skills'), skillDir);
+
+  const agentDir = join(configDir, 'agents');
+  copyDir(join(here, 'agents'), agentDir);
 }
 
 export default async () => {