# Docs System

> Гайд для AI-агента: как правильно составлять продуктовую и проектную документацию и её состав. Продуктовая ветка (VISION/PRD/ROADMAP/FEATURES) и проектная ветка (ARCHITECTURE/ADR/контракты/TEST_CASES/карта REFERENCE), порядок заполнения (фазы), шаблоны, чек-лист полноты, уровни L1/L2/L3 для больших систем. От идеи до полного набора документации. Триггеры: 'документация', 'набор документации', 'ка…

- **Type:** Skill
- **Install:** `agentstack add skill-bestdeejay-design-agent-skills-docs-system`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [bestdeejay-design](https://agentstack.voostack.com/s/bestdeejay-design)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [bestdeejay-design](https://github.com/bestdeejay-design)
- **Source:** https://github.com/bestdeejay-design/agent-skills/tree/main/skills/docs-system
- **Website:** https://bestdeejay-design.github.io/agent-skills/

## Install

```sh
agentstack add skill-bestdeejay-design-agent-skills-docs-system
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# docs-system — Guide: product & project documentation

A guide for an AI agent (and a human) on **how to compose product and project
documentation and what belongs in it**. It answers two questions:

1. **What documents exist** — the catalog, split into product docs (why/what)
   and project docs (how).
2. **In what order to create them** — the fill order, from an idea to a complete,
   consistent set.

## Why this skill exists

Most projects either have no docs (agents and humans get lost) or have *lots* of docs
with no system (contradictions, drift, nobody knows which file is authoritative).
This skill codifies the *system* that makes documentation useful:

- a **catalog** — what files exist, why, when they are created;
- a **fill order** — the phases from idea to a complete set;
- **templates** — copy-paste skeletons for every document;
- a **completeness checklist** — proof that nothing was forgotten;
- **levels** (optional reference) — right-sizing for small vs large systems.

The reference model behind this skill is the example monorepo (`examples/example-monorepo/`):
a microservices project whose docs stayed consistent for hundreds of commits
because every file had a purpose, there was an explicit hierarchy of truth, a
single entry point (`ENTRY.md`), a documentation map (`REFERENCE.md`), and a
delivery gate.

## When to use

- Starting a new repository / project — generate the docs skeleton **before** or
  **in parallel with** the first code.
- Turning a raw idea into a full documentation set.
- Auditing an existing project with missing/chaotic documentation.
- Adding a feature or service and needing to know *which docs to update*.

## Do not use

- Do not use for a single README or one standalone document — the skill is a system
  for a full documentation set, and a single file does not need the catalog/order.

## Two branches of documentation

### 1. Product docs — «why» and «what»

| Document | Answers | When |
|----------|---------|------|
| `docs/VISION.md` | Why does the product exist? For whom? | First — stays stable |
| `docs/PRD.md` | What exactly are we building? (requirements, priorities, metrics) | After VISION |
| `docs/ROADMAP.md` | What ships when? (milestones + proof) | Phase 2+, each milestone |
| `docs/FEATURES.md` | Feature catalog + status (✅/📋) | Phase 4, kept current |

### 2. Project docs — «how»

| Document | Answers | When |
|----------|---------|------|
| `README.md` | What is the project, how to run, status | 1 → 10 (final) |
| `ENTRY.md` (L2+) | Where to start; navigation «topic → file» | 9 |
| `docs/ARCHITECTURE.md` | Components, communication, data flows | 2 (draft) → 6 (final) |
| `docs/ADR/*` (L1: `DECISIONS.md`) | Architecture decision records | 2, ongoing |
| `docs/SAGA.md` (multi-module) | Cross-module scenarios, compensation | 5 |
| `docs/TEST_CASES.md` (L1: `TEST_PLAN.md`) | How correctness is proven | 6 |
| `docs/DEV_GUIDE.md` (L2+) | Local dev: run, env, debug, add-a-module | 7 |
| `docs/TROUBLESHOOTING.md` (L2+) | Errors E1…En + startup checklist | 8 |
| `docs/IMPROVEMENTS.md` (L2+) | Known issues, doc-vs-fact drift, fix plan | 8 |
| `docs/BACKLOG.md` (L2+) | Ideas, deferred features | 1, ongoing |
| `docs/REVIEW.md` / `STATUS.md` | Doc audit / state at delivery | 10 |
| `docs/REFERENCE.md` (L2+) | **The map** — written **last** | 10 |
| `contracts/openapi/*`, `contracts/asyncapi/` | Machine truth, **before code** | 3 |
| `AGENT.md`, `DELIVERY.md` (L2+) | Agent runbook + delivery gate | 8 |

## How to use this skill (TL;DR)

1. **Separate product from project.** Start with VISION/PRD («why/what»), never
   jump into architecture («how») first.
2. **Follow the fill order** (`references/order.md`): phases 1→10 from idea to
   complete set. Two golden rules: **contracts before code**, **map last**.
3. **Use the templates** (`templates/product/`, `templates/project/`): copy the
   skeleton, fill the sections.
4. **Finish with the completeness checklist** (`references/completeness.md`) —
   prove nothing was forgotten.
5. **Size the effort** (`references/levels.md`, optional): L1 minimal for small
   projects, L2 canonical, L3 hard per-profile layouts for large systems.
6. If auditing an existing project: first map what exists, then fill gaps in
   catalog order (see `references/project-docs.md` → map rule).

## Two golden rules (from example monorepo)

1. **Machine truth before code.** Contracts/OpenAPI/events (anything that *is* the
   interface) are written **before** implementation. Code implements the contract,
   not the other way around.
2. **The map comes last.** `REFERENCE.md` (the documentation map) is written last,
   because it describes everything above it. Writing it forces you to verify the
   whole set is consistent.

## References index

| File | Purpose |
|------|---------|
| `references/product-docs.md` | Product branch: VISION/PRD/ROADMAP/FEATURES — why, order, links |
| `references/project-docs.md` | Project branch: engineering docs, contracts, the map rule |
| `references/order.md` | Fill order: phases from idea to complete set |
| `references/completeness.md` | Checklist: «nothing forgotten» before delivery |
| `references/levels.md` | (Reference) L1/L2/L3 + profile layouts for large systems |
| `templates/product/*.tmpl` | Skeletons: VISION, PRD, ROADMAP |
| `templates/project/*.tmpl` | Skeletons: README, ARCHITECTURE, ADR, SAGA, TEST_CASES, DEV_GUIDE, IMPROVEMENTS, TROUBLESHOOTING, BACKLOG, REVIEW, STATUS, REFERENCE, ENTRY, FEATURES |
| `examples/example-monorepo/` | Real-world canonical reference (example monorepo) |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [bestdeejay-design](https://github.com/bestdeejay-design)
- **Source:** [bestdeejay-design/agent-skills](https://github.com/bestdeejay-design/agent-skills)
- **License:** MIT
- **Homepage:** https://bestdeejay-design.github.io/agent-skills/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-bestdeejay-design-agent-skills-docs-system
- Seller: https://agentstack.voostack.com/s/bestdeejay-design
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.