@trieungoctam/speckit 0.3.4 → 0.3.6

package/README.md

@@ -11,6 +11,7 @@ The curated skill set is intentionally small: `spec-shape`, `spec-research`, `sp
 ## Quickstart
 
 ```bash
+npx @trieungoctam/speckit@latest setup
 npx @trieungoctam/speckit@latest init --ide cursor
 npx @trieungoctam/speckit@latest init --ide all
 npx @trieungoctam/speckit@latest init --enterprise --ide all
@@ -19,6 +20,7 @@ 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 graph setup
 npx @trieungoctam/speckit@latest sprint plan
 npx @trieungoctam/speckit@latest graph triage --json
 npx @trieungoctam/speckit@latest validate --json
@@ -28,6 +30,8 @@ npx @trieungoctam/speckit@latest session checkpoint --note "red complete"
 npx @trieungoctam/speckit@latest review
 ```
 
+Interactive CLI output is colorized when the terminal supports ANSI colors. Use `NO_COLOR=1` to disable colors, or `SPECKIT_COLOR=1` to force colors for demos and snapshots.
+
 Or install globally:
 
 ```bash
@@ -66,6 +70,7 @@ For implementation stories, red-green-refactor evidence is mandatory. A story is
 
 | Command | Purpose |
 | --- | --- |
+| `speckit setup` | Open an interactive setup wizard for mode, IDE adapter, overwrite policy, and Beads Viewer setup. |
 | `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`. |
