5-phase-workflow 1.9.5 → 2.0.1

package/README.md

@@ -1,466 +1,137 @@
-# 5-Phase Workflow
+# foifi
 
-A systematic, AI-assisted feature development workflow for Claude Code and Codex that works with any tech stack.
+**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 is This?
+### What it does
 
-The **5-Phase Workflow** is a structured approach to feature development that breaks down the process into clear, manageable phases:
+**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.
 
-1. **Feature Planning** - Understand requirements through intensive Q&A
-2. **Implementation Planning** - Map requirements to technical components
-3. **Orchestrated Implementation** - Execute with state tracking and parallel processing
-4. **Verify Implementation** - Automated verification of completeness and correctness
-5. **Code Review** - AI-powered review, findings annotation, and fix application
+**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.
 
-## Why Use It?
+**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.
 
-- **Systematic**: Clear phases prevent missing requirements or skipping validation
-- **Efficient**: Parallel execution and smart agents minimize context usage
-- **Resumable**: State tracking allows pausing and continuing work across sessions
-- **Technology-Agnostic**: Works with JavaScript, Python, Java, Go, Rust, and more
-- **Transparent**: Visible progress tracking and clear handoffs between phases
+This separation keeps planning readable, implementation mechanical, and review structured.
 
-## Installation
+**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.
 
-Install the workflow in your project using npx:
+**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.
 
-```bash
-# Install locally for Claude Code
-npx 5-phase-workflow
-
-# Install locally for Codex
-npx 5-phase-workflow --codex
+**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.
 
-# Or install globally
-npx 5-phase-workflow --global
-npx 5-phase-workflow --codex --global
-```
+### The name
 
-The installer will:
-- For Claude Code: copy workflow commands, agents, and skills to `.claude/`, then set up hooks and settings
-- For Codex: convert workflow commands into skills in `.codex/skills/` and generate `.codex/instructions.md`
-- Create `.5/features/` directory for feature tracking
+"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.
 
-**After installation, you must configure your project:**
-
-## Required: Configure Your Project
+## Install
 
 ```bash
-# Claude Code
-/5:configure
-
-# Codex
-$5-configure
+npx foifi
+npx foifi --codex
 ```
 
-This will:
-- Auto-detect your project type (JavaScript, Python, Java, etc.)
-- Set up build and test commands
-- Configure ticket tracking patterns
-- Generate comprehensive CLAUDE.md documentation
-- Generate a rebuildable codebase index in `.5/index/`
-- Create project-specific skills (create-component, create-service, etc.)
-
-Follow the standard workflow after configuration:
-1. Claude Code: `/5:plan-implementation CONFIGURE`
-2. Codex: `$5-plan-implementation CONFIGURE`
-3. Claude Code: `/5:implement-feature CONFIGURE`
-4. Codex: `$5-implement-feature CONFIGURE`
-5. Claude Code: `/5:verify-implementation`
-6. Codex: `$5-verify-implementation`
-
-**The workflow is ready to use after completing configuration.**
-
-## Start Your First Feature
-
-After configuration is complete, start your first feature:
+Global installs are also supported:
 
 ```bash
-# Claude Code
-/5:plan-feature
-/5:plan-implementation {ticket-id}-{description}
-/5:implement-feature {ticket-id}-{description}
-/5:verify-implementation
-/5:review-code
-/5:address-review-findings
-
-# Codex
-$5-plan-feature
-$5-plan-implementation {ticket-id}-{description}
-$5-implement-feature {ticket-id}-{description}
-$5-verify-implementation
-$5-review-code
-$5-address-review-findings
-```
-
-**Tip:** Running `/clear` between phases in Claude Code resets context and keeps conversations focused. In Codex, start a fresh turn or keep the next phase focused. Each phase reads necessary artifacts from previous phases, so no context is lost.
-
-## Supported Tech Stacks
-
-The workflow auto-detects and supports:
-
-**JavaScript/TypeScript**:
-- Node.js (npm, yarn, pnpm)
-- Next.js
-- NestJS
-- Express
-- React
-- Vue
-
-**Python**:
-- Django
-- Flask
-- FastAPI
-- Generic Python projects
-
-**Java**:
-- Gradle
-- Maven
-- Spring Boot
-
-**Other**:
-- Rust (Cargo)
-- Go
-- Ruby on Rails
-- Custom projects (via manual config)
-
-## Available Commands
-
-Claude Code exposes the workflow under the `/5:` namespace. Codex exposes the same workflow as `$5-...` skills:
-
-| Command | Phase | Purpose |
-|---------|-------|---------|
-| `/5:configure` or `$5-configure` | Setup | Interactive project configuration |
-| `/5:plan-feature` or `$5-plan-feature` | 1 | Create feature specification with Q&A |
-| `/5:discuss-feature` or `$5-discuss-feature` | 1 | Refine existing feature spec |
-| `/5:plan-implementation` or `$5-plan-implementation` | 2 | Map feature to technical components |
-| `/5:implement-feature` or `$5-implement-feature` | 3 | Execute implementation with agents |
-| `/5:verify-implementation` or `$5-verify-implementation` | 4 | Verify completeness and correctness |
-| `/5:review-code` or `$5-review-code` | 5 | AI-powered code review (Claude, Codex, or CodeRabbit workflows) |
-| `/5:address-review-findings` or `$5-address-review-findings` | 5 | Apply annotated findings and address PR comments |
-| `/5:quick-implement` or `$5-quick-implement` | Fast | Streamlined workflow for small tasks |
-| `/5:eject` or `$5-eject` | Utility | Permanently remove update infrastructure |
-| `/5:unlock` or `$5-unlock` | Utility | Remove planning guard lock |
-| `/5:synchronize-agents` or `$5-synchronize-agents` | Utility | Sync user content between Claude Code and Codex runtimes |
-
-## Configuration
-
-The workflow is configured via `.5/config.json`. Here's an example:
-
-```json
-{
-  "projectType": "nextjs",
-  "ticket": {
-    "pattern": "[A-Z]+-\\d+",
-    "extractFromBranch": true
-  },
-  "build": {
-    "command": "npm run build",
-    "testCommand": "npm test"
-  },
-  "steps": [
-    { "name": "foundation", "mode": "parallel" },
-    { "name": "logic", "mode": "sequential" },
-    { "name": "integration", "mode": "sequential" }
-  ],
-  "reviewTool": "coderabbit"
-}
+npx foifi --global
+npx foifi --codex --global
 ```
 
-### Configuration Options
-
-#### Required Fields
-
-- **`projectType`**: Detected project type (e.g., `"nextjs"`, `"django"`, `"rust"`)
-- **`build.command`**: Command to build the project
-- **`build.testCommand`**: Command to run tests
-
-#### Optional Fields
-
-- **`ticket.pattern`**: Regex pattern for ticket IDs (e.g., `"PROJ-\\d+"`)
-- **`ticket.extractFromBranch`**: Auto-extract ticket from branch name
-- **`steps`**: Implementation step configuration
-- **`framework`**: Framework-specific patterns (routes, models, etc.)
-- **`integration`**: Integration point configuration
-- **`tools`**: Available development tools (CodeRabbit, IDE, etc.)
-
-Run `/5:configure` to set up or update your configuration.
-
-## How It Works
-
-### Phase 1: Feature Planning
-
-Claude asks 5-10 clarifying questions to understand your requirements:
-
-- What exactly should this feature do?
-- What are the edge cases?
-- How will we verify it works?
-- Are there simpler alternatives?
-
-The output is a comprehensive feature spec at `.5/features/{ticket-id}/feature.md`.
-
-### Phase 2: Implementation Planning
-
-Claude maps your feature to technical components:
-
-- Analyzes your codebase structure
-- Identifies affected modules
-- Maps components to implementation steps
-- Creates dependency graph
-
-The output is an **atomic plan structure** at `.5/features/{ticket-id}/`:
-- `feature.md` - Feature specification (Phase 1)
-- `plan.md` - Implementation plan (Phase 2)
-- `state.json` - Implementation state tracking (Phase 3)
-
-Each step file is self-contained and independently loadable, making large plans manageable and improving agent efficiency.
-
-### Phase 3: Orchestrated Implementation
-
-Claude executes the plan using specialized agents:
-
-- **step-executor**: Creates each component using skills or direct file creation
-- **step-verifier**: Compiles and checks for errors after each step
-- **integration-agent**: Wires components and registers routes
-
-State is tracked in `.5/features/{ticket-id}/state.json` for resumability.
-
-### Phase 4: Verify Implementation
-
-An agent performs comprehensive verification:
-
-- All planned files exist
-- No compilation/build errors
-- Tests pass
-- IDE diagnostics clean
-
-Results are saved to a verification report.
-
-### Phase 5: Code Review
-
-Two commands work together to handle the review workflow:
-
-**`/5:review-code`** — runs the automated review and presents findings:
-- Supports Claude (built-in, no setup) or CodeRabbit CLI
-- Reviews staged changes, unstaged changes, or branch diff
-- Categorizes findings as Fixable, Questions, or Manual
-- Lets you fix immediately or save findings for later
-
-**`/5:address-review-findings`** — applies annotated findings from a saved file:
-- Reads the `review-findings-*.md` file generated by `/5:review-code`
-- Applies `[FIX]` items, skips `[SKIP]` items, and follows `[MANUAL]` instructions
-- Optionally fetches and addresses GitHub PR review comments
-- Posts threaded replies to processed PR comments
-- Runs build, tests, and lint after applying fixes
-- Saves a summary report
+Claude Code installs commands under `.claude/`. Codex installs converted skills under `.codex/skills/`.
 
