@trieungoctam/speckit 0.1.0 → 0.2.2

package/README.md

@@ -2,13 +2,17 @@
 
 Speckit is a local-first Agile + TDD workflow compiler for agentic IDEs. It turns rough intent into specs, stories, TDD evidence, and native IDE instruction packs.
 
-It is inspired by the operating patterns in ClaudeKit, BMad Method, and Beads Viewer, but it does not fork their runtime. Speckit owns the workflow contract and generates adapters for the tools you already use.
+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.
 
 ## Quickstart
 
 ```bash
 npx @trieungoctam/speckit@latest init --ide all
+npx @trieungoctam/speckit@latest init --enterprise --ide all
 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 ready .speckit/stories/<story>.md
 npx @trieungoctam/speckit@latest review
 ```
 
@@ -24,9 +28,13 @@ speckit doctor
 
 ```text
 intent
+  -> start session
   -> shape
   -> plan
+  -> context
   -> story with acceptance criteria
+  -> sync / triage
+  -> readiness gate
   -> red test evidence
   -> minimal implementation
   -> green test evidence
@@ -41,15 +49,22 @@ 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 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 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 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. |
 
 ## Supported IDEs
 

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/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, 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 .speckit/context/current.md and .speckit/context/subagent-handoff.md. 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, 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/context/current.md first, preserve session handoff, use red-green-refactor, and use robot-safe graph commands only.`;
 export const claudeCodeAdapter = {
     name: "claude-code",
     displayName: "Claude Code",
@@ -21,7 +21,10 @@ 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 context\`, \`speckit sync\`, \`speckit triage\`, \`speckit run\`, and \`speckit review\` over ad hoc prompts.
+- Run \`speckit ready <story>\` before implementation; story status must be \`ready-for-dev\` and context status must be \`fresh\`.
+- 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 +36,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/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/context/current.md`, `.speckit/context/subagent-handoff.md`, and `.speckit/workflows/tdd-run.md`. Do not implement before `speckit ready <story>` passes, test intent is clear, and red evidence is recorded."),
+            skill("speckit-review", "Review a Speckit change.", "Read `.speckit/workflows/review.md`. Prioritize AC coverage, TDD evidence gaps, security, docs impact, and graph sync status."),
         ];
     },
 };

package/dist/adapters/codex-adapter.js

@@ -19,6 +19,8 @@ This repository uses Speckit: Agile + TDD for agentic development.
 
 Rules:
 - Shape intent before implementation.
+- 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\`.
 - 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 +39,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. Preserve session context, include PRD, architecture, stories, ACs, TDD checklist, risks, and graph sync notes."),
+            prompt("tdd-run", "Execute the selected Speckit story using .speckit/context/current.md, .speckit/context/subagent-handoff.md, and red-green-refactor. Require speckit ready <story>, confirm ACs, 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, 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/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, 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, 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,9 @@ 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/context/current.md\` before implementation work.
+- Read \`.speckit/context/subagent-handoff.md\` before implementation work.
+- Run \`speckit ready <story>\` before code changes.
 - 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/context/current.md\` and \`.speckit/context/subagent-handoff.md\` before implementation work, require \`speckit ready <story>\`, confirm acceptance criteria, preserve session handoff, record red-green-refactor evidence, and use only robot-safe graph commands.
 `),
     };
 }

package/dist/adapters/tool-checks.js

