@pjmendonca/devflow 1.13.1 → 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/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