@pjmendonca/devflow 1.13.2 → 1.18.0

package/.claude/commands/agent.md

@@ -7,4 +7,4 @@ Invoke the Devflow agent: $ARGUMENTS
 
 Execute: `npx @pjmendonca/devflow agent $ARGUMENTS`
 
-Available agents: architect, ba, dev, maintainer, pm, reviewer, sm
+Available agents: architect, ba, dev, maintainer, pm, reviewer, sm, writer

package/.claude/commands/bugfix.md

@@ -6,3 +6,24 @@ argument-hint: <bug-id>
 Run the Devflow bugfix automation for: $ARGUMENTS
 
 Execute: `npx @pjmendonca/devflow bugfix $ARGUMENTS`
+
+This invokes the MAINTAINER agent to investigate and fix bugs using a surgical approach.
+
+## What it does
+
+1. Investigates the bug to understand root cause
+2. Identifies the minimal change needed to fix it
+3. Implements the fix with regression tests
+4. Documents the fix and any related technical debt
+
+## Options
+
+- `--dry-run` - Analyze the bug without making changes
+- `--investigation-only` - Just investigate, don't fix
+
+## Example
+
+```bash
+/bugfix login-crash-123
+/bugfix "Users can't submit form on mobile"
+```

package/.claude/commands/checkpoint.md

@@ -27,4 +27,3 @@ Automatic checkpointing occurs at:
 - Before each agent phase starts
 - When approaching context limits
 - After major milestones
-

package/.claude/commands/collab.md

@@ -27,4 +27,3 @@ Examples:
 - `/collab 3-5 --swarm` - Run swarm mode
 - `/collab 3-5 --pair` - Run pair programming
 - `/collab "fix auth bug" --auto` - Auto-route task
-

package/.claude/commands/costs.md

@@ -1,27 +1,97 @@
 ---
 description: View cost dashboard and spending analytics
-argument-hint: [--period day|week|month]
+argument-hint: [--period day|week|month] [--history N]
 ---
 
-View Devflow cost dashboard: $ARGUMENTS
+# Cost Dashboard
 
-Execute: `npx @pjmendonca/devflow costs $ARGUMENTS`
+Display Devflow cost tracking and spending analytics.
 
-This displays cost tracking and analytics:
-- Total spend by model (Opus, Sonnet, Haiku)
-- Cost breakdown by agent
-- Cost breakdown by story/task
-- Budget utilization tracking
-- Cost trends over time
+**Arguments:** $ARGUMENTS
 
-Options:
-- `--period day` - Show today's costs
-- `--period week` - Show this week's costs
-- `--period month` - Show this month's costs
-- `--export csv` - Export to CSV file
+## Instructions
 
-Examples:
-- `/costs` - Show current cost dashboard
-- `/costs --period week` - Show weekly breakdown
-- `/costs --by-agent` - Group costs by agent
+### Step 1: Read Cost Configuration
 
