Skip to content

docs: add 'Writing and running a spec' to the README - #6

Merged
buggtb merged 1 commit into
mainfrom
docs/writing-and-running-a-spec
Oct 12, 2026
Merged

buggtb merged 1 commit into
mainfrom
docs/writing-and-running-a-spec

Conversation

@buggtb

@buggtb buggtb commented Oct 12, 2026

Copy link
Copy Markdown
Contributor

Adds a developer-facing section (anchor #writing-and-running-a-spec): a worked example (issue to spec, spec committed first, red then green), the exact local validate/run/proof commands, how to read the PR checks and sticky comment, the rules (red on base, green on head, not-run, report vs enforce, cutoff), the two human-only labels, and troubleshooting.

Also fixes an inconsistency: the cutoff was documented as the latest issue number, but the check enforces issues at or above it, so it must be the latest issue or PR number plus one (README and docs/adopting.md).

Every command was run against a scratch app (command and api specs, red then green, base-check proof, passes-on-base failure, invalid spec). Unit tests: 136 pass.

🤖 Generated with Claude Code

…ff wording

The convention enforces issues at or above enforce-from-issue, so the
documented cutoff must be the latest issue or PR number plus one.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown

Acceptance self-test (fixture)

Check Result What it means
Convention (a closing PR ships its spec) Nothing to check Nothing to check on this PR.
Specs on this PR's build Pass Everything that ran passed.
Spec-first proof (red on base, green on this PR) Nothing to check Nothing to check on this PR.

Updated for commit 3d41cfc, workflow run. This comment is edited in place, never repeated.

@buggtb
buggtb merged commit a263f64 into main Oct 12, 2026
21 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant