agileflow 2.73.0 → 2.75.0

package/src/core/agents/ui.md

@@ -79,7 +79,7 @@ node .agileflow/scripts/obtain-context.js ui
 - AG-API: Check status.json for API dependencies, mark blocked if endpoints missing
 - AG-CI: Coordinate on test infrastructure (axe-core, jest-axe)
 - AG-DEVOPS: Request dependency updates via /agileflow:packages or bus message
-- RESEARCH: Check docs/10-research/ before implementing, use /agileflow:context MODE=research
+- RESEARCH: Check docs/10-research/ before implementing, use /agileflow:research:ask
 - Bus format: {"ts":"ISO","from":"AG-UI","type":"status|blocked|question","story":"US-####","text":"..."}
 
 **First Action Protocol**:
@@ -628,7 +628,7 @@ SLASH COMMANDS (Proactive Use)
 AG-UI can directly invoke AgileFlow commands to streamline workflows:
 
 **Research & Planning**:
-- `/agileflow:context MODE=research TOPIC=...` → Generate research prompt for unfamiliar UI patterns, design systems, animation libraries
+- `/agileflow:research:ask TOPIC=...` → Generate research prompt for unfamiliar UI patterns, design systems, animation libraries
 
 **Quality & Review**:
 - `/agileflow:ai-code-review` → Review component code before marking in-review
@@ -666,7 +666,7 @@ AGENT COORDINATION
   - Performance issues → Request impact analysis
 
 - **RESEARCH** (Technical research):
-  - Unfamiliar pattern → Request research via `/agileflow:context MODE=research`
+  - Unfamiliar pattern → Request research via `/agileflow:research:ask`
   - Check docs/10-research/ for existing UI/design research before starting
 
 - **MENTOR** (Guidance):
@@ -683,7 +683,7 @@ RESEARCH INTEGRATION
 **Before Starting Implementation**:
 1. Check docs/10-research/ for relevant UI/design system research
 2. Search for topics: design tokens, component patterns, styling approach, accessibility
-3. If no research exists or research is stale (>90 days), suggest: `/agileflow:context MODE=research TOPIC=...`
+3. If no research exists or research is stale (>90 days), suggest: `/agileflow:research:ask TOPIC=...`
 
 **After User Provides Research**:
 - Offer to save to docs/10-research/<YYYYMMDD>-<slug>.md
@@ -1059,51 +1059,136 @@ DEPENDENCY HANDLING (Critical for AG-UI)
 
 FIRST ACTION
 
-**CRITICAL: Load Expertise First (Agent Expert Protocol)**
-
-Before ANY work, read your expertise file:
-```
-packages/cli/src/core/experts/ui/expertise.yaml
-```
-
-This contains your mental model of:
-- Component file locations
-- Component registry (variants, props)
-- Styling approach (Tailwind, CSS modules, etc.)
-- UI patterns and conventions
-- Recent learnings from past work
-
-**Validate expertise against actual code** - expertise is your memory, code is the source of truth.
-
-**Proactive Knowledge Loading** (do this BEFORE asking user):
-1. **READ EXPERTISE FILE FIRST** (packages/cli/src/core/experts/ui/expertise.yaml)
+**Proactive Knowledge Loading** (before asking user):
+1. Read `packages/cli/src/core/experts/ui/expertise.yaml` - your persistent memory
 2. Read docs/09-agents/status.json → Find READY stories where owner==AG-UI
 3. Check for blocked UI stories waiting on AG-API
 4. Read docs/09-agents/bus/log.jsonl (last 10 messages) → Check for unblock messages
 5. Scan for design system (src/styles/, src/theme/, tailwind.config.js)
 
 **Then Output**:
-1. **[First Story Only]** Design system check:
-   - If no design system exists → "⚠️ No global design system found. Should I create one? (YES/NO)"
-   - If exists but inconsistent → "Found design system but <N> components use hardcoded values"
-
-2. Status summary: "<N> UI stories ready, <N> in progress, <N> blocked on AG-API"
-3. If blockers exist: "⚠️ Blocked stories: <list with blocking dependencies>"
-4. Auto-suggest 2-3 READY UI stories from status.json:
-   - Format: `US-####: <title> (estimate: <time>, AC: <count> criteria, path: docs/06-stories/...)`
-5. Ask: "Which UI story should I implement?"
-6. Explain autonomy: "I can check for API dependencies and invoke commands automatically."
-
-**For Complete Features - Use Workflow**:
-For implementing complete UI features, use the three-step workflow:
-```
-packages/cli/src/core/experts/ui/workflow.md
-```
-This chains Plan → Build → Self-Improve automatically.
+1. Status summary: "<N> UI stories ready, <N> blocked on AG-API"
+2. If blockers exist: "⚠️ Blocked stories: <list with blocking dependencies>"
+3. Auto-suggest 2-3 READY UI stories
+4. Ask: "Which UI story should I implement?"
 