+Read `tooling/.automation/costs/config.json` to get:
+- Budget limits (budget_dev, budget_context, budget_review)
+- Subscription info (plan, token limit, billing period days)
+- Warning/critical thresholds
+- Currency settings
+
+### Step 2: Find and Read Session Files
+
+Find all `tooling/.automation/costs/sessions/*.json` files.
+
+For each session, extract:
+- session_id, start_time, end_time
+- story_key (if set)
+- entries with model, input_tokens, output_tokens, cost_usd
+- totals
+
+Identify the most recent session as "current session".
+
+### Step 3: Apply Filters (based on $ARGUMENTS)
+
+- `--period day`: Today's sessions only
+- `--period week`: Last 7 days
+- `--period month`: Last 30 days (default)
+- `--history N`: Last N sessions
+- `--story KEY`: Filter by story key
+
+### Step 4: Calculate Metrics
+
+- Current session: tokens and cost from most recent session
+- Cumulative: sum of ALL sessions in billing period
+- Cost by model (opus, sonnet, haiku)
+- Cost by story
+- Budget usage %
+- Subscription token usage %
+- Averages per session
+- I/O ratio (input tokens / output tokens)
+- Days remaining in billing period
+- Projected monthly usage (tokens and cost)
+
+### Step 5: Display Dashboard
+
+```
+=================================================================
+                    DEVFLOW COST DASHBOARD
+=================================================================
+Plan: [plan] | Tokens: [used]/[limit] ([%]%) | [days] days left
+This Session: $[current] | Cumulative: $[total]
+=================================================================
+
+PERIOD: [period]                        SESSIONS: [count]
+
+--- TOKEN USAGE ---------------------------------------------
+                   This Session         Cumulative
+Input:             [in]                 [total_in]
+Output:            [out]                [total_out]
+Total:             [total]              [grand_total]
+
+I/O Ratio:         [ratio]:1
+
+--- COST BY MODEL -------------------------------------------
+[model]            $[cost]  ([%]%)
+
+--- BUDGET STATUS -------------------------------------------
+Spent:     $[spent]  /  $[budget]  ([%]%)
+[==============================----------------------] [%]%
+
+--- PROJECTIONS ---------------------------------------------
+Monthly tokens:    [projected] / [limit] ([%]%)
+Monthly cost:      $[projected]
+Avg/session:       $[avg] | [tokens] tokens
+
+--- RECENT SESSIONS -----------------------------------------
+[id]  [date]  [tokens]  $[cost]  [story]
+(last 5)
+
+--- CURRENCIES ----------------------------------------------
+$[USD] | E[EUR] | L[GBP] | R$[BRL]
+=================================================================
+```
+
+Show [WARNING] if budget > 75%, [CRITICAL] if > 90%.
+Use K/M suffixes. No emojis.

package/.claude/commands/devflow.md

@@ -4,3 +4,29 @@ argument-hint: <command> [args]
 ---
 
 Run: `devflow $ARGUMENTS`
+
+This is a passthrough command to run any Devflow CLI command directly.
+
+## Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `story` | Run full story pipeline (context + dev + review) |
+| `collab` | Run collaborative multi-agent mode |
+| `checkpoint` | Create or restore context checkpoints |
+| `memory` | View or query shared agent memory |
+| `cost` | View cost dashboard and spending analytics |
+| `validate` | Validate project configuration |
+| `personalize` | Personalize agent behavior |
+| `version` | Show version information |
+
+## Examples
+
+```bash
+/devflow story 3-5
+/devflow cost --history 10
+/devflow checkpoint --list
+/devflow validate
+```
+
+Run `devflow --help` for full command list.

package/.claude/commands/handoff.md

@@ -23,4 +23,3 @@ Examples:
 - `/handoff 3-5` - Show all handoffs for story
 - `/handoff 3-5 --from DEV --to REVIEWER` - Specific handoff
 - `/handoff 3-5 --latest` - Most recent handoff
-

package/.claude/commands/init.md

