popeye-cli 1.10.0 → 2.0.0

package/src/pipeline/phases/intake.ts

@@ -0,0 +1,54 @@
+/**
+ * INTAKE phase — normalize user prompt into structured Master Plan v1.
+ * Reuses expandIdea() and createPlan() from workflow.
+ * v1.1: Creates constitution artifact and stores hash.
+ */
+
+import type { PhaseContext, PhaseResult } from './phase-context.js';
+import { successResult, failureResult } from './phase-context.js';
+import { generateRepoSnapshot, createSnapshotArtifact } from '../repo-snapshot.js';
+import { createConstitutionArtifact, computeConstitutionHash } from '../constitution.js';
+
+export async function runIntake(context: PhaseContext): Promise<PhaseResult> {
+  const { projectDir, pipeline, artifactManager } = context;
+  const artifacts = [];
+
+  try {
+    // 1. Generate repo snapshot
+    const snapshot = await generateRepoSnapshot(projectDir);
+    const snapshotEntry = createSnapshotArtifact(snapshot, artifactManager, 'INTAKE');
+    artifacts.push(snapshotEntry);
+    pipeline.latestRepoSnapshot = artifactManager.toArtifactRef(snapshotEntry);
+
+    // 2. Create constitution artifact and store hash
+    const constitutionEntry = createConstitutionArtifact(projectDir, artifactManager);
+    if (constitutionEntry) {
+      artifacts.push(constitutionEntry);
+    }
+    pipeline.constitutionHash = computeConstitutionHash(projectDir);
+
+    // 3. Expand idea using existing workflow
+    const { expandIdea, createPlan } = await import('../../workflow/plan-mode.js');
+    const expandedIdea = await expandIdea(
+      context.state.specification ?? context.state.idea ?? '',
+      context.state.language,
+    );
+
+    // 4. Create master plan using existing workflow
+    const plan = await createPlan(expandedIdea, '', context.state.language);
+
+    // 5. Store master plan as artifact
+    const planEntry = artifactManager.createAndStoreText(
+      'master_plan',
+      plan,
+      'INTAKE',
+    );
+    artifacts.push(planEntry);
+    pipeline.artifacts.push(...artifacts);
+
+    return successResult('INTAKE', artifacts, 'Master Plan v1 created');
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'Unknown error during intake';
+    return failureResult('INTAKE', 'Failed to create master plan', message);
+  }
+}

package/src/pipeline/phases/phase-context.ts

@@ -0,0 +1,86 @@
+/**
+ * Shared PhaseContext type and helpers for all phase implementations.
+ */
+
+import type { PipelinePhase, PipelineState, ArtifactEntry } from '../types.js';
+import type { ArtifactManager } from '../artifact-manager.js';
+import type { GateEngine } from '../gate-engine.js';
+import type { SkillLoader } from '../skill-loader.js';
+import type { ConsensusRunner } from '../consensus/consensus-runner.js';
+import type { ProjectState } from '../../types/workflow.js';
+
+// ─── PhaseContext ────────────────────────────────────────
+
+export interface PhaseContext {
+  state: ProjectState;
+  pipeline: PipelineState;
+  projectDir: string;
+  skillLoader: SkillLoader;
+  artifactManager: ArtifactManager;
+  gateEngine: GateEngine;
+  consensusRunner: ConsensusRunner;
+}
+
+// ─── PhaseResult ─────────────────────────────────────────
+
+export interface PhaseResult {
+  phase: PipelinePhase;
+  success: boolean;
+  artifacts: ArtifactEntry[];
+  message: string;
+  error?: string;
+}
+
+// ─── Journalist Helper (P1-F) ────────────────────────────
+
+/** Trigger journalist after consensus/audit/production phases */
+export async function triggerJournalist(
+  phase: PipelinePhase,
+  artifacts: ArtifactEntry[],
+  context: PhaseContext,
+): Promise<ArtifactEntry | null> {
+  const skill = context.skillLoader.loadSkill('JOURNALIST');
+
+  const traceContent = [
+    `# Journalist Trace — ${phase}`,
+    ``,
+    `**Timestamp:** ${new Date().toISOString()}`,
+    `**Phase:** ${phase}`,
+    ``,
+    `## Artifacts Recorded`,
+    ``,
+    ...artifacts.map((a) => `- [${a.type}] v${a.version}: ${a.path}`),
+    ``,
+    `## Skill: ${skill.role}`,
+    `${skill.systemPrompt.slice(0, 200)}...`,
+  ].join('\n');
+
+  const entry = context.artifactManager.createAndStoreText(
+    'journalist_trace',
+    traceContent,
+    phase,
+  );
+
+  // Update INDEX.md with all current artifacts
+  context.artifactManager.updateIndex(context.pipeline.artifacts);
+
+  return entry;
+}
+
+// ─── Phase Result Helpers ────────────────────────────────
+
+export function successResult(
+  phase: PipelinePhase,
+  artifacts: ArtifactEntry[],
+  message: string,
+): PhaseResult {
+  return { phase, success: true, artifacts, message };
+}
+
+export function failureResult(
+  phase: PipelinePhase,
+  message: string,
+  error?: string,
+): PhaseResult {
+  return { phase, success: false, artifacts: [], message, error };
+}

