Claude Code Workflow Template

> Automated development workflow powered by Claude Code CLI - A complete agent-based development system with smart model usage, context preservation, and multi-persona automation.


What is This?

A production-ready, portable workflow automation system that uses Claude Code CLI to implement user stories with minimal human intervention. Think "CI/CD for development" - but instead of deploying code, it writes code.

Find us at our discord

$3

- Multi-Persona Agent System - 8 specialized AI agents (SM, DEV, BA, ARCHITECT, PM, WRITER, MAINTAINER, REVIEWER)
- Smart Model Usage - Opus for development, Sonnet for planning (40-60% cost savings)
- Context Preservation - Automatic checkpoints prevent work loss from context limits
- Full Automation - Context -> Development -> Testing -> Review -> Commit pipeline
- Greenfield + Brownfield - Supports both new features AND existing codebase maintenance
- Agent Personalization - Agent overrides and persistent agent memory
- Claude Code Integration - Native slash commands (/story, /swarm, /pair, /route, etc.)
- Multi-Agent Collaboration - Swarm mode, pair programming, and auto-routing
- Knowledge Graph - Queryable database of all architectural decisions and design choices
- Shared Memory - Cross-agent memory pool for context sharing and learnings
- Agent Handoff System - Structured context preservation between agent transitions
- Multi-Currency Cost Tracking - Customizable currency display with budget controls and alerts
- Persistent Status Line - Real-time context and cost percentage display in CLI
- Validation Framework - Three-tier automated validation with auto-fix capability
- Project Agnostic - Works with Flutter, Node.js, Python, Rust, Go, Ruby, etc.
- Guided Setup - Interactive wizard guides you through installation

Quick Start

$3

macOS/Linux:
- Claude Code CLI - See installation guide
- Python 3.9+
- Git
- Bash or Zsh shell

Windows:
- Claude Code CLI - See installation guide
- Python 3.9+ (from python.org or Microsoft Store)
- Git for Windows
- PowerShell 5.1+ (included with Windows 10/11)

$3

Choose the method that best fits your needs:

#### Option 1: Add to Existing Project (Recommended)

``bash


Navigate to your project directory

cd your-project

Install Devflow into your existing project

npx @pjmendonca/devflow@latest install

This will:

1. Copy .claude/ and tooling/ directories into your project

2. Claude Code automatically detects the slash commands

3. Optionally run the setup wizard (use --skip-setup to skip)

Start using immediately:

/story
`

#### Option 2: Create Standalone Project

`bash


Create a new Devflow directory

npx @pjmendonca/devflow@latest

Or use npm create:

npm create @pjmendonca/devflow

This will:

1. Create a "Devflow" folder in your current directory

2. Copy all essential files into it

3. Run the interactive setup wizard

Then use it:

cd Devflow
/story
`

#### Option 3: Global Installation

`bash


Install globally for system-wide access

npm install -g @pjmendonca/devflow

Then run from anywhere:

devflow install # Add to existing project
devflow --help # Show available commands
`

$3

| Agent | Model | Cost | Use Case |
|-------|-------|------|----------|
| SM (Scrum Master) | Sonnet | Low | Context, planning, review |
| DEV (Developer) | Opus | High | Code implementation |
| BA (Business Analyst) | Sonnet | Low | Requirements |
| ARCHITECT | Sonnet | Low | Design specs |
| PM (Product Manager) | Sonnet | Low | Epic planning |
| WRITER | Sonnet | Low | Documentation |
| MAINTAINER | Opus/Sonnet | Varies | Bug fixes, refactoring, tech debt |
| REVIEWER (Adversarial) | Opus | High | Critical code review, finds problems |

Claude Slash Commands

Devflow provides native slash commands for Claude Code:

$3

| Command | Description |
|---------|-------------|
| /story | Run full story pipeline (context + dev + review) |
| /develop | Run development phase only |
| /review | Run code review phase |
| /agent | Invoke a specific agent |
| /adversarial | Critical review with Opus |

$3

| Command | Description |
|---------|-------------|
| /swarm | Multi-agent debate/consensus mode |
| /pair | DEV + REVIEWER pair programming |
| /route | Auto-route to best agents |
| /collab | Unified collaboration CLI |

$3

| Command | Description |
|---------|-------------|
| /memory | View/query shared agent memory |
| /handoff | View handoff summaries between agents |
| /checkpoint | Create/restore context checkpoints |
| /costs | View cost dashboard and analytics |
| /personalize | Agent personalization wizard |
| /devflow | Run any Devflow command |

Examples:
`bash
/swarm 3-5 # Run swarm with default agents
/swarm 3-5 --agents ARCHITECT,DEV # Custom agents
/pair 3-5 # Pair programming mode
/route "fix login bug" # Auto-route to specialists
/memory 3-5 --query "auth decisions" # Query knowledge graph
`

Knowledge Graph & Shared Memory

Devflow features a sophisticated memory system that enables agents to share context, track decisions, and maintain institutional knowledge across the entire development workflow.

$3

The Knowledge Graph is a queryable database of all architectural decisions, design choices, and key learnings made during development.

Features:
- Decision Tracking - All major decisions are recorded with context, rationale, and timestamps
- Semantic Queries - Ask natural language questions about past decisions
- Decision Supersession - Track when decisions are updated or replaced
- Agent Attribution - Know which agent made each decision

`bash


