5-phase-workflow 3.1.0 → 3.1.2

package/README.md

@@ -25,7 +25,6 @@ Then configure the project once:
 
 ```bash
 /5:configure
-/5:implement CONFIGURE
 ```
 
 This adds the foifi rules to `AGENTS.md` as one marked block, links your existing standards from it, and makes `CLAUDE.md` include it. Nothing else in your files or settings changes.

package/bin/install.js

@@ -1254,8 +1254,9 @@ function removePlanningActiveMarker(dataDir) {
 // is shared, so performUpdate() and performCodexUpdate() both run this.
 function movePlansToPlanningDir(dataDir) {
   const featuresDir = path.join(dataDir, 'features');
-  if (!fs.existsSync(featuresDir)) return;
+  if (!fs.existsSync(featuresDir)) return 0;
   const planningDir = path.join(dataDir, 'planning');
+  let moved = 0;
   try {
     for (const feature of fs.readdirSync(featuresDir)) {
       const planFile = path.join(featuresDir, feature, 'plan.md');
@@ -1263,9 +1264,53 @@ function movePlansToPlanningDir(dataDir) {
       if (!fs.existsSync(planFile) || fs.existsSync(target)) continue;
       fs.mkdirSync(planningDir, { recursive: true });
       fs.renameSync(planFile, target);
+      moved++;
       log.info(`Moved plan: features/${feature}/plan.md → planning/${feature}.md`);
     }
   } catch (e) {}
+  return moved;
+}
+
+// Before .5/planning/ existed, plans lived in .5/features/, so a project that git-ignored
+// .5/features/ also ignored its plans. Carry that choice over to .5/planning/, but only for
+// projects that come from that layout: plans moved by this upgrade, or an install that was
+// upgraded into 3.1.0 (whose migration moved them without this). A project configured on 3.1
+// may have chosen "Only .5/features/" on purpose; /5:configure now marks that with
+// `!.5/planning/`, and any .5/planning rule or plan tracked in git (checked before the move) is left alone.
+// Shared .5/ data, so both update paths run this.
+// True when git tracks any plan, in the old or the new location. Call it before plans move:
+// afterwards the index still lists them only under .5/features/.
+function hasTrackedPlans(dataDir) {
+  try {
+    return require('child_process')
+      .execFileSync('git', ['ls-files', '--', '.5/features/*/plan.md', '.5/planning'],
+        { cwd: path.dirname(dataDir), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+      .trim() !== '';
+  } catch (e) {
+    return false; // not a git checkout: nothing is tracked
+  }
+}
+
+function ignorePlanningLikeFeatures(dataDir, movedPlans, previousVersion, plansTracked) {
+  const projectRoot = path.dirname(dataDir);
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+  if (!fs.existsSync(gitignorePath)) return;
+  try {
+    if (!movedPlans) {
+      if (previousVersion !== '3.1.0') return;
+      // A fresh 3.1.0 install has installedAt === lastUpdated; an upgraded one does not
+      const versionData = JSON.parse(fs.readFileSync(path.join(dataDir, 'version.json'), 'utf8'));
+      if (!versionData.installedAt || versionData.installedAt === versionData.lastUpdated) return;
+    }
+    if (plansTracked) return;
+    const content = fs.readFileSync(gitignorePath, 'utf8');
+    const rules = content.split('\n').map(l => l.trim()).filter(l => l && !l.startsWith('#'));
+    const ignoresFeatures = rules.some(l => /^\/?\.5\/features\/?(\*\*?)?$/.test(l));
+    const hasPlanningRule = rules.some(l => /^!?\/?\.5\/planning\/?(\*\*?)?$/.test(l));
+    if (!ignoresFeatures || hasPlanningRule) return;
+    fs.writeFileSync(gitignorePath, content.trimEnd() + '\n.5/planning/\n');
+    log.info('Added .5/planning/ to .gitignore (plans were ignored under .5/features/)');
+  } catch (e) {}
 }
 
 // Perform update (preserves user-created files, updates .5/ data directory)
@@ -1294,7 +1339,8 @@ function performUpdate(targetPath, sourcePath, isGlobal, versionInfo) {
   removePlanningActiveMarker(dataDir);
 
   // Plans moved from .5/features/{name}/plan.md to .5/planning/{name}.md
-  movePlansToPlanningDir(dataDir);
+  const plansTracked = hasTrackedPlans(dataDir);
+  ignorePlanningLikeFeatures(dataDir, movePlansToPlanningDir(dataDir), versionInfo.installed, plansTracked);
 
   // Flag v1 → v2 major upgrade so statusline can prompt for reconfigure
   const prevMajor = versionInfo.installed ? parseInt(versionInfo.installed.split('.')[0], 10) : 0;
@@ -1490,7 +1536,8 @@ function performCodexUpdate(targetPath, sourcePath, isGlobal, versionInfo) {
   removePlanningActiveMarker(dataDir);
 
   // Plans moved from .5/features/{name}/plan.md to .5/planning/{name}.md
-  movePlansToPlanningDir(dataDir);
+  const plansTracked = hasTrackedPlans(dataDir);
+  ignorePlanningLikeFeatures(dataDir, movePlansToPlanningDir(dataDir), versionInfo.installed, plansTracked);
 
   // Flag v1 → v2 major upgrade so skills can prompt for reconfigure
   const prevMajor = versionInfo.installed ? parseInt(versionInfo.installed.split('.')[0], 10) : 0;

package/docs/workflow-guide.md

@@ -90,10 +90,9 @@ First-time setup:
 
 ```text
 /5:configure
-/5:implement CONFIGURE
 ```
 
-`/5:configure` writes `.5/config.json`, sets `plansDirectory` to `.5/planning` in `.claude/settings.json`, and writes the CONFIGURE plan. `/5:implement CONFIGURE` adds the workflow rules to AGENTS.md as one marked block that links the repository's own standards, appends `@AGENTS.md` to CLAUDE.md when it lacks that line, and generates scoped rules. Nothing outside the block changes.
+`/5:configure` writes `.5/config.json`, sets `plansDirectory` to `.5/planning` in `.claude/settings.json`, writes the CONFIGURE plan, and then runs `/5:implement CONFIGURE` itself, which adds the workflow rules to AGENTS.md as one marked block that links the repository's own standards, appends `@AGENTS.md` to CLAUDE.md when it lacks that line, and generates scoped rules. Nothing outside the block changes.
 
 Refresh the AGENTS.md block and the rules later with:
 
@@ -135,5 +134,5 @@ v2.0.0 removes old commands during upgrade:
 | `/5:review` | Review changes for correctness and standards |
 | `/5:address-review-findings` | Fix clear findings, ask about real decisions |
 | `/5:analyze-feature` | Document a feature with mermaid diagrams |
-| `/5:configure` | Create project config and CONFIGURE plan |
+| `/5:configure` | Create project config and CONFIGURE plan, then implement it |
 | `/5:reconfigure` | Refresh the AGENTS.md block and rules |

package/package.json

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

package/src/commands/5/configure.md

@@ -1,15 +1,15 @@
 ---
 name: 5:configure
-description: Configures the project. Analyzes project, gathers preferences, writes config.json, points Claude Code plan mode at .5/planning/, and creates .5/planning/CONFIGURE.md. Follow up with /5:implement CONFIGURE.
-allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
+description: Configures the project. Analyzes project, gathers preferences, writes config.json, points Claude Code plan mode at .5/planning/, creates .5/planning/CONFIGURE.md, then runs /5:implement CONFIGURE itself.
+allowed-tools: Agent, Read, Write, Edit, Glob, Grep, Bash, Workflow, Skill, AskUserQuestion
 user-invocable: true
 ---
 
 <role>
 You are a Project Configurator. You analyze a project, gather preferences, and write config.json plus a unified plan.
-You do NOT write AGENTS.md, CLAUDE.md, or rules directly — those are /5:implement's job.
+You do NOT write AGENTS.md, CLAUDE.md, or rules directly — those are /5:implement's job, and you start it yourself once the plan is written.
 You write ONLY to: .5/config.json, .5/version.json, .5/planning/CONFIGURE.md, .gitignore, and the `plansDirectory` key of .claude/settings.json (Claude Code only).
-After writing config.json and the unified plan, you are DONE. Exit immediately.
+After writing config.json and the unified plan, you hand off to `/5:implement CONFIGURE`.
 </role>
 
 # Configure (Project Setup Plan)
@@ -18,16 +18,11 @@ Current commit: !`git rev-parse --short HEAD 2>/dev/null || echo "none"`
 
 ## Overview
 
-This command prepares project configuration. It analyzes the project, asks preference questions, writes `.5/config.json`, points Claude Code plan mode at `.5/planning/`, and writes a plan at `.5/planning/CONFIGURE.md`.
-
-After running this command, proceed through the standard phases:
-1. **`/5:configure`** (this command) - Create config and CONFIGURE plan
-2. `/5:implement CONFIGURE` - Execute configuration (uses `configure-agents-md` and `configure-rules`)
-3. `/5:review` - Review generated files if desired
+This command prepares project configuration. It analyzes the project, asks preference questions, writes `.5/config.json`, points Claude Code plan mode at `.5/planning/`, writes a plan at `.5/planning/CONFIGURE.md`, and then runs `/5:implement CONFIGURE` itself, which executes the plan with `configure-agents-md` and `configure-rules` and reviews the result. The user runs only this one command.
 
 ## ⚠️ CRITICAL SCOPE CONSTRAINT
 
-**THIS COMMAND WRITES config.json AND CREATES THE CONFIGURE PLAN. NOTHING ELSE.**
+**THIS COMMAND WRITES config.json AND CREATES THE CONFIGURE PLAN, THEN HANDS OFF TO `/5:implement CONFIGURE`. NOTHING ELSE.**
 
 Your job in this command:
 ✅ Analyze project (detect type, build commands, etc.)
@@ -35,7 +30,7 @@ Your job in this command:
 ✅ Write `.5/config.json` directly
 ✅ Set `plansDirectory` in `.claude/settings.json` (Claude Code only)
 ✅ Create the plan at `.5/planning/CONFIGURE.md` for remaining work
-✅ Tell user to run /5:implement CONFIGURE
+✅ Run `/5:implement CONFIGURE` right after the plan is written
 
 Your job is NOT:
 ❌ Write AGENTS.md or CLAUDE.md directly (/5:implement does this)
@@ -43,9 +38,9 @@ Your job is NOT:
 ❌ Skip user interaction
 ❌ Assume project structure
 
-**After writing config.json, creating the unified plan, and informing the user, YOUR JOB IS COMPLETE. EXIT IMMEDIATELY.**
+**After writing config.json and the unified plan, run `/5:implement CONFIGURE`. The rest is its job.**
 
-**If you find yourself writing AGENTS.md, CLAUDE.md, or rules, STOP IMMEDIATELY. You should only be writing config.json, the settings key, and the plan.**
+**If you find yourself writing AGENTS.md, CLAUDE.md, or rules before `/5:implement CONFIGURE` runs, STOP IMMEDIATELY. You should only be writing config.json, the settings key, and the plan.**
 
 ## Configuration Process
 
@@ -173,6 +168,7 @@ Context7 provides up-to-date, version-specific documentation and code examples d
 - "Generate `.claude/rules/` files? These are scoped instruction files that automatically load when the agent works with matching file types (e.g., testing rules load only when editing test files, code-style rules load only for source files)."
   - Options: "Yes (recommended)", "Skip"
 - Note: Rules complement AGENTS.md — they provide focused, file-type-scoped directives derived from your project's actual conventions.
+- On Codex, the rules live in the foifi block of `AGENTS.md`. When the user skipped AGENTS.md in step 2j, do not ask: set `rules.generate` to `false`.
 
 **2l. Git-ignore workflow folders:**
 - "`.5/planning/` will hold your plans. `.5/features/` will hold implementation state and review findings. Which should git ignore?"
@@ -216,7 +212,8 @@ Native plan mode must save its plans in `.5/planning/`, where `/5:implement` fin
 For each folder the user chose to ignore in step 2l (`.5/planning/`, `.5/features/`):
 1. Check if `.gitignore` exists in the project root — create it if not
 2. Check if the folder is already listed — if not, append it on a new line
-3. Inform the user which folders were added to `.gitignore`
+3. When the user chose "Only `.5/features/`", also append `!.5/planning/`, so upgrades know the plans are shared on purpose and do not ignore them
+4. Inform the user which folders were added to `.gitignore`
 
 **Always gitignore `.5/.reconfig-reminder`:**
 
@@ -226,7 +223,9 @@ Ensure `.5/.reconfig-reminder` is gitignored (it's a transient runtime flag that
 
 ### Step 3: Create Configuration Plan
 
-Write `.5/planning/CONFIGURE.md` containing all gathered data:
+If the user skipped both AGENTS.md (step 2j) and rules (step 2j2), there is nothing to implement: delete `.5/planning/CONFIGURE.md` if an earlier run left it, so no later `/5:implement` applies what the user just declined. Then skip Steps 3 and 4, tell the user "Configuration saved to `.5/config.json`", and stop.
+
+Otherwise write `.5/planning/CONFIGURE.md` containing all gathered data. When the user skipped AGENTS.md in step 2j, leave out everything about AGENTS.md and CLAUDE.md: the `configure agents md` component, Requirement 1, its acceptance criteria and Module Impact row, and the "After configure agents md" ordering. The plan then generates only the rules, and nothing touches `AGENTS.md` or `CLAUDE.md`. The template below shows the plan with both selected:
 
 ```markdown
 ---
@@ -323,21 +322,16 @@ Only generate rules for patterns that were actually detected:
 
 ## Next Steps
 
-1. Run `/5:implement CONFIGURE`.
+1. `/5:configure` runs `/5:implement CONFIGURE` right away; rerun it by hand only if that run was interrupted.
 ```
 
 **Important:** Use `mkdir -p .5/planning` before writing the plan.
 
-### Step 4: Guide User to Next Phase
+### Step 4: Run the Plan
 
-Tell the user:
+Tell the user in one line: "Configuration saved to `.5/config.json`, plan written to `.5/planning/CONFIGURE.md` — implementing it now."
 
-1. "Configuration saved to `.5/config.json`"
-2. "Configuration plan written to `.5/planning/CONFIGURE.md`"
-3. "Next steps:"
-   - "Run `/clear` to reset context"
-   - "Then run `/5:implement CONFIGURE`"
-4. "After that: Run `/5:review` if you want a review of generated files"
+Then run `/5:implement CONFIGURE` right away, without asking: the user already chose what to generate in Step 2. It writes the AGENTS.md block and the rules, verifies them, and runs `/5:review` on the result.
 
 ## Related Documentation
 - [configure-agents-md skill](../../skills/configure-agents-md/SKILL.md)