task-planning-shrimp

Shrimp holds a persistent task graph (status, dependencies, verification criteria) outside chat context. It does not replace Cursor Plan Mode for interactive planning in the current session.

Shrimp vs Plan Mode

CoVe validates the plan whether Plan Mode or Shrimp produced it.

Activation gate (anti-noise)

Activate only when both are true:

1. Cross-session continuity — work will continue in a later chat or after context limits.
2. Structured backlog — multiple tasks with explicit dependencies, not a single atomic change.

Also activate when user explicitly asks for Shrimp, or /next / /retro already has Shrimp tasks for this effort.

Skip when:

• Single command, short Q&A, or bugfix in one session → troubleshooting-rca / Agent.
• Planning that ends in the same session → Plan Mode only (do not split_tasks for duplicate plan).
• Backlog belongs in issue tracker (GitHub/Linear) and won't be resumed via Shrimp.

Global volume warning (this setup)

In ~/.cursor/mcp.json, Shrimp uses one Docker volume (shrimp_data) for all workspaces — not per git repo.

Before split_tasks on a new effort:

1. list_tasks — note unrelated pending / in_progress from other projects.
2. If switching project context: use updateMode: clearAllTasks (backs up first) or append only when continuing the same epic.
3. State in one line which project/epic the new tasks belong to (task names or globalAnalysisResult).

Shrimp granularity (follow MCP, not arbitrary splits)

split_tasks expects coarse subtasks (from tool schema):

• Each subtask: completable in ~1–2 working days (8–16 h), single technical domain.
• Per split: ≤10 subtasks (prefer batches of 6–8).
• Task tree depth: ≤3 levels.
• Do not split into dozens of 30-minute micro-tasks — that fights the tool design.

For fine-grained same-session steps, use Plan Mode checkboxes instead.

Procedure

1) Discover existing state

list_tasks(status: "in_progress")
list_tasks(status: "pending")

If continuing: get_task_detail on the active task; set existingTasksReference: true in plan_task.

2) Plan (no code changes)

plan_task(description, requirements, existingTasksReference?)

Optional refinement: analyze_task, reflect_task, research_mode for complex/unknown domains.

3) Split into graph

split_tasks(updateMode, tasksRaw, globalAnalysisResult?)

Each task object must include:

updateMode:

4) Hand off to execution

Return: task IDs (from list_tasks), next executable task (deps satisfied), and activate mcp-shrimp-execution-loop.

Do not call execute_task in planning-only mode (Shrimp TaskPlanner vs TaskExecutor separation).

Dependency rules

• Dependencies are task names (strings), not IDs, in split_tasks.
• Before recommending execute_task, confirm prerequisite tasks are completed via list_tasks / get_task_detail.
• If execution fails with dependency conflict: complete or update_task dependencies, then retry.
• UNCERTAIN: whether server hard-blocks execute_task when deps are open — always verify in list_tasks first.

Alternatives when Shrimp is wrong tool

Output

• Epic summary (1–2 sentences)
• globalAnalysisResult echo if set
• Table: task name | status | blocked by | taskId
• Next task to run (with taskId) + which skill: mcp-shrimp-execution-loop