agileflow 2.77.0 → 2.79.0

package/src/core/commands/tests.md

@@ -1,6 +1,22 @@
 ---
 description: Set up automated testing infrastructure
 argument-hint: (no arguments)
+compact_context:
+  priority: high
+  preserve_rules:
+    - "Auto-detect language/runtime and testing framework (Node.js→Jest, Python→pytest, Ruby→RSpec, etc.)"
+    - "MUST use TodoWrite to track all 10 steps (detect, check existing, install, config, examples, structure, scripts, CI, docs, run)"
+    - "Always show diff-first preview before creating files"
+    - "Create working example tests (unit, integration, E2E if requested) - not just config"
+    - "Set reasonable coverage thresholds (70%, not 100%)"
+    - "Integrate with CI immediately (.github/workflows/ci.yml update)"
+    - "Create docs/02-practices/testing.md documentation"
+    - "Run test suite after setup to verify it works"
+  state_fields:
+    - framework_detected
+    - example_tests_created
+    - ci_integrated
+    - coverage_threshold_set
 ---
 
 # setup-tests
@@ -18,76 +34,18 @@ node .agileflow/scripts/obtain-context.js tests
 ---
 
 <!-- COMPACT_SUMMARY_START -->
-## Compact Summary
 
-**Purpose**: Test Infrastructure Bootstrapper - Automatically set up testing framework, config, example tests, and CI integration
+## ⚠️ COMPACT SUMMARY - /agileflow:setup-tests IS ACTIVE
 
-**Role**: Test Infrastructure Bootstrapper responsible for detecting project type and installing appropriate testing framework
+**CRITICAL**: You are bootstrapping test infrastructure. All 10 steps must complete to have working test suite.
 
-**Critical Rules**:
-- MUST use TodoWrite to track all 10 steps (detect language, check existing setup, install deps, create config, create examples, create structure, add scripts, integrate CI, create docs, run tests)
-- MUST preview all changes (diff-first, YES/NO)
-- MUST create working examples, not just config
-- MUST run test suite after setup to verify
-- MUST integrate with CI immediately
-- Set reasonable coverage thresholds (70%, not 100%)
-- Create docs/02-practices/testing.md documentation
+**ROLE**: Test Infrastructure Bootstrapper - Auto-detect language, install framework, create examples, integrate CI
 
-**Inputs** (optional):
-- FRAMEWORK=auto|jest|mocha|pytest|rspec|go-test|cargo-test (default: auto-detect)
-- COVERAGE=yes|no (default: yes)
-- E2E=yes|no (default: no, ask if needed)
-
-**Project Detection**:
-- Node.js: package.json → Jest/Mocha
-- Python: requirements.txt, pyproject.toml → pytest
-- Ruby: Gemfile → RSpec
-- Go: go.mod → go test
-- Rust: Cargo.toml → cargo test
-- Java: pom.xml, build.gradle → JUnit
-- .NET: *.csproj → xUnit/NUnit
+---
 
-**Directory Structure Created**:
-```
-tests/
-├── unit/           # Unit tests (isolated functions/classes)
-├── integration/    # Integration tests (multiple components)
-├── e2e/           # End-to-end tests (full user flows) [if E2E=yes]
-├── fixtures/      # Test data
-└── helpers/       # Test utilities
-```
+### 🚨 RULE #1: ALWAYS USE TodoWrite FOR 10 STEPS
 
-**Workflow Steps**:
-1. Detect language/runtime and framework
-2. Check existing test setup
-3. Install testing framework dependencies
-4. Create test configuration files (jest.config.js, pytest.ini, etc.)
-5. Create example tests (unit, integration, E2E if requested)
-6. Create test directory structure
-7. Add test scripts to package.json/equivalent
-8. Integrate with CI workflow (.github/workflows/ci.yml)
-9. Create docs/02-practices/testing.md documentation
-10. Run tests to verify setup
-
-**Output Files**:
-- Config: jest.config.js / pytest.ini / .rspec / etc.
-- Examples: tests/unit/example.test.ts, tests/integration/api.test.ts
-- CI: .github/workflows/ci.yml (test job added)
-- Docs: docs/02-practices/testing.md
-- Scripts: package.json updated with test commands
-
-**Success Criteria**:
-- All 10 todo items marked complete
-- Test framework installed and configured
-- Example tests created and passing
-- CI integration added
-- Documentation created
-- User confirmed via YES/NO prompt
-
-**Tools Used**:
-- TodoWrite: Track 10-step test infrastructure setup
-
-**TodoWrite Example**:
+Track all steps explicitly:
 ```xml
 <invoke name="TodoWrite">
 <parameter name="content">
@@ -106,6 +64,210 @@ tests/
 </invoke>
 ```
 
