@pjmendonca/devflow 1.13.1 → 1.18.0

package/.claude/hooks/session_tracker.py

@@ -0,0 +1,272 @@
+#!/usr/bin/env python3
+"""
+Session Tracker - Tracks costs for ALL Claude Code sessions.
+
+Called by hooks to track token usage across the entire session lifecycle.
+
+Usage:
+    python session_tracker.py start [--session-id ID]
+    python session_tracker.py log --input TOKENS --output TOKENS [--model MODEL]
+    python session_tracker.py end
+    python session_tracker.py status
+"""
+
+import argparse
+import json
+from datetime import datetime
+from pathlib import Path
+
+# Project paths
+PROJECT_DIR = Path(__file__).parent.parent.parent
+COSTS_DIR = PROJECT_DIR / "tooling" / ".automation" / "costs"
+SESSIONS_DIR = COSTS_DIR / "sessions"
+ACTIVE_SESSION_FILE = COSTS_DIR / ".active_session.json"
+
+# Pricing per 1M tokens (USD) - December 2025
+PRICING = {
+    "claude-opus-4-5-20251101": {"input": 15.00, "output": 75.00},
+    "claude-sonnet-4-20250514": {"input": 3.00, "output": 15.00},
+    "claude-3-5-sonnet-20241022": {"input": 3.00, "output": 15.00},
+    "claude-3-5-haiku-20241022": {"input": 0.80, "output": 4.00},
+    "claude-3-opus-20240229": {"input": 15.00, "output": 75.00},
+    "opus": {"input": 15.00, "output": 75.00},
+    "sonnet": {"input": 3.00, "output": 15.00},
+    "haiku": {"input": 0.80, "output": 4.00},
+}
+
+
+def get_pricing(model: str) -> dict:
+    """Get pricing for a model."""
+    model_lower = model.lower()
+
+    # Direct match
+    if model_lower in PRICING:
+        return PRICING[model_lower]
+
+    # Partial match
+    for key, price in PRICING.items():
+        if key in model_lower or model_lower in key:
+            return price
+
+    # Check for model family
+    if "opus" in model_lower:
+        return PRICING["opus"]
+    elif "sonnet" in model_lower:
+        return PRICING["sonnet"]
+    elif "haiku" in model_lower:
+        return PRICING["haiku"]
+
+    # Default to sonnet pricing
+    return PRICING["sonnet"]
+
+
+def calculate_cost(input_tokens: int, output_tokens: int, model: str) -> float:
+    """Calculate cost in USD."""
+    pricing = get_pricing(model)
+    input_cost = (input_tokens / 1_000_000) * pricing["input"]
+    output_cost = (output_tokens / 1_000_000) * pricing["output"]
+    return input_cost + output_cost
+
+
+def ensure_dirs():
+    """Ensure required directories exist."""
+    COSTS_DIR.mkdir(parents=True, exist_ok=True)
+    SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def start_session(session_id: str = None, model: str = None) -> dict:
+    """Start a new tracking session."""
+    ensure_dirs()
+
+    now = datetime.now()
+    if not session_id:
+        session_id = now.strftime("%Y%m%d_%H%M%S")
+
+    session = {
+        "session_id": session_id,
+        "start_time": now.isoformat(),
+        "end_time": None,
+        "model": model or "unknown",
+        "story_key": None,
+        "entries": [],
+        "totals": {
+            "input_tokens": 0,
+            "output_tokens": 0,
+            "total_tokens": 0,
+            "cost_usd": 0.0,
+        },
+    }
+
+    # Save active session
+    with open(ACTIVE_SESSION_FILE, "w") as f:
+        json.dump(session, f, indent=2)
+
+    return session
+
+
+def get_active_session() -> dict | None:
+    """Get the currently active session."""
+    if not ACTIVE_SESSION_FILE.exists():
+        return None
+
+    try:
+        with open(ACTIVE_SESSION_FILE) as f:
+            return json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def log_usage(input_tokens: int, output_tokens: int, model: str = None) -> dict | None:
+    """Log token usage to the active session."""
+    session = get_active_session()
+
+    if not session:
+        # Auto-start session if none exists
+        session = start_session(model=model)
+
+    # Update model if provided
+    if model and session.get("model") == "unknown":
+        session["model"] = model
+
+    # Use session model for pricing
+    use_model = model or session.get("model", "sonnet")
+    cost = calculate_cost(input_tokens, output_tokens, use_model)
+
+    # Create entry
+    entry = {
+        "timestamp": datetime.now().isoformat(),
+        "model": use_model,
+        "input_tokens": input_tokens,
+        "output_tokens": output_tokens,
+        "cost_usd": cost,
+    }
+
+    session["entries"].append(entry)
+
+    # Update totals
+    session["totals"]["input_tokens"] += input_tokens
+    session["totals"]["output_tokens"] += output_tokens
+    session["totals"]["total_tokens"] += input_tokens + output_tokens
+    session["totals"]["cost_usd"] += cost
+
+    # Save updated session
+    with open(ACTIVE_SESSION_FILE, "w") as f:
+        json.dump(session, f, indent=2)
+
+    return session
+
+
+def end_session() -> dict | None:
+    """End the current session and save to sessions directory."""
+    session = get_active_session()
+
+    if not session:
+        return None
+
+    # Set end time
+    session["end_time"] = datetime.now().isoformat()
+
+    # Only save if there was activity
+    if session["totals"]["total_tokens"] > 0:
+        # Generate filename
+        start_time = datetime.fromisoformat(session["start_time"])
+        filename = f"{start_time.strftime('%Y-%m-%d')}_{session['session_id']}.json"
+        session_file = SESSIONS_DIR / filename
+
+        # Save to sessions directory
+        with open(session_file, "w") as f:
+            json.dump(session, f, indent=2)
+
+    # Remove active session file
+    if ACTIVE_SESSION_FILE.exists():
+        ACTIVE_SESSION_FILE.unlink()
+
+    return session
+
+
+def get_status() -> dict:
+    """Get current session status."""
+    session = get_active_session()
+
+    if not session:
+        return {"active": False, "message": "No active session"}
+
+    totals = session.get("totals", {})
+    return {
+        "active": True,
+        "session_id": session.get("session_id"),
+        "model": session.get("model"),
+        "input_tokens": totals.get("input_tokens", 0),
+        "output_tokens": totals.get("output_tokens", 0),
+        "total_tokens": totals.get("total_tokens", 0),
+        "cost_usd": totals.get("cost_usd", 0.0),
+        "entries_count": len(session.get("entries", [])),
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Session cost tracker")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # Start command
+    start_parser = subparsers.add_parser("start", help="Start a new session")
+    start_parser.add_argument("--session-id", help="Custom session ID")
+    start_parser.add_argument("--model", help="Model name")
+
+    # Log command
+    log_parser = subparsers.add_parser("log", help="Log token usage")
+    log_parser.add_argument("--input", type=int, required=True, help="Input tokens")
+    log_parser.add_argument("--output", type=int, required=True, help="Output tokens")
+    log_parser.add_argument("--model", help="Model name")
+
+    # End command
+    subparsers.add_parser("end", help="End current session")
+
+    # Status command
+    subparsers.add_parser("status", help="Get session status")
+
+    args = parser.parse_args()
+
+    if args.command == "start":
+        session = start_session(args.session_id, args.model)
+        print(json.dumps({"status": "started", "session_id": session["session_id"]}))
+
+    elif args.command == "log":
+        model = getattr(args, "model", None)
+        session = log_usage(args.input, args.output, model)
+        if session:
+            print(
+                json.dumps(
+                    {
+                        "status": "logged",
+                        "total_tokens": session["totals"]["total_tokens"],
+                        "cost_usd": round(session["totals"]["cost_usd"], 4),
+                    }
+                )
+            )
+        else:
+            print(json.dumps({"status": "error", "message": "No active session"}))
+
+    elif args.command == "end":
+        session = end_session()
+        if session:
+            print(
+                json.dumps(
+                    {
+                        "status": "ended",
+                        "total_tokens": session["totals"]["total_tokens"],
+                        "cost_usd": round(session["totals"]["cost_usd"], 4),
+                        "saved": session["totals"]["total_tokens"] > 0,
+                    }
+                )
+            )
+        else:
+            print(json.dumps({"status": "no_session"}))
+
+    elif args.command == "status":
+        status = get_status()
+        print(json.dumps(status))
+
+
+if __name__ == "__main__":
+    main()

package/.claude/settings.json

@@ -0,0 +1,38 @@
+{
+  "statusLine": {
+    "type": "command",
+    "command": "~/.claude/statusline.sh"
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/session-startup.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/session-stop.sh"
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/session-notification.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/.claude/skills/costs/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: costs
+description: View cost dashboard and spending analytics (project)
+---
+
+# Cost Dashboard Skill
+
+Display Devflow cost tracking and spending analytics by reading session data directly.
+
+## Usage
+
+```
+/costs [options]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| --period day | Show today's costs only |
+| --period week | Show this week's costs |
+| --period month | Show this month's costs (default) |
+| --history N | Show last N sessions |
+| --story KEY | Filter by story key |
+
+## Prompt
+
+You are displaying the Devflow cost dashboard.
+
+**Arguments:** $ARGUMENTS
+
+### Step 1: Read Configuration
+
+Read the configuration file:
+- Path: `tooling/.automation/costs/config.json`
+
+This contains:
+- `budget_dev`: Development budget (USD)
+- `subscription_plan`: Current plan (free/pro)
+- `subscription_token_limit`: Monthly token limit
+- `subscription_billing_period_days`: Days in billing period
+- `display_currencies`: Currencies to show
+- `currency_rates`: Exchange rates
+
+### Step 2: Find Session Files
+
+Find all session files:
+- Path pattern: `tooling/.automation/costs/sessions/*.json`
+
+### Step 3: Read and Aggregate Session Data
+
+For each session file, extract:
+- `session_id`: Session identifier
+- `start_time` / `end_time`: Timestamps
+- `story_key`: Associated story (if any)
+- `entries[]`: Array of cost entries with `model`, `input_tokens`, `output_tokens`, `cost_usd`
+- `totals`: Aggregated totals for the session
+
+Identify the most recent session as the "current session".
+
+### Step 4: Calculate Metrics
+
+Calculate:
+1. **Current session tokens/cost**: From the most recent session
+2. **Cumulative tokens**: Sum of all tokens across ALL sessions this billing period
+3. **Cumulative cost**: Sum of all `cost_usd` across ALL sessions
+4. **Cost by model**: Group costs by model (opus, sonnet, haiku)
+5. **Cost by story**: Group costs by story_key
+6. **Budget usage**: (cumulative_cost / budget_dev) * 100
+7. **Subscription usage**: (cumulative_tokens / subscription_token_limit) * 100
+8. **Average cost per session**: cumulative_cost / session_count
+9. **Average tokens per session**: cumulative_tokens / session_count
+10. **Input/output ratio**: total_input_tokens / total_output_tokens
+11. **Days remaining**: Calculate from billing period start
+12. **Projected monthly cost**: (cumulative_cost / days_elapsed) * 30
+13. **Projected token usage**: (cumulative_tokens / days_elapsed) * 30
+
+### Step 5: Apply Filters
+
+Based on $ARGUMENTS:
+- `--period day`: Filter sessions from today only
+- `--period week`: Filter sessions from last 7 days
+- `--period month`: Filter sessions from last 30 days (default)
+- `--history N`: Show only last N sessions
+- `--story KEY`: Filter sessions matching story_key
+
+### Step 6: Format Output
+
+Display the dashboard using this format:
+
+```
+=================================================================
+                    DEVFLOW COST DASHBOARD
+=================================================================
+Plan: [plan] | Tokens: [cumulative]/[limit] ([%]%) | [days] days left
+This Session: $[current_cost] | Cumulative: $[total_cost]
+=================================================================
+
+PERIOD: [period]                        SESSIONS: [count]
+
+--- TOKEN USAGE ---------------------------------------------
+                   This Session         Cumulative
+Input:             [current_in]         [total_in]
+Output:            [current_out]        [total_out]
+Total:             [current_total]      [total_total]
+
+I/O Ratio:         [ratio]:1 (higher = more input-heavy conversations)
+
+--- COST BY MODEL -------------------------------------------
+[model]            $[cost]  ([%]%)  [bar]
+
+--- COST BY STORY -------------------------------------------
+[story-key]        $[cost]  ([%]%)
+(no story)         $[cost]  ([%]%)
+
+--- BUDGET STATUS -------------------------------------------
+Spent:     $[total]  /  $[budget]  ([%]%)
+[================================--------------------] [%]%
+
+[WARNING] if > 75%: "Approaching budget limit!"
+[CRITICAL] if > 90%: "Near budget limit - consider pausing"
+
+--- PROJECTIONS (based on current usage rate) ---------------
+Monthly token projection:    [projected] / [limit] ([%]%)
+Monthly cost projection:     $[projected_cost]
+Avg cost per session:        $[avg_cost]
+Avg tokens per session:      [avg_tokens]
+
+--- RECENT SESSIONS -----------------------------------------
+[session_id]  [date]  [tokens]  $[cost]  [story or "-"]
+[session_id]  [date]  [tokens]  $[cost]  [story or "-"]
+[session_id]  [date]  [tokens]  $[cost]  [story or "-"]
+(show last 5 sessions)
+
+--- CURRENCIES ----------------------------------------------
+$[USD] | E[EUR] | L[GBP] | R$[BRL]
+=================================================================
+```
+
+### Budget Warnings
+
+Display warnings based on config thresholds:
+- If budget usage > `warning_percent` (75%): Show [WARNING]
+- If budget usage > `critical_percent` (90%): Show [CRITICAL]
+- If subscription usage > 80%: Show token limit warning
+
+### Notes
+
+- Format large numbers with K/M suffixes (e.g., 1.5K, 2.3M)
+- Round costs to 2 decimal places
+- Show percentages to 1 decimal place
+- Use text-based progress bars with = and - characters
+- Current session = most recent session file by timestamp
+- Cumulative = sum of ALL sessions in the billing period
+- If no sessions found, display a message indicating no cost data available
+- Calculate days remaining: billing_period_days - days since first session of period

package/.claude/skills/validate/SKILL.md

@@ -0,0 +1,101 @@
+# Validate Skill
+
+Run automated validation checks with feedback loops.
+
+## Description
+
+The validate skill runs a three-tier validation system:
+
+1. **Pre-flight** (Tier 1): Checks before execution
+   - Story file exists
+   - Budget is available
+   - Dependencies are valid
+
+2. **Inter-phase** (Tier 2): Checks between agents
+   - Code compiles/parses
+   - Linting passes
+   - Phase transitions are valid
+
+3. **Post-completion** (Tier 3): Checks after pipeline
+   - Tests pass
+   - Types are valid
+   - Version is synced
+   - Changelog is updated
+
+## Usage
+
+```
+/validate [story-key] [--tier 1|2|3|all] [--auto-fix] [--json]
+```
+
+## Arguments
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| story-key | Story identifier to validate | Current branch |
+| --tier | Validation tier (1, 2, 3, or all) | all |
+| --auto-fix | Attempt automatic fixes | false |
+| --json | Output as JSON | false |
+| --quiet | Minimal output | false |
+
+## Examples
+
+### Run all validations
+```
+/validate 3-5 --tier all
+```
+
+### Run post-completion checks with auto-fix
+```
+/validate --tier 3 --auto-fix
+```
+
+### Get JSON output for CI
+```
+/validate 3-5 --json
+```
+
+## Prompt
+
+You are running validation checks for the Devflow project.
+
+$ARGUMENTS
+
+Execute the validation loop:
+
+```python
+import sys
+sys.path.insert(0, "tooling/scripts/lib")
+
+from validation_loop import (
+    create_validation_loop,
+    run_preflight_validation,
+    run_post_completion_validation,
+    ALL_GATES,
+    LoopContext,
+)
+
+# Parse arguments
+story_key = "$ARGUMENTS".split()[0] if "$ARGUMENTS" else "validation-check"
+tier = "all"  # Default to all tiers
+
+# Create context
+context = LoopContext(story_key=story_key)
+
+# Run appropriate validation
+if tier == "1" or tier == "all":
+    print("[VALIDATION] Running pre-flight checks...")
+    report = run_preflight_validation(story_key)
+    print(report.to_summary())
+
+if tier == "3" or tier == "all":
+    print("[VALIDATION] Running post-completion checks...")
+    report = run_post_completion_validation(story_key)
+    print(report.to_summary())
+```
+
+Report results clearly with:
+- [PASS] for passed gates
+- [WARN] for warnings
+- [FAIL] for failures
+- Suggested fixes when available