popeye-cli 1.10.0 → 2.1.0

package/src/pipeline/role-execution-adapter.ts

@@ -0,0 +1,238 @@
+/**
+ * Role Execution Adapter — bridges pipeline role planning
+ * with the existing runExecutionMode().
+ *
+ * Builds role-specific execution contexts by combining skill prompts
+ * with role plan constraints, then injects them as systemPrompt
+ * into ClaudeExecuteOptions for prompt-based enforcement.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type {
+  PipelineRole,
+  PipelineState,
+  ArtifactEntry,
+} from './types.js';
+import type { SkillLoader, SkillDefinition } from './skill-loader.js';
+
+// ─── Types ───────────────────────────────────────────────
+
+export interface RoleExecutionContext {
+  role: PipelineRole;
+  systemPrompt: string;
+  allowedPaths: string[];
+  forbiddenPatterns: string[];
+  taskScope: string;
+}
+
+export interface ClaudeExecuteOptions {
+  projectDir: string;
+  systemPrompt?: string;
+  [key: string]: unknown;
+}
+
+// ─── Context Builder ─────────────────────────────────────
+
+/**
+ * Build a role-specific execution context from a skill definition and role plan artifact.
+ *
+ * Args:
+ *   role: The pipeline role to build context for.
+ *   skill: The skill definition loaded by SkillLoader.
+ *   rolePlan: The approved role plan artifact entry.
+ *   projectDir: Root project directory.
+ *
+ * Returns:
+ *   RoleExecutionContext with system prompt, allowed paths, and task scope.
+ */
+export function buildRoleExecutionContext(
+  role: PipelineRole,
+  skill: SkillDefinition,
+  rolePlan: ArtifactEntry,
+  projectDir: string,
+): RoleExecutionContext {
+  // Read role plan content
+  const planPath = join(projectDir, rolePlan.path);
+  let planContent = '';
+  if (existsSync(planPath)) {
+    planContent = readFileSync(planPath, 'utf-8');
+  }
+
+  // Extract task scope from role plan
+  const taskScope = extractTaskScope(planContent);
+  const allowedPaths = extractAllowedPaths(planContent, role);
+  const forbiddenPatterns = extractForbiddenPatterns(role);
+
+  // Build system prompt combining skill + role constraints
+  const systemPrompt = buildRoleSystemPrompt(role, skill, planContent, forbiddenPatterns);
+
+  return {
+    role,
+    systemPrompt,
+    allowedPaths,
+    forbiddenPatterns,
+    taskScope,
+  };
+}
+
+/**
+ * Inject role context into ClaudeExecuteOptions by setting the systemPrompt field.
+ *
+ * Args:
+ *   context: The role execution context.
+ *   options: The execution options to augment.
+ *
+ * Returns:
+ *   Modified options with systemPrompt injected.
+ */
+export function executeWithRoleContext(
+  context: RoleExecutionContext,
+  options: ClaudeExecuteOptions,
+): ClaudeExecuteOptions {
+  return {
+    ...options,
+    systemPrompt: context.systemPrompt,
+  };
+}
+
+// ─── Role-to-Plan Mapping ────────────────────────────────
+
+/**
+ * Find role plan artifacts for each active role in the pipeline.
+ *
+ * Args:
+ *   pipeline: Current pipeline state.
+ *   skillLoader: Skill loader instance.
+ *   projectDir: Root project directory.
+ *
+ * Returns:
+ *   Map of role to RoleExecutionContext.
+ */
+export function buildAllRoleContexts(
+  pipeline: PipelineState,
+  skillLoader: SkillLoader,
+  projectDir: string,
+): Map<PipelineRole, RoleExecutionContext> {
+  const contexts = new Map<PipelineRole, RoleExecutionContext>();
+
+  // Find all role_plan artifacts
+  const rolePlanArtifacts = pipeline.artifacts.filter((a) => a.type === 'role_plan');
+
+  for (const rolePlan of rolePlanArtifacts) {
+    // Determine which role this plan belongs to by checking plan content
+    const planPath = join(projectDir, rolePlan.path);
+    if (!existsSync(planPath)) continue;
+
+    const content = readFileSync(planPath, 'utf-8');
+    const role = detectRoleFromPlan(content, pipeline.activeRoles);
+    if (!role) continue;
+
+    const skill = skillLoader.loadSkill(role);
+    contexts.set(role, buildRoleExecutionContext(role, skill, rolePlan, projectDir));
+  }
+
+  return contexts;
+}
+
+// ─── Internal Helpers ────────────────────────────────────
+
+/** Extract task scope description from role plan content */
+function extractTaskScope(planContent: string): string {
+  // Look for "## Tasks" or "## Responsibilities" section
+  const taskMatch = planContent.match(
+    /#+\s*(?:Tasks?|Responsibilities?|Work\s+Items?)\s*\n([\s\S]*?)(?=\n#+\s|\n---|\s*$)/i,
+  );
+  if (taskMatch) {
+    return taskMatch[1].trim().slice(0, 2000);
+  }
+  // Fallback: first 500 chars
+  return planContent.slice(0, 500).trim();
+}
+
+/** Extract allowed file paths from role plan */
+function extractAllowedPaths(planContent: string, role: PipelineRole): string[] {
+  // Default paths based on role
+  const roleDefaults: Partial<Record<PipelineRole, string[]>> = {
+    FRONTEND_PROGRAMMER: ['src/', 'app/', 'pages/', 'components/', 'styles/', 'public/'],
+    BACKEND_PROGRAMMER: ['src/', 'server/', 'api/', 'lib/', 'db/', 'prisma/'],
+    WEBSITE_PROGRAMMER: ['apps/website/', 'src/', 'app/', 'pages/', 'public/'],
+    DB_EXPERT: ['prisma/', 'migrations/', 'db/', 'alembic/', 'models/'],
+    QA_TESTER: ['tests/', '__tests__/', 'test/', 'spec/'],
+    UI_UX_SPECIALIST: ['src/', 'app/', 'styles/', 'components/'],
+  };
+
+  // Extract explicit file references from plan
+  const fileRefs = planContent.match(/(?:src|app|pages|lib|server|api|tests?)\/[\w\-./]+/g) ?? [];
+  const defaults = roleDefaults[role] ?? [];
+
+  return [...new Set([...defaults, ...fileRefs])];
+}
+
+/** Get forbidden patterns based on role boundaries */
+function extractForbiddenPatterns(role: PipelineRole): string[] {
+  const roleForbidden: Partial<Record<PipelineRole, string[]>> = {
+    FRONTEND_PROGRAMMER: ['server/', 'api/', 'prisma/', 'migrations/', 'alembic/'],
+    BACKEND_PROGRAMMER: ['components/', 'styles/', 'public/assets/'],
+    WEBSITE_PROGRAMMER: ['server/', 'api/', 'prisma/', 'migrations/'],
+    DB_EXPERT: ['components/', 'styles/', 'public/', 'pages/'],
+    QA_TESTER: [], // QA can touch anything
+  };
+
+  return roleForbidden[role] ?? [];
+}
+
+/** Build the full system prompt for a role */
+function buildRoleSystemPrompt(
+  role: PipelineRole,
+  skill: SkillDefinition,
+  planContent: string,
+  forbiddenPatterns: string[],
+): string {
+  const lines = [
+    `# Role: ${role}`,
+    '',
+    '## Skill System Prompt',
+    skill.systemPrompt,
+    '',
+    '## Your Approved Role Plan',
+    planContent.slice(0, 4000),
+    '',
+    '## Constraints',
+    ...skill.constraints.map((c) => `- ${c}`),
+  ];
+
+  if (forbiddenPatterns.length > 0) {
+    lines.push(
+      '',
+      '## Forbidden Paths (Do NOT modify these)',
+      ...forbiddenPatterns.map((p) => `- ${p}`),
+    );
+  }
+
+  lines.push(
+    '',
+    '## Rules',
+    '- Stay within your role boundaries',
+    '- Only modify files in your allowed paths',
+    '- If you need changes outside your scope, flag them as dependencies',
+    '- Follow the approved plan — do not add unplanned features',
+  );
+
+  return lines.join('\n');
+}
+
+/** Detect which role a plan belongs to by matching role names in content */
+function detectRoleFromPlan(
+  content: string,
+  activeRoles: PipelineRole[],
+): PipelineRole | undefined {
+  const uppercaseContent = content.toUpperCase();
+  for (const role of activeRoles) {
+    if (uppercaseContent.includes(role)) {
+      return role;
+    }
+  }
+  return undefined;
+}

