5-phase-workflow 1.9.5 → 2.0.1

package/bin/install.js

@@ -25,15 +25,60 @@ const log = {
   header: (msg) => console.log(`\n${colors.bright}${msg}${colors.reset}\n`)
 };
 
-// Version comparison (semver)
-// Uses parseInt to handle pre-release tags (e.g., "2-beta" → 2)
+// Version comparison (semver, including pre-release ordering)
 function compareVersions(v1, v2) {
-  const parts1 = v1.split('.').map(p => parseInt(p, 10) || 0);
-  const parts2 = v2.split('.').map(p => parseInt(p, 10) || 0);
+  const parsed1 = parseSemver(v1);
+  const parsed2 = parseSemver(v2);
+
   for (let i = 0; i < 3; i++) {
-    if (parts1[i] > parts2[i]) return 1;
-    if (parts1[i] < parts2[i]) return -1;
+    if (parsed1.core[i] > parsed2.core[i]) return 1;
+    if (parsed1.core[i] < parsed2.core[i]) return -1;
   }
+
+  return comparePrerelease(parsed1.prerelease, parsed2.prerelease);
+}
+
+function parseSemver(version) {
+  const normalized = String(version || '').trim().replace(/^v/, '').split('+')[0];
+  const prereleaseIndex = normalized.indexOf('-');
+  const corePart = prereleaseIndex === -1 ? normalized : normalized.slice(0, prereleaseIndex);
+  const prereleasePart = prereleaseIndex === -1 ? '' : normalized.slice(prereleaseIndex + 1);
+  const core = corePart.split('.').slice(0, 3).map(part => parseInt(part, 10) || 0);
+  while (core.length < 3) core.push(0);
+
+  return {
+    core,
+    prerelease: prereleasePart ? prereleasePart.split(/[.-]/) : []
+  };
+}
+
+function comparePrerelease(pre1, pre2) {
+  if (pre1.length === 0 && pre2.length === 0) return 0;
+  if (pre1.length === 0) return 1;
+  if (pre2.length === 0) return -1;
+
+  const length = Math.max(pre1.length, pre2.length);
+  for (let i = 0; i < length; i++) {
+    const id1 = pre1[i];
+    const id2 = pre2[i];
+    if (id1 === undefined) return -1;
+    if (id2 === undefined) return 1;
+    if (id1 === id2) continue;
+
+    const id1Numeric = /^[0-9]+$/.test(id1);
+    const id2Numeric = /^[0-9]+$/.test(id2);
+    if (id1Numeric && id2Numeric) {
+      const n1 = parseInt(id1, 10);
+      const n2 = parseInt(id2, 10);
+      if (n1 > n2) return 1;
+      if (n1 < n2) return -1;
+      continue;
+    }
+    if (id1Numeric) return -1;
+    if (id2Numeric) return 1;
+    return id1 > id2 ? 1 : -1;
+  }
+
   return 0;
 }
 