@@ -88,6 +93,7 @@ For implementation stories, red-green-refactor evidence is mandatory. A story is
 | `speckit next` | Safely wraps `bv --robot-next --format json`. |
 | `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 setup` | Print Beads Viewer install commands, check `br`/`bd`/`bv`, and prepare `.beads/beads.jsonl`. |
 | `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. |
@@ -112,6 +118,7 @@ See `docs/adapters.md` for exact output paths.
 ## Guides
 
 - `docs/use-cases.md` covers setup, migration, quick changes, full planning, long sessions, TDD, graph automation, review, CI, and troubleshooting.
+- `docs/beads-viewer-setup.md` covers Beads Viewer installation, `bv` verification, and robot-safe graph usage.
 - `docs/workflow-model.md` describes the quick and full workflow lanes.
 - `docs/prompt-architecture.md` describes the prompt contract used by the super-agent, skills, workflows, run prompt, and IDE adapters.
 - `docs/spec-quality-gates.md` describes validation gates for release readiness.

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

@@ -3,6 +3,8 @@ export type ToolCheck = {
     required: boolean;
     available: boolean;
     hint: string;
+    install?: string[];
 };
 export declare function checkTools(): ToolCheck[];
+export declare function beadsViewerInstallGuide(): string;
 export declare function commandExists(command: string): boolean;

package/dist/adapters/tool-checks.js

@@ -1,23 +1,50 @@
 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."],
-    ["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."],
+    ["git", true, "Install Git and run Speckit inside a repository.", ["https://git-scm.com/downloads"]],
+    ["node", true, "Install Node.js 20 or newer.", ["https://nodejs.org/"]],
+    ["br", false, "Recommended beads CLI. Use bd only for older projects.", ["Install beads_rust/br from your team's preferred channel."]],
+    ["bd", false, "Legacy beads CLI fallback.", ["brew install beads", "go install github.com/steveyegge/beads/cmd/bd@latest"]],
+    [
+        "bv",
+        false,
+        "Recommended for Beads Viewer robot commands.",
+        [
+            "brew install dicklesworthstone/tap/bv",
+            "go install github.com/Dicklesworthstone/beads_viewer/cmd/bv@latest",
+            "nix run github:Dicklesworthstone/beads_viewer -- --help",
+        ],
+    ],
+    ["claude", false, "Claude Code adapter runtime.", ["https://docs.anthropic.com/en/docs/claude-code"]],
+    ["codex", false, "Codex adapter runtime.", ["https://developers.openai.com/codex"]],
+    ["opencode", false, "OpenCode adapter runtime.", ["https://opencode.ai/"]],
+    ["cursor", false, "Cursor adapter runtime.", ["https://cursor.com/"]],
 ];
 export function checkTools() {
-    return tools.map(([name, required, hint]) => ({
+    return tools.map(([name, required, hint, install]) => ({
         name,
         required,
         available: commandExists(name),
         hint,
+        install: [...install],
     }));
 }
+export function beadsViewerInstallGuide() {
+    return `Beads Viewer setup
+
+Install bv with one of:
+  brew install dicklesworthstone/tap/bv
+  go install github.com/Dicklesworthstone/beads_viewer/cmd/bv@latest
+  nix run github:Dicklesworthstone/beads_viewer -- --help
+
+Verify:
+  bv --version
+  speckit sync
+  speckit graph triage --json
+
+Rules:
+  Never run bare bv from agents. Use Speckit wrappers or bv --robot-* flags.
+  Speckit writes .beads/beads.jsonl from .speckit stories before graph commands.`;
+}
 export function commandExists(command) {
     const result = spawnSync(command, ["--version"], {
         encoding: "utf8",

package/dist/cli.js

@@ -1,4 +1,5 @@
 import { initCommand } from "./commands/init.js";
+import { setupCommand } from "./commands/setup.js";
 import { doctorCommand } from "./commands/doctor.js";
 import { startCommand } from "./commands/start.js";
 import { shapeCommand } from "./commands/shape.js";
@@ -18,6 +19,7 @@ import { runCommand } from "./commands/run.js";
 import { readyCommand } from "./commands/ready.js";
 import { reviewCommand } from "./commands/review.js";
 import { closeCommand } from "./commands/close.js";
+import { createColors } from "./core/colors.js";
 export async function main(argv = process.argv.slice(2), root = process.cwd()) {
     const parsed = parseArgs(argv);
     try {
@@ -26,6 +28,8 @@ export async function main(argv = process.argv.slice(2), root = process.cwd()) {
             return 0;
         }
         switch (parsed.command) {
+            case "setup":
+                return setupCommand({ root });
             case "init":
                 return initCommand({
                     root,
@@ -142,9 +146,11 @@ function isHelp(parsed) {
     return parsed.command === "help" || parsed.command === "--help" || parsed.command === "-h" || has(parsed, "help");
 }
 function printHelp() {
-    console.log(`Speckit - Agile + TDD workflow compiler for agentic IDEs
+    const colors = createColors();
+    console.log(`${colors.bold(colors.cyan("Speckit"))} - Agile + TDD workflow compiler for agentic IDEs
 
 Usage:
+  speckit setup
   speckit init [--ide all|claude-code|codex|antigravity|opencode|cursor] [--force]
   speckit init --enterprise [--ide all] [--force]
   speckit doctor [--json] [--deep]
@@ -157,7 +163,7 @@ Usage:
   speckit permissions audit [--path <path>] [--command <command>] [--json]
   speckit session start|checkpoint|compact|resume|status [target] [--note "..."] [--json]
   speckit sprint plan|next [--json]
-  speckit graph triage|plan|insights [--json]
+  speckit graph setup|triage|plan|insights [--json]
   speckit validate [--json]
   speckit triage [--json]
   speckit next

package/dist/commands/doctor.js

@@ -6,8 +6,10 @@ import { detectTestCommands } from "../core/test-detection.js";
 import { coreFiles, enterpriseFiles } from "../core/scaffold.js";
 import { agentFiles } from "../core/agent-scaffold.js";
 import { validateWorkflowContract } from "../core/workflow-validator.js";
+import { createColors } from "../core/colors.js";
 export async function doctorCommand(options) {
     const stdout = options.stdout ?? console;
+    const colors = createColors();
     const tools = checkTools();
     const tests = await detectTestCommands(options.root);
     const deepChecks = options.deep ? await runDeepChecks(options.root) : [];
@@ -29,18 +31,25 @@ export async function doctorCommand(options) {
         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"}`);