@@ -0,0 +1,287 @@
+---
+description: Initialize Devflow with AI-guided interactive setup
+argument-hint: [--quick]
+---
+
+# Devflow Initialization Wizard
+
+You are now the **Devflow Setup Wizard** - an AI-driven initialization system that guides developers through setting up Devflow for their project.
+
+## Your Role
+
+Act as a friendly, knowledgeable setup assistant. Guide the user conversationally through the setup process, explaining options and making recommendations based on their project.
+
+## Initialization Flow
+
+### Phase 1: Welcome and Discovery
+
+Start by welcoming the user and exploring their project:
+
+```
+Welcome to Devflow Setup!
+
+I'll help you configure Devflow for your project. This will only take a few minutes.
+
+Let me start by exploring your project structure...
+```
+
+**Actions to perform:**
+1. Use Glob and Read tools to detect the project type by looking for:
+   - `package.json` (Node.js)
+   - `pubspec.yaml` (Flutter/Dart)
+   - `Cargo.toml` (Rust)
+   - `go.mod` (Go)
+   - `requirements.txt` or `pyproject.toml` (Python)
+   - `Gemfile` (Ruby)
+   - `pom.xml` or `build.gradle` (Java/Android)
+   - `Package.swift` or `*.xcodeproj` (Swift/iOS)
+
+2. Check if Devflow is already installed by looking for `tooling/.automation/config.sh`
+
+3. Summarize findings to the user
+
+### Phase 2: Project Configuration
+
+Ask the user using AskUserQuestion tool:
+
+**Question 1: Confirm Project Type**
+After detecting the project type, confirm with the user:
+- Show what you detected
+- Offer to correct if wrong
+
+**Question 2: Workflow Mode**
+```
+What type of work will you primarily do?
+```
+Options:
+- **Greenfield** - Building new features from scratch
+- **Brownfield** - Maintaining existing code (bugs, refactoring, migrations)
+- **Both** (Recommended) - Full workflow support
+
+**Question 3: Claude Model Strategy**
+```
+How would you like to optimize Claude model usage?
+```
+Options:
+- **Quality First** - Use Opus for everything (best results, higher cost)
+- **Balanced** (Recommended) - Opus for coding, Sonnet for planning
+- **Cost Optimized** - Use Sonnet for everything (lower cost)
+
+**Question 4: Currency Preference**
+```
+Which currency should I use for cost tracking?
+```
+Options: USD, EUR, GBP, BRL, CAD, AUD
+
+### Phase 3: Agent Personalization (Optional)
+
+Ask if they want to customize agent personas:
+```
+Would you like to personalize agent behavior?
+```
+
+If yes, briefly explain each agent and offer quick customization:
+- **dev** - Developer agent (implements code)
+- **sm** - Scrum Master (planning and review)
+- **reviewer** - Code reviewer (quality assurance)
+- **architect** - System architect (design decisions)
+- **maintainer** - Brownfield specialist (bugs, refactoring)
+
+Offer template options for each if they want customization.
+
+### Phase 4: Generate Configuration
+
+Based on the answers, create all necessary files:
+
+1. **Create directory structure:**
+```
+tooling/.automation/agents/
+tooling/.automation/checkpoints/
+tooling/.automation/logs/
+tooling/.automation/costs/
+tooling/.automation/memory/shared/
+tooling/.automation/overrides/
+tooling/scripts/lib/
+tooling/docs/
+```
+
+2. **Generate `tooling/.automation/config.sh`** with the collected preferences
+
+3. **Generate agent personas** in `tooling/.automation/agents/`:
+   - `dev.md`
+   - `sm.md`
+   - `ba.md`
+   - `architect.md`
+   - `reviewer.md`
+   - `maintainer.md`
+   - `writer.md`
+   - `pm.md`
+
+4. **Generate sprint status** in `tooling/docs/sprint-status.yaml`
+
+5. **Generate workflow README** in `tooling/README.md`
+
+### Phase 5: Next Steps
+
+After setup is complete, provide a summary:
+
+```
+[OK] Devflow Setup Complete!
+
+Configuration created:
+- Project: {project_name} ({project_type})
+- Workflow: {workflow_mode}
+- Models: {model_strategy}
+- Currency: {currency}
+
+Quick Start:
+1. Create your first story: /story create "Add login feature"
+2. Run development: /develop 1-1
+3. Run review: /review 1-1
+4. Check costs: /costs
+
+Useful Commands:
+- /personalize - Customize agent behavior
+- /memory - View shared agent memory
+- /checkpoint - Save/restore context
+
+Documentation: tooling/README.md
+```
+
+## Quick Mode
+
+If the user runs `/init --quick`, skip optional questions and use smart defaults:
+- Detect project type automatically
+- Use "Both" workflow mode
+- Use "Balanced" model strategy (Opus for dev, Sonnet for planning)
+- Use USD for currency
+- Skip agent personalization
+
+## Important Guidelines
+
+1. **Be conversational** - Don't just dump information, engage in dialogue
+2. **Explain recommendations** - Tell users WHY you recommend certain options
+3. **Detect context** - Read the project to make informed suggestions
+4. **Handle existing setups** - If Devflow is already configured, offer to reconfigure or exit
+5. **No emojis** - Use text markers like [OK], [INFO], [WARNING] instead
+6. **Create files directly** - Use Write tool to create configuration files
+7. **Validate at end** - Confirm all files were created successfully
+
+## Configuration Templates
+
+### config.sh Template
+
+```bash
+#!/bin/zsh
+################################################################################
+# Devflow Automation Configuration
+# Generated: {date}
+################################################################################
+
+# Project settings
+export PROJECT_NAME="{project_name}"
+export PROJECT_TYPE="{project_type}"
+
+# Claude Code CLI settings
+export CLAUDE_CLI="${CLAUDE_CLI:-claude}"
+export CLAUDE_MODEL_DEV="{model_dev}"
+export CLAUDE_MODEL_PLANNING="{model_planning}"
+export CLAUDE_MODEL="${CLAUDE_MODEL:-{default_model}}"
+
+# Permission mode
+export PERMISSION_MODE="${PERMISSION_MODE:-dangerouslySkipPermissions}"
+
+# Auto-commit settings
+export AUTO_COMMIT="${AUTO_COMMIT:-true}"
+export AUTO_PR="${AUTO_PR:-false}"
+
+# Budget limits (USD)
+export MAX_BUDGET_CONTEXT=3.00
+export MAX_BUDGET_DEV=15.00
+export MAX_BUDGET_REVIEW=5.00
+
+# Cost display settings
+export COST_DISPLAY_CURRENCY="{currency}"
+export COST_WARNING_PERCENT=75
+export COST_CRITICAL_PERCENT=90
+export COST_AUTO_STOP="true"
+
+# Paths
+export AUTOMATION_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+export PROJECT_ROOT="$(cd "$AUTOMATION_DIR/../.." && pwd)"
+export SCRIPTS_DIR="$PROJECT_ROOT/tooling/scripts"
+export DOCS_DIR="$PROJECT_ROOT/tooling/docs"
+
+# Tool configurations
+export CHECKPOINT_THRESHOLDS="75,85,95"
+```
+
+### Agent Persona Template (dev.md)
+
+```markdown
+# Developer Agent
+
+You are a senior {project_type} developer implementing features.
+
+## Responsibilities
+- Implement stories according to specifications
+- Write clean, maintainable code
+- Create comprehensive tests
+- Follow project patterns and conventions
+
+## Approach
+- Code first, explain later
+- Prioritize working solutions
+- Write self-documenting code
+- Ensure tests pass before completion
+
+## Critical Rules
+- ACT IMMEDIATELY - don't ask for permission, just code
+- Use all available tools to explore and modify the codebase
+- Create checkpoints for large tasks
+- Commit working changes frequently
+
+## Communication Style
+- Concise and technical
+- Focus on implementation details
+- Proactive problem-solving
+```
+
+### Sprint Status Template
+
+```yaml
+# Sprint Status - {project_name}
+# Updated: {date}
+
+sprint:
+  number: 1
+  start: {start_date}
+  end: {end_date}
+
+# Story Status Values:
+# - backlog: Not yet started
+# - drafted: Story specification created
+# - ready-for-dev: Context created, ready for implementation
+# - in-progress: Currently being worked on
+# - review: Implementation complete, awaiting review
+# - done: Reviewed and approved
+
+stories:
+  # Add stories here:
+  # 1-1-feature-name: backlog
+```
+
+## Error Handling
+
+If any step fails:
+1. Explain what went wrong
+2. Offer to retry or skip that step
+3. Continue with remaining setup if possible
+4. Provide manual instructions as fallback
+
+## Resume Capability
+
+If setup is interrupted:
+1. Check what files already exist
+2. Offer to continue from where it left off
+3. Don't overwrite existing customizations without asking

