fix(implement-feature): give each path a next step #196

Merged

claudiomaradonna merged 2 commits from fix/implement-feature-flow into main

2026-11-05 10:59:29 +01:00

motoko commented

2026-11-05 10:55:12 +01:00

Collaborator

Why

Walking the chart of docs/workflows/implement-feature.md against the
skills it draws showed five paths where an agent reaches a step with no
stated next one. When dependency-advisor advises against an upgrade,
the agent goes on by default. When the reshape that before-plan sends
to refactor-code ends in a pull request or a branch left behind, the
feature has no instruction for the wait. A task that needs a reshape,
found in write-plan or mid-execution with the branch already open,
has a return path only in one sentence of the extension. A handed-in
work file starts at "the phase after its last filled one", which can
skip the Brief's gate for a security surface or an unfinished design.
A trim's new audit on a written Brief surfaces only at
check-work-folder, sometimes not until verify-execution.

The chart also redrew the shared chain of how-it-works.md with less
detail than the skills, which is how it lost several of these steps.

Alternatives set aside: stacking the feature branch on the reshape's
branch instead of waiting, since five skills would have to learn about a
base other than main; a new route-back destination instead of a rule
in write-plan, since that changes a skill every workflow shares; and
leaving the audit gap to check-work-folder, since it surfaces too
late.

What changed

When the advisor recommends wait or skip for an upgrade, brainstorm
step 2 stops and the user chooses to go on, to change the work, or to
close it. The rule lives in that one step for both a request and a
handed-in work file.

While a reshape has not reached main, before-plan names it in Status's
Blocked on and stops. On resume, both run-change and execute-plan
send the work back to before-plan, which then rebases an open branch
onto main and proves the tests of the done tasks again. Rewriting a
branch a remote holds still needs the user to name it, as Git and
delivery requires, and a refusal goes to route-back as a dead end.

write-plan step 1 sends a task that needs a reshape back to the
workflow's before-plan. A handed-in work file starts at the first step
whose skill's Done condition it does not meet. It enters at brainstorm
step 4 when the Brief is written. It never starts before execute-plan
once the Work file gate has passed. design counts as done only once
its drafts are reviewed. A new trim audit on a written Brief sends the
work back to brainstorm step 3, and the Work file gate is passed
again.

The page now draws two charts that show only what implement-feature
adds: its opening steps and its before-plan extension. The shared
chain stays in how-it-works.md. brainstorm.md, write-plan.md,
execute-plan.md, and how-it-works.md show the new edges and the new
start rule.

How to verify

Read implement-feature's before-plan on a fresh checkout of the
branch, as an agent resuming a work whose Status says "Blocked on:
reshape PR #N, until it lands on main". Expect to go to the wait in
item 3, then to the rebase and reproof in item 4. On main the
extension has no wait, so the agent would send the reshape again or
go on to write-plan.
Read run-change's last paragraph as an agent handed a work file
whose Brief is written, whose gate has not passed, and which names a
security surface. Expect to enter at brainstorm step 4 and pass the
gate before before-plan. On main the file starts at design or
before-plan.

On the tip these pass: bash tests/verify-agent-config.sh (225),
bash tests/check-work-folder.sh (46), .agents/hooks/shellcheck.sh repo, prettier --check '**/*.md', scripts/verify-agent-config.sh,
and git diff --check main. The behavioral evals were not run, because
they are billed and left to the maintainer before merge.

Considerations

The change is prose only, and no test checks that an agent follows the
new paths, so the evals are the only measure. One low review finding is
set aside: the route-back node in the second chart reads "a failed
attempt", and the edge into it carries the dead-end label instead.

https://claude.ai/code/session_012CBsgjdkRDt2uVUmT7bj64

