@trieungoctam/speckit 0.2.2 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/README.md +32 -5
  2. package/dist/adapters/antigravity-adapter.js +4 -4
  3. package/dist/adapters/claude-code-adapter.js +7 -5
  4. package/dist/adapters/codex-adapter.js +5 -3
  5. package/dist/adapters/cursor-adapter.js +7 -3
  6. package/dist/adapters/opencode-adapter.js +1 -1
  7. package/dist/cli.js +28 -0
  8. package/dist/commands/doctor.js +2 -1
  9. package/dist/commands/graph.d.ts +7 -0
  10. package/dist/commands/graph.js +51 -0
  11. package/dist/commands/init.js +3 -1
  12. package/dist/commands/memory.d.ts +6 -0
  13. package/dist/commands/memory.js +11 -0
  14. package/dist/commands/session.d.ts +9 -0
  15. package/dist/commands/session.js +49 -0
  16. package/dist/commands/sprint.d.ts +7 -0
  17. package/dist/commands/sprint.js +54 -0
  18. package/dist/commands/start.js +4 -3
  19. package/dist/commands/sync.js +3 -0
  20. package/dist/commands/triage.js +2 -15
  21. package/dist/core/agent-scaffold.d.ts +2 -0
  22. package/dist/core/agent-scaffold.js +57 -0
  23. package/dist/core/beads-mirror.d.ts +3 -0
  24. package/dist/core/beads-mirror.js +46 -0
  25. package/dist/core/memory.d.ts +1 -0
  26. package/dist/core/memory.js +47 -0
  27. package/dist/core/scaffold.js +33 -63
  28. package/dist/core/session-manager.d.ts +15 -0
  29. package/dist/core/session-manager.js +139 -0
  30. package/dist/core/skill-catalog.d.ts +2 -0
  31. package/dist/core/skill-catalog.js +177 -0
  32. package/dist/core/synced-stories.d.ts +8 -0
  33. package/dist/core/synced-stories.js +17 -0
  34. package/dist/core/templates.d.ts +2 -0
  35. package/dist/core/templates.js +54 -0
  36. package/docs/development-roadmap.md +7 -5
  37. package/docs/product-contract.md +7 -4
  38. package/docs/project-changelog.md +30 -0
  39. package/docs/spec-enterprise-harness-plan.md +18 -1
  40. package/docs/workflow-model.md +23 -0
  41. package/package.json +1 -1
