agileflow 2.37.2 → 2.39.0

package/README.md

@@ -41,6 +41,7 @@ This will:
 agileflow setup       # Set up AgileFlow in project
 agileflow status      # Check installation + updates
 agileflow update      # Update to latest version
+agileflow list        # List installed components
 agileflow doctor      # Diagnose issues
 agileflow uninstall   # Remove from project
 ```
@@ -50,6 +51,7 @@ agileflow uninstall   # Remove from project
 npx agileflow setup       # Set up AgileFlow in project
 npx agileflow status      # Check installation + updates
 npx agileflow update      # Update to latest version
+npx agileflow list        # List installed components
 npx agileflow doctor      # Diagnose issues
 npx agileflow uninstall   # Remove from project
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agileflow",
-  "version": "2.37.2",
+  "version": "2.39.0",
   "description": "AI-driven agile development system for Claude Code, Cursor, Windsurf, and more",
   "keywords": [
     "agile",

package/src/core/agents/api.md

@@ -364,6 +364,30 @@ RESEARCH INTEGRATION
 - Validation libraries (Zod, Yup, class-validator)
 - External integrations (Stripe, SendGrid, Twilio, etc.)
 
+PLAN MODE FOR COMPLEX API WORK
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+Before implementing, evaluate complexity:
+
+| Situation | Action |
+|-----------|--------|
+| Simple CRUD endpoint | Just implement it |
+| Schema migration | → `EnterPlanMode` (analyze impact) |
+| New auth pattern | → `EnterPlanMode` (architectural decision) |
+| External integration | → `EnterPlanMode` (research first) |
+| Multi-service changes | → `EnterPlanMode` (coordinate approach) |
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Read-only exploration
+2. Explore existing API patterns (routes, middleware, validation)
+3. Design endpoint/schema approach
+4. Present plan with file paths
+5. Get approval → `ExitPlanMode`
+6. Implement
+
+**Skip Plan Mode For**: Single endpoint additions following existing patterns, simple CRUD operations, minor bug fixes.
+
 WORKFLOW
 1. **[KNOWLEDGE LOADING]** Before implementation:
    - Read CLAUDE.md for project-specific API conventions

package/src/core/agents/database.md

@@ -305,6 +305,31 @@ SLASH COMMANDS
 - `/agileflow:impact-analysis` → Analyze impact of schema changes on other tables
 - `/agileflow:status STORY=... STATUS=...` → Update status
 
+PLAN MODE FOR DATABASE CHANGES (CRITICAL)
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+**Database changes are high-risk**. Always plan before schema modifications:
+
+| Situation | Action |
+|-----------|--------|
+| Simple query optimization | May skip planning |
+| New table/column | → `EnterPlanMode` (design schema) |
+| Schema migration | → `EnterPlanMode` (rollback strategy) |
+| Index changes | → `EnterPlanMode` (analyze query patterns) |
+| Data model refactoring | → `EnterPlanMode` (impact on all queries) |
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Read-only exploration
+2. Map current schema and relationships
+3. Identify all queries affected by change
+4. Design migration with rollback strategy
+5. Plan data migration if needed
+6. Present plan → Get approval → `ExitPlanMode`
+7. Implement with reversible migrations
+
+**Database Principle**: Schema changes are permanent. Plan twice, migrate once.
+
 WORKFLOW
 
 1. **[KNOWLEDGE LOADING]**:

package/src/core/agents/devops.md

@@ -291,6 +291,31 @@ RESEARCH INTEGRATION
 - Monitoring and observability (Prometheus, Grafana, Datadog, Sentry)
 - Infrastructure as Code (Terraform, Pulumi, CloudFormation)
 
+PLAN MODE FOR INFRASTRUCTURE CHANGES
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+**Infrastructure changes affect production**. Plan before deploying:
+
+| Situation | Action |
+|-----------|--------|
+| Minor config tweak | May skip planning |
+| New CI/CD pipeline | → `EnterPlanMode` (design workflow) |
+| Deployment strategy change | → `EnterPlanMode` (rollback plan) |
+| Infrastructure as Code | → `EnterPlanMode` (terraform plan) |
+| Environment changes | → `EnterPlanMode` (impact analysis) |
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Read-only exploration
+2. Map current infrastructure and dependencies
+3. Design change with rollback strategy
+4. Identify blast radius (what breaks if this fails?)
+5. Plan monitoring/alerting for the change
+6. Present plan → Get approval → `ExitPlanMode`
+7. Implement with verification at each step
+
+**DevOps Principle**: Infrastructure is cattle, not pets—but still needs planning.
+
 WORKFLOW
 1. **[KNOWLEDGE LOADING]** Before implementation:
    - Read CLAUDE.md for project-specific infrastructure setup

package/src/core/agents/mentor.md

@@ -241,6 +241,41 @@ IMPLEMENTATION FLOW
 8. Generate PR body with /agileflow:pr-template command
 9. Suggest syncing docs/context.md and saving research if applicable
 
+PLAN MODE FOR COMPLEX IMPLEMENTATIONS
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+Before implementing, evaluate task complexity:
+
+| Situation | Action |
+|-----------|--------|
+| Trivial fix (typo, small tweak) | Just do it |
+| Specific instructions given | Follow directly |
+| Research/exploration only | Use Task tool with Explore agent |
+| Complex/multi-file/unclear | → `EnterPlanMode` first |
+
+**When to Enter Plan Mode**:
+- New features with multiple valid approaches
+- Multi-file changes or refactoring
+- Architectural decisions (choosing patterns, libraries, approaches)
+- Unclear requirements (need to explore before designing)
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Read-only exploration
+2. Explore codebase with Glob, Grep, Read
+3. Design implementation approach
+4. Present plan with file paths and steps
+5. Clarify decisions with user
+6. Get approval → `ExitPlanMode`
+7. Implement the approved plan
+
+**Plan Quality Checklist**:
+- [ ] Explored relevant codebase
+- [ ] Identified all files to change
+- [ ] Considered existing patterns
+- [ ] Noted risks/breaking changes
+- [ ] Got user approval
+
 AGENT COORDINATION PATTERNS
 
 **When to Delegate to Specialized Agents**:

package/src/core/agents/performance.md

@@ -308,6 +308,31 @@ SLASH COMMANDS
 - `/agileflow:impact-analysis` → Analyze performance impact of changes
 - `/agileflow:status STORY=... STATUS=...` → Update status
 
+PLAN MODE FOR PERFORMANCE OPTIMIZATION
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+**Performance work requires measurement first**. Always plan before optimizing:
+
+| Situation | Action |
+|-----------|--------|
+| "Make it faster" (vague) | → `EnterPlanMode` (profile first!) |
+| Known bottleneck | → `EnterPlanMode` (design optimization) |
+| Caching implementation | → `EnterPlanMode` (invalidation strategy) |
+| Query optimization | → `EnterPlanMode` (measure before/after) |
+| Bundle size reduction | → `EnterPlanMode` (analyze dependencies) |
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Read-only exploration
+2. **Profile first** - measure current performance
+3. Identify actual bottlenecks (not assumptions)
+4. Design optimization with benchmarks
+5. Plan verification (how to prove it's faster?)
+6. Present plan → Get approval → `ExitPlanMode`
+7. Implement, measure, verify improvement
+
+**Performance Principle**: Measure, don't guess. Premature optimization is the root of all evil.
+
 WORKFLOW
 
 1. **[KNOWLEDGE LOADING]**:

package/src/core/agents/refactor.md

@@ -345,6 +345,31 @@ SLASH COMMANDS
 - `/agileflow:impact-analysis` → Analyze impact of refactoring changes
 - `/agileflow:status STORY=... STATUS=...` → Update status
 
+PLAN MODE FOR REFACTORING (ALWAYS USE)
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+**Refactoring REQUIRES planning**. Always enter plan mode before refactoring:
+
+| Situation | Action |
+|-----------|--------|
+| ANY refactoring work | → `EnterPlanMode` |
+| Rename across codebase | → `EnterPlanMode` (find all usages) |
+| Extract component/function | → `EnterPlanMode` (identify dependencies) |
+| Architectural changes | → `EnterPlanMode` (impact analysis) |
+| Technical debt cleanup | → `EnterPlanMode` (prioritize changes) |
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Read-only exploration
+2. Map current architecture and dependencies
+3. Identify all affected files and tests
+4. Design migration path (small, reversible steps)
+5. Note breaking changes and risks
+6. Present plan → Get approval → `ExitPlanMode`
+7. Implement incrementally, verify tests after each step
+
+**Refactoring Principle**: Never refactor without a plan. Small changes cascade.
+
 WORKFLOW
 
 1. **[KNOWLEDGE LOADING]**:

package/src/core/agents/security.md

@@ -303,6 +303,31 @@ AGENT COORDINATION
 {"ts":"2025-10-21T10:10:00Z","from":"AG-SECURITY","type":"status","story":"US-0050","text":"Security review complete: 3 high vulnerabilities found in dependency X, recommended updates"}
 ```
 
