@monoes/monomindcli 1.6.8 → 1.7.0

package/.claude/commands/monomind-do.md

@@ -1,6 +1,6 @@
 ---
 name: monomind-do
-description: "Monomind — Pick up tasks from monomind-task board, execute them with smart agent selection, review, fix bugs, then loop every 2 minutes"
+description: "Monomind — Execute tasks from monomind-task board with parallel, minimal, or sequential agent modes, smart context group routing, and review cycles"
 ---
 
 ## Argument Parsing
@@ -10,6 +10,8 @@ Parse `$ARGUMENTS` for the following flags (in any order):
 - `--space <SPACE_ID>` — use this space directly (skip space discovery)
 - `--board <BOARD_ID>` — use this task board directly (skip board discovery)
 - `--filter <text>` — only process tasks whose title contains this text (case-insensitive)
+- `--mode <parallel|minimal|sequential>` — execution mode (default: ask user)
+- `--max-agents <N>` — cap total agent spawns per run (default: 20). Prevents runaway costs on large boards.
 
 If `$ARGUMENTS` contains none of these flags, treat the entire string as a filter (legacy mode).
 
@@ -41,7 +43,7 @@ If `cargo` is also missing, output this and STOP:
 
 ## Step 1: Find the Task Board
 
-**If `--space` and `--board` were provided:** Skip discovery. Use the provided `SPACE_ID` and `TASK_BOARD_ID` directly. Jump to step 4.
+**If `--space` and `--board` were provided:** Skip discovery. Use the provided `SPACE_ID` and `TASK_BOARD_ID` directly. Jump to column discovery.
 
 **Otherwise, discover them:**
 
@@ -55,9 +57,73 @@ If `cargo` is also missing, output this and STOP:
 
 ---
 
-## Step 1.5: Initialize Loop State
+## Step 2: Scan All Tasks and Build Execution Plan
 
-Generate a loop ID and write the initial state file so the dashboard can track this run:
+### 2a: Load all pending tasks
+
+List cards in `Todo` and `Backlog`:
+```bash
+monotask card list $TASK_BOARD_ID $COL_TODO --json
+monotask card list $TASK_BOARD_ID $COL_BACKLOG --json
+```
+
+If `--filter` was set, filter by title match.
+
+If no cards found, output:
+```
+[monomind:do] No tasks in Todo or Backlog. Queue empty.
+```
+Remove any loop state files and STOP.
+
+### 2b: Read task metadata
+
+For each card, read its comments to extract:
+- **Assigned agent type** (from "Assigned agent:" comment)
+- **Context group** (from "Context group:" comment)
+- **Prerequisites** (from "Prerequisites:" comment)
+- **Parallel safe** (from "Parallel safe:" comment, default `true`)
+
+### 2c: Build context groups
+
+Group tasks by their `context_group` value:
+- Tasks with the same context group form a **chain** — they run sequentially on the same agent
+- Tasks with `context_group: independent` or no group are **independent** — they can run on any agent
+- Within a chain, order by prerequisites (prerequisite first)
+
+### 2d: Check session memory for execution strategy
+
+Call `mcp__monomind__memory_search` with `"task-strategy:<REPO_NAME>"`. If a recent strategy exists, use its `recommended_execution_mode` as the default.
+
+### 2e: Choose execution mode
+
+**If `--mode` was provided:** Use that mode.
+
+**If session memory has a recommendation:** Present it as default.
+
+**Otherwise, ask the user:**
+
+```
+[monomind:do] Found N tasks: X in context groups, Y independent.
+
+Context groups:
+  - <group-1>: 3 tasks (agent: backend-dev, sequential)
+  - <group-2>: 2 tasks (agent: Frontend Developer, sequential)
+  - independent: 4 tasks (mixed agents, parallelizable)
+
+How do you want to execute?
+
+1. **Parallel** — Spawn one agent per context group + one per independent task. (~N agents, fastest)
+2. **Minimal** — One agent per context group + one shared agent for all independents. (~M agents, balanced)
+3. **Sequential** — One agent processes everything in order. (1 agent, cheapest)
+```
+
+Store chosen mode as `EXEC_MODE`.
+
+---
+
+## Step 3: Initialize Loop State
+
+Generate a loop ID and write the initial state file:
 ```bash
 mkdir -p .monomind/loops
 export DO_LOOP_ID="do-$(date +%s%3N)"
@@ -66,7 +132,8 @@ cat > ".monomind/loops/${DO_LOOP_ID}.json" << EOF
   "id": "${DO_LOOP_ID}",
   "type": "do",
   "prompt": "/monomind:do $ARGUMENTS",
-  "currentTask": "discovering...",
+  "mode": "${EXEC_MODE}",
+  "currentTask": "starting...",
   "spaceId": "${SPACE_ID:-}",
   "boardId": "${TASK_BOARD_ID:-}",
   "filter": "${FILTER:-}",
@@ -78,142 +145,168 @@ cat > ".monomind/loops/${DO_LOOP_ID}.json" << EOF
 EOF
 ```
 
