agileflow 2.38.0 → 2.40.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.38.0",
+  "version": "2.40.0",
   "description": "AI-driven agile development system for Claude Code, Cursor, Windsurf, and more",
   "keywords": [
     "agile",

package/src/core/agents/configuration/hooks.md

@@ -148,7 +148,7 @@ chmod +x scripts/get-env.js
 
 ### Step 3: Create Claude Settings with Welcome Hook
 
-Create `.claude/settings.json` with basic SessionStart hook:
+Create `.claude/settings.json` with SessionStart hook that shows project status:
 
 ```json
 {
@@ -159,7 +159,7 @@ Create `.claude/settings.json` with basic SessionStart hook:
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🚀 AgileFlow loaded - Type /agileflow:help to see available commands'"
+            "command": "node scripts/agileflow-welcome.js 2>/dev/null || echo 'AgileFlow loaded'"
           }
         ]
       }
@@ -170,6 +170,79 @@ Create `.claude/settings.json` with basic SessionStart hook:
 }
 ```
 
+**Note**: The `agileflow-welcome.js` script outputs project status including version, branch, active stories, and recent commits. If it doesn't exist, it falls back to a simple message.
+
+### Step 3.5: Create Welcome Script
+
+Create `scripts/agileflow-welcome.js` for SessionStart:
+
+```javascript
+#!/usr/bin/env node
+/**
+ * agileflow-welcome.js - SessionStart hook script
+ * Outputs project status for Claude context
+ */
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const rootDir = process.cwd();
+
+// Get version
+let version = 'unknown';
+try {
+  const pkg = JSON.parse(fs.readFileSync(path.join(rootDir, 'package.json'), 'utf8'));
+  version = pkg.version || 'unknown';
+} catch (e) {}
+
+// Get git info
+let branch = 'unknown';
+let commit = 'unknown';
+let recentCommits = [];
+try {
+  branch = execSync('git branch --show-current', { encoding: 'utf8' }).trim();
+  commit = execSync('git rev-parse --short HEAD', { encoding: 'utf8' }).trim();
+  recentCommits = execSync('git log --oneline -3', { encoding: 'utf8' }).trim().split('\n');
+} catch (e) {}
+
+// Get AgileFlow status
+let activeStories = [];
+let wipCount = 0;
+try {
+  const statusPath = path.join(rootDir, 'docs/09-agents/status.json');
+  if (fs.existsSync(statusPath)) {
+    const status = JSON.parse(fs.readFileSync(statusPath, 'utf8'));
+    if (status.stories) {
+      Object.entries(status.stories).forEach(([id, story]) => {
+        if (story.status === 'in_progress') {
+          activeStories.push(`${id}: ${story.title}`);
+          wipCount++;
+        }
+      });
+    }
+  }
+} catch (e) {}
+
+// Output
+console.log(`Project: ${path.basename(rootDir)} v${version}`);
+console.log(`Branch: ${branch} (${commit})`);
+console.log(`---`);
+if (activeStories.length > 0) {
+  console.log(`Active Stories (${wipCount} WIP):`);
+  activeStories.forEach(s => console.log(`  - ${s}`));
+} else {
+  console.log('No stories in progress');
+}
+console.log(`---`);
+console.log('Recent commits:');
+recentCommits.slice(0, 3).forEach(c => console.log(`  ${c}`));
+```
+
+Make executable:
+```bash
+chmod +x scripts/agileflow-welcome.js
+```
+
 ### Step 4: Update .gitignore
 
 Auto-add .claude user-specific files to .gitignore:

package/src/core/agents/configuration/precompact.md

@@ -0,0 +1,253 @@
+---
+name: precompact
+description: Configure PreCompact hook for context preservation during conversation compacts
+tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+model: haiku
+---
+
+# PreCompact Configuration Agent
+
+Configures the PreCompact hook to preserve critical project context when Claude Code compacts conversations.
+
+## Prompt
+
+ROLE: PreCompact Configuration Specialist
+
+OBJECTIVE
+Set up the PreCompact hook system that outputs important project context before Claude compacts a conversation. This ensures critical information survives summarization.
+
+## What is PreCompact?
+
+When a Claude Code conversation fills its context window, it "compacts" (summarizes) to make room. The PreCompact hook runs before this happens, outputting context that should be preserved.
+
+**Benefits:**
+- Project conventions survive compacts (commit rules, file locations)
+- Active work context is preserved (current story, branch)
+- Key file paths are remembered
+- Team conventions don't get lost
+
+## Configuration Steps
+
+### Step 1: Check Prerequisites
+
+```bash
+# Verify .claude/settings.json exists (hooks system must be configured)
+if [ ! -f .claude/settings.json ]; then
+  echo "ERROR: Hooks system not configured. Run /agileflow:configure and select 'Hooks System' first."
+  exit 1
+fi
+
+# Check if PreCompact already configured
+if grep -q "PreCompact" .claude/settings.json 2>/dev/null; then
+  echo "PreCompact hook already configured"
+  ALREADY_CONFIGURED=true
+else
+  echo "PreCompact hook not yet configured"
+  ALREADY_CONFIGURED=false
+fi
+```
+
+### Step 2: Create PreCompact Script
+
+Create `scripts/precompact-context.sh`:
+
+```bash
+#!/bin/bash
+#
+# AgileFlow PreCompact Hook
+#
+# Outputs critical context that should survive conversation compacts.
+# Mirrors the context that /agileflow:babysit loads on startup.
+#
+
+# Get current version from package.json
+VERSION=$(node -p "require('./package.json').version" 2>/dev/null || echo "unknown")
+
+# Get current git branch
+BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
+
+# Get current story from status.json (if exists)
+CURRENT_STORY=""
+WIP_COUNT=0
+if [ -f "docs/09-agents/status.json" ]; then
+  CURRENT_STORY=$(node -p "
+    const s = require('./docs/09-agents/status.json');
+    const stories = Object.entries(s.stories || {})
+      .filter(([,v]) => v.status === 'in_progress')
+      .map(([k,v]) => k + ': ' + v.title)
+      .join(', ');
+    stories || 'None in progress';
+  " 2>/dev/null || echo "Unable to read")
+
+  WIP_COUNT=$(node -p "
+    const s = require('./docs/09-agents/status.json');
+    Object.values(s.stories || {}).filter(v => v.status === 'in_progress').length;
+  " 2>/dev/null || echo "0")
+fi
+
+# Get recent epics
+EPICS=""
+if [ -d "docs/05-epics" ]; then
+  EPICS=$(ls docs/05-epics/*.md 2>/dev/null | head -5 | xargs -I {} basename {} .md | tr '\n' ', ' | sed 's/,$//')
+fi
+
+# Get practices list
+PRACTICES=""
+if [ -d "docs/02-practices" ]; then
+  PRACTICES=$(ls docs/02-practices/*.md 2>/dev/null | head -8 | xargs -I {} basename {} .md | tr '\n' ', ' | sed 's/,$//')
+fi
+
+# Output context for Claude to preserve
+cat << EOF
+AGILEFLOW PROJECT CONTEXT (preserve during compact):
+====================================================
+
+## Project Status
+- Project: $(basename "$(pwd)") v${VERSION}
+- Branch: ${BRANCH}
+- Active Stories: ${CURRENT_STORY}
+- WIP Count: ${WIP_COUNT}
+
+## Key Files to Check After Compact
+- CLAUDE.md - Project system prompt with conventions
+- README.md - Project overview and setup
+- docs/09-agents/status.json - Story statuses and assignments
+- docs/02-practices/ - Codebase practices (${PRACTICES:-check folder})
+
+## Active Epics
+${EPICS:-Check docs/05-epics/ for epic files}
+
+## Key Conventions (from CLAUDE.md)
+$(grep -A 15 "## Key\|## Critical\|## Important\|CRITICAL:" CLAUDE.md 2>/dev/null | head -20 || echo "- Read CLAUDE.md for project conventions")
+
+## Recent Agent Activity
+$(tail -3 docs/09-agents/bus/log.jsonl 2>/dev/null | head -3 || echo "- Check docs/09-agents/bus/log.jsonl for recent activity")
+
+## Post-Compact Actions
+1. Re-read CLAUDE.md if unsure about conventions
+2. Check status.json for current story state
+3. Review docs/02-practices/ for implementation patterns
+4. Check git log for recent changes
+
+====================================================
+EOF
+```
+
+### Step 3: Make Script Executable
+
+```bash
+chmod +x scripts/precompact-context.sh
+```
+
+### Step 4: Add PreCompact Hook to Settings
+
+Read current `.claude/settings.json` and add PreCompact hook:
+
+```json
+{
+  "hooks": {
+    "PreCompact": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/precompact-context.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Important:** Merge this with existing hooks - don't overwrite SessionStart or other hooks.
+
+### Step 5: Test the Hook
+
+```bash
+bash scripts/precompact-context.sh
+```
+
+Should output project context. Verify it shows:
+- Project name and version
+- Current git branch
+- Active story (if any)
+- Key conventions from CLAUDE.md
+- Key directories
+
+### Step 6: Document in CLAUDE.md
+
+Add to CLAUDE.md:
+
+```markdown
+## PreCompact Hook
+
+**Purpose**: Preserve critical project context during conversation compacts.
+
+**Script**: `scripts/precompact-context.sh`
+
+**When it runs**: Automatically before Claude compacts the conversation (either manually via `/compact` or automatically when context fills).
+
+**What it preserves**:
+- Project version, git branch, active stories, WIP count
+- Active epics list and practices list
+- Key conventions from CLAUDE.md
+- Recent agent activity from bus/log.jsonl
+- Post-compact action reminders
+
+**To customize**: Edit `scripts/precompact-context.sh` to change what context is preserved.
+```
+
+## User Customization Options
+
+Ask the user what to include in the PreCompact output:
+
+```
+What information should be preserved during compacts?
+
+1. Project basics (version, branch, active story) - RECOMMENDED
+2. Full CLAUDE.md conventions
+3. Recent git commits
+4. Custom context (specify)
+
+Select options (default: 1):
+```
+
+## Output
+
+After configuration:
+
+```
+✅ PreCompact Hook Configured!
+
+Created: scripts/precompact-context.sh
+Updated: .claude/settings.json
+
+What happens now:
+- Before any compact, the hook runs automatically
+- Critical project context is output and preserved
+- Your conventions and current work survive summarization
+
+Test it now:
+  bash scripts/precompact-context.sh
+
+To trigger a compact manually:
+  /compact "Additional focus areas to preserve"
+```
+
+## Rules
+
+- REQUIRE hooks system to be configured first
+- CREATE scripts/precompact-context.sh with intelligent defaults
+- MERGE PreCompact hook into existing settings.json (don't overwrite)
+- TEST the script before confirming success
+- DOCUMENT in CLAUDE.md for future reference
+- OFFER customization options for what to preserve

package/src/core/commands/configure.md

@@ -36,6 +36,7 @@ Each feature is handled by a specialized agent:
 - **Auto-Archival** (`AgileFlow:agents:configuration:archival`) - Status.json size management
 - **CI/CD** (`AgileFlow:agents:configuration:ci`) - Automated testing and quality checks
 - **Status Line** (`AgileFlow:agents:configuration:status-line`) - Custom Claude Code status bar with AgileFlow context
+- **PreCompact** (`AgileFlow:agents:configuration:precompact`) - Context preservation during conversation compacts
 
 ## Detection Phase (Run First)
 
@@ -124,6 +125,15 @@ else
   STATUSLINE_CONFIGURED=false
 fi
 
+# Check PreCompact hook
+if [ -f scripts/precompact-context.sh ] && grep -q "PreCompact" .claude/settings.json 2>/dev/null; then
+  echo "✅ PreCompact hook configured"
+  PRECOMPACT_CONFIGURED=true
+else
+  echo "❌ PreCompact hook not configured"
+  PRECOMPACT_CONFIGURED=false
+fi
+
 echo "===================================="
 echo ""
 ```
@@ -164,7 +174,8 @@ The AskUserQuestion tool allows you to prompt the user for input. It requires XM
     {"label": "Hooks System", "description": "Set up event-driven automation"},
     {"label": "Auto-Archival", "description": "Manage status.json file size"},
     {"label": "CI/CD", "description": "Set up automated testing"},
-    {"label": "Status Line", "description": "Custom status bar with story/WIP/context info"}
+    {"label": "Status Line", "description": "Custom status bar with story/WIP/context info"},
+    {"label": "PreCompact Hook", "description": "Preserve project context during conversation compacts"}
   ]
 }]</parameter>
 </invoke>
