@trieungoctam/speckit 0.1.0

package/README.md

@@ -0,0 +1,71 @@
+# Speckit
+
+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.
+
+## Quickstart
+
+```bash
+npx @trieungoctam/speckit@latest init --ide all
+npx @trieungoctam/speckit@latest quick "Add checkout validation"
+npx @trieungoctam/speckit@latest review
+```
+
+Or install globally:
+
+```bash
+npm i -g @trieungoctam/speckit
+speckit init --ide cursor
+speckit doctor
+```
+
+## Core Flow
+
+```text
+intent
+  -> shape
+  -> plan
+  -> story with acceptance criteria
+  -> red test evidence
+  -> minimal implementation
+  -> green test evidence
+  -> refactor validation
+  -> review
+```
+
+For implementation stories, red-green-refactor evidence is mandatory. A story is not review-ready until the evidence file records test intent, red result, green result, and refactor validation.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `speckit init` | Create `.speckit/` core rules and all IDE adapters. |
+| `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 shape "<intent>"` | Create a short spec contract. |
+| `speckit quick "<intent>"` | Create one story plus matching TDD evidence file. |
+| `speckit plan "<intent>"` | Create PRD, architecture, story, and evidence skeletons. |
+| `speckit next` | Safely wraps `bv --robot-next --format json`. |
+| `speckit sync` | Export Speckit stories as beads-compatible JSONL metadata. |
+| `speckit run <story>` | Print the TDD execution handoff for a story. |
+| `speckit review` | Print the review checklist and current diff summary. |
+
+## Supported IDEs
+
+Speckit generates native instruction/config files for:
+
+- Claude Code
+- Codex
+- Antigravity
+- OpenCode
+- Cursor
+
+See `docs/adapters.md` for exact output paths.
+
+## Validation
+
+```bash
+npm run build
+npm test
+```

package/bin/speckit

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from "../dist/cli.js";
+
+process.exitCode = await main();

package/dist/adapters/antigravity-adapter.d.ts

@@ -0,0 +1,2 @@
+import { IdeAdapter } from "./ide-adapter.js";
+export declare const antigravityAdapter: IdeAdapter;

package/dist/adapters/antigravity-adapter.js

@@ -0,0 +1,41 @@
+import { markdown } from "../core/managed-files.js";
+export const antigravityAdapter = {
+    name: "antigravity",
+    displayName: "Antigravity",
+    outputPaths: [
+        ".agents/rules/speckit-agile.md",
+        ".agents/rules/speckit-tdd.md",
+        ".agents/rules/speckit-enterprise-safety.md",
+        ".agents/workflows/speckit-plan.md",
+        ".agents/workflows/speckit-tdd-run.md",
+        ".agents/workflows/speckit-review.md",
+    ],
+    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("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."),
+        ];
+    },
+};
+function rule(name, body) {
+    return {
+        path: `.agents/rules/speckit-${name}.md`,
+        content: markdown(`# Speckit ${name}
+
+${body}
+`),
+    };
+}
+function workflow(name, body) {
+    return {
+        path: `.agents/workflows/speckit-${name}.md`,
+        content: markdown(`# /speckit-${name}
+
+${body}
+`),
+    };
+}

package/dist/adapters/claude-code-adapter.d.ts

@@ -0,0 +1,2 @@
+import { IdeAdapter } from "./ide-adapter.js";
+export declare const claudeCodeAdapter: IdeAdapter;

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