@@ -0,0 +1,46 @@
1
+ import { mkdir, writeFile } from "node:fs/promises";
2
+ import { dirname, join } from "node:path";
3
+ import { readSyncedStories } from "./synced-stories.js";
4
+ export async function writeBeadsMirror(root, stories) {
5
+ const path = ".beads/beads.jsonl";
6
+ const now = new Date().toISOString();
7
+ const jsonl = stories
8
+ .map((story) => JSON.stringify(toBeadIssue(story, now)))
9
+ .join("\n");
10
+ const target = join(root, path);
11
+ await mkdir(dirname(target), { recursive: true });
12
+ await writeFile(target, `${jsonl}${jsonl ? "\n" : ""}`, "utf8");
13
+ return path;
14
+ }
15
+ export async function prepareBeadsMirror(root) {
16
+ return writeBeadsMirror(root, await readSyncedStories(root));
17
+ }
18
+ function toBeadIssue(story, timestamp) {
19
+ return {
20
+ id: story.id,
21
+ title: story.title,
22
+ description: `Speckit story: ${story.path}`,
23
+ status: mapStatus(story.status),
24
+ priority: 2,
25
+ issue_type: "task",
26
+ labels: ["speckit", "story"],
27
+ created_at: timestamp,
28
+ updated_at: timestamp,
29
+ };
30
+ }
31
+ function mapStatus(status) {
32
+ switch (status) {
33
+ case "in-progress":
34
+ return "in_progress";
35
+ case "ready-for-review":
36
+ case "review-ready":
37
+ return "review";
38
+ case "closed":
39
+ case "done":
40
+ return "closed";
41
+ case "draft":
42
+ return "draft";
43
+ default:
44
+ return "open";
45
+ }
46
+ }
@@ -0,0 +1 @@
1
+ export declare function refreshMemory(root: string): Promise<string[]>;
@@ -0,0 +1,47 @@
1
+ import { markdown, writeManagedFiles } from "./managed-files.js";
2
+ export async function refreshMemory(root) {
3
+ const files = [
4
+ {
5
+ path: ".speckit/memory/project-context.md",
6
+ content: markdown(`# Spec Project Context
7
+
8
+ ## Technology Stack & Versions
9
+ - Update this section with project-specific runtime, framework, test, and deployment facts.
10
+
11
+ ## Critical Implementation Rules
12
+ - Prefer existing project patterns over generic framework defaults.
13
+ - Keep implementation scoped to the active story and acceptance criteria.
14
+ - Record red-green-refactor evidence for code stories.
15
+ - Use robot-safe graph commands only.
16
+
17
+ ## Context Loading Rules
18
+ - Load this file before implementation, review, sprint planning, and session resume.
19
+ - Treat this file as durable guidance, not as proof that the current environment still matches it.
20
+ `),
21
+ },
22
+ {
23
+ path: ".speckit/memory/decisions.md",
24
+ content: markdown(`# Spec Decisions
25
+
26
+ ## Active Decisions
27
+ - Record durable architecture and workflow decisions here.
28
+
29
+ ## Superseded Decisions
30
+ - Move stale decisions here with the replacement decision and date.
31
+ `),
32
+ },
33
+ {
34
+ path: ".speckit/memory/lessons.md",
35
+ content: markdown(`# Spec Lessons
36
+
37
+ ## Repeated Mistakes To Avoid
38
+ - Add a lesson when an agent repeats a mistake or review catches a missed project rule.
39
+
40
+ ## Useful Verification Commands
41
+ - Add commands that reliably validate this project.
42
+ `),
43
+ },
44
+ ];
45
+ const results = await writeManagedFiles(root, files, false);
46
+ return results.map((result) => result.path);
47
+ }
@@ -1,5 +1,6 @@
1
1
  import { markdown, text } from "./managed-files.js";
2
2
  import { agilePolicy, enterpriseSafetyPolicy, tddPolicy, workflowReview, workflowShape, workflowTddRun, } from "./policy.js";