@@ -183,7 +194,8 @@ The AskUserQuestion tool allows you to prompt the user for input. It requires XM
     {"label": "Hooks System", "description": "Set up event-driven automation"},
     {"label": "Auto-Archival", "description": "Manage status.json file size"},
     {"label": "CI/CD", "description": "Set up automated testing"},
-    {"label": "Status Line", "description": "Custom status bar with story/WIP/context info"}
+    {"label": "Status Line", "description": "Custom status bar with story/WIP/context info"},
+    {"label": "PreCompact Hook", "description": "Preserve project context during conversation compacts"}
   ]
 }]</parameter>
 </invoke>
@@ -205,6 +217,7 @@ Available options:
 4. Auto-Archival (status.json size management)
 5. CI/CD (automated testing and quality checks)
 6. Status Line (custom status bar with story/WIP/context info)
+7. PreCompact Hook (preserve context during conversation compacts)
 
 You can select multiple options. Features already configured are marked with ✅.
 
@@ -215,6 +228,7 @@ Current status:
 - Auto-Archival: [✅ Configured / ❌ Not configured]
 - CI/CD: [✅ Configured / ❌ Not configured]
 - Status Line: [✅ Configured / ❌ Not configured]
+- PreCompact Hook: [✅ Configured / ❌ Not configured]
 
 Select features to configure:
 ```
@@ -287,6 +301,16 @@ Task({
 })
 ```
 
