cokaremote/docs/superpowers/plans/2026-09-17-managed-task-tools.md

Managed Task Tools Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Add recoverable, compact-output managed task tools for long-running Coka MCP commands.

Architecture: Add a ManagedTaskManager facade on top of the existing ProcessManager. Extend process startup with an internal output observer so managed tasks can persist complete output without changing low-level tool responses, then register four additive MCP tools.

Tech Stack: Node.js 22+, TypeScript, MCP SDK, Zod, Vitest.

Spec: docs/superpowers/specs/2026-09-17-managed-task-tools-design.md

Global Constraints

• Preserve all existing low-level process tools and semantics.
• Do not execute the same retained managed task twice when the same task key, command, and cwd are supplied.
• Store full managed-task output on disk while keeping MCP responses bounded.
• Recovery must work by stable task key after a response-stream interruption.

---

Task 1: Managed task core

Files:

• Create: src/managed-task-manager.ts

• Modify: src/process-manager.ts

• Test: test/managed-task-manager.test.ts

• Write failing tests for reuse, compact summaries/full logs, restart, cancellation, and recovery listing.

• Run the focused test and verify RED.

• Add the smallest ProcessManager output-observer seam and ManagedTaskManager implementation.

• Run the focused test and verify GREEN.

Task 2: MCP tool surface

Files:

• Create: src/managed-task-tools.ts

• Modify: src/mcp-server.ts

• Modify: test/tool-metadata.test.ts

• Modify: test/all-tools.integration.test.ts

• Update inventory/metadata tests first and verify RED.

• Register start_managed_task, read_managed_task, list_managed_tasks, and cancel_managed_task.

• Exercise start/reuse/read/list/cancel through MCP integration tests.

• Verify focused tests GREEN.

Task 3: Documentation and regression verification

Files:

• Modify: README.md

• Create: AGENTS.md

• Document the high-level managed-task workflow and recovery behavior.

• Run npm test.

• Run npm run typecheck.

• Run npm run build.

• Run git diff --check and inspect the final diff.