docs: lead with the four-line start, and the 1.0.1 changelog (#140) - #143
Conversation
…swer the gates (#140) The README opens with install, init, start your agent, one prompt — and says who does what. The introduction's reading order says the same two things first; the quickstart's suggested prompt matches.
4283290 to
2770848
Compare
![radiusred-checky[bot]](https://avatars.githubusercontent.com/in/4719924?s=60&v=4){kind=small}
There was a problem hiding this comment.
One blocking accuracy finding in the new “Start now” copy:
“from there it opens the first milestone, writes a plan into a task before touching code, does the work, opens the PR, and stops at every gate — because the CLI refuses to let it do otherwise.”
The scaffold gives an agent instructions, and individual verbs refuse invalid state when the agent invokes them; the CLI cannot make an arbitrary agent open a milestone or PR, cannot observe whether it touched code before planning, and cannot force it to invoke the next verb. Please recast this as the intended guided workflow rather than behavior the framework guarantees. The following “Everything else … takes care of itself” makes the same unsupported promise and should be made concrete as well.
The README's start block promised behaviour the CLI cannot make an agent perform. It now names the shape the contracts give the work and the three refusals that enforce it (checky, PR #143).
|
Right — that paragraph claimed the CLI makes the agent do things, when what it does is refuse at the gates. Recast in |
There was a problem hiding this comment.
Fix round verified cold. The README now describes the contract-shaped workflow and names enforceable refusals instead of promising agent behaviour. Source confirms task start refuses with NO_PLAN when no plan is present; task finish refuses for absent, pending, or failing checks and requires the routed reviewer holder's approval (or a non-author approval in the solo path); milestone close refuses with VERDICT_MISSING or VERDICT_UNSATISFIED for requirements lacking a satisfied QA verdict. I found no remaining sentence in the amended paragraph that claims the CLI can compel agent behaviour. HEAD~1..HEAD touches only README.md, all commit-message lines are at most 69 characters, and both PR checks pass.
Closes #140
The README now opens with the whole of onboarding — four lines and one sentence to your agent — directly after the "why", and says the thing the old page only implied: you do not run the verbs; your agent does. The operator is needed at three moments (a gate's question, a PR review, a verdict). The old "Start solo in five minutes" folds into a short "Where it goes from here" that keeps the ladder. The introduction's reading order says the same two things first, and the quickstart's suggested prompt matches.
The bare prompt is true because #141 (merged, PR #142) makes
initwriteCLAUDE.mdimportingAGENTS.md; the CHANGELOG entry for 1.0.1 rides here, and the v1.0.1 tag follows this merge so the README describes the release adopters install.Operator review waived for this one (Darren, 2026-08-27: "no tone check needed from me"); routed reviewer seat next.
Requirement: M6-R2.