5-phase-workflow 2.0.0 → 2.0.1

package/README.md

@@ -1,6 +1,29 @@
 # foifi
 
-A structured AI-assisted development workflow for Claude Code and Codex.
+**foifi** is an opinionated AI development workflow layer that sits on top of Claude Code and Codex. It handles project setup, structured feature implementation, and code review — so you spend less time managing the AI and more time shipping.
+
+### What it does
+
+**Project setup** — The `/5:configure` command detects your stack, generates a `CLAUDE.md` / `AGENTS.md` tailored to your project, writes a `.5/index/` knowledge base, and installs project-specific skills and rules. This gives every AI session the right context from the start rather than letting the model guess.
+
+**Status line** — foifi installs an informative Claude Code status line that surfaces the active feature, current workflow phase, and relevant state directly in the terminal footer. No more digging through files to remember where you left off.
+
+**Structured implementation workflow** — Instead of asking Claude or Codex to "just implement this," foifi enforces a three-phase loop:
+1. **Plan** (`/5:plan`) — writes a single human-reviewed `plan.md` with scope, acceptance criteria, component checklist, and decisions.
+2. **Implement** (`/5:implement`) — an orchestrator agent turns the plan into a typed execution graph (`state.json`), then delegates each component to a focused executor agent. A verification agent checks completeness, correctness, and test coverage at the end of every run.
+3. **Review** (`/5:review`) — triages changed files, produces structured findings, and feeds them into `/5:address-review-findings` for interactive fix decisions and PR replies.
+
+This separation keeps planning readable, implementation mechanical, and review structured.
+
+**Code review and findings** — `/5:review` triages changed files and produces structured `review-findings-*.md`. `/5:address-review-findings` presents each finding interactively, records `fix`/`wont_fix`/`wait` decisions, applies approved local fixes, handles PR comment replies, and keeps a decision log — all without losing context between sessions.
+
+**Plan management helpers** — `/5:discuss-feature` refines an existing plan in conversation. `/5:split` breaks a large plan into smaller linked child plans. `/5:unlock` clears a stale planning lock. `/5:reconfigure` refreshes docs and skills when the project evolves.
+
+**Codex support** — Every command has a `$5-*` Codex equivalent. Codex runs are token-budgeted: simple steps use a lighter model and low reasoning, complex or security-sensitive steps escalate automatically.
+
+### The name
+
+"foifi" is Swiss German for *five*. The name comes from the project's original 5-phase workflow. That workflow has since been streamlined into the current 3-phase plan → implement → review loop, but the name stuck — and all commands still carry the `/5:` prefix.
 
 ## Install
 

package/bin/install.js

@@ -569,6 +569,13 @@ During the planning phase ($5-plan):
 - Do NOT write to any file outside \`.5/\`
 - 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>`;
 }
 
@@ -828,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');
   }
 }
 
@@ -1070,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}`);
@@ -1085,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);
@@ -1325,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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "5-phase-workflow",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "A dev-workflow for Claude Code and Codex",
   "bin": {
     "foifi": "bin/install.js"

package/src/commands/5/reconfigure.md

@@ -177,9 +177,9 @@ After the skill completes, update `.5/version.json`:
 
 ### Step 8: Clean Up
 
-Remove the `.5/.reconfig-reminder` flag file if it exists:
+Remove the `.5/.reconfig-reminder` and `.5/.migration-v2` flag files if they exist:
 ```bash
-rm -f .5/.reconfig-reminder
+rm -f .5/.reconfig-reminder .5/.migration-v2
 ```
 
 ### Step 9: Report

package/src/hooks/statusline.js

@@ -113,6 +113,11 @@ process.stdin.on('end', () => {
       if (fs.existsSync(flagFile)) {
         parts.push(`\x1b[35m↻ /5:reconfigure\x1b[0m`);
       }
+
+      const migrationFlag = path.join(dir, '.5', '.migration-v2');
+      if (fs.existsSync(migrationFlag)) {
+        parts.push(`\x1b[31m⚠ v1→v2: /5:reconfigure\x1b[0m`);
+      }
     } catch (e) {}
 
     process.stdout.write(parts.join(' | '));

package/src/skills/configure-docs-index/SKILL.md

@@ -3,7 +3,6 @@ name: configure-docs-index
 description: Analyzes the codebase, creates project documentation, generates a rebuildable codebase index, and updates AGENTS.md. Used during /5:implement CONFIGURE.
 allowed-tools: Read, Write, Bash, Glob, Grep
 model: sonnet
-context: fork
 user-invocable: false
 ---
 

package/src/skills/configure-skills/SKILL.md

@@ -3,7 +3,6 @@ name: configure-skills
 description: Generates project-specific create-*/run-* skills and scoped rules from the current codebase. Used during /5:implement CONFIGURE.
 allowed-tools: Read, Write, Bash, Glob, Grep, create-skill, scaffold-skill
 model: sonnet
-context: fork
 user-invocable: false
 ---
 
@@ -77,24 +76,23 @@ For EACH pattern selected by the user in the unified plan:
 
 ### A2. Skill Template Structure
 
-For each skill, create `.claude/skills/create-{pattern}/SKILL.md`:
+For each skill, create `.claude/skills/{pattern}/SKILL.md`:
 
 ```yaml
 ---
-name: create-{pattern}
-description: Creates a {Pattern} following project conventions at {location}.
+name: {pattern}
+description: Creates or updates a {Pattern} following project conventions at {location}.
 allowed-tools: Read, Write, Glob, Grep
 model: haiku
-context: fork
 user-invocable: true
 ---
 ```
 
 ```markdown
-# Create {Pattern}
+# {Pattern}
 
-## What This Skill Creates
-A {pattern} following this project's conventions.
+## What This Skill Does
+Creates or updates a {pattern} following this project's conventions.
 
 ## Detected Conventions
 - **Location:** {detected-location}
@@ -103,14 +101,14 @@ A {pattern} following this project's conventions.
 - **Imports:** {detected-import-pattern}
 
 ## Template
-Based on {example-file}, new {patterns} should follow:
+Based on {example-file}, {patterns} should follow:
 
 \`\`\`{language}
 {template-derived-from-analysis}
 \`\`\`
 
 ## Checklist
-- [ ] File created at correct location
+- [ ] File at correct location
 - [ ] Naming convention followed
 - [ ] Required imports added
 - [ ] {pattern-specific-items}
@@ -118,7 +116,7 @@ Based on {example-file}, new {patterns} should follow:
 
 ### A3. Pattern to Skill Name Mapping
 
-**Rule:** Skill name is `create-{pattern}` (e.g., `controller` → `create-controller`, `component` → `create-component`, `dto` → `create-dto`). For compound patterns, use the short form: `model/entity` → `create-model`, `api-route` → `create-api-route`.
+**Rule:** Skill name is `{pattern}` (e.g., `controller` → `controller`, `component` → `component`, `dto` → `dto`). For compound patterns, use the short form: `model/entity` → `model`, `api-route` → `api-route`.
 
 ---
 
@@ -153,7 +151,6 @@ name: run-{command}
 description: Runs {command} for this project using {source}.
 allowed-tools: Bash
 model: haiku
-context: fork
 user-invocable: true
 ---
 ```