+#### PreCompact Agent
+
+```javascript
+Task({
+  subagent_type: "AgileFlow:agents:configuration:precompact",
+  description: "Configure PreCompact hook",
+  prompt: "Set up the PreCompact hook to preserve project context during conversation compacts. Create scripts/precompact-context.sh, add PreCompact hook to .claude/settings.json, and document in CLAUDE.md."
+})
+```
+
 ### Parallel Execution
 
 **CRITICAL**: Spawn multiple agents in a **single message** for parallel execution:
@@ -308,13 +332,15 @@ Task({ subagent_type: "AgileFlow:agents:configuration:hooks", ... })
 Some agents have dependencies:
 - **Auto-Archival** depends on **Hooks System** (needs .claude/settings.json to exist)
 - **Status Line** depends on **Hooks System** (needs .claude/settings.json to exist)
+- **PreCompact** depends on **Hooks System** (needs .claude/settings.json to exist)
 - **Git Config**, **Attribution**, and **CI/CD** are independent (can run in parallel)
 
 **Execution Strategy**:
 1. If user selects Git + Attribution + CI: Run in parallel (no dependencies)
 2. If user selects Hooks + Archival: Run hooks FIRST, then archival (dependency)
 3. If user selects Hooks + Status Line: Run hooks FIRST, then status line (dependency)
