Docs Project

---
name: docs-project
description: "Project (engineering) documentation branch — the 'how': README, ENTRY, AGENT/DELIVERY runbooks, and docs/ (REFERENCE map, ARCHITECTURE, ADR, SAGA, TEST_CASES, DEV_GUIDE, IMPROVEMENTS, TROUBLESHOOTING, BACKLOG, REVIEW, STATUS) plus contracts/ (OpenAPI/AsyncAPI — machine truth written BEFORE code). The map rule: every doc gets a card in REFERENCE.md. Full catalog + checklist in references/project-docs.md. Triggers: 'проектная документация', 'архитектура документация', 'adr', 'engineering docs', 'документация разработчика', 'контракты openapi', 'project docs', 'инженерная документация'."
license: MIT
metadata:
  author: bestdeejay-design
  version: "1.0.1"
compatibility: "No scripts — template-driven authoring"
when_to_use: "Use when user needs engineering docs: 'проектная документация', 'архитектура документация', 'adr', 'engineering docs', 'документация разработчика', 'контракты openapi', 'project docs', 'инженерная документация'. Examples: 'write the ARCHITECTURE.md', 'сгенерируй README и ADR для репозитория'."
---

# 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.