golden-hoop-spell-opencode 0.1.0

package/shared/references/sprint-agent.md

@@ -0,0 +1,261 @@
+# Sprint Agent Reference
+
+## Table of Contents
+1. [Workflow](#workflow)
+2. [Feature Breakdown](#feature-breakdown)
+3. [File Schemas](#file-schemas)
+4. [Examples](#examples)
+
+## Workflow
+
+### When Invoked
+
+1. **New Project**: After initialization
+2. **New Sprint**: User requests new iteration
+3. **Requirement Update**: User wants to modify planned features
+
+### Archive Completed Sprints First
+
+Before creating a new sprint, archive completed sprints:
+
+```bash
+command python3 ${CLAUDE_PLUGIN_ROOT}/shared/scripts/archive_sprint.py --list --project-dir "<PROJECT_DIR>"      # List completed sprints
+command python3 ${CLAUDE_PLUGIN_ROOT}/shared/scripts/archive_sprint.py --dry-run --project-dir "<PROJECT_DIR>"   # Preview archive
+command python3 ${CLAUDE_PLUGIN_ROOT}/shared/scripts/archive_sprint.py --project-dir "<PROJECT_DIR>"             # Archive
+```
+
+Archived sprints move to `.ghs/archived/`.
+
+### Planning Process
+
+#### Step 1: Analyze Requirements
+
+Break down requirements into categories:
+
+- **Core Features** - Essential for MVP/sprint goal
+- **Supporting Features** - Enhance core functionality
+- **Technical Enablers** - Infrastructure, refactoring
+
+Context sources:
+- User's high-level requirements
+- Existing `.ghs/features.json`
+- Previous sprint learnings from `.ghs/progress.md`
+
+#### Step 2: Create Atomic Features
+
+Each feature must be:
+
+- **Atomic**: Completable in one session (2-4 hours)
+- **Independent**: Minimal dependencies
+- **Testable**: Clear acceptance criteria
+- **Valuable**: Delivers user value
+
+#### Step 3: Categorize and Prioritize
+
+Categories: `core`, `ui`, `api`, `auth`, `data`, `infra`
+
+Priorities:
+- `high`: Sprint blockers, core functionality
+- `medium`: Important but not blocking
+- `low`: Nice to have, can be deferred
+
+#### Step 4: Define Acceptance Criteria
+
+Format: `Given [context], when [action], then [outcome]`
+
+Example: `Given a user is logged in, when they click "Add to Cart", then the item should appear in their cart with correct quantity.`
+
+#### Step 5: Order by Dependencies
+
+Rules:
+1. Infrastructure first, then features
+2. Core before supporting features
+3. UI after backend support
+4. Features with dependencies must wait
+
+## Feature Breakdown
+
+### Feature Definition
+
+```json
+{
+  "id": "s1-feat-001",
+  "category": "core | ui | api | auth | data | infra",
+  "priority": "high | medium | low",
+  "title": "Short feature title",
+  "description": "Detailed description",
+  "acceptance_criteria": ["Criterion 1", "Criterion 2"],
+  "technical_notes": "Implementation hints",
+  "status": "pending",
+  "blocked_reason": "Optional. Explanation of why the feature is blocked. Only present when status is 'blocked'.",
+  "dependencies": [],
+  "estimated_complexity": "small | medium | large",
+  "files_affected": ["path/to/file.ts"]
+}
+```
+
+Note: Feature IDs follow the format `s{N}-feat-{NNN}` where `N` matches the parent sprint number and `NNN` is a zero-padded sequential number.
+
+### Complexity Estimation
+
+- **small**: < 2 hours, simple changes
+- **medium**: 2-4 hours, moderate complexity
+- **large**: 4+ hours, break into smaller features
+
+### Dependencies
+
+Mark dependencies with feature IDs:
+
+```json
+"dependencies": ["s1-feat-001", "s1-feat-002"]
+```
+
+## File Schemas
+
+### ID Format Rules
+
+Sprint IDs and feature IDs must follow strict naming conventions for consistency and tooling compatibility:
+
+- **Sprint ID**: matches `^s\d{1,4}$` — e.g., `s1`, `s2`, `s10`, `s9999`
+- **Feature ID**: matches `^s\d{1,4}-feat-\d{3}$` — e.g., `s1-feat-001`, `s2-feat-010`, `s10-feat-003`
+
+The sprint number in the feature ID must match its parent sprint. Feature numbers are zero-padded to 3 digits and sequential within each sprint.
+
+### features.json Structure
+
+```json
+{
+  "project": {
+    "name": "string (required)",
+    "description": "string (required)",
+    "tech_stack": ["string"],
+    "created_at": "YYYY-MM-DD (required)"
+  },
+  "sprints": [
+    {
+      "id": "string (required, unique, format: s{number})",
+      "name": "string (required)",
+      "goal": "string",
+      "status": "planning | in_progress | completed | on_hold",
+      "created_at": "YYYY-MM-DD",
+      "features": [ /* feature objects */ ]
+    }
+  ],
+  "metadata": {
+    "version": "1.0.0",
+    "last_updated": "YYYY-MM-DD"
+  }
+}
+```
+
+### Sprint Status Values
+
+| Status | Description |
+|--------|-------------|
+| `planning` | Being defined |
+| `in_progress` | Features being implemented |
+| `completed` | All features done |
+| `on_hold` | Temporarily paused |
+
+### Feature Status Values
+
+| Status | Description |
+|--------|-------------|
+| `pending` | Not started |
+| `in_progress` | Currently being worked on |
+| `completed` | Fully implemented and tested |
+| `blocked` | Cannot proceed |
+
+### Category Definitions
+
+| Category | Description |
+|----------|-------------|
+| `core` | Business logic, main features |
+| `ui` | User interface, components |
+| `api` | API routes, data fetching |
+| `auth` | Authentication, authorization |
+| `data` | Database, models, migrations |
+| `infra` | Configuration, deployment, tooling |
+
+## Examples
+
+See [examples.md](examples.md) for complete examples.
+
+## Output Requirements
+
+### File Management
+
+Only modify `.ghs/features.json` and `.ghs/progress.md`. Do NOT create additional files like planning summaries, architecture docs, or data model documents. All planning information goes into these two files.
+
+Before writing, resolve the project directory with `command python3 ${CLAUDE_PLUGIN_ROOT}/shared/scripts/resolve_project_dir.py` and use the returned absolute path for all file reads/writes. This prevents files from being written to the wrong location (e.g., inside `.ghs/`) if the working directory shifts during the session.
+
+### Update features.json
+
+Add new sprint with structured features following schema above.
+
+### Update progress.md
+
+Add planning session entry at top:
+
+```markdown
+## Sprint Planning - YYYY-MM-DD
+**Agent**: Sprint Agent
+**Sprint**: [Sprint ID and Name]
+
+### Requirements Received
+- [User's requirement summary]
+
+### Features Planned
+- Total: N features
+- High priority: N
+- Medium priority: N
+- Low priority: N
+
+### Sprint Goal
+[Clear goal statement]
+
+### Implementation Order
+1. [feature-id] - [title]
+2. [feature-id] - [title]
+
+### Notes
+[Any context or decisions]
+```
+
+### Summary Output Format
+
+Display this summary in the terminal and ask the user to confirm before finalizing the sprint:
+
+```markdown
+## Sprint Planning Complete
+
+### Sprint: [Name]
+**Goal**: [Sprint goal]
+
+### Feature Summary
+- Total features: N
+- High priority: N (list IDs)
+- Medium priority: N
+- Low priority: N
+
+### Recommended Implementation Order
+1. [id] [title] - [complexity]
+2. [id] [title] - [complexity]
+
+### Dependencies
+- [id] depends on [id]
+- No blockers for: [ids]
+
+### Ready for Development
+Run the Coding Agent with the first pending feature: [first-feature-id]
+```
+
+After displaying the summary, ask the user to confirm. No git commit needed — `.ghs/` tracking files are local metadata (gitignored by `ghs:init`).
+
+## Critical Rules
+
+1. **Never Remove Features** - Only add or change status
+2. **Unique IDs** - Each feature must have a unique ID
+3. **Respect Tech Stack** - Features must be achievable
+4. **Balance Sprint** - Mix of complexity levels
+5. **Document Decisions** - Explain prioritization rationale

package/src/index.ts

@@ -0,0 +1,9 @@
+// Plugin entry — default-exported re-export of the `ghsPlugin` Plugin function
+// defined in `src/plugin.ts`.
+//
+// `package.json` points `main` at this file (`src/index.ts`); OpenCode's
+// plugin loader resolves the module, takes the default export, and invokes
+// it as the plugin's `server` function. The actual Plugin implementation
+// lives in `plugin.ts` to keep this entry focused on module resolution.
+
+export { ghsPlugin as default } from "./plugin.ts";

package/src/lib/assets.ts

@@ -0,0 +1,31 @@
+// Read plugin-bundled text assets (templates, default config, fixtures) from
+// `<pluginRoot>/shared/<relativePath>`.
+//
+// Assets are shipped with the npm package (see `package.json` `files:
+// ["src","shared"]`). They are read at runtime — not inlined — so a plugin
+// upgrade picks up new asset content without a rebuild.
+//
+// `loadAsset` is the single entry point for reading these files; callers
+// should not reach for `Bun.file`/`fs.readFile` against the shared tree
+// directly, so that the root-resolution strategy stays in one place.
+
+import { resolve } from "node:path";
+import { pluginRoot } from "./paths";
+
+/**
+ * Read a text asset relative to `<pluginRoot>/shared/`.
+ *
+ * @param name - asset path relative to `shared/`, e.g. `"assets/features.json"`
+ *               or `"ghs.default.json"`.
+ * @returns the file's UTF-8 contents.
+ * @throws {Error} if the file does not exist or cannot be read.
+ */
+export async function loadAsset(name: string): Promise<string> {
+  const filePath = resolve(pluginRoot(), "shared", name);
+  const file = Bun.file(filePath);
+  const exists = await file.exists();
+  if (!exists) {
+    throw new Error(`Asset not found: ${filePath}`);
+  }
+  return file.text();
+}

package/src/lib/codegraph.ts

@@ -0,0 +1,66 @@
+// Runtime probe for the codegraph MCP integration.
+//
+// codegraph (R1) is an *optional* knowledge-graph backend. The host project
+// opts in by running the codegraph MCP server, which materialises a
+// `.codegraph/` directory at the project root. The plan dispatcher's
+// `ghs-plan-start` tool calls `detectCodegraph()` to decide which Context
+// Subagent prompt to use:
+//
+//   - `.codegraph/` present → `context-codegraph` prompt (graph-aware).
+//   - `.codegraph/` absent  → `context-grep` prompt (grep fallback).
+//
+// This function is intentionally a *pure* probe: it inspects the filesystem
+// and returns a boolean. It does NOT start the MCP server — that is declared
+// statically in `opencode.json` (`mcp.codegraph`) and loaded by the OpenCode
+// core once at startup (plan §3.4 D3, §3.5). Running-time availability is a
+// separate concern (the dispatcher additionally asks the main AI to issue a
+// `codegraph_status` call); here we only answer "was codegraph ever
+// initialised for this project?".
+//
+// Style follows s1-feat-008's `resolve-project-dir.ts` / `paths.ts`: no
+// `process.exit`, no `console.log`, defensive on bad input.
+
+import { statSync } from "node:fs";
+import { resolve } from "node:path";
+
+/**
+ * Probe whether the codegraph backend is available for a project.
+ *
+ * Returns `true` iff `<projectDir>/.codegraph/` exists and is a directory.
+ *
+ * Defensive contract (AC #3): any failure mode returns `false` rather than
+ * throwing:
+ *   - empty / whitespace-only `projectDir`
+ *   - non-string input (coerced via the string guard)
+ *   - path that does not exist
+ *   - path that exists but is a file (not a directory)
+ *   - any underlying `statSync` error (permissions, broken symlink, EIO, …)
+ *
+ * The probe specifically checks for a *directory* — a stray `.codegraph`
+ * file does not count as "codegraph initialised".
+ *
+ * @param projectDir - absolute or relative path to the host project root.
+ * @returns `true` when the codegraph directory is present, `false` otherwise.
+ */
+export function detectCodegraph(projectDir: string): boolean {
+  // Guard against empty / non-string input. A missing or blank projectDir
+  // means we have nothing meaningful to probe — report "not available" and
+  // let the dispatcher fall back to the grep path rather than crash.
+  if (typeof projectDir !== "string" || projectDir.trim().length === 0) {
+    return false;
+  }
+
+  // `resolve` normalises relative paths against process.cwd() and collapses
+  // `.`/`..` segments. We resolve defensively inside try/catch because
+  // `resolve` itself is pure but the subsequent `statSync` touches the FS.
+  try {
+    const codegraphPath = resolve(projectDir, ".codegraph");
+    const stats = statSync(codegraphPath);
+    return stats.isDirectory();
+  } catch {
+    // Any stat failure — ENOENT (missing), ENOTDIR (a parent is a file),
+    // EACCES (permissions), or a dangling symlink — means codegraph is not
+    // usable. Suppress and report `false` per the defensive contract.
+    return false;
+  }
+}

package/src/lib/config.ts

@@ -0,0 +1,278 @@
+// Load `.ghs/ghs.json`, merge with defaults, and render agent markdown
+// templates with the resolved model IDs.
+//
+// This module is the load-bearing implementation for R3 (Round 6): user-
+// configurable model IDs. The user's `.ghs/ghs.json` overrides
+// `shared/ghs.default.json` on a per-field basis. The merged config drives
+// `syncAgents()`, which renders the three subagent markdown templates
+// (`ghs-context-haiku`, `ghs-plan-designer`, `ghs-plan-reviewer`) into
+// `<projectDir>/.opencode/agents/` so opencode picks them up on next start.
+//
+// Spike 004 verified that `String.replaceAll()` over the template body +
+// fresh opencode process is sufficient — no template engine needed.
+
+import { z } from "zod";
+import { resolve } from "node:path";
+import { mkdir } from "node:fs/promises";
+
+// -----------------------------------------------------------------------------
+// Schema
+// -----------------------------------------------------------------------------
+
+/**
+ * Zod schema for `.ghs/ghs.json`. `strict()` rejects unknown top-level fields
+ * (e.g. a typo like `"model"` instead of `"models"`) so misconfiguration is
+ * surfaced loudly rather than silently ignored.
+ */
+export const GhsConfigSchema = z.strictObject({
+  models: z.strictObject({
+    context: z.string(),
+    designer: z.string(),
+    reviewer: z.string(),
+  }),
+});
+
+export type GhsConfig = z.infer<typeof GhsConfigSchema>;
+
+// -----------------------------------------------------------------------------
+// Internal helpers
+// -----------------------------------------------------------------------------
+
+/**
+ * The three placeholders recognised inside `*.md.template` files. Each is
+ * substituted with the corresponding model ID from the resolved config.
+ */
+const PLACEHOLDERS = {
+  context: "__GHS_MODEL_CONTEXT__",
+  designer: "__GHS_MODEL_DESIGNER__",
+  reviewer: "__GHS_MODEL_REVIEWER__",
+} as const;
+
+/**
+ * Map from agent name → the placeholder it cares about. All three templates
+ * share the same substitution pass (every placeholder is replaced on every
+ * template), but this map documents which placeholder each template is
+ * *expected* to contain. Templates without placeholders pass through
+ * unchanged (acceptance criterion #7).
+ */
+const AGENT_NAMES = ["ghs-context-haiku", "ghs-plan-designer", "ghs-plan-reviewer"] as const;
+type AgentName = (typeof AGENT_NAMES)[number];
+
+/** Resolve the default config path under the plugin root. */
+function defaultConfigPath(pluginRootDir: string): string {
+  return resolve(pluginRootDir, "shared", "ghs.default.json");
+}
+
+/** Resolve the user config path under the project directory. */
+function userConfigPath(projectDir: string): string {
+  return resolve(projectDir, ".ghs", "ghs.json");
+}
+
+/** Resolve a template path under `<pluginRoot>/shared/agents/<name>.md.template`. */
+function templatePath(pluginRootDir: string, name: string): string {
+  return resolve(pluginRootDir, "shared", "agents", `${name}.md.template`);
+}
+
+/** Resolve an output agent markdown path under `<projectDir>/.opencode/agents/`. */
+function outputPath(projectDir: string, name: string): string {
+  return resolve(projectDir, ".opencode", "agents", `${name}.md`);
+}
+
+/**
+ * Check whether a file exists. Thin wrapper over `Bun.file().exists()` so
+ * callers can `await fileExists(p)` without juggling a BunFile object.
+ */
+export async function fileExists(path: string): Promise<boolean> {
+  return Bun.file(path).exists();
+}
+
+/** Read + JSON-parse a file, throwing a descriptive error on any failure. */
+async function readJsonFile(path: string, label: string): Promise<unknown> {
+  const file = Bun.file(path);
+  const exists = await file.exists();
+  if (!exists) {
+    throw new Error(`Failed to read ${label}: file not found at ${path}`);
+  }
+  let text: string;
+  try {
+    text = await file.text();
+  } catch (err) {
+    throw new Error(`Failed to read ${label} at ${path}: ${(err as Error).message}`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    throw new Error(
+      `Failed to parse ${label} at ${path}: invalid JSON — ${(err as Error).message}`,
+    );
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Public API
+// -----------------------------------------------------------------------------
+
+/**
+ * Load and validate the GHS config, merging the user's `.ghs/ghs.json` with
+ * the plugin's `shared/ghs.default.json` on a per-field basis.
+ *
+ * Field-level fallback rules:
+ *   - If `.ghs/ghs.json` does not exist → all three model fields come from
+ *     defaults; `defaults_used` is `true`.
+ *   - If `.ghs/ghs.json` exists and is missing one or more model fields →
+ *     those fields fall back to defaults; `defaults_used` is `true`.
+ *   - If `.ghs/ghs.json` exists with all three model fields set → no
+ *     fallback; `defaults_used` is `false`.
+ *
+ * `defaults_used` is therefore `true` whenever ANY field fell back, and
+ * `false` only when the user's file fully specified all three models.
+ *
+ * Unknown top-level fields in either file are rejected by Zod `.strict()`.
+ *
+ * @param projectDir   - absolute path to the host project (where `.ghs/` lives).
+ * @param pluginRootDir - absolute path to this plugin's package root.
+ * @returns `{ config, defaults_used }` where `config` matches `GhsConfig`.
+ * @throws {Error} if either file is missing (defaults must exist), unparseable,
+ *         or schema-invalid.
+ */
+export async function loadGhsConfig(
+  projectDir: string,
+  pluginRootDir: string,
+): Promise<{ config: GhsConfig; defaults_used: boolean }> {
+  // Defaults are always required — they ship with the plugin.
+  const defaultRaw = await readJsonFile(defaultConfigPath(pluginRootDir), "ghs.default.json");
+  const defaultParsed = GhsConfigSchema.parse(defaultRaw);
+
+  // User file is optional; if present, overlay per-field.
+  const userFile = userConfigPath(projectDir);
+  const userExists = await fileExists(userFile);
+
+  if (!userExists) {
+    return { config: defaultParsed, defaults_used: true };
+  }
+
+  const userRaw = await readJsonFile(userFile, "ghs.json");
+
+  // Validate user file shape with the same strict schema — this is what
+  // surfaces "extra top-level field" as a hard error (AC #5) and what
+  // catches malformed structures before the per-field merge below.
+  const userParsed = GhsConfigSchema.parse(userRaw);
+
+  // Per-field merge. A field falls back to its default when the user's
+  // value is absent *or* the empty string. Empty-string fallback matters
+  // because the feature's AC #3 explicitly tests `models.context: ""`.
+  //
+  // `defaults_used` is true if ANY of the three fields fell back — i.e. if
+  // the user's config did not fully specify all three models. This matches
+  // the feature's task notes:
+  //   - all 3 from default     → defaults_used = true
+  //   - some fields missing    → defaults_used = true (partial fallback)
+  //   - all 3 set by user      → defaults_used = false
+  let contextFellBack = false;
+  let designerFellBack = false;
+  let reviewerFellBack = false;
+
+  const context =
+    userParsed.models.context && userParsed.models.context.length > 0
+      ? userParsed.models.context
+      : ((contextFellBack = true), defaultParsed.models.context);
+  const designer =
+    userParsed.models.designer && userParsed.models.designer.length > 0
+      ? userParsed.models.designer
+      : ((designerFellBack = true), defaultParsed.models.designer);
+  const reviewer =
+    userParsed.models.reviewer && userParsed.models.reviewer.length > 0
+      ? userParsed.models.reviewer
+      : ((reviewerFellBack = true), defaultParsed.models.reviewer);
+
+  const merged: GhsConfig = { models: { context, designer, reviewer } };
+  const defaults_used = contextFellBack || designerFellBack || reviewerFellBack;
+
+  return { config: merged, defaults_used };
+}
+
+/**
+ * Render a single agent template by substituting the three model-ID
+ * placeholders with values from `config`.
+ *
+ * Templates without placeholders pass through unchanged (AC #7) —
+ * `String.replaceAll()` is a no-op when the target string is absent.
+ *
+ * @param name         - agent template name (without `.md.template`).
+ * @param config       - resolved config providing the substitution values.
+ * @param pluginRootDir - plugin package root (where `shared/agents/` lives).
+ * @returns the rendered template body.
+ * @throws {Error} if the template file is missing or unreadable.
+ */
+export async function renderAgentTemplate(
+  name: string,
+  config: GhsConfig,
+  pluginRootDir: string,
+): Promise<string> {
+  const path = templatePath(pluginRootDir, name);
+  const file = Bun.file(path);
+  const exists = await file.exists();
+  if (!exists) {
+    throw new Error(`Agent template not found: ${path}`);
+  }
+  const body = await file.text();
+  return body
+    .replaceAll(PLACEHOLDERS.context, config.models.context)
+    .replaceAll(PLACEHOLDERS.designer, config.models.designer)
+    .replaceAll(PLACEHOLDERS.reviewer, config.models.reviewer);
+}
+
+/**
+ * Result of `syncAgents()`. Returned to tool callers so they can report
+ * which files were written, which models were applied, and whether any
+ * defaults leaked through.
+ */
+export interface SyncAgentsResult {
+  /** Absolute paths of the 3 rendered agent markdown files written. */
+  written: string[];
+  /** The model IDs that were substituted into the templates. */
+  models: GhsConfig["models"];
+  /** `true` if any of the 3 model fields fell back to the default config. */
+  defaults_used: boolean;
+}
+
+/**
+ * Load config + render all three agent templates + write them to
+ * `<projectDir>/.opencode/agents/ghs-*.md`.
+ *
+ * Creates `<projectDir>/.opencode/agents/` if missing. Does NOT touch the
+ * opencode runtime — the caller (e.g. the `ghs-config` tool) is responsible
+ * for telling the user to restart opencode (per spike 004's finding that
+ * agent markdown requires a fresh process).
+ *
+ * @param projectDir    - host project directory (target of `.opencode/agents/`).
+ * @param pluginRootDir - plugin package root (source of templates + defaults).
+ * @returns `SyncAgentsResult`.
+ */
+export async function syncAgents(
+  projectDir: string,
+  pluginRootDir: string,
+): Promise<SyncAgentsResult> {
+  const { config, defaults_used } = await loadGhsConfig(projectDir, pluginRootDir);
+
+  const written: string[] = [];
+  // Ensure `<projectDir>/.opencode/agents/` exists before we write into it.
+  // Bun.write creates parent dirs automatically in recent versions, but we
+  // mkdir explicitly so behaviour is stable across versions and obvious to
+  // readers (and so AC #8 "creates .opencode/agents/ if missing" holds even
+  // on a clean project dir).
+  await mkdir(resolve(projectDir, ".opencode", "agents"), { recursive: true });
+
+  for (const name of AGENT_NAMES) {
+    const rendered = await renderAgentTemplate(name, config, pluginRootDir);
+    const out = outputPath(projectDir, name);
+    await Bun.write(out, rendered);
+    written.push(out);
+  }
+
+  return {
+    written,
+    models: config.models,
+    defaults_used,
+  };
+}