5-phase-workflow 1.9.4 → 2.0.0

package/README.md

@@ -1,466 +1,114 @@
-# 5-Phase Workflow
+# foifi
 
-A systematic, AI-assisted feature development workflow for Claude Code and Codex that works with any tech stack.
+A structured AI-assisted development workflow for Claude Code and Codex.
 
-## What is This?
-
-The **5-Phase Workflow** is a structured approach to feature development that breaks down the process into clear, manageable phases:
-
-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
-
-## Why Use It?
-
-- **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
-
-## Installation
-
-Install the workflow in your project using npx:
+## Install
 
 ```bash
-# Install locally for Claude Code
-npx 5-phase-workflow
-
-# Install locally for Codex
-npx 5-phase-workflow --codex
-
-# Or install globally
-npx 5-phase-workflow --global
-npx 5-phase-workflow --codex --global
+npx foifi
+npx foifi --codex
 ```
 
-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
-
-**After installation, you must configure your project:**
-
-## Required: Configure Your Project
+Global installs are also supported:
 
 ```bash
-# Claude Code
-/5:configure
-
-# Codex
-$5-configure
-```
-
-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:
-
-```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
+Claude Code installs commands under `.claude/`. Codex installs converted skills under `.codex/skills/`.
 
-Results are saved to a verification report.
+## Configure
 
-### 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
-
-## Project Structure
-
-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"
-
-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
+That generates project documentation, a rebuildable `.5/index/`, AGENTS.md, a CLAUDE.md shim, and selected project-specific skills/rules.
 
-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
+Verification runs at the end of `/5:implement` and records concise results in `state.json`.
 
-### Ejecting
+## Commands
 
-If you want to permanently opt out of the update system (e.g., to customize workflow files without future updates overwriting them), run:
+| 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 |
 
-```bash
-# Claude Code
-/5:eject
+## Artifacts
 
-# Codex
-$5-eject
-```
+Each feature lives under `.5/features/{feature-name}/`:
 
-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/`
+- `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
 
-All other workflow files remain untouched. **This is irreversible.** To restore update functionality, reinstall with `npx 5-phase-workflow`.
+## Design
 
-### Synchronizing Runtimes
+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.
 
-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:
+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.
 
-```bash
-# Claude Code
-/5:synchronize-agents
+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.
 
-# Codex
-$5-synchronize-agents
-```
-
-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
-
-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.