ctx-cc 3.1.0 → 3.3.0

package/commands/metrics.md

@@ -0,0 +1,465 @@
+---
+name: metrics
+description: Metrics dashboard - understand AI productivity impact with stories completed, time per story, token usage, and cost analysis.
+---
+
+<objective>
+CTX 3.2 Metrics Dashboard - Comprehensive productivity analytics for understanding AI development impact.
+</objective>
+
+<usage>
+```
+/ctx metrics                   # Show overview dashboard
+/ctx metrics today             # Today's metrics
+/ctx metrics week              # This week's metrics
+/ctx metrics month             # This month's metrics
+/ctx metrics story [id]        # Specific story metrics
+/ctx metrics cost              # Cost analysis
+/ctx metrics export            # Export dashboard HTML
+```
+</usage>
+
+<metrics_structure>
+
+## Data Sources
+
+Metrics are derived from:
+- `.ctx/audit/` - Action logs
+- `.ctx/STATE.md` - Current progress
+- `git log` - Commit history
+- `.ctx/phases/` - Story/task data
+
+## Metrics Directory
+
+```
+.ctx/metrics/
+├── daily/
+│   ├── 2024-01-20.json
+│   └── ...
+├── aggregates/
+│   ├── weekly.json
+│   └── monthly.json
+├── dashboard.html              # Local web view
+└── metrics-config.json
+```
+
+</metrics_structure>
+
+<core_metrics>
+
+## Productivity Metrics
+
+### Stories Per Day/Week
+```json
+{
+  "metric": "stories_completed",
+  "period": "week",
+  "value": 8,
+  "trend": "+2 vs last week",
+  "breakdown": {
+    "Mon": 2,
+    "Tue": 1,
+    "Wed": 2,
+    "Thu": 1,
+    "Fri": 2
+  }
+}
+```
+
+### Average Time Per Story
+```json
+{
+  "metric": "time_per_story",
+  "period": "week",
+  "average": "1h 45m",
+  "median": "1h 30m",
+  "range": {
+    "min": "30m",
+    "max": "4h 15m"
+  },
+  "trend": "-15m vs last week"
+}
+```
+
+### Debug Loop Frequency
+```json
+{
+  "metric": "debug_frequency",
+  "period": "week",
+  "total": 12,
+  "avgAttemptsPerLoop": 2.3,
+  "successRate": "92%",
+  "avgResolutionTime": "8m",
+  "topCauses": [
+    {"cause": "Type errors", "count": 5},
+    {"cause": "Import issues", "count": 3},
+    {"cause": "Logic bugs", "count": 4}
+  ]
+}
+```
+
+### Verification Success Rate
+```json
+{
+  "metric": "verification_success",
+  "period": "week",
+  "firstPassSuccess": "78%",
+  "overallSuccess": "96%",
+  "avgAttempts": 1.3,
+  "commonFailures": [
+    {"type": "Missing error handling", "count": 4},
+    {"type": "Empty catch blocks", "count": 2},
+    {"type": "TODO comments", "count": 3}
+  ]
+}
+```
+
+</core_metrics>
+
+<cost_metrics>
+
+## Token Usage
+
+```json
+{
+  "metric": "token_usage",
+  "period": "week",
+  "total": {
+    "input": 750000,
+    "output": 225000,
+    "combined": 975000
+  },
+  "byPhase": {
+    "research": {"input": 150000, "output": 45000},
+    "planning": {"input": 100000, "output": 30000},
+    "execution": {"input": 350000, "output": 105000},
+    "verification": {"input": 100000, "output": 30000},
+    "debugging": {"input": 50000, "output": 15000}
+  },
+  "byModel": {
+    "opus": {"tokens": 250000, "percentage": "26%"},
+    "sonnet": {"tokens": 600000, "percentage": "62%"},
+    "haiku": {"tokens": 125000, "percentage": "12%"}
+  }
+}
+```
+
+## Cost Analysis
+
+```json
+{
+  "metric": "cost",
+  "period": "week",
+  "total": 4.87,
+  "currency": "USD",
+  "byDay": {
+    "Mon": 1.20,
+    "Tue": 0.85,
+    "Wed": 1.10,
+    "Thu": 0.92,
+    "Fri": 0.80
+  },
+  "byPhase": {
+    "research": 1.20,
+    "planning": 0.80,
+    "execution": 2.10,
+    "verification": 0.50,
+    "debugging": 0.27
+  },
+  "perStory": {
+    "average": 0.61,
+    "min": 0.15,
+    "max": 1.85
+  },
+  "trend": "-12% vs last week",
+  "savings": {
+    "vsQualityProfile": "2.45 (saved 50%)",
+    "vsBudgetProfile": "-1.20 (spent 25% more)"
+  }
+}
+```
+
+## ROI Analysis
+
+```json
+{
+  "metric": "roi",
+  "period": "week",
+  "storiesCompleted": 8,
+  "estimatedManualHours": 32,
+  "actualAIHours": 8,
+  "timeSaved": "24h",
+  "costSaved": {
+    "atDevRate": 150,
+    "aiCost": 4.87,
+    "netSavings": 145.13,
+    "roiMultiple": "30x"
+  }
+}
+```
+
+</cost_metrics>
+
+<quality_metrics>
+
+## Code Quality
+
+```json
+{
+  "metric": "code_quality",
+  "period": "week",
+  "linesOfCode": {
+    "added": 1250,
+    "removed": 340,
+    "net": 910
+  },
+  "commits": 45,
+  "avgCommitSize": 28,
+  "reviewerBlocks": {
+    "critical": 0,
+    "high": 2,
+    "medium": 8,
+    "resolved": "100%"
+  },
+  "testCoverage": {
+    "before": "72%",
+    "after": "78%",
+    "change": "+6%"
+  }
+}
+```
+
+## Human Intervention Rate
+
+```json
+{
+  "metric": "human_intervention",
+  "period": "week",
+  "autoHandled": 95,
+  "userDecisions": 5,
+  "total": 100,
+  "autoRate": "95%",
+  "interventionTypes": [
+    {"type": "Architectural decision", "count": 3},
+    {"type": "Scope clarification", "count": 2}
+  ]
+}
+```
+
+</quality_metrics>
+
+<dashboard_output>
+
+## Terminal Dashboard
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║                     CTX METRICS DASHBOARD                         ║
+║                        Week 3, 2024                               ║
+╠══════════════════════════════════════════════════════════════════╣
+║                                                                   ║
+║  PRODUCTIVITY                          COST                       ║
+║  ─────────────                         ────                       ║
+║  Stories/Week:    8  (+2)              Total:      $4.87 (-12%)  ║
+║  Time/Story:      1h 45m (-15m)        Per Story:  $0.61         ║
+║  Debug Loops:     12 (92% resolved)    Tokens:     975K          ║
+║  Verify Success:  78% first pass                                  ║
+║                                                                   ║
+║  ┌──────────────────────────────────────────────────────────┐    ║
+║  │ Stories Completed by Day                                  │    ║
+║  │                                                           │    ║
+║  │  ██                                                       │    ║
+║  │  ██  ██        ██                                         │    ║
+║  │  ██  ██  █     ██  ██                                     │    ║
+║  │  ──────────────────────                                   │    ║
+║  │  Mon Tue Wed Thu Fri                                      │    ║
+║  └──────────────────────────────────────────────────────────┘    ║
+║                                                                   ║
+║  TOKEN USAGE BY MODEL              COST BY PHASE                  ║
+║  ────────────────────              ──────────────                 ║
+║  Opus:   250K (26%) ████           Research:  $1.20 ████         ║
+║  Sonnet: 600K (62%) █████████      Planning:  $0.80 ███          ║
+║  Haiku:  125K (12%) ██             Execution: $2.10 ███████      ║
+║                                    Verify:    $0.50 ██           ║
+║                                    Debug:     $0.27 █            ║
+║                                                                   ║
+║  ROI SUMMARY                                                      ║
+║  ───────────                                                      ║
+║  Time Saved:     24 hours                                         ║
+║  Cost Saved:     $145.13                                          ║
+║  ROI Multiple:   30x                                              ║
+║                                                                   ║
+╚══════════════════════════════════════════════════════════════════╝
+```
+
+## Story Metrics
+
+```
+[METRICS] Story S001: User Authentication
+
+Duration:    2h 15m
+Tasks:       5
+Commits:     8
+Cost:        $0.85
+
+Phases:
+  Research:    15m  ($0.15)  ████
+  Discussion:  20m  ($0.10)  █████
+  Planning:    10m  ($0.08)  ███
+  Execution:   1h 15m ($0.45) ████████████████
+  Verification: 15m  ($0.07) ████
+
+Debug Loops: 2
+  - Type error in auth.ts (resolved in 3m)
+  - Missing import (resolved in 2m)
+
+Verification: Passed on 2nd attempt
+  - First: Missing error handling
+  - Fixed: Added try/catch
+
+Files Modified: 8
+Lines Added: 245
+Lines Removed: 12
+```
+
+## Cost Dashboard
+
+```
+[METRICS] Cost Analysis - January 2024
+
+Total Spend: $42.50
+
+By Week:
+  W1: $12.30 ████████████
+  W2: $10.85 ██████████
+  W3:  $9.75 █████████
+  W4:  $9.60 █████████
+       └── Trend: -22% (improving efficiency)
+
+By Phase:
+  Research:     $8.50 (20%)
+  Planning:     $5.10 (12%)
+  Execution:   $21.25 (50%)
+  Verification: $4.25 (10%)
+  Debugging:    $3.40 (8%)
+
+By Model:
+  Opus:   $18.70 (44%) - Critical decisions
+  Sonnet: $19.55 (46%) - Most work
+  Haiku:   $4.25 (10%) - Quick tasks
+
+Efficiency:
+  Stories: 32
+  Cost/Story: $1.33
+  Time Saved: ~96 hours
+  ROI: 115x
+```
+
+</dashboard_output>
+
+<html_dashboard>
+
+## Export to HTML
+
+`/ctx metrics export` generates `.ctx/metrics/dashboard.html`:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>CTX Metrics Dashboard</title>
+  <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
+  <style>
+    /* Clean, modern dashboard styling */
+  </style>
+</head>
+<body>
+  <div class="dashboard">
+    <header>
+      <h1>CTX Metrics Dashboard</h1>
+      <span class="period">January 2024</span>
+    </header>
+
+    <div class="metrics-grid">
+      <div class="metric-card">
+        <h3>Stories Completed</h3>
+        <div class="value">32</div>
+        <div class="trend positive">+8 vs last month</div>
+      </div>
+      <!-- More metric cards -->
+    </div>
+
+    <div class="charts">
+      <canvas id="storiesChart"></canvas>
+      <canvas id="costChart"></canvas>
+      <canvas id="tokenChart"></canvas>
+    </div>
+  </div>
+
+  <script>
+    // Chart.js configurations
+  </script>
+</body>
+</html>
+```
+
+Open with: `open .ctx/metrics/dashboard.html`
+
+</html_dashboard>
+
+<configuration>
+
+## Metrics Settings
+
+`.ctx/metrics/metrics-config.json`:
+```json
+{
+  "enabled": true,
+  "collection": {
+    "tokens": true,
+    "costs": true,
+    "timing": true,
+    "quality": true
+  },
+  "aggregation": {
+    "daily": true,
+    "weekly": true,
+    "monthly": true
+  },
+  "costRates": {
+    "opus": {"input": 0.015, "output": 0.075},
+    "sonnet": {"input": 0.003, "output": 0.015},
+    "haiku": {"input": 0.00025, "output": 0.00125}
+  },
+  "roi": {
+    "developerHourlyRate": 150,
+    "hoursPerStoryManual": 4
+  },
+  "alerts": {
+    "dailyCostThreshold": 10,
+    "weeklyStoriesTarget": 10,
+    "verificationSuccessTarget": 80
+  },
+  "export": {
+    "format": "html",
+    "includeCharts": true,
+    "autoExport": false
+  }
+}
+```
+
+</configuration>
+
+<output_format>
+```
+[METRICS] {period}
+
+{summary_stats}
+
+{visualizations}
+
+{insights}
+
+Export: /ctx metrics export
+```
+</output_format>

