golden-hoop-spell-opencode 0.1.0

package/src/lib/scripts/validate-structure.ts

@@ -0,0 +1,290 @@
+// Port of golden-hoop-spell/plugin/shared/scripts/validate_structure.py.
+//
+// Behavior source-of-truth:
+//   /Users/tom/github/golden-hoop-spell/plugin/shared/scripts/validate_structure.py
+//
+// Faithful port notes:
+//   - ID-format patterns are anchored regexes ported verbatim:
+//       SPRINT_ID_PATTERN  = /^s\d{1,4}$/
+//       FEATURE_ID_PATTERN = /^s\d{1,4}-feat-\d{3}$/
+//     JS regexes are anchored the same way Python's re.compile with ^...$ is.
+//   - Validation produces two parallel arrays: `errors` and `warnings`.
+//     The order of items matches Python's append/extend order.
+//   - This module exports pure functions — no stdout writes. The CLI layer
+//     (s1-feat-009) renders the warnings/errors to text using formatReport.
+
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+const SPRINT_ID_PATTERN = /^s\d{1,4}$/;
+const FEATURE_ID_PATTERN = /^s\d{1,4}-feat-\d{3}$/;
+
+// Shared shape for the parsed JSON.
+type JsonObject = Record<string, unknown>;
+type Feature = JsonObject;
+type Sprint = JsonObject;
+type FeaturesData = JsonObject;
+
+/** Validation result: a tuple of error strings and warning strings. */
+export interface ValidationResult {
+  errors: string[];
+  warnings: string[];
+}
+
+const VALID_FEATURE_STATUSES = ["pending", "in_progress", "completed", "blocked"];
+const VALID_FEATURE_PRIORITIES = ["high", "medium", "low"];
+const VALID_FEATURE_CATEGORIES = ["core", "ui", "api", "auth", "data", "infra"];
+const VALID_SPRINT_STATUSES = ["planning", "in_progress", "completed", "on_hold"];
+
+/** Validate the `project` section of features.json. */
+export function validateProjectSection(data: FeaturesData): string[] {
+  const errors: string[] = [];
+  const project = (data.project ?? {}) as JsonObject;
+  const requiredFields = ["name", "description", "created_at"];
+  for (const field of requiredFields) {
+    if (!(field in project)) {
+      errors.push(`Missing project.${field}`);
+    }
+  }
+  return errors;
+}
+
+/** Validate that a sprint ID matches `^s\d{1,4}$`. */
+export function validateSprintIdFormat(
+  sprintId: string,
+  sprintIdx: number,
+): string[] {
+  const errors: string[] = [];
+  if (!SPRINT_ID_PATTERN.test(sprintId)) {
+    errors.push(
+      `Sprint ${sprintIdx}: invalid sprint ID format '${sprintId}' ` +
+        `(must match ^s\\d{1,4}$, e.g. s1, s12, s1234)`,
+    );
+  }
+  return errors;
+}
+
+/** Validate that a feature ID matches `^s\d{1,4}-feat-\d{3}$`. */
+export function validateFeatureIdFormat(
+  featureId: string,
+  featureIdx: number,
+): string[] {
+  const errors: string[] = [];
+  if (!FEATURE_ID_PATTERN.test(featureId)) {
+    errors.push(
+      `Feature ${featureIdx}: invalid feature ID format '${featureId}' ` +
+        `(must match ^s\\d{1,4}-feat-\\d{3}$, e.g. s1-feat-001)`,
+    );
+  }
+  return errors;
+}
+
+/** Validate that the sprint number prefix in a feature ID matches its parent sprint. */
+export function validateFeaturePrefixConsistency(
+  featureId: string,
+  sprintId: string,
+  featureIdx: number,
+): string[] {
+  const errors: string[] = [];
+  if (SPRINT_ID_PATTERN.test(sprintId) && FEATURE_ID_PATTERN.test(featureId)) {
+    const sprintNum = sprintId.slice(1); // strip leading 's'
+    const featurePrefix = featureId.split("-feat-")[0].slice(1);
+    if (sprintNum !== featurePrefix) {
+      errors.push(
+        `Feature ${featureIdx}: feature ID '${featureId}' prefix ` +
+          `does not match parent sprint '${sprintId}' ` +
+          `(sprint number ${sprintNum} vs feature prefix ${featurePrefix})`,
+      );
+    }
+  }
+  return errors;
+}
+
+/** Validate a single feature. Returns `{ errors, warnings }`. */
+export function validateFeature(
+  feature: Feature,
+  featureIdx: number,
+  sprintId = "",
+): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  const requiredFields = ["id", "title", "description", "status"];
+  for (const field of requiredFields) {
+    if (!(field in feature)) {
+      errors.push(`Feature ${featureIdx}: missing '${field}'`);
+    }
+  }
+
+  const featureId = (feature.id as string | undefined) ?? "";
+  if (featureId) {
+    errors.push(...validateFeatureIdFormat(featureId, featureIdx));
+  }
+
+  if (featureId && sprintId) {
+    errors.push(
+      ...validateFeaturePrefixConsistency(featureId, sprintId, featureIdx),
+    );
+  }
+
+  const status = (feature.status as string | undefined) ?? "";
+  if (status && !VALID_FEATURE_STATUSES.includes(status)) {
+    errors.push(`Feature ${featureIdx}: invalid status '${status}'`);
+  }
+
+  if (status === "blocked" && !("blocked_reason" in feature)) {
+    warnings.push(
+      `Feature ${featureIdx}: status is 'blocked' but no 'blocked_reason' field ` +
+        "(recommended but not required)",
+    );
+  }
+
+  const priority = (feature.priority as string | undefined) ?? "";
+  if (priority && !VALID_FEATURE_PRIORITIES.includes(priority)) {
+    errors.push(`Feature ${featureIdx}: invalid priority '${priority}'`);
+  }
+
+  const category = (feature.category as string | undefined) ?? "";
+  if (category && !VALID_FEATURE_CATEGORIES.includes(category)) {
+    errors.push(`Feature ${featureIdx}: invalid category '${category}'`);
+  }
+
+  return { errors, warnings };
+}
+
+/** Validate a single sprint. Returns `{ errors, warnings }`. */
+export function validateSprint(
+  sprint: Sprint,
+  sprintIdx: number,
+): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  const requiredFields = ["id", "name", "status"];
+  for (const field of requiredFields) {
+    if (!(field in sprint)) {
+      errors.push(`Sprint ${sprintIdx}: missing '${field}'`);
+    }
+  }
+
+  const sprintId = (sprint.id as string | undefined) ?? "";
+  if (sprintId) {
+    errors.push(...validateSprintIdFormat(sprintId, sprintIdx));
+  }
+
+  const status = (sprint.status as string | undefined) ?? "";
+  if (status && !VALID_SPRINT_STATUSES.includes(status)) {
+    errors.push(`Sprint ${sprintIdx}: invalid status '${status}'`);
+  }
+
+  const features = sprint.features;
+  if (!Array.isArray(features)) {
+    errors.push(`Sprint ${sprintIdx}: 'features' must be an array`);
+  } else {
+    features.forEach((feature, idx) => {
+      const r = validateFeature(feature as Feature, idx, sprintId);
+      errors.push(...r.errors);
+      warnings.push(...r.warnings);
+    });
+  }
+
+  return { errors, warnings };
+}
+
+/**
+ * Validate an entire features.json structure on disk.
+ *
+ * Mirrors Python `validate_features_json(Path)`: returns `{ errors, warnings }`.
+ * The first error is `"File not found: <path>"` when the file is missing, or
+ * `"Invalid JSON: <message>"` when parsing fails.
+ */
+export async function validateFeaturesJson(
+  filepath: string,
+): Promise<ValidationResult> {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (!existsSync(filepath)) {
+    return { errors: [`File not found: ${filepath}`], warnings: [] };
+  }
+
+  let data: FeaturesData;
+  try {
+    const text = await readFile(filepath, "utf8");
+    data = JSON.parse(text) as FeaturesData;
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return { errors: [`Invalid JSON: ${msg}`], warnings: [] };
+  }
+
+  errors.push(...validateProjectSection(data));
+
+  const sprints = data.sprints;
+  if (!Array.isArray(sprints)) {
+    errors.push("'sprints' must be an array");
+  } else {
+    sprints.forEach((sprint, idx) => {
+      const r = validateSprint(sprint as Sprint, idx);
+      errors.push(...r.errors);
+      warnings.push(...r.warnings);
+    });
+  }
+
+  return { errors, warnings };
+}
+
+/**
+ * Validate features.json for the project at `projectDir`.
+ *
+ * Convenience wrapper that resolves `<projectDir>/.ghs/features.json` and
+ * invokes `validateFeaturesJson`.
+ */
+export async function validateProjectStructure(
+  projectDir: string,
+): Promise<ValidationResult> {
+  const featuresPath = join(resolve(projectDir), ".ghs", "features.json");
+  return validateFeaturesJson(featuresPath);
+}
+
+/**
+ * Render a validation report as the Python `main()` would print to stdout.
+ *
+ * This is exported so the CLI wrapper in s1-feat-009 can produce byte-identical
+ * output without re-implementing the format. The text matches:
+ *
+ *     === Validating features.json ===\n\n
+ *     [<warnings block if any>]
+ *     [<errors block if any> | <success block>]
+ */
+export function formatValidationReport(result: ValidationResult): string {
+  const lines: string[] = [];
+  lines.push("=== Validating features.json ===");
+  lines.push("");
+
+  if (result.warnings.length > 0) {
+    lines.push("⚠️  Warnings:");
+    lines.push("");
+    for (const warning of result.warnings) {
+      lines.push(`  • ${warning}`);
+    }
+    lines.push("");
+  }
+
+  if (result.errors.length > 0) {
+    lines.push("❌ Validation failed:");
+    lines.push("");
+    for (const error of result.errors) {
+      lines.push(`  • ${error}`);
+    }
+  } else {
+    lines.push("✅ Validation passed!");
+    lines.push("   All required fields present");
+    lines.push("   All status values valid");
+    lines.push("   All ID formats valid");
+    lines.push("   Feature ID prefixes consistent");
+    lines.push("   Structure is correct");
+  }
+
+  return lines.join("\n");
+}

package/src/lib/state.ts

@@ -0,0 +1,305 @@
+// Read/write the plan dispatcher's per-plan `status.json` state file.
+//
+// Each `ghs-plan-*` tool invocation is one step in a multi-round plan
+// generation loop (plan §3.5 / §3.7). Between steps the dispatcher persists
+// its progress to `<projectDir>/.ghs/plans/<plan_id>-status.json` so that:
+//   - the next `ghs-plan-review` call can pick up where the previous one left
+//     off (round counter, current phase, codegraph path taken);
+//   - `ghs-plan-finalize` can flip `status` to `approved` atomically;
+//   - post-hoc auditing (`grep '"accepted_with_fail": true'`) still works
+//     exactly as in the source plugin.
+//
+// Schema field-by-field parity with the source skill
+// (`plugin/skills/ghs-plan/SKILL.md` → "State Tracking"), plus the R1 addition
+// required by this sprint: `codegraph_available: boolean` records whether the
+// Context Subagent for THIS plan took the codegraph path or the grep fallback
+// (drives status reporting + downstream tooling decisions).
+//
+// Style follows s2-feat-001's writer modules (pure, Zod-validated) + s1-feat-008's
+// I/O style (Bun.file / Bun.write, no process.exit, no console.log, descriptive
+// thrown Errors on failure). The read/write helpers are *not* pure — they touch
+// the filesystem — but each is a thin, single-responsibility wrapper that the
+// plan tools compose.
+
+import { z } from "zod";
+import { resolve } from "node:path";
+import { mkdir } from "node:fs/promises";
+
+// -----------------------------------------------------------------------------
+// Schema
+// -----------------------------------------------------------------------------
+
+/**
+ * Lifecycle states a plan moves through, matching the source skill's enum
+ * verbatim. We keep this as a literal union (rather than `z.enum(...)`) so
+ * callers get precise autocompletion and the type flows into `PlanStatus.status`
+ * without a cast.
+ */
+export const PLAN_STATUS_VALUES = [
+  "designing",
+  "reviewing",
+  "revising",
+  "pending_approval",
+  "approved",
+  "rejected",
+  "aborted",
+] as const;
+export type PlanStatusValue = (typeof PLAN_STATUS_VALUES)[number];
+
+/**
+ * Zod schema for `<plan_id>-status.json`.
+ *
+ * `strict()` rejects unknown fields so a typo in the dispatcher's write path
+ * surfaces immediately instead of silently corrupting state. Mirrors the
+ * `GhsConfigSchema` discipline in `src/lib/config.ts`.
+ *
+ * Fields (source: `plugin/skills/ghs-plan/SKILL.md` "State Tracking"):
+ *   - `plan_id`:               the `{date}-{slug}` identifier used to derive
+ *                              every sibling file name (`<plan_id>.md`,
+ *                              `<plan_id>-context.md`, `<plan_id>-review.md`,
+ *                              `<plan_id>-status.json`).
+ *   - `plan_file`:             relative name of the designer's plan markdown.
+ *   - `context_file`:          relative name of the context snapshot markdown.
+ *   - `review_file`:           relative name of the reviewer's review markdown
+ *                              (optional until the reviewer has run at least
+ *                              once — absence is meaningful).
+ *   - `round`:                 current review-revise round, 1-indexed.
+ *   - `status`:                lifecycle enum (see {@link PLAN_STATUS_VALUES}).
+ *   - `codegraph_available`:   R1 addition — whether `.codegraph/` was present
+ *                              when `ghs-plan-start` ran. Persists the path
+ *                              choice for the entire plan lifetime so later
+ *                              phases and status reports stay consistent.
+ *   - `max_rounds`:            soft cap on review-revise iterations.
+ *   - `max_rounds_breaches`:   how many times the user overrode the soft cap.
+ *   - `accepted_with_fail`:    true iff the plan passed with unfixed issues
+ *                              (audit flag — `status` stays `approved`).
+ *   - `keep_raw_on_success`:   debug flag — when true, raw subagent responses
+ *                              are kept on the happy path.
+ *   - `created_at` / `updated_at`: ISO-ish timestamps (`YYYY-MM-DDTHH:mm:ss`).
+ */
+export const PlanStatusSchema = z.strictObject({
+  plan_id: z.string().min(1),
+  plan_file: z.string().min(1),
+  context_file: z.string().min(1),
+  review_file: z.string().optional(),
+  round: z.number().int().nonnegative(),
+  status: z.enum(PLAN_STATUS_VALUES),
+  codegraph_available: z.boolean(),
+  max_rounds: z.number().int().positive(),
+  max_rounds_breaches: z.number().int().nonnegative(),
+  accepted_with_fail: z.boolean(),
+  keep_raw_on_success: z.boolean(),
+  created_at: z.string().min(1),
+  updated_at: z.string().min(1),
+});
+
+export type PlanStatus = z.infer<typeof PlanStatusSchema>;
+
+// -----------------------------------------------------------------------------
+// Path helpers
+// -----------------------------------------------------------------------------
+
+/**
+ * Directory holding every plan-related artefact for a project
+ * (`<projectDir>/.ghs/plans/`). The status file and its sibling
+ * plan/context/review markdowns all live here per the source skill's
+ * "File Conventions" table.
+ */
+export function plansDir(projectDir: string): string {
+  return resolve(projectDir, ".ghs", "plans");
+}
+
+/**
+ * Absolute path to a plan's status file
+ * (`<projectDir>/.ghs/plans/<plan_id>-status.json`).
+ *
+ * `planId` is the `{date}-{slug}` identifier emitted by `ghs-plan-start`. The
+ * `-status.json` suffix matches the source skill's file convention table
+ * verbatim.
+ */
+export function statusFilePath(projectDir: string, planId: string): string {
+  return resolve(plansDir(projectDir), `${planId}-status.json`);
+}
+
+// -----------------------------------------------------------------------------
+// Timestamp helper
+// -----------------------------------------------------------------------------
+
+/**
+ * Produce a `YYYY-MM-DDTHH:mm:ss` timestamp in the *local* timezone, matching
+ * the format the source skill writes. The source uses Python
+ * `datetime.now().strftime("%Y-%m-%dT%H:%M:%S")` (no `tzinfo` → local time, no
+ * millis). We mirror that exactly so a status file written by the TS port is
+ * indistinguishable from one the source plugin would have produced.
+ *
+ * We deliberately avoid `new Date().toISOString()` — that emits UTC with
+ * millis and a `Z` suffix, which would break byte-parity with any future
+ * equivalence harness and reads as a different timezone to users diffing
+ * `status.json`.
+ */
+export function formatLocalTimestamp(now: Date = new Date()): string {
+  const pad = (n: number): string => n.toString().padStart(2, "0");
+  return (
+    `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}` +
+    `T${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`
+  );
+}
+
+// -----------------------------------------------------------------------------
+// Defaults
+// -----------------------------------------------------------------------------
+
+/**
+ * Default soft cap on review-revise rounds before the dispatcher asks the user
+ * whether to breach. Matches the source skill's default (Phase 2 "Constants"
+ * block). Exposed as a named constant so the plan tools can reference the same
+ * source of truth instead of re-hardcoding `5`.
+ */
+export const DEFAULT_MAX_ROUNDS = 5;
+
+/**
+ * Build a fresh `PlanStatus` object for a newly-started plan, with sensible
+ * defaults pulled from the source skill's "State Tracking" section.
+ *
+ * The caller supplies the identifying fields (`planId`, `planFile`,
+ * `contextFile`, `codegraphAvailable`) plus optional overrides (e.g. a
+ * non-default `max_rounds`). Everything else gets the source defaults:
+ *   - `round: 1`           — first review-revise round.
+ *   - `status: "designing"` — initial lifecycle state.
+ *   - `max_rounds_breaches: 0`, `accepted_with_fail: false`,
+ *     `keep_raw_on_success: false`.
+ *   - `created_at` and `updated_at` set to the same local timestamp.
+ *
+ * This is a pure function — it does NOT touch the filesystem. Pair with
+ * {@link writePlanStatus} to persist.
+ */
+export function createInitialPlanStatus(args: {
+  planId: string;
+  planFile: string;
+  contextFile: string;
+  codegraphAvailable: boolean;
+  maxRounds?: number;
+  now?: Date;
+}): PlanStatus {
+  const ts = formatLocalTimestamp(args.now);
+  return {
+    plan_id: args.planId,
+    plan_file: args.planFile,
+    context_file: args.contextFile,
+    round: 1,
+    status: "designing",
+    codegraph_available: args.codegraphAvailable,
+    max_rounds: args.maxRounds ?? DEFAULT_MAX_ROUNDS,
+    max_rounds_breaches: 0,
+    accepted_with_fail: false,
+    keep_raw_on_success: false,
+    created_at: ts,
+    updated_at: ts,
+  };
+}
+
+// -----------------------------------------------------------------------------
+// I/O — read / write / existence probe
+// -----------------------------------------------------------------------------
+
+/**
+ * Read + validate a plan's status file.
+ *
+ * Behaviour:
+ *   - If the file does not exist, returns `null` (the caller — typically
+ *     `ghs-plan-review` — decides whether that is an error, e.g. "no plan in
+ *     progress, call `ghs-plan-start` first"). We do NOT throw here because
+ *     "no status yet" is a normal state for the dispatcher's first step.
+ *   - If the file exists but is unparseable JSON or fails the Zod schema,
+ *     throws a descriptive `Error` (corrupt state should never be silently
+ *     ignored — the dispatcher must stop and surface the problem).
+ *
+ * @param projectDir - absolute host project root.
+ * @param planId     - the `{date}-{slug}` plan identifier.
+ * @returns the validated `PlanStatus`, or `null` when no status file exists.
+ */
+export async function readPlanStatus(
+  projectDir: string,
+  planId: string,
+): Promise<PlanStatus | null> {
+  const path = statusFilePath(projectDir, planId);
+  const file = Bun.file(path);
+  const exists = await file.exists();
+  if (!exists) {
+    return null;
+  }
+
+  let text: string;
+  try {
+    text = await file.text();
+  } catch (err) {
+    throw new Error(
+      `Failed to read plan status at ${path}: ${(err as Error).message}`,
+    );
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    throw new Error(
+      `Failed to parse plan status at ${path}: invalid JSON — ${(err as Error).message}`,
+    );
+  }
+
+  // Zod validation surfaces structural corruption (missing fields, wrong
+  // types, unknown fields via `.strict()`) as a thrown ZodError. We let it
+  // propagate — the plan tools catch Errors and return the message to the AI.
+  return PlanStatusSchema.parse(parsed);
+}
+
+/**
+ * Write a `PlanStatus` to its status file.
+ *
+ * Side effects:
+ *   - Creates `<projectDir>/.ghs/plans/` (recursively) if it does not already
+ *     exist, so a fresh project that just ran `ghs-init` does not need a
+ *     separate `mkdir`. Matches the source skill's Phase 0 step 3 behaviour.
+ *   - Validates `status` against the schema BEFORE writing — a caller that
+ *     built an invalid object (e.g. forgot `codegraph_available`) fails loudly
+ *     here rather than persisting corrupt state.
+ *
+ * The on-disk format is `JSON.stringify(status, null, 2)` (pretty-printed,
+ * matching the source skill's `json.dump(indent=2)` convention so diffs stay
+ * reviewable). No trailing newline is added — the source does not emit one
+ * either (`json.dump` has no trailing newline).
+ *
+ * @param projectDir - absolute host project root.
+ * @param status     - the status object to persist (validated + written).
+ * @returns the absolute path the status was written to.
+ */
+export async function writePlanStatus(
+  projectDir: string,
+  status: PlanStatus,
+): Promise<string> {
+  // Validate first so we never write a structurally-invalid status to disk.
+  // Zod `.parse` throws ZodError on failure; the plan tools surface that.
+  const validated = PlanStatusSchema.parse(status);
+
+  const dir = plansDir(projectDir);
+  // mkdir -p the plans dir. `recursive: true` makes this a no-op when the dir
+  // already exists, so repeated writes are cheap.
+  await mkdir(dir, { recursive: true });
+
+  const path = statusFilePath(projectDir, validated.plan_id);
+  await Bun.write(path, JSON.stringify(validated, null, 2));
+  return path;
+}
+
+/**
+ * Whether a status file exists for the given plan. Convenience wrapper around
+ * `Bun.file(...).exists()` so callers don't have to import BunFile plumbing
+ * just to do an existence check (mirrors the `fileExists` helper in
+ * `src/lib/config.ts`).
+ */
+export async function planStatusExists(
+  projectDir: string,
+  planId: string,
+): Promise<boolean> {
+  return Bun.file(statusFilePath(projectDir, planId)).exists();
+}

