Repository navigation
chore(agents): add delivery-flow skills - #2110
Merged
Benoît Cortier (CBenoit) merged 15 commits intoOct 20, 2026
Merged
Conversation
Six skills describing how a change is delivered at each scale, so an agent picks the smallest flow that fits and knows where the intent, contract, test, and review skills enter it. - `contribute`: the router. Fix, Change, or Effort by scale, the signals that promote one to the next, and where the other skills enter. - `tdd`: the red-green loop for one behaviour at an agreed seam, with `test-writer` deciding the test and `test-oracle-reviewer` the value. - `lead`: one pull request per session, delivered with sub-agents, a fresh-context reviewer on a frozen snapshot, the lead's own verification, and a report the reader can verify; the brief and report templates sit in a reference file. - `orchestrate-effort`: a multi-pull-request effort with stages, one lead per pull request, scheduled human gates on intent and contract, and a state record kept outside the tree; the harness mapping and state artifacts sit in reference files. - `review-feedback-loop`: triage of findings on an open pull request, one re-request per substantive change, and the signals that end the loop. - `blind-testsuite`: a conformance suite written from a `CONTRACT.md` and published sources only, by an author who never sees an implementation, and read-only while implementations are built against it. Every flow is the same loop at a different scale: decide what must hold, write the check that fails without it, make it pass, and have someone who did not write it review. The skills name each other rather than restating rules, so a decision has one home: `contribute` routes, `tdd` and `lead` run the loop, `orchestrate-effort` coordinates leads, and the two remaining skills cover the moments the others hand off to. The skills are deliberately small because every loaded line costs context; each triggers and loads on its own, and material read only when needed sits in `references/`. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Shared-branch push guidance can discard human changes, and workflow instructions contain unresolved contradictions.
4 open issues
What changed in this PR
Adds six delivery-flow skills that connect existing intent, contract, testing, and review guidance.
Changes:
- Routes work into fix, single-PR, or multi-PR workflows.
- Defines test-first development, blind-suite isolation, and review follow-up.
- Adds delegation templates and orchestration state references.
| File | Description |
|---|---|
.agents/skills/tdd/SKILL.md |
Defines the red-green development loop. |
.agents/skills/review-feedback-loop/SKILL.md |
Guides review triage and stopping conditions. |
.agents/skills/orchestrate-effort/SKILL.md |
Coordinates multi-PR delivery. |
.agents/skills/orchestrate-effort/references/state.md |
Defines persistent coordination artifacts. |
.agents/skills/orchestrate-effort/references/harness.md |
Maps workflow concepts to agent tools. |
.agents/skills/lead/SKILL.md |
Guides single-PR delegation and verification. |
.agents/skills/lead/references/templates.md |
Provides brief and report templates. |
.agents/skills/contribute/SKILL.md |
Selects workflows by change scope. |
.agents/skills/blind-testsuite/SKILL.md |
Defines independent conformance-suite authoring. |
Review effort: Balanced
Same rules and reasons in fewer words, because every loaded line costs context and a rule that takes two sentences to state is read less carefully than one that takes one. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…the text In a stacked effort the contract and suite pull requests stay open while implementations run against them, so a change to that text goes to the lead that owns the pull request rather than to a new one. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Where a pipeline reviews each head on its own, the push is the request and each head spends one of a bounded number of reviews, so fixes are batched per push and findings that need no code change are answered with the pipeline's hand-off command. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
A design choice that paper cannot settle is probed by two or three isolated implementations judged blind against fixed criteria. The resulting brief informs the final design, which is implemented fresh rather than promoted from a probe. Intent stays human-written, and a provisional design guides implementation but not merge. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
A criterion measures what the design commits to and cannot polish away later, so hygiene a lint catches is excluded. Acceptance checks are shared and written before the variants. Only the front where a trade exists reaches the brief. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
A lease guards against pushes after the fetch, not before it, so the branch is rebased onto its moved head before any push. A lead may edit the normative text its own pull request owns. Acceptance evidence and brief deviations go in a comment, because the body becomes the squash commit. The blind suite step applies only when there is a contract. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…he review round A decision stated by the intent, the contract, or the bug report is settled, so only one none of them states triggers the interview. A lead's workers build each behaviour through `tdd` or against the blind suite's failing checks, so the failing check comes first at every scale. An automated round's result is watched for and triaged when it lands, while a human's approval is reported and not watched for. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
A reviewer that saw the fixes is the only evidence they held, so the loop runs until a round returns nothing accepted. A wrong finding is answered with the governing clause, not applied. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
In a single-pull-request change the same pull request owns the intent change and its realisation, so only normative text the pull request does not own is routed elsewhere. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…erage The contract keeps only what conformance means for each party, because neither party agrees to which test checks which rule, and a mapping kept apart from the tests drifts as they are renamed. The rule-to-test mapping, review-only claims, and known gaps live in a coverage record beside the suite. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The contract's rules define conformance, and the suite is independent evidence derived from them. Defining conformance as passing the suite makes the evidence the rule, so a party that follows the contract stops conforming when the suite has a bug. Shared vectors stay a rule in the section they test. An acceptance rule for the work, such as passing the suite before merge, is a process rule and not the software's. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Test vectors and suites are evidence for the rules, so their role and pass conditions belong to the suite and its intent, never to the contract. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
A rule about an output is tested through that output, and inventing a rejection for it would fail a conforming implementation. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
A reviewer sees where a change's weight lies before reading it when the lines changed are split into production code, tests, and the rest. The report is a comment because the body becomes the squash commit, whose own stat already carries the raw numbers. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Member
Author
|
Lines changed against
Counted with Note LLM-assisted content (no human feedback). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Seven skills describing how a change is delivered at each scale, so an agent picks the smallest flow that fits and knows where the intent, contract, test, and review skills enter it.
contribute: the router. Fix, Change, or Effort by scale, the signals that promote one to the next, and where the other skills enter.tdd: the red-green loop for one behaviour at an agreed seam, withtest-writerdeciding the test andtest-oracle-reviewerthe value.lead: one pull request per session, delivered with sub-agents, a fresh-context reviewer on a frozen snapshot, the lead's own verification, and a report the reader can verify; the brief and report templates sit in a reference file.orchestrate-effort: a multi-pull-request effort with stages, one lead per pull request, scheduled human gates on intent and contract, and a state record kept outside the tree; the harness mapping and state artifacts sit in reference files.review-feedback-loop: triage of findings on an open pull request, one re-request per substantive change, and the signals that end the loop.blind-testsuite: a conformance suite written from aCONTRACT.mdand published sources only, by an author who never sees an implementation, and read-only while implementations are built against it.variants: two or three isolated probe implementations of one brief that differ in named decisions, judged blind against fixed criteria, returning a decision brief from which the human or the lead picks or composes the final design.Every flow is the same loop at a different scale: decide what must hold, write the check that fails without it, make it pass, and have someone who did not write it review.
The skills name each other rather than restating rules, so a decision has one home:
contributeroutes,tddandleadrun the loop,orchestrate-effortcoordinates leads,variantssettles a choice only implementation evidence can, and the two remaining skills cover the moments the others hand off to.contract-authoringandcontract-reviewdrop the conformance section from the contract: its rules define conformance, and the rule-to-test mapping, review-only claims, and known gaps live in the suite's coverage record.commit-and-pr-conventionsasks for a lines-changed comment split into production code, tests, and other files.The skills are deliberately small because every loaded line costs context; each triggers and loads on its own, and material read only when needed sits in
references/.Co-authored-by: Copilot App 223556219+Copilot@users.noreply.github.com