package/commands/milestone.md

@@ -0,0 +1,264 @@
+---
+name: milestone
+description: Milestone workflow - list, audit, complete, and start new milestones for release management.
+---
+
+<objective>
+CTX 3.2 Milestone Workflow - Full release management with audit, archive, and git tagging.
+</objective>
+
+<usage>
+```
+/ctx milestone                  # Show current milestone status
+/ctx milestone list             # List all milestones
+/ctx milestone audit            # Verify current milestone complete
+/ctx milestone complete         # Archive and tag release
+/ctx milestone new [name]       # Start next version
+```
+</usage>
+
+<workflow>
+
+## Step 0: Parse Subcommand
+
+Extract subcommand from args:
+- No args or "status" → Show Status
+- "list" → List All
+- "audit" → Audit Current
+- "complete" → Complete & Archive
+- "new [name]" → Start New
+
+## Step 1: Show Status (default)
+
+Read STATE.md and show:
+```
+[MILESTONE] v1.0.0 - "Initial Release"
+
+Phases:
+  ✓ Phase 1: Authentication (3/3 stories)
+  ✓ Phase 2: Dashboard (5/5 stories)
+  → Phase 3: API Integration (2/4 stories)
+  ○ Phase 4: Polish (0/2 stories)
+
+Progress: 10/14 stories (71%)
+Started: 2024-01-01
+Estimated: 2024-01-20
+```
+
+## Step 2: List All Milestones
+
+Read `.ctx/milestones/` directory:
+```
+[MILESTONES]
+
+Active:
+  → v1.0.0 "Initial Release" (71% complete)
+
+Archived:
+  ✓ v0.5.0 "Beta" (2024-01-01) - git tag: v0.5.0
+  ✓ v0.4.0 "Alpha" (2023-12-15) - git tag: v0.4.0
+```
+
+## Step 3: Audit Current Milestone
+
+Spawn ctx-verifier to check all stories:
+
+```
+[AUDIT] v1.0.0
+
+Phase 1: Authentication
+  ✓ S001: User registration
+  ✓ S002: User login
+  ✓ S003: Password reset
+
+Phase 2: Dashboard
+  ✓ S004: Dashboard layout
+  ✓ S005: Charts component
+  ⚠ S006: Data export (missing error handling)
+  ✓ S007: Filters
+  ✓ S008: Pagination
+
+Phase 3: API Integration
+  ✓ S009: REST endpoints
+  ✗ S010: Webhooks (not implemented)
+  → S011: Rate limiting (in progress)
+  ○ S012: Documentation
+
+Phase 4: Polish
+  ○ S013: Performance
+  ○ S014: Accessibility
+
+[RESULT] NOT READY
+  - 2 stories incomplete
+  - 1 story has issues
+
+Run `/ctx milestone gaps` to create fix phases.
+```
+
+## Step 4: Complete Milestone
+
+Only if audit passes:
+
+1. **Archive State**
+```bash
+mkdir -p .ctx/archive/v1.0.0
+cp -r .ctx/phases .ctx/archive/v1.0.0/
+cp .ctx/STATE.md .ctx/archive/v1.0.0/
+cp .ctx/PRD.json .ctx/archive/v1.0.0/
+```
+
+2. **Create Git Tag**
+```bash
+git tag -a v1.0.0 -m "CTX Milestone: v1.0.0 - Initial Release
+
+Stories completed: 14
+Phases: 4
+Duration: 20 days
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+
+git push origin v1.0.0
+```
+
+3. **Update Milestone Record**
+```json
+{
+  "version": "1.0.0",
+  "name": "Initial Release",
+  "completedAt": "2024-01-20T15:30:00Z",
+  "gitTag": "v1.0.0",
+  "stats": {
+    "phases": 4,
+    "stories": 14,
+    "commits": 47,
+    "duration": "20d"
+  }
+}
+```
+
+4. **Output**
+```
+[COMPLETE] v1.0.0 archived successfully
+
+Archive: .ctx/archive/v1.0.0/
+Git tag: v1.0.0
+Duration: 20 days
+Stories: 14
+
+Ready to start next milestone with `/ctx milestone new`
+```
+
+## Step 5: Start New Milestone
+
+```
+/ctx milestone new v1.1.0 "Feature Expansion"
+```
+
+1. **Create Milestone Directory**
+```
+.ctx/milestones/v1.1.0/
+├── MILESTONE.json
+└── phases/
+```
+
+2. **Initialize MILESTONE.json**
+```json
+{
+  "version": "1.1.0",
+  "name": "Feature Expansion",
+  "createdAt": "2024-01-21T09:00:00Z",
+  "status": "active",
+  "phases": [],
+  "previousMilestone": "v1.0.0"
+}
+```
+
+3. **Reset STATE.md**
+```markdown
+# CTX State
+
+## Current
+- **Milestone**: v1.1.0 - Feature Expansion
+- **Status**: initializing
+- **Phase**: None
+
+## Context
+- Started: 2024-01-21
+- Previous: v1.0.0 (archived)
+```
+
+4. **Output**
+```
+[NEW] Milestone v1.1.0 "Feature Expansion" created
+
+Previous: v1.0.0 (archived at .ctx/archive/v1.0.0/)
+Status: initializing
+
+Next steps:
+1. Define phases with `/ctx phase add "goal"`
+2. Or use `/ctx` to start with research
+```
+
+## Step 6: Generate Gap Phases
+
+If audit fails, offer to create fix phases:
+
+```
+/ctx milestone gaps
+```
+
+Analyzes audit failures and creates:
+```
+[GAPS] Creating fix phases for v1.0.0
+
+Phase 4.1: Fix S006 error handling
+  - Add try/catch to export function
+  - Add user feedback on failure
+
+Phase 4.2: Implement S010 webhooks
+  - Create webhook endpoints
+  - Add signature validation
+  - Test with external service
+
+Phase 4.3: Complete S011 rate limiting
+  - Finish middleware implementation
+  - Add Redis backend
+
+Add these phases? [Y/n]
+```
+
+</workflow>
+
+<state_updates>
+After any milestone action, update STATE.md:
+
+```markdown
+## Milestone
+- **Current**: v1.0.0
+- **Status**: active | auditing | completing | archived
+- **Progress**: 10/14 (71%)
+- **Last Audit**: 2024-01-20 (FAILED: 2 incomplete)
+```
+</state_updates>
+
+<integration>
+If issue tracker integration enabled:
+
+**On Complete**:
+- Close all stories in Linear/Jira
+- Create release in GitHub
+- Post to Slack channel
+
+**On Gaps**:
+- Create issues for gap phases
+- Link to milestone epic
+</integration>
+
+<output_format>
+```
+[MILESTONE] {action}
+{details}
+
+{next_steps}
+```
+</output_format>