@applica-software-guru/sdd-core 1.0.0 → 1.3.3

package/src/scaffold/templates.ts

@@ -17,13 +17,30 @@ export interface ProjectInfo {
   description: string;
 }
 
-export const AGENT_MD_TEMPLATE = `# SDD Project
+export const SKILL_MD_TEMPLATE = `---
+name: sdd
+description: >
+  Story Driven Development workflow. Use when working in a project
+  with .sdd/config.yaml, or when the user mentions SDD, sdd sync,
+  story driven development, or spec-driven development.
+license: MIT
+compatibility: Requires sdd CLI (npm i -g @applica-software-guru/sdd)
+allowed-tools: Bash(sdd:*) Read Glob Grep
+metadata:
+  author: applica-software-guru
+  version: "1.0"
+---
+
+# SDD — Story Driven Development
 
-This project uses **Story Driven Development (SDD)**.
-Documentation drives implementation: read the docs first, then write code.
+## Detection
+
+This project uses SDD if \`.sdd/config.yaml\` exists in the project root.
 
 ## Workflow
 
+Follow this loop every time you work on an SDD project:
+
 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
@@ -80,7 +97,142 @@ Delete the related code in \`code/\`, then run \`sdd mark-synced <file>\` (the d
 6. Respect all constraints in \`## Agent Notes\` sections (if present)
 7. Do not edit files inside \`.sdd/\` manually
 
-## File format
+## Project structure
+
+- \`product/\` — What to build (vision, users, features)
+- \`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)
+
+## References
+
+For detailed information on specific topics, see:
+
+- [File format and status lifecycle](references/file-format.md)
+- [Change Requests workflow](references/change-requests.md)
+- [Bug workflow](references/bugs.md)
+`;
+
+export const SKILL_UI_MD_TEMPLATE = `---
+name: sdd-ui
+description: >
+  UI Component Editor workflow. Use when the user wants to implement a React component
+  from a screenshot in an SDD project, iterating visually with live preview.
+license: MIT
+compatibility: >
+  Requires sdd CLI (npm i -g @applica-software-guru/sdd).
+  Requires Playwright MCP configured in Claude Code
+  (e.g. @playwright/mcp or @executeautomation/playwright-mcp).
+allowed-tools: Bash(sdd:*) Read Glob Grep Edit Write mcp__playwright__screenshot mcp__playwright__navigate mcp__playwright__click
+metadata:
+  author: applica-software-guru
+  version: "1.1"
+---
+
+# SDD UI — Visual Component Editor
+
+## Purpose
+
+Use this workflow when implementing a React component from a screenshot reference in an SDD project.
+The split-panel editor shows the spec screenshot on the left and the live component on the right,
+so you can iterate visually until they match.
+
+## Prerequisites
+
+- \`sdd\` CLI installed globally
+- Playwright MCP configured in Claude Code settings
+  - e.g. \`@playwright/mcp\` or \`@executeautomation/playwright-mcp\`
+  - If not configured, inform the user and stop — visual feedback won't work without it
+
+## Workflow
+
+### Step 1 — Read the spec
+
+Read the SDD feature file to understand what the component should look like and do.
+Look for any screenshot paths referenced in the feature doc.
+
+### Step 2 — Launch the editor
+
+\`\`\`bash
+# Single screenshot — detached (recommended when run by an agent)
+sdd ui launch-editor LoginForm \\
+  --screenshot product/features/auth/login.png \\
+  --detach
+
+# Multiple screenshots (e.g. desktop + mobile)
+sdd ui launch-editor LoginForm \\
+  --screenshot product/features/auth/login-desktop.png \\
+  --screenshot product/features/auth/login-mobile.png \\
+  --detach
+\`\`\`
+
+The command will:
+- Scaffold \`code/components/LoginForm.tsx\` if it doesn't exist
+- Print the exact component file path to edit
+- Start the editor at \`http://localhost:5174\`
+
+With \`--detach\` the process runs in background and the terminal is immediately free.
+Without \`--detach\` it runs in foreground (use Ctrl+C to stop).
+
+With multiple screenshots, the left panel shows a tab per screenshot.
+With a single screenshot, no tab bar is shown.
+
+### Step 3 — Implement the component
+
+Edit the file printed by \`sdd ui launch-editor\` (e.g. \`code/components/LoginForm.tsx\`).
+
+Write a React component that matches the screenshot. Use standard HTML/CSS or inline styles —
+no external UI library unless the project already uses one.
+
+Vite HMR will update the right panel automatically on every save.
+
+### Step 4 — Visual check with Playwright
+
+After each save, screenshot the live preview and compare it with the spec:
+
+\`\`\`
+mcp__playwright__navigate http://localhost:5174
+mcp__playwright__screenshot
+\`\`\`
+
+The left panel already shows the spec screenshot for direct comparison.
+Note differences in layout, spacing, typography, colors, and component structure.
+
+### Step 5 — Iterate
+
+Edit component → Playwright screenshot → compare → repeat until the preview matches the spec.
+
+### Step 6 — Finalize
+
+\`\`\`bash
+sdd ui stop
+sdd mark-synced product/features/auth/login.md
+git add -A && git commit -m "sdd sync: implement LoginForm component"
+\`\`\`
+
+## Notes
+
+- The component file is permanent — it lives in \`code/components/\` and is part of your project
+- Port \`5174\` by default (not \`5173\`) to avoid conflicts with the user's app dev server
+- If the component needs props, scaffold it with hardcoded sample data for the preview
+
+## Troubleshooting
+
+**Playwright MCP not configured:**
+Stop and ask the user to add it to their Claude Code MCP settings before continuing.
+
+**Component import fails in preview:**
+Check that the component file has a valid default export and no TypeScript errors.
+
+**Port already in use:**
+\`sdd ui launch-editor LoginForm --screenshot login.png --port 5175\`
+`;
+
+export const FILE_FORMAT_REFERENCE = `# File Format and Status Lifecycle
+
+## YAML Frontmatter
 
 Every \`.md\` file in \`product/\` and \`system/\` must start with this YAML frontmatter:
 
@@ -94,13 +246,20 @@ version: "1.0"
 ---
 \`\`\`
 
-- **status**: one of:
-  - \`new\` — new file, needs to be implemented
-  - \`changed\` — modified since last sync, code needs updating
-  - \`deleted\` — feature to be removed, agent should delete related code
-  - \`synced\` — already implemented, up to date
-- **version**: patch-bump on each edit (1.0 → 1.1 → 1.2)
-- **last-modified**: ISO 8601 datetime, updated on each edit
+## Status values
+
+- **\`new\`** — new file, needs to be implemented
+- **\`changed\`** — modified since last sync, code needs updating
+- **\`deleted\`** — feature to be removed, agent should delete related code
+- **\`synced\`** — already implemented, up to date
+
+## Version
+
+Patch-bump on each edit: 1.0 → 1.1 → 1.2
+
+## Last-modified
+
+ISO 8601 datetime, updated on each edit.
 
 ## How sync works
 
@@ -112,11 +271,37 @@ version: "1.0"
 
 This is why **committing after every mark-synced is mandatory** — the git history is what SDD uses to detect changes.
 
-## Change Requests
+## UX and screenshots
+
+When a feature has UX mockups or screenshots, place them next to the feature doc:
+
+- **Simple feature** (no screenshots): \`product/features/auth.md\`
+- **Feature with screenshots**: use a folder with \`index.md\`:
+
+\`\`\`
+product/features/auth/
+  index.md          ← feature doc
+  login.png         ← screenshot
+  register.png      ← screenshot
+\`\`\`
+
+Reference images in the markdown with relative paths:
+
+\`\`\`markdown
+## UX
+
+![Login screen](login.png)
+![Register screen](register.png)
+\`\`\`
+
+Both formats work — use a folder only when you have screenshots or multiple files for a feature.
+`;
+
+export const CHANGE_REQUESTS_REFERENCE = `# Change Requests
 
 Change Requests (CRs) are markdown files in \`change-requests/\` that describe modifications to the documentation.
 
-### CR format
+## CR format
 
 \`\`\`yaml
 ---
@@ -129,24 +314,25 @@ created-at: "2025-01-01T00:00:00.000Z"
 
 - **status**: \`draft\` (pending) or \`applied\` (already processed)
 
-### CR workflow
+## CR workflow
 
 1. Check for pending CRs: \`sdd cr pending\`
 2. Read each pending CR and apply the described changes to the documentation files (marking them as \`new\`, \`changed\`, or \`deleted\`)
 3. After applying a CR to the docs, mark it: \`sdd mark-cr-applied change-requests/CR-001.md\`
 4. Then run \`sdd sync\` to implement the code changes
 
-### CR commands
+## CR commands
 
 - \`sdd cr list\` — See all change requests and their status
 - \`sdd cr pending\` — Show only draft CRs to process
 - \`sdd mark-cr-applied [files...]\` — Mark CRs as applied after updating the docs
+`;
 
