Changelog

All notable changes to this project are documented here. Format — Keep a Changelog, versioning — SemVer.

This file is maintained in English — see CONTRIBUTING.md.

[6.0.0] — 2026-10-06

Roadmap items carry a **Size:** hint instead of **Model:**, and roadmap-to-workflow picks each stage's model and effort from it, so a hint no longer names a model that ages with every generation. Breaking — see Migration below.

Changed (breaking)

• **Size:** replaces **Model:** on roadmap items. An item takes **Size:** S | M | L, M when absent, and one table in the driver maps the size to a model and effort for the plan and implement stages: opus plans every item, at medium effort for S and high otherwise; sonnet implements S and M at medium effort, opus implements L at medium. The reviewer keeps its own model and effort, so an item's size never lowers its review. **Model:** is no longer read: a leftover line is ordinary body text and the item runs as M. to-roadmap writes **Size:** only with a real basis, and its reference page says what S, M and L mean.

Changed

• The implement stage always runs at an explicit effort. It used to get none and inherited the session's, so a session on low effort implemented every item on low.

Migration

• Replace **Model:** with **Size:** in in-flight roadmaps. An old haiku item is roughly S, an old sonnet or opus item roughly L; drop the line for the default M. Skipping the edit breaks nothing — every item just runs as M.
• A roadmap-to-workflow run interrupted on 5.0.0 cannot be resumed on 6.0.0: the driver's items now take a size field instead of model. Rerun /task:roadmap-to-workflow <slug> instead; items the review already ticked are skipped.

[5.0.0] — 2026-10-03

Captured artifacts now read cleanly in a Markdown preview. A roadmap item's checkbox moves out of its heading onto a status line under it, the Ready description trades quoted headings for bold lines, and fields that used to merge into one paragraph each get their own. The parsers read only the new roadmap grammar, so a roadmap captured before this release needs a one-time conversion. Breaking — see Migration below.

Changed (breaking)

• The roadmap item grammar. An item is now a ### N. <title> heading whose first non-blank line is a - [ ] Done status line, which a preview renders as a real checkbox; the status keeps the five states [ ], [x], [~], [>] and [-]. Inside the **Ready description:** quote the sub-headings are bold lines — > **Context**, > **Goal**, > **Outcomes**, > **Acceptance criteria** — and the spec citation is > **Spec references:**. validate.sh, roadmap-to-workflow and the reviewer's tick read only this form. An item heading that still carries its checkbox (### - [ ] 3. Title) is reported by validate.sh as an error naming that heading, and roadmap-to-workflow stops on such a roadmap before running anything.

Changed

• Task files, plans and specs render cleanly too. Task headers, plan steps, spec sections and roadmap item fields each sit in a paragraph of their own, so the task header no longer turns into a setext heading over ---, and Touches is a list. The templates the models copy changed with the format, since they were where the merged layout came from. Existing task files and specs need no migration: the old layout still reads.
• Capture digests print as flat Markdown lists. A spec or roadmap pin no longer shows as an empty dash over a lettered list, and the lines after a list (Left for…, validate:, architecture:) no longer fold into its last item.
• preflight.sh prints TASKS: and SPECS: for captures only. roadmap-to-workflow never read them, and they grow with every task ever written.

Fixed

• A roadmap item whose heading drifted out of the grammar vanished silently. An item under #### N. or ## N. validated clean while every parser dropped it from the run; validate.sh now names a - [ ] Done status line that no item heading owns.
• Non-UTF-8 bytes still broke two parsers on macOS. A Latin-1 byte in a Makefile or package.json read as COMMANDS: none, so first-run setup wrote None declared. into Build and Tests; one in another roadmap item's title made the reviewer's checkbox flip fail and turned an OK review into a FAIL. Both now parse byte-wise.
• The driver misread a failed checkbox flip — it keyed on the words "no unique" anywhere in the review's free-text summary; it now matches the whole MARK-FAIL #N line.
• roadmap-to-workflow had no defined output for unborn and interrupted runs. In a repository with no commit yet the Commits: range now comes from git log HEAD; a Workflow call that errors or is interrupted prints the tool's error, the Commits: range and a resume-or-rerun footer; and the 0/0 footer is pasteable, with no backslashes inside its code span.
• to-task took the slug from the chat instead of the title. It now settles the title first, so the filename comes from it as the slug rule requires. With no chat and no arguments it goes straight to picking a roadmap item instead of offering a chip that could only stop, and a mistyped or roadmap-less slug#N stops instead of capturing an empty draft.
• write-task.sh input — a blank --plan, or a directory passed as a body, is a usage error (exit 2); a blank --tests drops the section. Bodies no longer go through a whole-body pattern substitution, which was quadratic on macOS's bash 3.2.
• resolve-ws.sh keeps an inherited AI_DIR only when it holds a CLAUDE.md, and resolves an absolute root on git older than 2.31, which echoes --path-format back instead of honoring it.
• The reviewer defines its diff base when the task's commit is the repository's root commit, and names an unwritable roadmap directory as a MARK-FAIL cause. It and the planner follow a **Source:** pointer in .task/CLAUDE.md to the file it names, rather than treating the section as empty.
• Docs realigned with what ships — the contract drops notes about earlier versions and features that are long gone, states each repeated fact once, and corrects three statements that had drifted from the code; the website's landing card no longer says "git-excluded", a mechanism the pipeline stopped using.

Migration

• Convert each in-flight roadmap once. validate.sh roadmap <slug> names every item heading still in the old form. In each item, move the checkbox out of the heading onto a status line under it, keeping its state: ### - [x] 3. Title becomes ### 3. Title, a blank line, then - [x] Done. Inside the Ready description quote, turn each > ### Context-style heading into a bold line, > **Context**, in a paragraph of its own; turn a ### Spec references → … heading into a **Spec references:** … line, quoted if the heading was. Then rerun validate.sh until it is clean. Every item keeps its number, title and state. .task/ is not under version control, so copy the file aside first if you want something to diff against.
• A fully shipped roadmap you will not run again can stay as it is; only validate.sh all will keep reporting it.
• Task files and specs need nothing.

[4.0.0] — 2026-09-29

Two capture skills fold into the two that remain: a task is always captured with its plan, and a roadmap always with its architecture. Five skills instead of seven, and the promote / revise / enrich branches that served two capture depths are gone — in write-task.sh too, which now only writes whole files, so every task file carries a ## Plan. Breaking — see Migration below.

Removed (breaking)

• write-task.sh --promote / --revise / --fresh. With a Description-only capture gone, nothing adds a Plan to an existing file or replaces one in place, and a single mode needs no flag: all three are now unknown arguments (exit 2). --plan is required; a driver rerun regenerates an unchecked item's own task file from the roadmap with --force, earned by the header match on that file.
• /task:to-plan. A Description-only capture turned out not to earn its file: a task too vague to plan is quicker done in chat, and every task worth an artifact was being deepened into a plan anyway. to-task now does what to-plan did.
• /task:to-architecture. The architecture section is what every planner follows, too useful to leave as an optional second skill that could be skipped. to-roadmap now writes it with every roadmap.
• The preflight kinds plan and architecture. preflight.sh now rejects them as a usage error.

Changed (breaking)

• to-task always writes Description + Plan (Goal/Touches/Logic steps), plus ## Tests when the testing policy calls for it — the former to-plan pipeline, through the same plan-driver.md § Core the driver's plan agent follows. It is a fresh capture only: it no longer targets an existing task file to add or replace its Plan. An existing slug is surfaced first with a chip (pick another slug, or overwrite); a roadmap item's own earlier file is offered for regeneration from the item.
• ## Plan is required in every task file. validate.sh now reports a task without one as an ERROR, as it already did for a Plan with no ### Step N: block. Every producer writes one, so the only files affected are ones captured before this release.
• The reviewer fails an uncommitted roadmap item. When the implementation never got committed (a pre-commit hook rejected it, say), task:code-reviewer used to pass and tick the item while its work sat in the tree, to be swept into the next item's commit. It is now a FAIL, nothing is ticked, and roadmap-to-workflow's footer says to commit, tick by hand, and rerun. A task whose HEAD is plainly another task's, with none of its own change in the tree, is a FAIL too: there is nothing to review.
• A bare slug resolves under .task/ only. validate.sh <kind> <slug> and roadmap-items.sh no longer try the argument as a file in the working directory first, where a stray file named like the slug shadowed the artifact. An argument holding a / is still a path. roadmap-to-workflow accepts a positional path only when it names the roadmap under .task/roadmap/.
• to-roadmap always writes the roadmap together with its ## Architecture. The decomposition comes first and stays behavioral; then the code is read at module level over the fixed items, the architecture is harvested from the discussion or settled in rounds, and the whole file lands in one write, with technical ordering already folded into the items' Dependencies. It is a fresh capture only: there is no enrich or revise mode for an existing roadmap.
• grill routes to three skills — to-spec, then to-roadmap, then to-task, first match wins. The "one task, approach still open" route is gone: an open approach is a fork the grill should ask before it ends.
• to-spec redirects local outcomes to to-task, and an initiative's pure technical shape to to-roadmap.
• The eval cases follow the skills — to-task-from-chat gains the plan graders and the runner-format fixes, and the architecture case becomes to-roadmap-fresh.

Fixed

• Non-UTF-8 bytes broke every parser on macOS — only one awk pass in validate.sh ran under LC_ALL=C. A Latin-1 byte still made validate.sh report a missing Plan or Tests section and a bad title, and silenced dangling-Spec: WARNs; it truncated roadmap-items.sh's item list, and emptied preflight.sh's counts so the roadmap read as finished. Every helper now parses byte-wise, and a roadmap that cannot be read reports unchecked=unreadable instead of none.
• write-task.sh hung on a trailing value flag — --plan with nothing after it made the argument loop spin forever. It is a usage error now.
• write-task.sh publishing — two parallel writers on one new slug both printed WROTE: and the second silently replaced the first; a write without --force now fails atomically when the file exists. A directory at the target path no longer reports success, and task files keep the mode a plain redirect gives them instead of turning owner-only.
• The driver implemented a wave before checking all its plans — a malformed plan digest on a later item stopped the run only after its wave-mates had landed, and two items planned onto one slug shared one task file. Both now stop the wave before any implement.
• The reviewer's range when no commit matched Touches — it put an unrelated HEAD into the diff under review, read any dirty file as an uncommitted implementation, and skipped untracked files. It now counts only the task's own change, and reviews a HEAD that merely missed Touches whole.
• roadmap-to-workflow footers — a tick failure and an uncommitted implementation got the generic "re-plan it" footer, which re-implements committed work; the generic footer itself suggested re-planning with to-task, a plan the rerun overwrites. resumeFromRunId was recommended after any stop, though it replays the cached failing stage.
• Capture edge cases — to-task and the driver's plan agent keyed their fatal case on validate.sh's exit 2, which write-task.sh never passes on; they now read the ERROR precondition line. to-task's exit 4 had no defined end, and a slug disambiguated from a namesake was never rechecked, so a driver rerun failed on its own earlier file every time. Roadmap and spec slugs now stay English under a non-English Language policy.

Migration

• Replace /task:to-plan with /task:to-task, and /task:to-architecture with /task:to-roadmap.
• Description-only task files no longer validate. validate.sh reports missing '## Plan' section heading for each; roadmap-to-workflow's setup gate lists the error but blocks only on the roadmap it runs. Re-capture such a task with /task:to-task (it asks before overwriting), or add a ## Plan with at least one ### Step N: block by hand. Existing roadmaps without ## Architecture stay valid; their planners have no architecture to follow, as before.
• Edit an unchecked roadmap item, not its task file. A roadmap-to-workflow rerun regenerates an unchecked item's task file from the roadmap, so hand edits to that file are lost.
• Pass a path with a /. A script that called validate.sh task notes.md for a file in the working directory now gets a lookup under .task/task/; write ./notes.md.
• To add or change the architecture of an existing roadmap, edit its ## Architecture section in chat. To re-plan an existing task, run /task:to-task again: it asks before overwriting.
• A .task/CLAUDE.md written by an earlier version may name to-plan in its Testing Policy line. The file is yours and is never rewritten; edit the name by hand if it bothers you — nothing parses it.

[3.7.0] — 2026-09-23

A roadmap gains a technical layer: to-architecture writes an initiative's components, interfaces between items and per-item sketches into the roadmap itself, and the planners follow it. .task/ now hides itself with its own .gitignore instead of a line in .git/info/exclude. Non-breaking: the new section is optional, a configured project gets its .task/.gitignore from preflight on the next run, and old info/exclude lines are left alone.

Added

• /task:to-architecture — the technical layer for a roadmap. It writes an ## Architecture section inside .task/roadmap/<slug>.md: components, the interfaces between items, a module-level sketch per item, and the technical ordering. Until now that shape had no home: items stay behavioral and specs pin individual decisions, so it leaked into specs or got lost. Fresh mode captures the roadmap first through the shared capture flow; enrich and revise work on an existing one, like to-plan does on a task. The ordering is mirrored into unchecked items' Dependencies, and missing Spec: headers are wired, because the driver's waves and the plan agents read only those. It stops on a fully checked roadmap, where no planner would read the section.
• Planners follow the roadmap architecture — plan-driver.md § Core step 1 reads the source roadmap's ## Architecture, so interactive to-plan and the driver's plan agents share one rule. It is the intended shape, not a fixed anchor: a plan step may depart from it when the code disagrees, and says why in its Goal. The to-plan digest gains an architecture line; to-task keeps its Description behavioral.
• validate.sh checks the architecture section — a duplicated section, missing required sub-headings, a numbered sub-heading inside it, and #N references naming no item (a renumbering strands them silently). All of these are WARNs: no parser reads the section, and an ERROR would stop roadmap-to-workflow from launching over a stale sketch. The summary now also counts WARN lines emitted by the awk pass, which it used to drop.
• grill routes technical-shape initiatives to to-architecture — a new routing test sits between the spec and roadmap tests. The spec test is narrowed to lines naming a concrete artifact and a rejected alternative, or it would swallow every interface between items.
• to-spec applies a decision test — each section must name a concrete artifact and a rejected alternative, so a restated roadmap item no longer passes as a decision. Pure technical shape is routed to to-architecture, and anything the test drops is named in the digest instead of vanishing.
• An eval case for to-architecture covering fresh mode end to end. evals/README.md records that the older cases share three runner-format defects this one avoids, so a red result there is not read as a prompt regression.

Changed

• .task/ ignores itself — setup writes .task/.gitignore with the pattern *, covering the file itself, instead of adding a line to .git/info/exclude. The rule travels with the folder: rm -rf .task really leaves nothing behind, and a later git init still hides it. Setup no longer skips the step outside a git repository. The one cost: ripgrep applies the nested * to the folder's own files, so a search scoped to .task/ comes back empty — the website has a troubleshooting entry for it.
• preflight.sh restores a missing .task/.gitignore — the skills promised a lost marker would come back, but no code did it, since setup runs only on first use. Preflight is the one path every skill except grill takes on an existing root. It never rewrites an existing file and never writes before the root is confirmed.
• The roadmap capture flow has one owner, skills/_lib/roadmap-capture.md — to-roadmap Steps 1–5 point into its Core, so to-architecture's fresh mode captures a roadmap without a drifting copy. The flow is caller-aware: to-roadmap recommends the architecture follow-up, and the collision chip warns before an overwrite destroys an existing ## Architecture.
• The driver gates on an exact digest — the implement and review stages must end with OK #N <item-slug>; anything else is a hard stop. The old startsWith('FAIL') check read a drifted line such as **FAIL** #3 … or a closing code fence as a pass, which let the mark stage tick an item whose review had failed. The check is the pure digestPassed(), pinned by tests/driver-digest.test.sh.

Fixed