package/src/pipeline/phases/production-gate.ts

@@ -0,0 +1,113 @@
+/**
+ * PRODUCTION_GATE phase — binary PASS/FAIL production-ready decision.
+ * Uses commandResolver + checkRunner. Runs placeholder scan (P2-2).
+ * v1.1: Adds start check and env check.
+ */
+
+import type { PhaseContext, PhaseResult } from './phase-context.js';
+import { successResult, failureResult, triggerJournalist } from './phase-context.js';
+import { resolveCommands } from '../command-resolver.js';
+import { runAllChecks, runPlaceholderScan, runStartCheck, runEnvCheck, storeCheckResults } from '../check-runner.js';
+import { generateRepoSnapshot } from '../repo-snapshot.js';
+
+export async function runProductionGate(context: PhaseContext): Promise<PhaseResult> {
+  const { pipeline, artifactManager, projectDir } = context;
+  const artifacts = [];
+
+  try {
+    // 1. Resolve commands from snapshot
+    const snapshot = await generateRepoSnapshot(projectDir);
+    const commands = resolveCommands(snapshot);
+    pipeline.resolvedCommands = commands;
+
+    // 2. Run all checks
+    const checkResults = await runAllChecks(commands, projectDir);
+
+    // 3. Run placeholder scan (P2-2)
+    const placeholderResult = runPlaceholderScan(projectDir);
+    checkResults.push(placeholderResult);
+
+    // 4. Run env check (v1.1)
+    const envResult = runEnvCheck(projectDir, snapshot);
+    checkResults.push(envResult);
+
+    // 5. Run start check if start command exists (v1.1)
+    if (commands.start) {
+      const startResult = await runStartCheck(commands.start, projectDir, {
+        port: snapshot.ports_entrypoints[0]?.port,
+      });
+      checkResults.push(startResult);
+    }
+
+    // 6. Store check results as artifacts
+    const checkArtifacts = storeCheckResults(checkResults, artifactManager, 'PRODUCTION_GATE');
+    artifacts.push(...checkArtifacts);
+
+    // 7. Store in pipeline gate checks
+    pipeline.gateChecks['PRODUCTION_GATE'] = checkResults;
+
+    // 8. Determine PASS/FAIL
+    const failedChecks = checkResults.filter(
+      (r) => r.status === 'fail' && r.check_type !== 'placeholder_scan',
+    );
+    const hasPlaceholders = placeholderResult.status === 'fail';
+    const auditPassed = pipeline.artifacts.some((a) => a.type === 'audit_report');
+    const passed = failedChecks.length === 0 && auditPassed;
+
+    // 9. Create production readiness report
+    const report = [
+      '# Production Readiness Report',
+      '',
+      `**Timestamp:** ${new Date().toISOString()}`,
+      `**Verdict:** ${passed ? 'PASS' : 'FAIL'}`,
+      '',
+      '## Check Results',
+      '',
+      ...checkResults.map((r) =>
+        `- **${r.check_type}**: ${r.status} ${r.duration_ms > 0 ? `(${r.duration_ms}ms)` : ''}`,
+      ),
+      '',
+      hasPlaceholders ? '## Warning: Placeholder content detected\n' + (placeholderResult.stderr_summary ?? '') : '',
+      '',
+      '## Gate Status',
+      `- Build: ${findCheckStatus(checkResults, 'build')}`,
+      `- Tests: ${findCheckStatus(checkResults, 'test')}`,
+      `- Lint: ${findCheckStatus(checkResults, 'lint')}`,
+      `- Typecheck: ${findCheckStatus(checkResults, 'typecheck')}`,
+      `- Env: ${findCheckStatus(checkResults, 'env_check')}`,
+      `- Start: ${findCheckStatus(checkResults, 'start')}`,
+      `- Audit: ${auditPassed ? 'PASS' : 'MISSING'}`,
+      `- Placeholders: ${hasPlaceholders ? 'WARNING' : 'CLEAN'}`,
+    ].join('\n');
+
+    const reportEntry = artifactManager.createAndStoreText(
+      'production_readiness',
+      report,
+      'PRODUCTION_GATE',
+    );
+    artifacts.push(reportEntry);
+
+    pipeline.artifacts.push(...artifacts);
+
+    // 10. Journalist trigger
+    await triggerJournalist('PRODUCTION_GATE', artifacts, context);
+
+    return successResult(
+      'PRODUCTION_GATE',
+      artifacts,
+      passed ? 'Production Gate PASS' : `Production Gate FAIL: ${failedChecks.length} failed checks`,
+    );
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'Unknown error';
+    return failureResult('PRODUCTION_GATE', 'Production gate failed', message);
+  }
+}
+
+function findCheckStatus(
+  results: { check_type: string; status: string }[],
+  type: string,
+): string {
+  const r = results.find((c) => c.check_type === type);
+  if (!r) return 'SKIP';
+  return r.status.toUpperCase();
+}