@@ -0,0 +1,57 @@
+import { json, markdown } from "../core/managed-files.js";
+const skillIntro = `Follow Speckit: Agile story flow plus mandatory TDD evidence. Use project-local context first.`;
+export const claudeCodeAdapter = {
+    name: "claude-code",
+    displayName: "Claude Code",
+    outputPaths: [
+        "CLAUDE.md",
+        ".claude/settings.json",
+        ".claude/skills/speckit-plan/SKILL.md",
+        ".claude/skills/speckit-tdd/SKILL.md",
+        ".claude/skills/speckit-review/SKILL.md",
+    ],
+    render() {
+        return [
+            {
+                path: "CLAUDE.md",
+                content: markdown(`# Speckit Project Instructions
+
+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.
+`),
+            },
+            {
+                path: ".claude/settings.json",
+                content: json({
+                    permissions: {
+                        defaultMode: "ask",
+                    },
+                    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."),
+        ];
+    },
+};
+function skill(name, description, body) {
+    return {
+        path: `.claude/skills/${name}/SKILL.md`,
+        content: markdown(`---
+name: ${name}
+description: "${description}"
+---
+
+# ${name}
+
+${skillIntro}
+
+${body}
+`),
+    };
+}

package/dist/adapters/codex-adapter.d.ts

@@ -0,0 +1,2 @@
+import { IdeAdapter } from "./ide-adapter.js";
+export declare const codexAdapter: IdeAdapter;

package/dist/adapters/codex-adapter.js

@@ -0,0 +1,54 @@
+import { markdown, text } from "../core/managed-files.js";
+export const codexAdapter = {
+    name: "codex",
+    displayName: "Codex",
+    outputPaths: [
+        "AGENTS.md",
+        ".codex/config.toml",
+        ".speckit/codex-prompts/plan.md",
+        ".speckit/codex-prompts/tdd-run.md",
+        ".speckit/codex-prompts/review.md",
+    ],
+    render() {
+        return [
+            {
+                path: "AGENTS.md",
+                content: markdown(`# Speckit Agent Instructions
+
+This repository uses Speckit: Agile + TDD for agentic development.
+
+Rules:
+- Shape intent before implementation.
+- 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.
+- Keep changes scoped to the story and update docs when behavior changes.
+`),
+            },
+            {
+                path: ".codex/config.toml",
+                content: text(`model = "gpt-5.4"
+approval_policy = "on-request"
+sandbox_mode = "workspace-write"
+
+[tools]
+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."),
+        ];
+    },
+};
+function prompt(name, body) {
+    return {
+        path: `.speckit/codex-prompts/${name}.md`,
+        content: markdown(`# Codex Prompt: ${name}
+
+${body}
+`),
+    };
+}

package/dist/adapters/cursor-adapter.d.ts

@@ -0,0 +1,2 @@
+import { IdeAdapter } from "./ide-adapter.js";
+export declare const cursorAdapter: IdeAdapter;

package/dist/adapters/cursor-adapter.js

@@ -0,0 +1,51 @@
+import { json, markdown } from "../core/managed-files.js";
+export const cursorAdapter = {
+    name: "cursor",
+    displayName: "Cursor",
+    outputPaths: [
+        ".cursor/rules/speckit-agile.mdc",
+        ".cursor/rules/speckit-tdd.mdc",
+        ".cursor/rules/speckit-review.mdc",
+        ".cursor/rules/speckit-enterprise-safety.mdc",
+        ".cursor/mcp.json",
+        "AGENTS.md",
+    ],
+    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("enterprise-safety", "alwaysApply: true", "Do not expose secrets. Ask before destructive commands, deployment, or production changes."),
+            {
+                path: ".cursor/mcp.json",
+                content: json({
+                    mcpServers: {},
+                }),
+            },
+            {
+                path: "AGENTS.md",
+                content: markdown(`# Speckit Agent Instructions
+
+Use Speckit for Agile + TDD work. Cursor-specific rules live in \`.cursor/rules/*.mdc\`; this file is the cross-tool fallback.
+
+- Follow \`.speckit/rules/agile-policy.md\`.
+- Follow \`.speckit/rules/tdd-policy.md\` for code stories.
+- Never run bare \`bv\`; use robot commands only.
+`),
+            },
+        ];
+    },
+};
+function rule(name, frontmatter, body) {
+    return {
+        path: `.cursor/rules/speckit-${name}.mdc`,
+        content: markdown(`---
+${frontmatter}
+---
+
+# Speckit ${name}
+
+${body}
+`),
+    };
+}

package/dist/adapters/ide-adapter.d.ts

@@ -0,0 +1,7 @@
+import { ManagedFile } from "../core/managed-files.js";
+export type IdeAdapter = {
+    name: "claude-code" | "codex" | "antigravity" | "opencode" | "cursor";
+    displayName: string;
+    outputPaths: string[];
+    render(): ManagedFile[];
+};

package/dist/adapters/ide-adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/adapters/opencode-adapter.d.ts

@@ -0,0 +1,2 @@
+import { IdeAdapter } from "./ide-adapter.js";
+export declare const opencodeAdapter: IdeAdapter;

package/dist/adapters/opencode-adapter.js

@@ -0,0 +1,58 @@
+import { json, markdown } from "../core/managed-files.js";
+export const opencodeAdapter = {
+    name: "opencode",
+    displayName: "OpenCode",
+    outputPaths: [
+        "opencode.json",
+        ".opencode/agent/speckit-planner.md",
+        ".opencode/agent/speckit-tdd-developer.md",
+        ".opencode/agent/speckit-reviewer.md",
+        ".opencode/agent/speckit-docs.md",
+    ],
+    render() {
+        return [
+            {
+                path: "opencode.json",
+                content: json({
+                    $schema: "https://opencode.ai/config.json",
+                    instructions: ["AGENTS.md", ".speckit/rules/*.md"],
+                    permission: {
+                        edit: "ask",
+                        bash: "ask",
+                    },
+                }),
+            },
+            agent("planner", "Plan Speckit Agile work without editing files.", "primary", {
+                edit: "deny",
+                bash: { "*": "ask", "git status*": "allow", "git diff*": "allow" },
+            }),
+            agent("tdd-developer", "Implement Speckit stories with TDD evidence.", "primary", {
+                edit: "ask",
+                bash: "ask",
+            }),
+            agent("reviewer", "Review changes without editing files.", "subagent", {
+                edit: "deny",
+                bash: { "*": "ask", "git diff*": "allow", "git log*": "allow", "npm test*": "allow" },
+            }),
+            agent("docs", "Update Speckit docs after approved changes.", "subagent", {
+                edit: "ask",
+                bash: "deny",
+            }),
+        ];
+    },
+};
+function agent(name, description, mode, permission) {
+    return {
+        path: `.opencode/agent/speckit-${name}.md`,
+        content: markdown(`---
+description: "${description}"
+mode: ${mode}
+permission: ${JSON.stringify(permission)}
+---
+
+# speckit-${name}
+
+Follow \`.speckit/rules/agile-policy.md\`, \`.speckit/rules/tdd-policy.md\`, and \`.speckit/rules/enterprise-safety.md\`.
+`),
+    };
+}

package/dist/adapters/tool-checks.d.ts

@@ -0,0 +1,8 @@
+export type ToolCheck = {
+    name: string;
+    required: boolean;
+    available: boolean;
+    hint: string;
+};
+export declare function checkTools(): ToolCheck[];
+export declare function commandExists(command: string): boolean;

package/dist/adapters/tool-checks.js

@@ -0,0 +1,28 @@
+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."],
+    ["claude", false, "Claude Code adapter runtime."],
+    ["codex", false, "Codex adapter runtime."],
+    ["opencode", false, "OpenCode adapter runtime."],
+    ["cursor", false, "Cursor adapter runtime."],
+];
+export function checkTools() {
+    return tools.map(([name, required, hint]) => ({
+        name,
+        required,
+        available: commandExists(name),
+        hint,
+    }));
+}
+export function commandExists(command) {
+    const result = spawnSync(command, ["--version"], {
+        encoding: "utf8",
+        stdio: "ignore",
+    });
+    return result.status === 0;
+}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[], root?: string): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,104 @@
+import { initCommand } from "./commands/init.js";
+import { doctorCommand } from "./commands/doctor.js";
+import { shapeCommand } from "./commands/shape.js";
+import { quickCommand } from "./commands/quick.js";
+import { planCommand } from "./commands/plan.js";
+import { nextCommand } from "./commands/next.js";
+import { syncCommand } from "./commands/sync.js";
+import { runCommand } from "./commands/run.js";
+import { reviewCommand } from "./commands/review.js";
+export async function main(argv = process.argv.slice(2), root = process.cwd()) {
+    const parsed = parseArgs(argv);
+    try {
+        switch (parsed.command) {
+            case "init":
+                return initCommand({
+                    root,
+                    ide: value(parsed, "ide"),
+                    force: has(parsed, "force"),
+                });
+            case "doctor":
+                return doctorCommand({ root, json: has(parsed, "json") });
+            case "shape":
+                return shapeCommand({ root, intent: requiredIntent(parsed) });
+            case "quick":
+                return quickCommand({ root, intent: requiredIntent(parsed) });
+            case "plan":
+                return planCommand({ root, intent: requiredIntent(parsed) });
+            case "next":
+                return nextCommand();
+            case "sync":
+                return syncCommand({ root });
+            case "run":
+                return runCommand({ root, target: requiredIntent(parsed) });
+            case "review":
+                return reviewCommand({ root });
+            case "help":
+            case "":
+                printHelp();
+                return 0;
+            default:
+                console.error(`Unknown command: ${parsed.command}`);
+                printHelp();
+                return 1;
+        }
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}
+function parseArgs(argv) {
+    const [command = "", ...rest] = argv;
+    const args = [];
+    const flags = new Map();
+    for (let index = 0; index < rest.length; index += 1) {
+        const token = rest[index];
+        if (!token.startsWith("--")) {
+            args.push(token);
+            continue;
+        }
+        const name = token.slice(2);
+        const next = rest[index + 1];
+        if (next && !next.startsWith("--")) {
+            flags.set(name, next);
+            index += 1;
+        }
+        else {
+            flags.set(name, true);
+        }
+    }
+    return { command, args, flags };
+}
+function requiredIntent(parsed) {
+    const intent = parsed.args.join(" ").trim();
+    if (!intent)
+        throw new Error(`Command "${parsed.command}" requires a target or intent.`);
+    return intent;
+}
+function value(parsed, name) {
+    const found = parsed.flags.get(name);
+    return typeof found === "string" ? found : undefined;
+}
+function has(parsed, name) {
+    return parsed.flags.has(name);
+}
+function printHelp() {
+    console.log(`Speckit - Agile + TDD workflow compiler for agentic IDEs
+
+Usage:
+  speckit init [--ide all|claude-code|codex|antigravity|opencode|cursor] [--force]
+  speckit doctor [--json]
+  speckit shape "<intent>"
+  speckit quick "<intent>"
+  speckit plan "<intent>"
+  speckit next
+  speckit sync
+  speckit run <story-path-or-id>
+  speckit review
+`);
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    const exitCode = await main();
+    process.exitCode = exitCode;
+}

package/dist/commands/doctor.d.ts

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

package/dist/commands/doctor.js

@@ -0,0 +1,50 @@
+import { access } from "node:fs/promises";
+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";
+export async function doctorCommand(options) {
+    const stdout = options.stdout ?? console;
+    const tools = checkTools();
+    const tests = await detectTestCommands(options.root);
+    const adapters = await Promise.all(getAdapters("all").map(async (adapter) => ({
+        name: adapter.name,
+        ...(await adapterStatus(options.root, adapter.outputPaths)),
+    })));
+    const report = {
+        node: process.versions.node,
+        tools,
+        tests,
+        adapters,
+        status: tools.filter((tool) => tool.required && !tool.available).length === 0 ? "ok" : "needs-attention",
+    };
+    if (options.json) {
+        stdout.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        stdout.log(`Speckit doctor: ${report.status}`);
+        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 adapter of adapters) {
+            stdout.log(`Adapter ${adapter.name}: ${adapter.present}/${adapter.total} files present`);
+        }
+    }
+    return report.status === "ok" ? 0 : 1;
+}
+async function adapterStatus(root, paths) {
+    const missing = [];
+    for (const path of paths) {
+        try {
+            await access(join(root, path));
+        }
+        catch {
+            missing.push(path);
+        }
+    }
+    return {
+        present: paths.length - missing.length,
+        total: paths.length,
+        missing,
+    };
+}

package/dist/commands/init.d.ts

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

package/dist/commands/init.js

@@ -0,0 +1,17 @@
+import { coreFiles } 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 adapterFiles = getAdapters(selectedIde).flatMap((adapter) => adapter.render());
+    const results = await writeManagedFiles(options.root, [...coreFiles(), ...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.`);
+    for (const result of skipped) {
+        stdout.log(`skipped ${result.path}: ${result.reason}`);
+    }
+    return skipped.length > 0 ? 2 : 0;
+}

package/dist/commands/next.d.ts

@@ -0,0 +1,4 @@
+export type NextOptions = {
+    stdout?: Pick<typeof console, "log" | "error">;
+};
+export declare function nextCommand(options?: NextOptions): Promise<number>;

package/dist/commands/next.js

@@ -0,0 +1,17 @@
+import { spawnSync } from "node:child_process";
+import { commandExists } from "../adapters/tool-checks.js";
+export async function nextCommand(options = {}) {
+    const stdout = options.stdout ?? console;
+    if (!commandExists("bv")) {
+        stdout.error("bv is not installed. Install Beads Viewer, then run: bv --robot-next --format json");
+        return 1;
+    }
+    const result = spawnSync("bv", ["--robot-next", "--format", "json"], {
+        encoding: "utf8",
+    });
+    if (result.stdout)
+        stdout.log(result.stdout.trim());
+    if (result.stderr)
+        stdout.error(result.stderr.trim());
+    return result.status ?? 1;
+}

package/dist/commands/plan.d.ts

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