opencodekit 0.16.15 → 0.16.17

package/dist/template/.opencode/command/verify.md

@@ -2,20 +2,17 @@
 description: Verify implementation completeness, correctness, and coherence
 argument-hint: "<bead-id> [--quick] [--fix]"
 agent: review
-subtask: true
 ---
 
 # Verify: $ARGUMENTS
 
-Three-dimensional verification before claiming work complete. Inspired by OpenSpec's verify workflow.
+Check implementation against PRD before shipping.
 
 ## Load Skills
 
 ```typescript
 skill({ name: "beads" });
 skill({ name: "verification-before-completion" });
-skill({ name: "systematic-debugging" });
-skill({ name: "memory-system" });
 ```
 
 ## Parse Arguments
@@ -23,285 +20,74 @@ skill({ name: "memory-system" });
 | Argument    | Default  | Description                      |
 | ----------- | -------- | -------------------------------- |
 | `<bead-id>` | required | The bead to verify               |
-| `--quick`   | false    | Skip coherence check, gates only |
-| `--fix`     | false    | Auto-fix issues where possible   |
+| `--quick`   | false    | Gates only, skip coherence check |
+| `--fix`     | false    | Auto-fix lint/format issues      |
 
----
-
-## Phase 1: Check Memory for Context
-
-Search for relevant verification patterns and past issues:
-
-```typescript
-memory_search({ query: "$ARGUMENTS verification issues patterns", limit: 3 });
-```
-
----
-
-## Phase 2: Gather Artifacts
+## Phase 1: Gather Context
 
 ```bash
 br show $ARGUMENTS
 ls .beads/artifacts/$ARGUMENTS/
 ```
 
-Read all artifacts:
+Read the PRD and any other artifacts (plan.md, research.md, design.md).
 
-```bash
-cat .beads/artifacts/$ARGUMENTS/prd.md 2>/dev/null
-cat .beads/artifacts/$ARGUMENTS/plan.md 2>/dev/null
-cat .beads/artifacts/$ARGUMENTS/research.md 2>/dev/null
-cat .beads/artifacts/$ARGUMENTS/design.md 2>/dev/null
-```
+## Phase 2: Completeness
 
----
+Extract all requirements/tasks from the PRD and verify each is implemented:
 
-## Phase 3: Completeness Check
+- For each requirement: find evidence in the codebase (file:line reference)
+- Mark as: complete, partial, or missing
+- Report completeness score (X/Y requirements met)
 
-**Are all required artifacts present?**
+## Phase 3: Correctness
 
-| Artifact      | Required | Status |
-| ------------- | -------- | ------ |
-| `prd.md`      | Yes      | [ ]    |
-| `plan.md`     | Yes      | [ ]    |
-| `research.md` | No       | [ ]    |
-| `design.md`   | No       | [ ]    |
+Detect project type and run the appropriate verification gates:
 
-**Are all tasks in the PRD addressed?**
+| Project Type    | Detect Via                    | Build            | Test            | Lint                          | Typecheck                             |
+| --------------- | ----------------------------- | ---------------- | --------------- | ----------------------------- | ------------------------------------- |
+| Node/TypeScript | `package.json`                | `npm run build`  | `npm test`      | `npm run lint`                | `npm run typecheck` or `tsc --noEmit` |
+| Rust            | `Cargo.toml`                  | `cargo build`    | `cargo test`    | `cargo clippy -- -D warnings` | (included in build)                   |
+| Python          | `pyproject.toml` / `setup.py` | —                | `pytest`        | `ruff check .`                | `mypy .`                              |
+| Go              | `go.mod`                      | `go build ./...` | `go test ./...` | `golangci-lint run`           | (included in build)                   |
 
-Extract tasks/criteria from prd.md and verify each is implemented:
+Check `package.json` scripts, `Makefile`, or `justfile` for project-specific commands first — prefer those over generic defaults.
 