+        stdout.log(`${colors.bold("Speckit doctor")}: ${colors.status(report.status === "ok", "ok", report.status)}`);
+        stdout.log(`${colors.bold("Node")}: ${report.node}`);
+        stdout.log(`Tools: ${tools.map((tool) => `${tool.name}=${colors.status(tool.available)}`).join(", ")}`);
+        for (const tool of tools.filter((tool) => !tool.available)) {
+            stdout.log(`${colors.yellow("Tool hint")} ${tool.name}: ${tool.hint}`);
+            if (tool.install?.length) {
+                stdout.log(`${colors.cyan(`Install ${tool.name}`)}: ${tool.install.join(" OR ")}`);
+            }
+        }
+        stdout.log(`${colors.bold("Tests")}: ${tests[0]?.command ?? colors.yellow("not detected")}`);
         for (const check of deepChecks) {
-            stdout.log(`Deep ${check.name}: ${check.ok ? "ok" : "missing"}`);
+            stdout.log(`Deep ${check.name}: ${colors.status(check.ok)}`);
         }
         for (const check of contractChecks) {
-            stdout.log(`Contract ${check.name}: ${check.ok ? "ok" : check.detail}`);
+            stdout.log(`Contract ${check.name}: ${check.ok ? colors.green("ok") : colors.red(check.detail)}`);
         }
         for (const adapter of adapters) {
-            stdout.log(`Adapter ${adapter.name}: ${adapter.present}/${adapter.total} files present`);
+            const ok = adapter.present === adapter.total;
+            stdout.log(`Adapter ${adapter.name}: ${colors.status(ok, `${adapter.present}/${adapter.total}`, `${adapter.present}/${adapter.total}`)} files present`);
         }
     }
     return report.status === "ok" ? 0 : 1;

package/dist/commands/graph.js

@@ -1,6 +1,7 @@
 import { spawnSync } from "node:child_process";
-import { commandExists } from "../adapters/tool-checks.js";
+import { beadsViewerInstallGuide, checkTools, commandExists } from "../adapters/tool-checks.js";
 import { prepareBeadsMirror } from "../core/beads-mirror.js";
+import { createColors } from "../core/colors.js";
 import { readSyncedStories, selectableStories } from "../core/synced-stories.js";
 const robotActions = new Map([
     ["triage", "--robot-triage"],
@@ -9,9 +10,12 @@ const robotActions = new Map([
 ]);
 export async function graphCommand(options) {
     const stdout = options.stdout ?? console;
+    if (options.action === "setup") {
+        return graphSetup(options);
+    }
     const robotFlag = robotActions.get(options.action);
     if (!robotFlag) {
-        stdout.error("Usage: speckit graph triage|plan|insights [--json]");
+        stdout.error("Usage: speckit graph setup|triage|plan|insights [--json]");
         return 1;
     }
     if (commandExists("bv")) {
@@ -32,6 +36,30 @@ export async function graphCommand(options) {
     stdout.log(JSON.stringify(fallback, null, 2));
     return 0;
 }
+async function graphSetup(options) {
+    const stdout = options.stdout ?? console;
+    const colors = createColors();
+    const tools = checkTools().filter((tool) => ["br", "bd", "bv"].includes(tool.name));
+    const mirrorPath = await prepareBeadsMirror(options.root);
+    const report = {
+        status: tools.find((tool) => tool.name === "bv")?.available ? "ready" : "needs-bv",
+        mirror: mirrorPath,
+        tools,
+        install: beadsViewerInstallGuide(),
+    };
+    if (options.json) {
+        stdout.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        stdout.log(beadsViewerInstallGuide());
+        stdout.log("");
+        stdout.log(`${colors.bold("Mirror")}: ${colors.cyan(mirrorPath)}`);
+        for (const tool of tools) {
+            stdout.log(`${colors.bold(tool.name)}: ${colors.status(tool.available)} - ${colors.dim(tool.hint)}`);
+        }
+    }
+    return 0;
+}
 async function localGraphFallback(root, action) {
     const stories = await readSyncedStories(root);
     const selectable = selectableStories(stories);
@@ -46,6 +74,6 @@ async function localGraphFallback(root, action) {
             top_pick: selectable[0] ?? null,
         },
         recommendations: selectable.slice(0, 3),
-        command: "Install Beads Viewer for graph metrics: bv --robot-triage --format json",
+        command: "Install Beads Viewer for graph metrics: brew install dicklesworthstone/tap/bv",
     };
 }

package/dist/commands/init.js

@@ -2,8 +2,10 @@ 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";
+import { createColors } from "../core/colors.js";
 export async function initCommand(options) {
     const stdout = options.stdout ?? console;
+    const colors = createColors();
     const selectedIde = options.ide ?? "all";
     const sharedFiles = [...coreFiles(), ...agentFiles()];
     const baseFiles = options.enterprise ? [...sharedFiles, ...enterpriseFiles()] : sharedFiles;
@@ -13,9 +15,9 @@ export async function initCommand(options) {
     const updated = results.filter((result) => result.status === "updated").length;
     const skipped = results.filter((result) => result.status === "skipped");
     const mode = options.enterprise ? "enterprise" : "standard";
-    stdout.log(`Speckit initialized (${mode}): ${created} created, ${updated} updated, ${skipped.length} skipped.`);
+    stdout.log(`${colors.bold("Speckit initialized")} (${colors.cyan(mode)}): ${colors.green(String(created))} created, ${colors.yellow(String(updated))} updated, ${colors.status(skipped.length === 0, String(skipped.length), String(skipped.length))} skipped.`);
     for (const result of skipped) {
-        stdout.log(`skipped ${result.path}: ${result.reason}`);
+        stdout.log(`${colors.yellow("skipped")} ${result.path}: ${result.reason}`);
     }
     return skipped.length > 0 ? 2 : 0;
 }

package/dist/commands/next.js

@@ -1,9 +1,9 @@
 import { spawnSync } from "node:child_process";
-import { commandExists } from "../adapters/tool-checks.js";
+import { beadsViewerInstallGuide, 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");
+        stdout.error(`bv is not installed.\n\n${beadsViewerInstallGuide()}`);
         return 1;
     }
     const result = spawnSync("bv", ["--robot-next", "--format", "json"], {

package/dist/commands/ready.js

@@ -1,20 +1,22 @@
 import { evaluateReadiness } from "../core/readiness.js";
+import { createColors } from "../core/colors.js";
 export async function readyCommand(options) {
     const stdout = options.stdout ?? console;
+    const colors = createColors();
     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}`);
+    stdout.log(`# ${colors.bold("Speckit Readiness")}: ${colors.status(report.status === "ready", "ready", report.status)}`);
     if (report.story) {
-        stdout.log(`Story: ${report.story.path}`);
+        stdout.log(`${colors.bold("Story")}: ${colors.cyan(report.story.path)}`);
     }
     for (const check of report.checks) {
-        stdout.log(`- ${check.ok ? "ok" : "blocked"} ${check.name}: ${check.detail}`);
+        stdout.log(`- ${colors.status(check.ok, "ok", "blocked")} ${check.name}: ${check.detail}`);
     }
     if (report.status !== "ready") {
-        stdout.error("Run the suggested setup commands before `speckit run`.");
+        stdout.error(colors.yellow("Run the suggested setup commands before `speckit run`."));
     }
     return report.status === "ready" ? 0 : 1;
 }

package/dist/commands/setup.d.ts

@@ -0,0 +1,9 @@
+import { Readable, Writable } from "node:stream";
+export type SetupOptions = {
+    root: string;
+    answers?: string[];
+    stdin?: Readable;
+    output?: Writable;
+    stdout?: Pick<typeof console, "log" | "error">;
+};
+export declare function setupCommand(options: SetupOptions): Promise<number>;

package/dist/commands/setup.js

@@ -0,0 +1,131 @@
+import { createInterface } from "node:readline/promises";
+import { adapters } from "../config/adapter-registry.js";
+import { createColors } from "../core/colors.js";
+import { graphCommand } from "./graph.js";
+import { initCommand } from "./init.js";
+const modeChoices = [
+    { label: "Enterprise Agile + TDD harness", value: "enterprise" },
+    { label: "Standard Agile + TDD runtime", value: "standard" },
+];
+const ideChoices = [
+    { label: "All supported IDEs", value: "all" },
+    ...adapters.map((adapter) => ({
+        label: adapter.displayName,
+        value: adapter.name,
+    })),
+];
+export async function setupCommand(options) {
+    const stdin = options.stdin ?? process.stdin;
+    const output = options.output ?? process.stdout;
+    const stdout = options.stdout ?? console;
+    const colors = createColors(output);
+    if (options.answers) {
+        return setupFromAnswers(options, stdout, options.answers);
+    }
+    if (!stdin.isTTY || !output.isTTY) {
+        stdout.error("Interactive setup requires a TTY. Use `speckit init --enterprise --ide all` for non-interactive setup.");
+        return 1;
+    }
+    const rl = createInterface({ input: stdin, output });
+    try {
+        stdout.log(colors.bold(colors.cyan("Speckit setup")));
+        stdout.log("");
+        const mode = await select(rl, stdout, modeChoices, "Choose setup mode", "1", colors);
+        const ide = await select(rl, stdout, ideChoices, "Choose IDE adapter", "1", colors);
+        const force = await confirm(rl, stdout, "Overwrite unmanaged files if needed?", false, colors);
+        const configureGraph = await confirm(rl, stdout, "Run Beads Viewer setup after init?", true, colors);
+        stdout.log("");
+        stdout.log(colors.dim(`Selected: ${mode}, ide=${ide}, force=${force ? "yes" : "no"}, graph=${configureGraph ? "yes" : "no"}`));
+        stdout.log("");
+        const initExit = await initCommand({
+            root: options.root,
+            ide,
+            enterprise: mode === "enterprise",
+            force,
+            stdout,
+        });
+        if (configureGraph) {
+            stdout.log("");
+            await graphCommand({ root: options.root, action: "setup", stdout });
+        }
+        return initExit;
+    }
+    finally {
+        rl.close();
+    }
+}
+async function setupFromAnswers(options, stdout, answers) {
+    const colors = createColors();
+    stdout.log(colors.bold(colors.cyan("Speckit setup")));
+    stdout.log("");
+    const mode = selectAnswer(stdout, modeChoices, "Choose setup mode", "1", answers.shift(), colors);
+    const ide = selectAnswer(stdout, ideChoices, "Choose IDE adapter", "1", answers.shift(), colors);
+    const force = confirmAnswer("Overwrite unmanaged files if needed?", false, answers.shift());
+    const configureGraph = confirmAnswer("Run Beads Viewer setup after init?", true, answers.shift());
+    stdout.log("");
+    stdout.log(colors.dim(`Selected: ${mode}, ide=${ide}, force=${force ? "yes" : "no"}, graph=${configureGraph ? "yes" : "no"}`));
+    stdout.log("");
+    const initExit = await initCommand({
+        root: options.root,
+        ide,
+        enterprise: mode === "enterprise",
+        force,
+        stdout,
+    });
+    if (configureGraph) {
+        stdout.log("");
+        await graphCommand({ root: options.root, action: "setup", stdout });
+    }
+    return initExit;
+}
+function selectAnswer(stdout, choices, prompt, defaultValue, answer, colors = createColors()) {
+    stdout.log(colors.bold(prompt));
+    choices.forEach((choice, index) => stdout.log(`  ${colors.cyan(String(index + 1))}. ${choice.label}`));
+    const selected = (answer?.trim() || defaultValue);
+    const index = Number.parseInt(selected, 10) - 1;
+    if (!Number.isInteger(index) || !choices[index]) {
+        throw new Error(`Invalid selection: ${selected}`);
+    }
+    stdout.log("");
+    return choices[index].value;
+}
+function confirmAnswer(prompt, defaultValue, answer) {
+    const selected = answer?.trim().toLowerCase();
+    if (!selected)
+        return defaultValue;
+    if (["y", "yes"].includes(selected))
+        return true;
+    if (["n", "no"].includes(selected))
+        return false;
+    throw new Error(`Invalid yes/no answer for "${prompt}": ${answer}`);
+}
+async function select(rl, stdout, choices, prompt, defaultValue, colors = createColors()) {
+    for (;;) {
+        stdout.log(colors.bold(prompt));
+        choices.forEach((choice, index) => {
+            const number = String(index + 1);
+            stdout.log(`  ${colors.cyan(number)}. ${choice.label}`);
+        });
+        const answer = (await rl.question(`${colors.dim("Select")} [${colors.cyan(defaultValue)}]: `)).trim() || defaultValue;
+        const index = Number.parseInt(answer, 10) - 1;
+        if (Number.isInteger(index) && choices[index]) {
+            stdout.log("");
+            return choices[index].value;
+        }
+        stdout.log(colors.red(`Invalid selection: ${answer}`));
+        stdout.log("");
+    }
+}
+async function confirm(rl, stdout, prompt, defaultValue, colors = createColors()) {
+    const suffix = defaultValue ? "Y/n" : "y/N";
+    for (;;) {
+        const answer = (await rl.question(`${prompt} [${colors.cyan(suffix)}]: `)).trim().toLowerCase();
+        if (!answer)
+            return defaultValue;
+        if (["y", "yes"].includes(answer))
+            return true;
+        if (["n", "no"].includes(answer))
+            return false;
+        stdout.log(colors.yellow("Please answer y or n."));
+    }
+}

package/dist/commands/sync.js

@@ -3,8 +3,10 @@ import { join } from "node:path";
 import { markdown, writeManagedFiles } from "../core/managed-files.js";
 import { firstHeading, frontmatterValue } from "../core/story.js";
 import { writeBeadsMirror } from "../core/beads-mirror.js";
+import { createColors } from "../core/colors.js";
 export async function syncCommand(options) {
     const stdout = options.stdout ?? console;
+    const colors = createColors();
     const storiesDir = join(options.root, ".speckit", "stories");
     let entries;
     try {
@@ -45,7 +47,7 @@ bv --robot-next --format json
         },
     ], true);
     const beadsPath = await writeBeadsMirror(options.root, stories);
-    stdout.log(`Synced ${stories.length} stories to .speckit/sync/beads-sync.jsonl`);
-    stdout.log(`Prepared Beads Viewer mirror at ${beadsPath}`);
+    stdout.log(`Synced ${colors.cyan(String(stories.length))} stories to ${colors.cyan(".speckit/sync/beads-sync.jsonl")}`);
+    stdout.log(`Prepared Beads Viewer mirror at ${colors.cyan(beadsPath)}`);
     return 0;
 }

package/dist/commands/validate.js

@@ -1,6 +1,8 @@
 import { validateWorkflowContract } from "../core/workflow-validator.js";
+import { createColors } from "../core/colors.js";
 export async function validateCommand(options) {
     const stdout = options.stdout ?? console;
+    const colors = createColors();
     const checks = await validateWorkflowContract(options.root);
     const status = checks.every((check) => check.ok) ? "ok" : "needs-attention";
     const report = { status, checks };
@@ -8,9 +10,9 @@ export async function validateCommand(options) {
         stdout.log(JSON.stringify(report, null, 2));
     }
     else {
-        stdout.log(`Speckit workflow contract: ${status}`);
+        stdout.log(`${colors.bold("Speckit workflow contract")}: ${colors.status(status === "ok", "ok", status)}`);
         for (const check of checks) {
-            stdout.log(`${check.ok ? "ok" : "fail"} ${check.name}: ${check.detail}`);
+            stdout.log(`${colors.status(check.ok, "ok", "fail")} ${check.name}: ${check.detail}`);
         }
     }
     return status === "ok" ? 0 : 1;

package/dist/core/colors.d.ts

@@ -0,0 +1,11 @@
+type ColorOutput = {
+    isTTY?: boolean;
+};
+type ColorName = "blue" | "cyan" | "dim" | "green" | "red" | "yellow" | "bold";
+export type Colors = Record<ColorName, (text: string) => string> & {
+    enabled: boolean;
+    status(ok: boolean, okText?: string, failText?: string): string;
+};
+export declare function createColors(output?: ColorOutput): Colors;
+export declare function colorsEnabled(output?: ColorOutput): boolean;
+export {};

package/dist/core/colors.js

@@ -0,0 +1,40 @@
+const ansi = {
+    blue: [34, 39],
+    cyan: [36, 39],
+    dim: [2, 22],
+    green: [32, 39],
+    red: [31, 39],
+    yellow: [33, 39],
+    bold: [1, 22],
+};
+export function createColors(output) {
+    const enabled = colorsEnabled(output);
+    const style = (name) => (text) => {
+        if (!enabled)
+            return text;
+        const [open, close] = ansi[name];
+        return `\u001B[${open}m${text}\u001B[${close}m`;
+    };
+    return {
+        enabled,
+        blue: style("blue"),
+        cyan: style("cyan"),
+        dim: style("dim"),
+        green: style("green"),
+        red: style("red"),
+        yellow: style("yellow"),
+        bold: style("bold"),
+        status(ok, okText = "ok", failText = "missing") {
+            return ok ? this.green(okText) : this.red(failText);
+        },
+    };
+}
+export function colorsEnabled(output) {
+    if (process.env.NO_COLOR || process.env.SPECKIT_COLOR === "0")
+        return false;
+    if (process.env.FORCE_COLOR === "0")
+        return false;
+    if (process.env.FORCE_COLOR || process.env.SPECKIT_COLOR === "1")
+        return true;
+    return output?.isTTY ?? process.stdout.isTTY ?? false;
+}

package/docs/adapters.md

@@ -25,3 +25,24 @@ Speckit never invokes bare `bv`. The `next` command calls:
 ```bash
 bv --robot-next --format json
 ```
+
+Run this once on a new machine to see install commands and prepare the graph mirror:
+
+```bash
+speckit graph setup
+```
+
+Common `bv` installs:
+
+```bash
+brew install dicklesworthstone/tap/bv
+go install github.com/Dicklesworthstone/beads_viewer/cmd/bv@latest
+```
+
+Graph wrappers use robot mode:
+
+```bash
+speckit graph triage --json
+speckit graph plan --json
+speckit graph insights --json
+```

package/docs/beads-viewer-setup.md

@@ -0,0 +1,58 @@
+<!-- speckit:managed -->
+# Beads Viewer Setup
+
+Speckit works without Beads Viewer by falling back to local JSON. Install `bv` when you want graph-aware prioritization, bottleneck detection, critical path analysis, and robot-mode planning.
+
+## Install `bv`
+
+Recommended on macOS/Linux:
+
+```bash
+brew install dicklesworthstone/tap/bv
+```
+
+Go install:
+
+```bash
+go install github.com/Dicklesworthstone/beads_viewer/cmd/bv@latest
+```
+
+Nix:
+
+```bash
+nix run github:Dicklesworthstone/beads_viewer -- --help
+```
+
+## Verify With Speckit
+
+```bash
+speckit graph setup
+speckit sync
+speckit graph triage --json
+speckit next
+```
+
+`speckit graph setup` prepares `.beads/beads.jsonl` from Speckit stories and reports whether `bv` is available.
+
+## Agent Safety Rule
+
+Do not run bare `bv` from an agent session. Bare `bv` opens the interactive TUI. Use:
+
+```bash
+speckit graph triage --json
+speckit graph plan --json
+speckit graph insights --json
+bv --robot-triage --format json
+bv --robot-next --format json
+```
+
+## Data Flow
+
+```text
+.speckit/stories/*.md
+  -> speckit sync
+  -> .speckit/sync/beads-sync.jsonl
+  -> .beads/beads.jsonl
+  -> bv --robot-* or Speckit graph wrappers
+```
+

package/docs/development-roadmap.md

@@ -4,7 +4,7 @@
 
 Speckit MVP is implemented and pushed to `git@github.com:trieungoctam/speckit.git` on `main`.
 
-Current package target: `@trieungoctam/speckit@0.3.4`.
+Current package target: `@trieungoctam/speckit@0.3.5`.
 
 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/session tests plus CI.
 
@@ -13,11 +13,11 @@ The CLI is npx-ready, generates Agile + TDD rules, creates workflow artifacts, s
 | Milestone | Status | Notes |
 | --- | --- | --- |
 | Product contract | Complete | Contract, workflow model, and command surface documented. |
-| CLI scaffold | Complete | `bin/speckit`, TypeScript build, command router, managed file writer. |
+| CLI scaffold | Complete | `bin/speckit`, TypeScript build, command router, interactive setup wizard, managed file writer. |
 | Workflow engine | Complete | `start`, `shape`, `plan`, `context`, `quick`, `sync`, `triage`, `ready`, `run`, `review`, and `close` generate linked artifacts. |
 | Long session manager | Complete | `memory refresh` plus `session start/checkpoint/compact/resume/status` preserve agent continuity outside chat history. |
 | IDE adapters | Complete | Claude Code, Codex, Antigravity, OpenCode, Cursor. |
-| Beads integration | MVP Complete | `next` and `graph triage/plan/insights` wrap BV robot mode; `sync` exports story metadata JSONL. |
+| Beads integration | MVP Complete | `graph setup` prints install commands and prepares `.beads/beads.jsonl`; `next` and `graph triage/plan/insights` wrap BV robot mode; `sync` exports story metadata JSONL. |
 | Sprint automation | MVP Complete | `sprint plan` and `sprint next` select work from synced stories. |
 | Enterprise harness | MVP Complete | `init --enterprise` creates flow, tool-policy, and prompt harness files; `doctor --deep` verifies them. |
 | Curated skill catalog | Complete | Speckit now generates focused phase skills, a schema, delegation statuses, and task hydration/sync-back guidance. |

package/docs/project-changelog.md

@@ -1,5 +1,31 @@
 # Project Changelog
 
+## 0.3.6 - 2026-05-11
+
+### Added
+
+- Added ANSI color rendering for interactive CLI and TUI output, including setup prompts, init summaries, doctor checks, graph setup, readiness, validation, sync, and help headers.
+- Added `SPECKIT_COLOR=1` / `FORCE_COLOR` support for demos and snapshots, with `NO_COLOR` / `SPECKIT_COLOR=0` opt-out support.
+
+### Quality
+
+- Added color helper regression tests.
+- JSON output remains uncolored for automation.
+
+## 0.3.5 - 2026-05-11
+
+### Added
+
+- Added `speckit setup`, an interactive TUI wizard for setup mode, IDE adapter, overwrite policy, and optional Beads Viewer setup.
+- Added `speckit graph setup` to print Beads Viewer install commands, check `br`/`bd`/`bv`, and prepare `.beads/beads.jsonl`.
+- Added `docs/beads-viewer-setup.md` with Homebrew, Go, and Nix setup paths plus robot-safe verification commands.
+
+### Changed
+
+- `speckit doctor` now prints install hints for missing tools.
+- `speckit next` now prints concrete Beads Viewer setup guidance when `bv` is missing.
+- README and workflow docs now include the graph setup step.
+
 ## 0.3.4 - 2026-05-11
 
 ### Fixed

package/docs/use-cases.md

@@ -6,6 +6,16 @@ This guide shows how to use Speckit for common product and engineering workflows
 
 Use when a repository does not have Speckit runtime files yet.
 
+Interactive:
+
+```bash
+npx @trieungoctam/speckit@latest setup
+```
+
+The wizard asks for setup mode, IDE adapter, overwrite policy, and whether to run Beads Viewer setup.
+
+Scripted:
+
 ```bash
 npx @trieungoctam/speckit@latest init --enterprise --ide cursor
 npx @trieungoctam/speckit@latest doctor --deep
@@ -131,6 +141,7 @@ Use when multiple stories exist and the next task is not obvious.
 
 ```bash
 speckit sync
+speckit graph setup
 speckit sprint plan
 speckit sprint next --json
 speckit graph triage --json
@@ -141,6 +152,7 @@ speckit graph insights --json
 Best practices:
 
 - Run `sync` before any graph command.
+- Run `graph setup` on new machines to print Beads Viewer install commands, check `bv`, and prepare `.beads/beads.jsonl`.
 - Keep graph commands robot-safe. Use Speckit wrappers instead of interactive graph commands.
 - Treat graph output as prioritization input, not automatic permission to implement.
 - Re-run `sprint plan` when story status or dependencies change.

package/docs/workflow-model.md

@@ -70,3 +70,5 @@ Long-running agent work must keep durable state outside chat history:
 ## Beads Viewer Automation
 
 `speckit sync` prepares both Speckit sync metadata and a Beads Viewer-compatible `.beads/beads.jsonl` mirror. `speckit graph triage|plan|insights` refreshes that mirror before invoking `bv --robot-*` from the project root, then falls back to local JSON if Beads Viewer is unavailable or still fails.
+
+Run `speckit graph setup` on a new machine to print Beads Viewer install commands, check `br`/`bd`/`bv`, and prepare `.beads/beads.jsonl`.

package/package.json

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