133 lines
5.2 KiB
Markdown
133 lines
5.2 KiB
Markdown
# Documentation Standard (MANDATORY)
|
|
|
|
This guide defines REQUIRED documentation behavior for all Mosaic projects.
|
|
If code, API contracts, auth, or infrastructure changes, documentation updates are REQUIRED before completion.
|
|
|
|
## Hard Rules
|
|
|
|
1. Documentation is a delivery gate. Missing required documentation is a BLOCKER.
|
|
2. `docs/PRD.md` or `docs/PRD.json` is REQUIRED as the project requirements source before coding begins.
|
|
3. API documentation is OpenAPI-first. `docs/API/OPENAPI.yaml` (or `.json`) is the canonical API contract.
|
|
4. Public and private/internal endpoints MUST be documented.
|
|
5. API input and output schemas MUST be documented.
|
|
6. API authentication and permissions MUST be documented per endpoint.
|
|
7. A current site map MUST exist at `docs/SITEMAP.md`.
|
|
8. Documentation updates MUST be committed in the same logical change set as the code/API change.
|
|
9. Generated publishing output (Docusaurus/VitePress/MkDocs artifacts) is not canonical unless the project explicitly declares it canonical.
|
|
10. `docs/` root MUST stay clean. Reports and working artifacts MUST be stored in dedicated subdirectories, not dumped at `docs/` root.
|
|
|
|
## Required Documentation Structure
|
|
|
|
```text
|
|
docs/
|
|
PRD.md (or PRD.json)
|
|
TASKS.md (active orchestrator tracking, when orchestrator is used)
|
|
SITEMAP.md
|
|
USER-GUIDE/
|
|
ADMIN-GUIDE/
|
|
DEVELOPER-GUIDE/
|
|
API/
|
|
OPENAPI.yaml
|
|
ENDPOINTS.md
|
|
scratchpads/
|
|
reports/
|
|
tasks/
|
|
releases/
|
|
templates/ (optional)
|
|
```
|
|
|
|
Minimum requirements:
|
|
|
|
- `docs/PRD.md` or `docs/PRD.json`: authoritative requirements source for implementation and testing.
|
|
- `docs/USER-GUIDE/`: End-user workflows, feature behavior, common troubleshooting.
|
|
- `docs/ADMIN-GUIDE/`: Configuration, deployment, operations, incident/recovery procedures.
|
|
- `docs/DEVELOPER-GUIDE/`: Architecture, local setup, contribution/testing workflow, design constraints.
|
|
- `docs/API/OPENAPI.yaml`: API SSOT for all HTTP endpoints.
|
|
- `docs/API/ENDPOINTS.md`: Human-readable index for API endpoints, permissions, and change notes.
|
|
- `docs/SITEMAP.md`: Navigation index for all user/admin/developer/API documentation pages.
|
|
- `docs/reports/`: Review outputs, QA automation reports, deferrals, and audit artifacts.
|
|
- `docs/tasks/`: Archived task snapshots and orchestrator learnings.
|
|
- `docs/releases/`: Release notes and release-specific documentation.
|
|
- `docs/scratchpads/`: Active task-level working notes.
|
|
|
|
## Root Hygiene Rule (MANDATORY)
|
|
|
|
Allowed root documentation files are intentionally limited:
|
|
|
|
1. `docs/PRD.md` or `docs/PRD.json`
|
|
2. `docs/TASKS.md` (active milestone only, when task orchestration is in use)
|
|
3. `docs/SITEMAP.md`
|
|
4. `docs/README.md` (optional index)
|
|
|
|
All other docs MUST be placed in scoped folders (`docs/reports/`, `docs/tasks/`, `docs/releases/`, `docs/scratchpads/`, `docs/API/`, guide books).
|
|
|
|
## Artifact Placement Rules
|
|
|
|
| Artifact Type | REQUIRED Location |
|
|
|---|---|
|
|
| Code review reports, QA reports, audits | `docs/reports/<category>/` |
|
|
| Deferred error lists / unresolved findings | `docs/reports/deferred/` |
|
|
| Archived milestone task snapshots | `docs/tasks/` |
|
|
| Orchestrator learnings JSON | `docs/tasks/orchestrator-learnings.json` |
|
|
| Release notes | `docs/releases/` |
|
|
| Active scratchpads | `docs/scratchpads/` |
|
|
|
|
## API Documentation Contract (OpenAPI-First)
|
|
|
|
For every API endpoint, documentation MUST include:
|
|
|
|
1. visibility: `public` or `private/internal`
|
|
2. method and path
|
|
3. endpoint purpose
|
|
4. request/input schema
|
|
5. response/output schema(s)
|
|
6. auth method and required permission/role/scope
|
|
7. error status codes and behavior
|
|
|
|
If OpenAPI cannot fully express an internal constraint, document it in `docs/API/ENDPOINTS.md`.
|
|
|
|
## Book/Chapter/Page Structure
|
|
|
|
Use this structure for every guide:
|
|
|
|
1. Book: one root guide folder (`USER-GUIDE`, `ADMIN-GUIDE`, `DEVELOPER-GUIDE`)
|
|
2. Chapter: one subdirectory per topic area
|
|
3. Page: one focused markdown file per concern
|
|
|
|
Required index files:
|
|
|
|
1. `docs/USER-GUIDE/README.md`
|
|
2. `docs/ADMIN-GUIDE/README.md`
|
|
3. `docs/DEVELOPER-GUIDE/README.md`
|
|
|
|
Each index file MUST link to all chapters and pages in that book.
|
|
|
|
## Situational Documentation Matrix
|
|
|
|
| Change Surface | REQUIRED Documentation Updates |
|
|
|---|---|
|
|
| New feature or behavior change | User guide + developer guide + sitemap |
|
|
| API endpoint added/changed/removed | OpenAPI + API endpoint index + sitemap |
|
|
| Auth/RBAC/permission change | API auth/permission docs + admin guide + developer guide |
|
|
| Database schema/migration change | Developer guide + admin operational notes if runbook impact |
|
|
| CI/CD or deployment change | Admin guide + developer guide |
|
|
| Incident, recovery, or security control change | Admin guide runbook + security notes + sitemap |
|
|
|
|
## Publishing Target Rule (MANDATORY)
|
|
|
|
If the user does not specify documentation publishing target, the agent MUST ask:
|
|
|
|
1. Publish in-app (embedded docs)
|
|
2. Publish on external docs platform (for example: Docusaurus, VitePress, MkDocs)
|
|
|
|
Default behavior before publishing decision:
|
|
|
|
- Keep canonical docs in-repo under `docs/`.
|
|
- Do not assume external publishing platform.
|
|
|
|
## Completion Gate
|
|
|
|
You MUST NOT declare completion until all required documentation updates are done.
|
|
|
|
Use `~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md` as the final gate.
|