Bring-Your-Own Spec Canvas - substrate (c)
For teams who bring their own idea. You don’t have to build
/recommendor start from the blank skeleton - you can spec a small slice of something real to your world. This canvas keeps you honest: same spec-first discipline, same Definition of Done, scoped to one endpoint so you can actually finish in 55 minutes.Fill the six boxes top to bottom. Each box flows into the next - the contract is written from the acceptance criteria, the DoD checks the contract. That’s Way #1. Freeze it at Gate 1 before you write code.
The canvas - fill top to bottom
1. Problem (one sentence)
What can’t someone do today? Whose pain?
▸ _______________________________________________
2. Consumers (who calls it, what they do with the answer)
Name the caller and the screen/job. API-as-a-product (REQ-API-1).
| Consumer | What they do with the response |
|---|---|
3. One endpoint (method + path)
Exactly one. Pick the smallest slice that proves the idea. (ENG-PRIN-INCR-STMT - small steps.)
▸
GET /api/__________- orPOST /api/__________If it’s a
POST(a write), note that retries need anIdempotency-Key(REQ-API-6). If it’s aGET, it’s safe and idempotent already - no key needed.
4. Acceptance criteria (the demo checklist)
Concrete, testable. These become your contract assertions and your tests.
- …
- …
- Errors use the shared RFC 7807
Problemenvelope (REQ-API-5).
5. Contract (the response shape)
Write the schema BEFORE the code. Start from greenfield-openapi-skeleton.yaml, rename the resource, fill in your fields. This is the machine-readable contract the whole team works from (REQ-API-2).
▸ Schema name: ______________ ▸ Required fields: ______________________
▸ Lives in:
./<your-api>.openapi.yaml
6. Definition of Done (QUAL-PRINC-SDLC)
The same bar as everyone else - no shortcuts because it’s your own idea.
- Contract written and frozen (
REQ-API-2) - One unit test for the core logic at the lowest viable layer (
QTEST-EARLY) - One contract test: the response validates against your OpenAPI schema (
REQ-API-7,QTEST-CONTRACT) - One E2E happy path (
QTEST-E2E) - A human reviewed and approved - no self-merge (
ENG-PRIN-REVIEW-STMT, Way #2) - One ADR capturing the key trade-off (
adr-template.md, Way #5)
Guardrails - non-negotiable
| Rule | Why |
|---|---|
| No secrets in prompts. No API keys, tokens, credentials, real customer data, or PII. | Way #3: Mind what you feed it. Treat every prompt like a public postcard. |
| No prod systems. Don’t connect to anything real - no live databases, internal APIs, or production endpoints. | This is a sandbox. Blast radius = zero. |
| One endpoint only. Resist scope creep; ship one slice that works. | ENG-PRIN-SIMPLE-STMT (YAGNI), ENG-PRIN-INCR-STMT (small steps). A finished slice beats a half-built epic. |
| Synthetic data only. Invent rows. Anonymise anything inspired by reality (Person A, Vendor 1). | Way #3. |
| Same DoD as everyone. The bar in box 6 applies to your idea too. | QUAL-PRINC-SDLC - fairness and a real teaching point. |
Stuck for an idea? The /recommend worked example in feature-spec-template.md is the reference shape. The five ways: ways-of-working.md.
Downloads for this session
Grab the templates and sample files used here.