wogiflow 1.1.7 → 1.1.9

package/.claude/commands/wogi-bulk.md

@@ -1,6 +1,8 @@
 Execute multiple tasks in sequence, following all workflow rules.
 
-**v2.1**: Now uses task queue for automatic continuation between tasks.
+**v3.0**: Now supports **orchestrator mode** where each task executes in a fresh sub-agent context, preventing context pollution. Inspired by Matt Maher's "do-work" pattern.
+
+**v2.1**: Uses task queue for automatic continuation between tasks.
 
 ## Usage
 
@@ -13,7 +15,38 @@ Execute multiple tasks in sequence, following all workflow rules.
 - "do wf-001, wf-002, wf-003"
 - "work on these 3 stories"
 
-## How It Works (v2.1)
+## How It Works (v3.0 - Orchestrator Mode)
+
+**Default behavior** (when `bulkOrchestrator.enabled: true`):
+
+1. **Build Execution Plan**:
+   - Detect dependencies between tasks
+   - Group independent tasks into parallel batches
+   - Order batches to respect dependencies
+
+2. **Execute Each Batch**:
+   - For each batch, spawn sub-agent(s) with **fresh context**
+   - Independent tasks in same batch run in parallel
+   - Dependent tasks wait for their dependencies
+
+3. **Pass-Forward Summaries**:
+   - When Task A completes, generate completion summary
+   - Task B (if dependent on A) receives summary as context
+   - Ensures continuity without context pollution
+
+4. **Failure Handling** (configurable via `onFailure`):
+   - `stop-all`: Stop entire queue on any failure
+   - `stop-dependent`: Skip tasks that depend on failed task, continue others
+   - `continue`: Log failure and continue all remaining tasks
+
+**Benefits over v2.1:**
+- No context pollution between tasks
+- Can run for hours without context exhaustion
+- Each task is atomic and reliable
+
+## How It Works (v2.1 - Legacy Mode)
+
+When `bulkOrchestrator.enabled: false`:
 
 1. **Initialize Queue**:
    - Parse task IDs from arguments or natural language
@@ -36,27 +69,98 @@ Execute multiple tasks in sequence, following all workflow rules.
    - Quality gates and validation
    - Request log and app-map updates
 
-## Execution Flow
+## Execution Flow (v3.0 Orchestrator)
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│  /wogi-bulk 3                                               │
+│  /wogi-bulk wf-001 wf-002 wf-003                            │
+├─────────────────────────────────────────────────────────────┤
+│  1. Detect dependencies between tasks                       │
+│  2. Build execution batches:                                │
+│     Batch 1: [wf-001, wf-002] (independent, run parallel)   │
+│     Batch 2: [wf-003] (depends on wf-001, run after)        │
+│                                                             │
+│  3. Execute Batch 1:                                        │
+│     ┌─────────────────┐  ┌─────────────────┐                │
+│     │ Sub-Agent A     │  │ Sub-Agent B     │  ← Parallel    │
+│     │ /wogi-start     │  │ /wogi-start     │                │
+│     │ wf-001          │  │ wf-002          │                │
+│     │ (fresh context) │  │ (fresh context) │                │
+│     └────────┬────────┘  └────────┬────────┘                │
+│              │                    │                         │
+│              ▼                    ▼                         │
+│     [Summary A]           [Summary B]                       │
+│                                                             │
+│  4. Execute Batch 2:                                        │
+│     ┌─────────────────────────────────┐                     │
+│     │ Sub-Agent C                     │                     │
+│     │ Context: Summary A (dependency) │  ← Pass-forward     │
+│     │ /wogi-start wf-003              │                     │
+│     │ (fresh context + summary)       │                     │
+│     └─────────────────────────────────┘                     │
+│                                                             │
+│  5. All batches complete - show summary                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Execution Flow (v2.1 Legacy)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  /wogi-bulk 3 --no-orchestrator                             │
 ├─────────────────────────────────────────────────────────────┤
 │  1. Get 3 ready tasks sorted by priority                    │
 │  2. Initialize task queue: [wf-001, wf-002, wf-003]         │
-│  3. Start wf-001 (full loop)                                │
+│  3. Start wf-001 (full loop, SAME context)                  │
 │     → All scenarios implemented and verified                │
 │     → Quality gates pass                                    │
 │     → Committed                                             │
 │  4. Stop hook detects queue has more tasks                  │
-│  5. Auto-continue to wf-002 (full loop)                     │
+│  5. Auto-continue to wf-002 (full loop, SAME context)       │
 │     → ...                                                   │
