@assistkick/create 1.0.0

package/templates/product-system/packages/shared/lib/pipeline.ts

@@ -0,0 +1,489 @@
+/**
+ * Pipeline Orchestration Module.
+ * The full develop→review→merge cycle, using injected dependencies.
+ */
+
+const TOOL_CALL_COUNTERS = { Write: 'write', Edit: 'edit', Read: 'read', Bash: 'bash' };
+
+/**
+ * Pipeline class — orchestrates the develop→review→merge cycle.
+ * Receives PromptBuilder, GitWorkflow, kanban, stateStore, claudeService,
+ * and log via constructor injection.
+ */
+export class Pipeline {
+  constructor({ promptBuilder, gitWorkflow, claudeService, kanban, paths, log, stateStore = null, workSummaryParser = null, getNode = null }) {
+    this.promptBuilder = promptBuilder;
+    this.gitWorkflow = gitWorkflow;
+    this.claudeService = claudeService;
+    this.kanban = kanban;
+    this.paths = paths;
+    this.log = log;
+    this.stateStore = stateStore;
+    this.workSummaryParser = workSummaryParser;
+    this.getNode = getNode;
+    this.pipelines = new Map();
+    this.lastLoggedStatus = new Map();
+  }
+
+  /** Persist state to DB if stateStore is available (fire-and-forget with logging). */
+  persistState = (featureId) => {
+    if (!this.stateStore) return;
+    const state = this.pipelines.get(featureId);
+    if (!state) return;
+    this.stateStore.save(featureId, state, state.projectId).catch(err => {
+      this.log('PERSIST', `Failed to persist state for ${featureId}: ${err.message}`);
+    });
+  };
+
+  run = async (featureId) => {
+    const state = this.pipelines.get(featureId);
+    if (!state) {
+      this.log('PIPELINE', `No pipeline state found for ${featureId}, aborting`);
+      return;
+    }
+
+    this.log('PIPELINE', `=== Starting pipeline for ${featureId} ===`);
+    this.log('PIPELINE', `Worktree: ${state.worktree_path}`);
+    let previousReviewNotes = null;
+    let debuggerFindings = null;
+
+    // Debug-first step: check for unaddressed QA notes before cycle 1
+    debuggerFindings = await this.runDebugStep(featureId, state);
+
+    for (let cycle = 1; cycle <= 3; cycle++) {
+      state.cycle = cycle;
+      this.log('PIPELINE', `--- Cycle ${cycle}/3 for ${featureId} ---`);
+
+      // 1. Move card to in_progress (on retries, reviewer left it in todo)
+      try {
+        const devEntry = await this.kanban.getKanbanEntry(featureId);
+        if (devEntry && devEntry.column !== 'in_progress') {
+          devEntry.column = 'in_progress';
+          devEntry.moved_at = new Date().toISOString();
+          await this.kanban.saveKanbanEntry(featureId, devEntry);
+          this.log('PIPELINE', `Moved ${featureId} → in_progress (cycle ${cycle})`);
+        }
+      } catch (err) {
+        this.log('PIPELINE', `WARN: Failed to move ${featureId} to in_progress: ${err.message}`);
+      }
+
+      // 2. Run developer
+      state.status = cycle === 1 ? 'developing' : 'fixing_review';
+      state.tasks = { completed: 0, total: 0, items: [] };
+      state.toolCalls = { total: 0, write: 0, edit: 0, read: 0, bash: 0 };
+      this.log('PIPELINE', `Status → ${state.status}`);
+      this.persistState(featureId);
+      try {
+        const devPrompt = await this.promptBuilder.buildDeveloperPrompt(featureId, cycle, previousReviewNotes, debuggerFindings, state.projectId);
+        if (cycle === 1) debuggerFindings = null;
+        this.log('PIPELINE', `Spawning developer Claude for ${featureId}...`);
+        const onToolUse = (toolName, input) => {
+          if (toolName === 'TodoWrite' && Array.isArray(input.todos)) {
+            state.tasks.items = input.todos.map(t => ({ name: t.content || t.activeForm || '', status: t.status || 'pending' }));
+            state.tasks.total = state.tasks.items.length;
+            state.tasks.completed = state.tasks.items.filter(t => t.status === 'completed').length;
+          }
+          state.toolCalls.total += 1;
+          const counterKey = TOOL_CALL_COUNTERS[toolName];
+          if (counterKey) {
+            state.toolCalls[counterKey] += 1;
+          }
+          this.persistState(featureId);
+        };
+        const devOutput = await this.claudeService.spawnClaude(devPrompt, state.worktree_path, `dev:${featureId}`, { onToolUse });
+        this.log('PIPELINE', `Developer Claude completed for ${featureId}`);
+
+        // Capture work summary from dev output and git diff --stat
+        await this.captureWorkSummary(featureId, state, cycle, devOutput);
+      } catch (err) {
+        this.log('PIPELINE', `Developer Claude FAILED for ${featureId}: ${err.message}`);
+        state.status = 'failed';
+        state.error = `Developer failed: ${err.message}`;
+        this.persistState(featureId);
+        return;
+      }
+
+      // 1b. Commit any uncommitted changes in the worktree
+      try {
+        await this.gitWorkflow.commitChanges(featureId, state.worktree_path);
+      } catch (commitErr) {
+        this.log('PIPELINE', `WARN: Auto-commit failed for ${featureId}: ${commitErr.message}`);
+      }
+
+      // 1c. Rebase feature branch onto current main
+      await this.gitWorkflow.rebaseBranch(featureId, state.worktree_path);
+
+      // 2. Pipeline moves card to in_review
+      this.log('PIPELINE', `Moving ${featureId} to in_review...`);
+      try {
+        const reviewEntry = await this.kanban.getKanbanEntry(featureId);
+        if (reviewEntry) {
+          reviewEntry.column = 'in_review';
+          reviewEntry.moved_at = new Date().toISOString();
+          await this.kanban.saveKanbanEntry(featureId, reviewEntry);
+          this.log('PIPELINE', `Moved ${featureId} → in_review`);
+        }
+      } catch (err) {
+        this.log('PIPELINE', `WARN: Failed to move ${featureId} to in_review: ${err.message}`);
+      }
+
+      // 3. Run reviewer
+      state.status = 'reviewing';
+      this.log('PIPELINE', `Status → reviewing`);
+      this.persistState(featureId);
+      try {
+        const revPrompt = await this.promptBuilder.buildReviewerPrompt(featureId, state.projectId);
+        this.log('PIPELINE', `Spawning reviewer Claude for ${featureId}...`);
+        await this.claudeService.spawnClaude(revPrompt, state.worktree_path, `review:${featureId}`);
+        this.log('PIPELINE', `Reviewer Claude completed for ${featureId}`);
+      } catch (err) {
+        this.log('PIPELINE', `Reviewer Claude FAILED for ${featureId}: ${err.message}`);
+        state.status = 'failed';
+        state.error = `Reviewer failed: ${err.message}`;
+        this.persistState(featureId);
+        return;
+      }
+
+      // 4. Check kanban outcome
+      this.log('PIPELINE', `Checking kanban outcome for ${featureId}...`);
+      let entry;
+      try { entry = await this.kanban.getKanbanEntry(featureId); } catch (err) {
+        this.log('PIPELINE', `FAIL reading kanban: ${err.message}`);
+        break;
+      }
+      if (!entry) {
+        this.log('PIPELINE', `Feature ${featureId} no longer in kanban — aborting`);
+        break;
+      }
+      this.log('PIPELINE', `Kanban column for ${featureId}: ${entry.column}`);
+
+      // If reviewer didn't move the card at all (still in_review), treat as rejection
+      if (entry.column === 'in_review') {
+        this.log('PIPELINE', `Reviewer did not move ${featureId} (still in_review) — treating as rejection`);
+        entry.column = 'todo';
+        entry.moved_at = new Date().toISOString();
+        await this.kanban.saveKanbanEntry(featureId, entry);
+      }
+
+      if (entry.column === 'qa') {
+        // Store approved review outcome
+        if (!entry.reviews) entry.reviews = [];
+        entry.reviews.push({ cycle, status: 'approved', timestamp: new Date().toISOString() });
+        await this.kanban.saveKanbanEntry(featureId, entry);
+        this.log('PIPELINE', `Review PASSED for ${featureId} — starting merge`);
+
+        await this.handleMerge(featureId, state);
+        return;
+      }
+
+      // Review rejected — collect notes for next cycle
+      this.log('PIPELINE', `Review REJECTED for ${featureId} (cycle ${cycle}) — card in column: ${entry.column}`);
+      const latestNotes = (entry.notes || []).map(n => n.text).join('\n');
+      previousReviewNotes = latestNotes || 'Review rejected without specific notes.';
+      this.log('PIPELINE', `Review notes for next cycle: ${previousReviewNotes.slice(0, 200)}`);
+
+      // Store rejected review outcome
+      if (!entry.reviews) entry.reviews = [];
+      entry.reviews.push({ cycle, status: 'rejected', reason: previousReviewNotes, timestamp: new Date().toISOString() });
+      await this.kanban.saveKanbanEntry(featureId, entry);
+    }
+
+    // All 3 cycles exhausted — block the card
+    await this.handleBlock(featureId, state);
+  };
+
+  /** Capture work summary after a developer cycle completes. */
+  captureWorkSummary = async (featureId, state, cycle, devOutput) => {
+    if (!this.workSummaryParser) return;
+    try {
+      // Get git diff --name-status comparing worktree branch to main
+      let diffNameStatus = '';
+      try {
+        diffNameStatus = await this.claudeService.spawnCommand('git', ['diff', '--name-status', 'main...HEAD'], state.worktree_path);
+      } catch (err) {
+        this.log('PIPELINE', `WARN: git diff --name-status failed for ${featureId}: ${err.message}`);
+      }
+
+      const summary = this.workSummaryParser.buildSummary(cycle, diffNameStatus, devOutput || '');
+      if (!state.workSummaries) state.workSummaries = [];
+      state.workSummaries.push(summary);
+      this.persistState(featureId);
+      const totalFiles = summary.filesCreated.length + summary.filesUpdated.length + summary.filesDeleted.length;
+      this.log('PIPELINE', `Work summary captured for ${featureId} cycle ${cycle}: ${totalFiles} files (${summary.filesCreated.length} created, ${summary.filesUpdated.length} updated, ${summary.filesDeleted.length} deleted), ${summary.decisions.length} decisions`);
+    } catch (err) {
+      this.log('PIPELINE', `WARN: Failed to capture work summary for ${featureId}: ${err.message}`);
+    }
+  };
+
+  runDebugStep = async (featureId, state) => {
+    try {
+      const debugEntry = await this.kanban.getKanbanEntry(featureId);
+      if (debugEntry && debugEntry.notes && debugEntry.notes.length > 0) {
+        const unaddressedNotes = debugEntry.notes.filter(n => !n.addressed);
+        if (unaddressedNotes.length > 0) {
+          this.log('PIPELINE', `Found ${unaddressedNotes.length} unaddressed QA notes for ${featureId} — running debugger first`);
+          state.status = 'debugging';
+          this.persistState(featureId);
+          let debuggerFindings = null;
+          try {
+            const debugPrompt = await this.promptBuilder.buildDebuggerPrompt(featureId, unaddressedNotes, state.projectId);
+            this.log('PIPELINE', `Spawning debugger Claude for ${featureId}...`);
+            debuggerFindings = await this.claudeService.spawnClaude(debugPrompt, state.worktree_path, `debug:${featureId}`);
+            this.log('PIPELINE', `Debugger Claude completed for ${featureId} — findings: ${(debuggerFindings || '').length} chars`);
+          } catch (err) {
+            this.log('PIPELINE', `Debugger Claude FAILED for ${featureId}: ${err.message} — continuing without findings`);
+            debuggerFindings = null;
+          }
+
+          // Mark processed notes as addressed
+          const postEntry = await this.kanban.getKanbanEntry(featureId);
+          if (postEntry && postEntry.notes) {
+            for (const note of postEntry.notes) {
+              if (!note.addressed) {
+                note.addressed = true;
+              }
+            }
+            await this.kanban.saveKanbanEntry(featureId, postEntry);
+            this.log('PIPELINE', `Marked ${unaddressedNotes.length} notes as addressed for ${featureId}`);
+          }
+          return debuggerFindings;
+        } else {
+          this.log('PIPELINE', `All QA notes for ${featureId} are already addressed — skipping debugger`);
+        }
+      } else {
+        this.log('PIPELINE', `No QA notes for ${featureId} — skipping debugger`);
+      }
+    } catch (err) {
+      this.log('PIPELINE', `WARN: Failed to check QA notes for debug step: ${err.message} — continuing without debugger`);
+    }
+    return null;
+  };
+
+  handleMerge = async (featureId, state) => {
+    state.status = 'merging';
+    this.log('PIPELINE', `Status → merging`);
+    this.persistState(featureId);
+
+    // Step 1: Stash any local changes on the parent branch before merging
+    let stashed = false;
+    try {
+      stashed = await this.gitWorkflow.stash();
+    } catch (stashErr) {
+      this.log('PIPELINE', `Stash failed (non-fatal): ${stashErr.message}`);
+    }
+
+    // Step 2: Merge the feature branch
+    let mergeSucceeded = false;
+    try {
+      await this.gitWorkflow.mergeBranch(featureId);
+      mergeSucceeded = true;
+    } catch (mergeErr) {
+      this.log('PIPELINE', `Merge FAILED: ${mergeErr.message} — attempting fix`);
+      state.status = 'fixing_merge';
+      this.log('PIPELINE', `Status → fixing_merge`);
+      this.persistState(featureId);
+      try {
+        const fixed = await this.gitWorkflow.fixMergeConflicts(featureId);
+        if (fixed) {
+          this.log('PIPELINE', `Merge fix succeeded — branch verified as merged`);
+          mergeSucceeded = true;
+        } else {
+          this.log('PIPELINE', `Merge fix agent ran but branch is NOT merged — treating as failure`);
+          state.status = 'failed';
+          state.error = `Merge fix did not result in a successful merge: ${mergeErr.message}`;
+          this.persistState(featureId);
+        }
+      } catch (fixErr) {
+        this.log('PIPELINE', `Merge fix FAILED: ${fixErr.message}`);
+        state.status = 'failed';
+        state.error = `Merge fix failed: ${mergeErr.message}`;
+        this.persistState(featureId);
+      }
+    }
+
+    // Step 3: Pop stash to restore local changes
+    if (stashed) {
+      try {
+        await this.gitWorkflow.unstash();
+      } catch (popErr) {
+        this.log('PIPELINE', `Stash pop failed — changes remain in stash: ${popErr.message}`);
+      }
+    }
+
+    // Step 4: Cleanup worktree + branch
+    if (mergeSucceeded) {
+      this.log('PIPELINE', `Cleaning up worktree and branch for ${featureId}...`);
+      await this.gitWorkflow.removeWorktree(state.worktree_path);
+      await this.gitWorkflow.deleteBranch(featureId);
+      state.status = 'completed';
+      this.log('PIPELINE', `=== Pipeline COMPLETED for ${featureId} ===`);
+      this.persistState(featureId);
+    }
+  };
+
+  handleBlock = async (featureId, state) => {
+    this.log('PIPELINE', `=== All 3 cycles exhausted for ${featureId} — BLOCKING ===`);
+    try {
+      const blockEntry = await this.kanban.getKanbanEntry(featureId);
+      if (blockEntry) {
+        blockEntry.dev_blocked = true;
+        await this.kanban.saveKanbanEntry(featureId, blockEntry);
+        this.log('PIPELINE', `Set dev_blocked=true for ${featureId}`);
+      }
+      this.log('PIPELINE', `Cleaning up worktree for ${featureId}...`);
+      await this.gitWorkflow.removeWorktree(state.worktree_path);
+      await this.gitWorkflow.deleteBranch(featureId, true);
+    } catch (err) {
+      this.log('PIPELINE', `Block/cleanup error (non-fatal): ${err.message}`);
+    }
+    state.status = 'blocked';
+    this.log('PIPELINE', `=== Pipeline BLOCKED for ${featureId} ===`);
+    this.persistState(featureId);
+  };
+
+  start = async (featureId) => {
+    this.log('API', `POST /api/kanban/${featureId}/develop`);
+
+    // Check for existing active pipeline
+    if (this.pipelines.has(featureId)) {
+      const existing = this.pipelines.get(featureId);
+      this.log('DEVELOP', `Existing pipeline for ${featureId}: status=${existing.status}`);
+      if (!['completed', 'blocked', 'failed'].includes(existing.status)) {
+        this.log('DEVELOP', `REJECT: pipeline already running for ${featureId}`);
+        return { error: `Pipeline already running for ${featureId}`, status: 409 };
+      }
+    }
+
+    const entry = await this.kanban.getKanbanEntry(featureId);
+
+    if (!entry) {
+      this.log('DEVELOP', `REJECT: ${featureId} not found in kanban`);
+      return { error: `Feature "${featureId}" not found in kanban`, status: 404 };
+    }
+
+    this.log('DEVELOP', `${featureId}: column=${entry.column} dev_blocked=${entry.dev_blocked || false}`);
+
+    if (entry.column !== 'todo') {
+      this.log('DEVELOP', `REJECT: ${featureId} not in todo (is in ${entry.column})`);
+      return { error: `Feature must be in "todo" column (currently "${entry.column}")`, status: 400 };
+    }
+    if (entry.dev_blocked) {
+      this.log('DEVELOP', `REJECT: ${featureId} is dev_blocked`);
+      return { error: `Feature "${featureId}" is dev_blocked. Unblock it first.`, status: 400 };
+    }
+
+    // Pre-flight: reject if working tree is dirty to avoid stash conflicts on merge
+    const dirtyFiles = await this.gitWorkflow.getDirtyFiles();
+    if (dirtyFiles.length > 0) {
+      this.log('DEVELOP', `REJECT: working tree has ${dirtyFiles.length} uncommitted change(s)`);
+      return { error: `Working tree has uncommitted changes. Commit or stash them before starting a pipeline.\n${dirtyFiles.join('\n')}`, status: 400 };
+    }
+
+    // Move to in_progress
+    entry.column = 'in_progress';
+    entry.moved_at = new Date().toISOString();
+    await this.kanban.saveKanbanEntry(featureId, entry);
+    this.log('DEVELOP', `Moved ${featureId} to in_progress`);
+
+    // Create worktree
+    let worktreePath;
+    try {
+      worktreePath = await this.gitWorkflow.createWorktree(featureId);
+    } catch (err) {
+      this.log('DEVELOP', `Worktree creation FAILED: ${err.message}`);
+      // Revert kanban change
+      entry.column = 'todo';
+      await this.kanban.saveKanbanEntry(featureId, entry);
+      this.log('DEVELOP', `Reverted ${featureId} back to todo`);
+      return { error: `Failed to create worktree: ${err.message}`, status: 500 };
+    }
+
+    // Look up the projectId from the feature node
+    let projectId = null;
+    if (this.getNode) {
+      try {
+        const node = await this.getNode(featureId);
+        if (node) projectId = node.project_id || null;
+      } catch {}
+    }
+
+    const state = { status: 'developing', cycle: 1, worktree_path: worktreePath, process: null, error: null, tasks: { completed: 0, total: 0, items: [] }, toolCalls: { total: 0, write: 0, edit: 0, read: 0, bash: 0 }, workSummaries: [], projectId };
+    this.pipelines.set(featureId, state);
+    this.persistState(featureId);
+    this.log('DEVELOP', `Pipeline state initialized for ${featureId}`);
+
+    // Start async pipeline (fire and forget)
+    this.log('DEVELOP', `Launching async pipeline for ${featureId}...`);
+    this.run(featureId).catch(err => {
+      this.log('DEVELOP', `Pipeline UNCAUGHT ERROR for ${featureId}: ${err.message}`);
+      const s = this.pipelines.get(featureId);
+      if (s) { s.status = 'failed'; s.error = err.message; this.persistState(featureId); }
+    });
+
+    return { started: true, feature_id: featureId, status: 200 };
+  };
+
+  getStatus = async (featureId) => {
+    const state = this.pipelines.get(featureId);
+    if (!state) {
+      // Fall back to DB if no in-memory state
+      if (this.stateStore) {
+        try {
+          const dbState = await this.stateStore.load(featureId);
+          if (dbState) return dbState;
+        } catch (err) {
+          this.log('STATUS', `Failed to load DB state for ${featureId}: ${err.message}`);
+        }
+      }
+      return { status: 'idle', feature_id: featureId };
+    }
+
+    // Only log when status or cycle changes
+    const key = `${state.status}:${state.cycle}`;
+    if (this.lastLoggedStatus.get(featureId) !== key) {
+      this.log('STATUS', `${featureId}: status=${state.status} cycle=${state.cycle} error=${state.error || 'none'}`);
+      this.lastLoggedStatus.set(featureId, key);
+    }
+
+    const result = {
+      status: state.status,
+      cycle: state.cycle,
+      feature_id: featureId,
+      error: state.error || null,
+    };
+    if (state.tasks && state.tasks.total > 0) {
+      result.tasks = state.tasks;
+    }
+    if (state.toolCalls && state.toolCalls.total > 0) {
+      result.toolCalls = state.toolCalls;
+    }
+    if (state.workSummaries && state.workSummaries.length > 0) {
+      result.workSummaries = state.workSummaries;
+    }
+    return result;
+  };
+
+  unblock = async (featureId) => {
+    this.log('API', `POST /api/kanban/${featureId}/unblock`);
+
+    const entry = await this.kanban.getKanbanEntry(featureId);
+    if (!entry) {
+      this.log('UNBLOCK', `REJECT: ${featureId} not found`);
+      return { error: `Feature "${featureId}" not found in kanban`, status: 404 };
+    }
+
+    this.log('UNBLOCK', `${featureId}: dev_blocked was ${entry.dev_blocked || false}`);
+    delete entry.dev_blocked;
+    await this.kanban.saveKanbanEntry(featureId, entry);
+
+    // Clear blocked pipeline state
+    const state = this.pipelines.get(featureId);
+    if (state && state.status === 'blocked') {
+      this.pipelines.delete(featureId);
+      this.log('UNBLOCK', `Cleared blocked pipeline state for ${featureId}`);
+    }
+
+    this.log('UNBLOCK', `OK: ${featureId} unblocked`);
+    return { unblocked: true, feature_id: featureId, status: 200 };
+  };
+}