Query the knowledge graph

python tooling/scripts/run-collab.py 3-5 --query "What authentication approach was decided?"

View all decisions for a story

python tooling/scripts/run-collab.py 3-5 --decisions

Add a decision programmatically

python -c "
from tooling.scripts.lib.shared_memory import get_knowledge_graph
kg = get_knowledge_graph('3-5')
kg.add_decision('ARCHITECT', 'auth-approach', 'Use JWT with refresh tokens',
context={'reason': 'Stateless, scalable'})
"
`

Decision Structure:
- id - Unique identifier
- topic - Decision category (e.g., "auth-approach", "database-choice")
- decision - The actual decision text
- context - Supporting rationale and metadata
- status - active, superseded, or revoked

$3

The Shared Memory system allows all agents to contribute and access shared context, learnings, and notes throughout the workflow.

Features:
- Cross-Agent Sharing - Any agent can add entries, all agents can read
- Tagging System - Organize entries with searchable tags
- References - Link related memory entries together
- Persistent Storage - Memory persists across sessions

`bash


View shared memory for a story

python tooling/scripts/run-collab.py 3-5 --memory

Search memory entries

python tooling/scripts/run-collab.py 3-5 --memory --search "database"

Add to shared memory programmatically

python -c "
from tooling.scripts.lib.shared_memory import get_shared_memory
memory = get_shared_memory('3-5')
memory.add('DEV', 'Decided to use PostgreSQL for user data', tags=['database', 'decision'])
"
`

Memory Entry Structure:
- agent - Which agent contributed the entry
- content - The actual memory content
- tags - Searchable categorization tags
- references - Links to related entries

Agent Handoff System

The Agent Handoff System ensures seamless transitions between agents with structured context preservation. When one agent finishes their work, a comprehensive handoff summary is automatically generated for the next agent.

Features:
- Automatic Context Extraction - Key decisions, files changed, and blockers are auto-detected
- Git Diff Analysis - Changed files are analyzed and summarized
- Warning/Blocker Identification - Critical issues are highlighted for the next agent
- Structured Templates - Each agent transition has specific focus areas

`bash


View handoff summaries between agents

python tooling/scripts/run-collab.py 3-5 --handoffs

Generate a manual handoff

python -c "
from tooling.scripts.lib.agent_handoff import create_handoff
handoff = create_handoff(
story_key='3-5',
from_agent='SM',
to_agent='DEV',
work_summary='Created story context with all acceptance criteria'
)
print(handoff)
"
`

Handoff Contents:
- Summary - What was accomplished
- Key Decisions - Important choices made
- Blockers Resolved - Issues that were addressed
- Watch Out For - Warnings and concerns
- Files Modified - List of changed files
- Next Steps - Recommended actions for the next agent

Standard Handoff Transitions:

| From | To | Focus Areas |
|------|-----|-------------|
| SM -> DEV | Acceptance criteria, technical context, patterns to follow |
| SM -> ARCHITECT | High-level requirements, system constraints, scale requirements |
| ARCHITECT -> DEV | Architecture decisions, design patterns, interface definitions |
| DEV -> REVIEWER | Implementation approach, key decisions, test coverage |
| REVIEWER -> DEV | Issues found, required changes, approval status |
| BA -> DEV | Refined requirements, acceptance criteria, edge cases |

Multi-Agent Collaboration

Devflow supports advanced multi-agent collaboration modes for complex development tasks.

$3

Multiple agents work together, debating and iterating until consensus:

`bash