-```markdown
-## Completeness Report
+If `--fix` flag provided, run the project's auto-fix command (e.g., `npm run lint:fix`, `ruff check --fix`, `cargo clippy --fix`).
 
-| Requirement       | Status     | Evidence                |
-| ----------------- | ---------- | ----------------------- |
-| [Req 1 from spec] | ✓ Complete | `src/foo.ts:42`         |
-| [Req 2 from spec] | ✓ Complete | `src/bar.ts:15`         |
-| [Req 3 from spec] | ⚠ Partial  | Missing edge case tests |
-| [Req 4 from spec] | ✗ Missing  | Not implemented         |
-```
-
-**Completeness Score:** X/Y requirements met
-
----
-
-## Phase 4: Correctness Check
-
-**Do the automated gates pass?**
-
-```bash
-# Detect project type and run gates
-ls package.json Cargo.toml pyproject.toml go.mod 2>/dev/null
-```
-
-**Node/TypeScript:**
-
-```bash
-npm run build 2>&1 | tail -10
-npm test 2>&1 | tail -20
-npm run lint 2>&1 | tail -10
-npm run typecheck 2>&1 | tail -10
-```
+Report gate results (pass/warn/fail for each).
 
-**Rust:**
-
-```bash
-cargo build 2>&1 | tail -10
-cargo test 2>&1 | tail -20
-cargo clippy -- -D warnings 2>&1 | tail -10
-```
-
-**Python:**
-
-```bash
-pytest 2>&1 | tail -20
-ruff check . 2>&1 | tail -10
-mypy . 2>&1 | tail -10
-```
-
-**Go:**
-
-```bash
-go build ./... 2>&1 | tail -10
-go test ./... 2>&1 | tail -20
-golangci-lint run 2>&1 | tail -10
-```
-
-```markdown
-## Correctness Report
-
-| Gate      | Status | Details                   |
-| --------- | ------ | ------------------------- |
-| Build     | ✓ Pass |                           |
-| Tests     | ✓ Pass | 42 tests, 0 failures      |
-| Lint      | ⚠ Warn | 2 warnings (non-blocking) |
-| Typecheck | ✓ Pass |                           |
-```
-
-**Correctness Score:** X/Y gates passed
-
----
-
-## Phase 5: Coherence Check (skip with --quick)
-
-**Do artifacts agree with each other?**
+## Phase 4: Coherence (skip with --quick)
 
 Cross-reference artifacts for contradictions:
 
-| Check                        | Status | Issue                               |
-| ---------------------------- | ------ | ----------------------------------- |
-| prd.md ↔ plan.md             | ✓      | Plan addresses all PRD requirements |
-| plan.md ↔ implementation     | ✓      | Code follows plan structure         |
-| research.md ↔ implementation | ⚠      | Didn't use recommended approach     |
-| design.md ↔ implementation   | ✓      | Follows design patterns             |
-
-**Common coherence issues:**
-
-- Plan says X, implementation does Y
-- Research recommended approach A, used approach B (without justification)
-- Spec says must-have, implementation treats as optional
-- Design specifies pattern, implementation uses different pattern
+- PRD vs implementation (does code address all PRD requirements?)
+- Plan vs implementation (did code follow the plan?)
+- Research recommendations vs actual approach (if different, is it justified?)
 
-```markdown
-## Coherence Report
-
-Contradictions found: 1
-
-1. **Research vs Implementation**
-   - Research recommended: Use `zod` for validation
-   - Implementation uses: Manual validation
-   - Impact: Medium - works but less maintainable
-   - Action: Document decision or refactor
-```
+Flag contradictions with specific file references.
 
