@trieungoctam/speckit 0.2.2 → 0.3.0

package/README.md

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

package/dist/adapters/antigravity-adapter.js

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

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

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

package/dist/adapters/codex-adapter.js

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

package/dist/adapters/cursor-adapter.js

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

package/dist/adapters/opencode-adapter.js

@@ -53,7 +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.
+Read \`.speckit/agents/super-agent.md\`, \`.speckit/skills/catalog.md\`, \`.speckit/memory/project-context.md\`, \`.speckit/sessions/active.md\`, \`.speckit/context/current.md\`, and \`.speckit/context/subagent-handoff.md\` before implementation work. Select the smallest matching Speckit skill. Require \`speckit ready <story>\`, confirm acceptance criteria, preserve session handoff, checkpoint red-green-refactor boundaries, compact before handoff, and use only robot-safe graph commands.
 `),
     };
 }

package/dist/cli.js

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

package/dist/commands/doctor.js

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

package/dist/commands/graph.d.ts

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

package/dist/commands/graph.js

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

package/dist/commands/init.js

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

package/dist/commands/memory.d.ts

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

package/dist/commands/memory.js

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

package/dist/commands/session.d.ts

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

package/dist/commands/session.js

@@ -0,0 +1,49 @@
+import { checkpointSession, compactSession, ensureSession, resumeSession, sessionStatus, } from "../core/session-manager.js";
+export async function sessionCommand(options) {
+    const stdout = options.stdout ?? console;
+    switch (options.action) {
+        case "start": {
+            const session = await ensureSession(options.root, options.note ?? options.target ?? "long session");
+            stdout.log(session.id);
+            stdout.log(`${session.dir}/handoff.md`);
+            return 0;
+        }
+        case "checkpoint": {
+            const session = await checkpointSession({
+                root: options.root,
+                note: options.note ?? options.target,
+                story: options.target,
+            });
+            stdout.log(`Checkpointed ${session.id}`);
+            return 0;
+        }
+        case "compact": {
+            const session = await compactSession(options.root);
+            stdout.log(`${session.dir}/summary.md`);
+            return 0;
+        }
+        case "resume": {
+            const session = await resumeSession(options.root, options.target);
+            if (!session) {
+                stdout.error("No Speckit session to resume.");
+                return 1;
+            }
+            stdout.log(session.id);
+            stdout.log(`${session.dir}/handoff.md`);
+            return 0;
+        }
+        case "status": {
+            const status = await sessionStatus(options.root);
+            stdout.log(options.json ? JSON.stringify(status, null, 2) : renderStatus(status));
+            return status.status === "missing" ? 1 : 0;
+        }
+        default:
+            stdout.error("Usage: speckit session start|checkpoint|compact|resume|status");
+            return 1;
+    }
+}
+function renderStatus(status) {
+    if (status.status === "missing")
+        return "Spec session: missing";
+    return `Spec session: ${status.id}\nState: ${status.state}\nSummary: ${status.summary}\nHandoff: ${status.handoff}`;
+}

package/dist/commands/sprint.d.ts

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

package/dist/commands/sprint.js

@@ -0,0 +1,54 @@
+import { markdown, text, writeManagedFiles } from "../core/managed-files.js";
+import { readSyncedStories, selectableStories } from "../core/synced-stories.js";
+export async function sprintCommand(options) {
+    const stdout = options.stdout ?? console;
+    const stories = await readSyncedStories(options.root);
+    switch (options.action) {
+        case "plan": {
+            const selected = selectableStories(stories);
+            await writeManagedFiles(options.root, [
+                {
+                    path: ".speckit/sprint/status.yaml",
+                    content: text(renderStatus(stories)),
+                },
+                {
+                    path: ".speckit/sprint/plan.md",
+                    content: markdown(renderPlan(selected)),
+                },
+            ], true);
+            stdout.log(`Planned sprint with ${selected.length} selectable stories`);
+            return 0;
+        }
+        case "next": {
+            const next = selectableStories(stories)[0] ?? null;
+            stdout.log(options.json ? JSON.stringify({ next }, null, 2) : renderNext(next));
+            return next ? 0 : 1;
+        }
+        default:
+            stdout.error("Usage: speckit sprint plan|next [--json]");
+            return 1;
+    }
+}
+function renderStatus(stories) {
+    const rows = stories.map((story) => `  ${story.id}: ${story.status}`);
+    return `version: 1\nsource: .speckit/sync/beads-sync.jsonl\ndevelopment_status:\n${rows.join("\n") || "  none: empty"}\n`;
+}
+function renderPlan(stories) {
+    const rows = stories.map((story) => `- [ ] ${story.id} (${story.status}) - \`${story.path}\``);
+    return `# Spec Sprint Plan
+
+## Goal
+Deliver the highest-priority ready stories while preserving TDD evidence and graph traceability.
+
+## Selected Stories
+${rows.join("\n") || "- No selectable stories. Run `speckit quick`, `speckit sync`, then retry."}
+
+## Automation
+- Run \`speckit graph triage --json\` before claiming work.
+- Run \`speckit context <story>\` and \`speckit ready <story>\` before implementation.
+- Run \`speckit session checkpoint\` at task boundaries.
+`;
+}
+function renderNext(story) {
+    return story ? `Next sprint story: ${story.id} (${story.path})` : "Next sprint story: none";
+}

