@specmarket/cli 0.0.4 → 0.0.6

package/src/lib/meta-instructions.ts

@@ -0,0 +1,562 @@
+import { readFile, readdir } from 'fs/promises';
+import { join } from 'path';
+import { parse as parseYaml } from 'yaml';
+import { fileExists, directoryExists } from './format-detection.js';
+import { SIDECAR_FILENAME } from '@specmarket/shared';
+
+/** Filename for generated meta-instructions in the run directory */
+export const META_INSTRUCTION_FILENAME = '.specmarket-runner.md';
+
+interface SidecarData {
+  display_name?: string;
+  description?: string;
+  spec_format?: string;
+}
+
+/** Read display_name and description from specmarket.yaml if present */
+async function readSidecarData(dir: string): Promise<SidecarData> {
+  const sidecarPath = join(dir, SIDECAR_FILENAME);
+  if (!(await fileExists(sidecarPath))) return {};
+  try {
+    const raw = await readFile(sidecarPath, 'utf-8');
+    const parsed = parseYaml(raw) as unknown;
+    if (parsed && typeof parsed === 'object') {
+      const d = parsed as Record<string, unknown>;
+      return {
+        display_name: typeof d['display_name'] === 'string' ? d['display_name'] : undefined,
+        description: typeof d['description'] === 'string' ? d['description'] : undefined,
+        spec_format: typeof d['spec_format'] === 'string' ? d['spec_format'] : undefined,
+      };
+    }
+  } catch {
+    // Non-fatal — proceed without sidecar data
+  }
+  return {};
+}
+
+/**
+ * Return a numerically-sorted list of story-*.md filenames in the directory.
+ *
+ * Uses numeric sort so story-10.md follows story-9.md, not story-1.md.
+ * Extracts the leading number from the filename stem (e.g. "story-02" → 2).
+ * Files without a parseable number sort after numbered files, then lexicographically.
+ */
+async function listStoryFiles(dir: string): Promise<string[]> {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries
+      .filter((e) => e.isFile() && e.name.startsWith('story-') && e.name.endsWith('.md'))
+      .map((e) => e.name)
+      .sort((a, b) => {
+        const numA = parseInt(a.replace(/^story-(\d+).*/, '$1'), 10);
+        const numB = parseInt(b.replace(/^story-(\d+).*/, '$1'), 10);
+        if (!isNaN(numA) && !isNaN(numB)) return numA - numB;
+        if (!isNaN(numA)) return -1;
+        if (!isNaN(numB)) return 1;
+        return a.localeCompare(b);
+      });
+  } catch {
+    return [];
+  }
+}
+
+/** Return files from the candidates list that actually exist in dir */
+async function presentFiles(dir: string, candidates: string[]): Promise<string[]> {
+  const found: string[] = [];
+  for (const f of candidates) {
+    if (await fileExists(join(dir, f))) found.push(f);
+  }
+  return found;
+}
+
+/** Shared preamble block */
+function preamble(sidecar: SidecarData): string {
+  const lines: string[] = [
+    '# SpecMarket Runner Instructions',
+    '',
+    'You are an AI coding agent executing a software specification.',
+    'Read this file carefully before starting work. Follow the instructions exactly.',
+  ];
+  if (sidecar.display_name) {
+    lines.push('', `**Spec:** ${sidecar.display_name}`);
+  }
+  if (sidecar.description) {
+    lines.push(`**Description:** ${sidecar.description}`);
+  }
+  return lines.join('\n');
+}
+
+/** Shared testing section */
+function testingSection(): string {
+  return [
+    '## Running Tests',
+    '',
+    'After completing each major task, run the test suite:',
+    '',
+    '- `package.json` present → `npm test -- --run` (or `npx vitest run` if vitest is configured)',
+    '- `pytest.ini` or `pyproject.toml` present → `python -m pytest`',
+    '- `Makefile` with `test` target → `make test`',
+    '- No test runner found → verify functionality manually by running the application',
+    '',
+    'Fix all test failures before proceeding to the next task.',
+  ].join('\n');
+}
+
+/** Shared completion reminder */
+function completionReminder(): string {
+  return [
+    '## Important Reminders',
+    '',
+    '- Only mark a task complete when you have **fully implemented and tested** it.',
+    '- Do not skip tasks. Do not leave stubs or placeholders.',
+    '- If you discover a blocking issue, note it in the relevant task file and continue with other tasks if possible.',
+    '- Run the full test suite one final time before declaring the spec complete.',
+  ].join('\n');
+}
+
+// ── Format-specific generators ──────────────────────────────────────────────
+
+/**
+ * Generate meta-instructions for the native `specmarket` format.
+ *
+ * Layout: spec.yaml + PROMPT.md + SPEC.md + SUCCESS_CRITERIA.md + stdlib/
+ * Tasks tracked in TASKS.md (or implicitly via SUCCESS_CRITERIA.md checkboxes).
+ */
+async function generateSpecmarketInstructions(
+  dir: string,
+  sidecar: SidecarData
+): Promise<string> {
+  const coreFiles = await presentFiles(dir, [
+    'PROMPT.md',
+    'SPEC.md',
+    'SUCCESS_CRITERIA.md',
+    'TASKS.md',
+    'spec.yaml',
+    'stdlib/STACK.md',
+    'stdlib/PATTERNS.md',
+    'stdlib/SECURITY.md',
+  ]);
+
+  const fileList = coreFiles.length > 0
+    ? coreFiles.map((f) => `- \`${f}\``).join('\n')
+    : '- *(no standard spec files found — inspect directory contents)*';
+
+  // Build reading order prose only for files that are actually present
+  const readingOrderParts: string[] = [];
+  if (coreFiles.includes('PROMPT.md')) {
+    readingOrderParts.push('`PROMPT.md` for the high-level goal');
+  }
+  if (coreFiles.includes('SPEC.md')) {
+    readingOrderParts.push('`SPEC.md` for full requirements');
+  }
+  if (coreFiles.includes('SUCCESS_CRITERIA.md')) {
+    readingOrderParts.push('`SUCCESS_CRITERIA.md` to understand exactly what "done" means');
+  }
+  const readingOrder = readingOrderParts.length > 0
+    ? `Start with ${readingOrderParts.join(', then ')}.`
+    : 'Read all available files to understand the spec requirements.';
+  const stackNote = coreFiles.some((f) => f.startsWith('stdlib/'))
+    ? '\nRead `stdlib/STACK.md` for technology and coding standards before writing any code.'
+    : '';
+
+  return [
+    preamble(sidecar),
+    '',
+    '## Spec Format: SpecMarket (Native)',
+    '',
+    '## Files to Read First',
+    '',
+    fileList,
+    '',
+    readingOrder + stackNote,
+    '',
+    '## Finding Tasks',
+    '',
+    'Tasks are tracked in `TASKS.md` using this format:',
+    '',
+    '```',
+    '- [ ] Incomplete task',
+    '- [x] Completed task',
+    '```',
+    '',
+    coreFiles.includes('SPEC.md')
+      ? 'If `TASKS.md` does not exist, derive tasks from `SPEC.md` and `SUCCESS_CRITERIA.md`.'
+      : 'If `TASKS.md` does not exist, derive tasks from the available spec files.',
+    'Work through tasks from top to bottom. Complete each fully before moving to the next.',
+    '',
+    '## Marking Tasks Complete',
+    '',
+    'When a task is done, update `TASKS.md`:',
+    '- Change `- [ ]` to `- [x]` for the completed task.',
+    '',
+    '## Completion Criteria',
+    '',
+    'The run is complete when ALL of the following are true:',
+    '',
+    '1. **All tasks checked** — No `- [ ]` lines remain in `TASKS.md`.',
+    '2. **Tests pass** — Run the test suite; all tests green.',
+    '3. **Success criteria met** — Every criterion in `SUCCESS_CRITERIA.md` is checked `- [x]`.',
+    '   Update each criterion in `SUCCESS_CRITERIA.md` as it is satisfied.',
+    '',
+    testingSection(),
+    '',
+    completionReminder(),
+  ].join('\n');
+}
+
+/**
+ * Generate meta-instructions for the `speckit` format.
+ *
+ * Layout: spec.md + tasks.md (or plan.md) + optional .specify/
+ * Tasks tracked in tasks.md or plan.md.
+ */
+async function generateSpeckitInstructions(
+  dir: string,
+  sidecar: SidecarData
+): Promise<string> {
+  const hasTasksMd = await fileExists(join(dir, 'tasks.md'));
+  const hasPlanMd = await fileExists(join(dir, 'plan.md'));
+  const hasSpecifyDir = await directoryExists(join(dir, '.specify'));
+
+  const taskFile = hasTasksMd ? 'tasks.md' : hasPlanMd ? 'plan.md' : 'tasks.md';
+
+  const knownFiles = await presentFiles(dir, [
+    'spec.md',
+    'tasks.md',
+    'plan.md',
+    'requirements.md',
+    'README.md',
+  ]);
+
+  const fileList = knownFiles.length > 0
+    ? knownFiles.map((f) => `- \`${f}\``).join('\n')
+    : '- `spec.md` — primary specification';
+
+  const specifyNote = hasSpecifyDir
+    ? '\nThe `.specify/` directory contains additional context files. Read them for implementation details.\n'
+    : '';
+
+  return [
+    preamble(sidecar),
+    '',
+    '## Spec Format: Spec Kit',
+    '',
+    '## Files to Read First',
+    '',
+    fileList,
+    specifyNote,
+    'Start with `spec.md` for the full specification.',
+    `Then read \`${taskFile}\` to find your task list.`,
+    '',
+    '## Finding Tasks',
+    '',
+    `Tasks are listed in \`${taskFile}\`. Look for checkbox items:`,
+    '',
+    '```',
+    '- [ ] Incomplete task',
+    '- [x] Completed task',
+    '```',
+    '',
+    'If the task file uses numbered lists or headings instead of checkboxes,',
+    'treat each actionable item as a task. Work through them in order.',
+    '',
+    '## Marking Tasks Complete',
+    '',
+    `When a task is done, update \`${taskFile}\`:`,
+    '- Change `- [ ]` to `- [x]` for the completed task.',
+    '- If using a different format, add `[DONE]` next to the completed item.',
+    '',
+    '## Completion Criteria',
+    '',
+    'The run is complete when:',
+    '',
+    `1. **All tasks checked** — No unchecked \`- [ ]\` items remain in \`${taskFile}\`.`,
+    '2. **Tests pass** — Run the test suite; all tests green.',
+    '3. **Spec satisfied** — Implementation matches all requirements in `spec.md`.',
+    '',
+    testingSection(),
+    '',
+    completionReminder(),
+  ].join('\n');
+}
+
+/**
+ * Generate meta-instructions for the `bmad` format (BMAD Method).
+ *
+ * Layout: prd.md + architecture.md + story-*.md files.
+ * Each story-*.md is a user story with acceptance criteria.
+ */
+async function generateBmadInstructions(
+  dir: string,
+  sidecar: SidecarData
+): Promise<string> {
+  const storyFiles = await listStoryFiles(dir);
+  const coreFiles = await presentFiles(dir, ['prd.md', 'architecture.md', 'epic.md']);
+
+  const coreFileList = coreFiles.map((f) => `- \`${f}\``).join('\n') || '- *(no core files found)*';
+
+  const storySection = storyFiles.length > 0
+    ? [
+        '**Story files found:**',
+        ...storyFiles.map((f) => `- \`${f}\``),
+      ].join('\n')
+    : '*(No story-*.md files found — check prd.md for tasks)*';
+
+  return [
+    preamble(sidecar),
+    '',
+    '## Spec Format: BMAD Method',
+    '',
+    '## Files to Read First',
+    '',
+    coreFileList,
+    '',
+    'Start with `prd.md` for product requirements. Read `architecture.md` for technical design.',
+    'Then read each story file in order.',
+    '',
+    '## Finding Tasks',
+    '',
+    'Work is organized as user stories in `story-*.md` files:',
+    '',
+    storySection,
+    '',
+    'Each story file contains:',
+    '- Story description and goal',
+    '- Acceptance criteria (what must be true for the story to be complete)',
+    '- Technical notes',
+    '',
+    'If no story files exist, derive tasks from `prd.md`.',
+    '',
+    '## Marking Tasks Complete',
+    '',
+    'For each story:',
+    '1. Implement everything required by the acceptance criteria.',
+    '2. Mark each acceptance criterion as met in the story file by checking it: `- [ ]` → `- [x]`.',
+    '3. Add a `## Status: Done` line at the top of the story file when all criteria are met.',
+    '',
+    'If working from `prd.md` directly, add a `Done:` checklist section as you complete items.',
+    '',
+    '## Completion Criteria',
+    '',
+    'The run is complete when:',
+    '',
+    '1. **All stories done** — Every `story-*.md` has `Status: Done` and all acceptance criteria checked.',
+    '   (Or: all tasks in `prd.md` implemented if no story files.)',
+    '2. **Tests pass** — Run the test suite; all tests green.',
+    '3. **Architecture followed** — Implementation matches the design in `architecture.md`.',
+    '',
+    testingSection(),
+    '',
+    completionReminder(),
+  ].join('\n');
+}
+
+/**
+ * Generate meta-instructions for the `ralph` format.
+ *
+ * Layout: prd.json with userStories[] array.
+ * Each user story is an atomic unit of work.
+ */
+async function generateRalphInstructions(
+  dir: string,
+  sidecar: SidecarData
+): Promise<string> {
+  // Try to read user story titles from prd.json for a concrete task list
+  let userStoryList = '';
+  try {
+    const raw = await readFile(join(dir, 'prd.json'), 'utf-8');
+    const data = JSON.parse(raw) as unknown;
+    if (
+      data &&
+      typeof data === 'object' &&
+      'userStories' in data &&
+      Array.isArray((data as { userStories: unknown[] }).userStories)
+    ) {
+      const stories = (data as { userStories: Array<Record<string, unknown>> }).userStories;
+      const titles = stories
+        .map((s, i) => {
+          const title =
+            typeof s['title'] === 'string'
+              ? s['title']
+              : typeof s['name'] === 'string'
+              ? s['name']
+              : `Story ${i + 1}`;
+          return `- [ ] ${title}`;
+        })
+        .join('\n');
+      userStoryList = titles
+        ? `\n**User stories in prd.json:**\n\n${titles}\n`
+        : '';
+    }
+  } catch {
+    // Non-fatal — prd.json may be unreadable at generation time
+  }
+
+  const extraFiles = await presentFiles(dir, [
+    'architecture.md',
+    'README.md',
+    'CONTRIBUTING.md',
+  ]);
+  const extraFileList = extraFiles.length > 0
+    ? '\n**Additional files:**\n' + extraFiles.map((f) => `- \`${f}\``).join('\n')
+    : '';
+
+  return [
+    preamble(sidecar),
+    '',
+    '## Spec Format: Ralph',
+    '',
+    '## Files to Read First',
+    '',
+    '- `prd.json` — Product requirements document with user stories',
+    extraFileList,
+    '',
+    'Read `prd.json` carefully. The `userStories` array defines all the work to be done.',
+    '',
+    '## Finding Tasks',
+    '',
+    'Open `prd.json` and read the `userStories` array. Each entry is a task.',
+    userStoryList,
+    'Each user story typically has:',
+    '- `title` or `name` — what to build',
+    '- `description` or `details` — how to build it',
+    '- `acceptanceCriteria` — what must be true for the story to be complete',
+    '',
+    '## Marking Tasks Complete',
+    '',
+    'Ralph format does not have a built-in task-tracking file.',
+    'Create a `PROGRESS.md` file in the working directory and track progress there:',
+    '',
+    '```markdown',
+    '# Progress',
+    '',
+    '- [x] Story title (completed)',
+    '- [ ] Next story title',
+    '```',
+    '',
+    'Update `PROGRESS.md` as you complete each user story.',
+    '',
+    '## Completion Criteria',
+    '',
+    'The run is complete when:',
+    '',
+    '1. **All user stories implemented** — Every story in `prd.json` has a working implementation.',
+    '2. **All acceptance criteria met** — Verify each story\'s `acceptanceCriteria` is satisfied.',
+    '3. **Tests pass** — Run the test suite; all tests green.',
+    '4. **PROGRESS.md updated** — All stories checked `[x]` in `PROGRESS.md`.',
+    '',
+    testingSection(),
+    '',
+    completionReminder(),
+  ].join('\n');
+}
+
+/**
+ * Generate meta-instructions for `custom` format specs.
+ *
+ * Layout: arbitrary markdown files — no fixed structure.
+ * Agent must discover tasks from whatever is present.
+ */
+async function generateCustomInstructions(
+  dir: string,
+  sidecar: SidecarData
+): Promise<string> {
+  // Enumerate markdown files at top level (non-recursive for brevity)
+  let mdFiles: string[] = [];
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    mdFiles = entries
+      .filter((e) => e.isFile() && e.name.endsWith('.md'))
+      .map((e) => e.name)
+      .sort();
+  } catch {
+    // Ignore
+  }
+
+  const mdFileList = mdFiles.length > 0
+    ? mdFiles.map((f) => `- \`${f}\``).join('\n')
+    : '- *(no .md files found at top level)*';
+
+  return [
+    preamble(sidecar),
+    '',
+    '## Spec Format: Custom',
+    '',
+    '## Files to Read First',
+    '',
+    'Markdown files found in this spec:',
+    '',
+    mdFileList,
+    '',
+    'Read all markdown files to understand the full scope of work.',
+    'Look for a README, specification, or requirements document as your primary source of truth.',
+    '',
+    '## Finding Tasks',
+    '',
+    'This spec uses a custom format. Scan all markdown files for:',
+    '',
+    '1. **Checkbox items**: `- [ ] task description` — these are explicit tasks',
+    '2. **Numbered lists**: actionable steps in requirements documents',
+    '3. **Heading-based sections**: major features or modules to implement',
+    '',
+    'If you find a file that looks like a task list (TASKS.md, TODO.md, checklist.md, etc.), use it.',
+    '',
+    '## Marking Tasks Complete',
+    '',
+    'If the spec has checkboxes (`- [ ]`), update them to `- [x]` as you complete tasks.',
+    '',
+    'If the spec has no checkboxes, create a `PROGRESS.md` file to track progress:',
+    '',
+    '```markdown',
+    '# Progress',
+    '',
+    '- [x] Task or feature completed',
+    '- [ ] Next task',
+    '```',
+    '',
+    '## Completion Criteria',
+    '',
+    'The run is complete when:',
+    '',
+    '1. **All tasks done** — All checkbox items checked, or all items in `PROGRESS.md` checked.',
+    '2. **Tests pass** — Run the test suite; all tests green.',
+    '3. **Requirements satisfied** — Implementation matches all requirements found in the spec files.',
+    '',
+    testingSection(),
+    '',
+    completionReminder(),
+  ].join('\n');
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Generate format-aware meta-instructions for the AI agent executing a spec.
+ *
+ * Returns the full markdown content for `.specmarket-runner.md`.
+ * The content tells the agent: which files to read, how to find tasks,
+ * how to mark completion, how to run tests, and when the run is done.
+ *
+ * @param specDir - Path to the spec source directory (may differ from runDir)
+ * @param format  - Detected spec format (specmarket | speckit | bmad | ralph | custom | any string)
+ */
+export async function generateMetaInstructions(
+  specDir: string,
+  format: string
+): Promise<string> {
+  const sidecar = await readSidecarData(specDir);
+
+  switch (format) {
+    case 'specmarket':
+      return generateSpecmarketInstructions(specDir, sidecar);
+    case 'speckit':
+      return generateSpeckitInstructions(specDir, sidecar);
+    case 'bmad':
+      return generateBmadInstructions(specDir, sidecar);
+    case 'ralph':
+      return generateRalphInstructions(specDir, sidecar);
+    case 'custom':
+    default:
+      return generateCustomInstructions(specDir, sidecar);
+  }
+}