5-phase-workflow
Advanced tools
A systematic, AI-assisted feature development workflow for Claude Code and Codex that works with any tech stack.
The 5-Phase Workflow is a structured approach to feature development that breaks down the process into clear, manageable phases:
Install the workflow in your project using npx:
# 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
The installer will:
.claude/, then set up hooks and settings.codex/skills/ and generate .codex/instructions.md.5/features/ directory for feature trackingAfter installation, you must configure your project:
# Claude Code
/5:configure
# Codex
$5-configure
This will:
.5/index/Follow the standard workflow after configuration:
/5:plan-implementation CONFIGURE$5-plan-implementation CONFIGURE/5:implement-feature CONFIGURE$5-implement-feature CONFIGURE/5:verify-implementation$5-verify-implementationThe workflow is ready to use after completing configuration.
After configuration is complete, start your first feature:
# 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.
The workflow auto-detects and supports:
JavaScript/TypeScript:
Python:
Java:
Other:
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 |
The workflow is configured via .5/config.json. Here's an example:
{
"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"
}
projectType: Detected project type (e.g., "nextjs", "django", "rust")build.command: Command to build the projectbuild.testCommand: Command to run teststicket.pattern: Regex pattern for ticket IDs (e.g., "PROJ-\\d+")ticket.extractFromBranch: Auto-extract ticket from branch namesteps: Implementation step configurationframework: Framework-specific patterns (routes, models, etc.)integration: Integration point configurationtools: Available development tools (CodeRabbit, IDE, etc.)Run /5:configure to set up or update your configuration.
Claude asks 5-10 clarifying questions to understand your requirements:
The output is a comprehensive feature spec at .5/features/{ticket-id}/feature.md.
Claude maps your feature to technical components:
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.
Claude executes the plan using specialized agents:
State is tracked in .5/features/{ticket-id}/state.json for resumability.
An agent performs comprehensive verification:
Results are saved to a verification report.
Two commands work together to handle the review workflow:
/5:review-code — runs the automated review and presents findings:
/5:address-review-findings — applies annotated findings from a saved file:
review-findings-*.md file generated by /5:review-code[FIX] items, skips [SKIP] items, and follows [MANUAL] instructionsAfter 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
├── 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
/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:quick-implement
# Describe the fix
# Claude implements, builds, tests in one step
/5:configure to verify configuration.5/config.json with correct commandsThe auto-detection failed. Run /5:configure and manually select your project type.
If implementation gets stuck:
.5/features/{ticket-id}/state.jsoncurrentStep value/5:implement-feature again - it will resume from that stepcoderabbit auth login/5:configure to update configThe workflow automatically detects when a new version is available.
# 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
npx 5-phase-workflow --uninstall
npx 5-phase-workflow
Note: During updates:
.5/ are preservedIf you want to permanently opt out of the update system (e.g., to customize workflow files without future updates overwriting them), run:
# Claude Code
/5:eject
# Codex
$5-eject
This permanently removes the update infrastructure:
check-updates.js hook, update.md and eject.md commands.5/version.json and .5/.update-cache.json.claude/settings.json.codex/skills/All other workflow files remain untouched. This is irreversible. To restore update functionality, reinstall with npx 5-phase-workflow.
The project includes automated verification to ensure all workflow files are properly configured:
# Run verification tests
npm test
# Or run directly
bash test/verify-install-js.sh
This verifies that all workflow files (commands, agents, skills, hooks, templates) are properly listed in bin/install.js for selective updates.
A GitHub Actions workflow runs on every push to verify the install.js configuration. The workflow:
getWorkflowManagedFiles()See .github/workflows/test.yml for details.
When adding new commands, agents, skills, hooks, or templates:
src/ directorybin/install.js - Add the file to getWorkflowManagedFiles()npm test to verifySee CLAUDE.md for detailed development guidelines.
MIT
FAQs
A 5-phase feature development workflow for Claude Code
We found that 5-phase-workflow demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.