agileflow 2.43.0 → 2.45.0

package/scripts/precompact-context.sh

@@ -0,0 +1,123 @@
+#!/bin/bash
+#
+# AgileFlow PreCompact Hook
+# Outputs critical context that should survive conversation compaction.
+#
+
+# 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
+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 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
+
+# Get active epics
+EPICS=""
+if [ -d "docs/05-epics" ]; then
+  EPICS=$(ls docs/05-epics/ 2>/dev/null | head -5 | tr '\n' ',' | sed 's/,$//')
+fi
+
+# Detect active commands and extract their Compact Summaries
+COMMAND_SUMMARIES=""
+if [ -f "docs/09-agents/session-state.json" ]; then
+  ACTIVE_COMMANDS=$(node -p "
+    const s = require('./docs/09-agents/session-state.json');
+    (s.active_commands || []).map(c => c.name).join(' ');
+  " 2>/dev/null || echo "")
+
+  for ACTIVE_COMMAND in $ACTIVE_COMMANDS; do
+    [ -z "$ACTIVE_COMMAND" ] && continue
+
+    COMMAND_FILE=""
+    if [ -f "packages/cli/src/core/commands/${ACTIVE_COMMAND}.md" ]; then
+      COMMAND_FILE="packages/cli/src/core/commands/${ACTIVE_COMMAND}.md"
+    elif [ -f ".agileflow/commands/${ACTIVE_COMMAND}.md" ]; then
+      COMMAND_FILE=".agileflow/commands/${ACTIVE_COMMAND}.md"
+    elif [ -f ".claude/commands/agileflow/${ACTIVE_COMMAND}.md" ]; then
+      COMMAND_FILE=".claude/commands/agileflow/${ACTIVE_COMMAND}.md"
+    fi
+
+    if [ ! -z "$COMMAND_FILE" ]; then
+      SUMMARY=$(node -e "
+        const fs = require('fs');
+        const content = fs.readFileSync('$COMMAND_FILE', 'utf8');
+        const match = content.match(/<!-- COMPACT_SUMMARY_START[\\s\\S]*?-->([\\s\\S]*?)<!-- COMPACT_SUMMARY_END -->/);
+        if (match) {
+          console.log('## ACTIVE COMMAND: /agileflow:${ACTIVE_COMMAND}');
+          console.log('');
+          console.log(match[1].trim());
+        }
+      " 2>/dev/null || echo "")
+
+      if [ ! -z "$SUMMARY" ]; then
+        COMMAND_SUMMARIES="${COMMAND_SUMMARIES}
+
+${SUMMARY}"
+      fi
+    fi
+  done
+fi
+
+# Output context
+cat << EOF
+AGILEFLOW PROJECT CONTEXT (preserve during compact):
+
+## Project Status
+- Project: AgileFlow 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 "")
+EOF
+
+# Output active command summaries
+if [ ! -z "$COMMAND_SUMMARIES" ]; then
+  echo "$COMMAND_SUMMARIES"
+fi
+
+cat << EOF
+
+## 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

package/scripts/validate-expertise.sh

@@ -0,0 +1,259 @@
+#!/bin/bash
+#
+# validate-expertise.sh - Validate Agent Expert expertise.yaml files
+#
+# Purpose: Ensure expertise files remain accurate and useful over time
+#
+# Checks performed:
+#   1. Schema validation (required fields: domain, last_updated, version)
+#   2. Staleness check (last_updated > 30 days old)
+#   3. File size check (warn if > 200 lines)
+#   4. Learnings check (warn if empty - never self-improved)
+#
+# Usage:
+#   ./scripts/validate-expertise.sh           # Validate all expertise files
+#   ./scripts/validate-expertise.sh database  # Validate specific domain
+#   ./scripts/validate-expertise.sh --help    # Show help
+#
+# Exit codes:
+#   0 - All checks passed
+#   1 - One or more checks failed (warnings don't cause failure)
+#
+
+set -e
+
+# Colors
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Configuration
+EXPERTS_DIR="packages/cli/src/core/experts"
+STALE_THRESHOLD_DAYS=30
+MAX_LINES=200
+
+# Counters
+TOTAL=0
+PASSED=0
+WARNINGS=0
+FAILED=0
+
+# Help message
+show_help() {
+    echo "Usage: $0 [domain]"
+    echo ""
+    echo "Validate Agent Expert expertise.yaml files"
+    echo ""
+    echo "Options:"
+    echo "  domain    Validate only the specified domain (e.g., 'database', 'testing')"
+    echo "  --help    Show this help message"
+    echo ""
+    echo "Checks performed:"
+    echo "  - Schema validation (domain, last_updated, version fields)"
+    echo "  - Staleness check (last_updated > $STALE_THRESHOLD_DAYS days)"
+    echo "  - File size check (> $MAX_LINES lines)"
+    echo "  - Learnings check (empty learnings array)"
+    echo ""
+    echo "Examples:"
+    echo "  $0                 # Validate all expertise files"
+    echo "  $0 database        # Validate only database domain"
+    echo "  $0 --help          # Show this help"
+}
+
+# Check if yq is available (for better YAML parsing)
+has_yq() {
+    command -v yq &> /dev/null
+}
+
+# Extract YAML field using grep (fallback if yq not available)
+get_yaml_field() {
+    local file="$1"
+    local field="$2"
+    grep "^${field}:" "$file" 2>/dev/null | sed "s/^${field}:[[:space:]]*//" | tr -d '"' || echo ""
+}
+
+# Check if learnings is empty
+learnings_empty() {
+    local file="$1"
+    # Check for "learnings: []" or learnings with only comments
+    if grep -q "^learnings: \[\]" "$file" 2>/dev/null; then
+        return 0  # Empty
+    fi
+    # Check if there's actual content after learnings:
+    local after_learnings
+    after_learnings=$(sed -n '/^learnings:/,/^[a-z]/p' "$file" | grep -v "^#" | grep -v "^learnings:" | grep -v "^$" | head -1)
+    if [ -z "$after_learnings" ]; then
+        return 0  # Empty
+    fi
+    return 1  # Has content
+}
+
+# Get file line count
+get_line_count() {
+    wc -l < "$1" | tr -d ' '
+}
+
+# Calculate days since date
+days_since() {
+    local date_str="$1"
+    local date_epoch
+    local now_epoch
+
+    # Handle different date formats
+    if [[ "$date_str" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]]; then
+        date_epoch=$(date -d "$date_str" +%s 2>/dev/null || date -j -f "%Y-%m-%d" "$date_str" +%s 2>/dev/null)
+    else
+        echo "999"  # Invalid date
+        return
+    fi
+
+    now_epoch=$(date +%s)
+    echo $(( (now_epoch - date_epoch) / 86400 ))
+}
+
+# Validate a single expertise file
+validate_expertise() {
+    local domain="$1"
+    local file="$EXPERTS_DIR/$domain/expertise.yaml"
+    local status="PASS"
+    local issues=()
+
+    TOTAL=$((TOTAL + 1))
+
+    # Check file exists
+    if [ ! -f "$file" ]; then
+        echo -e "${RED}FAIL${NC}  $domain - File not found: $file"
+        FAILED=$((FAILED + 1))
+        return 1
+    fi
+
+    # Schema validation
+    local domain_field version last_updated
+    domain_field=$(get_yaml_field "$file" "domain")
+    version=$(get_yaml_field "$file" "version")
+    last_updated=$(get_yaml_field "$file" "last_updated")
+
+    if [ -z "$domain_field" ]; then
+        issues+=("missing 'domain' field")
+        status="FAIL"
+    fi
+
+    if [ -z "$version" ]; then
+        issues+=("missing 'version' field")
+        status="FAIL"
+    fi
+
+    if [ -z "$last_updated" ]; then
+        issues+=("missing 'last_updated' field")
+        status="FAIL"
+    fi
+
+    # Staleness check
+    if [ -n "$last_updated" ]; then
+        local days_old
+        days_old=$(days_since "$last_updated")
+        if [ "$days_old" -gt "$STALE_THRESHOLD_DAYS" ]; then
+            issues+=("stale (${days_old} days since update)")
+            if [ "$status" = "PASS" ]; then
+                status="WARN"
+            fi
+        fi
+    fi
+
+    # File size check
+    local line_count
+    line_count=$(get_line_count "$file")
+    if [ "$line_count" -gt "$MAX_LINES" ]; then
+        issues+=("large file (${line_count} lines > ${MAX_LINES})")
+        if [ "$status" = "PASS" ]; then
+            status="WARN"
+        fi
+    fi
+
+    # Learnings check
+    if learnings_empty "$file"; then
+        issues+=("no learnings recorded (never self-improved)")
+        if [ "$status" = "PASS" ]; then
+            status="WARN"
+        fi
+    fi
+
+    # Output result
+    case "$status" in
+        PASS)
+            echo -e "${GREEN}PASS${NC}  $domain"
+            PASSED=$((PASSED + 1))
+            ;;
+        WARN)
+            echo -e "${YELLOW}WARN${NC}  $domain - ${issues[*]}"
+            WARNINGS=$((WARNINGS + 1))
+            ;;
+        FAIL)
+            echo -e "${RED}FAIL${NC}  $domain - ${issues[*]}"
+            FAILED=$((FAILED + 1))
+            ;;
+    esac
+}
+
+# Main
+main() {
+    # Handle help
+    if [ "$1" = "--help" ] || [ "$1" = "-h" ]; then
+        show_help
+        exit 0
+    fi
+
+    # Find script directory and change to repo root
+    local script_dir
+    script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    cd "$script_dir/.."
+
+    # Check experts directory exists
+    if [ ! -d "$EXPERTS_DIR" ]; then
+        echo -e "${RED}Error:${NC} Experts directory not found: $EXPERTS_DIR"
+        echo "Are you running this from the repository root?"
+        exit 1
+    fi
+
+    echo -e "${BLUE}Validating Agent Expert Files${NC}"
+    echo "================================"
+    echo ""
+
+    # Validate specific domain or all
+    if [ -n "$1" ]; then
+        # Single domain
+        if [ ! -d "$EXPERTS_DIR/$1" ]; then
+            echo -e "${RED}Error:${NC} Domain not found: $1"
+            echo "Available domains:"
+            ls -1 "$EXPERTS_DIR" | grep -v templates | grep -v README
+            exit 1
+        fi
+        validate_expertise "$1"
+    else
+        # All domains
+        for dir in "$EXPERTS_DIR"/*/; do
+            local domain
+            domain=$(basename "$dir")
+            # Skip templates directory
+            if [ "$domain" = "templates" ]; then
+                continue
+            fi
+            validate_expertise "$domain"
+        done
+    fi
+
+    # Summary
+    echo ""
+    echo "================================"
+    echo -e "Total: $TOTAL | ${GREEN}Passed: $PASSED${NC} | ${YELLOW}Warnings: $WARNINGS${NC} | ${RED}Failed: $FAILED${NC}"
+
+    # Exit code
+    if [ "$FAILED" -gt 0 ]; then
+        exit 1
+    fi
+    exit 0
+}
+
+main "$@"

package/src/core/commands/context.md

@@ -1,6 +1,6 @@
 ---
 description: Generate context export for web AI tools
-argument-hint: [MODE=full|export|note|research] [NOTE=<text>] [TOPIC=<text>] [DETAILS=<text>]
+argument-hint: [MODE=full|export|note|research|import] [NOTE=<text>] [TOPIC=<text>] [DETAILS=<text>] [CONTENT=<text>] [SOURCE=<url>]
 ---
 
 <!-- COMPACT_SUMMARY_START
@@ -12,11 +12,12 @@ This section is extracted by the PreCompact hook to preserve essential context a
 Web AI Context Manager - Generates/exports/manages project context briefs for web AI tools (ChatGPT, Perplexity, Gemini, Claude web).
 
 ### Critical Behavioral Rules
-- **ALWAYS create TodoWrite list** for MODE=full and MODE=research to track multi-step workflows
+- **ALWAYS create TodoWrite list** for MODE=full, MODE=research, and MODE=import to track multi-step workflows
 - **Diff-first approach**: Show changes and wait for YES/NO confirmation before ANY file writes
 - **Preserve user-written content**: Only update managed sections in docs/context.md
 - **No writes in export mode**: MODE=export outputs text only, never writes files
 - **Research is two-step**: STEP 1 generates prompt, STEP 2 stores results when user returns
+- **Import is one-step**: Process CONTENT immediately and create research file
 - **Link research files**: Always reference research from ADRs/Epics/Stories that use it
 
 ### Core Workflow
@@ -50,6 +51,16 @@ Web AI Context Manager - Generates/exports/manages project context briefs for we
 7. Ask if user wants ADR/Epic/Story created from research
 8. Add research reference to created ADR/Epic/Story
 
+**MODE=import**
+1. Create todo list tracking: validate inputs, process content, extract key points, extract code, generate actions, suggest stories, format research file, save, update index
+2. Validate TOPIC and CONTENT are provided
+3. Process raw content (transcript, article, etc.) by: summarizing key points, extracting code snippets, generating action items, suggesting user stories
+4. Format into structured research file with all extracted sections
+5. Save to docs/10-research/YYYYMMDD-topic-slug.md
+6. Update docs/10-research/README.md index
+7. Ask if user wants ADR/Epic/Story created from imported content
+8. Add research reference to created ADR/Epic/Story
+
 ### Key Files
 - docs/context.md - Main context brief (managed sections + user content)
 - docs/10-research/YYYYMMDD-topic-slug.md - Research results storage
@@ -68,9 +79,11 @@ Generate, export, or manage the web AI context brief.
 ROLE: Web AI Context Manager
 
 INPUTS (optional)
-- MODE=full|export|note|research (default: full)
+- MODE=full|export|note|research|import (default: full)
 - NOTE=<text> (required if MODE=note)
-- TOPIC=<text> (required if MODE=research)
+- TOPIC=<text> (required if MODE=research or MODE=import)
+- CONTENT=<text> (required if MODE=import - raw content to process)
+- SOURCE=<url> (optional for MODE=import - original source URL)
 
 ---
 
@@ -249,6 +262,124 @@ When user pastes research results back:
 
 ---
 
+## MODE=import
+Import raw content (transcripts, articles, notes) and convert to structured research file.
+
+### Input
+- TOPIC=<text> (required - name for the research file)
+- CONTENT=<text> (required - raw content to process: transcript, article, notes, etc.)
+- SOURCE=<url> (optional - original source URL for reference)
+
+### Use Cases
+- YouTube video transcripts
+- Conference talk notes
+- Podcast transcripts
+- Blog posts / articles
+- Documentation pages
+- Forum discussions / Stack Overflow threads
+- Meeting notes
+
+### TODO LIST TRACKING
+**CRITICAL**: Immediately create a todo list using TodoWrite tool to track import workflow:
+```
+1. Validate TOPIC and CONTENT are provided
+2. Analyze and summarize key points from content
+3. Extract any code snippets
+4. Generate action items based on content
+5. Create user story suggestions (if applicable)
+6. Format into structured research markdown
+7. Show diff for review
+8. Save to docs/10-research/YYYYMMDD-topic-slug.md
+9. Update docs/10-research/README.md index
+10. Ask about creating ADR/Epic/Story from research
+```
+
+Mark each step complete as you finish it.
+
+### Processing Steps
+
+1. **Validate Inputs**
+   - Verify TOPIC is provided (error if missing)
+   - Verify CONTENT is provided (error if missing)
+   - SOURCE is optional but recommended for attribution
+
+2. **Analyze Content**
+   Extract from the raw content:
+   - **Summary**: 2-3 paragraph TL;DR of the main points
+   - **Key Findings**: Bullet list of important takeaways
+   - **Code Snippets**: Any code blocks, commands, or configuration (preserve exactly)
+   - **Action Items**: Concrete next steps mentioned or implied
+   - **Story Suggestions**: Potential user stories/epics based on content
+
+3. **Format Research File**
+   ```markdown
+   # [Topic Title]
+
+   **Import Date**: YYYY-MM-DD
+   **Topic**: [original topic]
+   **Source**: [URL if provided, or "Direct import"]
+   **Content Type**: [transcript/article/notes/etc.]
+
+   ## Summary
+   [2-3 paragraph executive summary of the content]
+
+   ## Key Findings
+   - [Main point 1 with details]
+   - [Main point 2 with details]
+   - [Main point 3 with details]
+   - ...
+
+   ## Code Snippets
+   [Preserve all code snippets exactly as they appeared]
+   ```language
+   [code here]
+   ```
+
+   ## Action Items
+   - [ ] [Action 1 - concrete next step]
+   - [ ] [Action 2 - concrete next step]
+   - [ ] [Action 3 - concrete next step]
+
+   ## Story Suggestions
+   [If content suggests feature work, list potential stories]
+
+   ### Potential Epic: [Epic Title]
+   - **US-XXXX**: [Story 1 title]
+     - AC: [acceptance criteria bullet]
+   - **US-XXXX**: [Story 2 title]
+     - AC: [acceptance criteria bullet]
+
+   ## Raw Content Reference
+   <details>
+   <summary>Original content (click to expand)</summary>
+
+   [First 500 chars of original content for reference...]
+   </details>
+
+   ## References
+   - Source: [URL or "Direct import"]
+   - Import date: [YYYY-MM-DD]
+   ```
+
+4. **Save and Index**
+   - Save to `docs/10-research/YYYYMMDD-<topic-slug>.md`
+   - Update `docs/10-research/README.md` with new entry
+
+5. **Offer Next Steps**
+   Ask user via AskUserQuestion:
+   - Create an ADR referencing this research?
+   - Create an Epic/Stories based on the story suggestions?
+   - Link this research to an existing Epic/Story?
+
+### Rules
+- Diff-first; YES/NO before writing research file
+- Preserve ALL code snippets exactly as provided
+- Generate actionable items (not vague suggestions)
+- Keep raw content reference collapsed to save space
+- Always update the research index
+
+---
+
 ## Usage Examples
 
 ```bash
@@ -262,9 +393,13 @@ When user pastes research results back:
 # Add a quick note
 /agileflow:context MODE=note NOTE="User reported auth bug in production"
 
-# Build research prompt
+# Build research prompt for web AI
 /agileflow:context MODE=research TOPIC="Implement OAuth 2.0 with Google"
 /agileflow:context MODE=research TOPIC="Add Stripe payments" DETAILS="Launch by end of sprint"
+
+# Import external content (transcripts, articles, notes)
+/agileflow:context MODE=import TOPIC="React Server Components" CONTENT="[paste transcript here]"
+/agileflow:context MODE=import TOPIC="Stripe Webhooks Tutorial" SOURCE="https://youtube.com/..." CONTENT="[paste transcript here]"
 ```
 
 ---
@@ -276,3 +411,4 @@ Depending on MODE:
 - **export**: Text output ready to paste into web AI tool
 - **note**: Appended note to docs/context.md (after YES confirmation)
 - **research**: Research prompt in code block ready to paste into web AI tool
+- **import**: Processed research file saved to docs/10-research/ (after YES confirmation)