package/src/pipeline/phases/qa-validation.ts

@@ -0,0 +1,63 @@
+/**
+ * QA_VALIDATION phase — execute QA plan and validate critical paths.
+ * Runs tests via checkRunner. Creates qa_validation artifact.
+ */
+
+import type { PhaseContext, PhaseResult } from './phase-context.js';
+import { successResult, failureResult } from './phase-context.js';
+import { resolveCommands } from '../command-resolver.js';
+import { runCheck, storeCheckResults } from '../check-runner.js';
+import { generateRepoSnapshot } from '../repo-snapshot.js';
+
+export async function runQaValidation(context: PhaseContext): Promise<PhaseResult> {
+  const { pipeline, artifactManager, projectDir } = context;
+  const artifacts = [];
+
+  try {
+    // 1. Resolve test command
+    const snapshot = await generateRepoSnapshot(projectDir);
+    const commands = resolveCommands(snapshot);
+    pipeline.resolvedCommands = commands;
+
+    // 2. Run test command
+    if (commands.test) {
+      const testResult = await runCheck('test', commands.test, projectDir);
+      const stored = storeCheckResults([testResult], artifactManager, 'QA_VALIDATION');
+      artifacts.push(...stored);
+
+      // Store in pipeline gate checks
+      if (!pipeline.gateChecks['QA_VALIDATION']) {
+        pipeline.gateChecks['QA_VALIDATION'] = [];
+      }
+      pipeline.gateChecks['QA_VALIDATION'].push(testResult);
+    }
+
+    // 3. Create QA validation summary artifact
+    const qaReport = [
+      '# QA Validation Report',
+      '',
+      `**Timestamp:** ${new Date().toISOString()}`,
+      `**Test Command:** ${commands.test ?? 'none'}`,
+      `**Test Status:** ${pipeline.gateChecks['QA_VALIDATION']?.[0]?.status ?? 'skip'}`,
+      '',
+      '## Results',
+      '',
+      pipeline.gateChecks['QA_VALIDATION']?.map((r) =>
+        `- ${r.check_type}: ${r.status} (${r.duration_ms}ms)`,
+      ).join('\n') ?? 'No checks run',
+    ].join('\n');
+
+    const qaEntry = artifactManager.createAndStoreText(
+      'qa_validation',
+      qaReport,
+      'QA_VALIDATION',
+    );
+    artifacts.push(qaEntry);
+
+    pipeline.artifacts.push(...artifacts);
+    return successResult('QA_VALIDATION', artifacts, 'QA validation complete');
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'Unknown error';
+    return failureResult('QA_VALIDATION', 'QA validation failed', message);
+  }
+}