@@ -2,7 +2,6 @@ import { spawnSync } from "node:child_process";
 const tools = [
     ["git", true, "Install Git and run Speckit inside a repository."],
     ["node", true, "Install Node.js 20 or newer."],
-    ["ck", false, "Recommended for ClaudeKit-style skills and workflows."],
     ["br", false, "Recommended beads CLI. Use bd only for older projects."],
     ["bd", false, "Legacy beads CLI fallback."],
     ["bv", false, "Recommended for Beads Viewer robot commands."],

package/dist/cli.js

@@ -1,12 +1,17 @@
 import { initCommand } from "./commands/init.js";
 import { doctorCommand } from "./commands/doctor.js";
+import { startCommand } from "./commands/start.js";
 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 { 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()) {
     const parsed = parseArgs(argv);
     try {
@@ -16,23 +21,34 @@ export async function main(argv = process.argv.slice(2), root = process.cwd()) {
                     root,
                     ide: value(parsed, "ide"),
                     force: has(parsed, "force"),
+                    enterprise: has(parsed, "enterprise"),
                 });
             case "doctor":
-                return doctorCommand({ root, json: has(parsed, "json") });
+                return doctorCommand({ root, json: has(parsed, "json"), deep: has(parsed, "deep") });
+            case "start":
+                return startCommand({ root, intent: requiredIntent(parsed) });
             case "shape":
                 return shapeCommand({ root, intent: requiredIntent(parsed) });
+            case "context":
+                return contextCommand({ root, target: requiredIntent(parsed) });
             case "quick":
                 return quickCommand({ root, intent: requiredIntent(parsed) });
             case "plan":
                 return planCommand({ root, intent: requiredIntent(parsed) });
+            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":
                 return reviewCommand({ root });
+            case "close":
+                return closeCommand({ root, target: requiredIntent(parsed) });
             case "help":
             case "":
                 printHelp();
@@ -88,14 +104,20 @@ function printHelp() {
 
 Usage:
   speckit init [--ide all|claude-code|codex|antigravity|opencode|cursor] [--force]
-  speckit doctor [--json]
+  speckit init --enterprise [--ide all] [--force]
+  speckit doctor [--json] [--deep]
+  speckit start "<idea>"
   speckit shape "<intent>"
+  speckit context <story-path-or-id>
   speckit quick "<intent>"
   speckit plan "<intent>"
+  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>
 `);
 }
 if (import.meta.url === `file://${process.argv[1]}`) {

package/dist/commands/close.d.ts

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

package/dist/commands/close.js

@@ -0,0 +1,34 @@
+import { markdown, writeManagedFiles } from "../core/managed-files.js";
+import { slugify, timestamp } from "../core/slug.js";
+import { resolveStory } from "../core/story.js";
+export async function closeCommand(options) {
+    const stdout = options.stdout ?? console;
+    const story = await resolveStory(options.root, options.target);
+    if (!story) {
+        stdout.error(`Story not found: ${options.target}`);
+        return 1;
+    }
+    const closePath = `.speckit/closures/${timestamp()}-${slugify(story.id)}.md`;
+    await writeManagedFiles(options.root, [
+        {
+            path: closePath,
+            content: markdown(`# Spec Close: ${story.title}
+
+## Story
+\`${story.path}\`
+
+## Required Verification
+- [ ] Acceptance criteria reviewed
+- [ ] TDD evidence reviewed
+- [ ] Tests passed
+- [ ] Docs impact recorded
+- [ ] Graph sync completed with \`speckit sync\`
+
+## Review Command
+\`speckit review\`
+`),
+        },
+    ]);
+    stdout.log(closePath);
+    return 0;
+}

package/dist/commands/context.d.ts

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

package/dist/commands/context.js

@@ -0,0 +1,87 @@
+import { markdown, writeManagedFiles } from "../core/managed-files.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);
+    if (!story) {
+        stdout.error(`Story not found: ${options.target}`);
+        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(`---
+status: fresh
+story: ${story.path}
+evidence: ${evidenceReference ?? "missing"}
+---
+
+# Current Spec Context
+
+## Story
+${story.title}
+
+## Story Path
+\`${story.path}\`
+
+## Story Status
+${story.status ?? "missing"}
+
+## Acceptance Criteria
+${acceptanceCriteria}
+
+## TDD Evidence
+${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;
+}

package/dist/commands/doctor.d.ts

@@ -1,6 +1,7 @@
 export type DoctorOptions = {
     root: string;
     json?: boolean;
+    deep?: boolean;
     stdout?: Pick<typeof console, "log">;
 };
 export declare function doctorCommand(options: DoctorOptions): Promise<number>;

package/dist/commands/doctor.js

@@ -3,10 +3,12 @@ import { join } from "node:path";
 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";
 export async function doctorCommand(options) {
     const stdout = options.stdout ?? console;
     const tools = checkTools();
     const tests = await detectTestCommands(options.root);
+    const deepChecks = options.deep ? await runDeepChecks(options.root) : [];
     const adapters = await Promise.all(getAdapters("all").map(async (adapter) => ({
         name: adapter.name,
         ...(await adapterStatus(options.root, adapter.outputPaths)),
@@ -15,8 +17,9 @@ export async function doctorCommand(options) {
         node: process.versions.node,
         tools,
         tests,
+        deepChecks,
         adapters,
-        status: tools.filter((tool) => tool.required && !tool.available).length === 0 ? "ok" : "needs-attention",
+        status: statusFor(tools, deepChecks),
     };
     if (options.json) {
         stdout.log(JSON.stringify(report, null, 2));
@@ -26,12 +29,37 @@ export async function doctorCommand(options) {
         stdout.log(`Node: ${report.node}`);
         stdout.log(`Tools: ${tools.map((tool) => `${tool.name}=${tool.available ? "ok" : "missing"}`).join(", ")}`);
         stdout.log(`Tests: ${tests[0]?.command ?? "not detected"}`);
+        for (const check of deepChecks) {
+            stdout.log(`Deep ${check.name}: ${check.ok ? "ok" : "missing"}`);
+        }
         for (const adapter of adapters) {
             stdout.log(`Adapter ${adapter.name}: ${adapter.present}/${adapter.total} files present`);
         }
     }
     return report.status === "ok" ? 0 : 1;
 }
+async function runDeepChecks(root) {
+    const requiredFiles = [...coreFiles(), ...enterpriseFiles()];
+    return Promise.all(requiredFiles.map(async (file) => ({
+        name: file.path,
+        path: file.path,
+        ok: await fileExists(root, file.path),
+    })));
+}
+async function fileExists(root, path) {
+    try {
+        await access(join(root, path));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function statusFor(tools, deepChecks) {
+    const requiredToolsMissing = tools.some((tool) => tool.required && !tool.available);
+    const deepChecksMissing = deepChecks.some((check) => !check.ok);
+    return requiredToolsMissing || deepChecksMissing ? "needs-attention" : "ok";
+}
 async function adapterStatus(root, paths) {
     const missing = [];
     for (const path of paths) {

package/dist/commands/init.d.ts

@@ -2,6 +2,7 @@ export type InitOptions = {
     root: string;
     ide?: string;
     force?: boolean;
+    enterprise?: boolean;
     stdout?: Pick<typeof console, "log">;
 };
 export declare function initCommand(options: InitOptions): Promise<number>;

package/dist/commands/init.js

@@ -1,15 +1,17 @@
-import { coreFiles } from "../core/scaffold.js";
+import { coreFiles, enterpriseFiles } from "../core/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 adapterFiles = getAdapters(selectedIde).flatMap((adapter) => adapter.render());
-    const results = await writeManagedFiles(options.root, [...coreFiles(), ...adapterFiles], options.force ?? false);
+    const results = await writeManagedFiles(options.root, [...baseFiles, ...adapterFiles], options.force ?? false);
     const created = results.filter((result) => result.status === "created").length;
     const updated = results.filter((result) => result.status === "updated").length;
     const skipped = results.filter((result) => result.status === "skipped");
-    stdout.log(`Speckit initialized: ${created} created, ${updated} updated, ${skipped.length} skipped.`);
+    const mode = options.enterprise ? "enterprise" : "standard";
+    stdout.log(`Speckit initialized (${mode}): ${created} created, ${updated} updated, ${skipped.length} skipped.`);
     for (const result of skipped) {
         stdout.log(`skipped ${result.path}: ${result.reason}`);
     }

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;
+}