• A copied repository used the original's artifacts — after cp -R, the copy's task.root still named the original, which still held a .task/CLAUDE.md, so the copy read and wrote there and ignored its own .task/. resolve-ws.sh now accepts the anchor only when its git common dir is ours, or when it is exactly dirname(git-common-dir), which keeps a bare repo's container resolvable. Tests cover copies, unrelated anchors, linked and bare worktrees, --separate-git-dir, and a submodule anchored at its superproject.
• The driver's plan agent could fail on a rerun — with no TASKS: list, roadmap-item.md's ownership check could be skipped, so after a failed implement the agent called write-task.sh --fresh on the item's own file, hit exit 4 and failed instead of promoting or revising it. The check now keys on the file's existence.
• to-architecture broke an empty Dependencies line — appending to **Dependencies:** with no value wrote **Dependencies:** , 3, which validate.sh rejects. An empty value is now replaced, as validate.sh and roadmap-items.sh already treat it as no dependency.
• validate.sh passed item number 0 — a ### - [ ] 0. heading and a 0 in Dependencies: validated clean, yet the driver refused the launch with bad args. Both are now errors.
• validate.sh dropped architecture WARNs on macOS — in a UTF-8 locale macOS awk aborted on the → of an interface line. The awk checks now run under LC_ALL=C. An ## Architecture heading with trailing text now counts as the section, and an #N right after a multibyte arrow (#2→#9) is no longer missed.
• Every failure branch ends with a next-step footer — to-task and to-plan's write-failure branch and the driver's relayed bad args — … line had none.
• Wording that contradicted the invariants — collision warnings called .task/ "git-excluded", which names the forbidden info/exclude mechanism; to-architecture Step 2 promised dependencies and titles for every item, while roadmap-items.sh prints them for unchecked items only.
• Docs realigned with what ships — the README and website reference pages show each command's real argument-hint; the contract credits roadmap parsing to roadmap-items.sh and gives resolve-ws.sh a Helpers row; the website documents to-architecture and the self-ignoring .task/.gitignore, and corrects the worktree task.root advice; CONTRIBUTING.md lists roadmap-capture.md and .github/.

Removed

• The repo-local /self-improve meta-skill and its four lens agents — unused, and a duplicate of /self-audit's steps. /self-audit itself now derives its rosters from disk instead of hardcoded copies that had drifted into false findings. Neither ships with the plugin.

[3.6.0] — 2026-09-19

The deterministic half of every skill moves out of the prompts into bash helpers and the driver, the repo gains an executable test suite, and the autopilot driver is reached by its registered name — which is what makes it work anywhere but a dogfooding checkout. Non-breaking: no artifact-shape change, and existing .task/ directories keep working untouched.

Added

• skills/_lib/preflight.sh prints the capture entry state in one call — the resolved root, whether .task/CLAUDE.md exists, roadmaps with their progress and their unchecked item numbers, and the task / spec slugs, as a fixed parser-stable block injected into Step 0. It replaces the 2–4 bash round-trips each capture used to open with, and the listings that duplicated it: the roadmap picker's loop, the positional-slug resolve and the per-skill directory scans all read the block now. An absent config is reported as a line in the block rather than an exit code, so a skill branches on something it can already see. validate.sh all folds in under VALIDATE: for roadmap-to-workflow, the one caller that gates on the whole tree.
• skills/_lib/write-task.sh is the single task.md writer — the artifact template left three prompts for one script, so the header link forms, the separator, the section order and the stamped ## Execution pointer have exactly one owner. It also performs the in-place surgery the model used to do by hand: promote inserts the plan above the pointer, revise replaces the plan and leaves an untouched ## Tests byte-identical, and both repair a hand-edited target that lost its separator or pointer. Destructive cases are refused with distinct exit codes — an existing slug without --force, a target with no Description — so the caller's own collision chips stay in charge.
• skills/_lib/detect-project.sh seeds first-run setup with facts — setup's open-ended "analyze the project" becomes a printed block of what is actually there: manifests, the commands the project already declares, its commit-format doc, a documented TDD rule with its line. Prose language is reported as evidence (ASCII or not, plus a sample) and named by the model, which is the part a script should not decide.
• skills/_lib/roadmap-items.sh — the launcher's 45-line inline awk collector, lifted into a helper and covered by cases it could never have had inline. The terminator rules are kept verbatim, so it still agrees with validate.sh on what ends an item.
• A bash test suite — bash tests/run.sh — ten case files over root resolution, the roadmap tally and path resolver, validate.sh's 0/1/2 exit contract, preflight, the task writer, project detection, the item collector, the driver's wave sort and its three-way registration seam, and the skill injections. Dependency-free (bash, awk, git; node for the driver-wave case, which skips without it), one process per case file, run on ubuntu and macOS from CI.
• Plugin eval cases under evals/ — five cases covering what the bash suite cannot reach, since whether a skill fires at all, writes the artifact it promises and prints the interaction conventions is a property of the prompt and visible only in a real run. They are authored against the documented case format but unrun: claude plugin eval reports itself as early access and refuses. evals/README.md records that, and that to-roadmap has no case yet.
• argument-hint on every skill, mirroring its own Input: line and flag-free, so slash autocomplete shows the argument forms at the point of typing instead of leaving them buried in the body. The commands reference gained the argument column it was missing.

Changed