+PLAN MODE FOR SECURITY IMPLEMENTATIONS
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+**Security changes require careful planning**. Always plan before implementing:
+
+| Situation | Action |
+|-----------|--------|
+| Simple dependency update | May skip planning |
+| New auth mechanism | → `EnterPlanMode` (design security model) |
+| Vulnerability remediation | → `EnterPlanMode` (root cause analysis) |
+| Access control changes | → `EnterPlanMode` (audit impact) |
+| Encryption/secrets handling | → `EnterPlanMode` (key management plan) |
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Read-only exploration
+2. Audit current security posture
+3. Identify all attack surfaces affected
+4. Design fix with defense-in-depth approach
+5. Plan verification (how to prove it's secure?)
+6. Present plan → Get approval → `ExitPlanMode`
+7. Implement with security review at each step
+
+**Security Principle**: Security is not a feature—it's a property. Plan comprehensively.
+
 WORKFLOW
 
 1. **[KNOWLEDGE LOADING]** Before review:

package/src/core/agents/ui.md

@@ -606,6 +606,30 @@ RESEARCH INTEGRATION
 - Animation libraries (Framer Motion, React Spring, GSAP)
 - State management for UI (React Context, Zustand, Redux)
 
+PLAN MODE FOR COMPLEX UI WORK
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+Before implementing, evaluate complexity:
+
+| Situation | Action |
+|-----------|--------|
+| Simple component tweak | Just implement it |
+| New design system pattern | → `EnterPlanMode` (explore existing patterns) |
+| Multi-component feature | → `EnterPlanMode` (plan component hierarchy) |
+| Responsive/accessibility overhaul | → `EnterPlanMode` (audit first) |
+| State management changes | → `EnterPlanMode` (impact analysis) |
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Read-only exploration
+2. Explore existing UI patterns (components, styles, state)
+3. Design component structure and props
+4. Present plan with file paths
+5. Get approval → `ExitPlanMode`
+6. Implement
+
+**Skip Plan Mode For**: Single component additions following existing patterns, style tweaks, minor bug fixes.
+
 WORKFLOW
 1. **[PROACTIVE - First Story Only]** Check for design system (see DESIGN SYSTEM INITIALIZATION section above)
    - If none exists → Ask to create one

package/src/core/commands/babysit.md

@@ -546,6 +546,62 @@ This ensures the expert loads their mental model before working.
 
 ---
 
+PLAN MODE FOR COMPLEX IMPLEMENTATIONS
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+Before implementing features, evaluate complexity to decide whether to plan first or implement directly.
+
+**Decision Tree**:
+```
+Is this a trivial fix (typo, obvious bug, small tweak)?
+  → Just do it (no planning needed)
+
+Are specific, detailed instructions given?
+  → Follow instructions directly
+
+Is this research/exploration only?
+  → Use Task tool with Explore agent (no plan mode)
+
+Is this complex, multi-file, or unclear?
+  → EnterPlanMode FIRST
+```
+
+**When to Enter Plan Mode**:
+| Trigger | Example |
+|---------|---------|
+| New feature with choices | "Add user authentication" (JWT vs sessions?) |
+| Multiple valid approaches | "Add caching" (Redis vs in-memory?) |
+| Multi-file changes | "Refactor the auth system" |
+| Architectural decisions | "Add real-time updates" (WebSocket vs SSE?) |
+| Unclear requirements | "Make the app faster" |
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Switches to read-only exploration
+2. Explore with Glob, Grep, Read (understand codebase)
+3. Design implementation approach
+4. Present plan to user with file paths and steps
+5. Use AskUserQuestion to clarify decisions
+6. Get user approval
+7. `ExitPlanMode` → Resume with write access
+8. Implement the approved plan
+
+**Skip Plan Mode For**:
+- Single-line or few-line fixes
+- Adding a single function with clear requirements
+- Tasks where user gave very specific instructions
+- Pure research (use Task tool with Explore agent)
+
+**Plan Quality Checklist** (before ExitPlanMode):
+- [ ] Explored relevant parts of codebase
+- [ ] Identified all files that need changes
+- [ ] Considered existing patterns/conventions
+- [ ] Noted potential risks or breaking changes
+- [ ] Presented clear implementation steps
+- [ ] Got explicit user approval
+
+---
+
 ERROR HANDLING & RECOVERY
 
 When things go wrong, diagnose the issue and provide recovery steps. Follow the general recovery pattern:

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

@@ -1,6 +1,6 @@
 domain: accessibility
-last_updated: 2025-12-16
-version: 1.0
+last_updated: 2025-12-21
+version: 1.1
 
 files:
   components:
@@ -21,6 +21,12 @@ files:
     - path: ACCESSIBILITY.md
       purpose: Accessibility statement
 
+  cli:
+    - path: packages/cli/src/core/
+      purpose: CLI commands and agents (primary accessibility focus for AgileFlow)
+    - path: packages/cli/tools/
+      purpose: CLI tools and installers
+
 relationships:
   - component_type: form
     requirements: [labels, error_messages, focus_management]
@@ -31,6 +37,9 @@ relationships:
   - component_type: navigation
     requirements: [keyboard_nav, skip_links, landmarks]
     aria: [role=navigation, aria-current]
+  - component_type: cli_prompt
+    requirements: [clear_instructions, keyboard_only, error_feedback]
+    libraries: [inquirer, chalk, ora]
 
 patterns:
   - name: Focus Management
@@ -45,6 +54,15 @@ patterns:
   - name: Color Contrast
     description: "4.5:1 for text, 3:1 for large text"
     implementation: "Use contrast checker tools"
+  - name: CLI Semantic Colors
+    description: "Terminal colors convey meaning consistently"
+    implementation: "Green=success, Red=error, Yellow=warning, Cyan=info, no color-only indicators"
+  - name: CLI Progress Feedback
+    description: "Visual feedback for long-running operations"
+    implementation: "Ora spinners with descriptive text, percentage indicators where applicable"
+  - name: CLI Error Messages
+    description: "Clear, actionable error messages"
+    implementation: "Context + problem + solution, colored output with chalk, exit codes for automation"
 
 conventions:
   - "WCAG 2.1 AA minimum, AAA preferred"
@@ -54,6 +72,10 @@ conventions:
   - "Color never sole indicator of meaning"
   - "Motion respects prefers-reduced-motion"
   - "Skip links for keyboard users"
+  - "CLI: Always provide text with colored output (never color-only)"
+  - "CLI: All prompts keyboard-navigable (arrow keys, tab, enter)"
+  - "CLI: Error messages include context and next steps"
+  - "CLI: Progress indicators have descriptive text"
 
 wcag_checklist:
   perceivable:
@@ -74,4 +96,20 @@ wcag_checklist:
     - "4.1.1 Parsing (A)"
     - "4.1.2 Name, Role, Value (A)"
 
-learnings: []  # AUTO-UPDATED by self-improve
+learnings:
+  - date: 2025-12-21
+    context: "AgileFlow CLI accessibility patterns"
+    insight: "AgileFlow is a CLI tool, not a web application. Accessibility focuses on terminal UX: clear error messages with semantic colors (chalk), keyboard-friendly prompts (inquirer), progress indicators (ora spinners), and consistent color conventions (green=success, red=error, yellow=warning)."
+    impact: "Shifted accessibility focus from WCAG web patterns to CLI usability patterns. All user-facing output should be screen-reader friendly by always pairing colors with descriptive text."
+  - date: 2025-12-21
+    context: "CLI semantic color system"
+    insight: "Terminal colors must never be the sole indicator of meaning. Always include descriptive text alongside colored output. Example: '✓ Success: Installation complete' (green) vs just green checkmark."
+    impact: "Ensures CLI output is accessible to users with color blindness or screen readers. All installers (ui.js, docs-setup.js) follow this pattern."
+  - date: 2025-12-21
+    context: "Interactive prompts accessibility"
+    insight: "All CLI prompts use inquirer library which provides built-in keyboard navigation (arrow keys, tab, enter, escape). Prompts always include clear instructions and validation error messages."
+    impact: "Users can navigate all AgileFlow prompts without mouse. Validation errors are actionable and specific (e.g., 'Please enter a valid directory path' vs 'Invalid input')."
+  - date: 2025-12-21
+    context: "Long-running operation feedback"
+    insight: "AgileFlow uses ora spinners for operations >1 second. Spinners always have descriptive text explaining current action (e.g., 'Installing dependencies...' not just spinner). Completion shows success/failure with clear messaging."
+    impact: "Users always know what's happening during installs, setups, and file operations. No silent failures or mysterious waiting periods. Screen readers can announce status changes."

package/src/core/experts/adr-writer/expertise.yaml

@@ -3,36 +3,43 @@
 # AUTO-UPDATED by self-improve.md after completing work
 
 domain: adr-writer
-last_updated: 2025-12-16
-version: 1.0
+last_updated: 2025-12-21
+version: 1.1
 
+# AgileFlow-specific ADR patterns (learned from actual codebase)
 files:
   decisions:
     - path: docs/03-decisions/
       purpose: "Architecture Decision Records"
-      conventions: "ADR-####-slug.md naming"
-    - path: docs/03-decisions/template.md
-      purpose: "ADR template"
+      conventions: "adr-NNNN-slug.md naming (e.g., adr-0001-agent-expert-system.md)"
+      example: "adr-0001-agent-expert-system.md"
     - path: docs/03-decisions/README.md
-      purpose: "ADR index"
+      purpose: "ADR index listing all decisions"
 
   research:
     - path: docs/10-research/
       purpose: "Research supporting ADR alternatives"
+      naming: "YYYYMMDD-slug.md format"
     - path: docs/10-research/README.md
       purpose: "Research index"
 
   context:
     - path: CLAUDE.md
-      purpose: "Project context informing decisions"
+      purpose: "Project context informing decisions (internal)"
     - path: docs/04-architecture/
       purpose: "Architecture documentation"
+    - path: docs/05-epics/
+      purpose: "Epics link to ADRs for context"
 
 relationships:
   - parent: research
     child: adrs
     type: informs
-    notes: "Research provides alternatives for ADRs"
+    notes: "Research provides alternatives for ADRs (see ADR-0001 referencing research)"
+  - parent: adrs
+    child: epics
+    type: linked_from
+    notes: "Epics reference ADRs (EP-0001 → ADR-0001)"
   - parent: adrs
     child: implementation
     type: constrains
@@ -43,35 +50,56 @@ relationships:
     notes: "Old ADRs can be superseded by new ones"
 
 patterns:
-  - name: ADR Structure
-    description: "Title, Status, Context, Decision, Alternatives, Consequences"
+  - name: ADR Structure (AgileFlow)
+    description: "Status, Date, Decision Makers, Epic link, then sections"
+    location: docs/03-decisions/adr-0001-agent-expert-system.md
+    sections:
+      - "Context (problem statement with research foundation)"
+      - "Decision (what we're doing)"
+      - "Options Considered (3-4 alternatives with rationale)"
+      - "Consequences (Benefits and Trade-offs)"
+      - "Implementation Plan (phased approach)"
+      - "Risks and Mitigations (table format)"
+      - "Success Criteria (qualitative and quantitative)"
+      - "Related Documents (links to epic, research)"
+
+  - name: ADR Header Format
+    description: "Markdown frontmatter style at top"
     location: docs/03-decisions/
     example: |
-      # ADR-0001: Use PostgreSQL for data persistence
-      ## Status: Accepted
-      ## Context: Need relational database...
-      ## Decision: PostgreSQL...
-      ## Alternatives Considered: MySQL, MongoDB...
-      ## Consequences: +Reliability, -Learning curve
-
-  - name: ADR Status Lifecycle
-    description: "Proposed → Accepted → (Deprecated | Superseded)"
+      # ADR-0001: Agent Expert System
+      **Status**: Accepted
+      **Date**: 2025-12-16
+      **Decision Makers**: Development Team
+      **Epic**: [EP-0001](../05-epics/EP-0001-agent-expert-pilot.md)
+
+  - name: Options Considered Format
+    description: "Each option with brief rationale"
     location: docs/03-decisions/
-    example: "Start Proposed, approve to Accepted"
+    example: |
+      ### Option 1: Single Global Expert (Rejected)
+      - Description
+      - **Rejected**: Reason why not selected
+
+  - name: Risks Table Format
+    description: "Risk and Mitigation columns"
+    location: docs/03-decisions/
+    example: "| Stale expertise | Mandatory validation step |"
 
   - name: Research-First ADR
-    description: "Always research alternatives before writing ADR"
+    description: "Always reference research that informed decision"
     location: docs/10-research/
-    example: "Research 3-5 alternatives with pros/cons"
+    example: "See: docs/10-research/20251216-agent-experts-self-improving-agents.md"
 
 conventions:
   - "Research alternatives before writing ADR"
-  - "Document 2-5 alternatives with pros/cons"
-  - "State decision clearly and concisely"
-  - "List consequences (positive, negative, neutral)"
-  - "Link to related ADRs"
-  - "Update index after creating ADR"
-  - "Use imperative title (Use X, Choose Y)"
+  - "Link ADR to epic that drove the decision"
+  - "Document 3-4 alternatives with rationale for rejection/deferral"
+  - "Include Implementation Plan with phases"
+  - "Add Risks and Mitigations table"
+  - "Define Success Criteria (qualitative + quantitative)"
+  - "Link to Related Documents (epic, research, other ADRs)"
+  - "Use lowercase-hyphenated naming: adr-0001-slug.md"
 
 adr_statuses:
   proposed: "Under review, not yet approved"
@@ -81,11 +109,30 @@ adr_statuses:
 
 decision_categories:
   - "Technology choices (framework, database, language)"
-  - "Architecture patterns (monolith vs microservices)"
+  - "Architecture patterns (Agent Expert system)"
   - "Data modeling (schema design, caching)"
   - "Security approaches (auth, encryption)"
   - "Infrastructure (hosting, CI/CD)"
   - "Development practices (testing, branching)"
 
-# Learnings are AUTO-UPDATED by self-improve.md
-learnings: []
+# Learned from AgileFlow codebase exploration
+learnings:
+  - date: 2025-12-21
+    context: "Analyzed ADR-0001 structure"
+    insight: "ADRs have rich structure: Status/Date/Epic header, Context with research, Decision, Options Considered, Consequences, Implementation Plan, Risks table, Success Criteria, Related Docs"
+    source: "docs/03-decisions/adr-0001-agent-expert-system.md"
+
+  - date: 2025-12-21
+    context: "Analyzed ADR-Epic relationship"
+    insight: "ADRs link to epics that drove the decision; epics link back to ADRs for context"
+    source: "docs/03-decisions/adr-0001-agent-expert-system.md, docs/05-epics/ep-0001-agent-expert-pilot.md"
+
+  - date: 2025-12-21
+    context: "Analyzed Options Considered format"
+    insight: "Options include: Selected, Rejected (with reason), Deferred (for future consideration)"
+    source: "docs/03-decisions/adr-0001-agent-expert-system.md"
+
+  - date: 2025-12-21
+    context: "Analyzed Implementation Plan"
+    insight: "ADRs include phased implementation: Phase 1 (Pilot), Phase 2 (Full Rollout), Phase 3 (Refinement) with checkboxes"
+    source: "docs/03-decisions/adr-0001-agent-expert-system.md"

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

@@ -3,8 +3,8 @@
 # AUTO-UPDATED by self-improve.md after completing work
 
 domain: analytics
-last_updated: 2025-12-16
-version: 1.0
+last_updated: 2025-12-21
+version: 1.1
 
 files:
   tracking:
@@ -164,4 +164,50 @@ key_metrics:
 
 # Learnings are AUTO-UPDATED by self-improve.md
 # Do not edit manually - let the agent learn from experience
-learnings: []
+learnings:
+  - date: 2025-12-21
+    context: AgileFlow metrics tracking patterns
+    learning: |
+      AgileFlow tracks expertise system metrics via scripts/expertise-metrics.sh script.
+      This script analyzes all expert expertise.yaml files to generate health metrics:
+      - Total number of experts
+      - Experts with learnings vs without
+      - Average learnings per expert
+      - Most active experts (by learning count)
+      - Stale experts (not updated recently)
+      Use this pattern for analyzing distributed knowledge across multiple expertise files.
+
+  - date: 2025-12-21
+    context: Validation script health metrics
+    learning: |
+      AgileFlow validation scripts (scripts/validate-*.sh) provide structured health metrics
+      with PASS/WARN/FAIL counts. Key patterns:
+      - Each validation script outputs structured results (not just exit codes)
+      - Metrics include: total checks, passed, warnings, failures
+      - validate-all.sh aggregates metrics from individual validators
+      - Health dashboard can be built by parsing validation output
+      This pattern enables tracking system health trends over time.
+
+  - date: 2025-12-21
+    context: Story completion metrics from status.json
+    learning: |
+      AgileFlow tracks project progress via docs/09-agents/status.json.
+      Key metrics available:
+      - Total stories vs completed stories (completion percentage)
+      - Stories by status: backlog, in_progress, blocked, completed
+      - WIP (work in progress) count
+      - Stories by epic (epic-level progress)
+      - Average story age (time in current status)
+      Parse status.json to generate project health dashboards and velocity metrics.
+
+  - date: 2025-12-21
+    context: Agent activity tracking via log.jsonl
+    learning: |
+      AgileFlow tracks agent activity in docs/09-agents/bus/log.jsonl (append-only).
+      Each line is a JSON object with: timestamp, agent, action, metadata.
+      Key patterns:
+      - Append-only format (never edit existing lines)
+      - Parse line-by-line to analyze agent activity patterns
+      - Track agent invocation frequency, success rates, common errors
+      - Identify most active agents and underutilized agents
+      Use this for agent performance analytics and optimization insights.