Restructure the product task workflow around vertical subtasks - #3629
Merged
Conversation
Tasks that fit in a single subtask no longer get a spec: they are grilled, implemented, and opened as a PR in one session, with the reasoning in the PR description. The size vocabulary goes with them — a deferred subtask is marked by having only a brief.md, which is what "large" used to record. A subtask is now a vertical slice, bounded to one fresh context window and one commit; its leaves stay layer-shaped, one project skill each (ADR 0002). Review and commit move from the leaf to the subtask, so an unattended chain no longer spends a subagent per axis on every step. Acceptance criteria replace the [verify] tag — a (human) criterion is what pauses the chain — and Blocked by edges replace implicit ordering, which keeps subtask numbers as identity and lets a deferred subtask expand into appended siblings. Nesting and the sub-branch/sub-PR scheme are gone. to-spec is now a pure writer: Slack harvesting is dropped and outreach moves to grill-the-task, where the questions are born and where a spec-less task needs it too. The spec axis of review-changes is gated on a spec existing, and create-pr carries the why for the PRs that have no spec behind them. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
tom2drum
commented
Aug 11, 2026
tom2drum
left a comment
tom2drum
left a comment
Collaborator
Author
There was a problem hiding this comment.
| Reviewed | 618a794f994db5df6b9a7579e45724de2cc9400b → 9a9183a680d23a57c0342428f7c1d03f3d99215b |
| Round | 1 of 3 |
| Findings | 2 blocker · 4 major · 2 nit |
| By axis | Spec skipped (no product-task spec) · Standards 3 · Correctness 4 |
| Outcome | blocked |
Instruction-surface PR only — Spec axis not dispatched.
The main index checkbox is what `Blocked by:` edges and PR finalization read, so it now moves at commit time rather than in the spec-update step — checking it early let an unverified, uncommitted subtask release its dependents. Three gaps in the handoff paths: `grill-the-task` had no subtask-mode branch, so scoping a deferred subtask matched the single-subtask path and would implement instead of writing the sub-spec; its input front-loading was gated on subtask count rather than on whether a later session executes the work, which skipped every subtask-mode run; and `implement-task` had no route from a `[human]` leaf that ends its subtask into verification and commit, which the default UI split makes the common case. Also drops `ready` from the subtask template — nothing set it, and stored readiness is what the derived model replaced — and trims restatements of the subtask model from the ADR, the subtask template, and AGENTS.md, leaving the definition with `.agents/tasks/README.md` alone. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
tom2drum
commented
Aug 11, 2026
tom2drum
left a comment
tom2drum
left a comment
Collaborator
Author
There was a problem hiding this comment.
| Reviewed | 618a794f994db5df6b9a7579e45724de2cc9400b → 7f470d41f830aca47bb41818e9e2aca15ef18862 |
| Round | 2 of 3 |
| Findings | 0 blocker · 0 major · 0 nit |
| By axis | Spec skipped · Standards n/a (arbitration) · Correctness n/a (arbitration) |
| Outcome | clear |
Arbitration of Round 1: all 8 claimed fixes verified in 7f470d41f (subtask-mode handoff, index-at-commit, front-load gate, human-leaf → Step 5, ADR/template restatement, subtask ready dropped, AGENTS.md pointer-only, ADR Consequences trimmed). No regressions from the fix commit.
— Reviewed by Cursor Grok 4.5
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Refines the spec-driven product task workflow in
.agents/. Documentation only — no application code is touched.A task that fits in one subtask no longer gets a spec. It is grilled, implemented, and opened as a PR inside a single session, with the reasoning going into the PR description. A spec exists to hand work to a session that wasn't in the room; a task that never leaves the room doesn't need one. The
small / medium / largevocabulary goes with it — a deferred subtask is marked by having only abrief.md, which is exactly whatlargeused to record, and nothing mechanical ever read the label.A subtask is now a vertical slice, bounded to one fresh context window and one commit, while the leaves inside it stay layer-shaped — one project skill each. The two levels answer different questions: what an agent can execute without judgement (a leaf) versus what a human can judge (a subtask). Recorded as ADR 0002, since it deviates from the tracer-bullet norm and looks wrong without its context.
That regrouping is what let the rest fall out:
[verify]tag. Each subtask spec carries a checklist; a(human)criterion is what pauses an unattended chain. The list is the gate, so no separate tag can drift from it — and the review's spec axis finally has a concrete target.Blocked by:edges replace implicit ordering. Numbers become identity rather than sequence, which is what lets a deferred subtask expand into appended siblings with no renumbering.Skill-level changes:
to-specbecomes a pure writer. Slack harvesting is dropped — reading replies is something the developer does in-session — and outreach moves togrill-the-task, where the questions are born and where a spec-less task needs it too.grill-the-taskloses its size-classification step and gains a quiz loop over the breakdown (granularity, context-window fit, edges, prefactor-first), then forks: implement in-session, or hand off toto-spec.review-changesgates its spec axis on a spec existing — with none it runs two axes and says so, rather than inventing a standard to judge against.create-prnow always carries the why, sourced from the conversation, the issue, or the diff.Environment variables
None.
Minimum API version
None.
Breaking or incompatible changes
None for any deployment. Within the workflow, specs written under the old shape (
Sizeheader row,[verify]tags, leaf-level breakdowns) are left untouched — a finished spec is a frozen record of what was decided then, and only new tasks follow the new structure.Additional information
pnpm lint:doc-linksandpnpm lint:cspellboth pass. The newsubtask-template.mdneeds no symlink:.claude/skillsis a directory symlink, so it is picked up automatically.