package/src/pipeline/phases/recovery-loop.ts

@@ -0,0 +1,118 @@
+/**
+ * RECOVERY_LOOP phase — self-heal using RCA, not guesswork.
+ * Routes via requires_phase_rewind_to (P1-3). Max 5 iterations.
+ */
+
+import type { PipelinePhase } from '../types.js';
+import type { PhaseContext, PhaseResult } from './phase-context.js';
+import { successResult, failureResult, triggerJournalist } from './phase-context.js';
+import { buildRCAPacket } from '../packets/rca-packet-builder.js';
+
+export async function runRecoveryLoop(context: PhaseContext): Promise<PhaseResult> {
+  const { pipeline, artifactManager, skillLoader } = context;
+  const artifacts = [];
+
+  try {
+    // 1. Load debugger skill
+    const debuggerSkill = skillLoader.loadSkill('DEBUGGER');
+
+    // 2. Gather failure evidence
+    const failedPhase = pipeline.failedPhase;
+    const failedGateResult = failedPhase ? pipeline.gateResults[failedPhase] : undefined;
+    const failedChecks = failedPhase ? pipeline.gateChecks[failedPhase] ?? [] : [];
+
+    const failureEvidence = [
+      `Failed phase: ${failedPhase ?? 'unknown'}`,
+      failedGateResult
+        ? `Gate blockers: ${failedGateResult.blockers.join(', ')}`
+        : 'No gate result available',
+      failedChecks.length > 0
+        ? `Failed checks: ${failedChecks.filter((c) => c.status === 'fail').map((c) => `${c.check_type}: ${c.stderr_summary?.slice(0, 200) ?? 'no details'}`).join('; ')}`
+        : 'No check failures',
+    ].join('\n');
+
+    // 3. Generate RCA via Claude with Debugger skill
+    const { executePrompt } = await import('../../adapters/claude.js');
+    const rcaPrompt = [
+      debuggerSkill.systemPrompt,
+      '',
+      '## Failure Evidence',
+      failureEvidence,
+      '',
+      '## Instructions',
+      'Produce a Root Cause Analysis:',
+      '1. Precise root cause',
+      '2. Origin phase',
+      '3. Responsible role',
+      '4. Corrective actions',
+      '5. Whether phase rewind is needed (and to which phase)',
+      '6. Prevention recommendation',
+    ].join('\n');
+
+    const rcaResult = await executePrompt(rcaPrompt);
+    const rcaResponse = rcaResult.response;
+
+    // 4. Build RCA packet
+    const rcaPacket = buildRCAPacket({
+      incidentSummary: `Gate failure at ${failedPhase ?? 'unknown'} (recovery iteration ${pipeline.recoveryCount})`,
+      symptoms: failedGateResult?.blockers ?? ['Gate failed'],
+      rootCause: rcaResponse.slice(0, 500),
+      responsibleLayer: failedPhase ?? 'IMPLEMENTATION',
+      originPhase: failedPhase ?? 'IMPLEMENTATION',
+      governanceGap: 'Detected during gate evaluation',
+      correctiveActions: ['See RCA report for details'],
+      prevention: 'See RCA report for details',
+      rewindTo: determineRewindTarget(rcaResponse, failedPhase),
+    });
+
+    // 5. Store RCA as artifacts
+    const rcaJsonEntry = artifactManager.createAndStoreJson(
+      'rca_report',
+      rcaPacket,
+      'RECOVERY_LOOP',
+    );
+    artifacts.push(rcaJsonEntry);
+
+    const rcaTextEntry = artifactManager.createAndStoreText(
+      'rca_report',
+      `# RCA Report\n\n${rcaResponse}`,
+      'RECOVERY_LOOP',
+    );
+    artifacts.push(rcaTextEntry);
+
+    pipeline.artifacts.push(...artifacts);
+
+    // 6. Journalist trigger
+    await triggerJournalist('RECOVERY_LOOP', artifacts, context);
+
+    return successResult(
+      'RECOVERY_LOOP',
+      artifacts,
+      `RCA complete: recovery iteration ${pipeline.recoveryCount}`,
+    );
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'Unknown error';
+    return failureResult('RECOVERY_LOOP', 'Recovery loop failed', message);
+  }
+}
+
+/** Determine rewind target from RCA response */
+function determineRewindTarget(
+  _rcaResponse: string,
+  failedPhase: PipelinePhase | undefined,
+): PipelinePhase | undefined {
+  // If the failure was in production gate or audit, rewind to implementation
+  if (failedPhase === 'PRODUCTION_GATE' || failedPhase === 'AUDIT') {
+    return 'IMPLEMENTATION';
+  }
+  // If in QA, rewind to implementation
+  if (failedPhase === 'QA_VALIDATION') {
+    return 'IMPLEMENTATION';
+  }
+  // For consensus failures, rewind to the phase being validated
+  if (failedPhase === 'CONSENSUS_MASTER_PLAN') return 'INTAKE';
+  if (failedPhase === 'CONSENSUS_ARCHITECTURE') return 'ARCHITECTURE';
+  if (failedPhase === 'CONSENSUS_ROLE_PLANS') return 'ROLE_PLANNING';
+
+  return undefined;
+}