-4. If user selects all 6: Run Git + Attribution + CI in parallel, wait, then run Hooks, wait, then run Archival + Status Line in parallel
+4. If user selects Hooks + PreCompact: Run hooks FIRST, then precompact (dependency)
+5. If user selects all 7: Run Git + Attribution + CI in parallel, wait, then run Hooks, wait, then run Archival + Status Line + PreCompact in parallel
 
 ## Agent Result Handling
 
@@ -330,6 +356,7 @@ Results:
 - Auto-Archival: [✅ Configured / ❌ Failed / ⏭️ Skipped]
 - CI/CD: [✅ Configured / ❌ Failed / ⏭️ Skipped]
 - Status Line: [✅ Configured / ❌ Failed / ⏭️ Skipped]
+- PreCompact Hook: [✅ Configured / ❌ Failed / ⏭️ Skipped]
 
 Next steps:
 [Agent-specific next steps from results]
@@ -396,6 +423,13 @@ If an agent fails:
 - Document in CLAUDE.md
 - **CRITICAL**: Remind user to restart Claude Code
 
+### 7. PreCompact Hook (precompact agent)
+- Create `scripts/precompact-context.sh` script
+- Add `PreCompact` hook to `.claude/settings.json`
+- Script outputs: version, branch, active story, key conventions
+- Document in CLAUDE.md
+- Hook runs automatically before conversation compacts
+
 ## Example Workflow
 
 ```
@@ -409,9 +443,10 @@ If an agent fails:
    ❌ Auto-archival not configured
    ❌ CI/CD not configured
    ❌ Status line not configured
+   ❌ PreCompact hook not configured
 
 3. Orchestrator presents menu using AskUserQuestion:
-   "Select features to configure: [Git Repository, Attribution Settings, Hooks System, Auto-Archival, CI/CD, Status Line]"
+   "Select features to configure: [Git Repository, Attribution Settings, Hooks System, Auto-Archival, CI/CD, Status Line, PreCompact Hook]"
 
 4. User selects: ["Attribution Settings", "Hooks System", "CI/CD"]
 

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."