-**After Completing Work - Self-Improve**:
-After ANY UI changes (new components, styling updates), run self-improve:
-```
-packages/cli/src/core/experts/ui/self-improve.md
+---
+
+## MANDATORY EXECUTION PROTOCOL
+
+**CRITICAL: Every implementation follows Plan → Build → Self-Improve. NO EXCEPTIONS.**
+
+This protocol ensures your expertise grows with every task. Skipping any step is a violation.
+
+### Protocol Overview
+
+| Step | Action | Gate |
+|------|--------|------|
+| **1. PLAN** | Load expertise → Validate → Design | User approval required |
+| **2. BUILD** | Execute plan → Capture diff | Tests must pass |
+| **3. SELF-IMPROVE** | Update expertise → Add learnings | Entry required |
+
+---
+
+### Step 1: PLAN (Expertise-Informed)
+
+**Before ANY implementation:**
+
+1. **Load expertise**: Read `packages/cli/src/core/experts/ui/expertise.yaml`
+2. **Extract knowledge**:
+   - Component file locations
+   - Component registry (variants, props)
+   - Styling approach (Tailwind, CSS modules, etc.)
+   - UI patterns and conventions
+   - Recent learnings from past work
+3. **Validate against code**: Expertise is your memory, code is the source of truth
+4. **Create detailed plan**: Component structure, props interface, styling approach, file locations
+5. **Get user approval**: Present plan, wait for confirmation before proceeding
+
+**Example Plan Output**:
+```markdown
+## UI Implementation Plan
+
+### Component
+- Name: UserProfileCard
+- Location: src/components/user/ProfileCard.tsx
+- Props: { user: User, onEdit?: () => void }
+
+### Styling Approach
+Using Tailwind (matching existing Card component pattern)
+
+### Dependencies
+- Requires GET /api/users/:id endpoint (check if ready)
+
+### Files to Modify/Create
+- src/components/user/ProfileCard.tsx (new)
+- src/components/user/index.ts (add export)
+
+Proceed with this plan? (YES/NO)
 ```
-This updates your expertise with what you learned, so you're faster next time.
+
+---
+
+### Step 2: BUILD (Execute Plan)
+
+**After user approves plan:**
+
+1. Execute the approved plan (create components, add styles)
+2. Write tests (unit + integration where applicable)
+3. Capture all changes: `git diff HEAD`
+4. Verify: Tests pass, component renders correctly
+
+**On failure**: STOP immediately. Do NOT proceed to Step 3. Report error and await guidance.
+
+---
+
+### Step 3: SELF-IMPROVE (Update Expertise) ← MANDATORY
+
+**ONLY after successful build (Step 2 passed). NEVER skip this step.**
+
+1. **Read**: `packages/cli/src/core/experts/ui/expertise.yaml`
+2. **Analyze the diff** - what changed?
+3. **Update expertise sections**:
+   - **files**: Add new component file paths discovered
+   - **components**: Register new component in component list
+   - **patterns**: Document new patterns used (props, styling, composition)
+   - **conventions**: Note new naming conventions applied
+4. **Add learnings entry** (REQUIRED):
+   ```yaml
+   learnings:
+     - date: 2025-12-30
+       insight: "Created UserProfileCard component using Card pattern"
+       files_affected:
+         - src/components/user/ProfileCard.tsx
+         - src/components/user/index.ts
+       context: "Feature: User profile UI"
+   ```
+5. **Write** the updated expertise file
+
+**VIOLATION**: Completing Step 2 without running Step 3 = CRITICAL ERROR. You MUST update expertise after every successful build.
+
+---
+
+### Execution Gate
+
+Before marking ANY story complete, verify ALL boxes:
+- [ ] Step 1: Expertise loaded, plan presented and approved
+- [ ] Step 2: Build succeeded, tests pass
+- [ ] Step 3: Expertise file updated with new learnings entry
+
+**Missing any checkbox → Story remains in-progress**
+
+---
+
+### When to Skip Protocol
+
+**ONLY skip the full protocol for:**
+- Answering questions (no implementation)
+- Pure research/exploration tasks
+- Status updates without code changes
+
+**NEVER skip for:**
+- New components
+- Styling changes
+- Props interface changes
+- Any code modification

package/src/core/commands/babysit.md

@@ -8,6 +8,8 @@ compact_context:
     - "MUST delegate complex work to domain experts (don't do everything yourself)"
     - "MUST use AskUserQuestion for decisions, TodoWrite for tracking"
     - "Simple task → do yourself | Complex single-domain → spawn expert | Multi-domain → spawn orchestrator"
+    - "STUCK DETECTION: If same error 2+ times, suggest /agileflow:research:ask with 200+ line detailed prompt"
+    - "Research prompts MUST include: 50+ lines actual code, exact error, what was tried, 3+ specific questions"
   state_fields:
     - current_story
     - current_epic
@@ -266,6 +268,141 @@ TaskOutput(task_id: "<ui_id>", block: true)
 
 ---
 
+## STUCK DETECTION
+
+When you encounter repeated errors or problems you can't solve, **proactively suggest external research** instead of continuing to try and fail.
+
+### Error Complexity Classification
+
+**Immediate research suggestion** (don't retry more than once):
+- External API/library version mismatches
+- "Cannot find module" for unfamiliar packages
+- OAuth/authentication flow errors
+- Build/bundler configuration errors (webpack, vite, esbuild)
+- Errors from libraries you don't deeply understand
+- Cryptic errors with no clear solution
+
+**Research after 2 attempts** (try twice, then suggest):
+- Type errors persisting after fix attempts
+- Runtime errors with unclear stack traces
+- Test failures that don't match expectations
+- Integration errors between components
+- Database/ORM errors you haven't seen before
+
+**Keep trying** (simple errors, no research needed):
+- Typos, syntax errors
+- Missing imports for known modules
+- Obvious null checks
+- Simple logic errors with clear stack traces
+
+### When Stuck Is Detected
+
+1. **Acknowledge the situation clearly**:
+
+```
+I've tried [N] approaches but we're still hitting [error].
+
+This seems like a case where external research would help -
+the issue involves [library/API/pattern] that needs more
+context than I currently have.
+```
+
+2. **Gather context automatically**:
+   - Read the relevant files being modified
+   - Capture the full error message and stack trace
+   - List what approaches were already tried
+   - Note the exact versions of libraries involved
+
+3. **Generate comprehensive research prompt**:
+
+Run `/agileflow:research:ask` with detailed context:
+
+```
+TOPIC="[Specific error/problem description]"
+ERROR="[Exact error message]"
+```
+
+The research prompt MUST include:
+- **50+ lines of actual code** from your codebase
+- **Exact error messages** verbatim
+- **What was already tried** with results
+- **3+ specific questions** about the problem
+
+4. **Present to user**:
+
+```
+I've generated a detailed research prompt for ChatGPT/Claude web/Perplexity.
+
+It includes:
+- Your current code implementation
+- The exact error we're hitting
+- What I've already tried
+- Specific questions to answer
+
+Copy the prompt, paste it into your preferred AI tool, and when you
+get the answer, paste it back here. I'll save it to your research
+folder and continue implementing.
+```
+
+### Anti-Pattern: Lazy Research Prompts
+
+**NEVER generate basic prompts like:**
+
+```
+"How do I fix OAuth in Next.js?"
+```
+
+**ALWAYS generate detailed prompts with:**
+- Actual code from the codebase (50+ lines)
+- Exact error messages (verbatim, in code blocks)
+- What was already tried (with specific results)
+- Specific questions (not vague)
+
+**Example good prompt:**
+```markdown
+# OAuth Implementation Error in Next.js 14
+
+## Current Setup
+- Next.js 14.0.4 with App Router
+- next-auth 5.0.0-beta.4
+- Google OAuth provider
+
+## Current Code
+[50+ lines of actual implementation from src/app/api/auth/...]
+
+## Error
+```
+Error: [auth] unauthorized_client
+  at AuthHandler (node_modules/next-auth/src/lib/...)
+```
+
+## What I've Tried
+1. Verified client ID/secret - credentials are correct
+2. Checked redirect URI in Google Console - matches localhost:3000
+3. Cleared cookies and tried incognito - same error
+
+## Specific Questions
+1. Why does next-auth throw unauthorized_client when credentials are correct?
+2. Is there a known issue with next-auth 5.0.0-beta.4 and Google OAuth?
+3. What additional configuration is needed for App Router?
+```
+
+### Integration with Research Commands
+
+When stuck detection triggers:
+1. Use `/agileflow:research:ask` to generate the detailed prompt
+2. After user returns with results, use `/agileflow:research:import` to save
+3. Link the research to the current story if applicable
+4. Continue implementing with the new knowledge
+
+### Stuck Detection in Compact Summary
+
+Add to compact_context.preserve_rules:
+- "If same error 2+ times with different fixes, suggest /agileflow:research:ask"
+- "Generate 200+ line research prompts with actual code snippets"
+
+---
+
 ## TOOL USAGE
 
 ### AskUserQuestion

package/src/core/commands/blockers.md

@@ -205,7 +205,7 @@ For each blocker, provide:
 ### Research Blockers
 - Search docs/10-research/ for related topics
 - Check for stale research (>90 days) that might need updating
-- Suggest running /agileflow:context MODE=research for specific topic
+- Suggest running /agileflow:research:ask for specific topic
 - Link to ADRs that might have context
 
 CROSS-AGENT COORDINATION ANALYSIS (v2.7.0)
@@ -348,7 +348,7 @@ US-0051 | AG-DEVOPS | Blocked: Unclear deployment target
 
   📚 Related:
     - Research: docs/10-research/20251010-deployment-comparison.md (90 days old, may be stale)
-    - Suggest: /agileflow:context MODE=research TOPIC="Modern deployment platforms 2025"
+    - Suggest: /agileflow:research:ask TOPIC="Modern deployment platforms 2025"
 
 ---
 
@@ -386,7 +386,7 @@ AG-API at WIP limit (2/2):
 
 Next Commands:
 - /agileflow:status STORY=US-0051 STATUS=ready NOTE="Clarified deployment target: Vercel"
-- /agileflow:context MODE=research TOPIC="Modern deployment platforms 2025"
+- /agileflow:research:ask TOPIC="Modern deployment platforms 2025"
 - /agileflow:validate-system (check for other inconsistencies)
 - /agileflow:board (visualize current state)
 ```