package/dist/commands/start.js

@@ -1,9 +1,10 @@
 import { markdown, writeManagedFiles } from "../core/managed-files.js";
-import { slugify, timestamp } from "../core/slug.js";
+import { createSession } from "../core/session-manager.js";
 export async function startCommand(options) {
     const stdout = options.stdout ?? console;
-    const sessionId = `${timestamp()}-${slugify(options.intent)}`;
-    const handoffPath = `.speckit/sessions/${sessionId}/handoff.md`;
+    const session = await createSession(options.root, options.intent);
+    const sessionId = session.id;
+    const handoffPath = `${session.dir}/handoff.md`;
     const contextPath = ".speckit/context/current.md";
     await writeManagedFiles(options.root, [
         {

package/dist/commands/sync.js

@@ -2,6 +2,7 @@ import { readdir, readFile } from "node:fs/promises";
 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";
 export async function syncCommand(options) {
     const stdout = options.stdout ?? console;
     const storiesDir = join(options.root, ".speckit", "stories");
@@ -43,6 +44,8 @@ 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}`);
     return 0;
 }

package/dist/commands/triage.js

@@ -1,9 +1,8 @@
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { readSyncedStories, selectableStories } from "../core/synced-stories.js";
 export async function triageCommand(options) {
     const stdout = options.stdout ?? console;
     const stories = await readSyncedStories(options.root);
-    const open = stories.filter((story) => ["open", "ready-for-dev", "in-progress"].includes(story.status));
+    const open = selectableStories(stories);
     const ready = stories.filter((story) => story.status !== "open");
     const report = {
         source: ".speckit/sync/beads-sync.jsonl",
@@ -19,15 +18,3 @@ export async function triageCommand(options) {
     stdout.log(open[0] ? `Next: ${open[0].id} (${open[0].path})` : "Next: none");
     return 0;
 }
-async function readSyncedStories(root) {
-    try {
-        const content = await readFile(join(root, ".speckit", "sync", "beads-sync.jsonl"), "utf8");
-        return content
-            .split("\n")
-            .filter(Boolean)
-            .map((line) => JSON.parse(line));
-    }
-    catch {
-        return [];
-    }
-}

package/dist/core/agent-scaffold.d.ts

@@ -0,0 +1,2 @@
+import { ManagedFile } from "./managed-files.js";
+export declare function agentFiles(): ManagedFile[];

package/dist/core/agent-scaffold.js

@@ -0,0 +1,57 @@
+import { markdown } from "./managed-files.js";
+import { specSkillFiles } from "./skill-catalog.js";
+export function agentFiles() {
+    return [
+        {
+            path: ".speckit/agents/super-agent.md",
+            content: markdown(`# Spec Super Agent
+
+## Mission
+
+Act as the controller for Speckit enterprise work. Do not be the only worker when context isolation is useful; route work through focused skills and subagent handoffs.
+
+## Load Order
+
+1. \`.speckit/memory/project-context.md\`
+2. \`.speckit/sessions/active.md\` and the linked session summary
+3. \`.speckit/skills/catalog.md\`
+4. \`.speckit/context/current.md\`
+5. \`.speckit/context/subagent-handoff.md\`
+
+## Routing Rules
+
+- Use planning skills before implementation.
+- Select the smallest matching Speckit skill for the current phase.
+- Route by the story state first, then by the requested action.
+- Use TDD execution skills only after \`speckit ready <story>\` passes.
+- Use graph skills before choosing or reordering work.
+- Use session skills at every task boundary.
+- Use review skills before closure.
+
+## Delegation Contract
+
+Every handoff must include:
+
+- Work context path.
+- Reports path.
+- Plans path.
+- Files to read.
+- Files to modify.
+- Acceptance criteria.
+- Constraints and stop conditions.
+
+Subagents must finish with one status: \`DONE\`, \`DONE_WITH_CONCERNS\`, \`BLOCKED\`, or \`NEEDS_CONTEXT\`.
+
+## Long Session Contract
+
+- Keep durable facts in files, not in chat.
+- Checkpoint after red, green, refactor, and review.
+- Compact before handoff, after noisy tool output, or before switching stories.
+- Prefer focused subagent handoffs over passing full conversation history.
+- Hydrate runtime tasks from unchecked plan/story checkboxes at session start.
+- Sync completed runtime tasks back to durable plan/story files before close.
+`),
+        },
+        ...specSkillFiles(),
+    ];
+}

package/dist/core/beads-mirror.d.ts

@@ -0,0 +1,3 @@
+import { SyncedStory } from "./synced-stories.js";
+export declare function writeBeadsMirror(root: string, stories: SyncedStory[]): Promise<string>;
+export declare function prepareBeadsMirror(root: string): Promise<string>;