@trieungoctam/speckit 0.2.0 → 0.3.0

package/README.md

@@ -4,12 +4,25 @@ Speckit is a local-first Agile + TDD workflow compiler for agentic IDEs. It turn
 
 Speckit owns the workflow contract and generates adapters for the tools you already use. The public product vocabulary is Speckit-only: Agile shaping, TDD execution, task graph triage, and IDE adapter compilation.
 
+Speckit also ships a portable skill catalog and super-agent router. IDE-specific agents read `.speckit/agents/super-agent.md` and `.speckit/skills/catalog.md` first, then load only the focused skill needed for the current phase.
+
+The curated skill set is intentionally small: `spec-shape`, `spec-research`, `spec-plan`, `spec-context`, `spec-graph`, `spec-session`, `spec-tdd`, `spec-test`, `spec-debug`, `spec-review`, `spec-docs`, and `spec-ship`. These are adapted from proven orchestration patterns without importing a broad domain-specific catalog.
+
 ## Quickstart
 
 ```bash
+npx @trieungoctam/speckit@latest init --ide cursor
 npx @trieungoctam/speckit@latest init --ide all
 npx @trieungoctam/speckit@latest init --enterprise --ide all
+npx @trieungoctam/speckit@latest memory refresh
+npx @trieungoctam/speckit@latest session start "Add checkout validation"
 npx @trieungoctam/speckit@latest quick "Add checkout validation"
+npx @trieungoctam/speckit@latest context .speckit/stories/<story>.md
+npx @trieungoctam/speckit@latest sync
+npx @trieungoctam/speckit@latest sprint plan
+npx @trieungoctam/speckit@latest graph triage --json
+npx @trieungoctam/speckit@latest ready .speckit/stories/<story>.md
+npx @trieungoctam/speckit@latest session checkpoint --note "red complete"
 npx @trieungoctam/speckit@latest review
 ```
 
@@ -26,15 +39,22 @@ speckit doctor
 ```text
 intent
   -> start session
+  -> super agent routing
+  -> refresh project memory
   -> shape
   -> plan
+  -> sprint plan
   -> context
   -> story with acceptance criteria
-  -> sync / triage
+  -> sync / graph triage
+  -> readiness gate
   -> red test evidence
+  -> session checkpoint
   -> minimal implementation
   -> green test evidence
+  -> session checkpoint
   -> refactor validation
+  -> session compact
   -> review
 ```
 
@@ -44,19 +64,31 @@ For implementation stories, red-green-refactor evidence is mandatory. A story is
 
 | Command | Purpose |
 | --- | --- |
-| `speckit init` | Create `.speckit/` core rules and all IDE adapters. |
-| `speckit init --enterprise` | Add flow, tool policy, and prompt harness files. |
-| `speckit init --ide <name>` | Generate one adapter: `claude-code`, `codex`, `antigravity`, `opencode`, or `cursor`. |
+| `speckit init` | Create `.speckit/` core runtime, super-agent, skill catalog, and all IDE adapters. |
+| `speckit init --enterprise` | Add flow, tool policy, and prompt harness files on top of the shared runtime. |
+| `speckit init --ide <name>` | Generate shared Speckit runtime plus one adapter: `claude-code`, `codex`, `antigravity`, `opencode`, or `cursor`. |
 | `speckit doctor` | Report required tools, optional integrations, test commands, and adapter readiness. |
 | `speckit doctor --deep` | Verify core enterprise harness files. |
 | `speckit start "<idea>"` | Create a durable session handoff and current context. |
+| `speckit memory refresh` | Create durable project memory files for long-running agent work. |
+| `speckit session start` | Create or resume the active session state. |
+| `speckit session checkpoint` | Append a long-session checkpoint and artifact log entry. |
+| `speckit session compact` | Create an anchored summary for resume or handoff. |
+| `speckit session resume` | Mark a session as active and print its handoff path. |
+| `speckit session status` | Print active session state paths. |
 | `speckit shape "<intent>"` | Create a short spec contract. |
 | `speckit context <story>` | Build the current implementation context from a story. |
 | `speckit quick "<intent>"` | Create one story plus matching TDD evidence file. |
 | `speckit plan "<intent>"` | Create PRD, architecture, story, and evidence skeletons. |
 | `speckit triage` | Summarize synced story state without interactive graph commands. |
 | `speckit next` | Safely wraps `bv --robot-next --format json`. |