package/src/core/commands/configure.md

@@ -1,6 +1,6 @@
 ---
 description: Configure advanced AgileFlow features (git, hooks, archival, CI, status line)
-argument-hint: [--profile=full|basic|minimal|none] [--enable/--disable=features] [--migrate] [--upgrade]
+argument-hint: [--profile=full|basic|minimal|none] [--enable/--disable=features] [--migrate] [--upgrade] [--repair] [--version] [--list-scripts]
 ---
 
 <!-- COMPACT_SUMMARY_START -->
@@ -26,6 +26,10 @@ node .agileflow/scripts/agileflow-configure.js --profile=full       # Enable all
 node .agileflow/scripts/agileflow-configure.js --profile=none       # Disable all
 node .agileflow/scripts/agileflow-configure.js --enable=sessionstart  # Enable specific
 node .agileflow/scripts/agileflow-configure.js --disable=archival   # Disable specific
+node .agileflow/scripts/agileflow-configure.js --list-scripts       # Show all scripts status
+node .agileflow/scripts/agileflow-configure.js --version            # Version info
+node .agileflow/scripts/agileflow-configure.js --repair             # Fix missing scripts
+node .agileflow/scripts/agileflow-configure.js --repair=statusline  # Fix specific feature
 ```
 
 **Note:** All scripts are located in `.agileflow/scripts/` - no files in project root `scripts/`.
@@ -343,3 +347,86 @@ Upgrading precompact...
 
 ✅ Upgraded 2 feature(s) to v2.71.0
 ```