• The autopilot driver is invoked by its registered name, task:roadmap-driver — declared in the plugin manifest under "workflows" — instead of by scriptPath. The Workflow tool permission-checks a scriptPath against the invoking session's working directory, which a plugin is never inside, so autopilot died before its first agent in every real install; it survived dogfooding only because there the plugin root is the cwd. A name that does not resolve hard-stops rather than sliding into the by-hand path: a stale or unreloaded plugin is an install defect, not a slow day. tests/driver-registration.test.sh now covers the manifest / meta.name / Step 2 seam, which a rename on either side used to expose only at someone's next autopilot run.
• The driver computes the dependency waves itself — the topological sort moved out of the prompt into computeWaves(items, done, scope), and the args went from ready-made waves to items plus done plus scope. The skill reports what the roadmap says and passes the scope through, nothing more. A cycle or an out-of-scope dependency is caught before the first agent is spawned and returns one line naming the items, instead of a wave that runs work out of order.
• roadmap-to-workflow hard-stops when the Workflow tool is absent. The old "graceful fallback" had the skill loop the items itself, invoke /task:to-plan (disable-model-invocation, so silently skipped) and tick roadmap checkboxes by hand — a hand-rolled driver copy that broke the "orchestration stays with the platform" invariant. It now prints a by-hand recipe (to-plan in chat, implement in a fresh session, which ticks the box itself) and touches no file, the roadmap included.
• The five capture / launcher skills state each rule once, with the rationale moved into docs/contract.md: roughly 4,100 words out of the skill bodies, off every invocation's bill. Two pipelines gained a single owner in the process — skills/_lib/plan-driver.md § Core for the plan pipeline (to-plan Steps 3–7 are pointers into it, and the driver's plan agent follows it), and skills/_lib/roadmap-item.md for the from-roadmap block, read by to-task, to-plan and that same agent. What stayed in the skills is what needs a user: the testing-adjacent question and the pre-write collision chips.
• allowed-tools grants one rule per helper script a skill actually invokes, replacing a _lib/*.sh glob. A Bash rule matches raw command text, so the glob pre-approved any such script anywhere on disk, not just the plugin's own — the docs claimed otherwise and are corrected. The grant has to exist before the Step 0 injection that needs it, since a preprocessed command never prompts and one matching no pattern aborts the whole invocation.
• task:code-reviewer reviews every implementation commit, not only HEAD — it derives the diff base by walking back while each commit's files intersect the plan's Touches, bounded three ways (10 commits, a commit that plainly belongs to other work, and no walk at all without a Plan), and reports the range as its own mandatory output line. A plan landed one commit per step used to put every step but the last outside the review.
• The reviewer's phase 2 sub-agents run on sonnet — they read a file or subsystem and report claims, and that diff-wide fan-out is where most of the review's tokens go. Phase 3 stays on the reviewer's own model: proving or refuting a candidate is the judgement the pass exists for.

Fixed

• The declared workflow path must start with ./ — the manifest schema requires it, so "workflows": ["skills/_lib/roadmap-driver.js"] failed validation with workflows.0: Invalid input, and a rejected manifest does not degrade to a plugin without a driver: it refuses to load the plugin at all, the six skills and the reviewer agent with it. Nothing in that error points at a missing prefix, so CLAUDE.md and the contract now say it outright.
• A Step 0 fallback note aborted the skill before it started — the note reproduced the !-injection syntax in all five bash-calling skills, and the platform's scan is positional, so the sentence itself ran as a second injection whose failure killed the invocation. Quoting does not save it: the pass that blanks ordinary code spans exempts a span preceded by a backtick or a !, which is exactly what double-backticking the example produces. tests/skill-injections.test.sh holds each of the five to exactly one injection, with the right kind argument, and grill to none.
• detect-project.sh silently lost its language verdict — a here-string feeding a grep -q that exits at the first match gets its command-substitution subshell killed with signal 11 on bash 5.x, printing README_LANG: — <sample> with no verdict and not a word on stderr. Measured at 11–17 bad runs per 300 on 5.3.15; piping the sample instead gave 0 in 700, and macOS's own bash 3.2 never hit it. setup.md reads both language lines to pick the project's Language, and a blank verdict left it guessing from the sample.
• Three helpers reported a success that had not happened — detect-project.sh read a compact "scripts": { … } line as an empty block and harvested the next object's keys as script names, so setup could compose Build and Tests from a dependency name, in a file it writes once and never repairs; write-task.sh checked neither the mkdir nor the redirection nor the final mv, printing WROTE: and exiting 0 on an unwritable directory, where it now exits 5 with no success line; and promoting a plan into a hand-edited file that already carried ## Tests anchored on the pointer and landed the plan below the tests, against the section order the contract fixes.
• preflight.sh's open-item collector accepted a heading no other parser does — ### - [ ] 3.Title, with no space after the dot, yielding 0/0 unchecked=3 and offering the pickers an item that roadmap.sh, roadmap-items.sh, validate.sh and the driver all ignore.
• validate.sh compares duplicate item numbers numerically — keyed on the raw digit string, 1. and 01. validated clean while the driver's mark awk and validate.sh's own Dependencies check treat them as the same item and MARK-FAIL.
• The test harness leaked its fixtures — temp dirs were registered inside the command substitution callers capture the path with, so the cleanup trap always saw an empty array.
• Docs realigned with what ships — the reviewer commits on top and never folds its fixes into the implementation's commit; the repository structure lists the five new _lib helpers and both new top-level directories; the driver is passed items, done numbers and a scope rather than ready-made waves; the contract's pipeline diagram ends at the review stage like its two peers; tests and evals join the closed scope list; the website's guide and reference pages match the skills, with a first-run entry for a driver that does not resolve, quoting the error verbatim.

[3.5.2] — 2026-09-05

A patch release for the review pass's final step, which asked for a permission the harness's auto-accept mode does not grant.

Changed

• task:code-reviewer commits its fixes on top instead of amending — phase 6 ended on git commit --amend --no-edit, folding the review's fixes into the implementation's commit to keep history at one item = one commit. Auto-accept mode blocks the amend, so in practice the phase either stalled on a permission prompt or ended with the fixes silently left in the working tree — the one outcome the phase exists to prevent, since an unattended autopilot then ticked the roadmap item and moved on. The reviewer now stages only the files it changed and writes its own follow-up commit, fix(<scope>): address review findings per .task/CLAUDE.md → Commit Format, one body bullet per fix it actually applied. Two behaviours are deliberately unchanged: a review that fixes nothing commits nothing, and an implementation that was never committed still leaves the fixes in the working tree rather than sweeping someone else's work into the reviewer's message. Phase 1's amend: <sha> bookkeeping is renamed to implementation commit: <sha> and the report prints Implementation: and Review fixes: on separate lines.
• The reviewer may no longer rewrite any commit at all — the Forbidden list banned push, rebase, reset and "amending any commit other than HEAD"; it now bans git commit --amend outright. That is a stronger guarantee than the rule it replaces, and it is what the docs site's trust page now states in place of "one task stays one commit".
• The .task/CLAUDE.md template's ## Executing a task step 4 and ## Build and Tests gloss describe the follow-up commit. The file is written once and never rewritten, so a project set up before this release keeps the old wording and needs a one-line manual edit to match — nothing breaks if it doesn't; the agent's own contract governs.
• Docs realigned — README.md, CLAUDE.md, CONTRIBUTING.md, docs/contract.md, roadmap-to-workflow's SKILL.md, the plugin description, comments in roadmap-driver.js and resolve-ws.sh, and thirteen pages of the docs site all asserted the amend or the one-commit property.

[3.5.1] — 2026-09-01

A patch release for the roadmap autopilot's mark stage, which could stop a wave on an item it had just ticked successfully.

Fixed

• The auto-mark stage is idempotent and reports its own result — a roadmap-to-workflow run could stop after an item with auto-mark matched no unique '### - [ ] N.' heading even though the checkbox was flipped and the commit had landed. The flip printed nothing, so the mark agent, asked to branch on an exit code it could not see, re-ran the same command to observe it; the second pass found [x], matched nothing, and reported failure. The heading is now matched on the full declared 5-state class [ x~>-], so the hit count means "item N exists" rather than "item N is unchecked" — an already-ticked item becomes a no-op that reports OK, while a missing, renumbered or duplicated heading still stops the wave, which is the property worth stopping on. Both branches echo MARK-OK / MARK-FAIL and the digest is mapped off stdout, so success is never invisible and no agent has to infer it — this also covers an agent() retry after a transient API error, which would have failed identically with a perfectly obedient agent. The rewrite is anchored to ^### - \[ \], since with the widened match class the line may already read [x] and an unanchored substitution would rewrite a literal [ ] inside the item's own title. The driver's stop message now names the remaining failure cause and tells the operator to tick the box by hand and rerun, the item's work being committed by then.
• Docs realigned with the new semantics — CLAUDE.md, docs/contract.md, roadmap-to-workflow's SKILL.md, the validate.sh comment, and the autopilot, troubleshooting and reference pages on the docs site all asserted the old unchecked-only match.

[3.5.0] — 2026-08-27

Cross-artifact references become Markdown links, so a .task/ file is navigable in a viewer instead of dead-ending on a bare slug, and the per-invocation prompt cost of the capture skills and roadmap-to-workflow drops sharply. Non-breaking — every consumer still accepts the bare form, and existing artifacts keep validating.

Added

• Roadmap: / Spec: headers, ### Spec references citations and the ## Execution pointer are written as Markdown links — Roadmap: [<slug>](../roadmap/<slug>.md). The label carries the identity: every consumer rebuilds $AI_DIR/<kind>/<slug>.md from the label and never follows the href, which would resolve against the agent's cwd (the project root) rather than the artifact's own directory. The href exists for humans and plan-review tools. Producers emit the link form; consumers, validate.sh included, still accept a bare slug, and the unwrap tolerates backticks and trailing text around the link.
• validate.sh warns when a Spec: header's target disagrees with its label — nothing else catches a stale href, since every agent follows the label and works regardless.
• validate.sh flags a near-miss roadmap item heading ([X], a double space, ####, a missing - ). No consumer treats such a heading as an item, so the file used to validate clean while an item quietly dropped out of an autopilot run. **Dependencies:** is now checked against the same file too, so a hand-written 1 2 (whitespace-stripped to item 12) or a number with no matching item is caught at capture time instead of hard-stopping a run mid-flight — self-dependencies and CRLF included.

Changed

• A roadmap's Spec: headers moved under # <Title>, so line 1 of every artifact is its own H1. Files in the old shape still validate.
• ## Executing a task now names ## Tests — to-plan wrote the section and validate.sh enforced its shape, but no consumer had ever been told to act on it.
• First-run setup moved out of the capture skills into skills/_lib/setup.md, read only when .task/CLAUDE.md is actually absent. to-task had carried roughly 5KB of setup sub-steps plus the template on every invocation, for a procedure that runs once per project; to-plan / to-roadmap / to-spec now point at the same file instead of at "exactly as to-task Step 0 does", leaving all four gates near-identical. The template moved byte-identical — its headings are load-bearing for the reviewer's and to-plan's by-heading lookups.
• The capture skills' Step 0 no longer runs validate.sh all — the full scan was advisory by design (report, never block) while costing a bash run whose output grows with every artifact. The gate keeps only the .task/CLAUDE.md existence check; each capture still validates the artifact it just wrote and still reports the result in its digest. roadmap-to-workflow keeps its validate.sh all gate, whose held-roadmap-error logic depends on the sweep.
• roadmap-to-workflow ships a static driver — skills/_lib/roadmap-driver.js, invoked via scriptPath + args, instead of re-authoring a ~150-line Workflow script every run; resumeFromRunId now caches completed stages cleanly. Per-item plan agents read skills/_lib/plan-driver.md rather than the full to-plan SKILL.md, dropping roughly 25KB of interactive-only prose, and the planner scales with the item's **Model:** hint — a haiku item plans on sonnet at low effort instead of opus. The checkbox flip became the driver's own serial mark stage, since the Workflow sandbox cannot write files itself; the exactly-one-match rule still stops the wave.

Fixed

• Root resolution no longer claimed a neighbouring project's .task/ — the ancestor walk was unbounded, so a checkout with no .task/ of its own climbed out of the working tree and wrote every artifact into another project's flat namespace, silently: the setup gate found a CLAUDE.md there and skipped setup. The walk is now ceilinged at the highest directory that still belongs to this project — its top level, the main worktree root, or a submodule's superproject, whichever is highest and still an ancestor of $PWD. Sibling worktrees still reach the shared root through step 3.
• Three narrower resolution faults behind the same walk — the ceiling could not be the checkout's top level alone (that broke submodules, landing AI_DIR inside .git/modules, and any linked worktree whose pipeline root sits above it); step 3 trusted dirname(git-common-dir) blindly, which under --separate-git-dir names whatever directory holds the git dir, often a neighbouring project; and the walk is now logical with a $PWD fallback, so a project entered through a symlink finds its own .task/ and a deleted cwd no longer degrades to a relative root plus a getcwd error on stderr.
• A drifted heading donated its Dependencies and Model to the item above it in roadmap-to-workflow's collector, inventing a phantom dependency or the wrong model with no signal. The collector now resets on any heading, excluding the ### Spec references citation that legitimately sits inside an item, and terminates only on a drifted item-heading attempt — terminating on any # line ate an item's own Dependencies and Model when it carried a sub-heading or a fenced code comment.
• A slug collision could overwrite a Plan — to-task's from-roadmap write is now guarded: the same item rewrites in place, the same item carrying a Plan goes through the Step 2.1 chip, and an unrelated task disambiguates instead of being silently overwritten. to-plan's no-Description promote fork uses that same sanctioned overwrite guard rather than a free-text exchange.
• validate.sh anchors tightened — ### Step N: / ### Test N: require the colon the producers already emit; the --- separator is accepted only in the header block, so a thematic break in the body no longer masks a deleted separator; Spec: headers are scanned only in the header block, so a Spec-shaped line quoted in a body no longer emits a spurious dangling-reference WARN; and a legacy bare Spec: <slug> carrying a copied template annotation is no longer mangled into a garbage slug — the trailing-text tolerance had lived only in the Markdown-link branch, contradicting what the contract promised.
• roadmap-to-workflow's positional-slug branch hard-stopped on a valid slug — each bash call is a fresh shell, and that branch skips the picker block, the only other place sourcing roadmap.sh, so resolve_artifact_path was undefined. It sources the helper itself now.
• to-plan's promote fallbacks cover a missing ---, and the two roadmap-resolution stops carry the → Next: footer — a promoted hand-written file otherwise failed the skill's own post-write validate call. to-plan's Step 2b also numbered two consecutive items 3., which reads as two phrasings of one step rather than the ordered pair Step 7's write consumes.
• A zero-match checkbox flip reported OK — the baked mark command's || rm -f tmp swallowed awk's non-zero exit, so a run that ticked nothing exited 0 and the agent reported success on an unticked box, the exact silent miss the exactly-one-match rule exists to stop. The cleanup branch exits 1 now, and the flip is anchored with 0* so a hand-written ### - [ ] 07. heading — which validate.sh sanctions as numerically equal to 7 — still matches, while the \. anchor keeps 7 from matching item 70.
• Docs realigned with what ships — the reviewer's phase 0 not 1, the reviewer listed as a spec consumer, one term for the capture skills, no hooks commit scope for a file that never ships, and the site's stale version and artifact paths.

[3.4.0] — 2026-08-21

Project settings move from a bespoke config file to a nested CLAUDE.md the platform loads on its own, and grill stops counting questions. Contains a breaking change — see Migration.

Changed

• config.md is replaced by a nested .task/CLAUDE.md — the platform auto-loads a nested CLAUDE.md into any session that reads a file under .task/, so the executing session and task:code-reviewer pick up Language, Testing Policy, Build and Tests and Commit Format without being told to open a config file. Two limits are load-bearing and shape the rest of the change: the auto-load fires only for file-read tools (never for cat or sed), and a nested CLAUDE.md is not re-injected after /compact.
• The file is the user's, not the pipeline's — setup writes it once, without a confirmation chip, and never rewrites or section-repairs it. Only task.root and the git-exclude line are repaired on later runs, so hand edits survive every capture. To regenerate it, delete it and re-run any capture.
• The stamped ## Execution block collapsed to a one-line pointer at .task/CLAUDE.md → ## Executing a task. The execution instructions now exist in exactly one copy, so editing them reaches tasks captured earlier. The pointer stays stamped in every artifact regardless — it is what survives /compact and a cat-based read.
• grill scales depth to the decision — the "typical 3–7 questions" anchor is gone, replaced by a functional stopping rule. Forks are asked in descending blast-radius order so an early stop loses the least, a wrap-up-or-keep-going checkpoint hands the stop decision to the user rather than the model, and the pre-mortem is skippable when no answer to it would change the ledger (Step 2's no-manufactured-questions rule, applied to the finale).

Fixed

• The docs site build no longer fails on the changelog's own links — changelog.md inlines CHANGELOG.md verbatim, so every repo-relative link in it must be exempt from the dead-link check. The v3.3.0 entry added a README.md link the exemption list did not cover, and the Pages deploy had failed on it since. README now sits alongside the CONTRIBUTING / CLAUDE / contract / agents patterns.

Migration

.task/config/config.md is no longer recognised. Before the next capture:

git mv .task/config/config.md .task/CLAUDE.md 2>/dev/null || mv .task/config/config.md .task/CLAUDE.md
rmdir .task/config

Until you do, the setup gate reports the project as unconfigured and writes a fresh .task/CLAUDE.md, orphaning any hand-edited settings; where .task/ sits in a subdirectory, root resolution falls through to the parent and creates a second .task/ beside the real one. Existing task files keep working — re-run /task:to-plan on one to re-stamp its ## Execution pointer.

[3.3.0] — 2026-08-11

The pipeline stops borrowing the platform's review commands and ships its own review agent. Non-breaking — no artifact-shape changes; existing task files keep working, though re-running /task:to-plan on one re-stamps its ## Execution block with the new sequence.

Added

• task:code-reviewer — the pipeline's own review pass (agents/code-reviewer.md, the plugin's first and only agent). It runs in explicit phases with a mandatory output each: read the task file and its Touches / Spec: anchors → gather the committed diff → collect candidate defects (fanning out where the diff warrants it) → prove or refute each one independently → fix only what it confirmed, inside Touches plus regressions the same diff introduced outside them → run config.md → Build and Tests → git commit --amend the implementation's commit. An unproven candidate is dropped, never fixed; 0 findings is a declared state; and a report that doesn't enumerate what was checked per Touches file counts as a failed review, not a passed one. It never pushes, never touches a commit other than HEAD, and writes nothing under .task/.

Changed

• /verify and /code-review are no longer part of the pipeline — Claude Code 2.1.217 marked both disable-model-invocation, and that gate treats every subagent as "the user didn't type this". Worse, a command in that state isn't listed to the model at all, so nothing errored: roadmap-to-workflow's per-item agent and every plain implement .task/task/<slug>.md session silently skipped the review step and still reported OK. The pipeline's review gate had been quietly absent rather than loudly broken, and there is no settings escape hatch. Both execution paths now spawn task:code-reviewer instead — a plain session per the ## Execution block, and roadmap-to-workflow's driver as its own stage in the per-item serial loop.
• The stamped ## Execution block carries the new sequence — implement → commit per config.md → Commit Format → spawn task:code-reviewer on the diff → tick the roadmap checkbox once the review returns OK. Existing task files keep working; re-run /task:to-plan on one to re-stamp it (they only ever named commands that weren't running anyway). Verification is relocated, not dropped: it rides inside the reviewer via config.md → Build and Tests, which fails the item on a red run and reports an explicit "skipped" when no command is declared.
• Implement commits, the reviewer amends — the implement step commits as before and the reviewer folds its fixes into that same commit, so work is durable immediately and one item stays one commit. If the implementation was never committed, the reviewer leaves its fixes in the working tree rather than rewriting an unrelated commit.
• roadmap-to-workflow is now three agents per item — opus-plans / sonnet-implements / task:code-reviewer-reviews. The review runs inside the existing per-item serial loop (not as a pipeline() stage), so the shared working tree keeps exactly one writer; auto-mark still belongs to the driver, now after the review; a failed review stops the wave exactly as a failed implement does. The item's **Model:** hint no longer reaches the review — the reviewer pins its own model, so a haiku item can't get a haiku review.
• Requirements dropped a prerequisite — no platform slash command has to be available any more; the reviewer only needs the task plugin enabled in the session doing the work. Since the ## Execution block names the agent directly with no fallback, a disabled or missing plugin is now the failure mode to know about — documented on the site's troubleshooting page.
• Two declared invariants were rewritten rather than silently violated: "orchestration, verification, review, and commits are delegated to the platform" (CLAUDE.md) and "there is no agents/ directory in v3" (CONTRIBUTING.md). The commit-scope list gains agents. Skill count is unchanged at six — the reviewer is an agent, not a skill.

Fixed

Two full self-audit passes over the skills, the agent, and the bash layer. The findings below are the ones that could cost you work or lie to you about what happened.

• A stale task.root could overwrite a live config.md — the anchor is an absolute path in .git/config, so it survives a moved or copied repo and then names where the repo used to live. find_ai_dir trusted it on the variable alone (step 4 already demanded evidence), resolved to an AI_DIR with no config, reported the project unconfigured, and let intake setup regenerate config.md over the real one — losing hand-tuned Build and Tests, Language and tool priority silently. Such an anchor is now ignored and the ancestor walk takes over; the next capture rewrites it.
• Captures wrote to a cwd-relative .task/ — validate.sh resolves $AI_DIR independently, so a capture run from a subdirectory or a linked worktree wrote into a second .task/ the validator never looked at. All four capture skills now anchor writes on the root they resolve in Step 0 (to-roadmap and to-spec did not source resolve-ws.sh at all), using ${CLAUDE_PLUGIN_ROOT} — a bare skills/_lib/resolve-ws.sh path does not exist relative to a user project's cwd.
• roadmap-to-workflow reported success where it had guessed — an unresolved positional slug reached the item scan as an empty path and awk 'prog' "" reads stdin, so a typo came back as a fully completed roadmap; the plan digest was consumed with split(" ")[2], so any drift in that LLM-authored line launched the next agent against task/undefined.md after the wave's planning was already paid for; and the auto-mark awk never checked that it matched, so a drifted heading left the box unticked while the commit landed and the next run redid the work. Each now fails loudly. The wave sorter also read **Dependencies:** none as a dependency on a missing item and hard-stopped.
• The driver's own writes ran in the wrong shell — the auto-mark awk referenced "$ROADMAP" from inside the JS Workflow body, where no shell exists. ROADMAP, AI_DIR and the item paths are now baked literals. Collected Spec: paths were dropped instead of being passed to the plan agent, and the paths were stamped into Spec: headers the contract defines as bare slugs — a derived SPEC_SLUGS now feeds the header while the paths feed the read.
• to-plan's handoff footer broke the driver — Step 8 told every run to close with → Next: …, but the driver lifts the item slug out of the plan agent's last line, so it fed the implement stage .task/task/<a-word-from-the-footer>.md. Driver mode is now carved out of Step 8 and restated in the driver's own prompt.
• A proven build failure could not be fixed — phase 5 of task:code-reviewer said "go back to phase 4" on a red build while phase 3 banned fixing anything it had not CONFIRMED, and a failure surfaced by the test run was never a phase-3 candidate. A Build and Tests failure traced to this diff is now the one sanctioned entry point (the failing run is its own evidence), with the trace stated either way. Unattended, that ambiguity turned a one-line break into a FAIL that stopped a whole wave.
• to-task / to-plan branch and overwrite gaps — the overwrite chip offered a flat "Accept" without saying what the colliding file held, though the natural to-task → to-plan → to-task flow derives the same slug and .task/ is git-excluded, so a Plan lost that way is gone; it now reads the file's headings first and recommends deepening. to-plan's case 1 matched any bare token vacuously and swallowed the roadmap branch; promote mode had no fallback without a ## Execution anchor and could replace an unrelated same-slug task's Plan with no chip; and free-form $ARGUMENTS hit "nothing to capture yet".
• The pre-draft recap read as a confirmation gate — to-roadmap and to-spec opened Step 3 with "once the decision list is confirmed", directly against Step 2 and interaction convention (b). grill's four routing bullets were unordered and its first test was satisfied by every ledger; the tests are now ordered and the spec test narrowed to anchors more than one future task must honor.
• Hard-stops and footers — the roadmap-validation, complete-roadmap, too-small-for-a-roadmap and nothing-to-pin stops now carry the → Next: footer convention (a) requires, and both "too small" stops say plainly that nothing was written.
• validate.sh's precondition error carries its own fix — a missing config.md stated a raw absolute path and no remedy, though the README and reference page both send first-run operators to validate.sh all by hand. It now names the four capture skills that write the file, keeping the literal config.md not found substring three skills branch on.
• Commit Format's last resort — with no project doc and no usable git log convention, to-task left config.md pointing nowhere; it now names the bundled _lib/templates/conventional-commits.md the contract had always declared the fallback.

Docs

• Version-diff framing removed everywhere — docs/contract.md, README.md, CLAUDE.md, CONTRIBUTING.md, the website, the skill prompts and the bash headers described the pipeline as a diff against v2 ("Removed in v3", "no build/ship step to run", "the mechanism that used to be two separate skills"), naming entities a reader has never had. All restated in present tense; no step, template or hard-stop changed. CHANGELOG.md is left alone — it is the record of that history.
• Corrections in the docs of record — the producer/consumer table claimed config.md is consumed by "every skill" (grill reads nothing under .task/) and that every to-* skill stamps ## Execution (only to-task / to-plan do), and omitted validate.sh from every "Consumed by" cell; resolve-ws.sh's comments credited worktrees roadmap-to-workflow never spawns and documented step 4 without its evidence requirement; CONTRIBUTING.md's tree was missing skills/grill/; the site's "config.md not found" cause implied /task:grill can hit the gate, and its spec-kit row listed three capture skills where the rest of the page lists four. The § task.md format link pointed at a non-existent anchor.
• Local meta-skills refreshed — /self-audit and /self-improve still described a repo with five skills and no agents/ directory; the Docs-sync lens now compares against ls skills/ rather than a hardcoded roster, and covers CONTRIBUTING.md and website/ too.
• validate.sh's subcommand list has one owner — the file-header # Usage: block was byte-identical to the --help heredoc, which alone carries the <slug> note and the exit-code line.

[3.2.1] — 2026-07-23

Patch release. Non-breaking — no artifact-shape changes.

Fixed

• roadmap-to-workflow wave concurrency — the script template passed { isolation: "worktree" } to parallel(), which the Workflow tool silently ignores, so every wave actually ran all agents concurrently in one shared tree, and true per-item worktrees have no reconciliation step anyway. Waves now plan all items in parallel (each plan agent writes only its own task file, never the tree) then implement them strictly one at a time, the sole mutator of the shared tree — a plan FAIL stops before any implement, an implement FAIL stops as before. Each implement now sees its wave-mates' already-landed commits and /verify runs against the integrated state.

Docs

• VitePress documentation site — added a searchable guide/reference site under website/, deployed to GitHub Pages: getting-started and core-concepts pages, per-skill workflow guides (grill, single task, roadmaps, autopilot, specs), a comparison against similar tools (superpowers, OpenSpec, spec-kit, Task Master, Matt Pocock's skills), and a full command reference. docs/usage.md and docs/troubleshooting.md are now thin pointers to the site, which is the single owner of user-facing usage prose.

[3.2.0] — 2026-07-20

Replaces the confirm-before-write gate with write-then-digest. Non-breaking — no artifact-shape changes.

Changed

• Write-then-digest replaces confirm-before-write — convention (b)'s print-draft → Accept/Edit/Decline gate was the pipeline's most error-prone step (three prior patch releases only papered over it) and re-reviewed content the chat discussion had already settled. Every capture skill now writes its artifact immediately, runs validate.sh on the written file, then prints a structural digest (path, title, sections, captured decisions/pins, validate result) inviting edits against the file. grill drops its ledger confirmation and prints the ledger as the digest after the pre-mortem. Chips survive only where the question isn't distilled content: config Step 0 setup and the slug-collision overwrite guard. Synced across CLAUDE.md, docs/contract.md, and self-invariants-auditor.

Fixed

• to-roadmap / to-spec no longer hard-stop on unrelated artifact errors — Step 0 treated any non-zero validate.sh exit as "config malformed → stop", but exit 1 means one or more existing artifacts failed validation; validate.sh never inspects config.md content. A pre-existing broken, unrelated file could block a fresh capture. Both now hard-stop only on a missing config.md (exit 2), matching to-task and roadmap-to-workflow; exit-1 artifact errors surface but don't block.

[3.1.2] — 2026-07-19

Bugfix release. Non-breaking — no artifact-shape or layout changes.

Fixed

• Confirmation gate hardened further — v3.1.1's "print the draft as message text first" wording did not change model behavior: a post-release transcript showed the turn going straight from bash checks to AskUserQuestion with no text block, so the draft was never actually printed. Every confirmation site (grill, to-task, to-plan, to-roadmap, to-spec) now carries an explicit gate — never emit AskUserQuestion until the full draft sits printed above it in the same reply; prior chat discussion does not count. Mirrored in both docs of record (CLAUDE.md, docs/contract.md).

[3.1.1] — 2026-07-19

Bugfix release. Non-breaking — no artifact-shape or layout changes.

Fixed

• Confirmation prints the draft first — the model was routing all confirmation output through the AskUserQuestion call and skipping the draft, so users confirmed content they never saw. Convention (b) is hardened at both docs of record (CLAUDE.md, docs/contract.md) and at every capture-skill confirmation site (grill, to-task, to-plan, to-roadmap, to-spec) to mandate printing the full draft as visible message text first, then posing the question in the same reply; the question box and option preview never render the draft.

[3.1.0] — 2026-07-19

Adds a pre-capture interrogation skill and tightens the capture flow. Non-breaking — no artifact-shape or layout changes.

Added

• grill skill — a pre-capture interrogation that sits at the "discuss freely" stage: it stress-tests a plan or decision one question at a time, keeps a running decision-plus-rationale ledger, ends with a pre-mortem, and routes to the right capture skill (to-task / to-plan / to-roadmap / to-spec). It writes no artifacts and touches nothing under .task/, so it can run before any capture exists and needs no config.md. Brings the pipeline to 6 skills.

Changed

• Skills and docs compacted — skill prompts and docs were trimmed to cut runtime token cost without changing behavior. validate is now a bash-only utility (skills/validate/validate.sh); its SKILL.md is removed.
• roadmap.sh slimmed — dropped the resolve_roadmap_path wrapper and a dead guard.

Fixed

• roadmap-to-workflow auto-mark — checkbox ticking is pinned to an anchored awk match and its fallback path is corrected, so the driver marks the right roadmap item.
• Capture flow hardened — to-task / to-plan / to-roadmap / to-spec handle empty and edge-case inputs cleanly; decline and stop branches now end with the canonical → Next: footer and aligned resume cues.
• validate diagnostics — a task-subcommand miss now reports the paths it searched.

Docs

• Contract — documents the 5-state roadmap checkbox class in docs/contract.md.

[3.0.0] — 2026-07-18

Chat-first rewrite. The pipeline is no longer an orchestration engine with phases, locks, and a hook gate — it is a small set of capture skills. Discuss freely in chat, then fix the discussion into a fixed-format Markdown artifact under .task/ with one short skill; capture depth is the skill name, never a flag. There is no execution skill — every artifact carries a stamped ## Execution block that an ordinary session follows to implement, verify, review, and commit. This replaces the entire v1/v2 surface and is breaking with no automatic migration. See Migration.

Added

• Capture skills — to-task (captures ## Description), to-plan (adds ## Plan: Goal / Touches / Logic steps), to-roadmap (a multi-task initiative), and to-spec (a standalone load-bearing technical decision under .task/spec/<slug>.md, referenced by tasks/roadmaps via a Spec: header). Depth of capture is the skill, not a flag.
• roadmap-to-workflow launcher — authors and invokes a dynamic Workflow over a roadmap's unchecked items in dependency-ordered waves, opus-plans / sonnet-implements per item by default. The driver ticks each roadmap checkbox after its agent returns OK (never inside the per-item agent).
• Stamped ## Execution block — every artifact carries an English, parser-stable Execution block that a plain session told implement .task/task/<slug>.md follows: implement the plan, run /verify + /code-review, apply review fixes within Touches, commit per config.md → Commit Format, and tick the roadmap item when Roadmap: / Source item: are present.
• Single artifact contract — docs/contract.md documents the full artifact shapes, producer/consumer table, and bash-layer contract in one place.

Changed (breaking)

• Flat .task/ layout — .task/config/config.md, .task/task/<slug>.md, .task/roadmap/<slug>.md, .task/spec/<slug>.md. No <task-id>/ subfolders, no workspace/, no log/, no archive — git history is the record. The slug (kebab-case, derived from the title) is the identity; task-ids and [TASK-ID] brackets are gone.
• Bash layer shrunk — resolve-ws.sh is now a pure .task/-root finder (no workspace resolution, no pointer read/write/self-heal). Only validate.sh and roadmap.sh remain alongside it.
• Orchestration delegated to the platform — verification, review, and per-item fan-out use /verify, /code-review, and dynamic Workflows instead of hand-rolled skill logic.

Removed (breaking)

• Skills — bootstrap, design, build, ship, roadmap, and auto-roadmap are removed, along with all phase companion files and the nine audit/runner subagents.
• Bash machinery — the lock protocol (auto-locks.sh), phase detection (phase-detect.sh), fail-log (fail-log.sh), touches-gate (touches-gate.sh), derive-task-id.sh, preamble.sh, and the auto-roadmap helpers are all gone.
• Layout markers — the active-task pointer, TASK_ID_OVERRIDE, per-worktree pointer files, and the roadmap .spec.md sidecar are removed. Pipeline markers are exactly git config task.root plus the .task exclude entry.
• docs/spec/* — replaced by the single docs/contract.md.

Migration

• No automatic migration from a v1/v2 .task/ workspace — this is a clean cut. Start fresh: discuss in chat, then run to-task / to-plan / to-roadmap / to-spec.
• Replace /task:design + /task:build + /task:ship with: capture via to-task / to-plan, then tell a session implement .task/task/<slug>.md and let it follow the stamped ## Execution block.
• Replace /task:auto-roadmap with roadmap-to-workflow over a .task/roadmap/<slug>.md.
• Replace /task:bootstrap — the four capture skills auto-run setup inline in a fresh project.

[2.0.0] — 2026-07-13

Interactive-first release. The pipeline now carries a task through each phase with structured questions, so a single bare command replaces most flag fiddling; the advanced flags stay fully functional but move off the everyday surface into a documented "Escape hatches" registry. This release also removes several redundant flags/modes and reworks the multi-worktree .task/ model — both are breaking. See Migration.

Added

• Interactive structured-choice layer — discrete path forks are now asked as AskUserQuestion chips in interactive runs: design's fresh-start entry fork and --from item picker, build's implement→audit advance, /task:auto-roadmap's roadmap picker and item-scope question (all remaining / only next / pick range). Interactive-only — the autopilot runners still pass explicit flags.
• Design phase-advance loop — after each design phase the skill re-detects state and asks once before chaining (Description-ready → build the plan; plan-ready → invoke /task:build), so one /task:design invocation walks the whole design half instead of needing repeated calls.
• Bootstrap language + testing-policy detection — /task:bootstrap now detects the repo's language policy and testing-policy mode and presents both as a single accept/decline/edit proposal instead of asking cold.
• Roadmap decision harvest — /task:roadmap can harvest decisions already settled in the prior conversation into a confirmed Decision Inventory before drafting, converging with the cold-start path on one pre-draft decision list.
• Roadmap light self-check — after authoring, /task:roadmap runs a report-only three-lens self-check (Coverage / Decomposition / Clarity) over the saved file and offers --refine inline only when findings warrant escalation.

Changed

• Question-driven cycle; advanced flags hidden — --idea / --from / --auto / --next / --refine / --phase are removed from README signatures, skill description frontmatter, examples, and every user-facing next-step footer. The surviving flags remain functional and are documented once in docs/troubleshooting.md § "Escape hatches", each paired with its interactive equivalent; /task:auto-roadmap's own flags stay a documented power surface.
• Clean build proposes ship; ship commit composed from artifacts — a clean interactive build flows into ship's single accept/decline/edit confirmation, and the commit header+body are composed from summary.md (fallback task.md) rather than free-text authoring. The audit tail is quieted to a one-line ### Result summary (full detail stays in audit.md; blocking findings are always shown in full).
• Bootstrap auto-runs on first design/roadmap — the first /task:design or /task:roadmap in an unconfigured project auto-runs /task:bootstrap inline, then continues the original request (stops only if you decline).
• Roadmap Size computed, Class inferred — Size is derived from the ### Outcomes count and **Class:** is a best-effort inferred, user-overridable hint; a codified archive path replaces ad-hoc naming.
• Stale active-task pointer self-heals — a provably-stale pointer (empty / missing workspace subfolder) is cleared with a one-line notice instead of hard-stopping.
• Canonical next-step footer + one interaction grammar — every core command ends with a → Next: footer (or → Done.), and content confirmations use one accept/decline/edit grammar.
• Faster /task:auto-roadmap per item — per-item token load and interactive validate round-trips trimmed; per-item time cut via the model split and lighter audit.

Changed (breaking)

• Multi-worktree .task/ model reworked — the .task symlink and /task:bootstrap join-mode are removed. All worktrees of a repo now share one .task/ resolved via git config --local task.root (written by bootstrap; dirname(git-common-dir) fallback), and the per-worktree active-task pointer moved from the worktree-root .task-current into git's per-worktree dir (git rev-parse --git-path task-current). Bootstrapped repos migrate automatically on the next command.

Removed (breaking)

• /task:ship --full and the hand-supplied commit slug — /task:ship has one mode (full close); the slug is always auto-derived. Both removed forms now fail loud.
• /task:ship --next subtask-transition mode — removed. This also fixed a bug where --next wiped a subtask's Description without archiving task.md; every close now archives task.md.
• /task:build --auto — removed; the interactive implement→audit advance question replaces it (the audit ≤2-iteration bound is unaffected).
• /task:design --idea and the design idea phase — removed; brainstorm a task in chat, then run /task:design "<description>".
• --full chore-finalize recovery convention — collapsed to a bare /task:ship.
• validate.sh todo legacy intake name — removed; use validate.sh roadmap <path|slug>.

Migration

• Run bare /task:ship (default full close, slug auto-derived) instead of /task:ship --full or /task:ship <slug>.
• Clean up an aborted /task:auto-roadmap run with a bare /task:ship instead of /task:ship --full chore-finalize.
• Replace /task:build --auto with a normal /task:build and accept the implement→audit advance question when prompted.
• Replace /task:design --idea by discussing the task in chat first, then /task:design "<description>"; work a multi-item roadmap by re-running /task:design --from <roadmap> per item.
• Reach design's plan-refine via /task:design --phase refine (repair-level, documented in docs/troubleshooting.md).
• Use validate.sh roadmap <path|slug> in place of validate.sh todo.
• Multi-worktree setups: standalone per-worktree .task/ is no longer supported — all worktrees share one .task/ via git config task.root, migrated automatically on the next command. To point the pipeline at an existing .task/ yourself: git config --local task.root /abs/path/containing/dot-task.

[1.1.0] — 2026-07-11

Added

• Bootstrap onboarding primer — after writing config.md, /task:bootstrap now prints a fixed-template primer that teaches the mental model at first value: the four .task/ artifacts and what each holds, phase auto-detect on re-run, the umbrella/subtask model, and the exact next command. Static template (localizable per config.md → Language).

Changed

• /task:auto-roadmap collapses the per-item cycle into one item-runner subagent — now that nested subagents are supported, each item's design → implement → audit → ship runs inside a single disposable auto-roadmap-item-runner, returning only a compact report-card digest to the driver. Driver context stays flat, lifting the previous ~15/~25-item auto-compact ceiling on long runs. The per-stage model split, fail-stop, sentinel, and cross-worktree contracts are preserved; is_last is now computed via checkbox look-ahead, fixing a latent dangling-umbrella case when a trailing item was already done.
• Skill descriptions rewritten as trigger→result — the six user-invocable skill descriptions drop the internal [N·phase] prefix codes (which collided across skills) in favor of a when-to-use then what-it-does form, so the / menu reads as guidance rather than pipeline taxonomy.
• Design open names the plan-building next step — the quick-draft next-step hint now names the action and the artifact (review task.md, then run /task:design again to build plan.md) instead of the opaque "auto-enters blueprint", removing the most common stall before a first ship.
• README and troubleshooting reworked for new users — a copy-paste quickstart leads the README (the dense flag list is demoted to a "Command reference"), a new safety section states upfront what the pipeline touches in your code and git, and the troubleshooting page is rewritten around first-run symptoms keyed on the literal strings the tool prints.

[1.0.1] — 2026-07-10

Changed

• Tool-agnostic references — the authoring guidance and heuristic lists no longer privilege specific products or language stacks. The pipeline already resolved all tooling from config.md at runtime; now bootstrap's config-authoring guidance and the README use role-based phrasing, the roadmap per-task verification reminder and the commit fallback template defer to config.md, and touches-gate path extensions plus audit-context lockfile excludes broaden to a language-agnostic superset (a missing entry only skips a fast-path, never yields a wrong result).

Fixed

• Pipeline root discovery — .task is now located by a git-style upward walk (find_ai_dir in _lib/resolve-ws.sh) instead of being assumed at the current working directory. Skill bash helpers (validate.sh, phase-detect.sh, the context scripts, close.sh, auto-roadmap-context.sh) previously failed with config.md not found whenever the shell had drifted out of the project root; they now resolve .task from any subdirectory. Linked-worktree .task symlinks are preserved (so the local .task-current is still found), and a call from outside any project still fails cleanly with the same message.
• Roadmap sidecar enumeration — /task:auto-roadmap and /task:roadmap --refine no longer list <slug>.spec.md / <slug>.refine.md sidecars as spurious "[malformed]" or empty roadmaps when enumerating .task/roadmap/. Both enumerators now skip the sidecars, matching what validate.sh already carved out.

[1.0.0] — 2026-06-23

First public release. A linear task pipeline for Claude Code — design → build → ship — with explicit, file-backed checkpoints and an off-cycle roadmap track.

Added

• Pipeline skills — /task:bootstrap (one-time per-project config), /task:design, /task:build, /task:ship, plus the off-cycle /task:roadmap and the /task:auto-roadmap autopilot. Phase-decomposed orchestrators (design → open / idea / blueprint / refine; build → implement / audit) dispatch to companion phase files.
• Artifact contract — every stage reads and writes plain Markdown under .task/ (task.md, plan.md, audit.md, summary.md), reviewable without the agent and enforced by a PreToolUse validator hook.
• Read-only audit lenses — six auditor-class subagents (Reuse / Simplicity / Clarity for the build audit phase; Coverage / Decomposition / Clarity for /task:roadmap --refine) fan out in parallel; build audit runs a bounded, scope-gated auto-fix loop.
• Roadmap autopilot — /task:auto-roadmap drives a whole roadmap item by item in the interactive session, with a per-item model split (cheaper model for the implement stage via plan.md → Implement-Model:).

---

Full release history and downloads: GitHub releases.