@trieungoctam/speckit 0.2.0 → 0.2.2

package/README.md

@@ -10,6 +10,9 @@ Speckit owns the workflow contract and generates adapters for the tools you alre
 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
 ```
 
@@ -31,6 +34,7 @@ intent
   -> context
   -> story with acceptance criteria
   -> sync / triage
+  -> readiness gate
   -> red test evidence
   -> minimal implementation
   -> green test evidence
@@ -57,6 +61,7 @@ For implementation stories, red-green-refactor evidence is mandatory. A story is
 | `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. |

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/cli.js

@@ -9,6 +9,7 @@ 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()) {
@@ -40,6 +41,8 @@ export async function main(argv = process.argv.slice(2), root = process.cwd()) {
                 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":
@@ -111,6 +114,7 @@ Usage:
   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/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.

package/dist/commands/sync.js

@@ -1,7 +1,7 @@
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { markdown, writeManagedFiles } from "../core/managed-files.js";
-import { firstHeading } from "../core/story.js";
+import { firstHeading, frontmatterValue } from "../core/story.js";
 export async function syncCommand(options) {
     const stdout = options.stdout ?? console;
     const storiesDir = join(options.root, ".speckit", "stories");
@@ -20,7 +20,7 @@ export async function syncCommand(options) {
             id: entry.replace(/\.md$/, ""),
             path: `.speckit/stories/${entry}`,
             title: firstHeading(content) ?? entry.replace(/\.md$/, ""),
-            status: content.includes("- [ ]") ? "open" : "ready-for-review",
+            status: frontmatterValue(content, "status") ?? (content.includes("- [ ]") ? "open" : "ready-for-review"),
         });
     }
     const jsonl = stories.map((story) => JSON.stringify(story)).join("\n");

package/dist/commands/triage.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 export async function triageCommand(options) {
     const stdout = options.stdout ?? console;
     const stories = await readSyncedStories(options.root);
-    const open = stories.filter((story) => story.status === "open");
+    const open = stories.filter((story) => ["open", "ready-for-dev", "in-progress"].includes(story.status));
     const ready = stories.filter((story) => story.status !== "open");
     const report = {
         source: ".speckit/sync/beads-sync.jsonl",

package/dist/core/readiness.d.ts

@@ -0,0 +1,13 @@
+import { StoryResolution } from "./story.js";
+export type ReadinessCheck = {
+    name: string;
+    ok: boolean;
+    detail: string;
+};
+export type ReadinessReport = {
+    story?: Pick<StoryResolution, "id" | "path" | "title" | "status" | "evidencePath">;
+    checks: ReadinessCheck[];
+    status: "ready" | "blocked";
+};
+export declare function evaluateReadiness(root: string, target: string): Promise<ReadinessReport>;
+export declare function evidenceStatus(root: string, evidencePath: string | undefined): Promise<string | undefined>;

package/dist/core/readiness.js

@@ -0,0 +1,120 @@
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { extractSection, frontmatterValue, resolveStory } from "./story.js";
+export async function evaluateReadiness(root, target) {
+    const story = await resolveStory(root, target);
+    if (!story) {
+        return {
+            checks: [{ name: "story", ok: false, detail: `Story not found: ${target}` }],
+            status: "blocked",
+        };
+    }
+    const evidencePath = story.evidencePath;
+    const checks = [
+        {
+            name: "story-status",
+            ok: story.status === "ready-for-dev",
+            detail: story.status ? `status=${story.status}` : "status missing",
+        },
+        {
+            name: "acceptance-criteria",
+            ok: hasActionableAcceptanceCriteria(story.content),
+            detail: "story has testable acceptance criteria",
+        },
+        {
+            name: "evidence-link",
+            ok: Boolean(evidencePath),
+            detail: evidencePath ?? "missing TDD evidence reference",
+        },
+        {
+            name: "evidence-file",
+            ok: evidencePath ? await fileExists(root, evidencePath) : false,
+            detail: evidencePath ?? "missing TDD evidence reference",
+        },
+        {
+            name: "context",
+            ok: await contextIsFreshForStory(root, story.path),
+            detail: ".speckit/context/current.md links this story and is fresh",
+        },
+        {
+            name: "graph-sync",
+            ok: await graphContainsStory(root, story.path),
+            detail: ".speckit/sync/beads-sync.jsonl contains this story",
+        },
+        {
+            name: "tool-policy",
+            ok: await fileExists(root, ".speckit/tool-policy.yaml"),
+            detail: ".speckit/tool-policy.yaml",
+        },
+        {
+            name: "safety-policy",
+            ok: await fileExists(root, ".speckit/rules/enterprise-safety.md"),
+            detail: ".speckit/rules/enterprise-safety.md",
+        },
+    ];
+    return {
+        story: {
+            id: story.id,
+            path: story.path,
+            title: story.title,
+            status: story.status,
+            evidencePath,
+        },
+        checks,
+        status: checks.every((check) => check.ok) ? "ready" : "blocked",
+    };
+}
+function hasActionableAcceptanceCriteria(content) {
+    const criteria = extractSection(content, "Acceptance Criteria");
+    if (!criteria)
+        return false;
+    return /Given .+|When .+|Then .+|\d+\./i.test(criteria) && !criteria.includes("...");
+}
+async function contextIsFreshForStory(root, storyPath) {
+    try {
+        const content = await readFile(join(root, ".speckit", "context", "current.md"), "utf8");
+        return content.includes("status: fresh") && content.includes(storyPath);
+    }
+    catch {
+        return false;
+    }
+}
+async function graphContainsStory(root, storyPath) {
+    try {
+        const content = await readFile(join(root, ".speckit", "sync", "beads-sync.jsonl"), "utf8");
+        return content
+            .split("\n")
+            .filter(Boolean)
+            .some((line) => {
+            try {
+                return JSON.parse(line).path === storyPath;
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    catch {
+        return false;
+    }
+}
+async function fileExists(root, path) {
+    try {
+        await access(join(root, path));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function evidenceStatus(root, evidencePath) {
+    if (!evidencePath)
+        return undefined;
+    try {
+        const content = await readFile(join(root, evidencePath), "utf8");
+        return frontmatterValue(content, "status");
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/core/scaffold.js

@@ -27,7 +27,13 @@ adapters:
         { path: ".speckit/workflows/review.md", content: markdown(workflowReview) },
         {
             path: ".speckit/templates/story.md",
-            content: markdown(`# Story: {{title}}
+            content: markdown(`---
+status: draft
+evidence: .speckit/evidence/{{slug}}-tdd-evidence.md
+context: pending
+---
+
+# Story: {{title}}
 
 ## Intent
 {{intent}}
@@ -46,11 +52,23 @@ adapters:
 ## Notes
 - Risks:
 - Dependencies:
+
+## 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.
+- Capture previous-story learnings if this continues prior work.
 `),
         },
         {
             path: ".speckit/templates/tdd-evidence.md",
-            content: markdown(`# TDD Evidence: {{story}}
+            content: markdown(`---
+status: missing
+story: {{story}}
+---
+
+# TDD Evidence: {{story}}
 
 ## Test Intent
 
@@ -105,12 +123,53 @@ graph:
             path: ".speckit/prompts/spec-run.md",
             content: markdown(`# Spec Run Prompt
 
-1. Read \`.speckit/context/current.md\`.
-2. Confirm story acceptance criteria.
-3. Write or run the failing test first.
-4. Implement the smallest change.
-5. Record red, green, and refactor evidence.
-6. Run \`speckit review\` before handoff.
+## Required Inputs
+
+- Current context: \`.speckit/context/current.md\`
+- Subagent handoff: \`.speckit/context/subagent-handoff.md\`
+- Story with acceptance criteria
+- Matching TDD evidence file
+- Tool policy: \`.speckit/tool-policy.yaml\`
+
+## Status Preconditions
+
+- Story status is \`ready-for-dev\`.
+- Context status is \`fresh\`.
+- \`speckit ready <story>\` returns ready.
+
+## Allowed Edits
+
+- Implementation files needed for the story.
+- Matching tests.
+- Linked TDD evidence file.
+- Story completion checkboxes and implementation notes.
+
+## Execution Contract
+
+Use the red-green-refactor loop.
+
+1. Read the current context before touching code.
+2. Confirm the story path, acceptance criteria, and evidence path.
+3. Write or run the smallest failing test first.
+4. Record red evidence before implementation.
+5. Implement the smallest change that satisfies the failing test.
+6. Record green evidence after tests pass.
+7. Refactor only while tests stay green, then record validation.
+8. Use graph commands only through robot-safe flags such as \`bv --robot-next --format json\`.
+9. Run \`speckit review\` before handoff.
+
+## Stop Conditions
+
+- Stop if acceptance criteria are missing.
+- Stop if the evidence file cannot be identified.
+- Stop if \`speckit ready <story>\` reports blocked.
+- Stop before destructive commands, production changes, or secret access.
+
+## Completion Signal
+
+- All acceptance criteria satisfied.
+- TDD evidence status can be advanced through red, green, and refactor.
+- Review handoff is ready.
 `),
         },
     ];

package/dist/core/story.d.ts

@@ -3,6 +3,11 @@ export type StoryResolution = {
     content: string;
     id: string;
     title: string;
+    status?: string;
+    evidencePath?: string;
 };
 export declare function resolveStory(root: string, target: string): Promise<StoryResolution | undefined>;
+export declare function frontmatterValue(content: string, key: string): string | undefined;
+export declare function extractEvidenceReference(content: string): string | undefined;
+export declare function extractSection(content: string, heading: string): string | undefined;
 export declare function firstHeading(content: string): string | undefined;

package/dist/core/story.js

@@ -16,6 +16,8 @@ export async function resolveStory(root, target) {
                 content,
                 id: basename(candidate).replace(/\.md$/, ""),
                 title: firstHeading(content) ?? basename(candidate).replace(/\.md$/, ""),
+                status: frontmatterValue(content, "status"),
+                evidencePath: frontmatterValue(content, "evidence") ?? extractEvidenceReference(content),
             };
         }
         catch {
@@ -24,6 +26,38 @@ export async function resolveStory(root, target) {
     }
     return undefined;
 }
+export function frontmatterValue(content, key) {
+    const lines = content.split("\n");
+    const start = lines.findIndex((line) => line.trim() === "---");
+    if (start === -1)
+        return undefined;
+    const end = lines.findIndex((line, index) => index > start && line.trim() === "---");
+    if (end === -1)
+        return undefined;
+    const prefix = `${key}:`;
+    const found = lines
+        .slice(start + 1, end)
+        .find((line) => line.trim().toLowerCase().startsWith(prefix.toLowerCase()));
+    return found?.slice(found.indexOf(":") + 1).trim().replace(/^["']|["']$/g, "");
+}
+export function extractEvidenceReference(content) {
+    const match = content.match(/`([^`]*tdd-evidence\.md)`/i);
+    return match?.[1];
+}
+export 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;
+}
 export function firstHeading(content) {
     return content
         .split("\n")

package/docs/development-roadmap.md

@@ -4,9 +4,9 @@
 
 Speckit MVP is implemented and pushed to `git@github.com:trieungoctam/speckit.git` on `main`.
 
-Current package target: `@trieungoctam/speckit@0.1.0`.
+Current package target: `@trieungoctam/speckit@0.2.2`.
 
-The CLI is npx-ready, generates Agile + TDD rules, creates workflow artifacts, supports five IDE adapters, wraps Beads Viewer safely, includes an enterprise harness, and has automated tests plus CI.
+The CLI is npx-ready, generates Agile + TDD rules, creates workflow artifacts, supports five IDE adapters, wraps Beads Viewer safely, includes an enterprise harness, and has automated prompt/readiness tests plus CI.
 
 ## Milestones
 
@@ -14,7 +14,7 @@ The CLI is npx-ready, generates Agile + TDD rules, creates workflow artifacts, s
 | --- | --- | --- |
 | Product contract | Complete | Contract, workflow model, and command surface documented. |
 | CLI scaffold | Complete | `bin/speckit`, TypeScript build, command router, managed file writer. |
-| Workflow engine | Complete | `start`, `shape`, `plan`, `context`, `quick`, `sync`, `triage`, `run`, `review`, and `close` generate linked artifacts. |
+| Workflow engine | Complete | `start`, `shape`, `plan`, `context`, `quick`, `sync`, `triage`, `ready`, `run`, `review`, and `close` generate linked artifacts. |
 | IDE adapters | Complete | Claude Code, Codex, Antigravity, OpenCode, Cursor. |
 | Beads integration | MVP Complete | `next` wraps BV robot mode; `sync` exports story metadata JSONL. |
 | Enterprise harness | MVP Complete | `init --enterprise` creates flow, tool-policy, and prompt harness files; `doctor --deep` verifies them. |
@@ -24,8 +24,8 @@ The CLI is npx-ready, generates Agile + TDD rules, creates workflow artifacts, s
 
 ## Next Roadmap
 
-- Release Speckit-only vocabulary cleanup as `0.1.1` or fold it into `0.2.0`.
 - Expand Speckit Enterprise Harness with richer profile and context-pack layers.
+- Add `review --deep` with blind, edge-case, and acceptance audit prompts.
 - Add graph commands: `graph-plan`, `insights`, and `drift`.
 - Add GitHub trusted publishing for npm releases.
 - Add snapshot tests for full adapter file contents.

package/docs/product-contract.md

@@ -5,7 +5,7 @@ Speckit owns the workflow contract for enterprise Agile + TDD development with a
 ## Speckit Owns
 
 - The `.speckit/` source of truth: config, rules, workflows, templates, generated artifacts.
-- The command surface: `init`, `doctor`, `start`, `shape`, `plan`, `context`, `quick`, `sync`, `triage`, `next`, `run`, `review`, `close`.
+- The command surface: `init`, `doctor`, `start`, `shape`, `plan`, `context`, `quick`, `sync`, `triage`, `next`, `ready`, `run`, `review`, `close`.
 - The TDD gate: code stories require red, green, and refactor evidence.
 - The adapter compiler for Claude Code, Codex, Antigravity, OpenCode, and Cursor.
 - The safety policy for destructive commands, secrets, production access, and review readiness.
@@ -21,7 +21,7 @@ Speckit owns the workflow contract for enterprise Agile + TDD development with a
 ## State Model
 
 ```text
-intake -> session -> shaped -> planned -> context-ready -> synced -> triaged -> tests-red -> running -> tests-green -> refactor -> review-ready -> closed
+intake -> session -> shaped -> planned -> context-ready -> synced -> triaged -> ready-for-dev -> tests-red -> running -> tests-green -> refactor -> review-ready -> closed
 ```
 
-Implementation starts only after a story is spec-ready. Review starts only after test evidence exists.
+Implementation starts only after `speckit ready <story>` passes. Review starts only after test evidence exists.

package/docs/project-changelog.md

@@ -1,5 +1,37 @@
 # Project Changelog
 
+## 0.2.2 - 2026-05-10
+
+### Added
+
+- Added `speckit ready <story>` readiness gate.
+- Added status frontmatter to generated stories, evidence files, and current context.
+- Added `.speckit/context/subagent-handoff.md` generation from story context.
+- Added anti-mistake checklist sections to story and context artifacts.
+
+### Changed
+
+- `speckit run <story>` now refuses blocked stories until readiness checks pass.
+- Prompt contracts now require readiness status, fresh context, and subagent handoff.
+
+### Quality
+
+- Added readiness and blocked-run tests.
+- Expanded prompt quality tests for readiness and subagent handoff.
+- `npm test` passes with 26 tests.
+
+## 0.2.1 - 2026-05-10
+
+### Changed
+
+- Strengthened generated prompts across Claude Code, Codex, Antigravity, OpenCode, Cursor, and the enterprise run prompt.
+- Made prompt contracts explicitly require current context, acceptance criteria, session handoff, red-green-refactor evidence, and robot-safe graph commands.
+
+### Quality
+
+- Added prompt quality tests covering enterprise prompts, IDE adapter prompts, and tracked generated prompt files.
+- `npm test` passes with 24 tests.
+
 ## 0.2.0 - 2026-05-10
 
 ### Added
@@ -16,6 +48,10 @@
 - `npm pack --dry-run` passes.
 - Full enterprise temp flow passes: `init --enterprise -> start -> quick -> context -> sync -> triage -> close -> doctor --deep`.
 
+### Published
+
+- Published `@trieungoctam/speckit@0.2.0` to npm with `latest` dist-tag.
+
 ## 2026-05-10
 
 ### Changed

package/docs/release-checklist.md

@@ -16,5 +16,5 @@ Before publishing Speckit:
 - [x] README quickstart is accurate.
 - [x] No secrets, local credentials, or generated private data are included.
 - [x] Initial code pushed to `git@github.com:trieungoctam/speckit.git`.
-- [ ] npm package published.
+- [x] npm package published.
 - [ ] GitHub trusted publishing configured for npm releases.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trieungoctam/speckit",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Enterprise Agile + TDD workflow compiler for agentic IDEs.",
   "type": "module",
   "files": [