agileflow 2.80.0 → 2.82.0

package/src/core/commands/babysit.md

@@ -1,6 +1,6 @@
 ---
 description: Interactive mentor for end-to-end feature implementation
-argument-hint: "[EPIC=<id>] [MODE=loop] [MAX=<iterations>] [VISUAL=true]"
+argument-hint: "[EPIC=<id>] [MODE=loop] [MAX=<iterations>] [VISUAL=true] [COVERAGE=<percent>]"
 compact_context:
   priority: critical
   preserve_rules:
@@ -62,6 +62,8 @@ When invoked with `MODE=loop`, babysit runs autonomously through an epic's stori
 | `MODE` | Yes | Must be `loop` for autonomous mode |
 | `MAX` | No | Max iterations (default: 20) |
 | `VISUAL` | No | Enable Visual Mode for UI development (screenshot verification) |
+| `COVERAGE` | No | Enable Coverage Mode - iterate until N% test coverage reached |
+| `CONDITIONS` | No | Semantic conditions for story completion (configured in metadata) |
 
 ### To Start Loop Mode
 
@@ -73,6 +75,9 @@ node scripts/ralph-loop.js --init --epic=EP-0042 --max=20
 
 # With Visual Mode for UI development
 node scripts/ralph-loop.js --init --epic=EP-0042 --max=20 --visual
+
+# With Coverage Mode - iterate until 80% coverage
+node scripts/ralph-loop.js --init --epic=EP-0042 --max=20 --coverage=80
 ```
 
 Or manually write to session-state.json:
@@ -86,7 +91,73 @@ Or manually write to session-state.json:
     "iteration": 0,
     "max_iterations": 20,
     "visual_mode": false,
-    "screenshots_verified": false
+    "screenshots_verified": false,
+    "coverage_mode": false,
+    "coverage_threshold": 80,
+    "coverage_baseline": 0,
+    "coverage_current": 0,
+    "coverage_verified": false
+  }
+}
+```
+
+### Discretion Conditions Mode
+
+Configure semantic conditions in `docs/00-meta/agileflow-metadata.json`:
+
+```json
+{
+  "ralph_loop": {
+    "conditions": [
+      "**all tests passing**",
+      "**no linting errors**",
+      "**no type errors**"
+    ]
+  }
+}
+```
+
+**Available conditions:**
+- `**all tests passing**` - Tests must pass
+- `**coverage above N%**` - Coverage threshold (e.g., `**coverage above 80%**`)
+- `**no linting errors**` - `npm run lint` must pass
+- `**no type errors**` - `npx tsc --noEmit` must pass
+- `**build succeeds**` - `npm run build` must pass
+- `**all screenshots verified**` - Screenshots need `verified-` prefix
+- `**all acceptance criteria verified**` - AC marked complete in status.json
+
+**Benefits:**
+- Natural language conditions that read like requirements
+- Multiple conditions can be combined
+- Extensible - add custom conditions as needed
+
+### Coverage Mode
+
+When `COVERAGE=<percent>` is specified, the loop adds test coverage verification:
+
+```
+/agileflow:babysit EPIC=EP-0042 MODE=loop COVERAGE=80
+```
+
+**Coverage Mode behavior:**
+1. After tests pass, runs coverage check command
+2. Parses `coverage/coverage-summary.json` (Jest/NYC format)
+3. Compares line coverage to threshold
+4. Requires minimum 2 iterations before completion
+5. Story completes only when coverage ≥ threshold AND confirmed
+
+**When to use Coverage Mode:**
+- Test-driven epics where coverage matters
+- "Write tests until X% coverage" goals
+- Batch test generation overnight
+
+**Configuration** (optional):
+Add to `docs/00-meta/agileflow-metadata.json`:
+```json
+{
+  "ralph_loop": {
+    "coverage_command": "npm run test:coverage",
+    "coverage_report_path": "coverage/coverage-summary.json"
   }
 }
 ```
