@pjmendonca/devflow 1.13.2 → 1.19.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/brainstorm.md

@@ -0,0 +1,28 @@
+---
+description: Run story brainstorming workshop
+argument-hint: [--quick|--journey|--features|--decompose EPIC|--prioritize]
+---
+
+# Brainstorm Command
+
+Run the brainstorm skill for story discovery and backlog creation.
+
+Use the Skill tool to invoke the brainstorm skill with the provided arguments:
+
+```
+skill: brainstorm
+args: $ARGUMENTS
+```
+
+If no arguments provided, run the full workshop mode.
+
+## Quick Reference
+
+| Mode | Time | Description |
+|------|------|-------------|
+| (default) | 30 min | Full workshop: vision, features, journey, decomposition, planning |
+| --quick | 10 min | Vision + 5 key features |
+| --journey | 15 min | Focus on user journey mapping |
+| --features | 15 min | Focus on rapid feature brainstorming |
+| --decompose EPIC | 10 min | Break down an epic into stories |
+| --prioritize | 5 min | Re-prioritize existing backlog |

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,383 @@
+---
+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: Story Discovery (Optional)
+
+Ask if they want to brainstorm initial stories:
+```
+Would you like to brainstorm your first stories now?
+```
+
+Options:
+- **Quick Discovery** (5 min) - Vision and 3-5 key features for sprint 1
+- **Skip for now** - Run `/brainstorm` later for a full workshop session
+
+If they choose Quick Discovery, run through this flow:
+
+**Step 1: Vision (2 questions)**
+
+Use AskUserQuestion with open text:
+```
+What problem are you solving with this project?
+```
+
+Then:
+```
+Who is your primary user? (e.g., "developers", "fitness enthusiasts", "small business owners")
+```
+
+**Step 2: Core Features (1 question)**
+
+```
+What are the 3-5 core features this project needs?
+(Enter as a comma-separated list)
+```
+
+**Step 3: First Sprint Planning**
+
+Based on their answers, propose 3-5 stories for Sprint 1:
+
+```
+Based on your vision, here's a proposed Sprint 1:
+
+1-1-{feature-slug}: {Feature description}
+1-2-{feature-slug}: {Feature description}
+1-3-{feature-slug}: {Feature description}
+
+Would you like to:
+- Accept these stories
+- Modify the list
+- Add more details to each
+```
+
+**Step 4: Generate Story Files**
+
+For each accepted story, create:
+1. Entry in `tooling/docs/sprint-status.yaml`
+2. Story file in `tooling/docs/stories/STORY-{key}.md`
+
+Use the story template from `tooling/docs/templates/story.md`.
+
+Story file example:
+```markdown
+# STORY-1-1-user-login
+
+**Type**: Feature
+**Status**: backlog
+**Sprint**: 1
+**Priority**: P1 (High)
+**Effort**: M
+**Created**: {date}
+
+---
+
+## Summary
+
+{One-line based on user's feature description}
+
+## User Story
+
+As a **{user type from step 1}**,
+I want **{goal extracted from feature}**,
+So that **{benefit based on problem statement}**.
+
+## Acceptance Criteria
+
+- [ ] **AC-1**: {Generated based on feature}
+- [ ] **AC-2**: {Generated based on feature}
+- [ ] **AC-3**: {Generated based on feature}
+```
+
+**Note**: For deeper brainstorming with user journeys, prioritization frameworks, and story decomposition, recommend running `/brainstorm` after setup.
+
+### Phase 5: 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/
+tooling/docs/stories/
+tooling/docs/templates/
+```
+
+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 6: 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}
+- Stories: {story_count} stories in Sprint 1 (if created)
+
+Quick Start:
+1. Brainstorm more stories: /brainstorm
+2. Run full story pipeline: /story 1-1-feature-name
+3. Development only: /develop 1-1-feature-name
+4. Review only: /review 1-1-feature-name
+5. Check costs: /costs
+
+Useful Commands:
+- /brainstorm - Full workshop for story discovery
+- /personalize - Customize agent behavior
+- /memory - View shared agent memory
+- /checkpoint - Save/restore context
+
+Your Stories: tooling/docs/stories/
+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
+- Skip story discovery (recommend `/brainstorm` after setup)
+
+## 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
-