Run swarm with default agents (ARCHITECT, DEV, REVIEWER)

npx @pjmendonca/devflow story 3-5 --swarm

Custom agent selection

npx @pjmendonca/devflow story 3-5 --swarm --agents ARCHITECT,DEV,REVIEWER

Control iterations

npx @pjmendonca/devflow story 3-5 --swarm --max-iter 5

Set budget limits

npx @pjmendonca/devflow story 3-5 --swarm --budget 20.00
`

Swarm Configuration Options:
- max_iterations - Maximum debate rounds (default: 3)
- consensus_type - unanimous, majority, quorum, or reviewer_approval
- parallel_execution - Run independent agents simultaneously
- auto_fix_enabled - DEV automatically addresses REVIEWER issues
- budget_limit_usd - Maximum cost for the swarm session

Consensus Types:
| Type | Description |
|------|-------------|
| unanimous | All agents must agree |
| majority | >50% of agents agree |
| quorum | N of M agents agree |
| reviewer_approval | REVIEWER must approve (default) |

How it works:
1. All agents analyze the task
2. Agents provide feedback on each other's work
3. Issues are addressed iteratively
4. Continues until consensus or max iterations

$3

DEV and REVIEWER work together in real-time:

`bash
npx @pjmendonca/devflow story 3-5 --pair
`

How it works:
1. DEV implements code in small chunks
2. REVIEWER provides immediate feedback
3. DEV addresses issues before continuing
4. Higher quality code with fewer late-stage revisions

$3

Let Devflow automatically select the best agents:

`bash


Auto-detect task type and select appropriate agents

npx @pjmendonca/devflow story "fix authentication bug" --auto-route

Works with any task description

npx @pjmendonca/devflow story "add user profile feature" --auto-route
`

How it works:
- Analyzes task description for keywords
- Considers file types and complexity
- Routes to appropriate specialists (e.g., bugs -> MAINTAINER agent, new features -> DEV agent)

Cost Tracking & Currency Configuration

Devflow includes a comprehensive cost tracking system with multi-currency support and budget controls.

$3

During setup, the initialization wizard prompts you to select your preferred currency for cost display. Supported currencies include:

| Currency | Symbol | Name |
|----------|--------|------|
| USD | $ | US Dollar |
| EUR | € | Euro |
| GBP | £ | British Pound |
| BRL | R$ | Brazilian Real |
| CAD | C$ | Canadian Dollar |
| AUD | A$ | Australian Dollar |
| JPY | ¥ | Japanese Yen |
| CNY | ¥ | Chinese Yuan |
| INR | ₹ | Indian Rupee |
| MXN | $ | Mexican Peso |

Setting currency in setup wizard:
`bash
./init-project-workflow.sh


or


.\init-project-workflow.ps1
`

Setting currency manually:
`bash


In your config file or environment

export COST_DISPLAY_CURRENCY="EUR"

Set custom exchange rates (optional)

export CURRENCY_RATE_EUR=0.92
export CURRENCY_RATE_GBP=0.79
export CURRENCY_RATE_BRL=6.10
`

$3

Set spending limits for different phases of the workflow:

`bash
export MAX_BUDGET_CONTEXT=3.00 # Context creation: $3 max
export MAX_BUDGET_DEV=15.00 # Development: $15 max
export MAX_BUDGET_REVIEW=5.00 # Code review: $5 max
`

$3

The system provides automatic alerts at configurable thresholds:

`bash
export COST_WARNING_PERCENT=75 # Yellow warning at 75%
export COST_CRITICAL_PERCENT=90 # Red warning at 90%
export COST_AUTO_STOP="true" # Auto-stop at 100%
`

$3

View detailed cost information with the cost dashboard:

`bash


