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

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

@@ -1,4 +1,4 @@
-export { SDD } from './sdd.js';
+export { SDD } from "./sdd.js";
 export type {
   StoryFrontmatter,
   StoryFile,
@@ -16,7 +16,19 @@ export type {
   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';
+} from "./types.js";
+export { SDDError, LockFileNotFoundError, ParseError, ProjectNotInitializedError } from "./errors.js";
+export type { ProjectInfo } from "./scaffold/templates.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";
+export { listSupportedAdapters, SKILL_ADAPTERS, syncSkillAdapters } from "./scaffold/skill-adapters.js";
+export type {
+  AdapterMode,
+  SkillAdapterDefinition,
+  SyncAdaptersOptions,
+  AdapterFileAction,
+  AdapterFileChange,
+  SyncAdaptersResult,
+} from "./scaffold/skill-adapters.js";

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

@@ -0,0 +1,58 @@
+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[] = [];
+
+  // Bugs
+  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
+  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
+  if (pendingFiles.length > 0) {
+    const lines = [`## Pending files (${pendingFiles.length})\n`];
+    for (const f of pendingFiles) {
+      lines.push(`- \`${f.relativePath}\` — **${f.frontmatter.status}**`);
+    }
+
+    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(`### Diff: \`${f.relativePath}\`\n\n\`\`\`diff\n${diff}\n\`\`\``);
+      }
+    }
+
+    sections.push(lines.join('\n'));
+  }
+
+  return sections.join('\n\n');
+}

package/src/prompt/prompt-generator.ts

@@ -2,48 +2,38 @@ import type { StoryFile } from '../types.js';
 import { getFileDiff } from '../git/git.js';
 
 export function generatePrompt(files: StoryFile[], root?: string): string {
-  const sections: string[] = [];
-
-  sections.push(
-    '# SDD Sync Prompt\n\nThis project uses Story Driven Development. Implement the changes described below.'
-  );
-
   if (files.length === 0) {
-    sections.push('Nothing to do — all files are synced.');
-    return sections.join('\n\n');
+    return 'Nothing to do — all files are synced.';
   }
 
-  const lines = [`## Files to process (${files.length})\n`];
+  const sections: string[] = [];
+
+  const lines = [`## Pending files (${files.length})\n`];
   for (const f of files) {
     lines.push(`- \`${f.relativePath}\` — **${f.frontmatter.status}**`);
   }
-  lines.push('');
-  lines.push('Read each file listed above before implementing.');
   sections.push(lines.join('\n'));
 
-  // Show git diff for changed files so the agent knows what was modified
+  // Git diff for changed files
   if (root) {
     const changed = files.filter((f) => f.frontmatter.status === 'changed');
     for (const f of changed) {
       const diff = getFileDiff(root, f.relativePath);
       if (diff) {
-        sections.push(`## Changes in \`${f.relativePath}\`\n\n\`\`\`diff\n${diff}\n\`\`\``);
+        sections.push(`## Diff: \`${f.relativePath}\`\n\n\`\`\`diff\n${diff}\n\`\`\``);
       }
     }
   }
 
+  // Deleted files
   const deleted = files.filter((f) => f.frontmatter.status === 'deleted');
   if (deleted.length > 0) {
     const delLines = ['## Files to remove\n'];
     for (const f of deleted) {
-      delLines.push(`- \`${f.relativePath}\` — remove all related code in \`code/\``);
+      delLines.push(`- \`${f.relativePath}\``);
     }
     sections.push(delLines.join('\n'));
   }
 
-  sections.push(
-    `## Instructions\n\n1. Read each file listed above\n2. For **new** files: implement what the documentation describes\n3. For **changed** files: update the code to match the updated documentation (see diff above)\n4. For **deleted** files: remove the related code from \`code/\`\n5. If a file has a \`## Agent Notes\` section, respect those constraints\n6. All code goes inside \`code/\`\n7. After implementing each file, run \`sdd mark-synced <file>\`\n8. **Immediately after mark-synced, commit**: \`git add -A && git commit -m "sdd sync: <description>"\`\n9. When done with all files, list every file you created or modified`
-  );
-
   return sections.join('\n\n');
 }

package/src/scaffold/init.ts