-Also check if a stop was requested from a previous cycle:
+Check if a stop was requested:
 ```bash
 [ -f ".monomind/loops/${DO_LOOP_ID}.stop" ] && echo "DO_STOP_REQUESTED=true"
 ```
 If `DO_STOP_REQUESTED=true`, output `[monomind:do] Stop requested via dashboard. Halting.`, remove state files, and STOP.
 
-## Step 2: Find Next Task
-
-1. List cards in `Todo` first (prioritized), then `Backlog`:
-   ```bash
-   monotask card list $TASK_BOARD_ID $COL_TODO --json
-   monotask card list $TASK_BOARD_ID $COL_BACKLOG --json
-   ```
-
-2. If `$ARGUMENTS` was provided, filter by title match.
+---
 
-3. Pick the **first available card** (Todo before Backlog). If no cards found, output:
-   ```
-   [monomind:do] No tasks in Todo or Backlog. Checking again in 2 minutes...
-   ```
-   Update loop state before scheduling:
-   ```bash
-   NEXT_AT=$(( $(date +%s%3N) + 120000 ))
-   cat > ".monomind/loops/${DO_LOOP_ID}.json" << EOF
-   {"id":"${DO_LOOP_ID}","type":"do","prompt":"/monomind:do $ARGUMENTS","currentTask":"queue empty — waiting","spaceId":"${SPACE_ID:-}","boardId":"${TASK_BOARD_ID:-}","filter":"${FILTER:-}","startedAt":$(cat .monomind/loops/${DO_LOOP_ID}.json 2>/dev/null | python3 -c "import sys,json;print(json.load(sys.stdin).get('startedAt',0))" 2>/dev/null || date +%s%3N),"lastRunAt":$(date +%s%3N),"nextRunAt":${NEXT_AT},"status":"waiting"}
-   EOF
-   ```
-   Then use `ScheduleWakeup` with `delaySeconds: 120` and prompt `/monomind:do --space $SPACE_ID --board $TASK_BOARD_ID` (plus `--filter` if one was set) to check again. STOP this iteration.
+## Step 4: Execute Based on Mode
 
-4. Store `CURRENT_CARD_ID` and `CURRENT_CARD_TITLE`.
+### Agent Budget Guard
 
----
+Before spawning, count total agents needed:
+- **Parallel**: one per context group + one per independent task
+- **Minimal**: one per context group + one shared
+- **Sequential**: one
 
-## Step 3: Read Full Task Context
+If total exceeds `--max-agents` (default: 20), downgrade mode automatically:
+- Parallel → Minimal (if still over budget → Sequential)
+- Output: `[monomind:do] Agent budget exceeded (N > max-agents). Downgrading to <mode>.`
 
-Gather ALL context for the selected card:
+Track `AGENTS_SPAWNED` counter. If it hits the limit mid-run (e.g., during review cycles), stop spawning and queue remaining work for the next cycle.
 
-1. **Card details**: Run `monotask card view $TASK_BOARD_ID $CURRENT_CARD_ID` to get title, description, impact, effort, and priority.
+### Mode: Parallel
 
-2. **Comments**: Run `monotask card comment list $TASK_BOARD_ID $CURRENT_CARD_ID --json`. Parse for:
-   - Task description (first comment)
-   - **Assigned agent type** — look for a comment starting with "Assigned agent:" and extract the type
-   - Additional context, edge cases, technical notes
+Spawn ALL agents in ONE message using the Agent tool:
 