package/src/pipeline/phases/review.ts

@@ -0,0 +1,149 @@
+/**
+ * REVIEW phase — verify implementation matches approved plans.
+ * Detects drift via snapshot diff (P1-E).
+ * v1.1: Creates Change Requests when drift is detected.
+ */
+
+import type { PhaseContext, PhaseResult } from './phase-context.js';
+import { successResult, failureResult } from './phase-context.js';
+import { generateRepoSnapshot, createSnapshotArtifact, diffSnapshots } from '../repo-snapshot.js';
+import type { RepoSnapshot, ChangeRequest } from '../types.js';
+import { buildChangeRequest, formatChangeRequest, routeChangeRequest } from '../change-request.js';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export async function runReview(context: PhaseContext): Promise<PhaseResult> {
+  const { pipeline, artifactManager, projectDir } = context;
+  const artifacts = [];
+  const changeRequests: ChangeRequest[] = [];
+
+  try {
+    // 1. Generate fresh snapshot
+    const currentSnapshot = await generateRepoSnapshot(projectDir);
+    const snapshotEntry = createSnapshotArtifact(currentSnapshot, artifactManager, 'REVIEW');
+    artifacts.push(snapshotEntry);
+    pipeline.latestRepoSnapshot = artifactManager.toArtifactRef(snapshotEntry);
+
+    // 2. Find role-plan-approval snapshot for drift detection
+    const rolePlanSnapshots = pipeline.artifacts.filter(
+      (a) => a.type === 'repo_snapshot' && a.phase === 'CONSENSUS_ROLE_PLANS',
+    );
+    const baselineSnapshot = rolePlanSnapshots[rolePlanSnapshots.length - 1];
+
+    let driftReport = 'No baseline snapshot found for drift detection.';
+    let hasDrift = false;
+
+    if (baselineSnapshot) {
+      const baselinePath = join(projectDir, baselineSnapshot.path);
+      if (existsSync(baselinePath)) {
+        try {
+          const baselineData = JSON.parse(readFileSync(baselinePath, 'utf-8')) as RepoSnapshot;
+          const diff = diffSnapshots(baselineData, currentSnapshot);
+
+          if (diff.has_changes) {
+            hasDrift = true;
+            driftReport = [
+              '## Implementation Drift Detected',
+              '',
+              `Files delta: ${diff.files_delta > 0 ? '+' : ''}${diff.files_delta}`,
+              `Lines delta: ${diff.lines_delta > 0 ? '+' : ''}${diff.lines_delta}`,
+              diff.added_configs.length > 0 ? `Added configs: ${diff.added_configs.join(', ')}` : '',
+              diff.removed_configs.length > 0 ? `Removed configs: ${diff.removed_configs.join(', ')}` : '',
+              diff.changed_configs.length > 0 ? `Changed configs: ${diff.changed_configs.join(', ')}` : '',
+            ].filter(Boolean).join('\n');
+
+            // v1.1: Create change requests for detected drift
+            if (diff.changed_configs.length > 0) {
+              const cr = buildChangeRequest({
+                originPhase: 'REVIEW',
+                requestedBy: 'REVIEWER',
+                changeType: 'config',
+                description: `Config files changed during implementation: ${diff.changed_configs.join(', ')}`,
+                justification: 'Detected by snapshot diff during review phase',
+                affectedArtifacts: [artifactManager.toArtifactRef(snapshotEntry)],
+                affectedPhases: ['IMPLEMENTATION', 'QA_VALIDATION'],
+                riskLevel: diff.changed_configs.length > 3 ? 'high' : 'medium',
+              });
+              changeRequests.push(cr);
+            }
+
+            if (Math.abs(diff.lines_delta) > 1000) {
+              const cr = buildChangeRequest({
+                originPhase: 'REVIEW',
+                requestedBy: 'REVIEWER',
+                changeType: 'scope',
+                description: `Significant scope drift detected: ${diff.lines_delta > 0 ? '+' : ''}${diff.lines_delta} lines`,
+                justification: 'Large line delta suggests scope changes beyond approved plans',
+                affectedArtifacts: [artifactManager.toArtifactRef(snapshotEntry)],
+                affectedPhases: ['CONSENSUS_MASTER_PLAN', 'IMPLEMENTATION'],
+                riskLevel: 'high',
+              });
+              changeRequests.push(cr);
+            }
+          } else {
+            driftReport = 'No drift detected between approved plans and implementation.';
+          }
+        } catch {
+          driftReport = 'Failed to parse baseline snapshot for drift detection.';
+        }
+      }
+    }
+
+    // 3. Store change requests as artifacts and register in pipeline state
+    for (const cr of changeRequests) {
+      const crEntry = artifactManager.createAndStoreText(
+        'change_request',
+        formatChangeRequest(cr),
+        'REVIEW',
+      );
+      artifacts.push(crEntry);
+
+      // Register CR in pipeline state for orchestrator routing
+      if (!pipeline.pendingChangeRequests) {
+        pipeline.pendingChangeRequests = [];
+      }
+      pipeline.pendingChangeRequests.push({
+        cr_id: cr.cr_id,
+        change_type: cr.change_type,
+        target_phase: routeChangeRequest(cr),
+        status: 'proposed',
+      });
+    }
+
+    // 4. Create review decision artifact
+    const reviewDoc = [
+      '# Review Decision',
+      '',
+      `**Timestamp:** ${new Date().toISOString()}`,
+      `**Phase:** REVIEW`,
+      `**Drift Detected:** ${hasDrift ? 'Yes' : 'No'}`,
+      `**Change Requests:** ${changeRequests.length}`,
+      '',
+      '## Drift Analysis',
+      driftReport,
+      '',
+      changeRequests.length > 0 ? '## Change Requests\n' + changeRequests.map((cr) => `- ${cr.cr_id}: ${cr.description}`).join('\n') : '',
+      '',
+      '## Plan Alignment',
+      'Implementation reviewed against approved role plans.',
+      '',
+      '## Decision',
+      hasDrift && changeRequests.length > 0
+        ? 'Review flagged drift — change requests created for consensus review.'
+        : 'Review completed. See drift analysis above.',
+    ].join('\n');
+
+    const reviewEntry = artifactManager.createAndStoreText(
+      'review_decision',
+      reviewDoc,
+      'REVIEW',
+    );
+    artifacts.push(reviewEntry);
+
+    pipeline.artifacts.push(...artifacts);
+    return successResult('REVIEW', artifacts, `Review complete. ${changeRequests.length} change requests.`);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'Unknown error';
+    return failureResult('REVIEW', 'Review failed', message);
+  }
+}