-**Coherence Score:** X/Y checks passed
-
----
-
-## Phase 6: Verification Summary
-
-```
-Verification: $ARGUMENTS
-━━━━━━━━━━━━━━━━━━━━━━━
-
-Dimension        Score    Status
-───────────────────────────────
-Completeness     4/5      ⚠ PARTIAL
-Correctness      4/4      ✓ PASS
-Coherence        3/4      ⚠ PARTIAL
-
-Overall: ⚠ NEEDS ATTENTION
-
-Issues Found:
-─────────────
-BLOCKING (must fix):
-  • [Req 4] Not implemented
-
-NON-BLOCKING (should fix):
-  • [Req 3] Missing edge case tests
-  • Research recommendation not followed
-
-Recommendations:
-────────────────
-1. Implement [Req 4] before closing
-2. Add tests for edge case X
-3. Document why zod was not used, or refactor to use it
-```
-
----
-
-## Phase 7: Auto-Fix (if --fix)
-
-For fixable issues, attempt automatic resolution:
-
-```typescript
-// If lint issues are fixable
-if (hasLintWarnings && canAutoFix) {
-  bash({ command: "npm run lint -- --fix" });
-}
-
-// If missing tests detected
-if (missingTests) {
-  console.log("Consider adding tests for: [list uncovered code]");
-}
-```
-
----
-
-## Phase 8: Update Bead Notes
-
-Record verification results in bead:
+## Phase 5: Report
 
 ```bash
 br comments add $ARGUMENTS "Verification: [PASS|PARTIAL|FAIL] - [summary]"
 ```
 
----
-
-## Phase 9: Record Findings
-
-If significant issues or patterns discovered:
-
-```typescript
-observation({
-  type: "discovery",
-  title: "Verification findings for $ARGUMENTS",
-  narrative: "[Summary of issues found, patterns discovered, or lessons learned]",
-  concepts: "verification, testing, quality",
-  bead_id: "$ARGUMENTS",
-  confidence: "high",
-});
-```
-
----
-
-## Output
-
-```
-Verification Complete: $ARGUMENTS
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Result: ✓ READY TO SHIP | ⚠ NEEDS WORK | ✗ BLOCKED
-
-Completeness: [score] - [status]
-Correctness:  [score] - [status]
-Coherence:    [score] - [status]
-
-[If READY TO SHIP]
-Next: /ship $ARGUMENTS
-
-[If NEEDS WORK]
-Fix these before shipping:
-• [issue 1]
-• [issue 2]
-
-[If BLOCKED]
-Cannot proceed until:
-• [blocker 1]
-```
-
----
-
-## Examples
-
-```bash
-# Full verification
-/verify br-feature-auth
-
-# Quick check (gates only)
-/verify br-feature-auth --quick
+Output:
 
-# Verify and auto-fix where possible
-/verify br-feature-auth --fix
-```
+1. **Result**: READY TO SHIP / NEEDS WORK / BLOCKED
+2. **Completeness**: score and status
+3. **Correctness**: gate results
+4. **Coherence**: contradictions found (if not --quick)
+5. **Blocking issues** to fix before shipping
+6. **Next step**: `/ship $ARGUMENTS` if ready, or list fixes needed
 
----
+Record significant findings with `observation()`.
 
 ## Related Commands
 
 | Need              | Command            |
 | ----------------- | ------------------ |
-| Ship after verify | `/ship $ARGUMENTS` |
+| Ship after verify | `/ship <id>`       |
 | Review code       | `/review-codebase` |
 | Check status      | `/status`          |

package/dist/template/.opencode/plugin/README.md

@@ -82,12 +82,16 @@ Session 3: read_session("previous") → Tests (90k) → close
 
 ### swarm-enforcer.ts
 
-**Swarm protocol guardrails (Beads-as-board)** - nudges agents to follow the Beads-first workflow.
+**Swarm protocol guardrails (Beads-as-board)** - enforces the `/create` → `/start` → `/ship` workflow.
 
 - Treats `.beads/` as the single source of truth for the swarm task board
