Skip to content

Cursor Multitask playbook

How to run Cursor Teamwork / Multitask on bounded features without polluting git with ephemeral orchestration state. Distilled from the aifeatures-site Vitest suite run (Aug 2026).

Canonical agent setup: Cursor agent setup.

When to use Multitask

Use Multitask when:

  • The feature has clear milestones and acceptance criteria
  • Parallel exploration or review gates save time (test suite, large refactor, multi-module feature)
  • A single agent session would lose track of scope

Use a single Agent for doc fixes, one-file bugs, and config tweaks.

Use Ship workers when work must land as a Plane ticket + Forgejo PR + Woodpecker CI without your IDE open.

Dual-track pattern

Orchestrator (metadata only — no src/ edits)
├── Implementation track (per milestone)
│   Explorer → Worker → Reviewer → Challenger → Auditor
└── E2E / acceptance track
    e2e_testing_orch → TEST_INFRA.md → TEST_READY.md

Role constraints

Archetype May do Must not
Orchestrator Update .agents/*/PROJECT.md, BRIEFING.md, DISPATCH.md, GATE_STATUS.md Edit src/, run builds/tests directly
Explorer Read codebase, write survey notes Implement features
Worker Implement code + tests per milestone Skip tests, hardcode fake assertions
Reviewer Code review, request changes Merge without green tests
Challenger Adversarial cases, benchmark disputes Override auditor veto
Auditor Forensic integrity check, veto cheating Write production code

Starter template pack

Copy from templates/multitask/ into the target repo before starting Multitask:

File Purpose
ORIGINAL_REQUEST.md Verbatim user prompt + acceptance criteria
PROJECT.md Milestones, feature inventory, interface contracts
BRIEFING.md Orchestrator mission + team roster stub
DISPATCH.md Per-milestone dispatch log
GATE_STATUS.md Pass/fail gates per milestone
archetypes.md Role constraints (this table expanded)

After the run:

  1. Commit distilled specs under docs/ (e.g. docs/testing/)
  2. Commit source code and tests
  3. Do not commit .agents/teamwork_* runtime trees — add .agents/ to .gitignore

Example: aifeatures-site test suite (Aug 2026)

Prompt: Ultra-fast (<15s) Vitest + RTL suite in Docker for FeatureMatrix, CalculatorView, CommandPalette, ToolCard + glass-token styling.

Milestone Scope Status
M1 Test infra (vitest, happy-dom, renderWithRouter) Done
M2 Component + DOM assertion tests Done
M3 Translucency / glass token tests Done
M4 Docker benchmark <15s Open (18–20s observed)
M5 Tier 5 adversarial hardening Planned

Committed specs: aifeatures-site/docs/testing/ (from multitask TEST_*.md).

Multitask-ready work packages

Independent tracks for parallel subagents after docs land:

Documentation (low risk)

  • Hub doc + per-repo docs/AI_CONTEXT.md IDE tables
  • AGENTS.md cross-links
  • Reviewer pass on MCP names and graphify commands

Cursor config bootstrap

  • .cursor/rules/ + hooks.json for app repos
  • local/gen-*-mcp-json.sh scripts
  • templates/cursor-app/ for onboard

Product (example: aifeatures M4)

  • Rebuild Docker dev image
  • Run docker compose run --rm dev npm test -- --legacy-peer-deps
  • Document wall-clock in docs/testing/benchmark.md
  • Challenger reviews <15s target vs measured time

Failure handling

Orchestrator escalation order (from aifeatures pattern):

  1. Retry same worker with clearer dispatch
  2. Replace worker
  3. Skip non-critical milestone (document in GATE_STATUS.md)
  4. Redistribute work across milestones
  5. Redesign scope in PROJECT.md
  6. Escalate to human (you)