@applica-software-guru/sdd-core 0.2.0 → 1.0.1

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEvE,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,eAAe,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,gBAAgB,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,KAAK;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,UAAU,GAAG,KAAK,GAAG,SAAS,CAAC;CACxC;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,KAAK,CAAC;QACX,YAAY,EAAE,MAAM,CAAC;QACrB,MAAM,EAAE,KAAK,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;QACjD,OAAO,EAAE,MAAM,CAAC;QAChB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,SAAS,CAAC;AAEtD,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,mBAAmB,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,wBAAwB,CAAC;IACtC,IAAI,EAAE,MAAM,CAAC;CACd"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEvE,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,eAAe,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,gBAAgB,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,KAAK;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,UAAU,GAAG,KAAK,GAAG,SAAS,CAAC;CACxC;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,KAAK,CAAC;QACX,YAAY,EAAE,MAAM,CAAC;QACrB,MAAM,EAAE,KAAK,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;QACjD,OAAO,EAAE,MAAM,CAAC;QAChB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,SAAS,CAAC;AAEtD,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,mBAAmB,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,wBAAwB,CAAC;IACtC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,UAAU,CAAC;AAE5C,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,GAAG;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,cAAc,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;CACd"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applica-software-guru/sdd-core",
-  "version": "0.2.0",
+  "version": "1.0.1",
   "description": "Core library for Story Driven Development",
   "author": "Bruno Fortunato <bruno.fortunato@applica.guru>",
   "main": "dist/index.js",

package/src/agent/agent-defaults.ts

@@ -0,0 +1,12 @@
+export const DEFAULT_AGENTS: Record<string, string> = {
+  claude: 'claude -p "$(cat $PROMPT_FILE)" --dangerously-skip-permissions --verbose',
+  codex: 'codex -q "$(cat $PROMPT_FILE)"',
+  opencode: 'opencode -p "$(cat $PROMPT_FILE)"',
+};
+
+export function resolveAgentCommand(
+  name: string,
+  configAgents?: Record<string, string>
+): string | undefined {
+  return configAgents?.[name] ?? DEFAULT_AGENTS[name];
+}

package/src/agent/agent-runner.ts