-| `speckit sync` | Export Speckit stories as beads-compatible JSONL metadata. |
+| `speckit sprint plan` | Build a sprint plan and status file from synced stories. |
+| `speckit sprint next` | Pick the next selectable story from sprint state. |
+| `speckit graph triage` | Run Beads Viewer robot triage, or local JSON fallback if `bv` is missing. |
+| `speckit graph plan` | Run Beads Viewer robot plan, or local JSON fallback if `bv` is missing. |
+| `speckit graph insights` | Run Beads Viewer robot insights, or local JSON fallback if `bv` is missing. |
+| `speckit sync` | Export Speckit stories as `.speckit/sync/beads-sync.jsonl` and prepare `.beads/beads.jsonl` for Beads Viewer. |
+| `speckit ready <story>` | Validate story status, context, evidence, graph sync, and safety policy before implementation. |
 | `speckit run <story>` | Print the TDD execution handoff for a story. |
 | `speckit review` | Print the review checklist and current diff summary. |
 | `speckit close <story>` | Create a closure checklist linked to the story and sync step. |

package/dist/adapters/antigravity-adapter.js

@@ -12,12 +12,12 @@ export const antigravityAdapter = {
     ],
     render() {
         return [
-            rule("agile", "Follow Speckit Agile: shape intent, create stories with ACs, preserve dependencies, and emit artifacts for review."),
-            rule("tdd", "For code changes, use TDD: record red evidence, green evidence, and refactor validation."),
+            rule("agile", "Follow Speckit Agile: shape intent, read .speckit/agents/super-agent.md, .speckit/skills/catalog.md, .speckit/memory/project-context.md, .speckit/sessions/active.md, and .speckit/context/current.md, create stories with ACs, preserve session handoff, and emit artifacts for review."),
+            rule("tdd", "For code changes, use TDD: confirm acceptance criteria, use red-green-refactor, checkpoint each boundary, compact before handoff, and record evidence for each step."),
             rule("enterprise-safety", "Require human approval for destructive commands, production changes, secrets access, and deployment."),
-            workflow("plan", "Create a Speckit plan artifact with PRD, architecture, stories, risks, and dependencies."),
-            workflow("tdd-run", "Run a story with TDD. Emit artifact sections: Test Intent, Red, Green, Refactor."),
-            workflow("review", "Review the produced artifacts and code diff. Flag AC gaps, TDD gaps, security issues, and docs needs."),
+            workflow("plan", "Create a Speckit plan artifact with PRD, architecture, stories, risks, dependencies, and graph sync notes."),
+            workflow("tdd-run", "Run a story with TDD from the Speckit super agent router, skill catalog, .speckit/memory/project-context.md, .speckit/context/current.md, .speckit/context/subagent-handoff.md, and active session summary. Require speckit ready <story> first. Emit artifact sections: Test Intent, Red, Green, Refactor. Use only robot-safe graph commands."),
+            workflow("review", "Review the produced artifacts and code diff. Flag AC gaps, TDD gaps, security issues, docs needs, session checkpoint freshness, and session handoff gaps."),
         ];
     },
 };

package/dist/adapters/claude-code-adapter.js

@@ -1,5 +1,5 @@
 import { json, markdown } from "../core/managed-files.js";
-const skillIntro = `Follow Speckit: Agile story flow plus mandatory TDD evidence. Use project-local context first.`;
+const skillIntro = `Follow Speckit: Agile story flow plus mandatory TDD evidence. Read .speckit/memory/project-context.md, .speckit/context/current.md, and active session summary first. Preserve session handoff, checkpoint long work, use red-green-refactor, and use robot-safe graph commands only.`;
 export const claudeCodeAdapter = {
     name: "claude-code",
     displayName: "Claude Code",
@@ -21,7 +21,12 @@ Use Speckit for Agile + TDD work.
 - Start from \`.speckit/rules/agile-policy.md\`.
 - For implementation, follow \`.speckit/rules/tdd-policy.md\`.
 - For safety, follow \`.speckit/rules/enterprise-safety.md\`.
-- Prefer \`speckit quick\`, \`speckit plan\`, \`speckit run\`, and \`speckit review\` over ad hoc prompts.
+- Prefer \`speckit start\`, \`speckit memory refresh\`, \`speckit session checkpoint\`, \`speckit context\`, \`speckit sync\`, \`speckit graph triage\`, \`speckit run\`, and \`speckit review\` over ad hoc prompts.
+- Read \`.speckit/agents/super-agent.md\`, \`.speckit/skills/catalog.md\`, \`.speckit/memory/project-context.md\`, and \`.speckit/sessions/active.md\` before long-running work.
+- Run \`speckit ready <story>\` before implementation; story status must be \`ready-for-dev\` and context status must be \`fresh\`.
+- Run \`speckit session compact\` before context gets noisy or before handoff.
+- For code stories, confirm acceptance criteria and record red-green-refactor evidence before handoff.
+- Never run bare \`bv\`; use robot flags such as \`bv --robot-next --format json\`.
 `),
             },
             {
@@ -33,9 +38,9 @@ Use Speckit for Agile + TDD work.
                     includeCoAuthoredBy: false,
                 }),
             },
-            skill("speckit-plan", "Create or update a Speckit Agile plan.", "Read `.speckit/workflows/shape.md`, then create PRD, architecture, and story artifacts with acceptance criteria."),
-            skill("speckit-tdd", "Execute a Speckit story with TDD.", "Read `.speckit/workflows/tdd-run.md`. Do not implement before test intent and red evidence are recorded."),
-            skill("speckit-review", "Review a Speckit change.", "Read `.speckit/workflows/review.md`. Prioritize bugs, TDD evidence gaps, security, and missing docs."),
+            skill("speckit-plan", "Create or update a Speckit Agile plan.", "Read `.speckit/agents/super-agent.md`, `.speckit/skills/catalog.md`, and `.speckit/workflows/shape.md`, preserve the session id, then create PRD, architecture, and story artifacts with acceptance criteria."),
+            skill("speckit-tdd", "Execute a Speckit story with TDD.", "Read `.speckit/memory/project-context.md`, `.speckit/context/current.md`, `.speckit/context/subagent-handoff.md`, active session summary, and `.speckit/workflows/tdd-run.md`. Do not implement before `speckit ready <story>` passes, test intent is clear, and red evidence is recorded. Checkpoint after red, green, and refactor."),
+            skill("speckit-review", "Review a Speckit change.", "Read `.speckit/workflows/review.md` and the active session artifact log. Prioritize AC coverage, TDD evidence gaps, security, docs impact, session checkpoint freshness, and graph sync status."),
         ];
     },
 };

package/dist/adapters/codex-adapter.js

@@ -19,6 +19,10 @@ This repository uses Speckit: Agile + TDD for agentic development.
 
 Rules:
 - Shape intent before implementation.
+- Read \`.speckit/agents/super-agent.md\`, \`.speckit/skills/catalog.md\`, \`.speckit/memory/project-context.md\`, and \`.speckit/sessions/active.md\` before long-running work.
+- Read \`.speckit/context/current.md\` before running code changes.
+- Run \`speckit ready <story>\` before implementation; story status must be \`ready-for-dev\` and context status must be \`fresh\`.
+- Use \`speckit session checkpoint\` at red, green, refactor, and review boundaries; use \`speckit session compact\` before handoff.
 - For code stories, write test intent and capture red/green/refactor evidence.
 - Never call bare \`bv\`; use \`bv --robot-*\`.
 - Do not weaken approval or sandbox settings.
@@ -37,9 +41,9 @@ web_search = true
 [features]
 child_agents_md = true`),
             },
-            prompt("plan", "Create a Speckit plan from the user intent. Include PRD, architecture, stories, ACs, TDD checklist, and risks."),
-            prompt("tdd-run", "Execute the selected Speckit story using red-green-refactor. Record command evidence before marking done."),
-            prompt("review", "Review the current diff against Speckit ACs, TDD evidence, security, and docs impact."),
+            prompt("plan", "Create a Speckit plan from the user intent. Use the Speckit super agent router and skill catalog. Preserve session context, project memory, PRD, architecture, stories, ACs, TDD checklist, risks, and graph sync notes."),
+            prompt("tdd-run", "Execute the selected Speckit story using .speckit/memory/project-context.md, .speckit/context/current.md, .speckit/context/subagent-handoff.md, active session summary, and red-green-refactor. Require speckit ready <story>, confirm ACs, checkpoint each boundary, record command evidence, and use only robot-safe graph commands."),
+            prompt("review", "Review the current diff against Speckit ACs, TDD evidence, security, docs impact, session handoff, session checkpoint freshness, and graph sync status."),
         ];
     },
 };