3
+ import { storyTemplate, tddEvidenceTemplate } from "./templates.js";
3
4
  export function coreFiles() {
4
5
  return [
5
6
  {
@@ -13,6 +14,14 @@ tdd:
13
14
  task_graph:
14
15
  provider: beads
15
16
  bv_robot_only: true
17
+ memory:
18
+ project_context: .speckit/memory/project-context.md
19
+ session_dir: .speckit/sessions
20
+ skills:
21
+ catalog: .speckit/skills/catalog.md
22
+ super_agent: .speckit/agents/super-agent.md
23
+ sprint:
24
+ status: .speckit/sprint/status.yaml
16
25
  adapters:
17
26
  enabled: []`),
18
27
  },
@@ -27,63 +36,11 @@ adapters:
27
36
  { path: ".speckit/workflows/review.md", content: markdown(workflowReview) },
28
37
  {
29
38
  path: ".speckit/templates/story.md",
30
- content: markdown(`---
31
- status: draft
32
- evidence: .speckit/evidence/{{slug}}-tdd-evidence.md
33
- context: pending
34
- ---
35
-
36
- # Story: {{title}}
37
-
38
- ## Intent
39
- {{intent}}
40
-
41
- ## Acceptance Criteria
42
- - Given ...
43
- - When ...
44
- - Then ...
45
-
46
- ## TDD Checklist
47
- - [ ] Test targets identified
48
- - [ ] Red evidence recorded
49
- - [ ] Green evidence recorded
50
- - [ ] Refactor validation recorded
51
-
52
- ## Notes
53
- - Risks:
54
- - Dependencies:
55
-
56
- ## Spec Anti-Mistake Checklist
57
- - Reuse existing project patterns before adding new files.
58
- - Verify file locations before editing.
59
- - Do not introduce new libraries without explicit need.
60
- - Preserve existing behavior unless an acceptance criterion requires change.
61
- - Capture previous-story learnings if this continues prior work.
62
- `),
39
+ content: markdown(storyTemplate),
63
40
  },
64
41
  {
65
42
  path: ".speckit/templates/tdd-evidence.md",
66
- content: markdown(`---
67
- status: missing
68
- story: {{story}}
69
- ---
70
-
71
- # TDD Evidence: {{story}}
72
-
73
- ## Test Intent
74
-
75
- ## Red
76
- - Command:
77
- - Result:
78
-
79
- ## Green
80
- - Command:
81
- - Result:
82
-
83
- ## Refactor
84
- - Command:
85
- - Result:
86
- `),
43
+ content: markdown(tddEvidenceTemplate),
87
44
  },
88
45
  ];
89
46
  }
@@ -94,12 +51,14 @@ export function enterpriseFiles() {
94
51
  content: markdown(`# Spec Flow
95
52
 
96
53
  ## Order
97
- start -> shape -> plan -> context -> sync -> triage -> run -> review -> close
54
+ start -> memory -> sprint -> context -> sync -> triage -> ready -> run -> checkpoint -> review -> close
98
55
 
99
56
  ## Traceability
100
57
  - A session links the original idea to every downstream artifact.
58
+ - Project memory links durable rules to every new session.
101
59
  - A story links acceptance criteria to TDD evidence.
102
60
  - Sync links stories to graph-ready JSONL.
61
+ - Session checkpoints preserve file changes, decisions, and next steps across compaction.
103
62
  - Close links review output back to story and graph sync.
104
63
  `),
105
64
  },
@@ -127,6 +86,11 @@ graph:
127
86
 
128
87
  - Current context: \`.speckit/context/current.md\`
129
88
  - Subagent handoff: \`.speckit/context/subagent-handoff.md\`
89
+ - Project memory: \`.speckit/memory/project-context.md\`
90
+ - Active session summary: \`.speckit/sessions/active.md\` and the linked \`summary.md\`
91
+ - Active artifact log: linked \`artifact-log.md\`
92
+ - Super agent router: \`.speckit/agents/super-agent.md\`
93
+ - Skill catalog: \`.speckit/skills/catalog.md\`
130
94
  - Story with acceptance criteria
131
95
  - Matching TDD evidence file
132
96
  - Tool policy: \`.speckit/tool-policy.yaml\`
@@ -136,6 +100,7 @@ graph:
136
100
  - Story status is \`ready-for-dev\`.
137
101
  - Context status is \`fresh\`.
138
102
  - \`speckit ready <story>\` returns ready.
103
+ - \`speckit session status\` identifies the active session.
139
104
 
140
105
  ## Allowed Edits
141
106
 
@@ -149,26 +114,31 @@ graph:
149
114
  Use the red-green-refactor loop.
150
115
 
151
116
  1. Read the current context before touching code.
152
- 2. Confirm the story path, acceptance criteria, and evidence path.
153
- 3. Write or run the smallest failing test first.
154
- 4. Record red evidence before implementation.
155
- 5. Implement the smallest change that satisfies the failing test.
156
- 6. Record green evidence after tests pass.
157
- 7. Refactor only while tests stay green, then record validation.
158
- 8. Use graph commands only through robot-safe flags such as \`bv --robot-next --format json\`.
159
- 9. Run \`speckit review\` before handoff.
117
+ 2. Read the super agent router and select the smallest matching Speckit skill.
118
+ 3. Confirm the story path, acceptance criteria, and evidence path.
119
+ 4. Write or run the smallest failing test first.
120
+ 5. Record red evidence before implementation.
121
+ 6. Implement the smallest change that satisfies the failing test.
122
+ 7. Record green evidence after tests pass.
123
+ 8. Refactor only while tests stay green, then record validation.
124
+ 9. Use graph commands only through robot-safe flags such as \`bv --robot-next --format json\`.
125
+ 10. Run \`speckit session checkpoint --note "<phase complete>"\` after red, green, refactor, and review boundaries.
126
+ 11. Run \`speckit session compact\` before context gets noisy or before handing off to another agent.
127
+ 12. Run \`speckit review\` before handoff.
160
128
 
161
129
  ## Stop Conditions
162
130
 
163
131
  - Stop if acceptance criteria are missing.
164
132
  - Stop if the evidence file cannot be identified.
165
133
  - Stop if \`speckit ready <story>\` reports blocked.
134
+ - Stop if active session state cannot be written.
166
135
  - Stop before destructive commands, production changes, or secret access.
167
136
 
168
137
  ## Completion Signal
169
138
 
170
139
  - All acceptance criteria satisfied.
171
140
  - TDD evidence status can be advanced through red, green, and refactor.
141
+ - Session checkpoint and compact summary are current.
172
142
  - Review handoff is ready.
173
143
  `),
174
144
  },
@@ -0,0 +1,15 @@
1
+ export type SessionCheckpointOptions = {
2
+ root: string;
3
+ note?: string;
4
+ story?: string;
5
+ };
6
+ export type SessionRef = {
7
+ id: string;
8
+ dir: string;
9
+ };
10
+ export declare function ensureSession(root: string, intent?: string): Promise<SessionRef>;
11
+ export declare function createSession(root: string, intent?: string): Promise<SessionRef>;
12
+ export declare function checkpointSession(options: SessionCheckpointOptions): Promise<SessionRef>;
13
+ export declare function compactSession(root: string): Promise<SessionRef>;
14
+ export declare function resumeSession(root: string, id?: string): Promise<SessionRef | undefined>;
15
+ export declare function sessionStatus(root: string): Promise<Record<string, string>>;
@@ -0,0 +1,139 @@
1
+ import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
2
+ import { dirname, join } from "node:path";
3
+ import { slugify, timestamp } from "./slug.js";
4
+ export async function ensureSession(root, intent = "long session") {
5
+ const active = await readActiveSession(root);
6
+ if (active)
7
+ return active;
8
+ return createSession(root, intent);
9
+ }
10
+ export async function createSession(root, intent = "long session") {
11
+ const id = `${timestamp()}-${slugify(intent)}`;
12
+ const ref = { id, dir: `.speckit/sessions/${id}` };
13
+ await mkdir(join(root, ref.dir), { recursive: true });
14
+ await writeActiveSession(root, ref);
15
+ await writeFile(join(root, ref.dir, "events.jsonl"), "", "utf8");
16
+ await writeFile(join(root, ref.dir, "artifact-log.md"), "# Spec Artifact Log\n\n", "utf8");
17
+ await writeFile(join(root, ref.dir, "summary.md"), baseSummary(intent), "utf8");
18
+ await writeState(root, ref, { phase: "started", status: "active", story: "pending" });
19
+ await writeHandoff(root, ref, "Start from the active Speckit session state.");
20
+ return ref;
21
+ }
22
+ export async function checkpointSession(options) {
23
+ const ref = await ensureSession(options.root, options.note ?? "checkpoint");
24
+ const event = {
25
+ type: "checkpoint",
26
+ at: new Date().toISOString(),
27
+ note: options.note ?? "Manual checkpoint",
28
+ story: options.story,
29
+ };
30
+ await appendFile(join(options.root, ref.dir, "events.jsonl"), `${JSON.stringify(event)}\n`, "utf8");
31
+ await appendFile(join(options.root, ref.dir, "artifact-log.md"), `## ${event.at}\n- Note: ${event.note}\n${options.story ? `- Story: \`${options.story}\`\n` : ""}\n`, "utf8");
32
+ await writeState(options.root, ref, {
33
+ phase: "checkpointed",
34
+ status: "active",
35
+ story: options.story ?? "pending",
36
+ });
37
+ return ref;
38
+ }
39
+ export async function compactSession(root) {
40
+ const ref = await ensureSession(root, "compact");
41
+ const [state, context, handoff, artifactLog] = await Promise.all([
42
+ readOptional(root, `${ref.dir}/state.yaml`),
43
+ readOptional(root, ".speckit/context/current.md"),
44
+ readOptional(root, ".speckit/context/subagent-handoff.md"),
45
+ readOptional(root, `${ref.dir}/artifact-log.md`),
46
+ ]);
47
+ const summary = `# Spec Session Summary
48
+
49
+ ## Session Intent
50
+ Preserve the active Speckit workflow so another agent or compacted session can continue safely.
51
+
52
+ ## Current State
53
+ ${state || "- No state recorded yet."}
54
+
55
+ ## Active Context
56
+ ${extractCompactSection(context)}
57
+
58
+ ## Files And Artifacts
59
+ ${extractCompactSection(artifactLog)}
60
+
61
+ ## Decisions Made
62
+ - Trust current files over stale memory.
63
+ - Keep implementation bounded by the selected story and readiness gate.
64
+
65
+ ## Next Steps
66
+ 1. Read \`.speckit/memory/project-context.md\`.
67
+ 2. Read \`.speckit/context/current.md\` and \`.speckit/context/subagent-handoff.md\`.
68
+ 3. Run \`speckit session status\`.
69
+ 4. Run \`speckit ready <story>\` before implementation.
70
+
71
+ ## Resume Handoff
72
+ ${extractCompactSection(handoff)}
73
+ `;
74
+ await writeFile(join(root, ref.dir, "summary.md"), summary, "utf8");
75
+ await writeHandoff(root, ref, "Resume from the compacted session summary before loading task context.");
76
+ return ref;
77
+ }
78
+ export async function resumeSession(root, id) {
79
+ const ref = id ? { id, dir: `.speckit/sessions/${id}` } : await readActiveSession(root);
80
+ if (!ref)
81
+ return undefined;
82
+ await writeActiveSession(root, ref);
83
+ await writeHandoff(root, ref, "Resume this session and continue from summary, context, and artifact log.");
84
+ return ref;
85
+ }
86
+ export async function sessionStatus(root) {
87
+ const ref = await readActiveSession(root);
88
+ if (!ref)
89
+ return { status: "missing" };
90
+ return {
91
+ status: "active",
92
+ id: ref.id,
93
+ dir: ref.dir,
94
+ state: `${ref.dir}/state.yaml`,
95
+ summary: `${ref.dir}/summary.md`,
96
+ handoff: `${ref.dir}/handoff.md`,
97
+ };
98
+ }
99
+ async function readActiveSession(root) {
100
+ try {
101
+ const content = await readFile(join(root, ".speckit", "sessions", "active.md"), "utf8");
102
+ const id = content.match(/session:\s*([^\s]+)/)?.[1];
103
+ return id ? { id, dir: `.speckit/sessions/${id}` } : undefined;
104
+ }
105
+ catch {
106
+ return undefined;
107
+ }
108
+ }
109
+ async function writeActiveSession(root, ref) {
110
+ await writeText(root, ".speckit/sessions/active.md", `# Active Spec Session\n\nsession: ${ref.id}\n`);
111
+ }
112
+ async function writeState(root, ref, state) {
113
+ const body = Object.entries({ session: ref.id, updated: new Date().toISOString(), ...state })
114
+ .map(([key, value]) => `${key}: ${value}`)
115
+ .join("\n");
116
+ await writeText(root, `${ref.dir}/state.yaml`, `${body}\n`);
117
+ }
118
+ async function writeHandoff(root, ref, note) {
119
+ await writeText(root, `${ref.dir}/handoff.md`, `# Spec Session Handoff\n\n${note}\n\n## Load Order\n1. \`${ref.dir}/summary.md\`\n2. \`${ref.dir}/state.yaml\`\n3. \`${ref.dir}/artifact-log.md\`\n4. \`.speckit/context/current.md\`\n`);
120
+ }
121
+ async function writeText(root, path, content) {
122
+ const target = join(root, path);
123
+ await mkdir(dirname(target), { recursive: true });
124
+ await writeFile(target, content, "utf8");
125
+ }
126
+ async function readOptional(root, path) {
127
+ try {
128
+ return await readFile(join(root, path), "utf8");
129
+ }
130
+ catch {
131
+ return "";
132
+ }
133
+ }
134
+ function baseSummary(intent) {
135
+ return `# Spec Session Summary\n\n## Session Intent\n${intent}\n\n## Current State\n- Session started.\n\n## Next Steps\n1. Build context.\n2. Sync graph.\n3. Run readiness.\n`;
136
+ }
137
+ function extractCompactSection(content) {
138
+ return content.trim() ? content.trim().split("\n").slice(0, 40).join("\n") : "- Not recorded.";
139
+ }
@@ -0,0 +1,2 @@
1
+ import { ManagedFile } from "./managed-files.js";
2
+ export declare function specSkillFiles(): ManagedFile[];
@@ -0,0 +1,177 @@
1
+ import { json, markdown } from "./managed-files.js";
2
+ const selectedSources = [
3
+ "brainstorm",
4
+ "research",
5
+ "docs-seeker",
6
+ "plan",
7
+ "project-management",
8
+ "scout",
9
+ "context-engineering",
10
+ "kanban",
11
+ "implementation-runner",
12
+ "test",
13
+ "debug",
14
+ "fix",
15
+ "code-review",
16
+ "security-scan",
17
+ "docs",
18
+ "journal",
19
+ "git",
20
+ "ship",
21
+ ];
22
+ const skills = [
23
+ skill("spec-shape", "shape", "Turn a rough request into a bounded Agile spec before planning.", [
24
+ "Clarify business goal, users, constraints, and non-goals.",
25
+ "Split large ideas into independent stories with acceptance criteria.",
26
+ "Challenge over-engineered scope before it reaches implementation.",
27
+ ]),
28
+ skill("spec-research", "research", "Validate external tools, docs, or architecture choices before planning.", [
29
+ "Define recency and source-quality requirements before searching.",
30
+ "Prefer official docs, primary repos, and current release notes.",
31
+ "Summarize recommendations, risks, and rejected options in reports.",
32
+ ]),
33
+ skill("spec-plan", "plan", "Create PRD, architecture, story, and evidence skeletons.", [
34
+ "Check unfinished plans before creating new work.",
35
+ "Write phases with files, dependencies, success criteria, and rollback.",
36
+ "Keep plan state durable so sessions can rehydrate tasks later.",
37
+ ]),
38
+ skill("spec-context", "context", "Build the smallest useful story context and subagent handoff.", [
39
+ "Read project memory, active session, story, evidence, and relevant files.",
40
+ "List files to read and files to modify separately.",
41
+ "Avoid passing full chat history to implementation agents.",
42
+ ]),
43
+ skill("spec-session", "session", "Manage checkpoint, compaction, resume, and artifact-log discipline.", [
44
+ "Checkpoint after red, green, refactor, review, and scope changes.",
45
+ "Compact noisy context into durable summaries before handoff.",
46
+ "Sync runtime task progress back to plan and story files.",
47
+ ]),
48
+ skill("spec-graph", "graph", "Use sprint and graph robot outputs to choose safe, unblocked work.", [
49
+ "Run Beads Viewer through robot-safe commands only.",
50
+ "Prefer unblocked, high-value stories with clear evidence paths.",
51
+ "Mirror story state to graph artifacts before triage or next selection.",
52
+ ]),
53
+ skill("spec-tdd", "run", "Run a ready story through red-green-refactor with evidence and checkpoints.", [
54
+ "Require ready-for-dev status and current context before code edits.",
55
+ "Write or run the smallest failing test before implementation.",
56
+ "Record red, green, and refactor evidence with session checkpoints.",
57
+ ]),
58
+ skill("spec-test", "test", "Select and run verification after implementation.", [
59
+ "Map changed files to focused tests first, then broaden when risk is high.",
60
+ "Run typecheck or build before claiming code is valid.",
61
+ "Never ignore failing tests; report root cause or blocker.",
62
+ ]),
63
+ skill("spec-debug", "debug", "Diagnose failures with evidence before changing code.", [
64
+ "Capture exact failing output and pre-fix state.",
65
+ "Trace root cause through callers, dependencies, and recent changes.",
66
+ "Fix the cause, then verify against the original failure.",
67
+ ]),
68
+ skill("spec-review", "review", "Review acceptance coverage, TDD evidence, safety, docs, and session freshness.", [
69
+ "Review spec compliance before code quality opinions.",
70
+ "Prioritize correctness, security, regressions, and missing tests.",
71
+ "Block closure when evidence, context, or session state is stale.",
72
+ ]),
73
+ skill("spec-docs", "docs", "Update durable docs, changelog, and lessons after behavior changes.", [
74
+ "Update roadmap and changelog when milestone or behavior changes.",
75
+ "Record decisions and lessons in project memory when reusable.",
76
+ "Keep docs aligned with actual implemented behavior.",
77
+ ]),
78
+ skill("spec-ship", "ship", "Prepare clean release handoff after tests and review pass.", [
79
+ "Check git diff for unrelated changes and secrets before commit.",
80
+ "Use focused conventional commits and release notes.",
81
+ "Do not ship while tests, review, or evidence gates are failing.",
82
+ ]),
83
+ ];
84
+ function skill(name, phase, purpose, practices) {
85
+ return { name, phase, purpose, practices };
86
+ }
87
+ export function specSkillFiles() {
88
+ return [catalogFile(), schemaFile(), ...skills.map(skillFile)];
89
+ }
90
+ function catalogFile() {
91
+ return {
92
+ path: ".speckit/skills/catalog.md",
93
+ content: markdown(`# Spec Skill Catalog
94
+
95
+ This catalog is intentionally smaller than a broad general-purpose skill set. Speckit keeps only the skills required for enterprise Agile, TDD, long sessions, graph-guided work, and release hygiene.
96
+
97
+ ## Core Skills
98
+
99
+ | Skill | Inspired By | Use When | Required Inputs |
100
+ | --- | --- | --- | --- |
101
+ | spec-shape | brainstorm, scenario | Turning rough intent into a bounded spec | user intent, project memory |
102
+ | spec-research | research, docs-seeker | Validating external choices and current docs | scope, source criteria |
103
+ | spec-plan | plan, project-management | Creating PRD, architecture, stories, and evidence skeletons | spec brief, project memory |
104
+ | spec-context | scout, context-engineering | Building current story context and handoff | story, evidence, session state |
105
+ | spec-graph | kanban, plans-kanban, gkg | Choosing and sequencing safe work | synced stories, robot graph output |
106
+ | spec-session | context-engineering, watzup | Preserving long-running work | active session, artifact log |
107
+ | spec-tdd | implementation-runner, test | Implementing code with red-green-refactor | ready story, context, evidence |
108
+ | spec-test | test, web-testing | Selecting and running verification | changed files, acceptance criteria |
109
+ | spec-debug | debug, fix, sequential-thinking | Diagnosing failures before changing code | failing output, impact scope |
110
+ | spec-review | code-review, security-scan | Reviewing code and artifacts | diff, story, evidence, session log |
111
+ | spec-docs | docs, journal, retro | Updating docs and durable decisions | changed behavior, release notes |
112
+ | spec-ship | git, ship, deploy | Preparing clean release handoff | passing tests, review result |
113
+
114
+ ## Selection Policy
115
+
116
+ - Pick the smallest skill that covers the current phase.
117
+ - Load skill detail only when that phase is active.
118
+ - Never mix planning and implementation in the same skill invocation.
119
+ - Prefer file handoff over chat handoff for subagents.
120
+ - Do not import broad domain skills unless the current story explicitly needs that domain.
121
+ - Use \`spec-debug\` before fixes when the root cause is not proven.
122
+ - Use \`spec-test\` after implementation and before review.
123
+ `),
124
+ };
125
+ }
126
+ function schemaFile() {
127
+ return {
128
+ path: ".speckit/skills/schema.json",
129
+ content: json({
130
+ version: 1,
131
+ required: ["name", "purpose", "phase", "inputs", "outputs", "stop_conditions"],
132
+ statuses: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED", "NEEDS_CONTEXT"],
133
+ selected_from: selectedSources,
134
+ }),
135
+ };
136
+ }
137
+ function skillFile(skill) {
138
+ return {
139
+ path: `.speckit/skills/${skill.name}.md`,
140
+ content: markdown(`# ${skill.name}
141
+
142
+ ## Purpose
143
+
144
+ ${skill.purpose}
145
+
146
+ ## Phase
147
+
148
+ ${skill.phase}
149
+
150
+ ## Required Context
151
+
152
+ - \`.speckit/memory/project-context.md\`
153
+ - \`.speckit/sessions/active.md\`
154
+ - \`.speckit/context/current.md\` when story-scoped
155
+ - \`.speckit/context/subagent-handoff.md\` when delegating
156
+
157
+ ## Practices
158
+
159
+ ${skill.practices.map((practice) => `- ${practice}`).join("\n")}
160
+
161
+ ## Stop Conditions
162
+
163
+ - Missing acceptance criteria.
164
+ - Missing or stale active session.
165
+ - Missing evidence path for code work.
166
+ - Blocked story or unresolved \`NEEDS_CONTEXT\` handoff.
167
+
168
+ ## Output Contract
169
+
170
+ - State what was read.
171
+ - State what changed.
172
+ - State the next Speckit command.
173
+ - Write durable progress to the appropriate Speckit artifact.
174
+ - End delegated work with \`DONE\`, \`DONE_WITH_CONCERNS\`, \`BLOCKED\`, or \`NEEDS_CONTEXT\`.
175
+ `),
176
+ };
177
+ }
@@ -0,0 +1,8 @@
1
+ export type SyncedStory = {
2
+ id: string;
3
+ path: string;
4
+ title: string;
5
+ status: string;
6
+ };
7
+ export declare function readSyncedStories(root: string): Promise<SyncedStory[]>;
8
+ export declare function selectableStories(stories: SyncedStory[]): SyncedStory[];
@@ -0,0 +1,17 @@
1
+ import { readFile } from "node:fs/promises";
2
+ import { join } from "node:path";
3
+ export async function readSyncedStories(root) {
4
+ try {
5
+ const content = await readFile(join(root, ".speckit", "sync", "beads-sync.jsonl"), "utf8");
6
+ return content
7
+ .split("\n")
8
+ .filter(Boolean)
9
+ .map((line) => JSON.parse(line));
10
+ }
11
+ catch {
12
+ return [];
13
+ }
14
+ }
15
+ export function selectableStories(stories) {
16
+ return stories.filter((story) => ["open", "ready-for-dev", "in-progress"].includes(story.status));
17
+ }
@@ -0,0 +1,2 @@
1
+ export declare const storyTemplate = "---\nstatus: draft\nevidence: .speckit/evidence/{{slug}}-tdd-evidence.md\ncontext: pending\n---\n\n# Story: {{title}}\n\n## Intent\n{{intent}}\n\n## Acceptance Criteria\n- Given ...\n- When ...\n- Then ...\n\n## TDD Checklist\n- [ ] Test targets identified\n- [ ] Red evidence recorded\n- [ ] Green evidence recorded\n- [ ] Refactor validation recorded\n\n## Notes\n- Risks:\n- Dependencies:\n\n## Spec Anti-Mistake Checklist\n- Reuse existing project patterns before adding new files.\n- Verify file locations before editing.\n- Do not introduce new libraries without explicit need.\n- Preserve existing behavior unless an acceptance criterion requires change.\n- Capture previous-story learnings if this continues prior work.\n";
2
+ export declare const tddEvidenceTemplate = "---\nstatus: missing\nstory: {{story}}\n---\n\n# TDD Evidence: {{story}}\n\n## Test Intent\n\n## Red\n- Command:\n- Result:\n\n## Green\n- Command:\n- Result:\n\n## Refactor\n- Command:\n- Result:\n";