Plan File Format Reference

Plan files are the single source of truth for task progress. Workers update them in place as they complete checklist items, and the dispatcher reads them to report status.

File Location

Each dispatched task gets a directory under .dispatch/tasks/:

.dispatch/
  tasks/
    <task-id>/
      plan.md      # Checklist updated by worker
      output.md    # Final output artifact (optional)
      context.md   # Context dump on IPC timeout (optional)
      ipc/         # Bidirectional communication files

Task ID naming: Short, descriptive, kebab-case identifiers like security-review, add-auth, fix-login-bug.

The .dispatch/ directory is ephemeral. Delete it to clean up task files.

Plan File Structure

Plan files use Markdown checklist format:

# Security Review

- [ ] Scan for hardcoded secrets
- [ ] Review auth logic
- [ ] Check dependencies for vulnerabilities
- [ ] Audit injection risks
- [ ] Write findings to .dispatch/tasks/security-review/output.md

Checklist Markers

Workers update checklist items using these markers:

[ ]

Pending

Not yet started, or currently in progress (if it’s the first unchecked item).

[x]

Done

Completed successfully. Workers can optionally add a note after the — separator:

- [x] Review auth logic — found rate limiting issue

[?]

Blocked

Worker is blocked and needs user input. The question should appear on the line(s) below:

- [?] Implement feature

Blocked: requirements.txt doesn't exist. What should I implement?

[!]

Error

Worker encountered an unresolvable error. The error description should appear below:

- [!] Run tests

Error: `npm test` failed with exit code 1. Missing jest.config.js

Plan Writing Guidelines

The dispatcher creates plan files before spawning workers. Follow these rules:

Match plan size to task complexity

Simple tasks (edits, quick fixes): 1-3 items
Medium tasks (refactoring, testing): 4-6 items
Complex tasks (architecture changes, multi-file refactors): 6-10 items

Don’t pad simple tasks with granular sub-steps. “Make the change and open a PR” is a single item, not three.

Use concrete, verifiable actions

Each item should be a specific action the worker can complete and verify.Good:

Scan for hardcoded API keys in src/
Add unit tests for auth.ts with 80%+ coverage
Refactor UserService to use dependency injection

Bad (too vague):

Review code
Make it better
Fix issues

Include output artifact when needed

The last item should produce an output artifact for tasks that warrant it:

- [ ] Write findings to .dispatch/tasks/<task-id>/output.md
- [ ] Write summary to .dispatch/tasks/<task-id>/output.md

For simple tasks (edits, fixes, small PRs), this isn’t needed.

Output Artifacts

output.md

Workers write final results to output.md when the task warrants a deliverable:

# Security Review Findings

## Critical Issues

1. **Hardcoded API key** (config.ts:14)
   - Risk: API key exposed in version control
   - Fix: Move to environment variable

2. **No rate limiting** (/api/login endpoint)
   - Risk: Brute force attack vulnerability
   - Fix: Implement exponential backoff

## Recommendations

- Enable dependabot for automated dependency updates
- Add pre-commit hook for secret scanning

The dispatcher surfaces this file to the user when reporting task completion.

context.md

Workers write context dumps to context.md when IPC times out (no answer to a question after ~3 minutes):

# Context for: Implement Feature

I've completed:
- [x] Read requirements.txt

I'm blocked at:
- [?] Implement /health endpoint

Blocked: requirements.txt doesn't exist. What feature should I implement?

Relevant files I've reviewed:
- src/app.ts (main Express app)
- src/routes/ (existing route handlers)

I was planning to:
1. Create a new route handler in src/routes/health.ts
2. Add the route to src/app.ts
3. Write tests in tests/health.test.ts

When the dispatcher receives the user’s answer, it spawns a NEW worker with instructions to:

Read the plan file
Read context.md for the previous worker’s context
Use the user’s answer to unblock
Continue from the blocked item onward

Context preservation is a fallback. The primary mechanism is IPC (question/answer files), which allows workers to continue without losing context. context.md is only used when IPC times out.

IPC Directory Structure

The ipc/ subdirectory enables bidirectional communication between workers and the dispatcher:

.dispatch/tasks/<task-id>/ipc/
question  # Worker's question (plain text)
answer    # Dispatcher's answer (plain text)
done      # Worker's acknowledgment
question
answer
done
  .done         # Completion marker (all tasks finished)

File Naming Convention

NNN.question

text file

Worker’s question, written atomically via temp file + mv. Sequence numbers are zero-padded to 3 digits (001, 002, 003).

NNN.answer

text file

Dispatcher’s answer to the question, written atomically.

NNN.done

marker file

Worker’s acknowledgment that it received the answer. Written after the worker reads the .answer file.

.done

marker file

Completion marker written by the worker when all checklist items are finished. Signals the monitor to exit cleanly.

Atomic Write Pattern

All IPC files use a two-step atomic write pattern to prevent reading partial content:

# Worker writing a question
echo "What feature should I implement?" > ipc/001.question.tmp
mv ipc/001.question.tmp ipc/001.question  # Atomic on POSIX

# Dispatcher writing an answer
echo "Add a /health endpoint" > ipc/001.answer.tmp
mv ipc/001.answer.tmp ipc/001.answer  # Atomic on POSIX

Both workers and dispatchers follow this pattern.

IPC Protocol Flow

The IPC system allows workers to ask questions without losing context:

Worker writes question

Worker encounters a blocker and writes to ipc/001.question (atomic write)

Monitor detects question

A lightweight monitor script polls the IPC directory. When it finds an unanswered question, it exits → triggers <task-notification>

Dispatcher reads question

Dispatcher reads ipc/001.question and surfaces it to the user

User answers

User provides an answer; dispatcher writes to ipc/001.answer (atomic write)

Dispatcher respawns monitor

The old monitor exited in step 2. Dispatcher spawns a new monitor to continue polling

Worker detects answer

Worker polls for ipc/001.answer. When found, it reads the answer, writes 001.done, and continues working without losing context

Timeout fallback: If no answer arrives within ~3 minutes, the worker dumps context to context.md, marks the item [?] in the plan file, and exits.

IPC Directionality

IPC is worker-initiated only. The worker writes questions; the dispatcher writes answers to those questions.The dispatcher must NEVER write unsolicited files to the IPC directory — the worker will not detect or process them.

To provide additional context to a running worker, append notes to the plan file instead:

# Task Title

- [x] First step
- [ ] Second step
- [ ] Third step

> **Note from dispatcher:** The skill is installed via `npx skills add`, not directly from Anthropic. Account for this in the output.

The worker reads the plan file as it works through items, so appended notes are visible.

Sequence Numbering

The next sequence number is derived from the count of existing *.question files, plus one:

# Worker determines next sequence number
NEXT_SEQ=$(printf "%03d" $(( $(ls ipc/*.question 2>/dev/null | wc -l) + 1 )))
echo "Question text" > ipc/${NEXT_SEQ}.question.tmp
mv ipc/${NEXT_SEQ}.question.tmp ipc/${NEXT_SEQ}.question

Monitor Script

A lightweight bash script polls the IPC directory and exits when it detects:

An unanswered question (.question file without matching .answer)
The completion marker (.done)

#!/bin/bash
IPC_DIR=".dispatch/tasks/<task-id>/ipc"
TIMEOUT=1800  # 30 minutes
START=$(date +%s)
shopt -s nullglob

while true; do
  # Check for completion
  [ -f "$IPC_DIR/.done" ] && exit 0
  
  # Check for unanswered questions
  for q in "$IPC_DIR"/*.question; do
    seq=$(basename "$q" .question)
    [ ! -f "$IPC_DIR/${seq}.answer" ] && exit 0
  done
  
  # Check timeout
  ELAPSED=$(( $(date +%s) - START ))
  [ "$ELAPSED" -ge "$TIMEOUT" ] && exit 1
  
  sleep 3
done

When the monitor exits, it triggers a <task-notification> that alerts the dispatcher.

Startup Reconciliation

If the dispatcher restarts mid-conversation (e.g., user closes and reopens the session), it should scan for unanswered questions:

List task directories

Scan .dispatch/tasks/ for all task directories

Check for unanswered questions

For each task, check ipc/ for *.question files without matching *.answer files

Resume IPC flow

If found, surface the question to the user and resume the IPC flow from step 3 onward (user answers → write answer → respawn monitor)

This ensures questions are never silently lost.

Example: Full Task Lifecycle

1. Dispatch

/dispatch "implement the feature described in requirements.txt"

Dispatcher creates:

.dispatch/tasks/impl-feature/
  plan.md      # With checklist
  ipc/         # Empty directory

2. Worker Progress

Worker updates plan.md as it works:

# Implement Feature

- [x] Read requirements.txt
- [ ] Implement /health endpoint
- [ ] Write tests
- [ ] Open PR

3. Worker Blocked

Worker discovers requirements.txt doesn’t exist. Writes question:

.dispatch/tasks/impl-feature/ipc/001.question

Content:

requirements.txt doesn't exist. What feature should I implement?

Monitor detects the question and exits → notification sent.

4. User Answers

Dispatcher reads the question, surfaces it:

Worker is asking: "requirements.txt doesn't exist. What feature should I implement?"

User responds:

Add a /health endpoint that returns JSON with uptime and version.

Dispatcher writes:

.dispatch/tasks/impl-feature/ipc/001.answer

Content:

Add a /health endpoint that returns JSON with uptime and version.

Dispatcher respawns monitor.

5. Worker Continues

Worker detects 001.answer, reads it, writes 001.done, continues working:

# Implement Feature

- [x] Read requirements.txt
- [x] Implement /health endpoint
- [ ] Write tests
- [ ] Open PR

6. Worker Completes

All items checked:

# Implement Feature

- [x] Read requirements.txt
- [x] Implement /health endpoint
- [x] Write tests
- [x] Open PR — https://github.com/user/repo/pull/123

Worker writes:

.dispatch/tasks/impl-feature/ipc/.done

Monitor detects .done and exits cleanly → notification sent.Dispatcher reads plan.md and reports:

`impl-feature` complete. PR opened: https://github.com/user/repo/pull/123

Plan File Best Practices

Keep items concrete

Each item should be a specific, verifiable action. Avoid vague items like “review code” or “make it better.”

Match complexity

Simple tasks get 1-3 items. Complex tasks get 6-10. Don’t over-decompose simple work.

Include output when needed

Tasks that produce findings, summaries, or reports should write to output.md as the last item.

Use notes for context

Append notes to the plan file (via > **Note:**) to provide additional context to running workers.

/dispatch Command

Command syntax and task delegation

Config File

Backend and model configuration

Command Reference

Development

Plan File Format Reference

File Location

Plan File Structure

Checklist Markers

Plan Writing Guidelines

Output Artifacts

output.md

context.md

IPC Directory Structure

File Naming Convention

Atomic Write Pattern

IPC Protocol Flow

IPC Directionality

Sequence Numbering

Monitor Script

Startup Reconciliation

Example: Full Task Lifecycle

Plan File Best Practices

Keep items concrete

Match complexity

Include output when needed

Use notes for context

/dispatch Command

Config File

Build docs developers (and LLMs) love

Command Reference

Development

​File Location

​Plan File Structure

​Checklist Markers

​Plan Writing Guidelines

​Output Artifacts

​output.md

​context.md

​IPC Directory Structure

​File Naming Convention

​Atomic Write Pattern

​IPC Protocol Flow

​IPC Directionality

​Sequence Numbering

​Monitor Script

​Startup Reconciliation

​Example: Full Task Lifecycle

​Plan File Best Practices

Keep items concrete

Match complexity

Include output when needed

Use notes for context

​Related

/dispatch Command

Config File

Build docs developers (and LLMs) love

File Location

Plan File Structure

Checklist Markers

Plan Writing Guidelines

Output Artifacts

output.md

context.md

IPC Directory Structure

File Naming Convention

Atomic Write Pattern

IPC Protocol Flow

IPC Directionality

Sequence Numbering

Monitor Script

Startup Reconciliation

Example: Full Task Lifecycle

Plan File Best Practices

Related