gsd-remix 1.0.0

package/sdk/src/prompt-builder.test.ts

@@ -0,0 +1,306 @@
+/**
+ * Unit tests for prompt-builder.ts
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  buildExecutorPrompt,
+  parseAgentTools,
+  parseAgentRole,
+  DEFAULT_ALLOWED_TOOLS,
+} from './prompt-builder.js';
+import type { ParsedPlan, PlanFrontmatter, MustHaves } from './types.js';
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function makePlan(overrides: Partial<ParsedPlan> = {}): ParsedPlan {
+  const defaultFrontmatter: PlanFrontmatter = {
+    phase: '01-auth',
+    plan: '01',
+    type: 'execute',
+    wave: 1,
+    depends_on: [],
+    files_modified: [],
+    autonomous: true,
+    requirements: ['AUTH-01'],
+    must_haves: { truths: [], artifacts: [], key_links: [] },
+  };
+
+  return {
+    frontmatter: { ...defaultFrontmatter, ...overrides.frontmatter },
+    objective: overrides.objective ?? 'Implement JWT authentication with refresh tokens',
+    execution_context: overrides.execution_context ?? [],
+    context_refs: overrides.context_refs ?? [],
+    tasks: overrides.tasks ?? [
+      {
+        type: 'auto',
+        name: 'Create auth module',
+        files: ['src/auth.ts'],
+        read_first: ['src/types.ts'],
+        action: 'Create the auth module with login and refresh endpoints',
+        verify: 'npm test -- --filter auth',
+        acceptance_criteria: ['JWT tokens issued on login', 'Refresh tokens rotate correctly'],
+        done: 'Auth module created and tests pass',
+      },
+      {
+        type: 'auto',
+        name: 'Add middleware',
+        files: ['src/middleware.ts'],
+        read_first: [],
+        action: 'Create auth middleware for protected routes',
+        verify: 'npm test -- --filter middleware',
+        acceptance_criteria: [],
+        done: 'Middleware validates JWT on protected routes',
+      },
+    ],
+    raw: '',
+  };
+}
+
+const SAMPLE_AGENT_DEF = `---
+name: gsd-executor
+description: Executes GSD plans
+tools: Read, Write, Edit, Bash, Grep, Glob
+permissionMode: acceptEdits
+---
+
+<role>
+You are a GSD plan executor. You execute PLAN.md files atomically.
+</role>
+
+<execution_flow>
+Some flow content
+</execution_flow>`;
+
+// ─── parseAgentTools ─────────────────────────────────────────────────────────
+
+describe('parseAgentTools', () => {
+  it('extracts tools from agent definition frontmatter', () => {
+    const tools = parseAgentTools(SAMPLE_AGENT_DEF);
+    expect(tools).toEqual(['Read', 'Write', 'Edit', 'Bash', 'Grep', 'Glob']);
+  });
+
+  it('returns defaults when no frontmatter found', () => {
+    const tools = parseAgentTools('Just some text without frontmatter');
+    expect(tools).toEqual(DEFAULT_ALLOWED_TOOLS);
+  });
+
+  it('returns defaults when frontmatter has no tools key', () => {
+    const def = `---\nname: test\n---\nContent`;
+    const tools = parseAgentTools(def);
+    expect(tools).toEqual(DEFAULT_ALLOWED_TOOLS);
+  });
+
+  it('handles empty tools value', () => {
+    const def = `---\ntools: \n---`;
+    const tools = parseAgentTools(def);
+    expect(tools).toEqual(DEFAULT_ALLOWED_TOOLS);
+  });
+});
+
+// ─── parseAgentRole ──────────────────────────────────────────────────────────
+
+describe('parseAgentRole', () => {
+  it('extracts role content from agent definition', () => {
+    const role = parseAgentRole(SAMPLE_AGENT_DEF);
+    expect(role).toContain('GSD plan executor');
+    expect(role).toContain('PLAN.md files atomically');
+  });
+
+  it('returns empty string when no role block', () => {
+    expect(parseAgentRole('No role block here')).toBe('');
+  });
+});
+
+// ─── buildExecutorPrompt ─────────────────────────────────────────────────────
+
+describe('buildExecutorPrompt', () => {
+  it('includes the objective text', () => {
+    const plan = makePlan();
+    const prompt = buildExecutorPrompt(plan);
+    expect(prompt).toContain('Implement JWT authentication with refresh tokens');
+  });
+
+  it('includes all task names', () => {
+    const plan = makePlan();
+    const prompt = buildExecutorPrompt(plan);
+    expect(prompt).toContain('Create auth module');
+    expect(prompt).toContain('Add middleware');
+  });
+
+  it('includes task actions', () => {
+    const plan = makePlan();
+    const prompt = buildExecutorPrompt(plan);
+    expect(prompt).toContain('Create the auth module with login and refresh endpoints');
+    expect(prompt).toContain('Create auth middleware for protected routes');
+  });
+
+  it('includes task verification commands', () => {
+    const plan = makePlan();
+    const prompt = buildExecutorPrompt(plan);
+    expect(prompt).toContain('npm test -- --filter auth');
+    expect(prompt).toContain('npm test -- --filter middleware');
+  });
+
+  it('includes task file references', () => {
+    const plan = makePlan();
+    const prompt = buildExecutorPrompt(plan);
+    expect(prompt).toContain('src/auth.ts');
+    expect(prompt).toContain('src/types.ts');
+  });
+
+  it('includes acceptance criteria', () => {
+    const plan = makePlan();
+    const prompt = buildExecutorPrompt(plan);
+    expect(prompt).toContain('JWT tokens issued on login');
+    expect(prompt).toContain('Refresh tokens rotate correctly');
+  });
+
+  it('includes SUMMARY.md creation instruction', () => {
+    const plan = makePlan();
+    const prompt = buildExecutorPrompt(plan);
+    expect(prompt).toContain('SUMMARY.md');
+    expect(prompt).toContain('Create a SUMMARY.md file');
+  });
+
+  it('includes sequential execution instruction', () => {
+    const plan = makePlan();
+    const prompt = buildExecutorPrompt(plan);
+    expect(prompt).toContain('Execute these tasks sequentially');
+  });
+
+  it('handles plan with no tasks gracefully', () => {
+    const plan = makePlan({ tasks: [] });
+    const prompt = buildExecutorPrompt(plan);
+    expect(prompt).toContain('No tasks defined');
+    expect(prompt).toContain('SUMMARY.md');
+    // Should not throw
+    expect(prompt.length).toBeGreaterThan(0);
+  });
+
+  it('includes context references when present', () => {
+    const plan = makePlan({
+      context_refs: ['src/config.ts', 'docs/architecture.md'],
+    });
+    const prompt = buildExecutorPrompt(plan);
+    expect(prompt).toContain('@src/config.ts');
+    expect(prompt).toContain('@docs/architecture.md');
+    expect(prompt).toContain('Read these files for context');
+  });
+
+  it('omits context section when no refs', () => {
+    const plan = makePlan({ context_refs: [] });
+    const prompt = buildExecutorPrompt(plan);
+    expect(prompt).not.toContain('Context Files');
+  });
+
+  it('includes plan metadata', () => {
+    const plan = makePlan();
+    const prompt = buildExecutorPrompt(plan);
+    expect(prompt).toContain('Phase: 01-auth');
+    expect(prompt).toContain('Plan: 01');
+  });
+
+  it('includes must-have truths when present', () => {
+    const plan = makePlan({
+      frontmatter: {
+        phase: '01',
+        plan: '01',
+        type: 'execute',
+        wave: 1,
+        depends_on: [],
+        files_modified: [],
+        autonomous: true,
+        requirements: [],
+        must_haves: {
+          truths: ['All endpoints require JWT auth', 'Tokens expire after 15 minutes'],
+          artifacts: [],
+          key_links: [],
+        },
+      },
+    });
+    const prompt = buildExecutorPrompt(plan);
+    expect(prompt).toContain('All endpoints require JWT auth');
+    expect(prompt).toContain('Tokens expire after 15 minutes');
+  });
+
+  it('includes must-have artifacts', () => {
+    const plan = makePlan({
+      frontmatter: {
+        phase: '01',
+        plan: '01',
+        type: 'execute',
+        wave: 1,
+        depends_on: [],
+        files_modified: [],
+        autonomous: true,
+        requirements: [],
+        must_haves: {
+          truths: [],
+          artifacts: [{ path: 'src/auth.ts', provides: 'JWT auth module' }],
+          key_links: [],
+        },
+      },
+    });
+    const prompt = buildExecutorPrompt(plan);
+    expect(prompt).toContain('`src/auth.ts`');
+    expect(prompt).toContain('JWT auth module');
+  });
+
+  it('includes must-have key_links', () => {
+    const plan = makePlan({
+      frontmatter: {
+        phase: '01',
+        plan: '01',
+        type: 'execute',
+        wave: 1,
+        depends_on: [],
+        files_modified: [],
+        autonomous: true,
+        requirements: [],
+        must_haves: {
+          truths: [],
+          artifacts: [],
+          key_links: [{ from: 'auth.ts', to: 'middleware.ts', via: 'import' }],
+        },
+      },
+    });
+    const prompt = buildExecutorPrompt(plan);
+    expect(prompt).toContain('auth.ts → middleware.ts via import');
+  });
+
+  it('includes role from agent definition when provided', () => {
+    const plan = makePlan();
+    const prompt = buildExecutorPrompt(plan, SAMPLE_AGENT_DEF);
+    expect(prompt).toContain('## Role');
+    expect(prompt).toContain('GSD plan executor');
+  });
+
+  it('works without agent definition', () => {
+    const plan = makePlan();
+    const prompt = buildExecutorPrompt(plan);
+    // Should still produce a valid prompt without role section
+    expect(prompt).toContain('## Objective');
+    expect(prompt).toContain('## Tasks');
+    expect(prompt).not.toContain('## Role');
+  });
+
+  it('provides fallback objective when plan has empty objective', () => {
+    const plan = makePlan({ objective: '' });
+    const prompt = buildExecutorPrompt(plan);
+    expect(prompt).toContain('Execute plan: 01');
+  });
+
+  it('includes done criteria for tasks', () => {
+    const plan = makePlan();
+    const prompt = buildExecutorPrompt(plan);
+    expect(prompt).toContain('Auth module created and tests pass');
+    expect(prompt).toContain('Middleware validates JWT on protected routes');
+  });
+
+  it('includes commit instruction in completion section', () => {
+    const plan = makePlan();
+    const prompt = buildExecutorPrompt(plan);
+    expect(prompt).toContain('Commit the SUMMARY.md');
+  });
+});

package/sdk/src/prompt-builder.ts

@@ -0,0 +1,193 @@
+/**
+ * Prompt builder — assembles executor prompts from parsed plans.
+ *
+ * Converts a ParsedPlan into a structured prompt that tells the
+ * executor agent exactly what to do: follow the tasks sequentially,
+ * verify each one, and produce a SUMMARY.md at the end.
+ */
+
+import type { ParsedPlan, PlanTask } from './types.js';
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+const DEFAULT_ALLOWED_TOOLS = ['Read', 'Write', 'Edit', 'Bash', 'Grep', 'Glob'];
+
+// ─── Agent definition parsing ────────────────────────────────────────────────
+
+/**
+ * Extract the tools list from a gsd-executor.md agent definition.
+ * Falls back to DEFAULT_ALLOWED_TOOLS if parsing fails.
+ */
+export function parseAgentTools(agentDef: string): string[] {
+  // Look for "tools:" in the YAML frontmatter
+  const frontmatterMatch = agentDef.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (!frontmatterMatch) return DEFAULT_ALLOWED_TOOLS;
+
+  const toolsMatch = frontmatterMatch[1].match(/^tools:\s*(.+)$/m);
+  if (!toolsMatch) return DEFAULT_ALLOWED_TOOLS;
+
+  const tools = toolsMatch[1]
+    .split(',')
+    .map((t) => t.trim())
+    .filter(Boolean);
+
+  return tools.length > 0 ? tools : DEFAULT_ALLOWED_TOOLS;
+}
+
+/**
+ * Extract the role instructions from a gsd-executor.md agent definition.
+ * Returns the <role>...</role> block content, or empty string.
+ */
+export function parseAgentRole(agentDef: string): string {
+  const match = agentDef.match(/<role>([\s\S]*?)<\/role>/i);
+  return match ? match[1].trim() : '';
+}
+
+// ─── Prompt assembly ─────────────────────────────────────────────────────────
+
+/**
+ * Format a single task into a prompt block.
+ */
+function formatTask(task: PlanTask, index: number): string {
+  const lines: string[] = [];
+  lines.push(`### Task ${index + 1}: ${task.name}`);
+
+  if (task.files.length > 0) {
+    lines.push(`**Files:** ${task.files.join(', ')}`);
+  }
+
+  if (task.read_first.length > 0) {
+    lines.push(`**Read first:** ${task.read_first.join(', ')}`);
+  }
+
+  lines.push('');
+  lines.push('**Action:**');
+  lines.push(task.action);
+
+  if (task.verify) {
+    lines.push('');
+    lines.push('**Verify:**');
+    lines.push(task.verify);
+  }
+
+  if (task.done) {
+    lines.push('');
+    lines.push('**Done when:**');
+    lines.push(task.done);
+  }
+
+  if (task.acceptance_criteria.length > 0) {
+    lines.push('');
+    lines.push('**Acceptance criteria:**');
+    for (const criterion of task.acceptance_criteria) {
+      lines.push(`- ${criterion}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Build the executor prompt from a parsed plan and optional agent definition.
+ *
+ * The prompt instructs the executor to:
+ * 1. Follow the plan tasks sequentially
+ * 2. Run verification for each task
+ * 3. Commit each task individually
+ * 4. Produce a SUMMARY.md file on completion
+ *
+ * @param plan - Parsed plan structure from plan-parser
+ * @param agentDef - Raw content of gsd-executor.md agent definition (optional)
+ * @returns Assembled prompt string
+ */
+export function buildExecutorPrompt(plan: ParsedPlan, agentDef?: string): string {
+  const sections: string[] = [];
+
+  // ── Role instructions from agent definition ──
+  if (agentDef) {
+    const role = parseAgentRole(agentDef);
+    if (role) {
+      sections.push(`## Role\n\n${role}`);
+    }
+  }
+
+  // ── Objective ──
+  if (plan.objective) {
+    sections.push(`## Objective\n\n${plan.objective}`);
+  } else {
+    sections.push(`## Objective\n\nExecute plan: ${plan.frontmatter.plan || plan.frontmatter.phase || 'unnamed'}`);
+  }
+
+  // ── Plan metadata ──
+  const meta: string[] = [];
+  if (plan.frontmatter.phase) meta.push(`Phase: ${plan.frontmatter.phase}`);
+  if (plan.frontmatter.plan) meta.push(`Plan: ${plan.frontmatter.plan}`);
+  if (plan.frontmatter.type) meta.push(`Type: ${plan.frontmatter.type}`);
+  if (meta.length > 0) {
+    sections.push(`## Plan Info\n\n${meta.join('\n')}`);
+  }
+
+  // ── Context references ──
+  if (plan.context_refs.length > 0) {
+    const refs = plan.context_refs.map((r) => `- @${r}`).join('\n');
+    sections.push(`## Context Files\n\nRead these files for context before starting:\n${refs}`);
+  }
+
+  // ── Tasks ──
+  if (plan.tasks.length > 0) {
+    const taskBlocks = plan.tasks.map((t, i) => formatTask(t, i)).join('\n\n---\n\n');
+    sections.push(`## Tasks\n\nExecute these tasks sequentially. For each task: read any referenced files, execute the action, run verification, confirm done criteria, then commit.\n\n${taskBlocks}`);
+  } else {
+    sections.push(`## Tasks\n\nNo tasks defined in this plan. Review the objective and determine if any actions are needed.`);
+  }
+
+  // ── Must-haves ──
+  if (plan.frontmatter.must_haves) {
+    const mh = plan.frontmatter.must_haves;
+    const parts: string[] = [];
+
+    if (mh.truths.length > 0) {
+      parts.push('**Truths (invariants):**');
+      for (const t of mh.truths) {
+        parts.push(`- ${t}`);
+      }
+    }
+
+    if (mh.artifacts.length > 0) {
+      parts.push('**Required artifacts:**');
+      for (const a of mh.artifacts) {
+        parts.push(`- \`${a.path}\`: ${a.provides}`);
+      }
+    }
+
+    if (mh.key_links.length > 0) {
+      parts.push('**Key links:**');
+      for (const l of mh.key_links) {
+        parts.push(`- ${l.from} → ${l.to} via ${l.via}`);
+      }
+    }
+
+    if (parts.length > 0) {
+      sections.push(`## Must-Haves\n\n${parts.join('\n')}`);
+    }
+  }
+
+  // ── Completion instructions ──
+  sections.push(
+    `## Completion\n\n` +
+    `After all tasks are complete:\n` +
+    `1. Run any overall verification or success criteria checks\n` +
+    `2. Create a SUMMARY.md file documenting:\n` +
+    `   - One-line summary of what was accomplished\n` +
+    `   - Tasks completed with commit hashes\n` +
+    `   - Any deviations from the plan\n` +
+    `   - Files created or modified\n` +
+    `   - Known issues (if any)\n` +
+    `3. Commit the SUMMARY.md\n` +
+    `4. Report completion`,
+  );
+
+  return sections.join('\n\n');
+}
+
+export { DEFAULT_ALLOWED_TOOLS };