agileflow 2.51.0 → 2.56.0

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

@@ -23,7 +23,7 @@ node .agileflow/scripts/obtain-context.js validate-expertise
 
 **Purpose**: Expertise Validator - Validate agent expertise files to detect drift, staleness, and structural issues
 
-**Role**: Expertise Validator responsible for checking expertise.yaml files against codebase and best practices
+**Role**: Validate expertise.yaml files against codebase and best practices (read-only validation)
 
 **Critical Rules**:
 - MUST run validation checks on all expertise files (or specific domain if provided)
@@ -34,64 +34,50 @@ node .agileflow/scripts/obtain-context.js validate-expertise
 - Non-destructive (read-only validation)
 - Report issues but don't auto-fix
 - Prioritize drift detection (most critical)
-- Keep output concise and actionable
 
 **Inputs** (optional):
-- DOMAIN=<domain-name> (validate specific domain, e.g., "database")
+- `DOMAIN`: <domain-name> (validate specific domain, e.g., "database")
 - If no domain specified, validate all experts
 
 **Validation Checks**:
 1. **File Path Drift** - Check that all file paths referenced in expertise files still exist
+   - Grep for file paths: `grep -oE '(src|packages|lib)/[a-zA-Z0-9/_.-]+' expertise.yaml`
+   - Verify each path exists: `[ -f <path> ]`
 2. **Stale Learnings** - Flag expertise files not updated in 30+ days
+   - Extract `last_updated:` field from expertise.yaml
+   - Compare to current date
 3. **File Size Check** - Warn if expertise file exceeds 200 lines
-4. **Required Sections** - Verify expertise.yaml has required structure:
-   - domain: Domain identifier
-   - mental_models: At least one mental model
-   - learnings: Learning history (can be empty initially)
-   - key_files: Important files for this domain
-   - patterns: Common patterns and anti-patterns
+   - Count lines: `wc -l < expertise.yaml`
+4. **Required Sections** - Verify expertise.yaml has required YAML structure:
+   - domain, mental_models, learnings, key_files, patterns
 
 **Expertise File Location**: .agileflow/experts/<domain>/expertise.yaml
 
+**Workflow**:
+1. Parse DOMAIN input (or default to all)
+2. For each domain: Read expertise.yaml → Run all 4 validation checks
+3. Collect results (PASS/FAIL/WARN)
+4. Generate summary report → Suggest remediation actions
+
+**Example Usage**:
+```bash
+/agileflow:validate-expertise
+/agileflow:validate-expertise DOMAIN=database
+```
+
 **Output Format**:
 ```
-======================================
 EXPERTISE VALIDATION REPORT
-======================================
-
+============================
 Validating: database
   [PASS] File exists: expertise.yaml
   [PASS] Required sections present
   [WARN] 2 stale learnings (>30 days)
   [FAIL] DRIFT: src/old/database.ts not found
 
---------------------------------------
-SUMMARY
---------------------------------------
-Total domains: 25
-Passed: 23
-Warnings: 1
-Failures: 1
-
-RECOMMENDED ACTIONS:
-1. Update database expertise - remove reference to src/old/database.ts
-2. Review stale learnings in database domain
+SUMMARY: Total: 25 | Passed: 23 | Warnings: 1 | Failures: 1
 ```
 
-**Workflow**:
-1. Parse DOMAIN input (or default to all)
-2. For each domain:
-   - Read expertise.yaml
-   - Run all 4 validation checks
-   - Collect results
-3. Generate summary report
-4. Suggest remediation actions
-
-**Integration**:
-- Run automatically on session start (optional hook)
-- Run before major releases
-- Run after large refactors
-
 **Success Criteria**:
 - All expertise files validated
 - Drift issues identified
@@ -99,6 +85,8 @@ RECOMMENDED ACTIONS:
 - Actionable recommendations provided
 - Report generated and displayed
 
+**Integration**: Session start hook, before major releases, after large refactors
+
 <!-- COMPACT_SUMMARY_END -->
 
 ## Prompt

package/src/core/commands/velocity.md

@@ -22,93 +22,52 @@ 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, and forecast epic/milestone completion dates
+**Purpose**: Velocity Analyst & Forecaster - Calculate team velocity, identify trends, forecast epic/milestone completion
 
-**Role**: Velocity Analyst responsible for tracking story completion velocity and predicting delivery timelines
+**Role**: Track story completion velocity and predict delivery timelines
 
 **Critical Rules**:
-- MUST parse bus/log.jsonl for "done" status changes
-- MUST match stories to estimates from frontmatter
-- MUST calculate over at least 3 time periods (for reliability)
-- MUST warn if sample size too small (<5 stories)
-- MUST exclude outliers (stories >3x avg) from velocity calc
-- MUST account for holidays/time off in forecasts
-- MUST update forecast confidence based on variance
+- 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/
 
 **Inputs** (optional):
-- PERIOD=week|sprint|month|all (default: sprint - last 2 weeks)
-- FORECAST=<EPIC_ID or milestone> (predict completion date)
-- FORMAT=report|chart|json (default: report)
+- `PERIOD`: week|sprint|month|all (default: sprint)
+- `FORECAST`: <EPIC_ID> (predict completion date)
+- `FORMAT`: report|chart|json (default: report)
 
 **Data Sources**:
-1. docs/09-agents/status.json - Current story state
-2. docs/09-agents/bus/log.jsonl - Historical status changes
-3. docs/06-stories/**/US-*.md - Story estimates and metadata
-4. docs/05-epics/*.md - Epic definitions
-5. docs/08-project/milestones.md - Milestone targets
+1. docs/09-agents/bus/log.jsonl - "done" status changes with timestamps
+2. docs/06-stories/**/US-*.md - Story estimates (frontmatter)
+3. docs/05-epics/*.md - Epic definitions
+4. docs/08-project/milestones.md - Milestone targets
 
-**Velocity Calculation**:
-```
-Velocity = Total points completed / Number of time periods
-```
+**Key Formulas**:
+- Velocity = Total points completed / Number of time periods
+- Days to complete = (Remaining points / Velocity) * 7
+- Confidence = 100% - (Std Dev / Velocity Avg) * 100
 
-Parse bus/log.jsonl for status changes to "done":
-```json
-{"ts":"2025-10-10T10:00:00Z","type":"status","story":"US-0030","status":"done"}
-```
-
-For each story, get estimate from frontmatter:
-```yaml
-estimate: 1.5d
-```
-
-Convert to points (1d = 1 point) and sum by time period.
-
-**Forecasting Algorithm**:
-```
-Days to complete = (Remaining points / Velocity) * 7
-Completion date = Today + Days to complete
-Confidence = 100% - (Velocity 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
+
+**Example Usage**:
+```bash
+/agileflow:velocity
+/agileflow:velocity PERIOD=month FORECAST=EP-0010
+/agileflow:velocity FORMAT=json
 ```
 
-**Report Sections**:
-1. Current Velocity (average, trend, last sprint, best/worst)
-2. Historical Velocity (chart, weekly breakdown, insights)
-3. Velocity by Owner (points/week, utilization, trends)
-4. Forecast: Epic Completion (stories, remaining, forecast date, confidence)
-5. Risk Analysis (velocity risks, schedule risks)
-6. Capacity Planning (current capacity, recommendations)
-7. Velocity Goals (current, target, action items)
-
-**Output Formats**:
-- report: Full markdown velocity report with charts
-- chart: ASCII art velocity chart
-- json: Machine-readable velocity data
-
-**Workflow**:
-1. Parse bus/log.jsonl for "done" status changes
-2. Match stories to estimates from frontmatter
-3. Group completions by time period (week/sprint)
-4. Calculate velocity stats (avg, trend, std dev)
-5. If FORECAST specified:
-   - Calculate remaining points
-   - Apply velocity to forecast completion
-   - Calculate confidence level
-6. Render report/chart
-7. Suggest actions based on findings
+**Output**: Full report with current velocity, historical trends, forecasts, risk analysis, capacity recommendations
 
-**Output Files**:
-- Velocity report: docs/08-project/velocity/velocity-YYYYMMDD.md
-- Optional: Update stakeholder dashboard
-
-**Success Criteria**:
-- Velocity calculated from at least 3 time periods
-- Trend analysis completed
-- Forecast provided (if requested)
-- Risk analysis included
-- Actionable recommendations provided
-- Report saved to velocity directory
+**Success Criteria**: Velocity from 3+ periods, trend analysis, forecast (if requested), risk analysis, actionable recommendations
 
 <!-- COMPACT_SUMMARY_END -->
 

package/src/core/commands/verify.md

@@ -73,6 +73,22 @@ This gathers git status, stories/epics, session state, and registers for PreComp
 - Used by: /agileflow:session:resume, /agileflow:baseline
 - Uses: environment.json (config), status.json (story status), session-state.json (tracking)
 
+**Tool Usage Examples**:
+
+TodoWrite:
+```xml
+<invoke name="TodoWrite">
+<parameter name="content">1. Run pre-flight checks (session harness initialized)
+2. Load test configuration from environment.json
+3. Execute test command with timeout
+4. Parse test results (exit code + output)
+5. Update status.json with test_status
+6. Update session-state.json (if exists)
+7. Generate and display verification report</parameter>
+<parameter name="status">in-progress</parameter>
+</invoke>
+```
+
 <!-- COMPACT_SUMMARY_END -->
 
 ## Prompt

package/src/core/experts/documentation/expertise.yaml

@@ -1,6 +1,6 @@
 domain: documentation
-last_updated: 2025-12-21
-version: 1.1
+last_updated: 2025-12-24
+version: 1.2
 
 # AgileFlow-specific documentation structure (learned from actual codebase)
 files:
@@ -132,3 +132,17 @@ learnings:
     context: "Analyzed research pattern"
     insight: "Research notes use YYYYMMDD-slug.md pattern in docs/10-research/"
     source: "docs/10-research/"
+
+  - date: 2025-12-24
+    context: "Generated command documentation (batch 4 - operations)"
+    insight: "Created 6 comprehensive operation command docs (ci, deploy, changelog, packages, tests, compress) following template with quick start, parameters, examples, workflow, output, and related commands sections"
+    created_files:
+      - "apps/docs/content/docs/commands/ci.mdx (155 lines)"
+      - "apps/docs/content/docs/commands/deploy.mdx (324 lines)"
+      - "apps/docs/content/docs/commands/changelog.mdx (329 lines)"
+      - "apps/docs/content/docs/commands/packages.mdx (377 lines)"
+      - "apps/docs/content/docs/commands/tests.mdx (449 lines)"
+      - "apps/docs/content/docs/commands/compress.mdx (375 lines)"
+    total_lines: 2009
+    source: "packages/cli/src/core/commands/*.md"
+    notes: "All files follow consistent documentation template: frontmatter, quick start, purpose, parameters table, examples with explanations, workflow steps, output/files, and related commands"

package/src/core/skills/agileflow-retro-facilitator/SKILL.md

@@ -16,9 +16,60 @@ This skill activates when:
 - Gathering team feedback
 - Running sprint reviews
 
+## Variables
+
+- default_format: start-stop-continue
+- track_action_items: true
+- include_metrics: true
+- save_to_docs: true
+
+## Cookbook
+
+Based on the context, select the appropriate retro format:
+
+### Start/Stop/Continue (Default)
+If running a standard sprint retrospective:
+Then read and execute cookbook/start-stop-continue.md
+
+Examples:
+- "run a retro for sprint 5"
+- "sprint retrospective"
+- "what went well this sprint?"
+- "let's do a retro"
+
+### Glad/Sad/Mad
+If discussing team dynamics, emotions, or interpersonal issues:
+Then read cookbook/glad-sad-mad.md
+
+Examples:
+- "the team seems frustrated"
+- "morale is low, let's talk about it"
+- "team dynamics retro"
+- "emotional check-in"
+- "glad sad mad retro"
+
+### 4Ls (Liked, Learned, Lacked, Longed For)
+If focusing on learning and growth:
+Then read cookbook/4ls.md
+
+Examples:
+- "learning retrospective"
+- "what did we learn this sprint?"
+- "growth-focused retro"
+- "4Ls retro"
+- "liked learned lacked longed"
+
+## Workflow
+
+1. Identify which format to use (check user request against Cookbook)
+2. Read the appropriate cookbook file for detailed template
+3. Gather feedback using that format's structure
+4. Create SMART action items (read prompts/action-items.md for guidance)
+5. Document in docs/08-project/retros/
+
 ## What This Does
 
-1. Structures retrospective using Start/Stop/Continue format
+1. Structures retrospective using the selected format
 2. Gathers feedback on what went well and what didn't
 3. Identifies patterns and root causes
 4. Creates SMART action items with owners and due dates
@@ -31,19 +82,17 @@ This skill activates when:
    - Review sprint metrics (velocity, completion rate)
    - Check previous action items
 
-2. **Gather feedback**:
-   - What went well?
-   - What didn't go well?
-   - What should we start doing?
-   - What should we stop doing?
-   - What should we continue doing?
+2. **Gather feedback** (using selected format):
+   - Use the cookbook file template
+   - Ensure all voices are heard
+   - Time-box each section
 
 3. **Identify patterns**:
    - Group similar feedback
    - Find root causes
    - Spot recurring themes
 
-4. **Create action items**:
+4. **Create action items** (see prompts/action-items.md):
    - Specific, actionable steps
    - Assign owners
    - Set due dates
@@ -54,217 +103,6 @@ This skill activates when:
    - Share with team
    - Add action items to backlog if needed
 
-## Retro Format (Start/Stop/Continue)
-
-```markdown
-# Sprint [Number] Retrospective
-
-**Date**: YYYY-MM-DD
-**Facilitator**: [Name]
-**Attendees**: [Team members present]
-**Sprint Duration**: [Start] - [End]
-
-## Sprint Metrics
-
-- **Committed**: X story points
-- **Completed**: Y story points
-- **Velocity**: Z%
-- **Stories Done**: A / B
-- **Bugs Found**: C
-
-## What Went Well ✅
-
-- [Positive 1: Specific thing that worked]
-- [Positive 2: Team success]
-- [Positive 3: Process improvement]
-
-## What Didn't Go Well ❌
-
-- [Challenge 1: Specific problem]
-- [Challenge 2: Blocker or delay]
-- [Challenge 3: Process issue]
-
-## Start (New Practices) 🟢
-
-- **[Practice 1]**
-  - Why: [Reasoning]
-  - Owner: [Who will drive this]
-  - Success metric: [How we'll measure]
-
-## Stop (Remove Practices) 🔴
-
-- **[Practice 1]**
-  - Why it's not working: [Reasoning]
-  - Alternative: [What we'll do instead]
-
-## Continue (Keep Doing) 🟡
-
-- **[Practice 1]**
-  - Why it's working: [Reasoning]
-  - How to maintain: [Keep it going]
-
-## Action Items
-
-- [ ] **[Action 1]** - @Owner - Due: [Date]
-  - Success criteria: [How we know it's done]
-
-- [ ] **[Action 2]** - @Owner - Due: [Date]
-  - Success criteria: [How we know it's done]
-
-## Previous Action Items Review
-
-- [✅] **[Completed Action]** - Implemented, improved X by Y%
-- [🔄] **[In Progress Action]** - Still working on it, 60% done
-- [❌] **[Not Done Action]** - Blocked by Z, rolling to next sprint
-
-## Key Insights
-
-1. [Insight 1: Pattern or learning]
-2. [Insight 2: Team dynamic observation]
-3. [Insight 3: Process discovery]
-```
-
-## Retro Formats
-
-Choose based on context:
-
-**Start/Stop/Continue**: Best for regular sprint retros
-
-**Glad/Sad/Mad**: Best for emotional topics, team dynamics
-```markdown
-## Glad 😊
-- [Things that made us happy]
-
-## Sad 😔
-- [Things that disappointed us]
-
-## Mad 😡
-- [Things that frustrated us]
-```
-
-**4Ls (Liked, Learned, Lacked, Longed For)**: Best for learning-focused retros
-```markdown
-## Liked 👍
-- [What we enjoyed]
-
-## Learned 💡
-- [New knowledge or skills]
-
-## Lacked ⚠️
-- [What was missing]
-
-## Longed For 🌟
-- [What we wish we had]
-```
-
-## Good vs Bad Feedback
-
-**Good (Specific, Actionable)**:
-```
-✅ "Daily standups ran long (20+ min) because we discussed
-   implementation details. Consider moving technical discussions
-   to separate sessions."
-
-✅ "Code reviews were faster this sprint (avg 4 hours vs 24 hours
-   last sprint) thanks to smaller PR sizes."
-```
-
-**Bad (Vague, Blame-Oriented)**:
-```
-❌ "Meetings were bad"
-❌ "Bob didn't do his job"
-❌ "Everything was terrible"
-❌ "Process is broken"
-```
-
-## SMART Action Items
-
-- **S**pecific: Clear what needs to be done
-- **M**easurable: Can verify it's complete
-- **A**ssignable: Has an owner
-- **R**elevant: Addresses the issue
-- **T**ime-bound: Has a deadline
-
-**Example**:
-```
-✅ Good:
-- [ ] **Create PR size guideline** - @TechLead - Due: Before next sprint
-  - Success: Document written, shared with team, added to CLAUDE.md
-  - Metric: 80% of PRs under 300 lines
-
-❌ Bad:
-- [ ] Fix code reviews
-```
-
-## Metrics to Track
-
-**Sprint Health**:
-- Velocity trend (increasing, stable, decreasing?)
-- Commitment accuracy (completed vs committed)
-- Bug count (increasing, decreasing?)
-- Blocker frequency
-
-**Team Health**:
-- Meeting effectiveness
-- Communication quality
-- Collaboration level
-- Work-life balance
-
-**Process Health**:
-- Cycle time (story start to done)
-- Code review turnaround
-- Deployment frequency
-- Incident count
-
-## Common Themes to Watch For
-
-**Positive Patterns**:
-- Consistent velocity
-- Low bug count
-- Fast code reviews
-- Clear requirements
-- Good collaboration
-
-**Warning Signs**:
-- Declining velocity
-- Recurring blockers
-- Communication issues
-- Scope creep
-- Burnout indicators
-
-## Facilitator Tips
-
-**Do**:
-- Create safe space for honest feedback
-- Focus on process, not people
-- Time-box discussions (5-10 min per topic)
-- Ensure everyone participates
-- End on positive note
-- Follow up on action items
-
-**Don't**:
-- Blame individuals
-- Let discussions run too long
-- Skip retros ("too busy")
-- Create action items without owners
-- Ignore previous action items
-
-## Remote Retro Adaptations
-
-For distributed teams:
-- Use anonymous feedback tools (Retrium, Metro Retro)
-- Give time for async reflection before meeting
-- Use polls/voting for prioritization
-- Record session for absent team members
-- Use collaborative docs for brainstorming
-
-## Frequency Guidelines
-
-- **Every sprint**: Standard retros (60-90 min)
-- **Major milestones**: Extended retros (2-3 hours)
-- **Quarterly**: Big-picture retros (process, tools, culture)
-- **Post-incident**: Blameless postmortems (as needed)
-
 ## Integration
 
 - **agileflow-sprint-planner**: Retro insights inform next sprint planning

package/src/core/skills/agileflow-retro-facilitator/cookbook/4ls.md

@@ -0,0 +1,86 @@
+# 4Ls Retrospective Format
+
+Best for learning-focused retros. Use when emphasizing growth, skill development, or process discovery.
+
+## When to Use
+
+- After learning sprints or experiments
+- When onboarding new team members
+- Quarterly or milestone retros
+- After trying new tools or processes
+- When team wants to focus on growth
+
+## Template
+
+```markdown
+# 4Ls Retrospective
+
+**Date**: YYYY-MM-DD
+**Facilitator**: [Name]
+**Attendees**: [Team members present]
+**Focus**: [Learning theme or milestone]
+
+## Liked (What we enjoyed)
+
+- [Liked 1: Enjoyable aspect of work]
+- [Liked 2: Positive experience]
+- [Liked 3: Successful collaboration]
+
+## Learned (New knowledge or skills)
+
+- [Learned 1: Technical skill acquired]
+- [Learned 2: Process insight]
+- [Learned 3: Team dynamic discovery]
+
+## Lacked (What was missing)
+
+- [Lacked 1: Resource or tool needed]
+- [Lacked 2: Knowledge gap]
+- [Lacked 3: Support or guidance needed]
+
+## Longed For (What we wish we had)
+
+- [Longed 1: Ideal state or tool]
+- [Longed 2: Process improvement]
+- [Longed 3: Future capability]
+
+## Key Learnings to Document
+
+| Learning | Source | How to Apply |
+|----------|--------|--------------|
+| [Learning 1] | [Sprint/Project] | [Next steps] |
+| [Learning 2] | [Sprint/Project] | [Next steps] |
+
+## Action Items
+
+- [ ] **Address [Lacked item]** - @Owner - Due: [Date]
+- [ ] **Move toward [Longed For item]** - @Owner - Due: [Date]
+- [ ] **Document [Learned item]** - @Owner - Due: [Date]
+
+## Knowledge Sharing Plan
+
+- [How will learnings be shared with broader team?]
+- [Documentation to create?]
+- [Training or pairing sessions?]
+```
+
+## Facilitation Notes
+
+**Focus on Growth**:
+- Emphasize that gaps are opportunities, not failures
+- Celebrate learning moments, even from mistakes
+- Connect learnings to future improvements
+
+**Timing**:
+- Liked: 10 minutes
+- Learned: 15 minutes
+- Lacked: 10 minutes
+- Longed For: 10 minutes
+- Action Items: 10 minutes
+- Total: ~55 minutes
+
+**Tips**:
+- "Learned" is the heart of this format - spend time here
+- Turn "Lacked" into specific asks, not complaints
+- "Longed For" should inspire, not depress
+- Create concrete knowledge-sharing actions