task

task-pipeline

Docs & guides → spair.github.io/task-pipeline

A plan file is only as good as the argument that produced it.

You:    "Let's cache the API responses in Redis."
Claude: "Great idea! I'll start implementing."

That second line is where projects quietly go wrong: the model agrees and starts building before the plan was ever argued. task-pipeline keeps the discussion and the doing apart, and sizes the paperwork to the task. Talk it through in chat; when you're ready, one command freezes that discussion into a single Markdown file under .task/ at the depth you pick — to-task for the what and why, to-plan to add a stepwise plan, to-roadmap for a multi-task initiative, to-spec to pin the load-bearing decisions. Then any session — this one, or a fresh one tomorrow — implements that file the same way: work the plan, commit, then hand the diff to the plugin's own reviewer agent, which proves each finding before it touches anything, runs your build and tests, and commits its fixes as a second commit on top — your implementation commit is never rewritten.

And when "talk it through" needs teeth, /task:grill interrogates the plan first (optional): one question at a time, its recommendations allowed to disagree with you, closing on a pre-mortem — so what gets frozen is what survived the questioning, not the first idea that sounded good. It's for tasks longer than one session; a two-file, twenty-minute fix doesn't need any of this, and leaves no trace either way — here's exactly what it will and won't touch.

discuss in chat
  → grill it (optional — interrogate the plan first)
  → capture to a file
  → any session implements it

Quickstart

/plugin marketplace add https://github.com/SpaiR/task-pipeline.git
/plugin install task@task-pipeline

Talk a task through in chat — say, an HTTP retry system with backoff and a dead-letter queue.

Optional first move: grill the plan before you freeze it. It writes nothing and needs no setup, so it works as the very first command in a fresh project — .task/CLAUDE.md is only written later, at your first capture:

/task:grill
#   → one question at a time, each with a recommended answer:
#     "Retry the 429s too, or only 5xx and timeouts?"  [recommended: 429s too]
#   → pushes back when the reasoning is thin; recommendations may disagree with you
#   → closes with a pre-mortem, prints a decision ledger, and routes you to the
#     right capture skill — never runs it for you, and touches nothing under .task/

Then capture the discussion at the depth you want:

/task:to-plan
#   → drafts .task/task/http-retry-backoff.md: ## Description + ## Plan (Goal/Touches/Logic steps)
#   → footer: implement it now, or in a fresh session run:
#     `implement .task/task/http-retry-backoff.md`

Hand the file to any session — this one or a fresh one:

"implement .task/task/http-retry-backoff.md"
#   → follows the artifact's ## Execution pointer into .task/CLAUDE.md
#   → implements per the plan, commits per .task/CLAUDE.md → Commit Format
#   → hands that diff to the task:code-reviewer agent: it proves each finding
#     before fixing it, runs your build and tests, and commits its fixes on top

That session follows the artifact's ## Execution pointer into .task/CLAUDE.md → ## Executing a task: implement the plan, commit per .task/CLAUDE.md → Commit Format, then spawn task:code-reviewer on the resulting diff. The reviewer proves each candidate defect independently, fixes only the confirmed ones inside the files named in Touches (plus a regression this change caused outside them), reports the rest instead of quietly widening the diff, runs .task/CLAUDE.md → Build and Tests, and commits its fixes as a second commit on top — the implementation's commit is never rewritten, so a task is one commit, plus one more only when the review actually fixed something.

The first capture in a fresh project also writes .task/CLAUDE.md inline (detect language + test policy, write, report) — there's no separate setup command to run first, and no confirmation to click through. Prefer a lighter touch? /task:to-task skips the Plan — good for a quick capture you'll flesh out with /task:to-plan later, or hand straight to implementation when the fix is obvious.

[!TIP] More scenarios — roadmap-driven initiatives, /task:roadmap-to-workflow, and returning to a task later — live in the guide on the docs site.

Why

task-pipeline doesn't fight the one-big-session failure with more machinery — it argues with the plan first, then sizes the record to the task. It leans on what Claude Code already ships (dynamic Workflows, your project's own build and test commands) and adds just enough structure around them: one artifact per task (.task/task/<slug>.md) carrying the discussion's "what, why, and how" in your language, plus a fixed ## Execution block (English, like every parser-stable string) that carries the run from implementation through commit to the review pass.

Concretely, you get:

• Depth is a skill you pick, not a flag. A two-file fix and a month-long migration don't deserve the same ceremony — reach for to-task, to-plan, to-roadmap, or to-spec and the file carries exactly that much structure. There is no --plan or --deep switch anywhere.
• The plan gets grilled before it gets frozen. /task:grill keeps a decision-plus-rationale ledger, makes recommendations that are allowed to disagree with you, and closes with a pre-mortem — so no "great idea!" rubber-stamp makes it into the file.
• Nothing new to learn on the execution side. There is no extra command to run — any session told implement .task/task/<slug>.md reads the artifact and follows its ## Execution pointer into .task/CLAUDE.md → ## Executing a task, through to a commit.
• Invisible to your repo. .task/ is git-excluded, never shows in git status, and rm -rf .task leaves the repo exactly as before — the trust section below spells out precisely what it will and won't touch.
• And yes, the discussion survives /clear, compaction, and tomorrow's fresh session — table stakes, but worth saying. The artifact's path is the only handle; there's no active-task state to lose or heal.

Why you can trust this

It runs bash, edits files, and writes commits — so here is exactly what it will and won't touch:

• Nothing is committed until the implementing session does so, per ## Executing a task. Until then every change is just working-tree edits; back them out with plain git restore / git checkout. One opt-in exception: /task:roadmap-to-workflow (autopilot) commits each roadmap item as it lands — it still never pushes.
• Commits stage only task-related files, and never push. Nothing leaves your machine.
• No hidden orchestration. The capture skills spawn nothing. The plugin ships exactly one subagent — task:code-reviewer, the review pass, whose whole prompt is a readable Markdown file in this repo (agents/code-reviewer.md) — and /task:roadmap-to-workflow runs a static Workflow script shipped with the plugin (skills/_lib/roadmap-driver.js), inspectable at any time — the skill only passes it the roadmap's unchecked items, the already-ticked numbers and your chosen scope; the driver derives the run order itself.
• The pipeline leaves no trace in the repo. .task/ is excluded via .git/info/exclude (not .gitignore), so it never shows up in git status; delete it with rm -rf .task and the repo is exactly as before.

Requirements

• Claude Code — this ships as a Claude Code plugin.
• Nothing else. Every skill except grill opens on its entry state — the resolved .task/ root, whether the project is set up, the roadmaps/tasks/specs that exist — gathered by the plugin's own preflight.sh and substituted into the skill before Claude reads it, so a capture starts without a single tool round-trip. (grill reads nothing under .task/ and runs no bash at all.) Those skills pre-approve the plugin's own helpers via allowed-tools, one rule per script they actually invoke — never a blanket grant over a directory.
• The review pass is the plugin's own agent (task:code-reviewer), so no platform slash command has to be available — it just needs the plugin enabled. Verification uses whatever build/test command your project declares in .task/CLAUDE.md → Build and Tests; when there is none, the reviewer says so instead of implying a green run.

Installation

The pipeline ships as a Claude Code plugin (task) inside the task-pipeline marketplace. The recommended path is through the marketplace:

/plugin marketplace add https://github.com/SpaiR/task-pipeline.git
/plugin install task@task-pipeline

From then on, updates are a single command: /plugin marketplace update task-pipeline.

After installation, Claude Code gains the commands /task:grill, /task:to-task, /task:to-plan, /task:to-roadmap, /task:to-spec, /task:roadmap-to-workflow, plus the task:code-reviewer agent the execution step spawns for you (you never invoke it by hand). There is no hook — enforcement is by convention, not a gate.

In a new project you don't have to run setup by hand first: the first /task:to-task, /task:to-plan, /task:to-roadmap, or /task:to-spec in an unconfigured project detects language and test policy, writes .task/CLAUDE.md, reports what it wrote, and continues with the requested capture. /task:grill needs no setup at all — it writes nothing and can run at the discussion stage before any capture exists. /task:roadmap-to-workflow presupposes an existing roadmap, so a fresh-project first-use of it hard-stops with a redirect to run a capture skill first.

/plugin marketplace add /path/to/task-pipeline
/plugin install task@task-pipeline

Command reference

Next-step footer: every capture skill ends its output with a copy-pasteable → Next: ... line naming the artifact path explicitly, e.g. implement .task/task/<slug>.md — the path is the handle, so there's nothing else to remember.

validate is an internal, optional self-check — not a slash command, not a gate. For a manual check: bash "${CLAUDE_PLUGIN_ROOT}/skills/validate/validate.sh" all.

One file per task; a roadmap is a backlog of items

Each capture produces exactly one .task/task/<slug>.md, where <slug> is both the filename and the identity — no task-id, no umbrella folder. A closed task is just a file that stays in .task/task/ (or you delete it); git history is the record, there is no archive. A roadmap (.task/roadmap/<slug>.md) groups several such items into one initiative; to-task/to-plan can open the next unchecked item directly, or roadmap-to-workflow fans the whole backlog out at once. A spec (.task/spec/<slug>.md) is a standalone file of load-bearing technical decisions that tasks and roadmaps point at with a Spec: header.