-- If user expresses implementation intent and no task is `in_progress`, injects a nudge to use `br ready/show/update`
-- If there are `in_progress` tasks but `.beads/artifacts/<id>/spec.md` is missing, nudges to create it before implementation
-- On `file.edited`, warns if code is being changed without a claimed task or with missing `spec.md`
+- **Workflow stage tracking**: Computes each bead's stage based on artifacts and status:
+  - `⏳needs:/create` — no prd.md exists yet
+  - `⏳needs:/start` — has prd.md but not claimed (in_progress)
+  - `✅ready:/ship` — in_progress with prd.md, ready for implementation
+  - `⚠needs:/create→/start` — in_progress but missing prd.md
+- **System prompt injection** via `experimental.chat.system.transform`: injects workflow stage per bead, enforcement rules ("Do NOT implement until `/start`"), and protocol reminders into every LLM call
+- On `file.edited`, warns if code is being changed without a claimed task or when workflow is incomplete (no prd.md)
 - On `session.idle`, reminds to `br close` + `br sync` when work is done
 
 ### notification.ts

package/dist/template/.opencode/plugin/swarm-enforcer.ts

@@ -3,14 +3,13 @@
  *
  * Beads is the single source of truth for the swarm board.
  * This plugin provides non-intrusive enforcement:
+ * - System prompt injection with active beads state (via experimental.chat.system.transform)
+ * - Workflow stage tracking: /create → /start → /ship (enforced order)
  * - Toast warning when code is edited without a claimed task
- * - Toast warning when in-progress tasks are missing spec.md
+ * - Toast warning when in-progress tasks are missing prd.md
+ * - Toast warning when implementation starts before /start
  * - Session-end reminder to close/sync in-progress tasks
  *
- * NOTE: chat.message nudging was removed — AGENTS.md and the beads skill
- * already instruct agents on the beads protocol. Injecting ASCII blocks
- * on every user message mentioning work intent caused excessive noise.
- *
  * This plugin is intentionally non-destructive: it never runs `br update/close/sync`.
  */
 
@@ -22,8 +21,19 @@ type BeadsIssue = {
 	id: string;
 	title?: string;
 	status?: string;
+	priority?: number;
+	issue_type?: string;
 };
 
+/**
+ * Workflow stage for a bead:
+ * - "uncreated": No prd.md exists — needs `/create`
+ * - "created": Has prd.md but not in_progress — needs `/start`
+ * - "started": In progress with prd.md — ready for `/ship`
+ * - "started-no-prd": In progress but missing prd.md — needs `/create` first
+ */
+type WorkflowStage = "uncreated" | "created" | "started" | "started-no-prd";
+
 const BEADS_DIR = ".beads";
 const ISSUES_FILE = "issues.jsonl";
 