-3. **Checklist**: Run `monotask card checklist list $TASK_BOARD_ID $CURRENT_CARD_ID --json`. If a checklist exists, treat each unchecked item as a sub-step.
+**For each context group chain:**
+- Spawn ONE agent of the chain's recommended type
+- Provide it with ALL tasks in the chain, in prerequisite order
+- The agent executes them sequentially, committing after each
+- Agent prompt includes: full task context for ALL tasks in the chain, project context, instruction to execute in order
 
-4. **Subtasks**: Check if comments reference subtask card IDs or child cards.
+**For each independent task:**
+- Spawn ONE agent of the task's assigned type
+- Provide it with that single task's context
+- The agent executes and commits
 
-5. **Attached images**: If comments contain image paths or URLs, read them with the Read tool.
+All agents run concurrently via `run_in_background: true`.
 
-Bundle into `TASK_CONTEXT`.
+**Agent prompt template for chain execution:**
+```
+You have N tasks to execute in order. Complete each one before moving to the next.
+Tasks share context — knowledge from earlier tasks applies to later ones.
+
+TASK 1 of N: <title>
+<full task context, checklist, acceptance criteria>
+
+TASK 2 of N: <title>
+<full task context, checklist, acceptance criteria>
+...
+
+For each task:
+1. Implement the changes following the checklist
+2. Write/update tests
+3. Verify tests pass
+4. Commit with descriptive message
+5. Write a HANDOFF CONTEXT section (3-5 lines): what files changed, what decisions were made, what the next task needs to know
+6. Report: DONE | DONE_WITH_CONCERNS | BLOCKED (with details)
+
+IMPORTANT — Handoff Context:
+After completing each task in the chain, write a brief ## Handoff Context block:
+- Files created/modified (with paths)
+- Key decisions made (naming, patterns chosen, trade-offs)
+- State the next task inherits (new types, config values, API shapes)
+This ensures continuity even if context is compressed between tasks.
+
+If you are BLOCKED on any task, STOP the entire chain. Do not attempt subsequent tasks.
+Report which task is blocked and list the remaining unstarted tasks.
+```
 
----
+**Agent prompt template for independent tasks:**
+```
+Execute this single task:
 
-## Step 4: Gather Project Context
+TASK: <title>
+<full task context, checklist, acceptance criteria>
 
-Collect in parallel (skip any that error):
+1. Implement the changes following the checklist
+2. Write/update tests
+3. Verify tests pass
+4. Commit with descriptive message
+5. Report: DONE | DONE_WITH_CONCERNS | BLOCKED (with details)
+```
 
-1. **README**: Read `README.md` (first 200 lines).
-2. **Package manifest**: Read whichever exists first: `package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`.
-3. **Memory search**: Call `mcp__monomind__memory_search` with the card title.
-4. **Knowledge graph**: Call `mcp__monomind__graphify_suggest` with the card title.
+Move all cards to `In Progress` before spawning agents:
+```bash
+monotask card move $TASK_BOARD_ID $CARD_ID $COL_IN_PROGRESS --json
+```
 
-Bundle into `PROJECT_CONTEXT`.
+### Mode: Minimal
 
----
+Same as parallel, but:
+- One agent per context group chain (same as parallel)
+- ONE shared agent for ALL independent tasks (executes them sequentially)
+- Total agents = number of context groups + 1
 
-## Step 5: Move to In Progress
+### Mode: Sequential
 
-```bash
-monotask card move $TASK_BOARD_ID $CURRENT_CARD_ID $COL_IN_PROGRESS --json
-monotask card comment add $TASK_BOARD_ID $CURRENT_CARD_ID "Work started by monomind:do"
-```
+Spawn ONE agent with ALL tasks (all chains flattened into prerequisite order, then independents):
+- The single agent receives every task
+- Executes them in order, committing after each
+- Maximum context preservation, minimum cost
 
 ---
 
-## Step 6: Assess Complexity and Choose Execution Mode
+## Step 5: Gather Project Context (for agent prompts)
 
-Analyze the task to determine complexity:
+Collect in parallel (skip any that error):
 
-**Simple task** (single agent) — use when:
-- Task touches 1-2 files
-- Clear, self-contained scope
-- Checklist has fewer than 4 items
-- Effort score is 0-4
+1. **README**: Read `README.md` (first 200 lines).
+2. **Package manifest**: Read whichever exists first: `package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`.
+3. **Memory search**: Call `mcp__monomind__memory_search` with the first task's title.
+4. **Knowledge graph**: Call `mcp__monomind__graphify_suggest` with the first task's title.
 