+Mark each step complete. This ensures comprehensive setup.
+
+---
+
+### 🚨 RULE #2: FRAMEWORK AUTO-DETECTION
+
+Detect from manifest files:
+- **Node.js**: package.json → **Jest** (or Mocha if configured)
+- **Python**: requirements.txt/pyproject.toml → **pytest**
+- **Ruby**: Gemfile → **RSpec**
+- **Go**: go.mod → **go test**
+- **Rust**: Cargo.toml → **cargo test**
+- **Java**: pom.xml/build.gradle → **JUnit**
+- **.NET**: *.csproj → **xUnit/NUnit**
+
+If unclear, ask: "Detected Node.js. Use Jest?"
+
+---
+
+### 🚨 RULE #3: WORKING EXAMPLES, NOT JUST CONFIG
+
+**NEVER** create config without example tests:
+- Create `tests/unit/example.test.ts` (passes immediately)
+- Create `tests/integration/api.test.ts` (passes immediately)
+- Create `tests/e2e/flow.spec.ts` (only if E2E=yes)
+
+Examples MUST pass on first run:
+```typescript
+describe('Example Test Suite', () => {
+  it('should pass this example test', () => {
+    expect(true).toBe(true);
+  });
+});
+```
+
+---
+
+### 🚨 RULE #4: COVERAGE THRESHOLD
+
+Always set REASONABLE thresholds (not perfectionistic):
+
+```javascript
+coverageThreshold: {
+  global: {
+    branches: 70,      // Don't require 100%
+    functions: 70,     // Realistic goals
+    lines: 70,
+    statements: 70
+  }
+}
+```
+
+Don't enforce >80% initially. Users will increase over time.
+
+---
+
+### 🚨 RULE #5: CI INTEGRATION MANDATORY
+
+Always update/create `.github/workflows/ci.yml` with test job:
+
+```yaml
+test:
+  runs-on: ubuntu-latest
+  steps:
+    - uses: actions/checkout@v4
+    - run: npm install
+    - run: npm test -- --coverage
+    - uses: codecov/codecov-action@v3
+```
+
+If .github/workflows/ci.yml exists, add test job. Don't replace.
+
+---
+
+### 🚨 RULE #6: DIFF-FIRST PATTERN
+
+Always show preview:
+
+```
+Will set up testing for: Node.js (Jest)
+
+Will create:
+✓ jest.config.js (test configuration)
+✓ tests/unit/example.test.ts (example unit test)
+✓ tests/integration/api.test.ts (example integration test)
+✓ tests/fixtures/ directory
+✓ Update .github/workflows/ci.yml
+
+Will install:
+✓ jest @types/jest ts-jest
+
+Proceed? (YES/NO)
+```
+
+Then ask: "Proceed with test setup? (YES/NO)"
+
+---
+
+### ANTI-PATTERNS (DON'T DO THESE)
+
+❌ Create jest.config.js but no example tests
+❌ Set coverage threshold to 100%
+❌ Forget to integrate with CI
+❌ Skip running tests after setup
+❌ Create config without docs
+❌ Hardcode framework (don't auto-detect)
+
+### DO THESE INSTEAD
+
+✅ Create config AND working example tests
+✅ Set realistic thresholds (70%)
+✅ Add test job to CI immediately
+✅ Run tests after setup to verify
+✅ Create docs/02-practices/testing.md
+✅ Auto-detect language/framework first
+
+---
+
+### WORKFLOW PHASES
+
+**Phase 1: Detection (Steps 1-2)**
+- Scan for package.json, Gemfile, go.mod, etc.
+- Detect language/runtime
+- Check if tests already exist
+
+**Phase 2: Installation (Step 3)**
+- Install framework deps (jest, pytest, etc.)
+- Install coverage tools if needed
+
+**Phase 3: Configuration (Step 4)**
+- Create config file (jest.config.js, pytest.ini, etc.)
+- Set coverage thresholds (70%)
+
+**Phase 4: Examples (Steps 5-6)**
+- Create working example tests
+- Create test directory structure
+
+**Phase 5: Integration (Steps 7-8)**
+- Add test scripts to package.json
+- Add test job to CI workflow
+
+**Phase 6: Documentation (Step 9)**
+- Create docs/02-practices/testing.md
+
+**Phase 7: Verification (Step 10)**
+- Run tests to verify everything works
+- Show test output
+
+---
+
+### OUTPUT STRUCTURE
+
+Always create:
+```
+tests/
+├── unit/           # Fast, isolated tests
+├── integration/    # Slower, multi-component tests
+├── e2e/           # Slow, full-flow tests (if E2E=yes)
+├── fixtures/      # Test data files
+└── helpers/       # Test utilities (mocks, factories)
+```
+
+---
+
+### SCRIPTS TO ADD
+
+```json
+{
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "test:unit": "jest tests/unit",
+    "test:integration": "jest tests/integration",
+    "test:e2e": "playwright test"
+  }
+}
+```
+
+---
+
+### KEY FILES TO REMEMBER
+
+| File | Purpose |
+|------|---------|
+| `jest.config.js` (or equivalent) | Test framework configuration |
+| `tests/unit/example.test.ts` | Working example test |
+| `docs/02-practices/testing.md` | How to write and run tests |
+| `.github/workflows/ci.yml` | CI test job |
+| `.gitignore` entry | Exclude coverage/ from git |
+
+---
+
+### REMEMBER AFTER COMPACTION
+
+- `/agileflow:setup-tests` IS ACTIVE - bootstrap test infrastructure
+- Auto-detect language/framework (Node.js→Jest, Python→pytest, etc.)
+- ALWAYS create working example tests (not just config)
+- Set reasonable coverage (70%, not 100%)
+- Run tests after setup to verify they pass
+- Use TodoWrite to track 10 steps
+- Integrate with CI immediately
+- Create docs/02-practices/testing.md
+
 <!-- COMPACT_SUMMARY_END -->
 
 ## Prompt

package/src/core/commands/update.md

@@ -1,6 +1,22 @@
 ---
 description: Generate stakeholder progress report
-argument-hint: (no arguments)
+argument-hint: [PERIOD=week|sprint|month|quarter] [AUDIENCE=exec|client|team|board] [FORMAT=email|markdown]
+compact_context:
+  priority: high
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:stakeholder-update - Stakeholder communication generator"
+    - "CRITICAL: Aggregate data from 10 sources (status, epics, stories, roadmap, risks, git, bus, ADRs, milestones, releases)"
+    - "CRITICAL: PREVIEW before sending (diff-first, YES/NO/EDIT)"
+    - "CRITICAL: Always HONEST about blockers and risks (never hide problems)"
+    - "MUST focus on business value, not technical jargon (for exec/client audiences)"
+    - "MUST save all updates to docs/08-project/updates/ for historical record"
+    - "MUST include specific metrics with trends (velocity, coverage, bugs, test coverage)"
+    - "Update structure: Executive Summary | Progress | Upcoming | Metrics | Blockers | Decisions | Resources"
+  state_fields:
+    - period
+    - audience
+    - format
+    - date_range
 ---
 
 # stakeholder-update

package/src/core/commands/validate-expertise.md

@@ -2,6 +2,22 @@
 description: Validate expertise files for drift and staleness
 argument-hint: "[DOMAIN]"
 model: haiku
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "DOMAIN is OPTIONAL - if not provided, validate ALL expertise files"
+    - "Run 4 validation checks: file path drift, stale learnings, file size, required sections"
+    - "File Path Drift CRITICAL - detect referenced files that no longer exist"
+    - "Stale Learnings - flag expertise not updated in 30+ days"
+    - "File Size Check - warn if expertise.yaml exceeds 200 lines"
+    - "Required Sections - verify domain, mental_models, learnings, key_files, patterns"
+    - "Non-destructive (read-only) - report issues but don't auto-fix"
+    - "Prioritize drift detection (most critical issue)"
+  state_fields:
+    - domain_filter
+    - total_checks
+    - pass_count
+    - fail_count
 ---
 
 # validate-expertise

package/src/core/commands/velocity.md

@@ -1,7 +1,23 @@
 ---
 description: Track velocity and forecast sprint capacity
-argument-hint: (no arguments)
+argument-hint: "[PERIOD=week|sprint|month|all] [FORECAST=<epic-id>] [FORMAT=report|chart|json]"
 model: haiku
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:velocity - Velocity analyst and forecaster (read-only)"
+    - "MUST read docs/09-agents/bus/log.jsonl (parse done status changes with timestamps)"
+    - "MUST read docs/06-stories/**/US-*.md for estimates (frontmatter)"
+    - "MUST calculate over 3+ time periods for reliability"
+    - "MUST warn if sample size <5 stories (unreliable forecast)"
+    - "MUST exclude outliers (>3x average) from velocity calc"
+    - "MUST save velocity history to docs/08-project/velocity/"
+    - "MUST show trend analysis (↗ ↘ →) with % change"
+  state_fields:
+    - current_velocity
+    - trend_pct
+    - period
+    - sample_size
 ---
 
 # velocity
@@ -21,54 +37,142 @@ This gathers git status, stories/epics, session state, and registers for PreComp
 ---
 
 <!-- COMPACT_SUMMARY_START -->
-## Compact Summary
 
-**Purpose**: Velocity Analyst & Forecaster - Calculate team velocity, identify trends, forecast epic/milestone completion
+## ⚠️ COMPACT SUMMARY - /agileflow:velocity IS ACTIVE
 
-**Role**: Track story completion velocity and predict delivery timelines
+**CRITICAL**: You are the Velocity Analyst. This command analyzes team productivity trends (read-only).
 
-**Critical Rules**:
-- Parse bus/log.jsonl for "done" status changes (JSON parsing required)
-- Match stories to estimates from frontmatter (YAML front matter)
-- Calculate over at least 3 time periods (for reliability)
-- Warn if sample size <5 stories
-- Exclude outliers (stories >3x avg) from velocity calc
-- Save velocity history to docs/08-project/velocity/
+---
+
+### 🚨 RULE #1: ALWAYS Parse bus/log.jsonl for Completions
+
+Extract "done" status changes:
+1. Read docs/09-agents/bus/log.jsonl
+2. Find entries with type="status" and status="done"
+3. Extract timestamps and story IDs
+4. Match to story files for estimates (frontmatter)
+5. Group by time period (week/sprint/month)
+6. Calculate velocity per period
+
+### 🚨 RULE #2: ALWAYS Calculate Over 3+ Time Periods
 
-**Inputs** (optional):
-- `PERIOD`: week|sprint|month|all (default: sprint)
-- `FORECAST`: <EPIC_ID> (predict completion date)
-- `FORMAT`: report|chart|json (default: report)
+- Minimum 3 periods for trend reliability
+- Warn if sample size <5 stories (unreliable)
+- Exclude outliers >3x average from calc
+- Show moving average trend (↗ ↘ →)
 
-**Data Sources**:
-1. docs/09-agents/bus/log.jsonl - "done" status changes with timestamps
+### 🚨 RULE #3: ALWAYS Show Confidence Levels
+
+Confidence = 100% - (StdDev / Velocity Avg) * 100
+- >80% = High confidence (stable velocity)
+- 60-80% = Medium confidence (some variance)
+- <60% = Low confidence (unreliable, don't forecast)
+
+### 🚨 RULE #4: ALWAYS Save History
+
+Save velocity reports to:
+- docs/08-project/velocity/velocity-YYYYMMDD.md
+- Track trends over time for capacity planning
+
+---
+
+## Key Files & Data
+
+**Input Parameters** (all optional):
+```
+PERIOD=week|sprint|month|all    # Time grouping (default: sprint)
+FORECAST=<EPIC_ID>               # Predict epic completion date
+FORMAT=report|chart|json          # Output format (default: report)
+```
+
+**Data Sources** (read-only):
+1. docs/09-agents/bus/log.jsonl - Completion events with timestamps
 2. docs/06-stories/**/US-*.md - Story estimates (frontmatter)
-3. docs/05-epics/*.md - Epic definitions
+3. docs/05-epics/*.md - Epic totals
 4. docs/08-project/milestones.md - Milestone targets
 
-**Key Formulas**:
-- Velocity = Total points completed / Number of time periods
-- Days to complete = (Remaining points / Velocity) * 7
-- Confidence = 100% - (Std Dev / Velocity Avg) * 100
+---
 
-**Workflow**:
-1. Parse bus/log.jsonl → Extract "done" status changes with timestamps
-2. Match stories to frontmatter estimates → Convert to points (1d = 1pt)
-3. Group by time period (week/sprint) → Calculate velocity stats
-4. If FORECAST: Calculate remaining points → Forecast completion date
-5. Render report/chart → Generate recommendations
-6. Save to docs/08-project/velocity/velocity-YYYYMMDD.md
+## Key Calculations
 
-**Example Usage**:
-```bash
-/agileflow:velocity
-/agileflow:velocity PERIOD=month FORECAST=EP-0010
-/agileflow:velocity FORMAT=json
+**Velocity Formula**:
+```
+Velocity = Total points completed / Number of periods
+Points = story estimate converted to days (1d = 1 point)
+```
+
+**Forecast Formula**:
 ```
+Days to complete = (Remaining points / Velocity) * 7
+Completion date = Today + Days to complete
+```
+
+**Trend Analysis**:
+```
+% Change = ((Current velocity - Previous velocity) / Previous velocity) * 100
+Trend: ↗ (positive), ↘ (negative), → (stable)
+```
+
+---
+
+## Output Structure
+
+**Velocity Report Includes**:
+- Current velocity (avg points/period)
+- Trend analysis (↗ ↘ → with % change)
+- Historical breakdown (by week/sprint/month)
+- Velocity by owner (individual agent productivity)
+- Forecasts (if requested)
+- Risk analysis (what could slow us down)
+- Capacity recommendations (plan next sprint)
+- Velocity goals (targets to achieve)
+
+**Forecast Details**:
+- Remaining points to complete epic
+- Weeks needed at current velocity
+- Predicted completion date
+- Confidence level (80%/70%/60%)
+- Risk assumptions
+
+---
+
+## Anti-Patterns & Correct Usage
+
+❌ **DON'T**:
+- Forecast with <5 stories in sample (unreliable)
+- Ignore outliers (can skew velocity)
+- Forecast without confidence levels
+- Use velocity from <3 time periods
+
+✅ **DO**:
+- Calculate over 3+ time periods
+- Show trend analysis with % changes
+- Warn if sample size too small
+- Exclude outliers >3x average
+- Show confidence levels (High/Medium/Low)
+
+---
+
+## Follow-up Integration
+
+After displaying velocity report, suggest:
+- `/agileflow:sprint-plan` - Plan next sprint using velocity
+- `/agileflow:metrics` - See detailed metrics (cycle time, WIP)
+- `/agileflow:board` - See current board state
+- Save velocity report for stakeholder updates
+
+---
 
-**Output**: Full report with current velocity, historical trends, forecasts, risk analysis, capacity recommendations
+## REMEMBER AFTER COMPACTION
 
-**Success Criteria**: Velocity from 3+ periods, trend analysis, forecast (if requested), risk analysis, actionable recommendations
+- Command is read-only (analyzes bus/log.jsonl + story estimates)
+- Parses "done" status changes from bus log
+- Calculates over 3+ time periods (minimum for reliability)
+- Shows trend analysis (↗ ↘ →) with % change
+- Warns if sample size <5 stories (unreliable forecast)
+- Excludes outliers >3x average from velocity
+- Saves velocity history to docs/08-project/velocity/
+- Shows confidence levels (High/Medium/Low)
 
 <!-- COMPACT_SUMMARY_END -->
 

package/src/core/commands/verify.md

@@ -1,6 +1,20 @@
 ---
 description: Run project tests and update story test status
 argument-hint: [story_id] (optional)
+compact_context:
+  priority: critical
+  preserve_rules:
+    - "ALWAYS run STEP 0 context activation before any other action"
+    - "Exit code is AUTHORITATIVE (0=passing, non-zero=failing) - trust over output parsing"
+    - "Read environment.json for test_command and test_timeout_ms config"
+    - "Update ONLY test-related fields in status.json - preserve all other fields"
+    - "If no STORY specified, update ALL in_progress stories"
+    - "Generate clear visual reports with ✅/❌ indicators"
+    - "Best-effort output parsing (Jest/Pytest/Cargo/Go) but exit code is final authority"
+  state_fields:
+    - test_status (passing/failing)
+    - test_results (with passed/failed counts and exit code)
+    - baseline_verified
 ---
 
 # Verify Project Tests

package/src/core/commands/whats-new.md

@@ -1,11 +1,41 @@
 ---
 description: Show what's new in AgileFlow
+argument-hint: (no arguments)
+compact_context:
+  priority: low
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:whats-new - Version reporter (display-only)"
+    - "MUST display current version, last 3-5 versions from CHANGELOG.md"
+    - "MUST check for updates via npm view agileflow version"
+    - "MUST show GitHub link for full changelog"
+    - "Display-only command (never writes files)"
+  state_fields:
+    - current_version
+    - latest_available_version
 ---
 
 # /agileflow:whats-new
 
 Display recent AgileFlow updates and version history.
 
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:whats-new` - Show version history and updates (display-only)
+
+**Quick Usage**:
+```
+/agileflow:whats-new
+```
+
+**What It Does**: Read CHANGELOG.md → Show last 3-5 versions → Check for updates → Display GitHub link
+
+**Output**: Markdown display with version history (no file writes)
+
+**Tool Usage**: None (display-only command)
+
+<!-- COMPACT_SUMMARY_END -->
+
 ---
 
 ## Prompt