5-phase-workflow 2.0.0 → 2.0.2

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

@@ -393,7 +393,8 @@ function getWorkflowManagedFiles() {
     skills: [
       'configure-docs-index',
       'configure-skills',
-      'generate-readme'
+      'generate-readme',
+      'use-index'
     ],
 
     // Hooks: specific hook files
@@ -569,6 +570,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 +836,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 +1081,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 +1142,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 +1398,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.2",
   "description": "A dev-workflow for Claude Code and Codex",
   "bin": {
     "foifi": "bin/install.js"

package/src/commands/5/analyze-feature.md

@@ -30,7 +30,7 @@ Do NOT proceed until you have a clear understanding of what to analyze.
 
 1. Derive a short kebab-case name from the analysis subject (e.g., `user-auth`, `order-processing`, `payment-integration`). This becomes the filename: `{name}-analysis.md`.
 
-2. Identify the relevant modules and layers to analyze. If `.5/index/` exists, read the index files for a quick structural overview. Otherwise, use Glob to understand the project layout.
+2. Identify the relevant modules and layers to analyze. Invoke the `use-index` skill for a quick structural overview. The skill will rebuild the index if stale; fall back to Glob only if the index is missing.
 
 3. Use Glob and Grep to locate the relevant source files. Search for key classes, interfaces, functions, and types related to the analysis subject.
 

package/src/commands/5/discuss-feature.md

@@ -111,7 +111,7 @@ Use `multiSelect: false` to get single focus area initially.
 
 Based on the user's focus area, explore the codebase if needed:
 
-**Index shortcut:** Before spawning Explore agents or running Glob/Grep, check if `.5/index/` exists. If it does, read `.5/index/README.md` first for the generation timestamp — if fresh (under 1 day old), read the relevant index files (e.g., modules.md for scope changes, routes.md for API discussions, models.md for data model questions) to quickly gather context and skip broad scanning. If outdated, inform the user they can run `.5/index/rebuild-index.sh` to refresh it. If `.5/index/` does not exist, inform the user they can run `/5:reconfigure` to generate it. In both missing/outdated cases, fall back to Glob/Grep or Explore agents for exploration.
+**Index shortcut:** Before spawning Explore agents or running Glob/Grep, invoke the `use-index` skill to quickly orient in the codebase using the generated index.
 
 **For technical constraint discussions:**
 - Search for similar implementations

package/src/commands/5/plan.md

@@ -79,6 +79,8 @@ Do not ask technical follow-ups yet.
 
 ## Step 3: Explore Codebase
 
+If `.5/index/` exists, check the `Generated:` timestamp in `.5/index/README.md`. If the index is more than one day old, run `.5/index/rebuild-index.sh` to refresh it before spawning the Explore agent.
+
 Spawn one Explore agent. In Codex, use `agent_type: explorer`, `model: gpt-5.4-mini`, and `reasoning_effort: low`.
 
 ```text
@@ -88,7 +90,7 @@ Feature description:
 {feature description}
 
 Tasks:
-1. If `.5/index/` exists, read `.5/index/README.md` first. Use only relevant fresh index files; do not rescan broad project structure. If stale, note it and fall back to targeted Grep/Glob.
+1. If `.5/index/` exists, read `.claude/skills/use-index/SKILL.md` and follow its guidance to select and read relevant index files. Skip broad project scanning. If the index is missing, fall back to targeted Grep/Glob and note it in the report.
 2. Identify relevant modules, existing patterns, and likely target files.
 3. Find at most 3 similar implementations and reusable helpers.
 4. Identify test framework, test file conventions, and the narrowest relevant build/test commands.

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
 ---
 ```

package/src/skills/use-index/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: use-index
+description: Navigate the .5/index/ codebase index to quickly identify target files and understand project structure. Use before running broad Glob/Grep scans when you need to find where a feature lives, where new code should go, which routes exist, or what the data model looks like.
+allowed-tools: Read, Bash
+user-invocable: false
+---
+
+# Use Index
+
+Use `.5/index/` to orient in the codebase quickly before resorting to broad file scans.
+
+## Step 1: Check existence
+
+```bash
+ls .5/index/ 2>/dev/null
+```
+
+If the directory is missing or empty, inform the user they can run `/5:reconfigure` to generate it, then fall back to Glob/Grep.
+
+## Step 2: Read the manifest
+
+Read `.5/index/README.md`. It lists every generated index file, its purpose, and the generation timestamp.
+
+## Step 3: Check freshness
+
+Look for the `Generated:` timestamp in README.md.
+
+- **Fresh (≤ 1 day):** proceed with the index.
+- **Stale (> 1 day):** run `.5/index/rebuild-index.sh` to rebuild it, then proceed with the refreshed index.
+
+## Step 4: Read only the relevant file(s)
+
+Pick the file that matches the task. Skip unrelated ones.
+
+| Task | File |
+|------|------|
+| Where does new code go / what modules exist? | `modules.md` |
+| API surface, HTTP routes, or handlers | `routes.md` |
+| Data models, schemas, or migrations | `models.md` |
+| Shared helpers, utilities, or exported functions | `libraries.md` |
+| Build, run, test, or dev-workflow commands | `commands.md` |
+
+## Step 5: Interpret entries
+
+Each file has compact entries — path plus a short descriptor (HTTP method, exported name, key field, etc.). Use them to identify target files directly. Do not read the full index file if a handful of entries answer the question.
+
+## Step 6: Fall back gracefully
+
+If a file is too sparse or an area is missing from the index, note the gap and fall back to a targeted Grep/Glob for that area only. Do not re-scan sections already covered by a fresh index entry.

package/src/templates/AGENTS.md

@@ -87,8 +87,6 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
 
 {CODEBASE_INDEX_LINKS}
 
-## Index Freshness
-
-If the codebase index files are more than one day old, regenerate them by running `.5/index/rebuild-index.sh` before relying on them.
+Use the `use-index` skill before running broad Glob/Grep scans. It handles freshness checks, file selection by task type, and fallback strategies. If index files are more than one day old, regenerate them by running `.5/index/rebuild-index.sh` before relying on them.
 
 {CUSTOM_DOCUMENTATION}