-## Bugs
+export const BUGS_REFERENCE = `# Bugs
 
 Bugs are markdown files in \`bugs/\` that describe problems found in the codebase.
 
-### Bug format
+## Bug format
 
 \`\`\`yaml
 ---
@@ -159,54 +345,21 @@ created-at: "2025-01-01T00:00:00.000Z"
 
 - **status**: \`open\` (needs fixing) or \`resolved\` (already fixed)
 
-### Bug workflow
+## 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
+## 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:
-
-- **Simple feature** (no screenshots): \`product/features/auth.md\`
-- **Feature with screenshots**: use a folder with \`index.md\`:
-
-\`\`\`
-product/features/auth/
-  index.md          ← feature doc
-  login.png         ← screenshot
-  register.png      ← screenshot
-\`\`\`
-
-Reference images in the markdown with relative paths:
-
-\`\`\`markdown
-## UX
-
-![Login screen](login.png)
-![Register screen](register.png)
-\`\`\`
-
-Both formats work — use a folder only when you have screenshots or multiple files for a feature.
-
-## Project structure
-
-- \`product/\` — What to build (vision, users, features)
-- \`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)
 `;
 
-export const EMPTY_LOCK_TEMPLATE = () => `synced-at: "${new Date().toISOString()}"
+export const EMPTY_LOCK_TEMPLATE =
+  () => `synced-at: "${new Date().toISOString()}"
 files: {}
 `;

package/src/sdd.ts

@@ -1,15 +1,22 @@
-import { readFile, writeFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
-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 { 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';
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+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";
+import {
+  listSupportedAdapters,
+  syncSkillAdapters,
+  type SyncAdaptersOptions,
+  type SyncAdaptersResult,
+} from "./scaffold/skill-adapters.js";
 
 export class SDD {
   private root: string;
@@ -22,6 +29,15 @@ export class SDD {
     return initProject(this.root, info);
   }
 
+  async syncAdapters(options?: SyncAdaptersOptions): Promise<SyncAdaptersResult> {
+    this.ensureInitialized();
+    return syncSkillAdapters(this.root, options);
+  }
+
+  supportedAdapters(): string[] {
+    return listSupportedAdapters();
+  }
+
   async config(): Promise<SDDConfig> {
     this.ensureInitialized();
     return readConfig(this.root);
@@ -36,15 +52,15 @@ export class SDD {
         relativePath: f.relativePath,
         status: f.frontmatter.status,
         version: f.frontmatter.version,
-        lastModified: f.frontmatter['last-modified'],
+        lastModified: f.frontmatter["last-modified"],
       })),
     };
   }
 
-  async pending(): Promise<import('./types.js').StoryFile[]> {
+  async pending(): Promise<import("./types.js").StoryFile[]> {
     this.ensureInitialized();
     const files = await parseAllStoryFiles(this.root);
-    return files.filter((f) => f.frontmatter.status !== 'synced');
+    return files.filter((f) => f.frontmatter.status !== "synced");
   }
 
   async sync(): Promise<string> {
@@ -52,6 +68,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);
@@ -65,21 +91,21 @@ export class SDD {
 
     for (const file of files) {
       const { status } = file.frontmatter;
-      if (status === 'synced') continue;
+      if (status === "synced") continue;
       if (paths && paths.length > 0 && !paths.includes(file.relativePath)) continue;
 
       const absPath = resolve(this.root, file.relativePath);
 
-      if (status === 'deleted') {
+      if (status === "deleted") {
         // File marked for deletion — remove it
-        const { unlink } = await import('node:fs/promises');
+        const { unlink } = await import("node:fs/promises");
         await unlink(absPath);
         marked.push(`${file.relativePath} (removed)`);
       } else {
         // new or changed → synced
-        const content = await readFile(absPath, 'utf-8');
-        const updated = content.replace(/^status:\s*(new|changed)/m, 'status: synced');
-        await writeFile(absPath, updated, 'utf-8');
+        const content = await readFile(absPath, "utf-8");
+        const updated = content.replace(/^status:\s*(new|changed)/m, "status: synced");
+        await writeFile(absPath, updated, "utf-8");
         marked.push(file.relativePath);
       }
     }
@@ -94,7 +120,7 @@ export class SDD {
 
   async pendingChangeRequests(): Promise<ChangeRequest[]> {
     const all = await this.changeRequests();
-    return all.filter((cr) => cr.frontmatter.status === 'draft');
+    return all.filter((cr) => cr.frontmatter.status === "draft");
   }
 
   async markCRApplied(paths?: string[]): Promise<string[]> {
@@ -103,13 +129,13 @@ export class SDD {
     const marked: string[] = [];
 
     for (const cr of all) {
-      if (cr.frontmatter.status === 'applied') continue;
+      if (cr.frontmatter.status === "applied") continue;
       if (paths && paths.length > 0 && !paths.includes(cr.relativePath)) continue;
 
       const absPath = resolve(this.root, cr.relativePath);
-      const content = await readFile(absPath, 'utf-8');
-      const updated = content.replace(/^status:\s*draft/m, 'status: applied');
-      await writeFile(absPath, updated, 'utf-8');
+      const content = await readFile(absPath, "utf-8");
+      const updated = content.replace(/^status:\s*draft/m, "status: applied");
+      await writeFile(absPath, updated, "utf-8");
       marked.push(cr.relativePath);
     }
 
@@ -123,7 +149,7 @@ export class SDD {
 
   async openBugs(): Promise<Bug[]> {
     const all = await this.bugs();
-    return all.filter((b) => b.frontmatter.status === 'open');
+    return all.filter((b) => b.frontmatter.status === "open");
   }
 
   async markBugResolved(paths?: string[]): Promise<string[]> {
@@ -132,13 +158,13 @@ export class SDD {
     const marked: string[] = [];
 
     for (const bug of all) {
-      if (bug.frontmatter.status === 'resolved') continue;
+      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');
+      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);
     }
 

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';

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();
+  });
+});