@trieungoctam/speckit 0.2.0 → 0.3.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

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

package/dist/core/beads-mirror.js

@@ -0,0 +1,46 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { readSyncedStories } from "./synced-stories.js";
+export async function writeBeadsMirror(root, stories) {
+    const path = ".beads/beads.jsonl";
+    const now = new Date().toISOString();
+    const jsonl = stories
+        .map((story) => JSON.stringify(toBeadIssue(story, now)))
+        .join("\n");
+    const target = join(root, path);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, `${jsonl}${jsonl ? "\n" : ""}`, "utf8");
+    return path;
+}
+export async function prepareBeadsMirror(root) {
+    return writeBeadsMirror(root, await readSyncedStories(root));
+}
+function toBeadIssue(story, timestamp) {
+    return {
+        id: story.id,
+        title: story.title,
+        description: `Speckit story: ${story.path}`,
+        status: mapStatus(story.status),
+        priority: 2,
+        issue_type: "task",
+        labels: ["speckit", "story"],
+        created_at: timestamp,
+        updated_at: timestamp,
+    };
+}
+function mapStatus(status) {
+    switch (status) {
+        case "in-progress":
+            return "in_progress";
+        case "ready-for-review":
+        case "review-ready":
+            return "review";
+        case "closed":
+        case "done":
+            return "closed";
+        case "draft":
+            return "draft";
+        default:
+            return "open";
+    }
+}

package/dist/core/memory.d.ts

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

package/dist/core/memory.js

@@ -0,0 +1,47 @@
+import { markdown, writeManagedFiles } from "./managed-files.js";
+export async function refreshMemory(root) {
+    const files = [
+        {
+            path: ".speckit/memory/project-context.md",
+            content: markdown(`# Spec Project Context
+
+## Technology Stack & Versions
+- Update this section with project-specific runtime, framework, test, and deployment facts.
+
+## Critical Implementation Rules
+- Prefer existing project patterns over generic framework defaults.
+- Keep implementation scoped to the active story and acceptance criteria.
+- Record red-green-refactor evidence for code stories.
+- Use robot-safe graph commands only.
+
+## Context Loading Rules
+- Load this file before implementation, review, sprint planning, and session resume.
+- Treat this file as durable guidance, not as proof that the current environment still matches it.
+`),
+        },
+        {
+            path: ".speckit/memory/decisions.md",
+            content: markdown(`# Spec Decisions
+
+## Active Decisions
+- Record durable architecture and workflow decisions here.
+
+## Superseded Decisions
+- Move stale decisions here with the replacement decision and date.
+`),
+        },
+        {
+            path: ".speckit/memory/lessons.md",
+            content: markdown(`# Spec Lessons
+
+## Repeated Mistakes To Avoid
+- Add a lesson when an agent repeats a mistake or review catches a missed project rule.
+
+## Useful Verification Commands
+- Add commands that reliably validate this project.
+`),
+        },
+    ];
+    const results = await writeManagedFiles(root, files, false);
+    return results.map((result) => result.path);
+}

package/dist/core/readiness.d.ts

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

package/dist/core/readiness.js

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

package/dist/core/scaffold.js

@@ -1,5 +1,6 @@
 import { markdown, text } from "./managed-files.js";
 import { agilePolicy, enterpriseSafetyPolicy, tddPolicy, workflowReview, workflowShape, workflowTddRun, } from "./policy.js";