-**Complex task** (swarm) — use when:
-- Task touches 3+ files or multiple modules
-- Has subtasks or long checklist (4+ items)
-- Involves cross-cutting concerns (API + DB + tests + docs)
-- Effort score is 5-10
+Bundle into `PROJECT_CONTEXT` and include in every agent prompt.
 
-### Simple mode: Single Agent
+---
 
-Determine the agent type from the "Assigned agent:" comment. If none specified, default to `coder`.
+## Step 6: Read Full Task Context (for each task)
 
-Spawn the agent via the Agent tool with:
-- Full `TASK_CONTEXT` and `PROJECT_CONTEXT`
-- The checklist items as step-by-step guide
-- Instructions to commit changes with a descriptive message
+For each task being assigned to an agent, gather:
 
-### Complex mode: Swarm
+1. **Card details**: Run `monotask card view $TASK_BOARD_ID $CARD_ID` to get title, description, impact, effort, priority.
 
-Use a `hierarchical` swarm with `raft` consensus and `specialized` strategy.
+2. **Comments**: Run `monotask card comment list $TASK_BOARD_ID $CARD_ID --json`. Parse for:
+   - Task description and context
+   - Assigned agent type
+   - Context group and prerequisites
+   - Acceptance criteria
+   - Additional notes
 
-Agent team (4-6 agents based on task domain):
-- **coordinator** — plans and delegates subtasks
-- **assigned agent type** (from card) — primary implementer
-- **tester** — writes and runs tests for the changes
-- Additional agents as needed based on task domain (e.g., `backend-dev` + `Frontend Developer` for full-stack work)
+3. **Checklist**: Run `monotask card checklist list $TASK_BOARD_ID $CARD_ID --json`. If a checklist exists, include as step-by-step guide.
 
-Spawn all agents in ONE message via the Agent tool. The coordinator receives the full task context and delegates to specialists.
+Bundle into `TASK_CONTEXT` for that task.
 
-### Agent prompt requirements (both modes):
+---
 
-The agent(s) MUST:
-- Implement the task as described
-- Follow the checklist if one exists
-- Write or update tests for all changes
-- Commit changes with descriptive messages
-- Report back with one of:
-  - **DONE**: Task completed. Include summary of changes and list of files modified.
-  - **DONE_WITH_CONCERNS**: Task completed with concerns. Include concerns.
-  - **BLOCKED**: Cannot complete. Include the specific question or blocker.
+## Step 7: Handle Agent Results
 
----
+After each agent completes (or all agents in parallel mode), process results:
 
-## Step 7: Handle Subtasks
+### For each completed task:
 
-After the main task completes, check for subtasks (child cards or referenced cards).
+**If DONE or DONE_WITH_CONCERNS:**
+- Proceed to review cycle (Step 8)
 