@@ -111,7 +182,7 @@ When `VISUAL=true` is specified, the loop adds screenshot verification:
 - Any work where visual appearance matters
 
 **Setup requirement:**
-Run `/agileflow:setup:visual-e2e` first to install Playwright and create e2e tests.
+Run `/agileflow:configure` and select "Set up Visual E2E testing" to install Playwright and create e2e tests.
 
 ### Loop Control Commands
 
@@ -200,7 +271,7 @@ Analysis/Review                   → /agileflow:multi-expert or Task(subagent_t
 - `agileflow-api` - Endpoints, business logic
 - `agileflow-ui` - Components, styling
 - `agileflow-testing` - Tests, coverage
-- `agileflow-orchestrator` - Multi-domain coordination
+- `agileflow-orchestrator` - Multi-domain coordination (supports nested loops for quality gates)
 
 ---
 
@@ -353,6 +424,23 @@ Task(
 )
 ```
 
+**🧪 EXPERIMENTAL: Nested Loops with Quality Gates**
+
+When you need agents to iterate until quality gates pass (coverage ≥ 80%, tests pass, etc.), the orchestrator can use **nested agent loops**. Each agent runs its own isolated loop.
+
+```
+Task(
+  description: "Profile feature with quality gates",
+  prompt: "Implement profile with quality enforcement:
+    1. API: /api/profile with COVERAGE >= 80% (agent loop)
+    2. UI: ProfilePage with VISUAL verification (agent loop)
+    Use agent-loop.js for isolated quality iterations.",
+  subagent_type: "agileflow-orchestrator"
+)
+```
+
+See `orchestrator.md` → "NESTED LOOP MODE" section for full details.
+
 ---
 
 #### Pattern 3: Parallel Execution (Manual Coordination)
@@ -434,6 +522,59 @@ Task(
 
 ---
 
+#### Retry with Backoff for Expert Spawning
+
+When an expert task fails, apply retry logic before giving up:
+
+**Retry Strategy:**
+```
+Attempt 1: Immediate retry
+Attempt 2: Wait 5 seconds, then retry
+Attempt 3: Wait 15 seconds, then retry (final)
+```
+
+**When to retry:**
+- Expert returns error or timeout
+- TaskOutput shows failure state
+- Expert reports "unable to complete"
+
+**When NOT to retry:**
+- User explicitly asked to stop
+- Expert completed but result was wrong (need different approach)
+- Multiple experts all failed same way (systemic issue)
+
+**Example retry flow:**
+```
+📍 Spawning agileflow-api expert...
+⚠️ Expert failed (timeout after 2 min)
+
+🔄 Retry 1/3: Retrying immediately...
+⚠️ Expert failed (same error)
+
+🔄 Retry 2/3: Waiting 5s, then retrying...
+⚠️ Expert failed (connection error)
+
+🔄 Retry 3/3: Waiting 15s, then retrying...
+✅ Expert succeeded!
+```
+
+**On final failure:**
+```
+⚠️ Error: Expert agileflow-api failed after 3 retries
+
+Last error: Connection timeout after 120s
+Attempts: 3
+
+Options:
+1. Try a different approach
+2. Check network/service status
+3. Manually implement the task
+
+[Present options via AskUserQuestion]
+```
+
+---
+
 ### KEY FILES TO REMEMBER
 
 | File | Purpose |
@@ -441,8 +582,6 @@ Task(
 | `docs/09-agents/status.json` | Story tracking, WIP status |
 | `docs/09-agents/session-state.json` | Session state, active command |
 | `CLAUDE.md` | Project conventions (included in full above) |
-| `docs/02-practices/*.md` | Implementation patterns |
-| `docs/04-architecture/*.md` | System design docs |
 
 ---
 
@@ -503,6 +642,18 @@ Based on your project state:
 
 ---
 
+### STATE NARRATION (emit in responses)
+
+| Marker | When |
+|--------|------|
+| 📍 | Working on story/phase |
+| 🔀 | Spawning parallel experts |
+| 🔄 | Loop iterations |
+| ⚠️ | Errors |
+| ✅ | Completions |
+
+---
+
 ### REMEMBER AFTER COMPACTION
 
 - `/agileflow:babysit` IS ACTIVE - follow these rules
@@ -510,11 +661,47 @@ Based on your project state:
 - Plan mode FIRST for non-trivial tasks
 - Delegate complex work to experts
 - If stuck 2+ times → research prompt
+- Use state narration markers (📍🔀🔄⚠️✅) for visibility
 
 <!-- COMPACT_SUMMARY_END -->
 
 ---
 
+## STATE NARRATION PROTOCOL
+
+In long sessions, track execution state visibly using emoji markers. This makes state scannable after compaction.
+
+### Markers
+
+| Marker | Meaning | Example |
+|--------|---------|---------|
+| 📍 | Execution position | `📍 Working on: US-0042 - Add login form` |
+| 📦 | Context/variables | `📦 Context: { auth: "complete", api: "pending" }` |
+| 🔀 | Parallel status | `🔀 Parallel: API (done), UI (in progress)` |
+| 🔄 | Loop iteration | `🔄 Iteration 3/10` |
+| ⚠️ | Error state | `⚠️ Error: Test failure in auth.spec.ts` |
+| ✅ | Completion | `✅ Story complete: US-0042` |
+| 🔒 | Blocked | `🔒 Blocked: Waiting for API schema` |
+
+### When to Emit Markers
+
+- **Start of story**: `📍 Starting: US-0042`
+- **Phase transitions**: `📍 Phase: Execution (plan approved)`
+- **Expert spawn**: `🔀 Spawned: agileflow-api (background)`
+- **Expert complete**: `✅ Expert done: agileflow-api`
+- **Loop iterations**: `🔄 Ralph Loop: 3/10`
+- **Errors**: `⚠️ Test failure: 2 tests failed`
+- **Completion**: `✅ Story complete: US-0042`
+
+### Benefits
+
+- **Visibility**: State is inline, not hidden in files
+- **Debugging**: Scan conversation for state changes
+- **Resumability**: Markers help restore context after compact
+- **Progress**: Clear indication of where work stands
+
+---
+
 ## DELEGATION FRAMEWORK
 
 ### Decision Tree
@@ -917,15 +1104,6 @@ After loading context, analyze and present ranked options:
 - Session state, current story
 - Docs structure, research notes
 
-**Read manually for deep dives:**
-
-| Domain | Docs |
-|--------|------|
-| Database | `docs/04-architecture/database-*.md` |
-| API | `docs/04-architecture/api-*.md` |
-| UI | `docs/02-practices/styling.md` |
-| Testing | `docs/02-practices/testing.md` |
-
 **State files:**
 - `docs/09-agents/status.json` - Story tracking
 - `docs/09-agents/bus/log.jsonl` - Agent messages

package/src/core/commands/batch.md

@@ -0,0 +1,362 @@
+---
+description: Process multiple items with functional patterns (map/pmap/filter/reduce)
+argument-hint: <operation> <pattern> [action]
+compact_context:
+  priority: normal
+  preserve_rules:
+    - "map: Execute action on each item sequentially"
+    - "pmap: Execute action on each item in parallel (spawn Task agents)"
+    - "filter: Return items matching criteria"
+    - "reduce: Aggregate items into single output"
+  state_fields:
+    - batch_operation
+    - items_processed
+    - items_total
+---
+
+# /agileflow:batch
+
+Process multiple items with functional patterns. Enables batch operations on stories, files, or tasks.
+
+---
+
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js batch
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+
+## Compact Summary
+
+**Role**: Batch Processor - Apply functional patterns to collections
+
+**Operations**:
+- `map` - Execute action on each item sequentially
+- `pmap` - Execute action in parallel (spawn agents)
+- `filter` - Return items matching criteria
+- `reduce` - Aggregate items into output
+
+**Usage Examples**:
+```
+/agileflow:batch map "docs/06-stories/*.md" validate
+/agileflow:batch pmap "src/**/*.tsx" add-tests
+/agileflow:batch filter stories status=ready
+/agileflow:batch reduce "docs/06-stories/*.md" summary
+```
+
+**Workflow**:
+1. Parse operation and pattern
+2. Resolve pattern to item list
+3. For each item: execute action based on operation type
+4. Collect and report results
+
+<!-- COMPACT_SUMMARY_END -->
+
+---
+
+## Usage
+
+```
+/agileflow:batch <operation> <pattern> [action]
+```
+
+### Operations
+
+| Operation | Description | Parallelism |
+|-----------|-------------|-------------|
+| `map` | Execute action on each item | Sequential |
+| `pmap` | Execute action in parallel | Parallel (agents) |
+| `filter` | Return matching items | N/A |
+| `reduce` | Aggregate to single output | Sequential |
+
+### Pattern Types
+
+| Pattern | Resolves To | Example |
+|---------|-------------|---------|
+| Glob | File paths | `src/**/*.tsx` |
+| `stories` | Stories from status.json | `stories status=ready` |
+| `epics` | Epics from status.json | `epics status=in_progress` |
+
+---
+
+## Examples
+
+### 1. Validate All Stories (map)
+
+```
+/agileflow:batch map "docs/06-stories/*.md" validate
+```
+
+Sequentially validates each story file:
+- Checks for required frontmatter
+- Validates acceptance criteria format
+- Reports issues
+
+**Output:**
+```
+📦 Batch: map over 12 items
+
+📍 Processing: docs/06-stories/US-0042.md
+  ✅ Valid story format
+
+📍 Processing: docs/06-stories/US-0043.md
+  ⚠️ Missing acceptance criteria
+
+...
+
+✅ Complete: 10 passed, 2 warnings
+```
+
+### 2. Generate Tests in Parallel (pmap)
+
+```
+/agileflow:batch pmap "src/components/*.tsx" add-tests
+```
+
+Spawns parallel agents to generate tests:
+
+**What happens:**
+1. Glob resolves to list of component files
+2. For each file, spawn Task agent:
+   ```
+   Task(
+     description: "Add tests for Button.tsx",
+     prompt: "Generate comprehensive tests for src/components/Button.tsx",
+     subagent_type: "agileflow-testing",
+     run_in_background: true
+   )
+   ```
+3. Collect results with TaskOutput
+4. Report summary
+
+**Output:**
+```
+🔀 Batch: pmap over 8 items (parallel)
+
+🔀 Spawning 8 parallel agents...
+  📍 task-001: Button.tsx
+  📍 task-002: Input.tsx
+  📍 task-003: Select.tsx
+  ...
+
+⏳ Waiting for completion...
+
+✅ task-001: Button.tsx - 5 tests added
+✅ task-002: Input.tsx - 4 tests added
+✅ task-003: Select.tsx - 6 tests added
+...
+
+✅ Complete: 8/8 successful, 38 tests added
+```
+
+### 3. Filter Ready Stories
+
+```
+/agileflow:batch filter stories status=ready
+```
+
+Returns stories matching criteria:
+
+**Output:**
+```
+🔍 Filter: stories where status=ready
+
+Found 3 matching stories:
+
+1. US-0042: Add user profile settings
+   Epic: EP-0009 | Priority: high
+
+2. US-0043: Implement password reset
+   Epic: EP-0009 | Priority: high
+
+3. US-0045: Add notification preferences
+   Epic: EP-0010 | Priority: medium
+```
+
+### 4. Reduce to Summary Report
+
+```
+/agileflow:batch reduce "docs/06-stories/*.md" summary
+```
+
+Aggregates stories into summary:
+
+**Output:**
+```
+📊 Reduce: 15 stories → summary
+
+Epic Distribution:
+  EP-0009: 8 stories (53%)
+  EP-0010: 4 stories (27%)
+  EP-0011: 3 stories (20%)
+
+Status Distribution:
+  ready: 5 (33%)
+  in_progress: 3 (20%)
+  completed: 7 (47%)
+
+Priority:
+  high: 6
+  medium: 7
+  low: 2
+```
+
+---
+
+## Actions
+
+### Built-in Actions
+
+| Action | Description | Works With |
+|--------|-------------|------------|
+| `validate` | Check format/structure | stories, epics |
+| `add-tests` | Generate tests | source files |
+| `lint` | Run linter | source files |
+| `format` | Apply formatting | source files |
+| `summarize` | Generate summary | any |
+| `count` | Count items | any |
+
+### Custom Actions
+
+For pmap, action becomes the agent prompt:
+
+```
+/agileflow:batch pmap "src/**/*.ts" "refactor to use async/await"
+```
+
+This spawns agents with prompt: "refactor to use async/await" for each file.
+
+---
+
+## Filter Criteria
+
+Filters use `field=value` syntax:
+
+```
+/agileflow:batch filter stories status=ready
+/agileflow:batch filter stories epic=EP-0009
+/agileflow:batch filter stories priority=high
+/agileflow:batch filter epics status=in_progress
+```
+
+Multiple criteria (AND):
+```
+/agileflow:batch filter stories status=ready priority=high
+```
+
+---
+
+## Implementation Details
+
+### Map Operation
+
+```javascript
+// Sequential execution
+for (const item of items) {
+  const result = await executeAction(item, action);
+  results.push(result);
+  console.log(`📍 ${item}: ${result.status}`);
+}
+```
+
+### Pmap Operation
+
+```javascript
+// Parallel execution with agents
+const tasks = items.map(item => Task({
+  description: `Process ${path.basename(item)}`,
+  prompt: `${action} for ${item}`,
+  subagent_type: getAgentForAction(action),
+  run_in_background: true
+}));
+
+// Collect results
+for (const task of tasks) {
+  const result = await TaskOutput(task.id, { block: true });
+  results.push(result);
+}
+```
+
+### Filter Operation
+
+```javascript
+// Load and filter status.json
+const status = loadStatus();
+const items = type === 'stories' ? status.stories : status.epics;
+
+const filtered = Object.entries(items)
+  .filter(([id, item]) => matchesCriteria(item, criteria))
+  .map(([id, item]) => ({ id, ...item }));
+```
+
+### Reduce Operation
+
+```javascript
+// Aggregate with accumulator
+let accumulator = initialValue;
+for (const item of items) {
+  accumulator = reducer(accumulator, item);
+}
+return accumulator;
+```
+
+---
+
+## Best Practices
+
+### When to Use Each Operation
+
+| Use Case | Operation |
+|----------|-----------|
+| Sequential processing | `map` |
+| Independent tasks, time-sensitive | `pmap` |
+| Query/search | `filter` |
+| Reports/aggregation | `reduce` |
+
+### Performance Considerations
+
+- **pmap** spawns agents - each costs tokens
+- Limit pmap to reasonable batch sizes (< 20 items)
+- Use `map` for quick operations (validation, counting)
+- Use `filter` before other operations to reduce scope
+
+### Error Handling
+
+- Map/pmap continue on individual item failures
+- Failed items are reported at end
+- Use `--fail-fast` flag to stop on first error:
+  ```
+  /agileflow:batch map "*.ts" lint --fail-fast
+  ```
+
+---
+
+## State Tracking
+
+Batch operations update session-state.json:
+
+```json
+{
+  "last_batch": {
+    "operation": "pmap",
+    "pattern": "src/**/*.tsx",
+    "action": "add-tests",
+    "items_total": 8,
+    "items_processed": 8,
+    "items_failed": 0,
+    "completed_at": "2026-01-09T12:00:00Z"
+  }
+}
+```
+
+---
+
+## Integration
+
+- Works with `/agileflow:babysit` for batch story processing
+- Can be used in Ralph Loop for batch operations per iteration
+- Integrates with agent system for parallel work