package/src/pipeline/phases/role-planning.ts

@@ -0,0 +1,92 @@
+/**
+ * ROLE_PLANNING phase — produce deterministic implementation plans by role.
+ * Runs per-role: DB, BE, FE, Website, QA. Creates role_plan artifacts.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { PipelineRole } from '../types.js';
+import type { PhaseContext, PhaseResult } from './phase-context.js';
+import { successResult, failureResult } from './phase-context.js';
+
+/** Roles that produce implementation plans */
+const PLANNING_ROLES: PipelineRole[] = [
+  'DB_EXPERT',
+  'BACKEND_PROGRAMMER',
+  'FRONTEND_PROGRAMMER',
+  'WEBSITE_PROGRAMMER',
+  'QA_TESTER',
+];
+
+export async function runRolePlanning(context: PhaseContext): Promise<PhaseResult> {
+  const { pipeline, artifactManager, skillLoader, projectDir } = context;
+  const artifacts = [];
+
+  try {
+    // Read architecture doc for context
+    const archArtifact = pipeline.artifacts.find((a) => a.type === 'architecture');
+    let architectureContent = '';
+    if (archArtifact) {
+      const fullPath = join(projectDir, archArtifact.path);
+      if (existsSync(fullPath)) {
+        architectureContent = readFileSync(fullPath, 'utf-8');
+      }
+    }
+
+    // Read master plan for context
+    const masterPlanArtifact = pipeline.artifacts.find((a) => a.type === 'master_plan');
+    let masterPlanContent = '';
+    if (masterPlanArtifact) {
+      const fullPath = join(projectDir, masterPlanArtifact.path);
+      if (existsSync(fullPath)) {
+        masterPlanContent = readFileSync(fullPath, 'utf-8');
+      }
+    }
+
+    const { executePrompt } = await import('../../adapters/claude.js');
+
+    // Generate plan for each role
+    for (const role of PLANNING_ROLES) {
+      // Skip website if not in active roles
+      if (role === 'WEBSITE_PROGRAMMER' && !pipeline.activeRoles.includes('WEBSITE_PROGRAMMER')) {
+        continue;
+      }
+
+      const skill = skillLoader.loadSkill(role);
+
+      const planPrompt = [
+        skill.systemPrompt,
+        '',
+        '## Master Plan',
+        masterPlanContent.slice(0, 5000),
+        '',
+        '## Architecture',
+        architectureContent.slice(0, 5000),
+        '',
+        '## Instructions',
+        `Create your ${role} implementation plan. Include:`,
+        '- Deterministic file-level outputs',
+        '- Specific tasks with acceptance criteria',
+        '- Dependencies on other roles',
+        '- Test requirements',
+      ].join('\n');
+
+      const planResult = await executePrompt(planPrompt);
+      const plan = planResult.response;
+
+      const entry = artifactManager.createAndStoreText(
+        'role_plan',
+        `# ${role} Plan\n\n${plan}`,
+        'ROLE_PLANNING',
+      );
+      artifacts.push(entry);
+    }
+
+    pipeline.artifacts.push(...artifacts);
+    return successResult('ROLE_PLANNING', artifacts, `Created ${artifacts.length} role plans`);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'Unknown error';
+    return failureResult('ROLE_PLANNING', 'Role planning failed', message);
+  }
+}