@@ -88,6 +98,12 @@ async function readIssuesJsonl(repoDir: string): Promise<BeadsIssue[]> {
 					id: parsed.id,
 					title: typeof parsed.title === "string" ? parsed.title : undefined,
 					status: typeof parsed.status === "string" ? parsed.status : undefined,
+					priority:
+						typeof parsed.priority === "number" ? parsed.priority : undefined,
+					issue_type:
+						typeof parsed.issue_type === "string"
+							? parsed.issue_type
+							: undefined,
 				});
 			}
 		} catch {
@@ -98,27 +114,46 @@ async function readIssuesJsonl(repoDir: string): Promise<BeadsIssue[]> {
 	return issues;
 }
 
-async function specExists(repoDir: string, issueId: string): Promise<boolean> {
-	const specPath = path.join(
+async function artifactExists(
+	repoDir: string,
+	issueId: string,
+	filename: string,
+): Promise<boolean> {
+	const filePath = path.join(
 		repoDir,
 		BEADS_DIR,
 		"artifacts",
 		issueId,
-		"spec.md",
+		filename,
 	);
 	try {
-		await fsPromises.access(specPath);
+		await fsPromises.access(filePath);
 		return true;
 	} catch {
 		return false;
 	}
 }
 
+function getWorkflowStage(issue: BeadsIssue, hasPrd: boolean): WorkflowStage {
+	const isInProgress = issue.status === "in_progress";
+
+	if (isInProgress && hasPrd) return "started";
+	if (isInProgress && !hasPrd) return "started-no-prd";
+	if (hasPrd) return "created";
+	return "uncreated";
+}
+
+type IssueWithStage = BeadsIssue & {
+	stage: WorkflowStage;
+	hasPrd: boolean;
+	hasPlan: boolean;
+};
+
 export const SwarmEnforcer: Plugin = async ({ client, directory }) => {
 	const repoDir = directory || process.cwd();
 	let lastStateAt = 0;
-	let cachedInProgress: BeadsIssue[] = [];
-	let cachedMissingSpec: BeadsIssue[] = [];
+	let cachedInProgress: IssueWithStage[] = [];
+	let cachedAllActive: IssueWithStage[] = [];
 
 	const refreshState = async () => {
 		const now = Date.now();
@@ -126,17 +161,20 @@ export const SwarmEnforcer: Plugin = async ({ client, directory }) => {
 		lastStateAt = now;
 
 		const issues = await readIssuesJsonl(repoDir);
-		const inProgress = issues.filter((i) => i.status === "in_progress");
+		const active = issues.filter(
+			(i) => i.status === "in_progress" || i.status === "open",
+		);
 
-		const missingSpec: BeadsIssue[] = [];
-		for (const issue of inProgress.slice(0, 10)) {
-			if (!(await specExists(repoDir, issue.id))) {
-				missingSpec.push(issue);
-			}
+		const enriched: IssueWithStage[] = [];
+		for (const issue of active.slice(0, 15)) {
+			const hasPrd = await artifactExists(repoDir, issue.id, "prd.md");
+			const hasPlan = await artifactExists(repoDir, issue.id, "plan.md");
+			const stage = getWorkflowStage(issue, hasPrd);
+			enriched.push({ ...issue, stage, hasPrd, hasPlan });
 		}
 
-		cachedInProgress = inProgress;
-		cachedMissingSpec = missingSpec;
+		cachedAllActive = enriched;
+		cachedInProgress = enriched.filter((i) => i.status === "in_progress");
 	};
 
 	const showToast = async (
@@ -159,7 +197,115 @@ export const SwarmEnforcer: Plugin = async ({ client, directory }) => {
 	};
 
 	return {
-		// Warn if code gets edited while no task is claimed / spec missing
+		// Inject active beads state + workflow stage into system prompt
+		"experimental.chat.system.transform": async (_input, output) => {
+			await refreshState();
+
+			if (cachedAllActive.length === 0) return;
+
+			const priorityLabel = (p?: number) => {
+				if (p === 0) return "P0-critical";
+				if (p === 1) return "P1-high";
+				if (p === 2) return "P2-normal";
+				if (p === 3) return "P3-low";
+				return "P?";
+			};
+
+			const stageLabel = (stage: WorkflowStage) => {
+				switch (stage) {
+					case "uncreated":
+						return "⏳needs:/create";
+					case "created":
+						return "⏳needs:/start";
+					case "started":
+						return "✅ready:/ship";
+					case "started-no-prd":
+						return "⚠needs:/create→/start";
+				}
+			};
+
+			const lines: string[] = [];
+			lines.push("<beads-state>");
+			lines.push("## Active Beads");
+			lines.push("");
+
+			// Show in-progress first, then open
+			const sorted = [...cachedAllActive].sort((a, b) => {
+				if (a.status === "in_progress" && b.status !== "in_progress") return -1;
+				if (a.status !== "in_progress" && b.status === "in_progress") return 1;
+				return 0;
+			});
+
+			for (const issue of sorted.slice(0, 7)) {
+				const typeTag = issue.issue_type || "task";
+				const prioTag = priorityLabel(issue.priority);
+				const stage = stageLabel(issue.stage);
+				const statusTag =
+					issue.status === "in_progress" ? "🔧in_progress" : "📋open";
+				lines.push(
+					`- **${issue.id}** ${issue.title || "(untitled)"} [${typeTag} ${prioTag}] ${statusTag} ${stage}`,
+				);
+			}
+
+			// Workflow enforcement warnings
+			const needsCreate = cachedAllActive.filter(
+				(i) => i.stage === "uncreated" || i.stage === "started-no-prd",
+			);
+			const needsStart = cachedAllActive.filter((i) => i.stage === "created");
+			const readyToShip = cachedInProgress.filter((i) => i.stage === "started");
+
+			lines.push("");
+			lines.push("**Workflow enforcement (required order):**");
+			lines.push(
+				"1. `/create <description>` — creates bead + prd.md (specification)",
+			);
+			lines.push(
+				"2. `/start <id>` — claims task, creates branch, sets in_progress",
+			);
+			lines.push("3. `/ship <id>` — implement, verify, review, close");
+			lines.push("");
+			lines.push(
+				"⛔ **Do NOT implement code until `/start` has been run.** Edit code only for beads marked ✅ready:/ship.",
+			);
+
+			if (needsCreate.length > 0) {
+				lines.push("");
+				lines.push(
+					`⚠ ${needsCreate.length} bead(s) need \`/create\`: ${needsCreate.map((i) => i.id).join(", ")}`,
+				);
+			}
+
+			if (needsStart.length > 0) {
+				lines.push("");
+				lines.push(
+					`⚠ ${needsStart.length} bead(s) have prd.md but need \`/start\`: ${needsStart.map((i) => i.id).join(", ")}`,
+				);
+			}
+
+			if (readyToShip.length > 0) {
+				lines.push("");
+				lines.push(
+					`✅ ${readyToShip.length} bead(s) ready for \`/ship\`: ${readyToShip.map((i) => i.id).join(", ")}`,
+				);
+			}
+
+			lines.push("");
+			lines.push("**Beads protocol reminders:**");
+			lines.push(
+				"- Claim before editing: `br update <id> --status in_progress`",
+			);
+			lines.push(
+				'- When done: `br close <id> --reason="..."` → `br sync --flush-only` → git commit',
+			);
+			lines.push(
+				'- Discovered work (>2min): `br create --title "..." --type bug|task`',
+			);
+			lines.push("</beads-state>");
+
+			output.system.push(lines.join("\n"));
+		},
+
+		// Warn if code gets edited while no task is claimed / workflow not followed
 		event: async ({ event }) => {
 			if (event.type === "file.edited") {
 				const filePath = event.properties?.file;
@@ -174,22 +320,31 @@ export const SwarmEnforcer: Plugin = async ({ client, directory }) => {
 
 				await refreshState();
 
+				// No tasks claimed at all
 				if (cachedInProgress.length === 0) {
 					await showToast(
 						"Beads: No task claimed",
-						"Run br ready/show/update to claim a task before edits.",
+						"Run /start <id> to claim a task before editing code.",
 						"warning",
 					);
 					return;
 				}
 
-				if (cachedMissingSpec.length > 0) {
+				// Tasks in progress but none are ready for /ship
+				const readyForShip = cachedInProgress.filter(
+					(i) => i.stage === "started",
+				);
+				if (readyForShip.length === 0) {
+					const notReady = cachedInProgress.filter(
+						(i) => i.stage !== "started",
+					);
+					const ids = notReady
+						.slice(0, 3)
+						.map((i) => i.id)
+						.join(", ");
 					await showToast(
-						"Beads: Missing spec.md",
-						`Create .beads/artifacts/<id>/spec.md for: ${cachedMissingSpec
-							.slice(0, 3)
-							.map((i) => i.id)
-							.join(", ")}`,
+						"Beads: Workflow incomplete",
+						`Task(s) ${ids} need prd.md via /create before implementing.`,
 						"warning",
 					);
 				}