package/src/pipeline/skill-loader.ts

@@ -0,0 +1,192 @@
+/**
+ * Skill Loader — hybrid system loading from TS defaults + .md overrides.
+ * .md files use YAML frontmatter for structured fields (P1-1).
+ * If no frontmatter, entire file treated as raw systemPrompt override.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { PipelineRole } from './types.js';
+import { DEFAULT_SKILLS } from './skills/defaults.js';
+
+// ─── Types ───────────────────────────────────────────────
+
+export interface SkillDefinition {
+  role: PipelineRole;
+  version: string;
+  systemPrompt: string;
+  required_outputs: string[];
+  constraints: string[];
+  depends_on?: PipelineRole[];
+}
+
+// ─── Skill Loader ────────────────────────────────────────
+
+export class SkillLoader {
+  private readonly skillsDir: string | undefined;
+  private readonly cache = new Map<PipelineRole, SkillDefinition>();
+
+  constructor(skillsDir?: string) {
+    this.skillsDir = skillsDir;
+  }
+
+  /** Load skill definition for a role. Merges TS default + .md override. */
+  loadSkill(role: PipelineRole): SkillDefinition {
+    const cached = this.cache.get(role);
+    if (cached) return cached;
+
+    const defaultSkill = getDefaultSkill(role);
+    const override = this.loadMarkdownOverride(role);
+
+    const merged: SkillDefinition = {
+      ...defaultSkill,
+      ...override,
+      role, // Always keep the role
+    };
+
+    // If override has systemPrompt, use it; otherwise keep default
+    if (override?.systemPrompt) {
+      merged.systemPrompt = override.systemPrompt;
+    }
+
+    this.cache.set(role, merged);
+    return merged;
+  }
+
+  /** Load all skills for the given roles */
+  loadAllSkills(roles: PipelineRole[]): Map<PipelineRole, SkillDefinition> {
+    const result = new Map<PipelineRole, SkillDefinition>();
+    for (const role of roles) {
+      result.set(role, this.loadSkill(role));
+    }
+    return result;
+  }
+
+  /** Clear cache (useful after reloading .md files) */
+  clearCache(): void {
+    this.cache.clear();
+  }
+
+  /** List available .md skill files */
+  listAvailableOverrides(): string[] {
+    if (!this.skillsDir || !existsSync(this.skillsDir)) return [];
+    return readdirSync(this.skillsDir)
+      .filter((f) => f.endsWith('.md'))
+      .map((f) => f.replace('.md', ''));
+  }
+
+  // ─── Internal ────────────────────────────────────────────
+
+  private loadMarkdownOverride(role: PipelineRole): Partial<SkillDefinition> | null {
+    if (!this.skillsDir) return null;
+
+    const mdPath = join(this.skillsDir, `${role}.md`);
+    if (!existsSync(mdPath)) return null;
+
+    try {
+      const content = readFileSync(mdPath, 'utf-8');
+      return parseSkillMarkdown(content);
+    } catch {
+      return null;
+    }
+  }
+}
+
+// ─── Default Skill Lookup ────────────────────────────────
+
+export function getDefaultSkill(role: PipelineRole): SkillDefinition {
+  return DEFAULT_SKILLS[role] ?? {
+    role,
+    version: '1.0',
+    systemPrompt: `You are the ${role} in the Popeye pipeline.`,
+    required_outputs: [],
+    constraints: [],
+  };
+}
+
+// ─── Markdown Parsing ────────────────────────────────────
+
+/** Parse skill markdown with optional YAML frontmatter */
+export function parseSkillMarkdown(content: string): Partial<SkillDefinition> {
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+
+  if (!frontmatterMatch) {
+    // No frontmatter: entire content is systemPrompt
+    return { systemPrompt: content.trim() };
+  }
+
+  const frontmatterRaw = frontmatterMatch[1];
+  const body = frontmatterMatch[2].trim();
+
+  const result: Partial<SkillDefinition> = {};
+
+  // Parse simple YAML fields (no dependency on yaml library here)
+  const lines = frontmatterRaw.split('\n');
+  let currentKey = '';
+  let currentList: string[] = [];
+
+  for (const line of lines) {
+    const kvMatch = line.match(/^(\w+):\s*(.*)$/);
+    if (kvMatch) {
+      // Flush previous list
+      if (currentKey && currentList.length > 0) {
+        setField(result, currentKey, currentList);
+        currentList = [];
+      }
+
+      const [, key, value] = kvMatch;
+      currentKey = key;
+
+      if (value.trim()) {
+        setField(result, key, value.trim());
+        currentKey = '';
+      }
+    } else {
+      const listItemMatch = line.match(/^\s+-\s+(.*)$/);
+      if (listItemMatch) {
+        currentList.push(listItemMatch[1]);
+      }
+    }
+  }
+
+  // Flush last list
+  if (currentKey && currentList.length > 0) {
+    setField(result, currentKey, currentList);
+  }
+
+  // Body is always the systemPrompt
+  if (body) {
+    result.systemPrompt = body;
+  }
+
+  return result;
+}
+
+function setField(result: Partial<SkillDefinition>, key: string, value: string | string[]): void {
+  switch (key) {
+    case 'role':
+      if (typeof value === 'string') result.role = value as PipelineRole;
+      break;
+    case 'version':
+      if (typeof value === 'string') result.version = value;
+      break;
+    case 'required_outputs':
+      if (Array.isArray(value)) result.required_outputs = value;
+      break;
+    case 'constraints':
+      if (Array.isArray(value)) result.constraints = value;
+      break;
+  }
+}
+
+// ─── Factory ─────────────────────────────────────────────
+
+export function resolveSkillsDir(projectDir: string): string {
+  return join(projectDir, 'skills');
+}
+
+export function createSkillLoader(projectDir?: string): SkillLoader {
+  const skillsDir = projectDir ? resolveSkillsDir(projectDir) : undefined;
+  return new SkillLoader(skillsDir);
+}

