Agent Skills

Docs Project — engineering documentation («how»)

Use this skill to write the engineering documents: architecture, decisions (ADR), contracts, dev guides, tests, and the documentation map. Assumes the product docs exist (docs-product: VISION/PRD/ROADMAP/FEATURES).

When to use

• A project needs its engineering docs: README, ENTRY, ARCHITECTURE, ADR, tests.
• User asks for “проектная документация”, “архитектура документация”, “adr”, “инженерная документация”, “контракты openapi”, “engineering docs”.
• Contracts (OpenAPI/AsyncAPI) must be written before code.

Do NOT use

• For product docs (VISION/PRD/ROADMAP/FEATURES) — that is docs-product.
• For the meta-guide (phases, levels L1/L2/L3, completeness checklist) — docs-system.

Root documents

File	Purpose	Phase	Template
README.md	Overview: what it is, stack, status, quick start, structure	1 → 10	templates/project/README.tmpl
ENTRY.md	Entry point: “start here”, navigation “topic → file”, onboarding checklist	9	templates/project/ENTRY.tmpl
AGENT.md	Runbook for the autonomous build agent: phases, rules, DoD, commit gate	8	—
DELIVERY.md	Delivery gate: build/run/verify, what’s in, what’s NOT	8	—
Legal/community	LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY	1/9	—

docs/ — engineering documents

File	Purpose	Phase	Template
docs/REFERENCE.md	The map. Card for EVERY doc: purpose/structure/facts/links, hierarchy of truth, drift table. Written last.	10	templates/project/REFERENCE.tmpl
docs/ARCHITECTURE.md	Components, communication, data flows, tech stack	2 → 6	templates/project/ARCHITECTURE.tmpl
docs/ADR/ADR-000.md	Architecture Decision Records — one per significant decision	2 (ongoing)	templates/project/ADR-000.tmpl
docs/SAGA.md	Cross-module scenarios (choreography, events, compensation, idempotency)	5	templates/project/SAGA.tmpl
docs/TEST_CASES.md	Test cases (Gherkin-style) + coverage matrix	6	templates/project/TEST_CASES.tmpl
docs/DEV_GUIDE.md	Local dev: prerequisites, run, env, migrations, debugging	7	templates/project/DEV_GUIDE.tmpl
docs/IMPROVEMENTS.md	Known issues / doc-vs-fact drift + prioritized fix plan	8	templates/project/IMPROVEMENTS.tmpl
docs/TROUBLESHOOTING.md	Runtime error diagnostics (E1…En) + startup checklist	8	templates/project/TROUBLESHOOTING.tmpl
docs/BACKLOG.md	Ideas, deferred features, priorities	1	templates/project/BACKLOG.tmpl
docs/REVIEW.md	Doc audit: problems, resolutions, per-service status	10	templates/project/REVIEW.tmpl
docs/STATUS.md	L1 alternative to REVIEW: done / in progress / limitations	10	templates/project/STATUS.tmpl

contracts/ — machine truth (API-first / microservices)

Path	Purpose	When
contracts/openapi/*.yaml	Per-service OpenAPI specs — the HTTP truth	before code
contracts/asyncapi/events.yaml	Event catalog — the event truth	before code
contracts/test/	Contract-conformance test fixtures	with tests

Contracts are written BEFORE code. The code implements the contract, not the other way around — «machine truth before code».

The map rule

Every document that exists gets a card in docs/REFERENCE.md (purpose → structure → key facts → links). Written last, maintained on every change: touch a doc → update its card.

Checklist (project side)

• One entry point exists (ENTRY.md) and routes “topic → file”.
• Every doc has a card in REFERENCE.md (including REFERENCE itself).
• Hierarchy of truth declared (which doc wins on conflict).
• Drift table (doc-vs-fact) populated — no silent inconsistencies.
• Contracts exist before code for every API/event (API-first projects).
• DELIVERY.md states how to build/verify/what’s in/what’s NOT.

Rule: engineering docs answer «how»; the map (REFERENCE.md) is written last because it describes everything above it.

Boundaries

• Do not use for product vision, PRDs, or roadmap decisions; use docs-product.

Authoring procedure

1. Inventory the repository and establish the hierarchy of truth.
2. Write contracts before implementation docs when the project exposes APIs or events.
3. Draft architecture and ADRs from observed code and explicit decisions; label assumptions.
4. Add runbooks and test cases with copy-pasteable commands and expected results.
5. Write REFERENCE.md last and add a card for every document.

Definition of done

Every generated document names its source of truth, owner or update trigger, prerequisites, commands, and failure path. Verify links, commands, and contract examples against the repository; do not mark a document complete merely because the template is filled.

This site is open source. View this page on GitHub.