package/templates/product-system/packages/shared/lib/prompt_builder.ts

@@ -0,0 +1,170 @@
+/**
+ * PromptBuilder — responsible for building developer, reviewer, and debugger
+ * prompts from skill files and context.
+ */
+
+import { readFile } from 'node:fs/promises';
+
+export class PromptBuilder {
+  constructor({ paths, log }) {
+    this.paths = paths;
+    this.log = log;
+  }
+
+  buildDeveloperPrompt = async (featureId, cycle, previousReviewNotes, debuggerFindings = null, projectId = null) => {
+    this.log('PROMPT', `Building developer prompt for ${featureId} cycle=${cycle} hasReviewNotes=${!!previousReviewNotes} hasDebugFindings=${!!debuggerFindings}`);
+    let skillContent = '';
+    try { skillContent = await readFile(this.paths.developerSkillPath, 'utf-8'); } catch { this.log('PROMPT', 'WARN: Could not read developer SKILL.md'); }
+
+    const mainToolsDir = this.paths.toolsDir;
+    const mainSkillDir = this.paths.dataDir;
+
+    let prompt = skillContent + '\n\n';
+
+    prompt += `## CRITICAL: Data Isolation\n`;
+    prompt += `You are working in a git worktree. The worktree is ONLY for code changes.\n`;
+    prompt += `All kanban, graph, and spec data lives in the MAIN REPO — never use the worktree copy.\n`;
+    prompt += `\n`;
+    prompt += `**All tool commands MUST use absolute paths to the main repo's tools:**\n`;
+    prompt += `- Tools directory: ${mainToolsDir}\n`;
+    prompt += `- All tool commands MUST be run from: ${mainSkillDir}\n`;
+    const pidFlag = projectId ? ` --project-id ${projectId}` : '';
+    prompt += `- Example: cd ${mainSkillDir} && node tools/get_node.ts ${featureId}${pidFlag}\n`;
+    prompt += `- Example: cd ${mainSkillDir} && node tools/move_card.ts ${featureId} in_review${pidFlag}\n`;
+    prompt += `\n`;
+    prompt += `NEVER run tools from the worktree directory. NEVER use relative paths like \`product-system/tools/\`.\n`;
+    prompt += `ALWAYS \`cd ${mainSkillDir}\` before running any tool command.\n`;
+    if (projectId) {
+      prompt += `ALWAYS include --project-id ${projectId} when running any tool command.\n`;
+    }
+    prompt += `\n`;
+
+    prompt += `## Development Guidelines\n`;
+    prompt += `Before writing any code, load the development guidelines:\n`;
+    prompt += `  cd ${mainSkillDir} && node tools/get_node.ts nfr_001${pidFlag}\n`;
+    prompt += `These guidelines define mandatory coding standards (class-based architecture, arrow functions, constructor DI, naming conventions). All code you write MUST follow them.\n\n`;
+
+    prompt += `## Current Task\n`;
+    prompt += `Implement feature ${featureId}. Read the feature spec using get_node, understand all related nodes, and implement it.\n`;
+
+    if (debuggerFindings) {
+      prompt += `\n## Debugger Investigation Findings\n`;
+      prompt += `A debugger agent has investigated the QA rejection notes and identified root causes.\n`;
+      prompt += `Use these findings to fix the actual root causes rather than just the symptom descriptions:\n\n`;
+      prompt += debuggerFindings + '\n';
+      this.log('PROMPT', `Included debugger findings — ${debuggerFindings.length} chars`);
+    }
+
+    if (cycle > 1 && previousReviewNotes) {
+      prompt += `\n## Previous Review Feedback (Cycle ${cycle})\n`;
+      prompt += `The previous implementation was rejected. Fix the following issues:\n`;
+      prompt += previousReviewNotes + '\n';
+      this.log('PROMPT', `Included review feedback for cycle ${cycle}`);
+    }
+
+    prompt += `\nWhen done implementing, do NOT move the card yourself — the pipeline will handle card transitions.\n`;
+
+    prompt += `\n## REQUIRED: Work Summary Output\n`;
+    prompt += `After completing your implementation, you MUST output a structured work summary block as your final text output.\n`;
+    prompt += `The pipeline will parse this block to record what was done. Use this exact format:\n\n`;
+    prompt += '```\n';
+    prompt += `## Work Summary\n`;
+    prompt += `### Approach\n`;
+    prompt += `<A short paragraph explaining what you implemented and why you chose this approach.>\n`;
+    prompt += `### Decisions\n`;
+    prompt += `- <Key decision 1 you made during implementation>\n`;
+    prompt += `- <Key decision 2>\n`;
+    prompt += '```\n\n';
+    prompt += `This block MUST appear in your final output. Do not skip it.\n`;
+
+    this.log('PROMPT', `Developer prompt built — ${prompt.length} chars`);
+    return prompt;
+  };
+
+  buildDebuggerPrompt = async (featureId, unaddressedNotes, projectId = null) => {
+    this.log('PROMPT', `Building debugger prompt for ${featureId} with ${unaddressedNotes.length} unaddressed notes`);
+    let skillContent = '';
+    try { skillContent = await readFile(this.paths.debuggerSkillPath, 'utf-8'); } catch { this.log('PROMPT', 'WARN: Could not read debugger SKILL.md'); }
+
+    const mainToolsDir = this.paths.toolsDir;
+    const mainSkillDir = this.paths.dataDir;
+
+    let prompt = skillContent + '\n\n';
+
+    prompt += `## CRITICAL: Data Isolation\n`;
+    prompt += `You are investigating bugs in a git worktree. The worktree is ONLY for code changes.\n`;
+    prompt += `All kanban, graph, and spec data lives in the MAIN REPO — never use the worktree copy.\n`;
+    prompt += `\n`;
+    prompt += `**All tool commands MUST use absolute paths to the main repo's tools:**\n`;
+    prompt += `- Tools directory: ${mainToolsDir}\n`;
+    prompt += `- All tool commands MUST be run from: ${mainSkillDir}\n`;
+    const pidFlag = projectId ? ` --project-id ${projectId}` : '';
+    prompt += `- Example: cd ${mainSkillDir} && node tools/get_node.ts ${featureId}${pidFlag}\n`;
+    prompt += `\n`;
+    prompt += `NEVER run tools from the worktree directory. NEVER use relative paths.\n`;
+    prompt += `ALWAYS \`cd ${mainSkillDir}\` before running any tool command.\n`;
+    if (projectId) {
+      prompt += `ALWAYS include --project-id ${projectId} when running any tool command.\n`;
+    }
+    prompt += `\n`;
+
+    prompt += `## Current Task\n`;
+    prompt += `You are running as part of an automated pipeline. Do NOT create bugfix features or move kanban cards.\n`;
+    prompt += `Instead, investigate the QA rejection notes below and output your findings as a structured report.\n\n`;
+    prompt += `Feature: ${featureId}\n\n`;
+    prompt += `## QA Rejection Notes to Investigate\n`;
+    for (const note of unaddressedNotes) {
+      prompt += `- [${note.id || 'no-id'}] ${note.text}\n`;
+    }
+    prompt += `\n`;
+    prompt += `## Instructions\n`;
+    prompt += `1. Read the feature spec using get_node to understand what the feature should do\n`;
+    prompt += `2. Read all related nodes to understand the full context\n`;
+    prompt += `3. Trace through the code to find the root cause of each reported issue\n`;
+    prompt += `4. Output a structured report with your findings. For each issue:\n`;
+    prompt += `   - The original QA note text\n`;
+    prompt += `   - Root cause analysis with specific file paths and line numbers\n`;
+    prompt += `   - Why the current code fails\n`;
+    prompt += `   - Specific guidance on what needs to change to fix it\n`;
+    prompt += `5. Do NOT create bugfix features, do NOT move kanban cards, do NOT write code fixes\n`;
+
+    this.log('PROMPT', `Debugger prompt built — ${prompt.length} chars`);
+    return prompt;
+  };
+
+  buildReviewerPrompt = async (featureId, projectId = null) => {
+    this.log('PROMPT', `Building reviewer prompt for ${featureId}`);
+    let skillContent = '';
+    try { skillContent = await readFile(this.paths.reviewerSkillPath, 'utf-8'); } catch { this.log('PROMPT', 'WARN: Could not read reviewer SKILL.md'); }
+
+    const mainToolsDir = this.paths.toolsDir;
+    const mainSkillDir = this.paths.dataDir;
+
+    let prompt = skillContent + '\n\n';
+
+    prompt += `## CRITICAL: Data Isolation\n`;
+    prompt += `You are reviewing code in a git worktree. The worktree is ONLY for code changes.\n`;
+    prompt += `All kanban, graph, and spec data lives in the MAIN REPO — never use the worktree copy.\n`;
+    prompt += `\n`;
+    prompt += `**All tool commands MUST use absolute paths to the main repo's tools:**\n`;
+    prompt += `- Tools directory: ${mainToolsDir}\n`;
+    prompt += `- All tool commands MUST be run from: ${mainSkillDir}\n`;
+    const pidFlag = projectId ? ` --project-id ${projectId}` : '';
+    prompt += `- Example: cd ${mainSkillDir} && node tools/get_node.ts ${featureId}${pidFlag}\n`;
+    prompt += `- Example: cd ${mainSkillDir} && node tools/move_card.ts ${featureId} qa${pidFlag}\n`;
+    prompt += `\n`;
+    prompt += `NEVER run tools from the worktree directory. NEVER use relative paths like \`product-system/tools/\`.\n`;
+    prompt += `ALWAYS \`cd ${mainSkillDir}\` before running any tool command.\n`;
+    if (projectId) {
+      prompt += `ALWAYS include --project-id ${projectId} when running any tool command.\n`;
+    }
+    prompt += `\n`;
+
+    prompt += `## Current Task\n`;
+    prompt += `Review feature ${featureId}. Read the feature spec using get_node, understand all related nodes, and review the implementation.\n`;
+    prompt += `If the implementation passes review, approve it by running: cd ${mainSkillDir} && node tools/move_card.ts ${featureId} qa${pidFlag}\n`;
+    prompt += `If it fails, reject it with a note: cd ${mainSkillDir} && node tools/move_card.ts ${featureId} todo${pidFlag} --note "description of issues"\n`;
+    this.log('PROMPT', `Reviewer prompt built — ${prompt.length} chars`);
+    return prompt;
+  };
+}