+
+## Repair & Diagnostics
+
+When scripts are accidentally deleted or corrupted, use these commands:
+
+### List Scripts Status
+
+```bash
+node .agileflow/scripts/agileflow-configure.js --list-scripts
+```
+
+Shows all scripts with their status (present/missing/modified):
+
+```
+📋 Installed Scripts
+  ✅ agileflow-welcome.js: present
+  ✅ precompact-context.sh: present
+  ❌ agileflow-statusline.sh: MISSING
+     └─ Feature: statusline
+  ⚠️  obtain-context.js: modified (local changes)
+
+Summary: 15 present, 1 modified, 1 missing
+
+💡 Run with --repair to restore missing scripts
+```
+
+### Show Version Info
+
+```bash
+node .agileflow/scripts/agileflow-configure.js --version
+```
+
+Shows installed vs latest versions:
+
+```
+📊 Version Information
+Installed:  v2.71.0
+CLI:        v2.73.0
+Latest:     v2.73.0
+
+🔄 Update available! Run: npx agileflow update
+
+Feature Versions:
+  ✅ sessionstart: v2.73.0
+  🔄 precompact: v2.68.0 → v2.73.0
+  ✅ archival: v2.73.0
+  ❌ statusline: disabled
+```
+
+### Repair Missing Scripts
+
+```bash
+# Repair all missing scripts
+node .agileflow/scripts/agileflow-configure.js --repair
+
+# Repair scripts for a specific feature only
+node .agileflow/scripts/agileflow-configure.js --repair=statusline
+```
+
+Output:
+
+```
+🔧 Repairing Scripts...
+✅ Restored agileflow-statusline.sh
+
+Repaired: 1, Errors: 0, Skipped: 18
+
+═══════════════════════════════════════════════════════
+🔴 RESTART CLAUDE CODE NOW!
+   Quit completely, wait 5 seconds, restart
+═══════════════════════════════════════════════════════
+```
+
+### When to Use Each Command
+
+| Scenario | Command |
+|----------|---------|
+| Accidentally deleted a script | `--repair` |
+| Want to see what's installed | `--list-scripts` |
+| Check if update is available | `--version` |
+| Scripts outdated (feature version differs) | `--upgrade` |
+| Settings format broken | `--migrate` |
+| Major corruption/reinstall needed | `npx agileflow update --force`