-For each subtask:
-1. Read its full context (same as Step 3)
-2. Move to `In Progress`
-3. Assess complexity and execute (same as Step 6, using the subtask's assigned agent or inheriting from parent)
-4. Run through the review cycle (Step 8) independently
+**If BLOCKED:**
+1. Add the blocking question as a comment:
+   ```bash
+   monotask card comment add $TASK_BOARD_ID $CARD_ID "Blocked: <question or issue>"
+   ```
+2. Move card to `Human in Loop`:
+   ```bash
+   monotask card move $TASK_BOARD_ID $CARD_ID $COL_HUMAN_IN_LOOP --json
+   ```
+3. **Chain failure propagation**: If this task belongs to a context group chain, ALL remaining tasks in that chain are now blocked. For each subsequent task in the chain:
+   ```bash
+   monotask card move $TASK_BOARD_ID $DEPENDENT_CARD_ID $COL_BACKLOG --json
+   monotask card comment add $TASK_BOARD_ID $DEPENDENT_CARD_ID "Chain paused: prerequisite '<blocked task title>' is blocked. Reason: <blocker summary>"
+   ```
+   Do NOT attempt to execute remaining chain tasks — they depend on the blocked task's output and context.
 
 ---
 
@@ -257,38 +350,38 @@ Proceed to Step 9.
 ### If APPROVED (from review cycle):
 1. Add a comment summarizing the changes and review outcome:
    ```bash
-   monotask card comment add $TASK_BOARD_ID $CURRENT_CARD_ID "Completed and reviewed: <summary>"
+   monotask card comment add $TASK_BOARD_ID $CARD_ID "Completed and reviewed: <summary>"
    ```
 2. If there's a checklist, mark completed items:
    ```bash
-   monotask card checklist check $TASK_BOARD_ID $CURRENT_CARD_ID <ITEM_ID>
+   monotask card checklist check $TASK_BOARD_ID $CARD_ID <ITEM_ID>
    ```
 3. If DONE_WITH_CONCERNS, add concerns:
    ```bash
-   monotask card comment add $TASK_BOARD_ID $CURRENT_CARD_ID "Concerns: <concerns>"
+   monotask card comment add $TASK_BOARD_ID $CARD_ID "Concerns: <concerns>"
    ```
 4. Move card to `Review`:
    ```bash
-   monotask card move $TASK_BOARD_ID $CURRENT_CARD_ID $COL_REVIEW --json
+   monotask card move $TASK_BOARD_ID $CARD_ID $COL_REVIEW --json
    ```
-
-### If BLOCKED (from execution):
-1. Add the blocking question:
+5. **Unblock dependents**: If this task was a prerequisite for other tasks, move those from `Backlog` to `Todo`:
    ```bash
-   monotask card comment add $TASK_BOARD_ID $CURRENT_CARD_ID "Blocked: <question or issue>"
-   ```
-2. Move card to `Human in Loop`:
-   ```bash
-   monotask card move $TASK_BOARD_ID $CURRENT_CARD_ID $COL_HUMAN_IN_LOOP --json
+   monotask card move $TASK_BOARD_ID $DEPENDENT_CARD_ID $COL_TODO --json
    ```
 
 ---
 
 ## Step 10: Summary and Next Cycle
 
-Output a single status line:
+Output a status summary:
 ```
-[monomind:do] "<title>" → <Review | Human in Loop> (agent: <type>, mode: <single|swarm>, review: <approved|blocked>)
+[monomind:do] Execution complete (mode: <parallel|minimal|sequential>)
+
+| Task                          | Status         | Agent        | Review     |
+|-------------------------------|----------------|-------------|------------|
+| <title>                       | Review         | backend-dev | approved   |
+| <title>                       | Review         | coder       | approved   |
+| <title>                       | Human in Loop  | coder       | blocked    |
 ```
 
 Then check for remaining tasks:
@@ -297,18 +390,37 @@ monotask card list $TASK_BOARD_ID $COL_TODO --json
 monotask card list $TASK_BOARD_ID $COL_BACKLOG --json
 ```
 
-If tasks remain, output:
+If tasks remain (including newly unblocked ones), output:
 ```
-[monomind:do] Remaining: N in Todo, M in Backlog. Next task in 2 minutes...
+[monomind:do] Remaining: N in Todo, M in Backlog. Processing next batch in 2 minutes...
 ```
 
-Use `ScheduleWakeup` with `delaySeconds: 120` and prompt `/monomind:do --space $SPACE_ID --board $TASK_BOARD_ID` (plus `--filter` if one was set) to process the next task.
+Update loop state and use `ScheduleWakeup` with `delaySeconds: 120` and prompt `/monomind:do --space $SPACE_ID --board $TASK_BOARD_ID --mode $EXEC_MODE` (plus `--filter` if one was set).
 
 If no tasks remain, output:
 ```
 [monomind:do] All tasks processed. Queue empty.
 ```
 
+### Store execution outcome in session memory
+
+Call `mcp__monomind__memory_store` with:
+```json
+{
+  "key": "execution-outcome:<REPO_NAME>:<timestamp>",
+  "content": {
+    "mode": "<EXEC_MODE>",
+    "tasks_completed": N,
+    "tasks_blocked": M,
+    "agents_spawned": K,
+    "review_cycles": L,
+    "outcome": "success | partial | blocked",
+    "lessons": ["any patterns observed — e.g. 'context groups worked well', 'task X was too large']"
+  },
+  "tags": ["execution-outcome", "monomind-do"]
+}
+```
+
 Remove the loop state file:
 ```bash
 rm -f ".monomind/loops/${DO_LOOP_ID}.json" ".monomind/loops/${DO_LOOP_ID}.stop"