Show current/latest session

python tooling/scripts/cost_dashboard.py

Show last 10 sessions

python tooling/scripts/cost_dashboard.py --history 10

Show costs for a specific story

python tooling/scripts/cost_dashboard.py --story 3-5

Export to CSV

python tooling/scripts/cost_dashboard.py --export costs.csv

Show aggregate summary

python tooling/scripts/cost_dashboard.py --summary
`

Dashboard Features:
- Real-time cost display during runs
- Multi-currency display (shows all selected currencies)
- Token usage breakdown (input/output)
- Cost by agent breakdown
- Budget utilization tracking
- Session history and analytics

$3

- Use Opus sparingly - Reserve for development and critical reviews
- Use Sonnet for planning - Context creation, documentation, and summaries
- Set budget limits - Prevent runaway costs with phase-specific limits
- Monitor the dashboard - Track spending patterns across stories

$3

Devflow provides a persistent status line in Claude Code that shows real-time metrics:

`
[Devflow] Claude Opus 4.5 | Context: 12.3% | Cost: $0.1234 (8.2%) | +45 -12 lines
`

What it shows:
- Model - Current Claude model in use
- Context - Percentage of context window used (with color coding)
- Cost - Cumulative cost with subscription usage percentage
- Lines - Lines added/removed in the session

Retroactive Cost Tracking:

The cost percentage is calculated retroactively across all sessions in your billing period:
- Reads all session files from tooling/.automation/costs/sessions/
- Sums tokens used within the billing period (default: 30 days)
- Shows percentage of your subscription token limit used
- Updates in real-time as you work

Color coding for cost percentage:
- Green - Under 75% of subscription limit
- Yellow - 75-89% of subscription limit (warning)
- Red - 90%+ of subscription limit (critical)

Configuration:

The status line reads currency settings from tooling/.automation/costs/config.json. To customize:

`bash


Set display currency

export COST_DISPLAY_CURRENCY="EUR"

Or edit config.json:

{
"display_currency": "BRL",
"currency_rates": {
"USD": 1.0,
"BRL": 6.10,
"EUR": 0.92
}
}
`

$3

Track your usage against API subscription limits:

`bash


View subscription usage

python tooling/scripts/cost_dashboard.py --subscription

Set your plan manually

python tooling/scripts/cost_dashboard.py --set-plan pro

View usage projection

python tooling/scripts/cost_dashboard.py --subscription
`

Auto-Detection:

Devflow automatically detects your subscription plan based on the model you're using:
- Opus users -> Pro plan (5M tokens/month)
- Sonnet users -> Developer plan (1M tokens/month)
- Haiku users -> Free plan (100K tokens/month)

The detected plan is saved to tooling/.automation/costs/config.json for future sessions.

Available plans: free, developer, pro, scale, enterprise

Manual configuration (overrides auto-detection):
`bash
export SUBSCRIPTION_PLAN="pro" # Use a preset plan
export SUBSCRIPTION_TOKEN_LIMIT=5000000 # Or set custom limit
`

$3

Analyze which models give you the best value:

`bash
python tooling/scripts/cost_dashboard.py --efficiency
`

Shows cost-per-output-token for each model, helping optimize model selection.

$3

Predict when you'll reach your subscription limits:

`bash


View usage projection in subscription view


python tooling/scripts/cost_dashboard.py --subscription
`

What it shows:
- Daily average token consumption
- Projected days until limit reached
- End-of-period usage forecast vs limit
- Color-coded status: on-track (green), warning (yellow), critical (red)

$3

Generate comprehensive analytics reports:

`bash


Generate full analytics report (Markdown)

python tooling/scripts/cost_dashboard.py --schedule-export report.md

Export to JSON format

