// Documentation workflow. Use when: writing or updating README, generating project documentation, documenting architecture, documenting API endpoints, documenting infrastructure, producing technical or non-technical documentation.
| name | documentation |
| description | Documentation workflow. Use when: writing or updating README, generating project documentation, documenting architecture, documenting API endpoints, documenting infrastructure, producing technical or non-technical documentation. |
| argument-hint | Describe what to document (e.g. 'Update the README with the new API endpoints' or 'Regenerate the full README') |
| compatibility | opencode |
Produce or update README.md (or another specified doc file). Every fact comes from the codebase — nothing is invented.
- Use #tool:vscode/askQuestions if the scope (FULL vs. PARTIAL, target sections) is unclear before starting - Never invent details — every fact must come from Phase 2 codebase research; if a value is not found, write `N/A — not found in codebase` - Never leave placeholder sections — a section without real content is omitted entirely - For PARTIAL scope, only edit the named sections; preserve all other content byte-for-byte - Run a security scan before saving — remove any secret, private URL, account ID, or internal ARN - Use emojis sparingly in section headings (e.g. 🚀 Getting Started, 🛠️ Tech Stack) to improve visual scannability — never in tables or code blocks - Never edit any file other than the target documentation file ## Phase 1 — Scope AssessmentSecurity — non-negotiable: Documentation is public. Never include secrets, credentials, API keys, tokens, private URLs, internal IPs, account IDs, or private ARNs. Reference environment variable names only. When in doubt, omit.
FULL — regenerate or create from scratchPARTIAL — update only named sectionsPARTIAL, restrict all changes to the named sections only.Quality check:
FULL or PARTIALCollect all facts before writing a single line. If a project-specific source map exists at ./references/source-map.md, use it as the primary guide.
Read infrastructure config files (CDK stacks, Terraform, serverless). Record every cloud resource: name, type, purpose.
Read source files:
Read the build descriptor (build.gradle, package.json, etc.): dependencies, build commands, test commands.
Read local dev setup files (Docker Compose, SAM, scripts):
.example file, never the real env fileRead integration/E2E test files (Bruno .bru, Postman, OpenAPI) to confirm the real API surface:
Search for auth annotations, JWT filters, OIDC config, and security middleware. Note public vs. protected endpoints.
Quality check:
.example fileIf a project-specific section template exists at ./references/readme-sections.md, follow it. Otherwise use this default structure:
xml, or Mermaid in fenced mermaid) + proseAdd or remove sections based on what the project actually contains. Never add a section with no real content.
Core rules:
N/A — not found in codebasexml) or Mermaid (fenced mermaid); no empty diagramsbash blocks; every command must be directly runnableBefore saving, self-review:
.example fileQuality check:
## Documentation — Run Report
**Scope**: FULL | PARTIAL (<section names>)
**Outcome**: SUCCESS | PARTIAL SUCCESS | FAILURE
### Changes Made
| Section | Action |
|---|---|
| <Section Name> | Created / Updated / Unchanged / Removed |
### Gaps (sections with incomplete data)
| Section | Missing Information | Recommended Action |
|---|---|---|
| <Section Name> | <what was missing> | <what to provide> |