opencodekit 0.16.14 → 0.16.17

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",
 					);
 				}

package/dist/template/.opencode/skill/augment-context-engine/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: augment-context-engine
+description: Semantic codebase search via Augment Context Engine MCP. Use when you need to understand code relationships, find relevant implementations, or explore unfamiliar codebases beyond keyword matching.
+---
+
+# Augment Context Engine (MCP)
+
+Semantic code search powered by Augment's Context Engine. Unlike grep (text matching), this understands code meaning, relationships, and cross-file dependencies.
+
+## Available Tools
+
+- `augment_code_search` - Semantic search across indexed GitHub repositories
+
+**Parameters:**
+
+- `repo_owner` (string, required) - GitHub org or username (e.g. `"augmentcode"`)
+- `repo_name` (string, required) - Repository name (e.g. `"test-repo"`)
+- `query` (string, required) - Natural language description of what you're looking for
+- `branch` (string, optional) - Branch to search (defaults to `"main"`)
+- `max_results` (integer, optional) - Max code snippets to return (defaults to 5)
+
+## Quick Start
+
+```
+# Search a GitHub repo for authentication code
+skill_mcp(skill_name="augment-context-engine", tool_name="augment_code_search", arguments='{"repo_owner": "myorg", "repo_name": "myapp", "query": "authentication middleware that validates JWT tokens"}')
+
+# Search a specific branch with more results
+skill_mcp(skill_name="augment-context-engine", tool_name="augment_code_search", arguments='{"repo_owner": "myorg", "repo_name": "myapp", "query": "error handling patterns", "branch": "develop", "max_results": 10}')
+```
+
+> **Tip:** Get `repo_owner` and `repo_name` from git: `git remote get-url origin`
+
+## Setup
+
+### 1. Install the Augment GitHub App
+
+Install at [github.com/apps/augmentcode](https://github.com/apps/augmentcode/installations/new) and grant access to the repos you want to index.
+
+### 2. Add the remote server
+
+The skill's `mcp.json` uses `mcp-remote` to bridge the remote API via stdio.
+
+For global access, add to `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "auggie": {
+      "type": "remote",
+      "url": "https://api.augmentcode.com/mcp",
+      "enabled": true
+    }
+  }
+}
+```
+
+### 3. Authenticate
+
+Sign in at [app.augmentcode.com](https://app.augmentcode.com) when prompted by `mcp-remote` on first use.
+
+## Query Tips
+
+Good queries (natural language, conceptual):
+
+- `"function that handles user authentication"`
+- `"database connection setup code"`
+- `"tests for the payment processing module"`
+
+Bad queries (use grep instead):
+
+- `"foo_bar"` — exact symbol search
+- `"TODO"` — keyword search
+- `"code that deals with everything"` — too vague
+
+## When to Use
+
+| Scenario                 | Use This              | Instead Of                 |
+| ------------------------ | --------------------- | -------------------------- |
+| Find code by meaning     | `augment_code_search` | `grep` (text only)         |
+| Understand relationships | `augment_code_search` | `@explore` agent (heavier) |
+| Unfamiliar codebase      | `augment_code_search` | Manual file exploration    |
+| Cross-repo dependencies  | `augment_code_search` | LSP references (narrower)  |
+
+## When NOT to Use
+
+- **Exact string matching** — Use `grep` instead (faster, free)
+- **Known file paths** — Use `read` directly
+- **Symbol definitions** — Use LSP `goToDefinition` (precise)
+- **Local-only work** — This searches GitHub-indexed repos, not local files
+
+## Tool Priority Integration
+
+```
+grep (text) → semantic search (meaning) → read (full file) → LSP (symbols) → edit
+```
+
+Use grep first for exact matches. Escalate to semantic search when grep results are noisy or you need conceptual understanding.
+
+## Cost
+
+- ~40-70 credits per query
+- Not free — use judiciously
+- Prefer grep for simple lookups
+
+## Resources
+
+- Docs: https://docs.augmentcode.com/context-services/mcp/overview
+- OpenCode Quickstart: https://docs.augmentcode.com/context-services/mcp/quickstart-open-code
+- GitHub App: https://github.com/apps/augmentcode/installations/new
+- Product: https://www.augmentcode.com/product/context-engine-mcp

package/dist/template/.opencode/skill/augment-context-engine/mcp.json

@@ -0,0 +1,6 @@
+{
+	"augment-context-engine": {
+		"command": "npx",
+		"args": ["-y", "mcp-remote", "https://api.augmentcode.com/mcp"]
+	}
+}

package/dist/template/.opencode/skill/core-data-expert/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: core-data-expert
+description: 'Expert Core Data guidance (iOS/macOS): stack setup, fetch requests & NSFetchedResultsController, saving/merge conflicts, threading & Swift Concurrency, batch operations & persistent history, migrations, performance, and NSPersistentCloudKitContainer/CloudKit sync.'
+---
+# Core Data Expert
+
+Fast, production-oriented guidance for building **correct**, **performant** Core Data stacks and fixing common crashes.
+
+## Agent behavior contract (follow these rules)
+
+1. Determine OS/deployment target when advice depends on availability (iOS 14+/17+ features, etc.).
+2. Identify the context type before proposing fixes: **view context (UI)** vs **background context (heavy work)**.
+3. Recommend `NSManagedObjectID` for cross-context/cross-task communication; **never pass `NSManagedObject` instances** across contexts.
+4. Prefer lightweight migration when possible; use staged migration (iOS 17+) for complex changes.
+5. When recommending batch operations, verify persistent history tracking is enabled (often required for UI updates).
+6. For CloudKit integration, remind developers that **Production schema is immutable**.
+7. Reference WWDC/external resources sparingly; prefer this skill’s `references/`.
+
+## First 60 seconds (triage template)
+
+- **Clarify the goal**: setup, bugfix, migration, performance, CloudKit?
+- **Collect minimal facts**:
+  - platform + deployment target
+  - store type (SQLite / in-memory) and whether CloudKit is enabled
+  - context involved (view vs background) and whether Swift Concurrency is in use
+  - exact error message + stack trace/logs
+- **Branch immediately**:
+  - threading/crash → focus on context confinement + `NSManagedObjectID` handoff
+  - migration error → identify model versions + migration strategy
+  - batch ops not updating UI → persistent history tracking + merge pipeline
+
+## Routing map (pick the right reference fast)
+
+- **Stack setup / merge policies / contexts** → `references/stack-setup.md`
+- **Saving patterns** → `references/saving.md`
+- **Fetch requests / list updates / aggregates** → `references/fetch-requests.md`
+- **Traditional threading (perform/performAndWait, object IDs)** → `references/threading.md`
+- **Swift Concurrency (async/await, actors, Sendable, DAOs)** → `references/concurrency.md`
+- **Batch insert/delete/update** → `references/batch-operations.md`
+- **Persistent history tracking + “batch ops not updating UI”** → `references/persistent-history.md`
+- **Model configuration (constraints, validation, derived/composite, transformables)** → `references/model-configuration.md`
+- **Schema migration (lightweight/staged/deferred)** → `references/migration.md`
+- **CloudKit integration & debugging** → `references/cloudkit-integration.md`
+- **Performance profiling & memory** → `references/performance.md`
+- **Testing patterns** → `references/testing.md`
+- **Terminology** → `references/glossary.md`
+
+## Common errors → next best move
+
+- **“Failed to find a unique match for an NSEntityDescription”** → `references/testing.md` (shared `NSManagedObjectModel`)
+- **`NSPersistentStoreIncompatibleVersionHashError`** → `references/migration.md` (versioning + migration)
+- **Cross-context/threading exceptions** (e.g. delete/update from wrong context) → `references/threading.md` and/or `references/concurrency.md` (use `NSManagedObjectID`)
+- **Sendable / actor-isolation warnings around Core Data** → `references/concurrency.md` (don’t “paper over” with `@unchecked Sendable`)
+- **`NSMergeConflict` / constraint violations** → `references/model-configuration.md` + `references/stack-setup.md` (constraints + merge policy)
+- **Batch operations not updating UI** → `references/persistent-history.md` + `references/batch-operations.md`
+- **CloudKit schema/sync issues** → `references/cloudkit-integration.md`
+- **Memory grows during fetch** → `references/performance.md` + `references/fetch-requests.md`
+
+## Verification checklist (when changing Core Data code)
+
+- Confirm the context matches the work (UI vs background).
+- Ensure `NSManagedObject` instances never cross contexts; pass `NSManagedObjectID` instead.
+- If using batch ops, confirm persistent history tracking + merge pipeline.
+- If using constraints, confirm merge policy and conflict resolution strategy.
+- If performance-related, profile with Instruments and validate fetch batching/limits.
+
+## Reference files
+
+- `references/_index.md` (navigation)
+- `references/stack-setup.md`
+- `references/saving.md`
+- `references/fetch-requests.md`
+- `references/threading.md`
+- `references/concurrency.md`
+- `references/batch-operations.md`
+- `references/persistent-history.md`
+- `references/model-configuration.md`
+- `references/migration.md`
+- `references/cloudkit-integration.md`
+- `references/performance.md`
+- `references/testing.md`
+- `references/glossary.md`