python tooling/scripts/cost_dashboard.py --schedule-export report.json
`

Report contents:
- Daily usage trends (last 14 days with tokens, cost, sessions)
- Per-story cost rankings (top 10 by token consumption)
- Period comparison (current vs previous period with deltas)
- API rate statistics (calls/day, calls/hour, peak times)

$3

Monitor your API call patterns:

`bash
python tooling/scripts/cost_dashboard.py --summary
`

Metrics tracked:
- Total API calls in period
- Average calls per day/hour
- Peak usage hour and day
- Hourly and daily distribution data

Validation Framework

Devflow includes a three-tier validation system that ensures code quality throughout the development pipeline.

$3

| Tier | Name | When | Validates |
|------|------|------|-----------|
| 1 | Pre-flight | Before starting | Story exists, budget available, dependencies |
| 2 | Inter-phase | Between phases | Code compiles, lint passes, phase transitions |
| 3 | Post-completion | After finishing | Tests pass, types valid, version synced |

$3

`bash


Validate a story

/validate 3-5

Run specific tier

/validate 3-5 --tier pre-flight

Run with auto-fix for lint issues

/validate 3-5 --auto-fix
`

$3

Pre-flight (Tier 1):
- Story file exists
- Budget is available
- Required dependencies installed

Inter-phase (Tier 2):
- TypeScript/Python compilation
- Linting (with auto-fix option)
- Phase transition rules

Post-completion (Tier 3):
- Test suite passes
- Type checking passes
- Version sync validated

$3

Customize validation in tooling/.automation/validation-config.yaml:

`yaml
gates:
lint:
enabled: true
auto_fix: true
timeout: 60
test:
enabled: true
command: "npm test"
timeout: 300
`

Shell Completion

Enable tab-completion for faster command entry.

$3

`bash


Option 1: Add to fpath (recommended)

mkdir -p ~/.zsh/completions
cp tooling/completions/_run-story ~/.zsh/completions/

Add to ~/.zshrc:

fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit && compinit

Reload shell

source ~/.zshrc
`

`bash


Option 2: Direct source

Add to ~/.zshrc:

source /path/to/devflow/tooling/completions/_run-story
`

$3

`bash


Option 1: System-wide (requires sudo)

sudo cp tooling/completions/run-story-completion.bash /etc/bash_completion.d/devflow

Option 2: User only - add to ~/.bashrc:

source /path/to/devflow/tooling/completions/run-story-completion.bash
`

$3

`powershell


Add to your PowerShell profile ($PROFILE):

. C:\path\to\devflow\tooling\completions\DevflowCompletion.ps1

Or import as module:

Import-Module C:\path\to\devflow\tooling\completions\DevflowCompletion.ps1

View available commands

devflow-help
`

$3

- Modes: --swarm, --pair, --auto-route, --sequential
- Agents: SM, DEV, BA, ARCHITECT, PM, WRITER, MAINTAINER, REVIEWER
- Models: opus, sonnet, haiku
- Options: --budget, --max-iterations, --quiet, etc.

Example usage:

`bash


Type and press Tab:


./run-story.sh 3-5 --sw # Completes to --swarm
./run-story.sh 3-5 --agents AR # Completes to ARCHITECT
`

Security Considerations

$3

Devflow relies on the Claude Code CLI for API authentication. The CLI handles API keys securely:

- API keys are managed by Claude Code CLI - Devflow never directly handles or stores API keys
- Keys are stored in the Claude CLI's secure configuration, not in Devflow's project files
- Never commit API keys - The .gitignore should exclude any files containing sensitive data

Best practices:

1. Use Claude CLI's built-in authentication:
`bash
claude login # Authenticate via the CLI
`

2. For CI/CD environments, use environment variables:
`bash
export ANTHROPIC_API_KEY="your-key-here"
`

3. Verify your .gitignore includes:
`
.env
.env.local
*.pem
*.key
tooling/.automation/config.sh # Contains environment-specific settings
`

4. Review logs before sharing - Cost tracking logs in tooling/.automation/logs/ may contain session metadata

$3

- Session cost data is stored locally in tooling/.automation/costs/`
- No data is sent to external servers by Devflow (only to Anthropic's API via Claude CLI)
- Context checkpoints may contain code snippets - review before sharing

License

MIT License - see LICENSE for details.

Free to use in commercial and personal projects.

Acknowledgments

- Built for Claude Code CLI
- Agent override system inspired by BMAD-METHOD
- Agent-based architecture influenced by AutoGPT, CrewAI

Version: 1.20.1
Status: Production Ready
Last Updated: 2026-01-18