Skill · Version 1.0.0

Documentation blueprint

Assigns verified project knowledge a clear home while preserving an existing documentation structure.

documentation-blueprint

Team members using this skill

AgentCleo

When is it useful?

Use when project instructions are scattered or contributors cannot distinguish product requirements from implementation details.

What does it help you do?

Maps product, architecture, development, data, API and operational topics to canonical documents.
Creates feature documentation only when it contains verified useful information.
Connects entry-point guidance to detailed references without duplicating facts.

Try asking this

Organize our existing documentation and show where onboarding, access rules, deployment and one complete feature description should live. Choose one existing feature as the model and link its setup, API and operational details. Assign each fact one maintained location rather than duplicate copies.

Detailed documentation

Read the skill’s original instructions, examples and checks in their authored language.

Details…Show less

Documentation Blueprint

Give every fact one home, so an agent finds what to build, how it works now and which rules hold. When the project already has a documentation layout, keep it and map these roles onto its files.

1. Where each fact lives

File	Owns
`README.md`	What the project is, how to start it, links to the rest
`docs/product.md`	Audience, problem, main capabilities, business rules, what is out of scope
`docs/architecture.md`	Modules, technologies, data flow, external dependencies
`docs/development.md`	Environment, install, configuration by variable name (never values), commands, coding conventions
`docs/design.md`	Colors, logos, typography, spacing, radii, backgrounds, components, responsive rules
`docs/data-model.md`	Entities, relations, field meaning, constraints, migration rules
`docs/api.md`	Endpoints, authentication, request and response formats, errors, webhooks, versioning
`docs/security.md`	Roles, permissions, tenant and project data isolation, secrets, sensitive data
`docs/testing.md`	Test commands, critical flows, test data, when a task counts as done
`docs/deployment.md`	Environments, build, release, database migration, domains, configuration, rollback
`docs/operations.md`	Logs, monitoring, background jobs, backup, restore, common failures
`docs/decisions/NNNN-title.md`	One decision each (see documentation-and-adrs)
`docs/features/<feature>.md`	One feature each (section 2)

Create a file when it has verified content. A young project starts with README.md, AGENTS.md and its first feature documents.
A fact whose owner file exists is linked from other documents, never copied into them.
Until the owner file exists, the feature document holds the fact and notes where it moves (Moves to docs/api.md); move it when that file is created.
Reference the code can produce (OpenAPI schema, schema dump, CLI help) comes from its generator: link the output and the command. Hand-written text explains meaning, rules and reasons.

2. Feature document

# <Feature>
Status: implemented | partly implemented | planned
Last verified: YYYY-MM-DD against <commit or branch>

## What it does
## Business rules
## States and transitions
## Edge cases and limits
## Acceptance criteria
## Planned changes
## Open questions
## Related
- API: [api.md#<anchor>](../api.md#<anchor>)
- Data model: [data-model.md#<anchor>](../data-model.md#<anchor>)
- UI components: `path/to/component`
- Code and tests: `path/to/file`, `path/to/test`

Status, Last verified and Related are required.
Each section ends with a Sources: line of repository paths it was checked against.
Acceptance criteria are observable checks taken from tests or the accepted spec, each with its source. A criterion no test covers ends with (not covered by a test).
States and transitions lists each transition with its trigger. An unknown trigger is Unknown, needs <role>, not a guess.
Planned changes holds accepted specs and roadmap items the code does not run yet, linked. An accepted spec is not proof the feature works.

3. Verification dates

Last verified changes only after re-checking the content against the code, never for wording edits.
Write the date of the check and the commit or branch you checked. A claim you could not check is marked Unverified.

4. The documentation section of AGENTS.md

Add one ## Documentation section or update the existing one; leave the file's other rules as they are. Name only files that exist and commands from the manifests:

## Documentation
| Before you | Read |
|---|---|
| Plan or change a feature | `docs/features/<feature>.md`, `docs/product.md` |
| Add a module or dependency | `docs/architecture.md` |
| Change endpoints, data or permissions | `docs/api.md`, `docs/data-model.md`, `docs/security.md` |

- Checks: `<test command>`, `<lint command>`, `<docs generator command>`.
- Current and planned stay apart: specs in `<spec folder>` describe work the code does not run yet.
- A task is done when the documents its change touches are updated in the same change, with a new Last verified line.

Before you finish

Every fact has one owner file; others link to it.
Each feature document has Status, Last verified, Related and per-section Sources.
Acceptance criteria and transitions name their source or are marked unknown.
Planned work sits under Planned changes, not under What it does.
AGENTS.md has one Documentation section: read-before table, checks, done rule.

Included files 1

SKILL.md