package/src/plugin.ts

@@ -0,0 +1,76 @@
+// Plugin entry point — the OpenCode plugin function.
+//
+// This module wires together everything implemented in s1-feat-005 through
+// s4-feat-005:
+//   - Registers all 10 tools (ghs-init / ghs-config / ghs-plan-start /
+//     ghs-plan-review / ghs-plan-finalize / ghs-sprint / ghs-code /
+//     ghs-status / ghs-archive / ghs-force-archive) under their hyphenated
+//     keys — the complete plan §3.4 D2 tool surface (Phase 0 spike 001
+//     confirmed hyphenated keys load + round-trip correctly).
+//   - Pushes a single-line workflow hint into the AI's system prompt via the
+//     `experimental.chat.system.transform` hook (Phase 0 spike 001 confirmed
+//     strings pushed here land in the system prompt verbatim).
+//
+// The hint lists all 10 implemented tools and the full init → plan → sprint
+// → code → status → archive workflow. Per spike 003 divergence, the hint text
+// uses descriptive phrasing ("codegraph MCP tools") rather than hardcoding
+// double-prefixed tool names (codegraph_codegraph_*) when those tools are
+// introduced — those names depend on the MCP server name and would be brittle.
+
+import type { Plugin } from "@opencode-ai/plugin";
+
+import { initTool } from "./tools/init.ts";
+import { statusTool } from "./tools/status.ts";
+import { archiveTool } from "./tools/archive.ts";
+import { forceArchiveTool } from "./tools/force-archive.ts";
+import { configTool } from "./tools/config.ts";
+import { sprintTool } from "./tools/sprint.ts";
+import { planStartTool } from "./tools/plan-start.ts";
+import { planReviewTool } from "./tools/plan-review.ts";
+import { planFinalizeTool } from "./tools/plan-finalize.ts";
+import { codeTool } from "./tools/code.ts";
+
+/**
+ * Single-line hint pushed into the AI's system prompt on every chat. Lists
+ * all 10 implemented tool names, the workflow order, and the model-config
+ * entry point. The plan-dispatcher subagents (ghs-context-haiku /
+ * ghs-plan-designer / ghs-plan-reviewer) are invoked by the plan tools via
+ * the Task tool; ghs-code's coding subagent is dispatched the same way
+ * after ghs-code returns its feature-impl prompt.
+ *
+ * Kept to one line so it shows up as a single contiguous block in the
+ * rendered system prompt (easier for the AI to spot). The user-facing note
+ * about `.ghs/ghs.json` is critical for R3: model IDs are user-configurable
+ * but only take effect after a `ghs-config` call + OpenCode restart.
+ */
+const SYSTEM_HINT_TEXT =
+  "Golden Hoop Spell (ghs) plugin — orchestrates a structured init → plan → sprint → code → status → archive workflow. " +
+  "Tools implemented: ghs-init, ghs-config, ghs-plan-start, ghs-plan-review, ghs-plan-finalize, ghs-sprint, ghs-code, ghs-status, ghs-archive, ghs-force-archive. " +
+  "Workflow order: ghs-init → ghs-config → ghs-plan-start → ghs-plan-review → ghs-plan-finalize → ghs-sprint → ghs-code → ghs-status → ghs-archive. " +
+  "Model IDs for the 3 plan-dispatcher subagents are user-configurable via `.ghs/ghs.json`; after editing run `ghs-config` then restart OpenCode.";
+
+/**
+ * The ghs OpenCode plugin. Default-exported from `src/index.ts`.
+ *
+ * Signature conforms to the canonical `Plugin` type from
+ * `@opencode-ai/plugin`: `async (input) => Hooks`. We don't currently use
+ * the input (session/project context); tools resolve the project dir from
+ * their own `ToolContext` (see `src/lib/project.ts`).
+ */
+export const ghsPlugin: Plugin = async () => ({
+  tool: {
+    "ghs-init": initTool,
+    "ghs-config": configTool,
+    "ghs-plan-start": planStartTool,
+    "ghs-plan-review": planReviewTool,
+    "ghs-plan-finalize": planFinalizeTool,
+    "ghs-sprint": sprintTool,
+    "ghs-code": codeTool,
+    "ghs-status": statusTool,
+    "ghs-archive": archiveTool,
+    "ghs-force-archive": forceArchiveTool,
+  },
+  "experimental.chat.system.transform": async (_input, output) => {
+    output.system.push(SYSTEM_HINT_TEXT);
+  },
+});