## Why Walking the chart of `docs/workflows/implement-feature.md` against the skills it draws showed five paths where an agent reaches a step with no stated next one. When `dependency-advisor` advises against an upgrade, the agent goes on by default. When the reshape that `before-plan` sends to `refactor-code` ends in a pull request or a branch left behind, the feature has no instruction for the wait. A task that needs a reshape, found in `write-plan` or mid-execution with the branch already open, has a return path only in one sentence of the extension. A handed-in work file starts at "the phase after its last filled one", which can skip the Brief's gate for a security surface or an unfinished `design`. A trim's new audit on a written Brief surfaces only at `check-work-folder`, sometimes not until `verify-execution`. The chart also redrew the shared chain of `how-it-works.md` with less detail than the skills, which is how it lost several of these steps. Alternatives set aside: stacking the feature branch on the reshape's branch instead of waiting, since five skills would have to learn about a base other than main; a new `route-back` destination instead of a rule in `write-plan`, since that changes a skill every workflow shares; and leaving the audit gap to `check-work-folder`, since it surfaces too late. ## What changed When the advisor recommends wait or skip for an upgrade, `brainstorm` step 2 stops and the user chooses to go on, to change the work, or to close it. The rule lives in that one step for both a request and a handed-in work file. While a reshape has not reached main, `before-plan` names it in Status's Blocked on and stops. On resume, both `run-change` and `execute-plan` send the work back to `before-plan`, which then rebases an open branch onto main and proves the tests of the done tasks again. Rewriting a branch a remote holds still needs the user to name it, as Git and delivery requires, and a refusal goes to `route-back` as a dead end. `write-plan` step 1 sends a task that needs a reshape back to the workflow's `before-plan`. A handed-in work file starts at the first step whose skill's Done condition it does not meet. It enters at `brainstorm` step 4 when the Brief is written. It never starts before `execute-plan` once the Work file gate has passed. `design` counts as done only once its drafts are reviewed. A new trim audit on a written Brief sends the work back to `brainstorm` step 3, and the Work file gate is passed again. The page now draws two charts that show only what `implement-feature` adds: its opening steps and its `before-plan` extension. The shared chain stays in `how-it-works.md`. `brainstorm.md`, `write-plan.md`, `execute-plan.md`, and `how-it-works.md` show the new edges and the new start rule. ## How to verify 1. Read `implement-feature`'s `before-plan` on a fresh checkout of the branch, as an agent resuming a work whose Status says "Blocked on: reshape PR #N, until it lands on main". Expect to go to the wait in item 3, then to the rebase and reproof in item 4. On main the extension has no wait, so the agent would send the reshape again or go on to `write-plan`. 2. Read `run-change`'s last paragraph as an agent handed a work file whose Brief is written, whose gate has not passed, and which names a security surface. Expect to enter at `brainstorm` step 4 and pass the gate before `before-plan`. On main the file starts at `design` or `before-plan`. On the tip these pass: `bash tests/verify-agent-config.sh` (225), `bash tests/check-work-folder.sh` (46), `.agents/hooks/shellcheck.sh repo`, `prettier --check '**/*.md'`, `scripts/verify-agent-config.sh`, and `git diff --check main`. The behavioral evals were not run, because they are billed and left to the maintainer before merge. ## Considerations The change is prose only, and no test checks that an agent follows the new paths, so the evals are the only measure. One low review finding is set aside: the `route-back` node in the second chart reads "a failed attempt", and the edge into it carries the dead-end label instead. https://claude.ai/code/session_012CBsgjdkRDt2uVUmT7bj64

motoko added 2 commits

2026-11-05 10:55:17 +01:00

fix(implement-feature): give each path a next step 1220415c34

Five paths through implement-feature left an agent without one: a
verdict against an upgrade, a reshape not yet on the main branch, a
task that needs a reshape, a handed-in work file whose phase is
unfinished, and a trim's new audit on a written Brief.

brainstorm step 2 now stops for the user on a wait or skip
recommendation. before-plan records the wait in Blocked on, then
rebases an open branch and proves the done tasks again, and
execute-plan step 1 sends a work so blocked back to it. write-plan
sends a reshape-first task to before-plan. run-change starts a
handed-in work file at the first step whose Done condition it misses,
with design done only once its drafts are reviewed. A trim's new audit
sends a written Brief back to brainstorm.

Claude-Session: https://claude.ai/code/session_012CBsgjdkRDt2uVUmT7bj64

docs(workflows): draw implement-feature's own steps

Maintenance / checks (pull_request) Successful in 4m7s

Details

Maintenance / checks (push) Successful in 3m51s

Details

58ba0618ee

The page redrew the shared chain with less detail than the skills and
lost steps on the way. It now draws two charts, the opening steps and
the before-plan extension, leaving the chain to how-it-works.md, and
brainstorm.md and how-it-works.md show the verdict stop and the start
of a handed-in work file.

Claude-Session: https://claude.ai/code/session_012CBsgjdkRDt2uVUmT7bj64