agileflow 2.74.0 → 2.76.0

package/src/core/agents/product.md

@@ -282,7 +282,7 @@ COORDINATION WITH EPIC-PLANNER
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research user needs, competitive analysis
+- `/agileflow:research:ask TOPIC=...` → Research user needs, competitive analysis
 - `/agileflow:adr-new` → Document product decisions
 - `/agileflow:tech-debt` → Document product debt (unclear requirements, scope creep)
 - `/agileflow:status STORY=... STATUS=...` → Update status
@@ -296,8 +296,8 @@ RESEARCH INTEGRATION
 4. Research industry standards
 
 **Suggest Research**:
-- `/agileflow:context MODE=research TOPIC="Best practices for [feature type]"`
-- `/agileflow:context MODE=research TOPIC="User needs analysis for [user type]"`
+- `/agileflow:research:ask TOPIC="Best practices for [feature type]"`
+- `/agileflow:research:ask TOPIC="User needs analysis for [user type]"`
 
 WORKFLOW
 

package/src/core/agents/qa.md

@@ -650,7 +650,7 @@ COORDINATION WITH OTHER AGENTS
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research QA best practices
+- `/agileflow:research:ask TOPIC=...` → Research QA best practices
 - `/agileflow:ai-code-review` → Review test strategy for completeness
 - `/agileflow:adr-new` → Document QA decisions
 - `/agileflow:status STORY=... STATUS=...` → Update status

package/src/core/agents/refactor.md

@@ -453,7 +453,7 @@ COORDINATION WITH OTHER AGENTS
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research refactoring patterns, modern approaches
+- `/agileflow:research:ask TOPIC=...` → Research refactoring patterns, modern approaches
 - `/agileflow:ai-code-review` → Review refactored code for quality
 - `/agileflow:adr-new` → Document refactoring decisions
 - `/agileflow:tech-debt` → Track and manage technical debt

package/src/core/agents/security.md

@@ -332,9 +332,9 @@ RESEARCH INTEGRATION
 4. Research common vulnerabilities in that tech stack
 
 **Suggest Research**:
-- `/agileflow:context MODE=research TOPIC="OWASP Top 10 for [framework] and how to prevent"`
-- `/agileflow:context MODE=research TOPIC="JWT best practices and token refresh strategy"`
-- `/agileflow:context MODE=research TOPIC="Input validation patterns for [language]"`
+- `/agileflow:research:ask TOPIC="OWASP Top 10 for [framework] and how to prevent"`
+- `/agileflow:research:ask TOPIC="JWT best practices and token refresh strategy"`
+- `/agileflow:research:ask TOPIC="Input validation patterns for [language]"`
 
 THREAT MODELING (for major features)
 
@@ -349,7 +349,7 @@ When implementing significant features, consider:
 SLASH COMMANDS (Proactive Use)
 
 **Security Research & Analysis**:
-- `/agileflow:context MODE=research TOPIC=...` → Research security patterns, vulnerabilities, compliance
+- `/agileflow:research:ask TOPIC=...` → Research security patterns, vulnerabilities, compliance
 - `/agileflow:impact-analysis` → Analyze security impact of code changes
 
 **Quality & Review**:

package/src/core/agents/testing.md

@@ -110,7 +110,7 @@ If tests failing but must proceed:
 - `/agileflow:verify US-XXXX` → Run tests for story (updates test_status)
 - `/agileflow:session:resume` → Load context and verify environment
 - `/agileflow:baseline "message"` → Create known-good baseline (requires passing tests)
-- `/agileflow:context MODE=research TOPIC=...` → Research test patterns
+- `/agileflow:research:ask TOPIC=...` → Research test patterns
 - `/agileflow:ai-code-review` → Review test code for anti-patterns
 - `/agileflow:adr-new` → Document testing decisions
 
@@ -421,7 +421,7 @@ COORDINATION WITH OTHER AGENTS
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research test patterns, best practices
+- `/agileflow:research:ask TOPIC=...` → Research test patterns, best practices
 - `/agileflow:ai-code-review` → Review test code for anti-patterns
 - `/agileflow:adr-new` → Document testing decisions
 - `/agileflow:tech-debt` → Document test debt (low coverage areas, flaky tests)

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

@@ -1,5 +1,6 @@
 ---
 description: Interactive mentor for end-to-end feature implementation
+argument-hint: "[EPIC=<id>] [MODE=loop] [MAX=<iterations>]"
 compact_context:
   priority: critical
   preserve_rules:
@@ -8,6 +9,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
@@ -32,6 +35,78 @@ This gathers: git status, stories/epics, session state, docs structure, research
 
 ---
 