@@ -1,10 +1,11 @@
-import { mkdir, writeFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { AGENT_MD_TEMPLATE, type ProjectInfo } from './templates.js';
-import { writeConfig, sddDirPath } from '../config/config-manager.js';
-import { isGitRepo, gitInit } from '../git/git.js';
-import type { SDDConfig } from '../types.js';
+import { mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { type ProjectInfo } from "./templates.js";
+import { syncSkillAdapters } from "./skill-adapters.js";
+import { writeConfig, sddDirPath } from "../config/config-manager.js";
+import { isGitRepo, gitInit } from "../git/git.js";
+import type { SDDConfig } from "../types.js";
 
 export async function initProject(root: string, info?: ProjectInfo): Promise<string[]> {
   const createdFiles: string[] = [];
@@ -13,7 +14,7 @@ export async function initProject(root: string, info?: ProjectInfo): Promise<str
   // Ensure git repo
   if (!isGitRepo(root)) {
     gitInit(root);
-    createdFiles.push('.git');
+    createdFiles.push(".git");
   }
 
   // Create .sdd directory
@@ -23,13 +24,13 @@ export async function initProject(root: string, info?: ProjectInfo): Promise<str
 
   // Write config
   const config: SDDConfig = {
-    description: info?.description ?? '',
+    description: info?.description ?? "",
   };
   await writeConfig(root, config);
-  createdFiles.push('.sdd/config.yaml');
+  createdFiles.push(".sdd/config.yaml");
 
   // Create directory structure
-  const dirs = ['product', 'product/features', 'system', 'code', 'change-requests', 'bugs'];
+  const dirs = ["product", "product/features", "system", "code", "change-requests", "bugs"];
   for (const dir of dirs) {
     const absDir = resolve(root, dir);
     if (!existsSync(absDir)) {
@@ -37,34 +38,12 @@ export async function initProject(root: string, info?: ProjectInfo): Promise<str
     }
   }
 
-  // Create agent instructions
-  const instructionsPath = resolve(root, 'INSTRUCTIONS.md');
-  if (!existsSync(instructionsPath)) {
-    await writeFile(instructionsPath, AGENT_MD_TEMPLATE, 'utf-8');
-    createdFiles.push('INSTRUCTIONS.md');
-  }
-
-  // Create agent instruction pointers
-  const POINTER = 'Read INSTRUCTIONS.md in the project root for all instructions.\n';
-  const agentFiles: Array<{ path: string; dir?: string }> = [
-    { path: '.claude/CLAUDE.md', dir: '.claude' },
-    { path: '.github/copilot-instructions.md', dir: '.github' },
-    { path: '.cursorrules' },
-  ];
-
-  for (const entry of agentFiles) {
-    const absPath = resolve(root, entry.path);
-    if (existsSync(absPath)) continue;
-
-    if (entry.dir) {
-      const absDir = resolve(root, entry.dir);
-      if (!existsSync(absDir)) {
-        await mkdir(absDir, { recursive: true });
-      }
+  // Create canonical skill and agent adapters
+  const adapters = await syncSkillAdapters(root);
+  for (const change of [...adapters.canonical, ...adapters.adapters]) {
+    if (change.action === "created") {
+      createdFiles.push(change.path);
     }
-
-    await writeFile(absPath, POINTER, 'utf-8');
-    createdFiles.push(entry.path);
   }
 
   return createdFiles;

package/src/scaffold/skill-adapters.ts

@@ -0,0 +1,322 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import {
+  BUGS_REFERENCE,
+  CHANGE_REQUESTS_REFERENCE,
+  FILE_FORMAT_REFERENCE,
+  SKILL_MD_TEMPLATE,
+  SKILL_UI_MD_TEMPLATE,
+} from "./templates.js";
+
+const MANAGED_HEADER =
+  "<!-- AUTO-GENERATED BY SDD. DO NOT EDIT MANUALLY. -->\n";
+
+export type AdapterMode = "pointer" | "mirror";
+
+export interface SkillPathsDefinition {
+  skillId: string;
+  paths: string[];
+}
+
+export interface SkillAdapterDefinition {
+  id: string;
+  mode: AdapterMode;
+  skills: SkillPathsDefinition[];
+}
+
+export interface SyncAdaptersOptions {
+  agents?: string[];
+  force?: boolean;
+  dryRun?: boolean;
+}
+
+export type AdapterFileAction = "created" | "updated" | "skipped";
+
+export interface AdapterFileChange {
+  path: string;
+  action: AdapterFileAction;
+  reason?: string;
+}
+
+export interface SyncAdaptersResult {
+  canonical: AdapterFileChange[];
+  adapters: AdapterFileChange[];
+  selectedAgents: string[];
+}
+
+const CANONICAL_BASE_DIR = ".sdd/skill";
+
+const CANONICAL_SKILLS: Array<{
+  id: string;
+  files: Array<{ path: string; content: string }>;
+}> = [
+  {
+    id: "sdd",
+    files: [
+      {
+        path: `${CANONICAL_BASE_DIR}/sdd/SKILL.md`,
+        content: SKILL_MD_TEMPLATE,
+      },
+      {
+        path: `${CANONICAL_BASE_DIR}/sdd/references/file-format.md`,
+        content: FILE_FORMAT_REFERENCE,
+      },
+      {
+        path: `${CANONICAL_BASE_DIR}/sdd/references/change-requests.md`,
+        content: CHANGE_REQUESTS_REFERENCE,
+      },
+      {
+        path: `${CANONICAL_BASE_DIR}/sdd/references/bugs.md`,
+        content: BUGS_REFERENCE,
+      },
+    ],
+  },
+  {
+    id: "sdd-ui",
+    files: [
+      {
+        path: `${CANONICAL_BASE_DIR}/sdd-ui/SKILL.md`,
+        content: SKILL_UI_MD_TEMPLATE,
+      },
+    ],
+  },
+];
+
+const CANONICAL_FILES: Array<{ path: string; content: string }> =
+  CANONICAL_SKILLS.flatMap((skill) => skill.files);
+
+export interface SkillPathsDefinition {
+  skillId: string;
+  paths: string[];
+}
+
+export interface SkillAdapterDefinition {
+  id: string;
+  mode: AdapterMode;
+  skills: SkillPathsDefinition[];
+}
+
+export const SKILL_ADAPTERS: SkillAdapterDefinition[] = [
+  {
+    id: "claude",
+    mode: "mirror",
+    skills: [
+      {
+        skillId: "sdd",
+        paths: [
+          ".claude/skills/sdd/SKILL.md",
+          ".claude/skills/sdd/references/file-format.md",
+          ".claude/skills/sdd/references/change-requests.md",
+          ".claude/skills/sdd/references/bugs.md",
+        ],
+      },
+      {
+        skillId: "sdd-ui",
+        paths: [".claude/skills/sdd-ui/SKILL.md"],
+      },
+    ],
+  },
+  {
+    id: "universal",
+    mode: "mirror",
+    skills: [
+      {
+        skillId: "sdd",
+        paths: [
+          ".agents/skills/sdd/SKILL.md",
+          ".agents/skills/sdd/references/file-format.md",
+          ".agents/skills/sdd/references/change-requests.md",
+          ".agents/skills/sdd/references/bugs.md",
+        ],
+      },
+      {
+        skillId: "sdd-ui",
+        paths: [".agents/skills/sdd-ui/SKILL.md"],
+      },
+    ],
+  },
+];
+
+export function listSupportedAdapters(): string[] {
+  return SKILL_ADAPTERS.map((adapter) => adapter.id);
+}
+
+export async function syncSkillAdapters(
+  root: string,
+  options?: SyncAdaptersOptions,
+): Promise<SyncAdaptersResult> {
+  const force = options?.force ?? false;
+  const dryRun = options?.dryRun ?? false;
+  const selected = resolveSelectedAdapters(options?.agents);
+
+  // Build a map of skillId → canonical files for quick lookup
+  const canonicalFilesBySkill = new Map<
+    string,
+    Array<{ path: string; content: string }>
+  >();
+  for (const skill of CANONICAL_SKILLS) {
+    canonicalFilesBySkill.set(skill.id, skill.files);
+  }
+
+  const canonicalChanges: AdapterFileChange[] = [];
+  for (const file of CANONICAL_FILES) {
+    const change = await upsertFile(root, file.path, file.content, {
+      force,
+      dryRun,
+      managed: false,
+    });
+    canonicalChanges.push(change);
+  }
+
+  const adapterChanges: AdapterFileChange[] = [];
+  for (const adapter of selected) {
+    for (const skillDef of adapter.skills) {
+      const canonicalFiles = canonicalFilesBySkill.get(skillDef.skillId);
+
+      if (adapter.mode === "pointer") {
+        const content = buildPointerContent(adapter.id, skillDef.skillId);
+        for (const path of skillDef.paths) {
+          const change = await upsertFile(root, path, content, {
+            force,
+            dryRun,
+            managed: true,
+          });
+          adapterChanges.push(change);
+        }
+        continue;
+      }
+
+      // mirror mode: copy canonical content to adapter paths
+      if (!canonicalFiles) {
+        for (const path of skillDef.paths) {
+          adapterChanges.push({
+            path,
+            action: "skipped",
+            reason: `No canonical files found for skill "${skillDef.skillId}"`,
+          });
+        }
+        continue;
+      }
+
+      for (let i = 0; i < skillDef.paths.length; i += 1) {
+        const canonical = canonicalFiles[i];
+        if (!canonical) {
+          adapterChanges.push({
+            path: skillDef.paths[i],
+            action: "skipped",
+            reason: "No corresponding canonical source file",
+          });
+          continue;
+        }
+
+        const change = await upsertFile(
+          root,
+          skillDef.paths[i],
+          canonical.content,
+          {
+            force,
+            dryRun,
+            managed: false,
+          },
+        );
+        adapterChanges.push(change);
+      }
+    }
+  }
+
+  return {
+    canonical: canonicalChanges,
+    adapters: adapterChanges,
+    selectedAgents: selected.map((adapter) => adapter.id),
+  };
+}
+
+function resolveSelectedAdapters(agents?: string[]): SkillAdapterDefinition[] {
+  if (!agents || agents.length === 0) {
+    return SKILL_ADAPTERS;
+  }
+
+  const normalized = new Set(
+    agents.map((agent) => agent.trim().toLowerCase()).filter(Boolean),
+  );
+  const selected = SKILL_ADAPTERS.filter((adapter) =>
+    normalized.has(adapter.id),
+  );
+
+  const missing = Array.from(normalized).filter(
+    (agent) => !SKILL_ADAPTERS.some((adapter) => adapter.id === agent),
+  );
+
+  if (missing.length > 0) {
+    throw new Error(`Unsupported adapters: ${missing.join(", ")}`);
+  }
+
+  return selected;
+}
+
+function buildPointerContent(adapterId: string, skillId: string): string {
+  if (adapterId === "cursor") {
+    return `---
+description: SDD ${skillId} adapter
+alwaysApply: false
+---
+
+Read .sdd/skill/${skillId}/SKILL.md for the full SDD ${skillId} workflow.
+
+If needed, also read the references in .sdd/skill/${skillId}/references/
+`;
+  }
+
+  return `# SDD ${skillId} Adapter (${adapterId})
+
+Primary instructions: .sdd/skill/${skillId}/SKILL.md
+
+References:
+- .sdd/skill/${skillId}/references/
+
+Fallback (legacy): .claude/skills/${skillId}/SKILL.md
+`;
+}
+
+async function upsertFile(
+  root: string,
+  relativePath: string,
+  content: string,
+  options: { force: boolean; dryRun: boolean; managed: boolean },
+): Promise<AdapterFileChange> {
+  const absPath = resolve(root, relativePath);
+  const finalContent = options.managed
+    ? `${MANAGED_HEADER}${content}`
+    : content;
+
+  if (!existsSync(absPath)) {
+    if (!options.dryRun) {
+      await mkdir(dirname(absPath), { recursive: true });
+      await writeFile(absPath, finalContent, "utf-8");
+    }
+    return { path: relativePath, action: "created" };
+  }
+
+  const current = await readFile(absPath, "utf-8");
+  if (current === finalContent) {
+    return {
+      path: relativePath,
+      action: "skipped",
+      reason: "Already up to date",
+    };
+  }
+
+  if (!options.force) {
+    return {
+      path: relativePath,
+      action: "skipped",
+      reason: "Exists (use --force to overwrite)",
+    };
+  }
+
+  if (!options.dryRun) {
+    await writeFile(absPath, finalContent, "utf-8");
+  }
+  return { path: relativePath, action: "updated" };
+}