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 folds its fixes into that commit.

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 — the config confirmation only appears later, at 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 block: implement per the plan
#   → commits per config.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 amends the commit

That session follows the artifact's own ## Execution block: implement the plan, commit per config.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 config.md → Build and Tests, and amends the commit — so one task stays one commit.

The first capture in a fresh project also writes .task/config/config.md inline (detect language + test policy, one confirmation) — there's no separate setup command to run first. 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 build/ship step to run — any session told implement .task/task/<slug>.md reads the artifact and follows its own ## Execution block 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 ## Execution. 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 is a plain Workflow the skill itself authors, which you can inspect before it runs.
• 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. 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 config.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, presents both for one confirmation, writes .task/config/config.md, and continues with the requested capture. /task:grill needs no config 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.

Commands

Comparison with alternatives

Most spec-driven tools answer "the model codes before it understands" with volume — more templates, more artifacts, the same ceremony for a rename and a rewrite. task-pipeline answers it with interrogation and proportion instead: a grill step that argues with the plan before anything is written, and capture depth chosen per task (to-task / to-plan / to-roadmap / to-spec, never a flag).

Underneath, the plan contract is fixed and validator-checked (### Step N — Goal / Touches / Logic), you author it in chat and it serializes to disk — rails that keep a session on the plan you already worked out, not a generator that invents one from a prompt. Load-bearing decisions pin into attachable per-decision specs, roadmaps fan out into a plan per item with auto-ticked checkboxes, and the whole surface stays small: flat Markdown under .task/, no MCP server, no API keys, no task database, one reviewer agent, and Workflows delegated to the platform. It is explicitly not for a two-file, twenty-minute fix.

Full head-to-head tables against default Claude Code, superpowers, Matt Pocock's skills, OpenSpec, spec-kit, and Task Master live on the site: Comparison with alternatives.

Configuration & policy

All of this lives in .task/config/config.md, written inline on first use of a capture skill:

• Language — by default the Description is in your language, everything else (headers, the ## Execution block, commits) is in English, per "Commit Format".
• Test policy — Testing Policy → Mode: always / on-demand (default) / never. In on-demand, ## Tests is written only if the Description explicitly asks for it ("needs tests" / "with tests" / "cover with tests").
• Idempotency — config.md is regenerated in full whenever setup runs again. After an interruption, implementation picks up from .task/task/<slug>.md as it stands.

How it works

discuss freely in chat
  ↓
/task:grill              grill before you capture — interrogate the decision, no artifact
  ↓
/task:to-task            capture what and why — no plan
/task:to-plan             …  + a Plan (Goal/Touches/Logic steps)
/task:to-roadmap          … a whole multi-task initiative
/task:to-spec             … pin technical decisions (tasks/roadmaps cite via Spec:)
  ↓                                          ↓
implement it now,                /task:roadmap-to-workflow
in a fresh session:                fans unchecked items out to
"implement .task/task/<slug>.md"   a dynamic Workflow, one per item
  → work the plan → commit → task:code-reviewer reviews, fixes, amends

/task:grill is the optional pre-capture step: point it at a plan or decision and it interrogates one question at a time, keeps a decision-plus-rationale ledger, ends with a pre-mortem, and routes you to the right capture skill — writing nothing itself. Grill before you capture, so the artifact serializes a decision that has already been pressure-tested. It descends from Matt Pocock's grill-me — the interrogate-before-you-build idea — and adds a decision ledger, recommendations that are allowed to disagree with you, a closing pre-mortem, and the part grill-me leaves open: somewhere to put the answers.

Depth of capture is the skill you pick, not a flag: to-task for a quick "what and why", to-plan when you already know the approach, to-roadmap for a multi-task initiative. to-spec is orthogonal — it pins load-bearing technical decisions into .task/spec/<slug>.md, which tasks and roadmaps reference via a Spec: header and the implementing session honors as a fixed anchor. There is no execution skill — capture ends with a copy-pasteable path, and any session (the same one, a fresh one, or one spawned by roadmap-to-workflow) executes the artifact directly.

The pipeline is built on a small set of invariants; the full contract lives in docs/contract.md.

• Artifacts. .task/ is flat — one file per task under .task/task/<slug>.md, one file per initiative under .task/roadmap/<slug>.md, one file per spec under .task/spec/<slug>.md. No workspace subfolders, no log, no archive, no active-task pointer — the artifact's path is the only handle there is. Full producer/consumer table: docs/contract.md.
• No hook gate. There is no hooks/hooks.json — the plugin ships no hook at all. Enforcement is by convention: validate.sh is available as an optional self-check, never wired to a PreToolUse matcher.
• Parallel worktrees. All worktrees of a repo share one .task/ automatically — its location is recorded in git config task.root on first setup, so nested, sibling, and bare-repo worktrees resolve it with zero setup (no symlink, no join step). Run several parallel worktrees of a repo and they all read and write the one .task/.

Contributing

This section is for those editing the tool itself. Start with CONTRIBUTING.md — it carries the commit format, the list of allowed scopes, the release procedure, and the repository layout.

Each SKILL.md is a prompt contract that another Claude instance will read in someone else's project. The invariants that must not be broken — the task.md format, the flat .task/ layout, the pipeline staying invisible outside .task/ — are pinned in docs/contract.md; a compact checklist is in CLAUDE.md. If you change something, update docs/contract.md and this README in the same commit; CHANGELOG.md is edited only on explicit request.