fix: match the guide and agent rules to the skills #202

Merged

claudiomaradonna merged 2 commits from fix/workflow-drift into main 2026-11-06 13:03:33 +01:00

Conversation 0 Commits 2 Files changed 11 +19 -12

motoko commented 2026-11-06 12:59:58 +01:00

Collaborator

Copy link

Why

A review of docs/workflows/ against the skills, after #201, found five
places that say what the skills no longer do. Someone who wants to
upgrade the agent policy finds no foundry-upgrade in the guide's
index, which lost it when ac48f83 grouped the guide by area. The
security-reviewer descriptions still name verify-execution, which
stopped calling it in c390726, and the document-reviewer ones leave
out design, which has called it since 186d88f, so whoever picks a
subagent by its description sees the wrong callers. Two charts, the work
template's list of the skills that keep Status, and the guide's claim
that design settles a diagnosis's fix options disagree with their
skills too.

A test tying each description to its callers would keep that drift from
coming back, but it adds a check beyond this fix and can be a change of
its own.

What changed

The guide's index lists foundry-upgrade under Code, noting that it
follows the source's UPGRADING.md rather than the shared chain.

The three adapters of each reviewer name the skills that call it today:
run-reviews for security-reviewer, and run-reviews, design,
document-feature, and implement-feature for document-reviewer.

refactor-code's chart leaves a security flaw's code to the user's
decision, recorded without naming the flaw, as the skill does, and the
chain chart draws route-back's way to diagnose and back to the first
phase left undone.

The work template counts implement-feature's before-plan, which
writes Blocked on, among the skills that keep Status.

design step 2 lists a choice among the fix options of diagnosis.md
that the Brief leaves open, and the guide now says design settles that
choice rather than every option.

How to verify

1. Open docs/workflows/README.md as someone who wants to upgrade the
   agent policy: the Code group ends with a link to
   foundry-upgrade.md, while on main nothing in the index leads
   there.
2. Compare grep -rl security-reviewer .agents/skills and
   grep -rl document-reviewer .agents/skills with the description line
   of each reviewer's adapters in .claude/agents/, .codex/agents/,
   and .opencode/agents/: they name the same skills, apart from
   settle-findings, which only settles findings.
3. View docs/workflows/refactor-code.md and
   docs/workflows/how-it-works.md rendered here: the security-flaw
   node names the user's decision, and dotted arrows run from
   route-back to diagnose and from diagnose back to the
   first-phase question.

The checks of docs/MAINTENANCE.md pass on the tip. No test checks this
text, so none is added. Not tried: rendering the charts locally, since
no Mermaid renderer is installed, and the behavioral evals, which are
billed and left to the maintainer before the merge.

Considerations

verify-execution stays in the template's list of the skills that keep
Status, although none of its steps writes it: the list is where that
duty lives, and the phase keeps the current action up to date through
its review rounds, which a resumed session reads first.

## Why A review of `docs/workflows/` against the skills, after #201, found five places that say what the skills no longer do. Someone who wants to upgrade the agent policy finds no `foundry-upgrade` in the guide's index, which lost it when ac48f83 grouped the guide by area. The `security-reviewer` descriptions still name `verify-execution`, which stopped calling it in c390726, and the `document-reviewer` ones leave out `design`, which has called it since 186d88f, so whoever picks a subagent by its description sees the wrong callers. Two charts, the work template's list of the skills that keep Status, and the guide's claim that `design` settles a diagnosis's fix options disagree with their skills too. A test tying each description to its callers would keep that drift from coming back, but it adds a check beyond this fix and can be a change of its own. ## What changed The guide's index lists `foundry-upgrade` under Code, noting that it follows the source's `UPGRADING.md` rather than the shared chain. The three adapters of each reviewer name the skills that call it today: `run-reviews` for `security-reviewer`, and `run-reviews`, `design`, `document-feature`, and `implement-feature` for `document-reviewer`. `refactor-code`'s chart leaves a security flaw's code to the user's decision, recorded without naming the flaw, as the skill does, and the chain chart draws `route-back`'s way to `diagnose` and back to the first phase left undone. The work template counts `implement-feature`'s `before-plan`, which writes Blocked on, among the skills that keep Status. `design` step 2 lists a choice among the fix options of `diagnosis.md` that the Brief leaves open, and the guide now says `design` settles that choice rather than every option. ## How to verify 1. Open `docs/workflows/README.md` as someone who wants to upgrade the agent policy: the Code group ends with a link to `foundry-upgrade.md`, while on `main` nothing in the index leads there. 2. Compare `grep -rl security-reviewer .agents/skills` and `grep -rl document-reviewer .agents/skills` with the description line of each reviewer's adapters in `.claude/agents/`, `.codex/agents/`, and `.opencode/agents/`: they name the same skills, apart from `settle-findings`, which only settles findings. 3. View `docs/workflows/refactor-code.md` and `docs/workflows/how-it-works.md` rendered here: the security-flaw node names the user's decision, and dotted arrows run from `route-back` to `diagnose` and from `diagnose` back to the first-phase question. The checks of `docs/MAINTENANCE.md` pass on the tip. No test checks this text, so none is added. Not tried: rendering the charts locally, since no Mermaid renderer is installed, and the behavioral evals, which are billed and left to the maintainer before the merge. ## Considerations `verify-execution` stays in the template's list of the skills that keep Status, although none of its steps writes it: the list is where that duty lives, and the phase keeps the current action up to date through its review rounds, which a resumed session reads first.

motoko added 2 commits 2026-11-06 13:00:04 +01:00

fix(agents): align rules with what the skills do ... fd68f8dec3

The security-reviewer descriptions still named verify-execution as a
caller, though only run-reviews has called it since c390726, and the
document-reviewer ones left out design, which has it review a rule
change's drafts since 186d88f. The work template listed the skills
that keep Status without implement-feature's before-plan, which writes
Blocked on, and design's step 2 never named the diagnosis whose fix
options the guide has it settle.

docs(workflows): match the guide to the skills ... becb455f3f

The guide's index lost foundry-upgrade when ac48f83 grouped it by area,
refactor-code's chart left a security flaw's code as it is although
the skill leaves it to the user's decision, and the chain chart never
drew route-back's way back to diagnose. design now lists the fix
options the Brief leaves open, so the guide says it settles those
rather than every option of the diagnosis.

claudiomaradonna merged commit becb455f3f into main 2026-11-06 13:03:33 +01:00

claudiomaradonna deleted branch fix/workflow-drift 2026-11-06 13:03:38 +01:00

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

claudiomaradonna/agent-foundry!202

No description provided.