Task pipeline

A phased workflow for complex tasks. State lives in files, not session memory. Any session can pick up where the last one left off by reading the docs.

File structure

All work happens in a worktree at

<repo>/.worktrees/<branch>/

plans/

plans/
  task.md     # research findings (fixed filename)
  plan.md     # implementation plan (fixed filename)

Fixed filenames because worktrees already isolate tasks — no need for unique slugs. Overwrite if exists.

Phase 1: Research

Entry:

/task <description>

/task

Any text after

/task

This phase runs in an isolated subagent (

researcher

1. If

   plans/task.md

   exists: main agent reads it and passes contents as context to the researcher subagent
2. Main agent invokes the subagent tool:

   { agent: "researcher", task: "<research task with context>" }

3. The researcher subagent runs in isolation — it can read, search, and run read-only commands, but cannot edit, write, or modify anything
4. Main agent saves the subagent output to

   plans/task.md

Research doc format

# <task description>

## Findings

- Finding 1 with evidence
- Finding 2 with source references
- ...

## Open questions

- Question that couldn't be answered
- ...

## Sources

- file paths, URLs, session references

Keep writing until you can't find more. The user will tell you when to move on.

Phase 2: Plan

Entry:

/plan

/plan <context>

This phase runs in an isolated subagent (

planner

1. Main agent reads

   plans/task.md

   — the research findings
2. If

   plans/task.md

   doesn't exist: tell the user to run

   /task

   first
3. If the user passed inline context (

   /plan <context>

   ), prepend it to the research findings before passing to the planner
4. Main agent invokes the subagent tool:

   { agent: "planner", task: "<user context + research findings>" }

5. The planner subagent runs in isolation — it can read files but cannot edit or write anything
6. Main agent saves the subagent output to

   plans/plan.md

Plan doc format

# Plan: <task description>

Research: `plans/task.md`

## Steps

### Step 1: <title>

- **What:** description
- **Files:** paths to change
- **Verify:** how to confirm it works

### Step 2: <title>

- **What:** description
- **Files:** paths to change
- **Verify:** how to confirm it works

## Notes

- Design decisions, trade-offs, things to watch out for

Each step maps 1:1 to a ticket. Steps are ordered by dependency.

The user reviews and iterates. Do not proceed to tickets until the user explicitly says to.

Phase 3: Tickets

Entry:

/tickets

1. Read

   plans/plan.md

2. Explore the codebase for file hints and verification commands
3. Seed

   plans/.ticket-context.md

   if it doesn't exist (see context seeding in ticket-creator skill)
4. Create one ticket per plan step using ticket-creator skill Mode 3
5. Self-validate (mandatory, every time):

   • tk list

     — check all tickets are open
   • For each ticket:

     tk show <id>

     — verify description has file hints, acceptance criteria are numbered and independently verifiable
   • Refine any weak tickets immediately

   • tk dep cycle

     — no cycles allowed

   • tk ready -T ready-for-development

     — at least one ticket must be unblocked
6. Report what was created

Phase transitions

/task <description>

/task

/plan

/plan <context>

/plan <context>

/tickets

work-tickets

You can go back: run

/plan

/tickets

tk close

Rules

• Always work in the worktree, not main checkout
• Always read existing files before writing — pick up where you left off
• Research and plan docs are living documents — update, don't replace with alternatives
• Plan steps must be small enough for one agent session (~30 min of work)
• Never skip self-validation when creating tickets