fix(skills): close the agent-facing audit's gaps #204

Merged

claudiomaradonna merged 4 commits from fix/skill-gaps into main 2026-11-09 09:18:15 +01:00

Conversation 0 Commits 4 Files changed 10 +72 -42

motoko commented 2026-11-06 18:48:16 +01:00

Collaborator

Copy link

Why

A documentation audit of the documents agents act on, run on 2026-11-06
at becb455, found five places where a skill leaves its reader without a
next step or with two homes for one rule. An agent in forge with no
login, or whose pull request goes to another remote, read that the
action is unavailable and nothing more, although the skill's Done
promises the user the text to paste. An implementer of a parallel task
got a worktree that parallel.md had opened where open-worktree puts
one, without the preparation that skill gives, so its Runs could fail
for a missing set-up. An agent in refactor-code read that pins come
before the Brief while the work template has the first task commit
"the pins Constraints asks for", and was sent to the Decisions of a
work file that did not exist yet. The rule for a reproduction built
from text from outside, commit with the hooks off and run only in the
sandbox, stood in the same words in diagnose and check-issue, so a
change to one left the other behind. And open-worktree's description
left out check-issue, which opens a scratch worktree from it.

What changed

forge runs the check read in step 2 and the action in step 3, and its
step 4 ends with the hand-over when the action is unavailable, the
check read fails, or the forge refuses the action: the body file's text
to paste, with the title for a pull request or an issue, or, for a read
whose caller takes a paste, a request for what the forge holds, and for
any other read, a refusal reported to the caller. The refused action is
the one case beyond the audit, taken while the user was away and
recorded as the agent's proposal, D3, in the work file.

parallel.md step 2 opens each task worktree as open-worktree step 3
does, from the work branch's tip, and prepares it as its step 4 does,
skipping its upstream check and its version check.

The sandbox commit has one home, run-sandboxed step 1, and diagnose
and check-issue point to its steps 1 and 2. UPGRADING.md gains the
Sandbox commit migration, which carries an adopted repository's changes
to that commit there, and the Shared procedures migration no longer
keeps the commit in check-issue.

refactor-code keeps its pins first; its in-brainstorm extension has
Constraints list them as the guards, already committed, so the first
task commits none, and leaves the user's decision on a flaw's code open
in the Brief for design. The guide's forge and run-sandboxed entries
and the refactor-code chart's flaw node say what the skills now say.

How to verify

From a checkout of the branch, read .agents/skills/forge/SKILL.md as
an agent with no login: step 4 ends the skill with the text to paste;
on main no step does. Read .agents/skills/execute-plan/parallel.md
step 2: it names the preparation; on main it does not. Run
grep -rn core.hooksPath .agents/skills: one skill prints; on main
two. Read .agents/skills/refactor-code/SKILL.md beside the Tasks
comment of .agents/templates/work.md: the pins have one moment, and
no step names Decisions before the Brief. Read the description of
.agents/skills/open-worktree/SKILL.md beside
grep -rl open-worktree .agents/skills: the callers match.

Checks run on the tip: the six checks of docs/MAINTENANCE.md, all
passing, with 225 agent configuration tests and 46 work-folder tests;
the drafts were reviewed by document-reviewer before they were
applied, and the branch by change-reviewer, security-reviewer, and
document-reviewer. No regression test changes: no test reads the text
of the steps the change edits. Not run: the behavioral evals, which
docs/MAINTENANCE.md leaves to the maintainer before a merge that
changes skills, since each run is billed.

Considerations

The audit's other findings on these documents stay for a later change:
the route of a pre-existing security flaw in settle-findings, which
AGENTS.md and file-issue already bound, and nine low ones.