package/dist/adapters/cursor-adapter.js

@@ -12,9 +12,9 @@ export const cursorAdapter = {
     ],
     render() {
         return [
-            rule("agile", "alwaysApply: true", "Use Speckit Agile flow. Shape intent, create stories with ACs, and keep work scoped."),
-            rule("tdd", "description: Apply when implementing or modifying code", "Use red-green-refactor. Record TDD evidence before review-ready."),
-            rule("review", "description: Apply when reviewing code or preparing a PR", "Review AC coverage, TDD evidence, security, and docs impact."),
+            rule("agile", "alwaysApply: true", "Use Speckit Agile flow. Read .speckit/agents/super-agent.md, .speckit/skills/catalog.md, .speckit/memory/project-context.md, .speckit/sessions/active.md, .speckit/context/current.md, and .speckit/context/subagent-handoff.md. Preserve session handoff, create stories with ACs, and keep work scoped."),
+            rule("tdd", "description: Apply when implementing or modifying code", "Use red-green-refactor. Run speckit ready <story>, confirm acceptance criteria, checkpoint each TDD boundary, and record TDD evidence before review-ready."),
+            rule("review", "description: Apply when reviewing code or preparing a PR", "Review AC coverage, TDD evidence, security, docs impact, session checkpoint freshness, and graph sync status."),
             rule("enterprise-safety", "alwaysApply: true", "Do not expose secrets. Ask before destructive commands, deployment, or production changes."),
             {
                 path: ".cursor/mcp.json",
@@ -30,6 +30,13 @@ Use Speckit for Agile + TDD work. Cursor-specific rules live in \`.cursor/rules/
 
 - Follow \`.speckit/rules/agile-policy.md\`.
 - Follow \`.speckit/rules/tdd-policy.md\` for code stories.
+- Read \`.speckit/agents/super-agent.md\` and \`.speckit/skills/catalog.md\` before selecting an execution mode.
+- Read \`.speckit/memory/project-context.md\` before long-running work.
+- Read \`.speckit/sessions/active.md\` before resuming or compacting work.
+- Read \`.speckit/context/current.md\` before implementation work.
+- Read \`.speckit/context/subagent-handoff.md\` before implementation work.
+- Run \`speckit ready <story>\` before code changes.
+- Run \`speckit session checkpoint\` at task boundaries and \`speckit session compact\` before handoff.
 - Never run bare \`bv\`; use robot commands only.
 `),
             },

package/dist/adapters/opencode-adapter.js

@@ -53,6 +53,7 @@ permission: ${JSON.stringify(permission)}
 # speckit-${name}
 
 Follow \`.speckit/rules/agile-policy.md\`, \`.speckit/rules/tdd-policy.md\`, and \`.speckit/rules/enterprise-safety.md\`.
+Read \`.speckit/agents/super-agent.md\`, \`.speckit/skills/catalog.md\`, \`.speckit/memory/project-context.md\`, \`.speckit/sessions/active.md\`, \`.speckit/context/current.md\`, and \`.speckit/context/subagent-handoff.md\` before implementation work. Select the smallest matching Speckit skill. Require \`speckit ready <story>\`, confirm acceptance criteria, preserve session handoff, checkpoint red-green-refactor boundaries, compact before handoff, and use only robot-safe graph commands.
 `),
     };
 }

package/dist/cli.js

@@ -5,10 +5,15 @@ import { shapeCommand } from "./commands/shape.js";
 import { contextCommand } from "./commands/context.js";
 import { quickCommand } from "./commands/quick.js";
 import { planCommand } from "./commands/plan.js";
