popeye-cli 2.1.0 → 2.2.0

package/src/generators/all.ts

@@ -10,7 +10,8 @@ import type { GenerationResult } from './python.js';
 import { generateFullstackProject } from './fullstack.js';
 import { generateWebsiteProject } from './website.js';
 import type { WebsiteContentContext } from './website-context.js';
-import { buildWebsiteContext, validateWebsiteContext } from './website-context.js';
+import { buildWebsiteContext, validateWebsiteContext, resolveBrandAssets } from './website-context.js';
+import { loadWebsiteStrategy } from '../workflow/website-strategy.js';
 import {
   generateDesignTokensPackage as generateDesignTokensPackageImpl,
   generateUiPackage as generateUiPackageImpl,
@@ -403,6 +404,25 @@ export async function generateAllProject(
       console.warn(`[website-context] Warning: ${contextWarning}`);
     }
 
+    // Resolve brand assets (logo output path) — must happen after buildWebsiteContext
+    if (contentContext?.brand) {
+      try {
+        contentContext.brandAssets = await resolveBrandAssets(projectDir, contentContext.brand);
+      } catch {
+        // Non-fatal: brand assets are optional
+      }
+    }
+
+    // Load website strategy if previously generated (e.g. re-scaffold)
+    try {
+      const strategyData = await loadWebsiteStrategy(projectDir);
+      if (strategyData && contentContext) {
+        contentContext.strategy = strategyData.strategy;
+      }
+    } catch {
+      // Strategy won't exist on first scaffold — generated later by runPlanMode
+    }
+
     // Soft validation: log quality issues without blocking monorepo generation
     if (contentContext) {
       const validation = validateWebsiteContext(contentContext, projectName);
@@ -419,12 +439,14 @@ export async function generateAllProject(
     filesCreated.push(...fullstackResult.filesCreated);
 
     // Generate website app
+    // skipValidation: strategy is generated later by runPlanMode, not at scaffold time
     const websiteResult = await generateWebsiteProject(spec, projectDir, {
       baseDir: path.join(projectDir, 'apps', 'website'),
       workspaceMode: true,
       skipDocker: true, // Website runs outside Docker (npm run dev / npm start)
       skipReadme: false,
       contentContext: contentContext,
+      skipValidation: true,
     });
     if (!websiteResult.success) {
       return {

package/src/pipeline/artifact-manager.ts

@@ -45,6 +45,8 @@ const ARTIFACT_DIRS: Record<string, string> = {
   resolved_commands: 'checks',
   constitution: 'governance',
   change_request: 'governance',
+  additional_context: 'context',
+  skill_generation_log: 'context',
 };
 
 /** All required subdirectories under /docs/ */
@@ -62,6 +64,7 @@ const DOCS_SUBDIRS = [
   'checks',
   'journal',
   'governance',
+  'context',
 ];
 
 // ─── Helper Functions ────────────────────────────────────

package/src/pipeline/gate-engine.ts

@@ -40,7 +40,7 @@ export interface GateResult {
 const GATE_DEFINITIONS: Record<PipelinePhase, GateDefinition> = {
   INTAKE: {
     phase: 'INTAKE',
-    requiredArtifacts: ['master_plan', 'repo_snapshot', 'constitution'],
+    requiredArtifacts: ['master_plan', 'repo_snapshot'],
     requiredChecks: [],
     allowedTransitions: ['CONSENSUS_MASTER_PLAN'],
     failTransition: 'RECOVERY_LOOP',

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

@@ -159,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);
 
@@ -201,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/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,14 +27,7 @@ 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);
-    }
-    pipeline.constitutionHash = computeConstitutionHash(projectDir);
-
-    // 3. Store additional_context artifact if session guidance provided
+    // 2. Store additional_context artifact if session guidance provided
     const guidance = pipeline.sessionGuidance ?? '';
     if (guidance) {
       const ctxEntry = artifactManager.createAndStoreText(
@@ -38,6 +38,9 @@ export async function runIntake(context: PhaseContext): Promise<PhaseResult> {
       artifacts.push(ctxEntry);
     }
 
+    // 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(
@@ -45,20 +48,66 @@ export async function runIntake(context: PhaseContext): Promise<PhaseResult> {
       context.state.language,
     );
 
-    // 5. Create master plan — prepend guidance so planner sees constraints first
+    // 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,
+      });
+
+      // 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);
 
-    // 6. Store master plan as artifact
+    // 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/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');
+}