Specifications as Execution Contracts
Greenlight before agents implement
"Build X" tickets produce unreviewable agent output. Reviewers argue product in the PR because there was never a merged rubric. Ambiguous specs become rework and midnight Slack - especially when agents widen the volume of code before intent is settled.
Here's what this piece covers: the leadership problem of prompt-and-pray delivery, what commit 74f9ffa (2026-07-07) adopted into the methodology, contract properties I still require, the named pattern, and three habits before you let agents open an implementation branch.
Part of the Field Notes: agentic delivery series - engineering-led delivery needs a contract, not a chat thread.
1. The leadership problem
Agents are excellent at filling space. Without a greenlit specification, they fill the wrong space. The anti-pattern is prompt and pray - no acceptance criteria, no out-of-scope, no verification plan.
Wrong: "Write better docs."
Right: "74f9ffa: contract properties and a post-greenlight lifecycle - what agents may implement after Owner approval."
A narrative wiki page is not an execution contract. A contract is testable, versioned, and explicit about what stays out.
2. What the git history shows
On 2026-07-07, commit 74f9ffa - Selectively adopt Zazz spec and feature methodology for SBD - landed the contract model in agentic-framework:
| Artifact | Role |
|---|---|
docs/methodology/specifications.md |
What a deliverable SPEC must contain |
docs/methodology/spec-driven-development.md |
Lifecycle after greenlight |
spec-builder skill |
Template + content rules for contracts |
spec-driven skill |
In-place amendments, change log, AC/TDD loop |
Same day, handoff/confluence skills continued the operating surface (c3543ec nearby). The proof point in product work: ~47 SPEC files under global-services/docs/ (team-tracked count from our metrics snapshot; light verify today finds ~45 *SPEC*.md matches - treat as approximate).
Weak vs strong criteria - the reusable teaching example:
Weak: The dashboard works correctly.
Strong: When the API returns no records, the dashboard renders the empty
state with no table rows and no error banner. Verified by the
empty-result component test and one browser check.3. What I built
Contract properties every SPEC carries: scope in/out, dependencies, acceptance criteria, test strategy and evidence, halt conditions, standards to load, paste-ready implementation prompt, and an Implementation And Review Change Log.
Authority gate - Owner greenlight before implementation. Small fixes may start at SPEC; uncertain direction starts at proposal. Spec approval is the authority gate, not a courtesy review after code exists.
Lifecycle after greenlight - accepted steering updates the SPEC in place; the change log is the audit trail, not a second requirements source. qa-testing produces evidence against criteria; pr-review grades the PR against the governing SPEC.
What broke: SPECs that read like marketing cause agents to over-build. Missing verification sections make "done" undefined - and human reviewers invent the rubric in the PR thread.
4. Named pattern: spec as execution contract
Spec as execution contract - testable, versioned, explicit out-of-scope; what agents may implement after greenlight.
| Property | Decision it supports |
|---|---|
| Scope / exclusions | What not to build |
| Acceptance criteria | Binary pass/fail |
| Test strategy + evidence | What "done" looks like in CI and review |
| Halt conditions | When the agent must stop and ask |
| Change log | How the current contract got there |
What broke: treating the SPEC as disposable once coding starts. After greenlight, the body remains the executable truth - amend it, do not invent a parallel Slack truth.
5. What I'd do as a lead
Three habits - steal one this month:
- No agent implementation branch without a merged SPEC path in the repo. Chat is not the contract.
- Template every program with
spec-builder. Same sections every time; stop free-form "agent prompts" as the only artifact. - Quarterly audit: open PRs without a SPEC link. If reviewers cannot find the rubric, the process failed before the diff.
Further reading
- Field notes: agentic delivery - series intro
- Next: Invisible Unicode - markdown as an attack surface
- agentic-framework anchor: commit
74f9ffa· 2026-07-07 ·docs/methodology/specifications.md