-## Project Structure
+## Configure
 
-After installation, your `.claude/` directory will contain:
-
-```
-.5/
-├── config.json               # Project configuration
-├── version.json              # Version tracking
-├── index/                    # Generated codebase index + rebuild script
-│   ├── rebuild-index.sh
-│   └── *.md
-└── features/                 # Feature tracking
-
-.claude/
-├── commands/5/               # Workflow commands
-│   ├── plan-feature.md
-│   ├── plan-implementation.md
-│   ├── implement-feature.md
-│   ├── verify-implementation.md
-│   ├── review-code.md
-│   ├── address-review-findings.md
-│   ├── discuss-feature.md
-│   ├── quick-implement.md
-│   ├── configure.md
-│   ├── eject.md
-│   ├── unlock.md
-│   └── synchronize-agents.md
-├── skills/                   # Atomic operations
-│   ├── build-project/
-│   ├── run-tests/
-│   └── generate-readme/
-├── hooks/
-│   ├── statusline.js         # Status line integration
-│   ├── check-updates.js      # Update notifications
-│   ├── plan-guard.js         # Planning phase edit guard
-│   └── config-guard.js       # Configuration guard
-└── settings.json             # Claude Code settings
-```
-
-## Examples
-
-### Example 1: Adding a REST API endpoint
+Run configuration once per project:
 
 ```bash
-/5:plan-feature
-# Claude asks about the endpoint: path, methods, request/response format, validation, etc.
-# Creates feature spec
-
-/5:plan-implementation PROJ-1234-add-user-endpoint
-# Claude maps to: route file, controller, service, tests
-# Creates technical plan
-
-/5:implement-feature PROJ-1234-add-user-endpoint
-# Creates route, controller, service, tests
-# Registers route in app
-# Runs build and tests
-
-/5:verify-implementation
-# Verifies all files created
-# Checks build passes
-# Confirms tests pass
+/5:configure
+# or in Codex
+$5-configure
 ```
 
-### Example 2: Small bug fix
+Configuration writes `.5/config.json` and `.5/features/CONFIGURE/plan.md`. Then run:
 
 ```bash
-/5:quick-implement
-# Describe the fix
-# Claude implements, builds, tests in one step
+/5:implement CONFIGURE
+# or
+$5-implement CONFIGURE
 ```
 
-## Troubleshooting
-
-### Build/Test commands not working
-
-1. Run `/5:configure` to verify configuration
-2. Test commands manually in terminal
-3. Update `.5/config.json` with correct commands
-
-### "Cannot find project type"
+That generates project documentation, a rebuildable `.5/index/`, AGENTS.md, a CLAUDE.md shim, and selected project-specific skills/rules.
 
-The auto-detection failed. Run `/5:configure` and manually select your project type.
-
-### State file issues
-
-If implementation gets stuck:
-
-1. Check `.5/features/{ticket-id}/state.json`
-2. Note the `currentStep` value
-3. Run `/5:implement-feature` again - it will resume from that step
-
-### CodeRabbit not working
-
-1. Install: https://docs.coderabbit.ai/cli/installation
-2. Authenticate: `coderabbit auth login`
-3. Run `/5:configure` to update config
-
-## Updating
-
-The workflow automatically detects when a new version is available.
-
-### Automatic Update (Recommended)
+## Workflow
 
 ```bash
-# Interactive upgrade (shows prompt)
-npx 5-phase-workflow
-
-# Force upgrade (no prompts)
-npx 5-phase-workflow --upgrade
-
-# Check version without updating
-npx 5-phase-workflow --check
+/5:plan
+/5:split {feature-name}
+/5:implement {feature-name}
+/5:review
+/5:address-review-findings {feature-name}
 ```
 
-### Legacy Upgrade Method
+Codex equivalents:
 
 ```bash
-npx 5-phase-workflow --uninstall
-npx 5-phase-workflow
+$5-plan
+$5-split {feature-name}
+$5-implement {feature-name}
+$5-review
+$5-address-review-findings {feature-name}
 ```
 
-**Note:** During updates:
-- Config files in `.5/` are preserved
-- User-created commands, agents, skills, hooks, and templates are preserved
-- Only workflow-managed files are updated
-
-### Ejecting
+Verification runs at the end of `/5:implement` and records concise results in `state.json`.
 
-If you want to permanently opt out of the update system (e.g., to customize workflow files without future updates overwriting them), run:
+## Commands
 
-```bash
-# Claude Code
-/5:eject
-
-# Codex
-$5-eject
-```
+| Command | Purpose |
+|---------|---------|
+| `/5:configure` / `$5-configure` | Detect project settings and write the CONFIGURE plan |
+| `/5:plan` / `$5-plan` | Create one unified `plan.md` from requirements, codebase exploration, and user decisions |
+| `/5:discuss-feature` / `$5-discuss-feature` | Refine an existing `plan.md` |
+| `/5:split` / `$5-split` | Split an existing plan into smaller linked plans for separate implementation |
+| `/5:implement` / `$5-implement` | Derive `state.json`, execute steps with agents, and verify inline |
+| `/5:review` / `$5-review` | Review code changes and save findings |
+| `/5:address-review-findings` / `$5-address-review-findings` | Decide on review findings interactively, then apply approved fixes and PR comments |
+| `/5:reconfigure` / `$5-reconfigure` | Refresh docs, index, skills, and rules |
+| `/5:update` / `$5-update` | Upgrade installed workflow files |
+| `/5:eject` / `$5-eject` | Stop workflow-managed updates |
+| `/5:unlock` / `$5-unlock` | Remove a stale planning guard lock |
+| `/5:synchronize-agents` / `$5-synchronize-agents` | Sync user content between Claude Code and Codex |
 
-This permanently removes the update infrastructure:
-- Deletes `check-updates.js` hook, `update.md` and `eject.md` commands
-- Deletes `.5/version.json` and `.5/.update-cache.json`
-- For Claude Code, removes the update check hook entry from `.claude/settings.json`
-- For Codex, removes the converted update/eject skills from `.codex/skills/`
+## Artifacts
 
-All other workflow files remain untouched. **This is irreversible.** To restore update functionality, reinstall with `npx 5-phase-workflow`.
+Each feature lives under `.5/features/{feature-name}/`:
 
-### Synchronizing Runtimes
+- `plan.md` - single human-reviewed planning artifact
+- `codebase-scan.md` - cached discovery used to reduce repeated scanning
+- `state.json` - enriched execution state derived by `step-orchestrator-agent`
+- `state-events.jsonl` - detailed execution history for retries, commands, commits, and verification
+- `split-manifest-*.json` - parent feature record for child plans created by `/5:split`
+- `review-findings-*.md` - review output for `/5:address-review-findings`
+- `review-decisions-*.json` - interactive fix/wont-fix/wait decisions for local findings
+- `pr-comment-decisions.json` - PR review comment decisions when PR handling is used
 
-If you have both Claude Code and Codex installed, user-generated content (project-specific skills, custom commands, rules) only exists in the runtime where it was created. To sync this content bidirectionally:
+## Design
 
-```bash
-# Claude Code
-/5:synchronize-agents
+Planning stays human-readable. `plan.md` contains scope, acceptance criteria, decisions, module impact, and a clean component checklist. Small low-risk changes can use the compact plan template. Plans intentionally do not ask the planner to fill model choices, verify commands, step grouping, or pattern-file wiring.
 
-# Codex
-$5-synchronize-agents
-```
+Implementation is mechanical. `step-orchestrator-agent` reads `plan.md` and `codebase-scan.md`, derives the execution graph into compact `state.json`, then `/5:implement` delegates each component to `step-executor-agent` with an inline executor contract. Pattern context is passed as targeted references instead of broad file lists so executors can read only the relevant ranges. Detailed history is appended to `state-events.jsonl`. This reduces planning token cost and avoids brittle prompt-table metadata.
 
-This will:
-- Sync project-specific skills (e.g., `create-controller`, `run-tests`) between `.claude/skills/` and `.codex/skills/` with appropriate format conversion
-- Convert custom Claude commands to Codex skills
-- Append `.claude/rules/` content to `.codex/instructions.md`
-- Sync Codex-only skills back to Claude
+Verification uses a dedicated agent. `/5:implement` runs `verification-agent` at the end and records a concise final status in `state.json` without generating an extra report.
 
-Workflow-managed files and shared data (`.5/`) are not affected — those are handled by the installer.
+Review is risk-based. Native review triages changed files first and reads full files only for risky changes or when diff context is insufficient. `/5:address-review-findings` presents each finding one by one with a recommendation, records `fix`/`wont_fix`/`wait` decisions, then coordinates narrower helpers for approved local fixes, PR comment triage, and PR replies so the common path stays compact.
 
-## Development
+Reconfiguration uses a compact `.5/reconfigure-manifest.json` to pass refresh decisions to documentation and skill generation helpers without duplicating long detection summaries in prompts.
 
-### Running Tests
+For Codex installs, the workflow is token-budgeted: exploration, orchestration, and simple executors default to `gpt-5.4-mini` with low reasoning. Complex logic, security-sensitive work, data migrations, public API changes, final verification that needs deeper review, and failed retries escalate to `gpt-5.4` with medium reasoning.
 
-The project includes automated verification to ensure all workflow files are properly configured:
+## Updating
 
 ```bash
-# Run verification tests
-npm test
-
-# Or run directly
-bash test/verify-install-js.sh
+npx foifi --upgrade
+npx foifi --codex --upgrade
 ```
 
-This verifies that all workflow files (commands, agents, skills, hooks, templates) are properly listed in `bin/install.js` for selective updates.
-
-### Continuous Integration
-
-A GitHub Actions workflow runs on every push to verify the install.js configuration. The workflow:
-- Checks that all workflow files are listed in `getWorkflowManagedFiles()`
-- Ensures selective updates will work correctly
-- Prevents accidental omissions that could break user upgrades
-
-See `.github/workflows/test.yml` for details.
-
-### Adding New Workflow Files
-
-When adding new commands, agents, skills, hooks, or templates:
-
-1. Create the file in the appropriate `src/` directory
-2. **Update `bin/install.js`** - Add the file to `getWorkflowManagedFiles()`
-3. Run `npm test` to verify
-4. Commit only if tests pass
-
-See `CLAUDE.md` for detailed development guidelines.
-
-## License
-
-MIT
-
-## Learn More
-
-- [Full Workflow Guide](./docs/workflow-guide.md) - Detailed documentation
-- [Claude Code Docs](https://docs.anthropic.com/claude/docs/claude-code) - Claude Code features
+v2.0.0 is a hard migration. Finish in-progress v1.9.5 features before upgrading; v1 `feature.md` and old `state.json` formats are not supported.