feat(skills): start a work from its folder's files #201

Merged

claudiomaradonna merged 2 commits from feat/folder-documents into main

2026-11-06 12:15:55 +01:00

motoko commented

2026-11-06 12:10:57 +01:00

Collaborator

Why

The skills said how to use a work file, a diagnosis, or an audit the
user hands in through 22 clauses spread over 12 skill and guide files,
each written for one workflow. They disagreed, as on the name a
handed-in audit is saved under, and none covered a work an earlier
session left in its folder. Agents met real gaps: document-feature
audited a handed-in work file again without sending its Brief back to
brainstorm, so the new findings surfaced only after execution; a new
production dependency in a handed-in work file or a design decision
never reached dependency-advisor, whose report was kept nowhere; and
document-feature's "stop or go on" question lived only in the guide.

Asking at every workflow's start whether the user has files to hand in
was set aside: it stops every work, unattended runs included, and
leaves the content rules in place. A home in run-change was set aside
because the opening steps and the actions run alone never read it, and
a new internal skill because it adds an abstraction.

What changed

AGENTS.md § Work folders now says which files of a work folder count,
those the user hands in or the work's sessions write, and run-change
starts a work at the first step they leave undone, keeping a passed
Work file gate's start at execute-plan. A step before write-plan
that changes an approved work file clears its gate rows, so the user
approves the change. Opening steps run only when the folder lacks their
document.

brainstorm is done only when the Brief answers every finding and fix
option in the folder and assessment.md, which keeps
dependency-advisor's reports, covers each upgrade and new production
dependency; design runs the advisor before a dependency decision, and
the user is asked when the advisor advises against a dependency the
work already counts on. A handed-in audit goes by its kind: a
documentation audit to document-feature or implement-feature,
another with a defect to fix-bug, the rest to brainstorm.
document-feature gains its stop step. The guide states the rule once,
in docs/workflows/how-it-works.md, and UPGRADING.md carries a
repository's own edits to the old clauses through the Folder documents
migration.

How to verify

From the branch's worktree, run the behavioral evals against main:
base=$(evals/run.sh --policy main), tip=$(evals/run.sh --policy HEAD),
then evals/report.sh "$tip" "$base"; each case should pass as often
as on main. By hand, in a session on the branch, put an approved
work.md and a new audit in one .plans/ folder and ask to resume
the work: the agent revises the Brief in brainstorm and asks for the
work file's approval again, where main goes on at execute-plan.

The checks of docs/MAINTENANCE.md pass on the tip: 225 agent
configuration tests, 46 work-folder check tests, ShellCheck on 49
files, Prettier, the validator, and git diff --check main. No test
checks this prose. The evals did not run, since each run is billed.

Considerations

AGENTS.md grows by two bullets, which every session loads.

https://claude.ai/code/session_012CBsgmcuP48k1DtpTcmWGP

## Why The skills said how to use a work file, a diagnosis, or an audit the user hands in through 22 clauses spread over 12 skill and guide files, each written for one workflow. They disagreed, as on the name a handed-in audit is saved under, and none covered a work an earlier session left in its folder. Agents met real gaps: `document-feature` audited a handed-in work file again without sending its Brief back to `brainstorm`, so the new findings surfaced only after execution; a new production dependency in a handed-in work file or a `design` decision never reached `dependency-advisor`, whose report was kept nowhere; and `document-feature`'s "stop or go on" question lived only in the guide. Asking at every workflow's start whether the user has files to hand in was set aside: it stops every work, unattended runs included, and leaves the content rules in place. A home in `run-change` was set aside because the opening steps and the actions run alone never read it, and a new internal skill because it adds an abstraction. ## What changed `AGENTS.md` § Work folders now says which files of a work folder count, those the user hands in or the work's sessions write, and `run-change` starts a work at the first step they leave undone, keeping a passed Work file gate's start at `execute-plan`. A step before `write-plan` that changes an approved work file clears its gate rows, so the user approves the change. Opening steps run only when the folder lacks their document. `brainstorm` is done only when the Brief answers every finding and fix option in the folder and `assessment.md`, which keeps `dependency-advisor`'s reports, covers each upgrade and new production dependency; `design` runs the advisor before a dependency decision, and the user is asked when the advisor advises against a dependency the work already counts on. A handed-in audit goes by its kind: a documentation audit to `document-feature` or `implement-feature`, another with a defect to `fix-bug`, the rest to `brainstorm`. `document-feature` gains its stop step. The guide states the rule once, in `docs/workflows/how-it-works.md`, and `UPGRADING.md` carries a repository's own edits to the old clauses through the Folder documents migration. ## How to verify From the branch's worktree, run the behavioral evals against `main`: `base=$(evals/run.sh --policy main)`, `tip=$(evals/run.sh --policy HEAD)`, then `evals/report.sh "$tip" "$base"`; each case should pass as often as on `main`. By hand, in a session on the branch, put an approved `work.md` and a new audit in one `.plans/` folder and ask to resume the work: the agent revises the Brief in `brainstorm` and asks for the work file's approval again, where `main` goes on at `execute-plan`. The checks of `docs/MAINTENANCE.md` pass on the tip: 225 agent configuration tests, 46 work-folder check tests, ShellCheck on 49 files, Prettier, the validator, and `git diff --check main`. No test checks this prose. The evals did not run, since each run is billed. ## Considerations `AGENTS.md` grows by two bullets, which every session loads. https://claude.ai/code/session_012CBsgmcuP48k1DtpTcmWGP

motoko added 2 commits

2026-11-06 12:11:03 +01:00

feat(skills): start a work from its folder's files 4b6d3b5208

The skills said how to use a work file, diagnosis, or audit the user
hands in, each for its own workflow, in clauses that disagreed and that
left out a work an earlier session had left in the folder. One rule in
AGENTS.md § Work folders now says which files of a folder count, and
run-change starts a work at the first step they leave undone.

With it, document-feature sends a written Brief back to brainstorm for
a new audit, and dependency-advisor assesses every new production
dependency, its report kept as assessment.md. UPGRADING.md carries a
repository's own edits to the new homes.

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

docs(workflows): describe the folder rule once

Maintenance / checks (pull_request) Successful in 4m10s

Details

Maintenance / checks (push) Successful in 3m43s

Details

954adcc6d6

The guide still said a handed-in work file starts "through its kind's
workflow", named the audit audits/docs.md on three pages, and drew the
upgrade step implement-feature no longer has. how-it-works.md now holds
the rule, with assessment.md and where each audit goes, and the pages
and charts of the workflows whose skills changed follow them.

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