## Why A documentation audit of the documents agents act on, run on 2026-11-06 at becb455, found five places where a skill leaves its reader without a next step or with two homes for one rule. An agent in `forge` with no login, or whose pull request goes to another remote, read that the action is unavailable and nothing more, although the skill's Done promises the user the text to paste. An implementer of a parallel task got a worktree that `parallel.md` had opened where `open-worktree` puts one, without the preparation that skill gives, so its Runs could fail for a missing set-up. An agent in `refactor-code` read that pins come before the Brief while the work template has the first task commit "the pins Constraints asks for", and was sent to the Decisions of a work file that did not exist yet. The rule for a reproduction built from text from outside, commit with the hooks off and run only in the sandbox, stood in the same words in `diagnose` and `check-issue`, so a change to one left the other behind. And `open-worktree`'s description left out `check-issue`, which opens a scratch worktree from it. ## What changed `forge` runs the check read in step 2 and the action in step 3, and its step 4 ends with the hand-over when the action is unavailable, the check read fails, or the forge refuses the action: the body file's text to paste, with the title for a pull request or an issue, or, for a read whose caller takes a paste, a request for what the forge holds, and for any other read, a refusal reported to the caller. The refused action is the one case beyond the audit, taken while the user was away and recorded as the agent's proposal, D3, in the work file. `parallel.md` step 2 opens each task worktree as `open-worktree` step 3 does, from the work branch's tip, and prepares it as its step 4 does, skipping its upstream check and its version check. The sandbox commit has one home, `run-sandboxed` step 1, and `diagnose` and `check-issue` point to its steps 1 and 2. `UPGRADING.md` gains the Sandbox commit migration, which carries an adopted repository's changes to that commit there, and the Shared procedures migration no longer keeps the commit in `check-issue`. `refactor-code` keeps its pins first; its `in-brainstorm` extension has Constraints list them as the guards, already committed, so the first task commits none, and leaves the user's decision on a flaw's code open in the Brief for `design`. The guide's forge and run-sandboxed entries and the refactor-code chart's flaw node say what the skills now say. ## How to verify From a checkout of the branch, read `.agents/skills/forge/SKILL.md` as an agent with no login: step 4 ends the skill with the text to paste; on main no step does. Read `.agents/skills/execute-plan/parallel.md` step 2: it names the preparation; on main it does not. Run `grep -rn core.hooksPath .agents/skills`: one skill prints; on main two. Read `.agents/skills/refactor-code/SKILL.md` beside the Tasks comment of `.agents/templates/work.md`: the pins have one moment, and no step names Decisions before the Brief. Read the description of `.agents/skills/open-worktree/SKILL.md` beside `grep -rl open-worktree .agents/skills`: the callers match. Checks run on the tip: the six checks of `docs/MAINTENANCE.md`, all passing, with 225 agent configuration tests and 46 work-folder tests; the drafts were reviewed by `document-reviewer` before they were applied, and the branch by `change-reviewer`, `security-reviewer`, and `document-reviewer`. No regression test changes: no test reads the text of the steps the change edits. Not run: the behavioral evals, which `docs/MAINTENANCE.md` leaves to the maintainer before a merge that changes skills, since each run is billed. ## Considerations The audit's other findings on these documents stay for a later change: the route of a pre-existing security flaw in `settle-findings`, which `AGENTS.md` and `file-issue` already bound, and nine low ones.

motoko added 4 commits 2026-11-06 18:48:22 +01:00

fix(skills): add the steps and callers agents miss ... cca1b246a8

forge named no step for the action reach.md finds unavailable, a failed
check read, or a refused action, so an agent without a login stopped to
ask although the skill's Done promised the user the text to paste.
parallel.md had each task worktree opened where open-worktree puts one,
without the preparation its step 4 gives, so an implementer's Runs could
fail for a missing set-up. open-worktree's description left out
check-issue, which opens a scratch worktree from it.

refactor(skills): give the sandbox commit one home ... c5167ad493

diagnose step 2 and check-issue step 3 stated the commit of a
reproduction built from text from outside in the same words, so a change
to one left the other behind. The rule now lives in run-sandboxed step
1, the skill that owns code from outside, and both callers point to its
steps 1 and 2. The Sandbox commit migration carries an adopted
repository's changes to that commit there, and Shared procedures no
longer keeps it in check-issue.

fix(skills): settle refactor-code's pins and flaw ... b8096a632f

refactor-code step 1 pinned before run-change while the work template
had the first task commit the pins Constraints asks for, and sent a
flaw decision to a work file that did not exist yet. The pins stay
first; in-brainstorm lists them in Constraints as the guards, already
committed, so the first task commits none, and leaves the user's
decision on a flaw's code open, unnamed, for design.

docs(workflows): follow the moved rules ... cc1c12b0f2

The guide's forge and run-sandboxed entries say what the skills now do,
the hand-over on a refused action or a read and the commit with hooks
off, and the refactor-code chart's flaw node says the decision stays
open in the Brief for design.

claudiomaradonna merged commit cc1c12b0f2 into main 2026-11-09 09:18:15 +01:00

claudiomaradonna deleted branch fix/skill-gaps 2026-11-09 09:18:18 +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!204

No description provided.