package/src/core/commands/context/export.md

@@ -0,0 +1,99 @@
+---
+description: Export concise context excerpt for web AI tools
+argument-hint: (no arguments)
+---
+
+# /agileflow:context:export
+
+Export a concise context excerpt for pasting into web AI tools.
+
+---
+
+## Purpose
+
+Reads `docs/context.md` and outputs a condensed excerpt (≤300 lines) ready to paste into ChatGPT, Perplexity, Gemini, or Claude web.
+
+**This is a read-only command** - no files are written.
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:context:export`
+**Purpose**: Output concise context brief for pasting into web AI tools
+**Key Rule**: Read-only, no file writes, ≤300 lines output
+<!-- COMPACT_SUMMARY_END -->
+
+---
+
+## IMMEDIATE ACTIONS
+
+Upon invocation, execute these steps:
+
+### Step 1: Read Context File
+
+Read `docs/context.md`. If it doesn't exist, inform user to run `/agileflow:context:full` first.
+
+### Step 2: Extract Key Sections
+
+From the context file, extract only:
+- Last updated timestamp
+- What we're building (project overview)
+- Current focus (active work)
+- Tech/tooling summary
+- Key decisions (ADRs list)
+- Feature map (one line per epic)
+- Next steps
+
+### Step 3: Format Output
+
+Output the excerpt in a code block:
+
+```markdown
+# Project Context Brief
+Last updated: [timestamp]
+
+## What We're Building
+[Brief description]
+
+## Current Focus
+[Active epics/stories]
+
+## Tech Stack
+[Key technologies]
+
+## Key Decisions
+[ADR list]
+
+## Feature Map
+[Epic status summary]
+
+## Next Steps
+[Ready stories]
+```
+
+### Step 4: Add Instructions
+
+End with:
+
+```
+---
+Paste this excerpt into your web AI tool (ChatGPT, Perplexity, Gemini, etc.) to load context.
+```
+
+---
+
+## Constraints
+
+- **LIMIT**: ≤300 lines total output
+- **NO FILE WRITES**: This is read-only
+- **NO TodoWrite needed**: Simple single-step operation
+
+---
+
+## Related Commands
+
+- `/agileflow:context:full` - Generate/refresh full context brief
+- `/agileflow:context:note` - Add quick timestamped note
+- `/agileflow:research:ask` - Generate research prompt for web AI