-│  6. Auto-continue to wf-003 (full loop)                     │
+│  6. Auto-continue to wf-003 (full loop, SAME context)       │
 │     → ...                                                   │
 │  7. Queue empty - stop                                      │
 └─────────────────────────────────────────────────────────────┘
 ```
 
+## Continuous Mode (v3.1)
+
+When enabled, the orchestrator keeps checking for new work instead of stopping when the queue is empty. This enables the two-terminal workflow:
+
+- **Terminal 1**: Running `/wogi-bulk --continuous` - continuously processing tasks
+- **Terminal 2**: Capturing ideas with `/wogi-capture` - ideas become ready tasks
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  /wogi-bulk --continuous                                     │
+├─────────────────────────────────────────────────────────────┤
+│  1. Process initial queue (wf-001, wf-002)                  │
+│     → All tasks complete                                     │
+│                                                             │
+│  2. Queue empty - but continuous mode enabled               │
+│     → Wait 60 seconds (configurable)                        │
+│     → Check for new tasks...                                │
+│                                                             │
+│  3. New task found! (wf-003 was captured during wait)       │
+│     → Process wf-003                                        │
+│     → Task complete                                         │
+│                                                             │
+│  4. Queue empty again                                       │
+│     → Wait 60 seconds                                       │
+│     → Check 1/3... no new tasks                             │
+│     → Wait 60 seconds                                       │
+│     → Check 2/3... no new tasks                             │
+│     → Wait 60 seconds                                       │
+│     → Check 3/3... no new tasks                             │
+│                                                             │
+│  5. Max idle checks reached - stop                          │
+│     → Show summary of all completed work                    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Graceful shutdown**: Press `Ctrl+C` to stop the loop. Current task will complete (or checkpoint) before stopping.
+
 ## Output
 
 **Start:**
@@ -95,14 +199,48 @@ Queue Summary:
 
 ## Options
 
-- `--auto` - Don't pause between tasks (default behavior in v2.1)
+### Orchestrator Options (v3.0)
+- `--no-orchestrator` - Disable orchestrator mode, use legacy v2.1 behavior (same context)
+- `--parallel-limit <N>` - Max tasks to run in parallel (default: 3)
+- `--on-failure <mode>` - How to handle failures: `stop-all`, `stop-dependent`, `continue`
+- `--summary-depth <level>` - Pass-forward summary detail: `minimal`, `standard`, `detailed`
+
+### Continuous Mode Options (v3.1)
+- `--continuous` - Enable continuous mode (keep checking for new tasks)
+- `--no-continuous` - Disable continuous mode (stop when initial queue is done)
+- `--idle-timeout <N>` - Seconds to wait when idle before rechecking (default: 60)
+- `--idle-action <mode>` - What to do when idle: `stop` or `wait`
+
+### General Options
+- `--auto` - Don't pause between tasks (default behavior)
 - `--pause` - Pause and ask before each task
-- `--plan` - Show order without executing
+- `--plan` - Show execution plan without executing (dry run)
 - `--feature <name>` - Only tasks in specified feature
 
 ## Configuration
 
 In `config.json`:
+
+### Orchestrator Configuration (v3.0)
+```json
+{
+  "bulkOrchestrator": {
+    "enabled": true,           // Use sub-agent isolation (false = legacy mode)
+    "parallelLimit": 3,        // Max tasks to run in parallel
+    "useWorktrees": true,      // Use git worktrees for parallel isolation
+    "onFailure": "stop-dependent",  // stop-all | stop-dependent | continue
+    "summaryDepth": "standard", // minimal | standard | detailed
+    "continuous": {
+      "enabled": false,        // Enable continuous mode
+      "idleAction": "stop",    // stop | wait when queue is empty
+      "idleTimeout": 60,       // Seconds to wait before rechecking
+      "maxIdleChecks": 3       // Max times to check before stopping
+    }
+  }
+}
+```
+
+### Task Queue Configuration (v2.1 Legacy)
 ```json
 {
   "taskQueue": {

package/.claude/commands/wogi-capture.md

@@ -1,5 +1,7 @@
 Quick capture an idea or bug without interrupting your current work. Provide a brief title: `/wogi-capture Add dark mode toggle`
 
+**v2.1**: Auto-Grouping + **Routing** (certain → roadmap, uncertain → discussion queue)
+
 ## Usage
 
 ```bash
@@ -9,38 +11,103 @@ Quick capture an idea or bug without interrupting your current work. Provide a b
 
 Just provide a brief title. That's it.
 
-## What Happens
+## Routing (v2.1)
 
-1. **Auto-detect type** from keywords:
-   - "bug", "fix", "broken", "error", "crash", "fails" → `bug`
-   - Everything else → `feature`
+Ideas are automatically routed based on certainty:
+
+- **Certain ideas** (clear action) → Added to `roadmap.md`
+- **Uncertain ideas** (questions, "maybe") → Added to `discussion-queue.md`
+
+### Auto-Detection
+
+The system detects uncertainty from:
+- **Question marks**: "should we add GraphQL?"
+- **Hedging words**: "maybe", "might", "could", "perhaps"
+- **Tentative phrases**: "what if", "should we", "thinking about", "wondering"
+
+### Examples
+
+```
+/wogi-capture "add dark mode toggle"
+→ Certain (explicit action) → Roadmap
+
+/wogi-capture "should we maybe use GraphQL?"
+→ Uncertain (question + "maybe") → Discussion queue
+
+/wogi-capture "refactor auth" --certain
+→ Forced to roadmap
+
+/wogi-capture "add caching" --idea
+→ Forced to discussion queue
+```
+
+### Routing Flags
 
-2. **Auto-tag** from current context (if a task is in progress)
+- `--certain` - Force routing to roadmap
+- `--idea` - Force routing to discussion queue
+- `--no-route` - Disable routing, just add to backlog
 
-3. **Add to backlog** in `ready.json` with minimal metadata
+## Auto-Grouping (v2.0)
 
-4. **Minimal confirmation** - just "Captured: [title]"
+When you capture multiple related items at once, they're automatically grouped:
 
-## Backlog Triage
+```
+/wogi-capture "change send button to blue, change cancel button to blue, change delete button to blue"
+→ ONE capture: "Update button colors" (3 items grouped)
+
+/wogi-capture "fix login bug, add dark mode, update footer"
+→ THREE captures (unrelated items split)
+
+/wogi-capture "change header to blue, change footer to blue, fix the login bug"
+→ TWO captures: color changes grouped, bug fix separate
+```
 
-Items go to a `backlog` array in ready.json. Use `/wogi-ready` to see them.
+### Grouping Heuristics
 
-Later you can:
-- Promote to `ready` (use `/wogi-story` to create proper story)
-- Discard if no longer relevant
-- Convert to bug with `/wogi-bug`
+Items are grouped when they share:
+- **Same action type**: color changes, size changes, text updates
+- **Same target**: button, header, form, etc.
+- **Same item type**: bugs with bugs, features with features
 
-## Examples
+### Disable Grouping
 
+Use `--no-group` to create separate items without grouping:
+```bash
+/wogi-capture "change all buttons to blue, fix the form" --no-group
+→ TWO captures (no grouping applied)
 ```
-/wogi-capture Add export to PDF
-→ Captured: Add export to PDF (feature)
 
-/wogi-capture Bug: form validation not working
-→ Captured: Bug: form validation not working (bug)
+## What Happens
 
-/wogi-capture Broken image on profile page
-→ Captured: Broken image on profile page (bug)
+1. **Parse input** - Split by commas, "and", numbered lists
+2. **Analyze items** - Extract action type, target component, item type
+3. **Group related** - Combine similar items above threshold
+4. **Detect certainty** - Check for uncertainty signals
+5. **Route** - Certain → roadmap, uncertain → discussion queue
+6. **Auto-detect type** from keywords:
+   - "bug", "fix", "broken", "error", "crash", "fails" → `bug`
+   - Everything else → `feature`
+7. **Auto-tag** from current context (if a task is in progress)
+
+## Files
+
+| Certainty | Destination |
+|-----------|-------------|
+| Certain | `.workflow/roadmap.md` |
+| Uncertain | `.workflow/state/discussion-queue.md` |
+| No routing | `.workflow/state/ready.json` (backlog) |
+
+### Discussion Queue Format
+
+```markdown
+## Pending Review
+
+### 2026-01-29
+- [ ] Should we refactor the auth system? (captured: 10:30)
+- [ ] Maybe add GraphQL support? (captured: 11:15)
+
+## Reviewed
+<!-- Moved items go here with decision -->
 ```
 
 ## CLI Usage
@@ -48,6 +115,8 @@ Later you can:
 ```bash
 node scripts/flow-capture.js "Add dark mode toggle"
 node scripts/flow-capture.js "Bug: login fails" --json
+node scripts/flow-capture.js "maybe add caching?" --idea
+node scripts/flow-capture.js "refactor auth" --certain
 ```
 
 ## Options
@@ -55,3 +124,25 @@ node scripts/flow-capture.js "Bug: login fails" --json
 - `--type <type>` - Force type (bug/feature) instead of auto-detect
 - `--tags <tags>` - Add comma-separated tags
 - `--json` - Output JSON instead of minimal confirmation
+- `--no-group` - Disable auto-grouping (create separate items)
+- `--certain` - Force routing to roadmap
+- `--idea` - Force routing to discussion queue
+- `--no-route` - Disable routing, just add to backlog
+
+## Configuration
+
+In `config.json`:
+```json
+{
+  "capture": {
+    "autoGroup": true,         // Enable/disable auto-grouping
+    "groupingThreshold": 0.5,  // Similarity threshold (0-1)
+    "maxGroupSize": 5,         // Max items per group
+    "routing": {
+      "enabled": true,           // Enable routing
+      "defaultCertainty": "certain", // Default when not detected
+      "autoDetect": true         // Auto-detect from text
+    }
+  }
+}
+```

package/.claude/commands/wogi-research.md

@@ -20,42 +20,98 @@ This command is **automatically triggered** (when strict mode is enabled) for:
 3. **Existence Questions**: "Is there a...", "Does X exist?"
 4. **Architecture Questions**: "How does X work?", "How is X structured?"
 5. **Integration Questions**: "How to integrate X with Y?"
+6. **Comparison Questions**: "What can we learn from X?", "How does X compare to Y?"
 
 ## Research Protocol Phases
 
-### Phase 1: Scope Mapping
+There are two flows depending on question type:
+
+### Standard Flow (Capability, Existence, Architecture Questions)
+
+For questions like "Does X support Y?" or "How does X work?":
+
+**Phase 1: Scope Mapping**
 - Identify all potentially relevant local files
 - Identify external tools/libraries mentioned
 - Generate search keywords
-- Create `research-scope.json`
 
-### Phase 2: Local Evidence Gathering
+**Phase 2: Local Evidence Gathering**
 - Read ALL files identified in scope (not just the first match)
 - Extract relevant code snippets and documentation
-- Log findings to research notes
 - **DO NOT SKIP FILES** - partial reading leads to false conclusions
 
-### Phase 3: External Verification
+**Phase 3: External Verification**
 - For each external tool/library:
   - Web search: "[tool] documentation [feature] [current year]"
   - Read official docs (top 3 results minimum)
-  - Extract quotes with URLs
 - **ASSUME training data is 2+ years stale**
 
-### Phase 4: Assumption Check
+**Phase 4: Assumption Check**
 - List ALL assumptions made during research
-- Tag each assumption:
-  - `[VERIFIED]` with HIGH confidence + source
-  - `[UNVERIFIED]` with LOW confidence - **MUST be verified before proceeding**
+- Tag each: `[VERIFIED]` with source or `[UNVERIFIED]`
 - Loop back to Phase 2/3 for any unverified assumptions
 
-### Phase 5: Synthesis
-- Generate research report with:
-  - Answer to original question
-  - Evidence chain (every claim → source)
-  - Confidence level (HIGH/MEDIUM/LOW)
-  - Caveats and uncertainties
-  - List of searches performed
+**Phase 5: Synthesis**
+- Generate research report with citations
+- State confidence level (HIGH/MEDIUM/LOW)
+
+---
+
+### Comparison Flow (External-First)
+
+For questions like "What can we learn from X?" or "How does X compare to Y?":
+
+**⚠️ CRITICAL: Do external research FIRST**
+
+You're comparing an external tool to your codebase. You must understand what the external tool HAS before you can search locally for equivalents.
+
+**Phase 0: External Research (DO THIS FIRST)**
+- Web search the external tool/repository
+- Read their documentation, README, source code
+- List the features, patterns, or approaches they have
+- **OUTPUT**: A clear list of "External tool X has: [features]"
+
+**Phase 1: Scope Mapping (informed by Phase 0)**
+- For EACH feature found in Phase 0:
+  - Identify local files that might have equivalent functionality
+  - Use search patterns based on what you learned externally
+
+**Phase 2: Local Evidence Gathering**
+- For EACH external feature, search the local codebase
+- Read ALL potentially relevant local files
+- Note specific implementations with file paths
+
+**Phase 4: Assumption Check**
+- List assumptions, mark [VERIFIED] or [UNVERIFIED]
+- Verify anything uncertain
+
+**Phase 5: Synthesis**
+- Generate comparison table: External Feature | Local Equivalent | Status
+- Cite sources for each claim
+
+**Phase 6: Recommendation Verification (MANDATORY)**
+
+Before presenting ANY recommendation ("We should add X"):
+
+1. **Search local codebase** for equivalent functionality
+   - Use Glob/Grep with relevant patterns
+   - Search for synonyms and related terms
+2. **Read at least one potentially relevant file**
+   - Don't just search - actually read the code
+3. **Mark each recommendation**:
+   - `EXISTS` - Already implemented → **DO NOT recommend**
+   - `PARTIAL` - Partially implemented → Recommend enhancement
+   - `MISSING` - Not implemented → Safe to recommend
+4. **Include verification evidence** in output:
+   ```
+   Searched: [patterns used]
+   Read: [files examined]
+   Status: EXISTS/PARTIAL/MISSING
+   ```
+
+**ONLY recommend features marked MISSING or PARTIAL.**
+
+This phase prevents recommending features that already exist in the codebase.
 
 ## Critical Rules