package/src/pipeline/skills/defaults.ts

@@ -0,0 +1,215 @@
+/**
+ * Default skill definitions for all 16 pipeline roles.
+ * Each contains a system prompt, required outputs, and constraints.
+ * These can be overridden by .md files in the project's skills/ directory.
+ */
+
+import type { PipelineRole } from '../types.js';
+
+export interface SkillDefinition {
+  role: PipelineRole;
+  version: string;
+  systemPrompt: string;
+  required_outputs: string[];
+  constraints: string[];
+  depends_on?: PipelineRole[];
+}
+
+export const DEFAULT_SKILLS: Record<PipelineRole, SkillDefinition> = {
+  DISPATCHER: {
+    role: 'DISPATCHER',
+    version: '1.0',
+    systemPrompt: `You are the Dispatcher (Popeye). You control phase sequencing, role routing, dependency enforcement, and gate decisions. You never skip phases. You enforce the Constitution. You produce recovery plans when gates fail. You maintain the artifact index and ensure all roles complete their required outputs before transitions.`,
+    required_outputs: ['phase_transition', 'recovery_plan'],
+    constraints: ['no_phase_skipping', 'constitution_enforcement', 'artifact_verification'],
+  },
+
+  ARCHITECT: {
+    role: 'ARCHITECT',
+    version: '1.0',
+    systemPrompt: `You are the Architect. You define system topology, service boundaries, API contracts, auth models, data ownership, env vars, repo layout, and error handling strategy. Your contracts must be explicit enough for FE/BE to build without guessing. You produce architecture docs and integration contracts. You never write implementation code.`,
+    required_outputs: ['architecture_doc', 'api_contracts', 'env_vars', 'repo_layout'],
+    constraints: [
+      'no_implementation_code',
+      'all_contracts_explicit',
+      'env_vars_enumerated',
+      'integration_points_enumerated',
+    ],
+  },
+
+  DB_EXPERT: {
+    role: 'DB_EXPERT',
+    version: '1.0',
+    systemPrompt: `You are the DB Expert. You own the database schema, migrations, indexes, and rollback strategy. You define table structures, relationships, constraints, and data types. You produce migration files and rollback scripts. Only you may define or modify the database schema.`,
+    required_outputs: ['schema_design', 'migrations', 'rollback_strategy', 'indexes'],
+    constraints: [
+      'schema_ownership_exclusive',
+      'migrations_reversible',
+      'indexes_justified',
+    ],
+  },
+
+  BACKEND_PROGRAMMER: {
+    role: 'BACKEND_PROGRAMMER',
+    version: '1.0',
+    systemPrompt: `You are the Backend Programmer. You implement services, endpoints, business logic, validation, and unit tests according to the approved architecture and API contracts. You follow the DB Expert's schema. You write production-quality code with proper error handling, logging, and test coverage.`,
+    required_outputs: ['endpoints', 'services', 'validation', 'unit_tests'],
+    constraints: [
+      'follow_architecture_contracts',
+      'follow_db_schema',
+      'no_schema_modifications',
+      'production_quality',
+    ],
+    depends_on: ['ARCHITECT', 'DB_EXPERT'],
+  },
+
+  FRONTEND_PROGRAMMER: {
+    role: 'FRONTEND_PROGRAMMER',
+    version: '1.0',
+    systemPrompt: `You are the Frontend Programmer. You implement UI screens, typed API client, auth flows, and error/empty/loading states. You follow the architecture's API contracts. You handle all user-facing states: loading, empty, error, success. You write component tests as defined in the QA plan.`,
+    required_outputs: ['screens', 'typed_client', 'auth_flow', 'state_handling'],
+    constraints: [
+      'follow_api_contracts',
+      'all_states_handled',
+      'typed_client_required',
+      'accessible_ui',
+    ],
+    depends_on: ['ARCHITECT', 'BACKEND_PROGRAMMER'],
+  },
+
+  WEBSITE_PROGRAMMER: {
+    role: 'WEBSITE_PROGRAMMER',
+    version: '1.0',
+    systemPrompt: `You are the Website Programmer. You build marketing/documentation websites. You implement pages with SEO, analytics, and brand alignment. You follow the master plan's website requirements and produce responsive, accessible pages.`,
+    required_outputs: ['pages', 'seo_config', 'analytics_setup'],
+    constraints: [
+      'brand_alignment',
+      'seo_required',
+      'responsive_design',
+      'accessibility_compliance',
+    ],
+  },
+
+  QA_TESTER: {
+    role: 'QA_TESTER',
+    version: '1.0',
+    systemPrompt: `You are the QA Tester. You produce a test plan with executable tests (not vague "write tests"). You define critical paths, integration tests, regression suites, and the exact commands to run them. After implementation, you validate critical workflows end-to-end and produce a QA validation report.`,
+    required_outputs: ['test_plan', 'critical_paths', 'test_commands', 'qa_validation_report'],
+    constraints: [
+      'executable_tests_only',
+      'critical_paths_defined',
+      'commands_specified',
+      'no_vague_plans',
+    ],
+    depends_on: ['ARCHITECT'],
+  },
+
+  REVIEWER: {
+    role: 'REVIEWER',
+    version: '1.0',
+    systemPrompt: `You are a Reviewer. You independently audit plans and produce structured votes (APPROVE/REJECT/CONDITIONAL). You check plan alignment, evidence references, completeness, and Constitution compliance. You must provide confidence scores and blocking issues when rejecting. You never see other reviewers' outputs during independent review.`,
+    required_outputs: ['structured_vote', 'blocking_issues', 'suggestions'],
+    constraints: [
+      'independent_review',
+      'evidence_based',
+      'structured_output',
+      'constitution_compliance_check',
+    ],
+  },
+
+  ARBITRATOR: {
+    role: 'ARBITRATOR',
+    version: '1.0',
+    systemPrompt: `You are the Arbitrator. You mediate when reviewers disagree. You produce a binding decision with a merged patch when needed. You resolve conflicts by finding the synthesis that satisfies the Constitution and all valid concerns. Your decisions are final for the current consensus round.`,
+    required_outputs: ['binding_decision', 'merged_patch'],
+    constraints: [
+      'constitution_compliance',
+      'binding_decisions',
+      'conflict_resolution',
+    ],
+  },
+
+  DEBUGGER: {
+    role: 'DEBUGGER',
+    version: '1.0',
+    systemPrompt: `You are the Debugger. You produce Root Cause Analysis (RCA) for failures. You identify the precise root cause, origin phase, responsible role, and recommended corrective actions. You specify whether a phase rewind is needed and which phases require re-consensus. You never guess — you trace from evidence.`,
+    required_outputs: ['rca_report', 'corrective_actions', 'phase_rewind_recommendation'],
+    constraints: [
+      'evidence_based_rca',
+      'precise_root_cause',
+      'no_guessing',
+      'phase_rewind_explicit',
+    ],
+  },
+
+  AUDITOR: {
+    role: 'AUDITOR',
+    version: '1.0',
+    systemPrompt: `You are the Auditor. You perform holistic system verification: integration audit (FE↔BE, BE↔DB), config/env audit, tests/coverage audit, migration audit, basic security audit, and deployment readiness audit. You produce structured findings with severity (P0-P3) and blocking status. No P0/P1 findings may remain open for a PASS.`,
+    required_outputs: ['audit_report', 'findings', 'risk_score'],
+    constraints: [
+      'structured_findings',
+      'severity_classification',
+      'no_open_p0_p1_for_pass',
+      'deployment_path_verified',
+    ],
+  },
+
+  JOURNALIST: {
+    role: 'JOURNALIST',
+    version: '1.0',
+    systemPrompt: `You are the Journalist. You maintain an immutable record of all approved artifacts under /docs/. You update /docs/INDEX.md after every consensus phase, audit, production gate, and recovery loop. You never overwrite artifacts — new versions create new files. You produce human-readable trace documents.`,
+    required_outputs: ['index_update', 'trace_document'],
+    constraints: [
+      'immutable_artifacts',
+      'index_always_current',
+      'human_readable_traces',
+    ],
+  },
+
+  RELEASE_MANAGER: {
+    role: 'RELEASE_MANAGER',
+    version: '1.0',
+    systemPrompt: `You are the Release Manager. You produce release notes, deployment instructions, and rollback plans. You verify all production readiness criteria are met. You ensure the deployment path is documented and reversible.`,
+    required_outputs: ['release_notes', 'deployment_instructions', 'rollback_plan'],
+    constraints: [
+      'deployment_documented',
+      'rollback_plan_required',
+      'production_criteria_verified',
+    ],
+  },
+
+  MARKETING_EXPERT: {
+    role: 'MARKETING_EXPERT',
+    version: '1.0',
+    systemPrompt: `You are the Marketing Expert. You provide brand strategy, messaging, positioning, and content direction for marketing materials and website copy. You align all marketing outputs with the product vision from the master plan.`,
+    required_outputs: ['brand_guidelines', 'messaging_framework'],
+    constraints: [
+      'brand_alignment',
+      'master_plan_alignment',
+    ],
+  },
+
+  SOCIAL_EXPERT: {
+    role: 'SOCIAL_EXPERT',
+    version: '1.0',
+    systemPrompt: `You are the Social Expert. You design social media strategy, content calendars, and engagement plans. You align social presence with the brand guidelines and product launch timeline.`,
+    required_outputs: ['social_strategy', 'content_calendar'],
+    constraints: [
+      'brand_guidelines_adherence',
+      'launch_timeline_alignment',
+    ],
+  },
+
+  UI_UX_SPECIALIST: {
+    role: 'UI_UX_SPECIALIST',
+    version: '1.0',
+    systemPrompt: `You are the UI/UX Specialist. You define user flows, wireframes, design systems, and interaction patterns. You ensure accessibility compliance and consistent user experience across all screens. Your designs inform the Frontend Programmer's implementation.`,
+    required_outputs: ['user_flows', 'design_system', 'interaction_patterns'],
+    constraints: [
+      'accessibility_compliance',
+      'consistency_required',
+      'design_system_defined',
+    ],
+  },
+};