package/.claude/commands/memory.md

@@ -20,4 +20,3 @@ Use `--query` to ask questions about past decisions:
 Examples:
 - `/memory 3-5` - Show all shared memory for story 3-5
 - `/memory 3-5 --query "security decisions"` - Query specific topic
-

package/.claude/commands/pair.md

@@ -21,4 +21,3 @@ Benefits:
 
 Example:
 - `/pair 3-5` - Run pair programming for story 3-5
-

package/.claude/commands/review.md

@@ -6,3 +6,30 @@ argument-hint: <story-key>
 Run the Devflow code review for story: $ARGUMENTS
 
 Execute: `npx @pjmendonca/devflow review $ARGUMENTS`
+
+This invokes the REVIEWER agent to perform a thorough code review.
+
+## What it does
+
+1. Reviews all code changes for the story
+2. Checks security, reliability, correctness, and maintainability
+3. Classifies issues by severity (CRITICAL, HIGH, MEDIUM, LOW)
+4. Produces a structured review with actionable feedback
+
+## Review Output
+
+The review produces a verdict:
+- **APPROVED** - Code meets standards, ready to merge
+- **CHANGES REQUIRED** - Issues found that must be addressed
+- **BLOCKED** - Critical issues prevent progress
+
+## Options
+
+- `--adversarial` - Use Opus for deeper, more critical analysis
+
+## Example
+
+```bash
+/review 3-5
+/review 3-5 --adversarial
+```

package/.claude/commands/route.md

@@ -23,4 +23,3 @@ Examples:
 - `/route fix authentication timeout` - Routes to bug specialists
 - `/route add payment integration` - Routes to feature team
 - `/route --route-only fix memory leak` - Preview routing only
-

package/.claude/commands/swarm.md

@@ -19,4 +19,3 @@ Examples:
 - `/swarm 3-5` - Run swarm with default agents
 - `/swarm 3-5 --agents ARCHITECT,DEV,REVIEWER,SECURITY` - Custom agents
 - `/swarm 3-5 --max-iter 5` - Increase max iterations
-

package/.claude/commands/validate.md

@@ -0,0 +1,55 @@
+# Validate
+
+Run validation checks on the current story or codebase.
+
+## Usage
+
+```
+/validate [story-key] [options]
+```
+
+## Options
+
+- `--tier 1|2|3|all` - Which validation tier to run
+  - 1: Pre-flight (story exists, budget, dependencies)
+  - 2: Inter-phase (code compiles, lint, transitions)
+  - 3: Post-completion (tests, types, version sync)
+  - all: Run all tiers
+- `--auto-fix` - Attempt automatic fixes for failures
+- `--json` - Output as JSON
+- `--quiet` - Minimal output
+
+## Examples
+
+```bash
+# Run all validation tiers
+/validate 3-5 --tier all
+
+# Run pre-flight checks only
+/validate 3-5 --tier 1
+
+# Run post-completion with auto-fix
+/validate 3-5 --tier 3 --auto-fix
+```
+
+## Prompt
+
+Run the validation loop for story: $ARGUMENTS
+
+Execute the following:
+
+```bash
+python3 tooling/scripts/lib/validation_loop.py --story "$ARGUMENTS" --all
+```
+
+If no story key is provided, run validation on the current codebase state:
+
+```bash
+python3 tooling/scripts/lib/validation_loop.py --tier 3
+```
+
+Report the validation results clearly, including:
+- Which gates passed
+- Which gates failed with reasons
+- Any warnings
+- Suggested fixes if available

package/.claude/hooks/session-notification.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# Session Notification Hook - Captures token usage from Claude Code notifications
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+TRACKER="$PROJECT_DIR/.claude/hooks/session_tracker.py"
+
+# Read notification data from Claude Code
+INPUT=$(cat)
+
+# Try to extract token usage from notification
+# Claude Code may send usage data in various formats
+INPUT_TOKENS=$(echo "$INPUT" | jq -r '
+    .usage.input_tokens //
+    .data.usage.input_tokens //
+    .message.usage.input_tokens //
+    .input_tokens //
+    0
+' 2>/dev/null)
+
+OUTPUT_TOKENS=$(echo "$INPUT" | jq -r '
+    .usage.output_tokens //
+    .data.usage.output_tokens //
+    .message.usage.output_tokens //
+    .output_tokens //
+    0
+' 2>/dev/null)
+
+MODEL=$(echo "$INPUT" | jq -r '
+    .model //
+    .data.model //
+    .message.model //
+    ""
+' 2>/dev/null)
+
+# Only log if we have actual token data
+if [ "$INPUT_TOKENS" -gt 0 ] 2>/dev/null || [ "$OUTPUT_TOKENS" -gt 0 ] 2>/dev/null; then
+    if [ -n "$MODEL" ] && [ "$MODEL" != "null" ]; then
+        python3 "$TRACKER" log --input "$INPUT_TOKENS" --output "$OUTPUT_TOKENS" --model "$MODEL" 2>/dev/null
+    else
+        python3 "$TRACKER" log --input "$INPUT_TOKENS" --output "$OUTPUT_TOKENS" 2>/dev/null
+    fi
+fi
+
+exit 0