+import { memoryCommand } from "./commands/memory.js";
+import { sessionCommand } from "./commands/session.js";
+import { sprintCommand } from "./commands/sprint.js";
+import { graphCommand } from "./commands/graph.js";
 import { triageCommand } from "./commands/triage.js";
 import { nextCommand } from "./commands/next.js";
 import { syncCommand } from "./commands/sync.js";
 import { runCommand } from "./commands/run.js";
+import { readyCommand } from "./commands/ready.js";
 import { reviewCommand } from "./commands/review.js";
 import { closeCommand } from "./commands/close.js";
 export async function main(argv = process.argv.slice(2), root = process.cwd()) {
@@ -34,12 +39,28 @@ export async function main(argv = process.argv.slice(2), root = process.cwd()) {
                 return quickCommand({ root, intent: requiredIntent(parsed) });
             case "plan":
                 return planCommand({ root, intent: requiredIntent(parsed) });
+            case "memory":
+                return memoryCommand({ root, action: requiredAction(parsed) });
+            case "session":
+                return sessionCommand({
+                    root,
+                    action: requiredAction(parsed),
+                    target: parsed.args.slice(1).join(" ").trim() || undefined,
+                    note: value(parsed, "note"),
+                    json: has(parsed, "json"),
+                });
+            case "sprint":
+                return sprintCommand({ root, action: requiredAction(parsed), json: has(parsed, "json") });
+            case "graph":
+                return graphCommand({ root, action: requiredAction(parsed), json: has(parsed, "json") });
             case "triage":
                 return triageCommand({ root, json: has(parsed, "json") });
             case "next":
                 return nextCommand();
             case "sync":
                 return syncCommand({ root });
+            case "ready":
+                return readyCommand({ root, target: requiredIntent(parsed), json: has(parsed, "json") });
             case "run":
                 return runCommand({ root, target: requiredIntent(parsed) });
             case "review":
@@ -89,6 +110,12 @@ function requiredIntent(parsed) {
         throw new Error(`Command "${parsed.command}" requires a target or intent.`);
     return intent;
 }
+function requiredAction(parsed) {
+    const action = parsed.args[0]?.trim();
+    if (!action)
+        throw new Error(`Command "${parsed.command}" requires an action.`);
+    return action;
+}
 function value(parsed, name) {
     const found = parsed.flags.get(name);
     return typeof found === "string" ? found : undefined;
@@ -108,9 +135,14 @@ Usage:
   speckit context <story-path-or-id>
   speckit quick "<intent>"
   speckit plan "<intent>"
+  speckit memory refresh
+  speckit session start|checkpoint|compact|resume|status [target] [--note "..."] [--json]
+  speckit sprint plan|next [--json]
+  speckit graph triage|plan|insights [--json]
   speckit triage [--json]
   speckit next
   speckit sync
+  speckit ready <story-path-or-id> [--json]
   speckit run <story-path-or-id>
   speckit review
   speckit close <story-path-or-id>

package/dist/commands/context.js

@@ -1,5 +1,5 @@
 import { markdown, writeManagedFiles } from "../core/managed-files.js";
-import { resolveStory } from "../core/story.js";
+import { extractEvidenceReference, extractSection, resolveStory } from "../core/story.js";
 export async function contextCommand(options) {
     const stdout = options.stdout ?? console;
     const story = await resolveStory(options.root, options.target);
@@ -8,10 +8,19 @@ export async function contextCommand(options) {
         return 1;
     }
     const contextPath = ".speckit/context/current.md";
+    const handoffPath = ".speckit/context/subagent-handoff.md";
+    const acceptanceCriteria = extractSection(story.content, "Acceptance Criteria") ?? "- Not defined";
+    const evidenceReference = story.evidencePath ?? extractEvidenceReference(story.content);
     await writeManagedFiles(options.root, [
         {
             path: contextPath,
-            content: markdown(`# Current Spec Context
+            content: markdown(`---
+status: fresh
+story: ${story.path}
+evidence: ${evidenceReference ?? "missing"}
+---
+
+# Current Spec Context
 
 ## Story
 ${story.title}
@@ -19,35 +28,60 @@ ${story.title}
 ## Story Path
 \`${story.path}\`
 
+## Story Status
+${story.status ?? "missing"}
+
 ## Acceptance Criteria
-${extractSection(story.content, "Acceptance Criteria") ?? "- Not defined"}
+${acceptanceCriteria}
 
 ## TDD Evidence
-${extractEvidenceReference(story.content) ?? "- Create or update matching `.speckit/evidence/*tdd-evidence.md`"}
+${evidenceReference ? `\`${evidenceReference}\`` : "- Create or update matching `.speckit/evidence/*tdd-evidence.md`"}
+
+## Spec Anti-Mistake Checklist
+- Reuse existing project patterns before adding new files.
+- Verify file locations before editing.
+- Do not introduce new libraries without explicit need.
+- Preserve existing behavior unless an acceptance criterion requires change.
+- Check prior related stories or changelog before repeating work.
 
 ## Next Command
+\`speckit ready ${story.id}\`
 \`speckit run ${story.id}\`
+`),
+        },
+        {
+            path: handoffPath,
+            content: markdown(`# Spec Subagent Handoff
+
+## Task
+Implement the story in \`${story.path}\`.
+
+## Files To Read
+- \`.speckit/context/current.md\`
+- \`${story.path}\`
+${evidenceReference ? `- \`${evidenceReference}\`` : "- Matching TDD evidence file"}
+- \`.speckit/tool-policy.yaml\`
+
+## Acceptance Criteria
+${acceptanceCriteria}
+
+## Constraints
+- Confirm story status is \`ready-for-dev\` before code changes.
+- Record red-green-refactor evidence.
+- Use only robot-safe graph commands.
+- Stop before destructive commands, production changes, or secret access.
+
+## Completion Signal
+- All acceptance criteria satisfied.
+- TDD evidence updated.
+- \`speckit review\` run before handoff.
+
+## Work Context
+${options.root}
 `),
         },
     ], true);
     stdout.log(contextPath);
+    stdout.log(handoffPath);
     return 0;
 }
-function extractEvidenceReference(content) {
-    const match = content.match(/`([^`]*tdd-evidence\.md)`/i);
-    return match ? `\`${match[1]}\`` : undefined;
-}
-function extractSection(content, heading) {
-    const lines = content.split("\n");
-    const start = lines.findIndex((line) => line.trim().toLowerCase() === `## ${heading}`.toLowerCase());
-    if (start === -1)
-        return undefined;
-    const collected = [];
-    for (const line of lines.slice(start + 1)) {
-        if (line.startsWith("## "))
-            break;
-        if (line.trim())
-            collected.push(line);
-    }
-    return collected.length > 0 ? collected.join("\n") : undefined;
-}

package/dist/commands/doctor.js

@@ -4,6 +4,7 @@ import { getAdapters } from "../config/adapter-registry.js";
 import { checkTools } from "../adapters/tool-checks.js";
 import { detectTestCommands } from "../core/test-detection.js";
 import { coreFiles, enterpriseFiles } from "../core/scaffold.js";
+import { agentFiles } from "../core/agent-scaffold.js";
 export async function doctorCommand(options) {
     const stdout = options.stdout ?? console;
     const tools = checkTools();
@@ -39,7 +40,7 @@ export async function doctorCommand(options) {
     return report.status === "ok" ? 0 : 1;
 }
 async function runDeepChecks(root) {
-    const requiredFiles = [...coreFiles(), ...enterpriseFiles()];
+    const requiredFiles = [...coreFiles(), ...enterpriseFiles(), ...agentFiles()];
     return Promise.all(requiredFiles.map(async (file) => ({
         name: file.path,
         path: file.path,

package/dist/commands/graph.d.ts

@@ -0,0 +1,7 @@
+export type GraphOptions = {
+    root: string;
+    action: string;
+    json?: boolean;
+    stdout?: Pick<typeof console, "log" | "error">;
+};
+export declare function graphCommand(options: GraphOptions): Promise<number>;

package/dist/commands/graph.js

@@ -0,0 +1,51 @@
+import { spawnSync } from "node:child_process";
+import { commandExists } from "../adapters/tool-checks.js";
+import { prepareBeadsMirror } from "../core/beads-mirror.js";
+import { readSyncedStories, selectableStories } from "../core/synced-stories.js";
+const robotActions = new Map([
+    ["triage", "--robot-triage"],
+    ["plan", "--robot-plan"],
+    ["insights", "--robot-insights"],
+]);
+export async function graphCommand(options) {
+    const stdout = options.stdout ?? console;
+    const robotFlag = robotActions.get(options.action);
+    if (!robotFlag) {
+        stdout.error("Usage: speckit graph triage|plan|insights [--json]");
+        return 1;
+    }
+    if (commandExists("bv")) {
+        await prepareBeadsMirror(options.root);
+        const result = spawnSync("bv", [robotFlag, "--format", options.json ? "json" : "toon"], {
+            encoding: "utf8",
+            cwd: options.root,
+        });
+        if ((result.status ?? 1) === 0) {
+            if (result.stdout)
+                stdout.log(result.stdout.trim());
+            if (result.stderr)
+                stdout.error(result.stderr.trim());
+            return 0;
+        }
+    }
+    const fallback = await localGraphFallback(options.root, options.action);
+    stdout.log(JSON.stringify(fallback, null, 2));
+    return 0;
+}
+async function localGraphFallback(root, action) {
+    const stories = await readSyncedStories(root);
+    const selectable = selectableStories(stories);
+    return {
+        source: ".speckit/sync/beads-sync.jsonl",
+        provider: "speckit-local-fallback",
+        action,
+        status: "bv-unavailable-or-failed",
+        quick_ref: {
+            total: stories.length,
+            selectable: selectable.length,
+            top_pick: selectable[0] ?? null,
+        },
+        recommendations: selectable.slice(0, 3),
+        command: "Install Beads Viewer for graph metrics: bv --robot-triage --format json",
+    };
+}

package/dist/commands/init.js

@@ -1,10 +1,12 @@
 import { coreFiles, enterpriseFiles } from "../core/scaffold.js";
+import { agentFiles } from "../core/agent-scaffold.js";
 import { writeManagedFiles } from "../core/managed-files.js";
 import { getAdapters } from "../config/adapter-registry.js";
 export async function initCommand(options) {
     const stdout = options.stdout ?? console;
     const selectedIde = options.ide ?? "all";
-    const baseFiles = options.enterprise ? [...coreFiles(), ...enterpriseFiles()] : coreFiles();
+    const sharedFiles = [...coreFiles(), ...agentFiles()];
+    const baseFiles = options.enterprise ? [...sharedFiles, ...enterpriseFiles()] : sharedFiles;
     const adapterFiles = getAdapters(selectedIde).flatMap((adapter) => adapter.render());
     const results = await writeManagedFiles(options.root, [...baseFiles, ...adapterFiles], options.force ?? false);
     const created = results.filter((result) => result.status === "created").length;

package/dist/commands/memory.d.ts

@@ -0,0 +1,6 @@
+export type MemoryOptions = {
+    root: string;
+    action: string;
+    stdout?: Pick<typeof console, "log" | "error">;
+};
+export declare function memoryCommand(options: MemoryOptions): Promise<number>;

package/dist/commands/memory.js

@@ -0,0 +1,11 @@
+import { refreshMemory } from "../core/memory.js";
+export async function memoryCommand(options) {
+    const stdout = options.stdout ?? console;
+    if (options.action !== "refresh") {
+        stdout.error("Usage: speckit memory refresh");
+        return 1;
+    }
+    const files = await refreshMemory(options.root);
+    stdout.log(`Refreshed Speckit memory: ${files.join(", ")}`);
+    return 0;
+}

package/dist/commands/plan.js

@@ -36,7 +36,13 @@ export async function planCommand(options) {
         },
         {
             path: `${dir}/story.md`,
-            content: markdown(`# Story: ${options.intent}
+            content: markdown(`---
+status: draft
+evidence: ${dir}/tdd-evidence.md
+context: pending
+---
+
+# Story: ${options.intent}
 
 ## Acceptance Criteria
 - Given ...
@@ -47,11 +53,22 @@ export async function planCommand(options) {
 \`${dir}/tdd-evidence.md\`
 
 ## Implementation Notes
+
+## Spec Anti-Mistake Checklist
+- Reuse existing project patterns before adding new files.
+- Verify file locations before editing.
+- Do not introduce new libraries without explicit need.
+- Preserve existing behavior unless an acceptance criterion requires change.
 `),
         },
         {
             path: `${dir}/tdd-evidence.md`,
-            content: markdown(`# TDD Evidence: ${options.intent}
+            content: markdown(`---
+status: missing
+story: ${dir}/story.md
+---
+
+# TDD Evidence: ${options.intent}
 
 ## Red
 

package/dist/commands/quick.js

@@ -11,7 +11,13 @@ export async function quickCommand(options) {
     await writeManagedFiles(options.root, [
         {
             path: storyPath,
-            content: markdown(`# Story: ${options.intent}
+            content: markdown(`---
+status: ready-for-dev
+evidence: ${evidencePath}
+context: pending
+---
+
+# Story: ${options.intent}
 
 ## Intent
 ${options.intent}
@@ -29,11 +35,23 @@ ${options.intent}
 
 ## Suggested Test Command
 \`${testCommand}\`
+
+## Spec Anti-Mistake Checklist
+- Reuse existing project patterns before adding new files.
+- Verify file locations before editing.
+- Do not introduce new libraries without explicit need.
+- Preserve existing behavior unless an acceptance criterion requires change.
+- Update docs only when behavior or workflow changes.
 `),
         },
         {
             path: evidencePath,
-            content: markdown(`# TDD Evidence: ${options.intent}
+            content: markdown(`---
+status: missing
+story: ${storyPath}
+---
+
+# TDD Evidence: ${options.intent}
 
 ## Test Intent
 

package/dist/commands/ready.d.ts

@@ -0,0 +1,7 @@
+export type ReadyOptions = {
+    root: string;
+    target: string;
+    json?: boolean;
+    stdout?: Pick<typeof console, "log" | "error">;
+};
+export declare function readyCommand(options: ReadyOptions): Promise<number>;

package/dist/commands/ready.js

@@ -0,0 +1,20 @@
+import { evaluateReadiness } from "../core/readiness.js";
+export async function readyCommand(options) {
+    const stdout = options.stdout ?? console;
+    const report = await evaluateReadiness(options.root, options.target);
+    if (options.json) {
+        stdout.log(JSON.stringify(report, null, 2));
+        return report.status === "ready" ? 0 : 1;
+    }
+    stdout.log(`# Speckit Readiness: ${report.status}`);
+    if (report.story) {
+        stdout.log(`Story: ${report.story.path}`);
+    }
+    for (const check of report.checks) {
+        stdout.log(`- ${check.ok ? "ok" : "blocked"} ${check.name}: ${check.detail}`);
+    }
+    if (report.status !== "ready") {
+        stdout.error("Run the suggested setup commands before `speckit run`.");
+    }
+    return report.status === "ready" ? 0 : 1;
+}

package/dist/commands/run.js

@@ -1,4 +1,5 @@
 import { resolveStory } from "../core/story.js";
+import { evaluateReadiness } from "../core/readiness.js";
 export async function runCommand(options) {
     const stdout = options.stdout ?? console;
     const story = await resolveStory(options.root, options.target);
@@ -6,16 +7,28 @@ export async function runCommand(options) {
         stdout.error(`Story not found: ${options.target}`);
         return 1;
     }
+    const readiness = await evaluateReadiness(options.root, options.target);
+    if (readiness.status !== "ready") {
+        stdout.error(`Story is not ready for implementation: ${story.path}`);
+        for (const check of readiness.checks.filter((item) => !item.ok)) {
+            stdout.error(`- ${check.name}: ${check.detail}`);
+        }
+        stdout.error(`Run \`speckit ready ${story.id}\` after preparing context and sync.`);
+        return 1;
+    }
     stdout.log(`# Speckit TDD Run
 
 Story: ${story.path}
 
-1. Read the story and acceptance criteria.
+Status: ready-for-dev
+
+1. Read \`.speckit/context/current.md\`, story, acceptance criteria, and subagent handoff.
 2. Identify the smallest executable test that should fail.
-3. Record red evidence in the matching \`.speckit/evidence/*tdd-evidence.md\` file.
+3. Record red evidence in the linked TDD evidence file.
 4. Implement the minimal behavior.
 5. Record green evidence.
 6. Refactor only after tests are green, then record validation.
+7. Continue until all acceptance criteria are satisfied or a stop condition is hit.
 
 Recommended handoff:
 \`speckit review\` before commit or PR.