Troubleshooting

First-run problems, then the edge cases of a solo, hook-free, pointer-free pipeline where enforcement is convention, not a gate.

First run

/task: commands don't appear after installing

Symptom — typing /task: shows nothing; no /task:to-task, /task:to-plan, etc.

Cause — the task plugin isn't installed/enabled in this session, or the marketplace was never added.

Fix

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

Then reopen the / menu. If it was already installed, make sure it isn't disabled (/plugin).

The code-reviewer agent doesn't resolve

Symptom — the session implements and commits, then reports that the agent type task:code-reviewer doesn't exist (or silently stops after the commit, with no review section in its output).

Cause — the review pass is the plugin's own agent (agents/code-reviewer.md), and the ## Execution block names it directly, with no fallback. So it resolves only when the task plugin is installed and enabled in the session doing the work. The usual causes: the plugin is disabled, it was never installed in this project, the task file was written by a much older plugin version, or the agent was renamed in a local fork.

Fix — check /plugin and enable task; reinstall via the marketplace if it isn't listed. Then re-run implement .task/task/<slug>.md — the implementation is already committed, so the reviewer will simply review that commit and amend it.

If you'd rather not run it at all, nothing is gated: the commit stands as it is, and you can run your project's build and tests plus your own review by hand. What you must not do is assume the review happened — a missing reviewer means no defect was proven and no fix was applied.

Why there's no fallback

Claude Code's own /verify and /code-review are marked disable-model-invocation, which means a subagent — and a session that was merely told implement … rather than typing the command itself — cannot run them, and the failure is silent: an unlisted command is skipped, not refused, so the run would still report success. The pipeline names its own agent instead, so a missing reviewer fails loudly.

"CLAUDE.md not found"

Symptom — a skill stops with .task/CLAUDE.md not found.

Cause — /task:roadmap-to-workflow and validate require .task/CLAUDE.md, and it hasn't been written in this project yet. The four capture skills (to-task / to-plan / to-roadmap / to-spec) write it inline on first use instead of stopping, and /task:grill needs no setup at all. There is no separate setup command — setup is folded inline into those four capture skills.

Fix — run any of /task:to-task, /task:to-plan, /task:to-roadmap, or /task:to-spec. Each detects language and test policy, writes .task/CLAUDE.md, records git config task.root, reports what it wrote, and continues into the capture. /task:roadmap-to-workflow is not setup-capable by design — if you hit this there, run a capture skill first, then retry.

.task/ shows up in git status

Symptom — .task/ appears as untracked in git status.

Cause — the local git exclusion wasn't written (e.g. .task/ was created before setup ran, or setup ran outside a git repo).

Fix — run any capture skill again; the inline setup is idempotent and re-adds .task to .git/info/exclude. This uses .git/info/exclude, not .gitignore, on purpose — the pipeline stays invisible to teammates and never touches a tracked file.

validate.sh ends with "FAIL N error(s)"

Symptom — bash "${CLAUDE_PLUGIN_ROOT}/skills/validate/validate.sh" all ends with FAIL <N> error(s), preceded by ERROR <label>: <message> lines.

Cause — a task or roadmap file drifted from the expected format: a missing # <Title> first line, no --- separator, no ## Description, a ## Plan with zero ### Step N: blocks, a roadmap item missing its checkbox prefix or a required sub-heading, a roadmap item heading that nearly matches the required form ([X] uppercase, a double space around the checkbox, ####, or the checkbox deleted), a **Dependencies:** value that doesn't parse (use an em dash for none, or a comma-separated list of item numbers), one that cites a number with no matching item, one that lists its own item, or a file saved with CRLF line endings.

Fix — read each ERROR <label>: line (it names the file and the exact problem) and fix the artifact by hand — these are plain Markdown files. Re-check with validate.sh all. It's an optional self-check, not a gate — only genuine structural ERRORs are worth fixing before you hand the file to an implementing session; a WARN never blocks anything.

validate.sh warns "no such spec … (dangling reference)"

Symptom — a WARN names a Spec: header pointing at a .task/spec/<slug>.md that doesn't exist.

Cause — the header names a spec that was never written, was renamed, or was deleted. This is the pipeline's one cross-file check, and only ever a WARN.

Fix — capture the missing spec with /task:to-spec (using that slug), correct the slug in the header, or drop the header if the reference is stale. The check reads the slug from the header's link text, so Spec: [<slug>](../spec/<slug>.md) and a bare Spec: <slug> behave the same — a hand-edited header in either form is never flagged for its shape, only for a spec that genuinely isn't there.

validate.sh warns "link target … does not match the slug"

Symptom — a WARN says a Spec: header's target isn't ../spec/<slug>.md.

Cause — the link text and the link target disagree, which is what renaming a spec and updating only one half leaves behind.

Fix — make the target ../spec/<slug>.md for the slug in the link text. Worth doing even though nothing is broken for the agent: every consumer resolves the label, so the task still implements correctly and only a human clicking the link lands on the wrong file — which is the one thing the link form was added to prevent.

Working with roadmaps

A roadmap item's checkbox never gets ticked

Cause — the auto-mark step is conditional on the task file carrying both Roadmap: and Source item: #N header lines, above the ---. If the file was hand-created, those headers were edited out, or the item number doesn't match, the executing session has nothing to key the flip off of.

Fix — check the top of .task/task/<item-slug>.md for both header lines and a correct #N. Add them if missing (ASCII, above ---, Roadmap: [<slug>](../roadmap/<slug>.md)) and re-run, or just tick the box yourself — it's a plain - [ ] → - [x] edit.

A roadmap-to-workflow run stops on a failed item

Cause — by design: the driver is stop-on-FAIL. A later wave never starts if an earlier item didn't land cleanly, since a later item may depend on it.

Fix — read the failure digest, fix the item (edit .task/task/<item-slug>.md, or re-implement it by hand), tick its checkbox, then rerun /task:roadmap-to-workflow <slug>. Completed items stay checked, so the rerun only picks up the unchecked remainder.

One digest is worth reading closely: a stop from the mark stage means the item's work already landed and was committed, and only the checkbox is behind. The flip is idempotent, so this is never "the box was already ticked" — it means the roadmap has no unique ### - [ ] N. heading for that item, because it was renumbered, retitled, or duplicated. Tick it by hand and rerun; there is nothing to re-implement.

A worktree can't find .task/

Cause — worktrees resolve the shared .task/ through git config --local task.root (fallbacks: an upward walk, then dirname(git-common-dir)). The anchor can be missing (repo set up by an older version) or wrong.

A moved or copied repo is the common way it goes wrong: task.root is an absolute path stored in .git/config, so it travels with the directory and then points at where the repo used to live. The resolver only trusts the anchor when that path actually holds a .task/CLAUDE.md, so a stale one is ignored and the upward walk finds the real .task/ that moved with the repo — but the anchor stays stale until a capture skill rewrites it.

Fix — run any capture skill from the stuck worktree; its inline setup records task.root and every worktree then resolves the same .task/. To point it at an existing .task/ yourself: git config --local task.root /abs/path/containing/dot-task (the directory that contains .task, not .task itself).

Finding your own state

There is no active-task pointer to lose or heal — the artifact's path is the only handle.

ls .task/task/
# every task file you've captured; a task stays here until you delete it

grep -L '^## Plan' .task/task/*.md
# task files with a Description but no Plan yet (to-task-only captures)

grep '^### - \[ \]' .task/roadmap/<slug>.md
# every item still unchecked in that roadmap

Once you've found the file, any session picks it up with implement .task/task/<slug>.md.

→ See also the maintainer-facing artifact contract in the repo.