+## LOOP MODE (Autonomous Execution)
+
+When invoked with `MODE=loop`, babysit runs autonomously through an epic's stories:
+
+```
+/agileflow:babysit EPIC=EP-0042 MODE=loop MAX=20
+```
+
+### How Loop Mode Works
+
+1. **Initialization**: Writes loop config to `session-state.json`
+2. **First Story**: Picks first "ready" story, marks it "in_progress"
+3. **Work**: You implement the story normally
+4. **Stop Hook**: When you stop, `ralph-loop.js` runs:
+   - Runs `npm test` (or configured test command)
+   - If tests pass → marks story complete, loads next story
+   - If tests fail → shows failures, you continue fixing
+5. **Loop**: Continues until epic complete or MAX iterations reached
+
+### Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `EPIC` | Yes | Epic ID to process (e.g., EP-0042) |
+| `MODE` | Yes | Must be `loop` for autonomous mode |
+| `MAX` | No | Max iterations (default: 20) |
+
+### To Start Loop Mode
+
+After running the context script, if EPIC and MODE=loop are specified:
+
+```bash
+# Initialize the loop
+node scripts/ralph-loop.js --init --epic=EP-0042 --max=20
+```
+
+Or manually write to session-state.json:
+
+```json
+{
+  "ralph_loop": {
+    "enabled": true,
+    "epic": "EP-0042",
+    "current_story": "US-0015",
+    "iteration": 0,
+    "max_iterations": 20
+  }
+}
+```
+
+### Loop Control Commands
+
+```bash
+node scripts/ralph-loop.js --status   # Check loop status
+node scripts/ralph-loop.js --stop     # Stop the loop
+node scripts/ralph-loop.js --reset    # Reset loop state
+```
+
+### When to Use Loop Mode
+
+**Good for:**
+- Working through a well-defined epic with clear stories
+- Test-driven development (tests define "done")
+- Batch processing multiple stories overnight
+
+**Not good for:**
+- Exploratory work without clear acceptance criteria
+- Stories requiring human review before proceeding
+- Complex multi-domain work needing coordination
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 
 ## Compact Summary
@@ -266,6 +341,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

@@ -36,7 +36,9 @@ node .agileflow/scripts/agileflow-configure.js --repair=statusline  # Fix specif
 
 ### Features
 
-`sessionstart`, `precompact`, `archival`, `statusline`, `autoupdate`
+`sessionstart`, `precompact`, `ralphloop`, `selfimprove`, `archival`, `statusline`, `autoupdate`
+
+**Stop hooks** (ralphloop, selfimprove) run when Claude completes or pauses work.
 
 ### Critical Rules
 
@@ -162,12 +164,12 @@ node .agileflow/scripts/agileflow-configure.js --enable=archival --archival-days
 
 ## Profile Details
 
-| Profile | SessionStart | PreCompact | Archival | StatusLine |
-|---------|-------------|------------|----------|------------|
-| `full` | ✅ | ✅ | ✅ 30 days | ✅ |
-| `basic` | ✅ | ✅ | ✅ 30 days | ❌ |
-| `minimal` | ✅ | ❌ | ✅ 30 days | ❌ |
-| `none` | ❌ | ❌ | ❌ | ❌ |
+| Profile | SessionStart | PreCompact | RalphLoop | SelfImprove | Archival | StatusLine |
+|---------|-------------|------------|-----------|-------------|----------|------------|
+| `full` | ✅ | ✅ | ✅ | ✅ | ✅ 30 days | ✅ |
+| `basic` | ✅ | ✅ | ❌ | ❌ | ✅ 30 days | ❌ |
+| `minimal` | ✅ | ❌ | ❌ | ❌ | ✅ 30 days | ❌ |
+| `none` | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
 
 ## Interactive Mode (via /configure command)
 
@@ -204,6 +206,8 @@ Based on selection, run appropriate command.
   "options": [
     {"label": "SessionStart Hook", "description": "Welcome display with project status"},
     {"label": "PreCompact Hook", "description": "Context preservation on compact"},
+    {"label": "RalphLoop (Stop Hook)", "description": "Autonomous story loop - runs tests, advances stories"},
+    {"label": "SelfImprove (Stop Hook)", "description": "Auto-update agent expertise from work"},
     {"label": "Archival", "description": "Auto-archive old completed stories"},
     {"label": "Status Line", "description": "Custom status bar"},
     {"label": "Auto-Update", "description": "Automatically update AgileFlow on session start"}
@@ -215,6 +219,8 @@ Based on selection, run appropriate command.
 Map selections:
 - "SessionStart Hook" → `sessionstart`
 - "PreCompact Hook" → `precompact`
+- "RalphLoop (Stop Hook)" → `ralphloop`
+- "SelfImprove (Stop Hook)" → `selfimprove`
 - "Archival" → `archival`
 - "Status Line" → `statusline`
 - "Auto-Update" → `autoupdate`
@@ -241,6 +247,43 @@ node .agileflow/scripts/agileflow-configure.js --enable=autoupdate
 
 **Check frequencies:** `hourly`, `daily`, `weekly`, `never`
 
+## Stop Hook Features
+
+Stop hooks run when Claude completes a task or pauses for user input. These enable autonomous workflows.
+
+### RalphLoop (`ralphloop`)
+
+Autonomous story processing loop (named after the "Ralph Wiggum" pattern):
+- Runs tests automatically when Claude stops
+- If tests pass → marks story as completed, loads next story in epic
+- If tests fail → shows failures for Claude to fix
+- Tracks iterations with configurable limits (default: 20)
+- Enable: `--enable=ralphloop`
+
+**How to use:**
+1. Enable: `node .agileflow/scripts/agileflow-configure.js --enable=ralphloop`
+2. Start a loop: `node .agileflow/scripts/ralph-loop.js --init --epic=EP-XXXX`
+3. Work on stories - tests run automatically when Claude stops
+4. Check status: `node .agileflow/scripts/ralph-loop.js --status`
+5. Stop loop: `node .agileflow/scripts/ralph-loop.js --stop`
+
+### SelfImprove (`selfimprove`)
+
+Automatic agent expertise learning:
+- Analyzes git changes when Claude stops
+- Detects which domain (database, api, ui, etc.) was modified
+- Appends learnings to the relevant agent's expertise.yaml
+- Helps agents improve over time based on actual work
+- Enable: `--enable=selfimprove`
+
+**What it learns:**
+- Files modified per domain
+- New patterns discovered
+- Test file changes
+- Configuration updates
+
+Both Stop hooks use error suppression (`2>/dev/null || true`) to avoid blocking Claude if they fail.
+
 ## Format Migration Details
 
 The script handles these migrations automatically: