popeye-cli 2.0.0 → 2.2.0

package/src/pipeline/migration.ts

@@ -3,9 +3,11 @@
  * Auto-triggered on load when pipelinePhase is missing from state.
  */
 
-import type { PipelinePhase, PipelineState, PipelineRole } from './types.js';
+import type { PipelinePhase, PipelineState } from './types.js';
 import { createDefaultPipelineState } from './types.js';
 import type { ProjectState, WorkflowPhase } from '../types/workflow.js';
+import { getActiveRoles } from './skills/role-map.js';
+import type { OutputLanguage } from '../types/project.js';
 
 // ─── Phase Mapping ───────────────────────────────────────
 
@@ -52,8 +54,8 @@ export function migrateToPipelineState(state: ProjectState): PipelineState {
   // Map legacy phase
   pipeline.pipelinePhase = toPipelinePhase(state.phase);
 
-  // Derive active roles from language
-  pipeline.activeRoles = deriveActiveRoles(state.language);
+  // Derive active roles from language using shared role-map
+  pipeline.activeRoles = getActiveRoles(state.language as OutputLanguage);
 
   return pipeline;
 }
@@ -62,30 +64,3 @@ export function migrateToPipelineState(state: ProjectState): PipelineState {
 export function needsPipelineMigration(state: unknown): boolean {
   return !(state as Record<string, unknown>).pipeline;
 }
-
-// ─── Role Derivation ─────────────────────────────────────
-
-function deriveActiveRoles(language: string): PipelineRole[] {
-  const baseRoles: PipelineRole[] = [
-    'DISPATCHER', 'ARCHITECT', 'REVIEWER', 'ARBITRATOR',
-    'DEBUGGER', 'AUDITOR', 'JOURNALIST', 'RELEASE_MANAGER',
-    'QA_TESTER',
-  ];
-
-  switch (language) {
-    case 'fullstack':
-    case 'all':
-      return [
-        ...baseRoles,
-        'DB_EXPERT', 'BACKEND_PROGRAMMER', 'FRONTEND_PROGRAMMER',
-        'WEBSITE_PROGRAMMER', 'UI_UX_SPECIALIST',
-      ];
-    case 'python':
-    case 'typescript':
-      return [...baseRoles, 'BACKEND_PROGRAMMER'];
-    case 'website':
-      return [...baseRoles, 'WEBSITE_PROGRAMMER', 'MARKETING_EXPERT', 'SOCIAL_EXPERT'];
-    default:
-      return [...baseRoles, 'BACKEND_PROGRAMMER'];
-  }
-}

package/src/pipeline/orchestrator.ts

@@ -53,6 +53,8 @@ export interface PipelineOptions {
   projectDir: string;
   state: ProjectState;
   consensusConfig?: Partial<ConsensusConfig>;
+  /** User steering, upgrade context, or resume instructions */
+  additionalContext?: string;
   onPhaseStart?: (phase: PipelinePhase) => void;
   onPhaseComplete?: (phase: PipelinePhase, result: PhaseResult) => void;
   onProgress?: (message: string) => void;
@@ -88,6 +90,7 @@ export async function runPipeline(options: PipelineOptions): Promise<PipelineRes
     projectDir,
     state,
     consensusConfig,
+    additionalContext,
     onPhaseStart,
     onPhaseComplete,
     onProgress,
@@ -97,6 +100,11 @@ export async function runPipeline(options: PipelineOptions): Promise<PipelineRes
   const pipeline: PipelineState = (state as unknown as { pipeline?: PipelineState }).pipeline
     ?? createDefaultPipelineState();
 
+  // Persist user guidance in pipeline state so it survives resume
+  if (additionalContext && !pipeline.sessionGuidance) {
+    pipeline.sessionGuidance = additionalContext;
+  }
+
   // Create context dependencies
   const gateEngine = createGateEngine();
   const artifactManager = createArtifactManager(projectDir);
@@ -151,6 +159,11 @@ export async function runPipeline(options: PipelineOptions): Promise<PipelineRes
 
     onPhaseComplete?.(phase, result);
 
+    // Log phase outcome — critical for diagnosing pipeline loops
+    if (!result.success) {
+      onProgress?.(`Phase ${phase} FAILED: ${result.message}${result.error ? ` — ${result.error}` : ''}`);
+    }
+
     // v1.1: Verify constitution integrity before evaluating gate
     const constitutionCheck = verifyConstitution(pipeline, projectDir);
 
@@ -193,6 +206,7 @@ export async function runPipeline(options: PipelineOptions): Promise<PipelineRes
       }
     } else {
       // ─── FAIL ────────────────────────────────────────
+      onProgress?.(`Gate FAILED for ${phase}: ${gateResult.blockers.join('; ')}`);
       if (pipeline.recoveryCount >= pipeline.maxRecoveryIterations) {
         phase = 'STUCK';
       } else {

package/src/pipeline/phases/implementation.ts

@@ -26,11 +26,15 @@ export async function runImplementation(context: PhaseContext): Promise<PhaseRes
         .join('\n\n');
     }
 
-    // Run existing execution mode with optional role context
+    // Merge session guidance with role prompt so execution sees user intent
+    const guidance = pipeline.sessionGuidance;
+    const systemPrompt = [combinedRolePrompt, guidance].filter(Boolean).join('\n\n') || undefined;
+
+    // Run existing execution mode with optional role context + guidance
     const { runExecutionMode } = await import('../../workflow/execution-mode.js');
     await runExecutionMode({
       projectDir,
-      ...(combinedRolePrompt ? { systemPrompt: combinedRolePrompt } : {}),
+      ...(systemPrompt ? { systemPrompt } : {}),
     });
 
     // Generate post-implementation repo snapshot

package/src/pipeline/phases/intake.ts

@@ -2,12 +2,19 @@
  * INTAKE phase — normalize user prompt into structured Master Plan v1.
  * Reuses expandIdea() and createPlan() from workflow.
  * v1.1: Creates constitution artifact and stores hash.
+ * v1.2: Generates project-specific skills and constitution.
  */
 
+import { join } from 'node:path';
+
 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';
+import { getActiveRoles, inferTechStack } from '../skills/role-map.js';
+import { generateProjectSkills } from '../skills/generator.js';
+import { generateConstitution } from '../skills/constitution-generator.js';
+import type { OutputLanguage } from '../../types/project.js';
 
 export async function runIntake(context: PhaseContext): Promise<PhaseResult> {
   const { projectDir, pipeline, artifactManager } = context;
@@ -20,31 +27,87 @@ export async function runIntake(context: PhaseContext): Promise<PhaseResult> {
     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);
+    // 2. Store additional_context artifact if session guidance provided
+    const guidance = pipeline.sessionGuidance ?? '';
+    if (guidance) {
+      const ctxEntry = artifactManager.createAndStoreText(
+        'additional_context',
+        guidance,
+        'INTAKE',
+      );
+      artifacts.push(ctxEntry);
     }
-    pipeline.constitutionHash = computeConstitutionHash(projectDir);
 
-    // 3. Expand idea using existing workflow
+    // 3. Push pre-AI artifacts to pipeline state now (survives if AI calls fail below)
+    pipeline.artifacts.push(...artifacts);
+
+    // 4. 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. Determine active roles
+    const language = context.state.language as OutputLanguage;
+    pipeline.activeRoles = getActiveRoles(language);
+
+    // 6-8. Generate project-specific skills and constitution (non-fatal)
+    const skillsDir = join(projectDir, 'skills');
+    try {
+      const projectName = context.state.name ?? 'Project';
+
+      await generateProjectSkills(
+        {
+          language,
+          expandedSpec: expandedIdea,
+          snapshot,
+          sessionGuidance: guidance || undefined,
+          activeRoles: pipeline.activeRoles,
+          skillsDir,
+          projectName,
+        },
+        artifactManager,
+      );
+
+      const techStack = inferTechStack(language, snapshot, expandedIdea);
+      generateConstitution({
+        language,
+        projectName,
+        techStack,
+        expandedSpec: expandedIdea,
+        sessionGuidance: guidance || undefined,
+        skillsDir,
+      });
 
-    // 5. Store master plan as artifact
+      // Clear skill loader cache so it picks up new .md files
+      context.skillLoader.clearCache();
+    } catch {
+      // Skill/constitution generation is non-fatal — pipeline continues with defaults
+    }
+
+    // 9. Create constitution artifact and store hash (AFTER generation)
+    const constitutionEntry = createConstitutionArtifact(projectDir, artifactManager);
+    if (constitutionEntry) {
+      artifacts.push(constitutionEntry);
+      pipeline.artifacts.push(constitutionEntry);
+    }
+    pipeline.constitutionHash = computeConstitutionHash(projectDir);
+
+    // 10. Create master plan — prepend guidance so planner sees constraints first
+    const planInput = guidance
+      ? `${guidance}\n\n---\n\n${expandedIdea}`
+      : expandedIdea;
+    const plan = await createPlan(planInput, '', context.state.language);
+
+    // 11. Store master plan as artifact
     const planEntry = artifactManager.createAndStoreText(
       'master_plan',
       plan,
       'INTAKE',
     );
     artifacts.push(planEntry);
-    pipeline.artifacts.push(...artifacts);
+    pipeline.artifacts.push(planEntry);
 
     return successResult('INTAKE', artifacts, 'Master Plan v1 created');
   } catch (err) {

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

@@ -33,9 +33,11 @@ export async function runRecoveryLoop(context: PhaseContext): Promise<PhaseResul
 
     // 3. Generate RCA via Claude with Debugger skill
     const { executePrompt } = await import('../../adapters/claude.js');
+    const guidance = pipeline.sessionGuidance;
     const rcaPrompt = [
       debuggerSkill.systemPrompt,
       '',
+      ...(guidance ? ['## User Guidance', guidance, ''] : []),
       '## Failure Evidence',
       failureEvidence,
       '',

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

@@ -46,10 +46,9 @@ export async function runRolePlanning(context: PhaseContext): Promise<PhaseResul
 
     const { executePrompt } = await import('../../adapters/claude.js');
 
-    // Generate plan for each role
+    // Generate plan for each role (skip roles not in activeRoles)
     for (const role of PLANNING_ROLES) {
-      // Skip website if not in active roles
-      if (role === 'WEBSITE_PROGRAMMER' && !pipeline.activeRoles.includes('WEBSITE_PROGRAMMER')) {
+      if (!pipeline.activeRoles.includes(role)) {
         continue;
       }
 

package/src/pipeline/skills/constitution-generator.ts

@@ -0,0 +1,236 @@
+/**
+ * Deterministic constitution generation — no AI call required.
+ * Produces skills/POPEYE_CONSTITUTION.md from templates + inferred tech stack.
+ * Includes pipeline governance invariants that never change.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { OutputLanguage } from '../../types/project.js';
+import type { ConstitutionContext, TechStack } from './types.js';
+
+// ─── Constants ──────────────────────────────────────────
+
+const CONSTITUTION_FILENAME = 'POPEYE_CONSTITUTION.md';
+const PIPELINE_VERSION = '1.0';
+
+// ─── Public API ─────────────────────────────────────────
+
+/**
+ * Generate the project constitution file if it doesn't already exist.
+ * Entirely deterministic — built from templates and tech stack data.
+ *
+ * @param context - Constitution generation context
+ */
+export function generateConstitution(context: ConstitutionContext): void {
+  const { skillsDir } = context;
+
+  if (shouldSkipConstitution(skillsDir)) {
+    return;
+  }
+
+  if (!existsSync(skillsDir)) {
+    mkdirSync(skillsDir, { recursive: true });
+  }
+
+  const content = buildConstitutionContent(context);
+  const constitutionPath = join(skillsDir, CONSTITUTION_FILENAME);
+  writeFileSync(constitutionPath, content, 'utf-8');
+}
+
+/**
+ * Check if constitution generation should be skipped.
+ * Returns true if the file already exists (hand-written or prior run).
+ *
+ * @param skillsDir - Path to the skills directory
+ * @returns true if generation should be skipped
+ */
+export function shouldSkipConstitution(skillsDir: string): boolean {
+  const constitutionPath = join(skillsDir, CONSTITUTION_FILENAME);
+  return existsSync(constitutionPath);
+}
+
+// ─── Content Assembly ───────────────────────────────────
+
+/**
+ * Build the full constitution markdown content.
+ *
+ * @param context - Constitution generation context
+ * @returns Complete markdown string
+ */
+function buildConstitutionContent(context: ConstitutionContext): string {
+  const { projectName, language, techStack, sessionGuidance } = context;
+  const date = new Date().toISOString().split('T')[0];
+
+  const sections = [
+    `# Project Constitution: ${projectName}`,
+    '',
+    `Generated: ${date} | Language: ${language} | Pipeline: v${PIPELINE_VERSION}`,
+    '',
+    getTechStackSection(techStack),
+    getArchitectureRules(techStack),
+    getCodeQualityRules(),
+    getGovernanceRules(),
+    getConstraintsSection(language, sessionGuidance),
+    getImmutabilitySection(),
+  ];
+
+  return sections.join('\n');
+}
+
+// ─── Template Sections ──────────────────────────────────
+
+/**
+ * Generate the tech stack section from inferred stack data.
+ *
+ * @param techStack - Inferred tech stack
+ * @returns Markdown section
+ */
+export function getTechStackSection(techStack: TechStack): string {
+  const lines = ['## Tech Stack'];
+  if (techStack.language) lines.push(`- Language: ${techStack.language}`);
+  if (techStack.backend) lines.push(`- Framework: ${techStack.backend}`);
+  if (techStack.frontend) lines.push(`- Frontend: ${techStack.frontend}`);
+  if (techStack.database) lines.push(`- Database: ${techStack.database}`);
+  if (techStack.orm) lines.push(`- ORM: ${techStack.orm}`);
+  if (techStack.testing) lines.push(`- Testing: ${techStack.testing}`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Generate architecture rules based on the tech stack.
+ *
+ * @param techStack - Inferred tech stack
+ * @returns Markdown section
+ */
+export function getArchitectureRules(techStack: TechStack): string {
+  const rules: string[] = [];
+  let ruleNum = 1;
+
+  if (techStack.backend?.includes('FastAPI')) {
+    rules.push(`${ruleNum++}. All API endpoints MUST use async/await`);
+  }
+  if (techStack.backend?.includes('Express')) {
+    rules.push(`${ruleNum++}. Use Express middleware pattern for cross-cutting concerns`);
+  }
+  if (techStack.backend?.includes('Django')) {
+    rules.push(`${ruleNum++}. Follow Django app structure conventions`);
+  }
+  if (techStack.orm?.includes('SQLAlchemy')) {
+    rules.push(`${ruleNum++}. Database access exclusively via SQLAlchemy ORM`);
+  }
+  if (techStack.orm?.includes('Prisma')) {
+    rules.push(`${ruleNum++}. Database access exclusively via Prisma client`);
+  }
+  if (techStack.language?.includes('Python')) {
+    rules.push(`${ruleNum++}. Environment variables via python-dotenv, never hardcoded`);
+    rules.push(`${ruleNum++}. PEP8 style with type hints on all functions`);
+  }
+  if (techStack.language?.includes('TypeScript')) {
+    rules.push(`${ruleNum++}. TypeScript strict mode, no implicit any`);
+    rules.push(`${ruleNum++}. Environment variables via dotenv, never hardcoded`);
+  }
+  if (techStack.frontend?.includes('React')) {
+    rules.push(`${ruleNum++}. React components use functional patterns with hooks`);
+  }
+  if (techStack.frontend?.includes('Next')) {
+    rules.push(`${ruleNum++}. Next.js App Router conventions for routing and layouts`);
+  }
+
+  // Always add a generic rule if nothing specific matched
+  if (rules.length === 0) {
+    rules.push('1. Environment variables never hardcoded in source code');
+    rules.push('2. Clear separation of concerns between modules');
+  }
+
+  return ['## Architecture Rules', ...rules, ''].join('\n');
+}
+
+/**
+ * Generate code quality rules (constant across all projects).
+ *
+ * @returns Markdown section
+ */
+export function getCodeQualityRules(): string {
+  return [
+    '## Code Quality',
+    '1. Maximum 500 lines per source file',
+    '2. Unit tests for every module (happy path + edge case + failure)',
+    '3. Standard logging (no unstructured print statements)',
+    '4. Docstrings/JSDoc on public functions',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Generate governance rules (pipeline invariants, constant).
+ *
+ * @returns Markdown section
+ */
+function getGovernanceRules(): string {
+  return [
+    '## Governance Rules',
+    '1. Consensus threshold: 0.95 with minimum 2 reviewers',
+    '2. All artifacts are immutable once stored (new versions create new files)',
+    '3. No placeholder content in production code or generated output',
+    '4. Gate failures route to RECOVERY_LOOP before phase retry',
+    '5. Constitution modifications during pipeline execution are forbidden',
+    '6. Change Requests required for scope changes after INTAKE',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Generate language-specific and session-specific constraints.
+ *
+ * @param language - Project language
+ * @param sessionGuidance - Optional session guidance text
+ * @returns Markdown section
+ */
+export function getConstraintsSection(
+  language: OutputLanguage,
+  sessionGuidance?: string,
+): string {
+  const lines = ['## Project Constraints'];
+
+  const langConstraints: Record<string, string[]> = {
+    python: ['- Python 3.11+ required', '- Use virtual environment (venv) for all operations'],
+    typescript: ['- Node.js 18+ required', '- ESM modules (import/export, .js extensions)'],
+    fullstack: [
+      '- Python 3.11+ for backend, Node.js 18+ for frontend',
+      '- Monorepo structure with clear app boundaries',
+    ],
+    website: ['- Node.js 18+ required', '- SSG/SSR optimization for performance and SEO'],
+    all: [
+      '- Python 3.11+ for backend, Node.js 18+ for frontend and website',
+      '- Monorepo structure with clear app boundaries',
+    ],
+  };
+
+  const constraints = langConstraints[language] ?? langConstraints.python;
+  lines.push(...constraints);
+
+  if (sessionGuidance) {
+    lines.push('', '### Session-Specific Guidance');
+    lines.push(sessionGuidance.slice(0, 500));
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Generate the immutability notice (constant).
+ *
+ * @returns Markdown section
+ */
+function getImmutabilitySection(): string {
+  return [
+    '## Immutability',
+    'This document MUST NOT be modified during pipeline execution.',
+    'Any modification triggers constitution verification failure at next gate.',
+    '',
+  ].join('\n');
+}