engdesign-kit

Detailed engineering design templates and worked examples — the layer between plan.md and tasks.md that spec-kit doesn't ship.

engdesign-kit is a complement to github/spec-kit, not a replacement. spec-kit's /specify → /plan → /tasks flow handles user stories and high-level architecture well, but stops short of the contract-level detail a real subsystem needs before code review or production. This repo fills that gap.

---

What spec-kit covers vs. what this repo adds

Layer	spec-kit	engdesign-kit
Governing principles	constitution.md	—
User stories / acceptance	spec.md	—
Tech stack / high-level architecture	plan.md	—
Data model	data-model.md	—
Interface signatures	contracts/	—
State machines	—	✅ template + example
Error code contracts	—	✅ template + example
Cross-cutting execution order + invariants (RBAC, audit, rate-limit)	—	✅ template + example
Guardrails / trust labels / prompt-injection	—	✅ template + example
Observability schema (span names, metric names, alert thresholds, audit JSON)	—	✅ template + example
Alternatives considered (decisions rejected, with reasons)	—	✅ template + example
Rollout / grayscale / rollback RTO	—	✅ template + example
Risk register with owner + trigger condition	—	✅ template + example
Phased tasks with [P] parallel markers	tasks.md	—

We position these as a single-file Google-style engineering design document (engineering-design.md) that sits between plan.md and tasks.md in the spec-kit flow. See INTEGRATION.md for the integrated pipeline.

---

Quick start

1. Decide if you need this layer. Most features don't. Run the needs-detailed-design checklist first.
2. Copy the template. Start from templates/engineering-design.md.
3. Read a worked example. examples/llm-tool-dispatcher/ is a battle-tested ~700-line design doc for an LLM agent tool dispatcher (state machine, error codes, RBAC, guardrails, observability, rollout — the works).
4. Wire it into spec-kit. Follow playbooks/spec-kit-integration.md.

---

When NOT to use this

Skip detailed engineering design when:

• Pure CRUD or UI-only changes
• Single-file bug fixes
• One-shot scripts or POCs
• Features with no cross-cutting concerns (auth, rate-limit, audit, observability)

The decision checklist gives the full rule.

---

Repository layout

engdesign-kit/
├── README.md                          # this file
├── INTEGRATION.md                     # how to wire into spec-kit (Mode B)
├── LICENSE                            # Apache 2.0
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── CHANGELOG.md
│
├── templates/
│   └── engineering-design.md          # single-file template, ~14 sections
│
├── examples/
│   └── llm-tool-dispatcher/           # worked example: LLM tool dispatcher
│       ├── README.md
│       └── design.md
│
├── checklists/
│   └── needs-detailed-design.md       # decision tree: do we need this layer?
│
├── playbooks/
│   └── spec-kit-integration.md        # Mode B: design.md between plan and tasks
│
└── docs/
    └── why.md                         # the 14 categories of non-functional concerns
                                         that spec-kit leaves to the implementor

---

Roadmap

• v0.1 (current): single-file template + one worked example + spec-kit integration playbook
• v0.2: component-level templates (state-machine.md, observability.md, etc.) for users who prefer multi-file
• v0.3: 2–3 more worked examples in different domains (REST CRUD with auth, async job pipeline)
• v0.4: AI-agent prompts for drafting individual sections from spec.md + plan.md

See CHANGELOG.md.

---

Contributing

We welcome PRs that add templates, refine checklists, or contribute new worked examples. See CONTRIBUTING.md. The bar for new templates is: does it solve a non-functional concern that spec-kit has no standard home for? If yes, propose via an issue first.

---

License

Apache 2.0 — same as spec-kit, to make integration friction-free.