@@ -0,0 +1,54 @@
+import { spawn } from 'node:child_process';
+import { writeFile, unlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { resolveAgentCommand } from './agent-defaults.js';
+
+export interface AgentRunnerOptions {
+  root: string;
+  prompt: string;
+  agent: string;
+  agents?: Record<string, string>;
+  onOutput?: (data: string) => void;
+}
+
+export async function runAgent(options: AgentRunnerOptions): Promise<number> {
+  const { root, prompt, agent, agents, onOutput } = options;
+
+  const template = resolveAgentCommand(agent, agents);
+  if (!template) {
+    throw new Error(`Unknown agent "${agent}". Available: ${Object.keys(agents ?? {}).join(', ') || 'claude, codex, opencode'}`);
+  }
+
+  // Write prompt to temp file (too large for CLI arg)
+  const tmpFile = join(tmpdir(), `sdd-prompt-${randomBytes(6).toString('hex')}.md`);
+  await writeFile(tmpFile, prompt, 'utf-8');
+
+  // Replace $PROMPT_FILE with the temp file path in the command template
+  const command = template.replace(/\$PROMPT_FILE/g, tmpFile);
+
+  try {
+    const exitCode = await new Promise<number>((resolve, reject) => {
+      const child = spawn(command, {
+        cwd: root,
+        shell: true,
+        stdio: onOutput ? ['inherit', 'pipe', 'pipe'] : 'inherit',
+      });
+
+      if (onOutput && child.stdout) {
+        child.stdout.on('data', (data: Buffer) => onOutput(data.toString()));
+      }
+      if (onOutput && child.stderr) {
+        child.stderr.on('data', (data: Buffer) => onOutput(data.toString()));
+      }
+
+      child.on('error', reject);
+      child.on('close', (code) => resolve(code ?? 1));
+    });
+
+    return exitCode;
+  } finally {
+    await unlink(tmpFile).catch(() => {});
+  }
+}

package/src/index.ts

@@ -13,7 +13,13 @@ export type {
   ChangeRequest,
   ChangeRequestFrontmatter,
   ChangeRequestStatus,
+  Bug,
+  BugFrontmatter,
+  BugStatus,
 } from './types.js';
 export { SDDError, LockFileNotFoundError, ParseError, ProjectNotInitializedError } from './errors.js';
 export type { ProjectInfo } from './scaffold/templates.js';
-export { isSDDProject, readConfig } from './config/config-manager.js';
+export { isSDDProject, readConfig, writeConfig } from './config/config-manager.js';
+export { runAgent } from './agent/agent-runner.js';
+export type { AgentRunnerOptions } from './agent/agent-runner.js';
+export { DEFAULT_AGENTS, resolveAgentCommand } from './agent/agent-defaults.js';

package/src/parser/bug-parser.ts

@@ -0,0 +1,41 @@
+import { readFile } from 'node:fs/promises';
+import { resolve, relative } from 'node:path';
+import { glob } from 'glob';
+import matter from 'gray-matter';
+import type { Bug, BugFrontmatter } from '../types.js';
+import { ParseError } from '../errors.js';
+
+export async function discoverBugFiles(root: string): Promise<string[]> {
+  const pattern = 'bugs/*.md';
+  const matches = await glob(pattern, { cwd: root, absolute: true });
+  return matches.sort();
+}
+
+export function parseBugFile(filePath: string, content: string): { frontmatter: BugFrontmatter; body: string } {
+  try {
+    const { data, content: body } = matter(content);
+    const frontmatter: BugFrontmatter = {
+      title: data.title ?? '',
+      status: data.status ?? 'open',
+      author: data.author ?? '',
+      'created-at': data['created-at'] ?? '',
+    };
+    return { frontmatter, body };
+  } catch (err) {
+    throw new ParseError(filePath, (err as Error).message);
+  }
+}
+
+export async function parseAllBugFiles(root: string): Promise<Bug[]> {
+  const paths = await discoverBugFiles(root);
+  const results: Bug[] = [];
+
+  for (const absPath of paths) {
+    const content = await readFile(absPath, 'utf-8');
+    const relPath = relative(root, absPath);
+    const { frontmatter, body } = parseBugFile(relPath, content);
+    results.push({ relativePath: relPath, frontmatter, body });
+  }
+
+  return results;
+}

package/src/prompt/apply-prompt-generator.ts

@@ -0,0 +1,82 @@
+import type { Bug, ChangeRequest, StoryFile } from '../types.js';
+import { getFileDiff } from '../git/git.js';
+
+export function generateApplyPrompt(
+  bugs: Bug[],
+  changeRequests: ChangeRequest[],
+  pendingFiles: StoryFile[],
+  root: string
+): string | null {
+  if (bugs.length === 0 && changeRequests.length === 0 && pendingFiles.length === 0) {
+    return null;
+  }
+
+  const sections: string[] = [];
+
+  sections.push('# SDD Apply\n\nThis project uses Story Driven Development. Complete the tasks below in order.');
+
+  // Bugs section
+  if (bugs.length > 0) {
+    const lines = [`## Open Bugs (${bugs.length})\n`];
+    for (const bug of bugs) {
+      lines.push(`### \`${bug.relativePath}\` — ${bug.frontmatter.title}\n`);
+      lines.push(bug.body.trim());
+      lines.push('');
+    }
+    sections.push(lines.join('\n'));
+  }
+
+  // Change Requests section
+  if (changeRequests.length > 0) {
+    const lines = [`## Pending Change Requests (${changeRequests.length})\n`];
+    for (const cr of changeRequests) {
+      lines.push(`### \`${cr.relativePath}\` — ${cr.frontmatter.title}\n`);
+      lines.push(cr.body.trim());
+      lines.push('');
+    }
+    sections.push(lines.join('\n'));
+  }
+
+  // Pending Files section
+  if (pendingFiles.length > 0) {
+    const lines = [`## Pending Files (${pendingFiles.length})\n`];
+    for (const f of pendingFiles) {
+      lines.push(`- \`${f.relativePath}\` — **${f.frontmatter.status}**`);
+    }
+    lines.push('');
+    lines.push('Read each file listed above before implementing.');
+
+    // Show git diff for changed files
+    const changed = pendingFiles.filter((f) => f.frontmatter.status === 'changed');
+    for (const f of changed) {
+      const diff = getFileDiff(root, f.relativePath);
+      if (diff) {
+        lines.push('');
+        lines.push(`### Changes in \`${f.relativePath}\`\n\n\`\`\`diff\n${diff}\n\`\`\``);
+      }
+    }
+
+    sections.push(lines.join('\n'));
+  }
+
+  // Instructions
+  const instructions = ['## Instructions\n'];
+
+  if (bugs.length > 0) {
+    instructions.push('1. Fix each open bug, then run `sdd mark-bug-resolved <file>` and commit');
+  }
+  if (changeRequests.length > 0) {
+    instructions.push(`${bugs.length > 0 ? '2' : '1'}. Apply each CR to the documentation, then run \`sdd mark-cr-applied <file>\` and commit`);
+  }
+  if (pendingFiles.length > 0) {
+    const step = (bugs.length > 0 ? 1 : 0) + (changeRequests.length > 0 ? 1 : 0) + 1;
+    instructions.push(`${step}. Implement each pending file, then run \`sdd mark-synced <file>\` and commit`);
+  }
+
+  const lastStep = (bugs.length > 0 ? 1 : 0) + (changeRequests.length > 0 ? 1 : 0) + (pendingFiles.length > 0 ? 1 : 0) + 1;
+  instructions.push(`${lastStep}. After each mark-* command, immediately commit: \`git add -A && git commit -m "sdd: <description>"\``);
+
+  sections.push(instructions.join('\n'));
+
+  return sections.join('\n\n');
+}

package/src/scaffold/init.ts

@@ -29,7 +29,7 @@ export async function initProject(root: string, info?: ProjectInfo): Promise<str
   createdFiles.push('.sdd/config.yaml');
 
   // Create directory structure
-  const dirs = ['product', 'product/features', 'system', 'code', 'change-requests'];
+  const dirs = ['product', 'product/features', 'system', 'code', 'change-requests', 'bugs'];
   for (const dir of dirs) {
     const absDir = resolve(root, dir);
     if (!existsSync(absDir)) {

package/src/scaffold/templates.ts

@@ -24,12 +24,14 @@ Documentation drives implementation: read the docs first, then write code.
 
 ## Workflow
 
-1. Run \`sdd cr pending\` — check if there are change requests to process first
-2. If there are pending CRs, apply them to the docs, then run \`sdd mark-cr-applied\`
-3. Run \`sdd sync\` to see what needs to be implemented
-4. Read the documentation files listed in the sync output
-5. Implement what each file describes, writing code inside \`code/\`
-6. After implementing, mark files as synced:
+1. Run \`sdd bug open\` — check if there are open bugs to fix first
+2. If there are open bugs, fix the code/docs, then run \`sdd mark-bug-resolved\`
+3. Run \`sdd cr pending\` — check if there are change requests to process
+4. If there are pending CRs, apply them to the docs, then run \`sdd mark-cr-applied\`
+5. Run \`sdd sync\` to see what needs to be implemented
+6. Read the documentation files listed in the sync output
+7. Implement what each file describes, writing code inside \`code/\`
+8. After implementing, mark files as synced:
 
 \`\`\`
 sdd mark-synced product/features/auth.md
@@ -41,7 +43,7 @@ Or mark all pending files at once:
 sdd mark-synced
 \`\`\`
 
-7. **Commit immediately after mark-synced** — this is mandatory:
+9. **Commit immediately after mark-synced** — this is mandatory:
 
 \`\`\`
 git add -A && git commit -m "sdd sync: <brief description of what was implemented>"
@@ -58,17 +60,20 @@ Delete the related code in \`code/\`, then run \`sdd mark-synced <file>\` (the d
 
 - \`sdd status\` — See all documentation files and their state (new/changed/deleted/synced)
 - \`sdd diff\` — See what changed since last sync
-- \`sdd sync\` — Get the sync prompt for pending files (new/changed/deleted)
+- \`sdd sync\` — Get the sync prompt for pending files (includes git diff for changed files)
 - \`sdd validate\` — Check for broken references and issues
 - \`sdd mark-synced [files...]\` — Mark specific files (or all) as synced
 - \`sdd cr list\` — List all change requests with their status
 - \`sdd cr pending\` — Show draft change requests to process
 - \`sdd mark-cr-applied [files...]\` — Mark change requests as applied
+- \`sdd bug list\` — List all bugs with their status
+- \`sdd bug open\` — Show open bugs to fix
+- \`sdd mark-bug-resolved [files...]\` — Mark bugs as resolved
 
 ## Rules
 
 1. **Always commit after mark-synced** — run \`git add -A && git commit -m "sdd sync: ..."\` immediately after \`sdd mark-synced\`. Never leave synced files uncommitted.
-2. Before running \`sdd sync\`, check for pending change requests with \`sdd cr pending\`
+2. Before running \`sdd sync\`, check for open bugs with \`sdd bug open\` and pending change requests with \`sdd cr pending\`
 3. If there are pending CRs, apply them to the docs first, then mark them with \`sdd mark-cr-applied\`
 4. Only implement what the sync prompt asks for
 5. All generated code goes inside \`code/\`
@@ -97,6 +102,16 @@ version: "1.0"
 - **version**: patch-bump on each edit (1.0 → 1.1 → 1.2)
 - **last-modified**: ISO 8601 datetime, updated on each edit
 
+## How sync works
+
+\`sdd sync\` generates a structured prompt for the agent based on pending files:
+
+- **\`new\` files**: the agent reads the full documentation and implements it from scratch
+- **\`changed\` files**: SDD uses \`git diff\` to compute what changed in the documentation since the last commit, and includes the diff in the sync prompt — this way the agent sees exactly what was modified and can update only the affected code
+- **\`deleted\` files**: the agent removes the related code
+
+This is why **committing after every mark-synced is mandatory** — the git history is what SDD uses to detect changes.
+
 ## Change Requests
 
 Change Requests (CRs) are markdown files in \`change-requests/\` that describe modifications to the documentation.
@@ -127,6 +142,36 @@ created-at: "2025-01-01T00:00:00.000Z"
 - \`sdd cr pending\` — Show only draft CRs to process
 - \`sdd mark-cr-applied [files...]\` — Mark CRs as applied after updating the docs
 
+## Bugs
+
+Bugs are markdown files in \`bugs/\` that describe problems found in the codebase.
+
+### Bug format
+
+\`\`\`yaml
+---
+title: "Login fails with empty password"
+status: open
+author: "user"
+created-at: "2025-01-01T00:00:00.000Z"
+---
+\`\`\`
+
+- **status**: \`open\` (needs fixing) or \`resolved\` (already fixed)
+
+### Bug workflow
+
+1. Check for open bugs: \`sdd bug open\`
+2. Read each open bug and fix the code and/or documentation
+3. After fixing a bug, mark it: \`sdd mark-bug-resolved bugs/BUG-001.md\`
+4. Commit the fix
+
+### Bug commands
+
+- \`sdd bug list\` — See all bugs and their status
+- \`sdd bug open\` — Show only open bugs to fix
+- \`sdd mark-bug-resolved [files...]\` — Mark bugs as resolved after fixing
+
 ## UX and screenshots
 
 When a feature has UX mockups or screenshots, place them next to the feature doc:
@@ -158,6 +203,7 @@ Both formats work — use a folder only when you have screenshots or multiple fi
 - \`system/\` — How to build it (entities, architecture, tech stack, interfaces)
 - \`code/\` — All generated source code goes here
 - \`change-requests/\` — Change requests to the documentation
+- \`bugs/\` — Bug reports
 - \`.sdd/\` — Project config and sync state (do not edit)
 `;
 

package/src/sdd.ts

@@ -1,13 +1,15 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
-import type { StoryStatus, ValidationResult, SDDConfig, ChangeRequest } from './types.js';
+import type { StoryStatus, ValidationResult, SDDConfig, ChangeRequest, Bug } from './types.js';
 import { ProjectNotInitializedError } from './errors.js';
 import { parseAllStoryFiles } from './parser/story-parser.js';
 import { generatePrompt } from './prompt/prompt-generator.js';
+import { generateApplyPrompt } from './prompt/apply-prompt-generator.js';
 import { validate } from './validate/validator.js';
 import { initProject } from './scaffold/init.js';
 import { isSDDProject, readConfig, writeConfig } from './config/config-manager.js';
 import { parseAllCRFiles } from './parser/cr-parser.js';
+import { parseAllBugFiles } from './parser/bug-parser.js';
 import type { ProjectInfo } from './scaffold/templates.js';
 
 export class SDD {
@@ -51,6 +53,16 @@ export class SDD {
     return generatePrompt(pending, this.root);
   }
 
+  async applyPrompt(): Promise<string | null> {
+    this.ensureInitialized();
+    const [bugs, changeRequests, pendingFiles] = await Promise.all([
+      this.openBugs(),
+      this.pendingChangeRequests(),
+      this.pending(),
+    ]);
+    return generateApplyPrompt(bugs, changeRequests, pendingFiles, this.root);
+  }
+
   async validate(): Promise<ValidationResult> {
     this.ensureInitialized();
     const files = await parseAllStoryFiles(this.root);
@@ -115,6 +127,35 @@ export class SDD {
     return marked;
   }
 
+  async bugs(): Promise<Bug[]> {
+    this.ensureInitialized();
+    return parseAllBugFiles(this.root);
+  }
+
+  async openBugs(): Promise<Bug[]> {
+    const all = await this.bugs();
+    return all.filter((b) => b.frontmatter.status === 'open');
+  }
+
+  async markBugResolved(paths?: string[]): Promise<string[]> {
+    this.ensureInitialized();
+    const all = await this.bugs();
+    const marked: string[] = [];
+
+    for (const bug of all) {
+      if (bug.frontmatter.status === 'resolved') continue;
+      if (paths && paths.length > 0 && !paths.includes(bug.relativePath)) continue;
+
+      const absPath = resolve(this.root, bug.relativePath);
+      const content = await readFile(absPath, 'utf-8');
+      const updated = content.replace(/^status:\s*open/m, 'status: resolved');
+      await writeFile(absPath, updated, 'utf-8');
+      marked.push(bug.relativePath);
+    }
+
+    return marked;
+  }
+
   private ensureInitialized(): void {
     if (!isSDDProject(this.root)) {
       throw new ProjectNotInitializedError(this.root);

package/src/types.ts

@@ -58,6 +58,8 @@ export interface StoryStatus {
 export interface SDDConfig {
   description: string;
   'last-sync-commit'?: string;
+  agent?: string;
+  agents?: Record<string, string>;
 }
 
 export type ChangeRequestStatus = 'draft' | 'applied';
@@ -74,3 +76,18 @@ export interface ChangeRequest {
   frontmatter: ChangeRequestFrontmatter;
   body: string;
 }
+
+export type BugStatus = 'open' | 'resolved';
+
+export interface BugFrontmatter {
+  title: string;
+  status: BugStatus;
+  author: string;
+  'created-at': string;
+}
+
+export interface Bug {
+  relativePath: string;
+  frontmatter: BugFrontmatter;
+  body: string;
+}

package/tests/apply.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect } from 'vitest';
+import { generateApplyPrompt } from '../src/prompt/apply-prompt-generator.js';
+import { resolveAgentCommand, DEFAULT_AGENTS } from '../src/agent/agent-defaults.js';
+import type { Bug, ChangeRequest, StoryFile } from '../src/types.js';
+
+function makeBug(overrides: Partial<Bug> = {}): Bug {
+  return {
+    relativePath: 'bugs/BUG-001.md',
+    frontmatter: {
+      title: 'Login button broken',
+      status: 'open',
+      author: 'test',
+      'created-at': '2024-01-01T00:00:00.000Z',
+    },
+    body: '## Description\n\nThe login button does not work.',
+    ...overrides,
+  };
+}
+
+function makeCR(overrides: Partial<ChangeRequest> = {}): ChangeRequest {
+  return {
+    relativePath: 'change-requests/CR-001.md',
+    frontmatter: {
+      title: 'Add dark mode',
+      status: 'draft',
+      author: 'test',
+      'created-at': '2024-01-01T00:00:00.000Z',
+    },
+    body: '## Changes\n\nAdd dark mode support.',
+    ...overrides,
+  };
+}
+
+function makeFile(overrides: Partial<StoryFile> = {}): StoryFile {
+  return {
+    relativePath: 'product/features/auth.md',
+    frontmatter: {
+      title: 'Auth',
+      status: 'new',
+      author: 'test',
+      'last-modified': '2024-01-01T00:00:00.000Z',
+      version: '1.0',
+    },
+    body: '# Auth Feature',
+    pendingItems: [],
+    agentNotes: null,
+    crossRefs: [],
+    hash: 'abc',
+    ...overrides,
+  };
+}
+
+describe('generateApplyPrompt', () => {
+  it('returns null when nothing to do', () => {
+    const result = generateApplyPrompt([], [], [], '/tmp');
+    expect(result).toBeNull();
+  });
+
+  it('generates prompt with only bugs', () => {
+    const prompt = generateApplyPrompt([makeBug()], [], [], '/tmp');
+    expect(prompt).not.toBeNull();
+    expect(prompt).toContain('# SDD Apply');
+    expect(prompt).toContain('Open Bugs (1)');
+    expect(prompt).toContain('Login button broken');
+    expect(prompt).toContain('bugs/BUG-001.md');
+    expect(prompt).not.toContain('Pending Change Requests');
+    expect(prompt).not.toContain('Pending Files');
+  });
+
+  it('generates prompt with only CRs', () => {
+    const prompt = generateApplyPrompt([], [makeCR()], [], '/tmp');
+    expect(prompt).not.toBeNull();
+    expect(prompt).toContain('Pending Change Requests (1)');
+    expect(prompt).toContain('Add dark mode');
+    expect(prompt).not.toContain('Open Bugs');
+    expect(prompt).not.toContain('Pending Files');
+  });
+
+  it('generates prompt with only pending files', () => {
+    const prompt = generateApplyPrompt([], [], [makeFile()], '/tmp');
+    expect(prompt).not.toBeNull();
+    expect(prompt).toContain('Pending Files (1)');
+    expect(prompt).toContain('product/features/auth.md');
+    expect(prompt).toContain('**new**');
+    expect(prompt).not.toContain('Open Bugs');
+    expect(prompt).not.toContain('Pending Change Requests');
+  });
+
+  it('generates prompt with all three', () => {
+    const prompt = generateApplyPrompt([makeBug()], [makeCR()], [makeFile()], '/tmp');
+    expect(prompt).not.toBeNull();
+    expect(prompt).toContain('Open Bugs (1)');
+    expect(prompt).toContain('Pending Change Requests (1)');
+    expect(prompt).toContain('Pending Files (1)');
+    expect(prompt).toContain('## Instructions');
+  });
+});
+
+describe('resolveAgentCommand', () => {
+  it('resolves built-in agent', () => {
+    const cmd = resolveAgentCommand('claude');
+    expect(cmd).toBe(DEFAULT_AGENTS.claude);
+  });
+
+  it('resolves config agent over built-in', () => {
+    const cmd = resolveAgentCommand('claude', { claude: 'my-claude $PROMPT' });
+    expect(cmd).toBe('my-claude $PROMPT');
+  });
+
+  it('resolves custom agent from config', () => {
+    const cmd = resolveAgentCommand('my-agent', { 'my-agent': 'my-agent-cmd $PROMPT' });
+    expect(cmd).toBe('my-agent-cmd $PROMPT');
+  });
+
+  it('returns undefined for unknown agent', () => {
+    const cmd = resolveAgentCommand('unknown');
+    expect(cmd).toBeUndefined();
+  });
+});