What the contract says today
implement-issue-workflow binds the behaviour specification to completion, not to start:
If the issue adds or changes observable behaviour — a feature, a behavioural enhancement, or a behaviour-changing bug fix — use ../bdd-specification/SKILL.md no later than implementation time. This is the strict default: a language-agnostic Gherkin .feature spec must exist and be bridged into the tests through the scenario-to-test naming convention before the change is considered done. Write or complete the spec first when analysis did not already produce it.
bdd-specification says the same thing from its own side:
Specify the behaviour as Gherkin as early as request or analysis time; the specification and its test bridge must exist by the time the change is implemented.
Both sentences are satisfied by an agent that writes code first and the .feature file afterwards, as long as both are there before the pull request is declared done. "Write or complete the spec first" states the preference but is not the binding condition — the binding condition is done.
Why that is a gap
The specification is not only documentation of the behaviour; it is the plan for it. Writing it is part of planning how a requirement gets implemented. If it may legitimately be produced after the code, three things the workflow relies on stop being true:
- The specification is no longer an independent statement of intent. It is written by the same session, against code that already exists, and it will agree with that code — including where the code is wrong.
- Nothing checks completeness of specification before development starts. The check exists, but it runs at the end:
convergence-check asks as the second of its seven questions whether "every added or changed observable behaviour [is] described by a Gherkin scenario, or covered by an explicit recorded waiver". At that point the cost of a missing scenario is rework, not a five-minute correction.
architecture-impact carries the same question in its own checklist, and it also runs alongside implementation rather than as a gate before it.
This is the same failure shape the toolkit already models elsewhere: generation and verification collapsing into one session and confirming the same assumption twice.
Proposal
Make the start of implementation conditional on the specification existing, rather than its end. Concretely, in implement-issue-workflow:
- Change "no later than implementation time" / "before the change is considered done" into a precondition: for behaviour-adding or behaviour-changing work, the Gherkin
.feature spec exists and is bridged before implementation of that slice begins.
- Keep the existing escape hatch unchanged — an explicit human waiver recorded in the issue or pull request.
- Say what happens when the precondition is not met: the workflow writes the specification first, it does not proceed and backfill.
Open decision
Where does the binding belong?
implement-issue-workflow — the skill that starts implementation, and the one that would enforce the precondition. This is the smaller change.slice-issues — arguably the more correct place, because that is where a requirement is decomposed and where the specification would naturally be written as part of planning. Today slice-issues contains no reference to Gherkin, .feature, or BDD at all; it produces sub-issues with acceptance criteria and explicitly says "Keep implementation work out of the slicing step". Adding the specification there would be a larger change to that skill's scope.
A third option is a light version in both: slice-issues produces the specification with the slice, implement-issue-workflow refuses to start without it.
Evidence
skills/implement-issue-workflow/SKILL.md on mainskills/bdd-specification/SKILL.md on mainskills/slice-issues/SKILL.md on main — no BDD referenceskills/convergence-check/SKILL.md on main, question 2skills/architecture-impact/SKILL.md on main
Found while checking the toolkit contract against the claims of an article about this workflow, so the wording had to hold up to an outside reader.
What the contract says today
implement-issue-workflowbinds the behaviour specification to completion, not to start:bdd-specificationsays the same thing from its own side:Both sentences are satisfied by an agent that writes code first and the
.featurefile afterwards, as long as both are there before the pull request is declared done. "Write or complete the spec first" states the preference but is not the binding condition — the binding condition is done.Why that is a gap
The specification is not only documentation of the behaviour; it is the plan for it. Writing it is part of planning how a requirement gets implemented. If it may legitimately be produced after the code, three things the workflow relies on stop being true:
convergence-checkasks as the second of its seven questions whether "every added or changed observable behaviour [is] described by a Gherkin scenario, or covered by an explicit recorded waiver". At that point the cost of a missing scenario is rework, not a five-minute correction.architecture-impactcarries the same question in its own checklist, and it also runs alongside implementation rather than as a gate before it.This is the same failure shape the toolkit already models elsewhere: generation and verification collapsing into one session and confirming the same assumption twice.
Proposal
Make the start of implementation conditional on the specification existing, rather than its end. Concretely, in
implement-issue-workflow:.featurespec exists and is bridged before implementation of that slice begins.Open decision
Where does the binding belong?
implement-issue-workflow— the skill that starts implementation, and the one that would enforce the precondition. This is the smaller change.slice-issues— arguably the more correct place, because that is where a requirement is decomposed and where the specification would naturally be written as part of planning. Todayslice-issuescontains no reference to Gherkin,.feature, or BDD at all; it produces sub-issues with acceptance criteria and explicitly says "Keep implementation work out of the slicing step". Adding the specification there would be a larger change to that skill's scope.A third option is a light version in both:
slice-issuesproduces the specification with the slice,implement-issue-workflowrefuses to start without it.Evidence
skills/implement-issue-workflow/SKILL.mdonmainskills/bdd-specification/SKILL.mdonmainskills/slice-issues/SKILL.mdonmain— no BDD referenceskills/convergence-check/SKILL.mdonmain, question 2skills/architecture-impact/SKILL.mdonmainFound while checking the toolkit contract against the claims of an article about this workflow, so the wording had to hold up to an outside reader.