Decisions
- Pending: Auto-generate on merge or on-demand?
- Pending: Doc format — markdown in vault or standalone site?
- Pending: Which docs to generate — API, architecture, user guide, or all?
User Tasks
Summary
Automatically generate and maintain documentation from code, vault structure, and FR history — keeping docs in sync with the actual system.
Problem / Motivation
- As src/ grows, there’s no automatic documentation of modules, APIs, or architecture.
- Vault structure and conventions are documented in CLAUDE.md but become stale as the system evolves.
- The orchestrator (FR-056) can ship code autonomously, but nobody updates the docs — they drift immediately.
- External project support (FR-065) means onboarding docs are needed for each project.
- Manual documentation is the first thing to be skipped under time pressure.
Proposed Solution
A /docs skill and a post-merge pipeline step that generates documentation from: (1) Python docstrings/type hints → API docs, (2) vault structure → system docs, (3) FR history → changelog/release notes. Output goes to vault/00_system/docs/generated/.
Open Questions
1. Documentation Scope
Question: What types of documentation should be generated?
| Option | Description |
|---|---|
| A) API + Architecture + Changelog | Code docs + system overview + what changed |
| B) API only | Just code documentation |
| C) Everything including user guide | Full documentation suite |
Recommendation: Option A — covers the three most likely to drift.
Decision:
2. Generation Tooling
Question: What tools should generate the docs?
| Option | Description |
|---|---|
| A) LLM-generated from source | Claude reads code/vault and writes markdown docs |
| B) Traditional tools | Sphinx/mkdocs for Python, custom scripts for vault |
| C) Hybrid | Traditional tools for API, LLM for architecture/changelog |
Recommendation: Option C — use proven tools where they exist (Sphinx/mkdocs for API docs), LLM for narrative docs that need judgment.
Decision:
3. Trigger
Question: When should docs be regenerated?
| Option | Description |
|---|---|
| A) Post-merge + on-demand | Auto-update after PR merge, /docs for manual |
| B) On-demand only | User/orchestrator runs /docs when needed |
| C) Continuous | Watch for changes, regenerate affected docs |
Recommendation: Option A — auto after merge catches drift, on-demand for ad-hoc.
Decision:
Phase Overview
| Phase | Description | Status |
|---|---|---|
| Phase 1 | /docs skill — generate API docs from Python code | — |
| Phase 2 | Architecture doc generation from vault structure | — |
| Phase 3 | Auto-trigger on merge + changelog from FR history | — |
Phase 1: API Documentation —
Goal: Generate Python API documentation from docstrings and type hints.
| File / Feature | Details | Owner | Status |
|---|---|---|---|
.claude/skills/docs/SKILL.md | /docs skill definition | opus | — |
vault/00_system/docs/generated/api/ | Output directory for API docs | opus | — |
| Tool selection | mkdocs + mkdocstrings or Sphinx + autodoc | opus | — |
pyproject.toml update | Add docs dependencies | opus | — |
| Module index | Auto-generated index of all src/opus/ modules | opus | — |
Phase 2: Architecture Documentation —
Goal: Generate system architecture docs from vault structure and CLAUDE.md.
| File / Feature | Details | Owner | Status |
|---|---|---|---|
vault/00_system/docs/generated/architecture.md | Auto-generated architecture overview | opus | — |
| Vault structure scanner | Read directory tree, generate structure doc | opus | — |
| Component diagram | Mermaid diagram of system components | opus | — |
| Skill/hook/agent inventory | Auto-generated list of all configured skills, hooks, agents | opus | — |
Phase 3: Auto-Trigger & Changelog —
Goal: Auto-regenerate docs after merges and generate changelogs from FR history.
| File / Feature | Details | Owner | Status |
|---|---|---|---|
| Post-merge hook | Trigger doc regeneration after PR merge | opus | — |
| Changelog generator | Parse done/ FRs → generate changelog grouped by date/phase | opus | — |
vault/00_system/docs/generated/changelog.md | Auto-generated changelog | opus | — |
| Orchestrator integration | FR-056 pipeline includes doc-update step after merge | opus | — |
Test
Manual tests
| Test | Expected | Actual | Last |
|---|---|---|---|
| Merge PR, verify auto-trigger | Docs regenerated automatically | pending | - |
| Check changelog after completing FR | FR appears in changelog | pending | - |
AI-verified tests
| Scenario | Expected behavior | Verification method |
|---|---|---|
| … | … | … |
E2E tests
| Scenario | Assertion |
|---|---|
| … | … |
Integration tests
| Component | Coverage |
|---|---|
| … | … |
Unit tests
| Component | Tests | Coverage |
|---|---|---|
| … | … | … |
History
| Date | Event | Details |
|---|---|---|
| 2026-03-12 | Created | Identified as gap for autonomous coding agency |
References
- FR-056 (Autonomous Coding Orchestrator) — doc-update as pipeline step
- FR-015 (Python Project Scaffold) — pyproject.toml setup for doc tools
- FR-042 (Session Changelog) — per-session logs, this FR covers release-level changelog
- FR-065 (Multi-Repo) — external projects need onboarding docs
- FR-048 (Workflow Documentation) — manual docs, this FR auto-generates