@@ -56,11 +101,15 @@ function getInstalledVersion(isGlobal) {
 
 // Get package version from package.json
 function getPackageVersion() {
-  const pkgPath = path.join(__dirname, '..', 'package.json');
+  const pkgPath = path.join(getPackageRoot(), 'package.json');
   const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
   return pkg.version;
 }
 
+function getPackageRoot() {
+  return path.join(__dirname, '..');
+}
+
 // Get full version info
 function getVersionInfo(targetPath, isGlobal) {
   const exists = checkExistingInstallation(targetPath);
@@ -126,9 +175,9 @@ function parseArgs() {
 // Show help message
 function showHelp() {
   console.log(`
-${colors.bright}5-Phase Workflow Installer${colors.reset}
+${colors.bright}dev-workflow Installer${colors.reset}
 
-Usage: npx 5-phase-workflow [options]
+Usage: npx foifi [options]
 
 Options:
   --global, -g      Install to ~/.claude/ (available across all projects)
@@ -141,13 +190,13 @@ Options:
   --help, -h        Show this help message
 
 Examples:
-  npx 5-phase-workflow              # Install locally for Claude Code
-  npx 5-phase-workflow --global     # Install globally for Claude Code
-  npx 5-phase-workflow --codex      # Install locally for Codex CLI
-  npx 5-phase-workflow --codex -g   # Install globally for Codex CLI
-  npx 5-phase-workflow --upgrade    # Auto-update to latest version
-  npx 5-phase-workflow --check      # Check version without updating
-  npx 5-phase-workflow --uninstall  # Remove from current directory
+  npx foifi              # Install locally for Claude Code
+  npx foifi --global     # Install globally for Claude Code
+  npx foifi --codex      # Install locally for Codex CLI
+  npx foifi --codex -g   # Install globally for Codex CLI
+  npx foifi --upgrade    # Auto-update to latest version
+  npx foifi --check      # Check version without updating
+  npx foifi --uninstall  # Remove from current directory
 `);
 }
 
@@ -228,7 +277,11 @@ function copyDirMerge(src, dest) {
 function getSourcePath() {
   // When installed via npm, __dirname is <install-location>/bin
   // Source files are in <install-location>/src
-  return path.join(__dirname, '..', 'src');
+  return path.join(getPackageRoot(), 'src');
+}
+
+function getPackageBinPath() {
+  return path.join(getPackageRoot(), 'bin');
 }
 
 // Copy directory recursively
@@ -251,6 +304,25 @@ function copyDir(src, dest) {
   }
 }
 
+function copyWorkflowHelperBins(targetPath) {
+  const managed = getWorkflowManagedFiles();
+  if (!managed.binHelpers || managed.binHelpers.length === 0) return;
+
+  const binSrc = getPackageBinPath();
+  const binDest = path.join(targetPath, 'bin');
+  if (!fs.existsSync(binDest)) {
+    fs.mkdirSync(binDest, { recursive: true });
+  }
+
+  for (const binHelper of managed.binHelpers) {
+    const src = path.join(binSrc, binHelper);
+    const dest = path.join(binDest, binHelper);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, dest);
+    }
+  }
+}
+
 // Remove directory recursively
 function removeDir(dir) {
   if (fs.existsSync(dir)) {
@@ -280,11 +352,28 @@ const LEGACY_REMOVED_FILES = [
   'agents/integration-agent.md',
   'agents/step-fixer.md',
   'agents/step-verifier.md',
-  'agents/verification-agent.md',
   'templates/STACK.md',
   'templates/STRUCTURE.md',
   'templates/CONVENTIONS.md',
-  'templates/INTEGRATIONS.md'
+  'templates/INTEGRATIONS.md',
+  'commands/5/plan-feature.md',
+  'commands/5/plan-implementation.md',
+  'commands/5/implement-feature.md',
+  'commands/5/verify.md',
+  'commands/5/verify-implementation.md',
+  'commands/5/review-code.md',
+  'commands/5/quick-implement.md',
+  'agents/component-executor.md',
+  'templates/workflow/FEATURE-SPEC.md',
+  'templates/workflow/VERIFICATION-REPORT.md',
+  'skills/5-plan-feature',
+  'skills/5-plan-implementation',
+  'skills/5-implement-feature',
+  'skills/5-verify',
+  'skills/5-verify-implementation',
+  'skills/5-review-code',
+  'skills/5-quick-implement',
+  'skills/configure-project'
 ];
 
 // Get list of workflow-owned files/directories (not user-created)
@@ -295,13 +384,14 @@ function getWorkflowManagedFiles() {
 
     // Agents: separate agent files referenced by commands via agent: frontmatter
     agents: [
-      'component-executor.md'
+      'step-executor-agent.md',
+      'step-orchestrator-agent.md',
+      'verification-agent.md'
     ],
 
     // Skills: specific skill directories
     skills: [
       'configure-docs-index',
-      'configure-project',
       'configure-skills',
       'generate-readme'
     ],
@@ -320,17 +410,22 @@ function getWorkflowManagedFiles() {
       'configure-tables.md'
     ],
 
+    // Helper binaries: runtime scripts invoked by commands
+    binHelpers: [
+      'sync-agents.js'
+    ],
+
     // Templates: specific template files
     templates: [
       // Project documentation templates
+      'AGENTS.md',
       'ARCHITECTURE.md',
       'CONCERNS.md',
       'TESTING.md',
       // Workflow output templates
-      'workflow/FEATURE-SPEC.md',
       'workflow/PLAN.md',
+      'workflow/PLAN-COMPACT.md',
       'workflow/STATE.json',
-      'workflow/VERIFICATION-REPORT.md',
       'workflow/REVIEW-FINDINGS.md',
       'workflow/REVIEW-SUMMARY.md',
       'workflow/FIX-PLAN.md'
@@ -365,7 +460,7 @@ function getFileManifest() {
     manifest.push(`hooks/${hook}`);
   }
 
-  // Templates are files (may include nested paths like workflow/FEATURE-SPEC.md)
+  // Templates are files (may include nested paths like workflow/PLAN.md)
   for (const template of managed.templates) {
     manifest.push(`templates/${template}`);
   }
@@ -377,6 +472,12 @@ function getFileManifest() {
     }
   }
 
+  if (managed.binHelpers) {
+    for (const binHelper of managed.binHelpers) {
+      manifest.push(`bin/${binHelper}`);
+    }
+  }
+
   return manifest;
 }
 
@@ -406,9 +507,30 @@ function convertClaudeToCodexMarkdown(content) {
   let converted = convertSlashCommandsToCodexMentions(content);
   // Replace .claude/ path references with .codex/
   converted = converted.replace(/\.claude\//g, '.codex/');
+  converted = convertClaudeSetupCommandsToCodexNotes(converted);
   return converted;
 }
 
+function convertClaudeSetupCommandsToCodexNotes(content) {
+  return content
+    .replace(
+      /1\. "Install now \(recommended\)" — run `claude mcp add context7 -- npx -y @anthropic-ai\/claude-code-mcp-server-context7` via Bash/g,
+      '1. "Install now" — not supported automatically in Codex; install Context7 using your Codex MCP setup outside this workflow, then rerun configuration'
+    )
+    .replace(
+      /- If user selects "Install now": execute the install command/g,
+      '- If user selects "Install now": explain that Codex cannot run the Claude Code installer command; leave `tools.context7.available = false` unless Context7 is already detected'
+    )
+    .replace(
+      /1\. "Install now \(recommended\)" — run `claude plugin install skill-creator@claude-plugins-official` via Bash/g,
+      '1. "Install now" — not supported automatically in Codex; install an equivalent skill authoring workflow outside this command, then rerun configuration'
+    )
+    .replace(
+      /- If user selects "Install now": execute the install command, then set `tools\.skillCreator\.available = true` in the config/g,
+      '- If user selects "Install now": explain that Codex cannot run the Claude Code plugin installer; leave `tools.skillCreator.available = false` unless an equivalent tool is already detected'
+    );
+}
+
 // Generate the adapter header that teaches Codex how to map Claude Code concepts
 function getCodexSkillAdapterHeader(skillName) {
   const invocation = `$${skillName}`;
@@ -423,8 +545,10 @@ This skill was authored for Claude Code. Map these tool references:
 | Claude Code | Codex Equivalent |
 |-------------|------------------|
 | \`AskUserQuestion\` | Ask the user directly in conversation |
-| \`Agent(subagent_type="Explore")\` | Research the codebase yourself using available tools |
-| \`Agent(prompt="...")\` | \`spawn_agent(message="...")\` |
+| \`Agent(subagent_type="Explore")\` | \`spawn_agent(agent_type="explorer", model="gpt-5.4-mini", reasoning_effort="low", message="...")\` |
+| \`Agent(prompt="...", model="haiku")\` | \`spawn_agent(model="gpt-5.4-mini", reasoning_effort="low", message="...")\` |
+| \`Agent(prompt="...", model="sonnet")\` | \`spawn_agent(model="gpt-5.4", reasoning_effort="medium", message="...")\` |
+| \`Agent(prompt="...")\` | \`spawn_agent(model="gpt-5.4-mini", reasoning_effort="low", message="...")\` unless the prompt explicitly requires complex reasoning |
 | \`Read\` | \`read_file\` |
 | \`Write\` | \`write_file\` |
 | \`Edit\` | \`patch\` |
@@ -434,11 +558,24 @@ This skill was authored for Claude Code. Map these tool references:
 | \`TaskCreate/TaskUpdate\` | Track progress internally |
 | \`EnterPlanMode\` | Not available — use structured output instead |
 
+## Codex Token Budget
+- Default to \`gpt-5.4-mini\` with \`reasoning_effort: low\` for exploration, orchestration, simple implementation, and mechanical file edits.
+- Use \`gpt-5.4\` with \`reasoning_effort: medium\` only for complex logic, cross-module behavior, security-sensitive changes, data migrations, final verification with meaningful logic review, or retries after failure.
+- Use stronger models only when a previous cheaper attempt failed for reasoning reasons.
+- Keep the parent skill context lean: delegate read-heavy exploration to explorer agents and pass only compact findings, target paths, pattern references, and command summaries between agents.
+
 ## Guard Rules (replaces plan-guard hook)
-During planning phases (plan-feature, plan-implementation):
+During the planning phase ($5-plan):
 - Do NOT write to any file outside \`.5/\`
-- Do NOT write source code — only specifications and plans
+- Do NOT write source code — only the unified plan and scan cache
 - Do NOT spawn implementation agents — only Explore/research agents
+
+## Update & Migration Notices (replaces statusline hooks)
+At the very start of this skill, before doing anything else, read these two files if they exist:
+- \`.5/.update-cache.json\` — if \`latestAvailableVersion\` is set, compare it to \`packageVersion\` in \`.5/version.json\`. If a newer version is available, tell the user: "foifi update available: <version> — run \`npx foifi --codex --upgrade\` to update."
+- \`.5/.migration-v2\` — if this file exists, tell the user: "You upgraded from foifi v1 to v2. Run \`$5-reconfigure\` to update your project configuration."
+
+Show each applicable notice once at the top of your response, then continue with the skill normally. Do not abort the skill because of a notice.
 </codex_skill_adapter>`;
 }
 
@@ -447,7 +584,7 @@ function convertClaudeCommandToCodexSkill(content, skillName) {
   const converted = convertClaudeToCodexMarkdown(content);
   const { frontmatter, body } = extractFrontmatterAndBody(converted);
 
-  let description = `Run 5-Phase Workflow: ${skillName}`;
+  let description = `Run dev-workflow: ${skillName}`;
   if (frontmatter) {
     const maybeDesc = extractFrontmatterField(frontmatter, 'description');
     if (maybeDesc) description = maybeDesc;
@@ -495,6 +632,11 @@ function getCodexFileManifest() {
     manifest.push(`skills/${skill}`);
   }
 
+  // Agents are copied as-is for Codex skills that reference .codex/agents/
+  for (const agent of managed.agents) {
+    manifest.push(`agents/${agent}`);
+  }
+
   // Templates are copied as-is
   for (const template of managed.templates) {
     manifest.push(`templates/${template}`);
@@ -507,6 +649,12 @@ function getCodexFileManifest() {
     }
   }
 
+  if (managed.binHelpers) {
+    for (const binHelper of managed.binHelpers) {
+      manifest.push(`bin/${binHelper}`);
+    }
+  }
+
   // Instructions file
   manifest.push('instructions.md');
 
@@ -590,7 +738,7 @@ function selectiveUpdate(targetPath, sourcePath) {
     const src = path.join(templatesSrc, template);
     const dest = path.join(templatesDest, template);
     if (fs.existsSync(src)) {
-      // Ensure parent directory exists for nested paths (e.g., workflow/FEATURE-SPEC.md)
+      // Ensure parent directory exists for nested paths (e.g., workflow/PLAN.md)
       const destDir = path.dirname(dest);
       if (!fs.existsSync(destDir)) {
         fs.mkdirSync(destDir, { recursive: true });
@@ -616,6 +764,23 @@ function selectiveUpdate(targetPath, sourcePath) {
     }
     log.success('Updated references/ (workflow files only)');
   }
+
+  // Update helper binaries used by runtime commands
+  if (managed.binHelpers && managed.binHelpers.length > 0) {
+    const binSrc = getPackageBinPath();
+    const binDest = path.join(targetPath, 'bin');
+    if (!fs.existsSync(binDest)) {
+      fs.mkdirSync(binDest, { recursive: true });
+    }
+    for (const binHelper of managed.binHelpers) {
+      const src = path.join(binSrc, binHelper);
+      const dest = path.join(binDest, binHelper);
+      if (fs.existsSync(src)) {
+        fs.copyFileSync(src, dest);
+      }
+    }
+    log.success('Updated bin/ (workflow helper binaries)');
+  }
 }
 
 // Clean up files that were previously installed but are no longer managed
@@ -670,17 +835,20 @@ function cleanupOrphanedFiles(targetPath, dataDir) {
   }
 }
 
-// Ensure .5/.gitignore exists and contains .update-cache.json
+// Ensure .5/.gitignore exists and contains transient runtime files
 function ensureDotFiveGitignore(dataDir) {
   const gitignorePath = path.join(dataDir, '.gitignore');
-  const entry = '.update-cache.json';
+  const entries = ['.update-cache.json', '.migration-v*', '.reconfig-reminder'];
   if (fs.existsSync(gitignorePath)) {
-    const content = fs.readFileSync(gitignorePath, 'utf8');
-    if (!content.includes(entry)) {
-      fs.appendFileSync(gitignorePath, '\n' + entry + '\n');
+    let content = fs.readFileSync(gitignorePath, 'utf8');
+    for (const entry of entries) {
+      if (!content.includes(entry)) {
+        content += '\n' + entry;
+      }
     }
+    fs.writeFileSync(gitignorePath, content.trimEnd() + '\n');
   } else {
-    fs.writeFileSync(gitignorePath, entry + '\n');
+    fs.writeFileSync(gitignorePath, entries.join('\n') + '\n');
   }
 }
 
@@ -825,24 +993,25 @@ function mergeSettings(targetPath, sourcePath) {
 // Check if installation exists
 function checkExistingInstallation(targetPath) {
   if (activeRuntime === 'codex') {
-    // Codex: commands are installed as skills/5-plan-feature/SKILL.md
-    const markerFile = path.join(targetPath, 'skills', '5-plan-feature', 'SKILL.md');
-    return fs.existsSync(markerFile);
-  }
-  const markerFile = path.join(targetPath, 'commands', '5', 'plan-feature.md');
-  return fs.existsSync(markerFile);
+    // Codex: commands are installed as skills/5-plan/SKILL.md
+    const markerFile = path.join(targetPath, 'skills', '5-plan', 'SKILL.md');
+    const legacyMarkerFile = path.join(targetPath, 'skills', '5-plan-feature', 'SKILL.md');
+    return fs.existsSync(markerFile) || fs.existsSync(legacyMarkerFile);
+  }
+  const markerFile = path.join(targetPath, 'commands', '5', 'plan.md');
+  const legacyMarkerFile = path.join(targetPath, 'commands', '5', 'plan-feature.md');
+  return fs.existsSync(markerFile) || fs.existsSync(legacyMarkerFile);
 }
 
 // Helper to show commands
 function showCommandsHelp(isGlobal) {
   if (activeRuntime === 'codex') {
     log.info('Available skills (invoke with $ prefix in Codex):');
-    log.info('  $5-plan-feature              - Start feature planning (Phase 1)');
-    log.info('  $5-plan-implementation       - Create implementation plan (Phase 2)');
-    log.info('  $5-implement-feature         - Execute implementation (Phase 3)');
-    log.info('  $5-verify-implementation     - Verify implementation (Phase 4)');
-    log.info('  $5-review-code               - Code review (Phase 5)');
-    log.info('  $5-address-review-findings   - Apply review findings & PR comments');
+    log.info('  $5-plan                      - Create unified plan');
+    log.info('  $5-split                     - Split plan into smaller plans');
+    log.info('  $5-implement                 - Execute implementation + verification');
+    log.info('  $5-review                    - Code review');
+    log.info('  $5-address-review-findings   - Decide review findings & PR comments');
     log.info('  $5-configure                 - Interactive project setup');
     log.info('  $5-reconfigure               - Refresh docs/skills (no Q&A)');
     log.info('  $5-eject                     - Eject from update mechanism');
@@ -850,12 +1019,11 @@ function showCommandsHelp(isGlobal) {
     log.info('  $5-synchronize-agents        - Sync user content between runtimes');
   } else {
     log.info('Available commands:');
-    log.info('  /5:plan-feature              - Start feature planning (Phase 1)');
-    log.info('  /5:plan-implementation       - Create implementation plan (Phase 2)');
-    log.info('  /5:implement-feature         - Execute implementation (Phase 3)');
-    log.info('  /5:verify-implementation     - Verify implementation (Phase 4)');
-    log.info('  /5:review-code               - Code review (Phase 5)');
-    log.info('  /5:address-review-findings   - Apply review findings & PR comments');
+    log.info('  /5:plan                      - Create unified plan');
+    log.info('  /5:split                     - Split plan into smaller plans');
+    log.info('  /5:implement                 - Execute implementation + verification');
+    log.info('  /5:review                    - Code review');
+    log.info('  /5:address-review-findings   - Decide review findings & PR comments');
     log.info('  /5:configure                 - Interactive project setup');
     log.info('  /5:reconfigure               - Refresh docs/skills (no Q&A)');
     log.info('  /5:eject                     - Eject from update mechanism');
@@ -889,6 +1057,10 @@ function performFreshInstall(targetPath, sourcePath, isGlobal) {
   // Merge settings
   mergeSettings(targetPath, sourcePath);
 
+  // Install helper binaries used by runtime commands
+  copyWorkflowHelperBins(targetPath);
+  log.success('Installed bin/ (workflow helper binaries)');
+
   // Initialize version tracking
   initializeVersionJson(isGlobal);
 
@@ -908,6 +1080,52 @@ function performFreshInstall(targetPath, sourcePath, isGlobal) {
   showCommandsHelp(isGlobal);
 }
 
+// Rename create-* generated skill directories to {pattern} (drop the create- prefix).
+// Earlier versions named them create-dto, create-service, etc. The new convention
+// uses the bare pattern name so skills work for both create and update.
+function renameCreateSkills(targetPath) {
+  const skillsDir = path.join(targetPath, 'skills');
+  if (!fs.existsSync(skillsDir)) return;
+  try {
+    for (const entry of fs.readdirSync(skillsDir)) {
+      if (!entry.startsWith('create-')) continue;
+      const oldPath = path.join(skillsDir, entry);
+      const newName = entry.slice('create-'.length);
+      const newPath = path.join(skillsDir, newName);
+      if (fs.existsSync(newPath)) continue; // don't clobber a user-created skill
+      const skillFile = path.join(oldPath, 'SKILL.md');
+      if (!fs.existsSync(skillFile)) continue; // skip non-workflow dirs
+      fs.renameSync(oldPath, newPath);
+      // Update name: and description: in the frontmatter to match
+      const content = fs.readFileSync(path.join(newPath, 'SKILL.md'), 'utf8');
+      const updated = content
+        .replace(/^name: create-/m, 'name: ')
+        .replace(/^description: Creates a /m, 'description: Creates or updates a ');
+      fs.writeFileSync(path.join(newPath, 'SKILL.md'), updated);
+      log.info(`Renamed skill: ${entry} → ${newName}`);
+    }
+  } catch (e) {}
+}
+
+// Remove `context: fork` from any skill SKILL.md files under .claude/skills/.
+// These were generated by earlier versions of configure-skills and cause loops.
+function removeContextForkFromSkills(targetPath) {
+  const skillsDir = path.join(targetPath, 'skills');
+  if (!fs.existsSync(skillsDir)) return;
+  try {
+    for (const entry of fs.readdirSync(skillsDir)) {
+      const skillFile = path.join(skillsDir, entry, 'SKILL.md');
+      if (!fs.existsSync(skillFile)) continue;
+      const original = fs.readFileSync(skillFile, 'utf8');
+      const updated = original.replace(/^context: fork\s*\n/m, '');
+      if (updated !== original) {
+        fs.writeFileSync(skillFile, updated);
+        log.info(`Removed context: fork from skills/${entry}/SKILL.md`);
+      }
+    }
+  } catch (e) {}
+}
+
 // Perform update (preserves user-created files, updates .5/ data directory)
 function performUpdate(targetPath, sourcePath, isGlobal, versionInfo) {
   log.header(`Updating from ${versionInfo.installed || 'legacy'} to ${versionInfo.available}`);
@@ -923,6 +1141,22 @@ function performUpdate(targetPath, sourcePath, isGlobal, versionInfo) {
   // Merge settings (deep merge preserves user customizations)
   mergeSettings(targetPath, sourcePath);
 
+  // Rename create-* skill dirs to bare pattern names (create-dto → dto)
+  renameCreateSkills(targetPath);
+
+  // Strip `context: fork` from generated skills — caused infinite loops
+  removeContextForkFromSkills(targetPath);
+
+  // Flag v1 → v2 major upgrade so statusline can prompt for reconfigure
+  const prevMajor = versionInfo.installed ? parseInt(versionInfo.installed.split('.')[0], 10) : 0;
+  const newMajor = versionInfo.available ? parseInt(versionInfo.available.split('.')[0], 10) : 0;
+  if (!isNaN(prevMajor) && !isNaN(newMajor) && prevMajor < newMajor) {
+    try {
+      if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true });
+      fs.writeFileSync(path.join(dataDir, '.migration-v' + newMajor), '1');
+    } catch (e) {}
+  }
+
   // Update version.json (per-runtime, preserving other runtime's state)
   writeVersionJson(dataDir, isGlobal, versionInfo.available);
   ensureDotFiveGitignore(dataDir);
@@ -944,40 +1178,41 @@ function performUpdate(targetPath, sourcePath, isGlobal, versionInfo) {
 
 // Generate instructions.md for Codex (replaces hooks + settings.json)
 function generateCodexInstructions(targetPath) {
-  const content = `# 5-Phase Workflow — Codex Instructions
+  const content = `# dev-workflow — Codex Instructions
 
-This file is managed by the 5-Phase Workflow installer. It provides Codex with
+This file is managed by the dev-workflow installer. It provides Codex with
 the context it needs to run the workflow skills correctly.
 
 ## Workflow Overview
 
-The 5-Phase Workflow provides structured feature development:
+The workflow provides structured feature development:
 
-1. **Plan Feature** (\`$5-plan-feature\`) — Requirements gathering & feature spec
-2. **Plan Implementation** (\`$5-plan-implementation\`) — Technical planning
-3. **Implement Feature** (\`$5-implement-feature\`) — Orchestrated implementation
-4. **Verify Implementation** (\`$5-verify-implementation\`) — Build & test verification
-5. **Review Code** (\`$5-review-code\`) — Code review
+1. **Plan** (\`$5-plan\`) — Requirements, discovery, and unified plan
+2. **Implement** (\`$5-implement\`) — Orchestrated implementation with inline verification
+3. **Review** (\`$5-review\`) — Code review
 
 ## Data Directory
 
 All workflow state lives in \`.5/\` at the project root:
 - \`.5/config.json\` — Project configuration
-- \`.5/features/{name}/feature.md\` — Feature specifications
-- \`.5/features/{name}/plan.md\` — Implementation plans
+- \`.5/features/{name}/plan.md\` — Unified plan
 - \`.5/features/{name}/state.json\` — Implementation state
 
 ## Guard Rules
 
-During planning phases (plan-feature, plan-implementation):
+During the planning phase ($5-plan):
 - Do NOT write files outside \`.5/\`
-- Do NOT write source code — only specifications and plans
+- Do NOT write source code — only the unified plan and scan cache
 - The \`.5/.planning-active\` marker indicates planning is in progress
 
 ## Configuration
 
 Run \`$5-configure\` after installation to set up your project.
 
+## Codex Token Budget
+
+Workflow skills use \`gpt-5.4-mini\` with low reasoning for exploration, orchestration, and simple executors by default. They escalate to \`gpt-5.4\` with medium reasoning only for complex logic, security-sensitive work, data migrations, public API changes, final verification that needs logic review, or retries after a cheaper attempt fails.
+
 ## Templates & References
 
 Templates are in \`.codex/templates/\` and references in \`.codex/references/\`.
@@ -1038,6 +1273,28 @@ function installCodexSkills(targetPath, sourcePath) {
   log.success('Installed utility skills');
 }
 
+// Install workflow agents for Codex skills that reference .codex/agents/
+function installCodexAgents(targetPath, sourcePath) {
+  const managed = getWorkflowManagedFiles();
+  const agentsSrc = path.join(sourcePath, 'agents');
+  const agentsDest = path.join(targetPath, 'agents');
+
+  if (!fs.existsSync(agentsSrc) || managed.agents.length === 0) return;
+
+  if (!fs.existsSync(agentsDest)) {
+    fs.mkdirSync(agentsDest, { recursive: true });
+  }
+
+  for (const agent of managed.agents) {
+    const src = path.join(agentsSrc, agent);
+    const dest = path.join(agentsDest, agent);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, dest);
+    }
+  }
+  log.success('Installed agents/');
+}
+
 // Codex fresh installation
 function performCodexFreshInstall(targetPath, sourcePath, isGlobal) {
   if (!fs.existsSync(targetPath)) {
@@ -1047,6 +1304,7 @@ function performCodexFreshInstall(targetPath, sourcePath, isGlobal) {
 
   // Install commands as Codex skills
   installCodexSkills(targetPath, sourcePath);
+  installCodexAgents(targetPath, sourcePath);
 
   // Copy templates and references as-is (just path conversion)
   for (const dir of ['templates', 'references']) {
@@ -1058,6 +1316,10 @@ function performCodexFreshInstall(targetPath, sourcePath, isGlobal) {
     }
   }
 
+  // Install helper binaries used by runtime commands
+  copyWorkflowHelperBins(targetPath);
+  log.success('Installed bin/ (workflow helper binaries)');
+
   // Generate instructions.md (replaces hooks + settings.json)
   generateCodexInstructions(targetPath);
 
@@ -1103,6 +1365,7 @@ function codexSelectiveUpdate(targetPath, sourcePath) {
 
   // Re-install all skills
   installCodexSkills(targetPath, sourcePath);
+  installCodexAgents(targetPath, sourcePath);
 
   // Update templates and references
   for (const dir of ['templates', 'references']) {
@@ -1115,6 +1378,10 @@ function codexSelectiveUpdate(targetPath, sourcePath) {
   }
   log.success('Updated templates and references');
 
+  // Update helper binaries used by runtime commands
+  copyWorkflowHelperBins(targetPath);
+  log.success('Updated bin/ helper binaries');
+
   // Regenerate instructions.md
   generateCodexInstructions(targetPath);
 }
@@ -1130,6 +1397,19 @@ function performCodexUpdate(targetPath, sourcePath, isGlobal, versionInfo) {
   const dataDir = getDataPath(isGlobal);
   cleanupOrphanedFiles(targetPath, dataDir);
 
+  // Rename create-* skill dirs to bare pattern names (create-dto → dto)
+  renameCreateSkills(targetPath);
+
+  // Flag v1 → v2 major upgrade so skills can prompt for reconfigure
+  const prevMajor = versionInfo.installed ? parseInt(versionInfo.installed.split('.')[0], 10) : 0;
+  const newMajor = versionInfo.available ? parseInt(versionInfo.available.split('.')[0], 10) : 0;
+  if (!isNaN(prevMajor) && !isNaN(newMajor) && prevMajor < newMajor) {
+    try {
+      if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true });
+      fs.writeFileSync(path.join(dataDir, '.migration-v' + newMajor), '1');
+    } catch (e) {}
+  }
+
   // Update version.json (per-runtime, preserving other runtime's state)
   writeVersionJson(dataDir, isGlobal, versionInfo.available);
   ensureDotFiveGitignore(dataDir);
@@ -1148,7 +1428,7 @@ function performCodexUpdate(targetPath, sourcePath, isGlobal, versionInfo) {
 function codexUninstall() {
   const targetPath = getTargetPath(false);
 
-  log.header('5-Phase Workflow Uninstallation (Codex)');
+  log.header('dev-workflow Uninstallation (Codex)');
   log.info(`Target: ${targetPath}`);
 
   if (!checkExistingInstallation(targetPath)) {
@@ -1176,6 +1456,13 @@ function codexUninstall() {
   }
   log.success('Removed utility skills (preserved user-created skills)');
 
+  // Remove agents
+  for (const agent of managed.agents) {
+    const agentPath = path.join(targetPath, 'agents', agent);
+    if (fs.existsSync(agentPath)) fs.unlinkSync(agentPath);
+  }
+  log.success('Removed workflow agents');
+
   // Remove templates
   for (const template of managed.templates) {
     const templatePath = path.join(targetPath, 'templates', template);
@@ -1192,6 +1479,19 @@ function codexUninstall() {
     log.success('Removed workflow references');
   }
 
+  // Remove helper binaries
+  if (managed.binHelpers) {
+    for (const binHelper of managed.binHelpers) {
+      const binPath = path.join(targetPath, 'bin', binHelper);
+      if (fs.existsSync(binPath)) fs.unlinkSync(binPath);
+    }
+    const binDir = path.join(targetPath, 'bin');
+    if (fs.existsSync(binDir) && fs.readdirSync(binDir).length === 0) {
+      fs.rmdirSync(binDir);
+    }
+    log.success('Removed workflow helper binaries');
+  }
+
   // Remove instructions.md
   const instructionsPath = path.join(targetPath, 'instructions.md');
   if (fs.existsSync(instructionsPath)) {
@@ -1217,7 +1517,7 @@ function install(isGlobal, forceUpgrade = false) {
   const sourcePath = getSourcePath();
 
   const runtimeLabel = activeRuntime === 'codex' ? 'Codex' : 'Claude Code';
-  log.header(`5-Phase Workflow Installation (${runtimeLabel})`);
+  log.header(`dev-workflow Installation (${runtimeLabel})`);
   log.info(`Target: ${targetPath}`);
   log.info(`Source: ${sourcePath}`);
 
@@ -1311,7 +1611,7 @@ function uninstall() {
 
   const targetPath = getTargetPath(false); // Always local for uninstall
 
-  log.header('5-Phase Workflow Uninstallation');
+  log.header('dev-workflow Uninstallation');
   log.info(`Target: ${targetPath}`);
 
   if (!checkExistingInstallation(targetPath)) {
@@ -1389,6 +1689,21 @@ function uninstall() {
     log.success('Removed workflow references (preserved user-created references)');
   }
 
+  // Remove only workflow-managed helper binaries
+  if (managed.binHelpers) {
+    for (const binHelper of managed.binHelpers) {
+      const binPath = path.join(targetPath, 'bin', binHelper);
+      if (fs.existsSync(binPath)) {
+        fs.unlinkSync(binPath);
+      }
+    }
+    const binDir = path.join(targetPath, 'bin');
+    if (fs.existsSync(binDir) && fs.readdirSync(binDir).length === 0) {
+      fs.rmdirSync(binDir);
+    }
+    log.success('Removed workflow helper binaries (preserved user-created binaries)');
+  }
+
   // Remove data directory (.5/)
   const dataDir = getDataPath(false);
   if (fs.existsSync(dataDir)) {
@@ -1457,7 +1772,7 @@ function main() {
     }
 
     if (anyUpdateAvailable) {
-      log.info('Run: npx 5-phase-workflow --upgrade');
+      log.info('Run: npx foifi --upgrade');
     }
 
     activeRuntime = primaryRuntime;