+import { storyTemplate, tddEvidenceTemplate } from "./templates.js";
 export function coreFiles() {
     return [
         {
@@ -13,6 +14,14 @@ tdd:
 task_graph:
   provider: beads
   bv_robot_only: true
+memory:
+  project_context: .speckit/memory/project-context.md
+  session_dir: .speckit/sessions
+skills:
+  catalog: .speckit/skills/catalog.md
+  super_agent: .speckit/agents/super-agent.md
+sprint:
+  status: .speckit/sprint/status.yaml
 adapters:
   enabled: []`),
         },
@@ -27,45 +36,11 @@ adapters:
         { path: ".speckit/workflows/review.md", content: markdown(workflowReview) },
         {
             path: ".speckit/templates/story.md",
-            content: markdown(`# Story: {{title}}
-
-## Intent
-{{intent}}
-
-## Acceptance Criteria
-- Given ...
-- When ...
-- Then ...
-
-## TDD Checklist
-- [ ] Test targets identified
-- [ ] Red evidence recorded
-- [ ] Green evidence recorded
-- [ ] Refactor validation recorded
-
-## Notes
-- Risks:
-- Dependencies:
-`),
+            content: markdown(storyTemplate),
         },
         {
             path: ".speckit/templates/tdd-evidence.md",
-            content: markdown(`# TDD Evidence: {{story}}
-
-## Test Intent
-
-## Red
-- Command:
-- Result:
-
-## Green
-- Command:
-- Result:
-
-## Refactor
-- Command:
-- Result:
-`),
+            content: markdown(tddEvidenceTemplate),
         },
     ];
 }
@@ -76,12 +51,14 @@ export function enterpriseFiles() {
             content: markdown(`# Spec Flow
 
 ## Order
-start -> shape -> plan -> context -> sync -> triage -> run -> review -> close
+start -> memory -> sprint -> context -> sync -> triage -> ready -> run -> checkpoint -> review -> close
 
 ## Traceability
 - A session links the original idea to every downstream artifact.
+- Project memory links durable rules to every new session.
 - A story links acceptance criteria to TDD evidence.
 - Sync links stories to graph-ready JSONL.
+- Session checkpoints preserve file changes, decisions, and next steps across compaction.
 - Close links review output back to story and graph sync.
 `),
         },
@@ -105,12 +82,64 @@ graph:
             path: ".speckit/prompts/spec-run.md",
             content: markdown(`# Spec Run Prompt
 
-1. Read \`.speckit/context/current.md\`.
-2. Confirm story acceptance criteria.
-3. Write or run the failing test first.
-4. Implement the smallest change.
-5. Record red, green, and refactor evidence.
-6. Run \`speckit review\` before handoff.
+## Required Inputs
+
+- Current context: \`.speckit/context/current.md\`
+- Subagent handoff: \`.speckit/context/subagent-handoff.md\`
+- Project memory: \`.speckit/memory/project-context.md\`
+- Active session summary: \`.speckit/sessions/active.md\` and the linked \`summary.md\`
+- Active artifact log: linked \`artifact-log.md\`
+- Super agent router: \`.speckit/agents/super-agent.md\`
+- Skill catalog: \`.speckit/skills/catalog.md\`
+- Story with acceptance criteria
+- Matching TDD evidence file
+- Tool policy: \`.speckit/tool-policy.yaml\`
+
+## Status Preconditions
+
+- Story status is \`ready-for-dev\`.
+- Context status is \`fresh\`.
+- \`speckit ready <story>\` returns ready.
+- \`speckit session status\` identifies the active session.
+
+## Allowed Edits
+
+- Implementation files needed for the story.
+- Matching tests.
+- Linked TDD evidence file.
+- Story completion checkboxes and implementation notes.
+
+## Execution Contract
+
+Use the red-green-refactor loop.
+
+1. Read the current context before touching code.
+2. Read the super agent router and select the smallest matching Speckit skill.
+3. Confirm the story path, acceptance criteria, and evidence path.
+4. Write or run the smallest failing test first.
+5. Record red evidence before implementation.
+6. Implement the smallest change that satisfies the failing test.
+7. Record green evidence after tests pass.
+8. Refactor only while tests stay green, then record validation.
+9. Use graph commands only through robot-safe flags such as \`bv --robot-next --format json\`.
+10. Run \`speckit session checkpoint --note "<phase complete>"\` after red, green, refactor, and review boundaries.
+11. Run \`speckit session compact\` before context gets noisy or before handing off to another agent.
+12. Run \`speckit review\` before handoff.
+
+## Stop Conditions
+
+- Stop if acceptance criteria are missing.
+- Stop if the evidence file cannot be identified.
+- Stop if \`speckit ready <story>\` reports blocked.
+- Stop if active session state cannot be written.
+- Stop before destructive commands, production changes, or secret access.
+
+## Completion Signal
+
+- All acceptance criteria satisfied.
+- TDD evidence status can be advanced through red, green, and refactor.
+- Session checkpoint and compact summary are current.
+- Review handoff is ready.
 `),
         },
     ];

package/dist/core/session-manager.d.ts

@@ -0,0 +1,15 @@
+export type SessionCheckpointOptions = {
+    root: string;
+    note?: string;
+    story?: string;
+};
+export type SessionRef = {
+    id: string;
+    dir: string;
+};
+export declare function ensureSession(root: string, intent?: string): Promise<SessionRef>;
+export declare function createSession(root: string, intent?: string): Promise<SessionRef>;
+export declare function checkpointSession(options: SessionCheckpointOptions): Promise<SessionRef>;
+export declare function compactSession(root: string): Promise<SessionRef>;
+export declare function resumeSession(root: string, id?: string): Promise<SessionRef | undefined>;
+export declare function sessionStatus(root: string): Promise<Record<string, string>>;