|
| 1 | +--- |
| 2 | +name: living-docs |
| 3 | +description: Generate and update C4 architecture diagrams and the living glossary from existing project docs |
| 4 | +version: "1.0" |
| 5 | +author: product-owner |
| 6 | +audience: product-owner |
| 7 | +workflow: feature-lifecycle |
| 8 | +--- |
| 9 | + |
| 10 | +# Living Docs |
| 11 | + |
| 12 | +This skill generates and updates two living documents after a feature is accepted (Step 5) or on stakeholder request: the **C4 architecture diagrams** and the **living glossary**. Both are derived from existing project documentation — no new decisions are made. |
| 13 | + |
| 14 | +The glossary is a secondary artifact derived from the code, the domain model, and domain-expert conversations. The canonical sources are the completed feature files, the discovery synthesis, and the architectural decisions. The glossary is a human-readable projection of those sources — not an independent authority. |
| 15 | + |
| 16 | +## When to Use |
| 17 | + |
| 18 | +- **PO at Step 5** — after the feature is accepted and moved to `completed/`, run this skill to reflect the new feature in C4 diagrams and glossary. |
| 19 | +- **Stakeholder on demand** — when the stakeholder asks "what does the system look like?" or "what does term X mean in this context?". |
| 20 | + |
| 21 | +## Ownership Rules |
| 22 | + |
| 23 | +| Document | Created/Updated by | Inputs read | |
| 24 | +|---|---|---| |
| 25 | +| `docs/c4/context.md` | `living-docs` skill (PO) | `docs/discovery.md`, `docs/features/completed/` | |
| 26 | +| `docs/c4/container.md` | `living-docs` skill (PO) | `docs/architecture.md`, `docs/features/completed/` | |
| 27 | +| `docs/glossary.md` | `living-docs` skill (PO) | `docs/discovery.md`, `docs/glossary.md` (existing), `docs/architecture.md`, `docs/features/completed/` | |
| 28 | +| `docs/architecture.md` | SE only (Step 2) | — | |
| 29 | +| `docs/discovery.md` | PO only (Step 1) | — | |
| 30 | + |
| 31 | +**Never edit `docs/architecture.md` or `docs/discovery.md` in this skill.** Those files are append-only by their respective owners. This skill reads them; it never writes to them. |
| 32 | + |
| 33 | +--- |
| 34 | + |
| 35 | +## Step 1 — Read Phase (all before writing anything) |
| 36 | + |
| 37 | +Read in this order: |
| 38 | + |
| 39 | +1. `docs/discovery.md` — project scope, domain model (nouns/verbs), feature list per session |
| 40 | +2. `docs/features/completed/` — all completed `.feature` files (full text: Rules, Examples, Constraints) |
| 41 | +3. `docs/architecture.md` — all architectural decisions (containers, modules, protocols, external deps) |
| 42 | +4. `docs/c4/` — existing C4 diagrams if they exist (update, do not replace from scratch) |
| 43 | +5. `docs/glossary.md` — existing glossary if it exists (extend, never remove existing entries) |
| 44 | + |
| 45 | +Identify from the read phase: |
| 46 | + |
| 47 | +- **Actors** — named human roles from feature `As a <role>` clauses and discovery Scope section |
| 48 | +- **External systems** — any system outside the package boundary named in features or architecture decisions |
| 49 | +- **Containers** — deployable/runnable units identified in `docs/architecture.md` (Hexagonal adapters, CLIs, services) |
| 50 | +- **Key domain terms** — all nouns from `docs/discovery.md` Domain Model tables, plus any terms defined in `docs/architecture.md` decisions |
| 51 | + |
| 52 | +--- |
| 53 | + |
| 54 | +## Step 2 — Update C4 Context Diagram (Level 1) |
| 55 | + |
| 56 | +File: `docs/c4/context.md` |
| 57 | + |
| 58 | +The Context diagram answers: **who uses the system and what external systems does it interact with?** |
| 59 | + |
| 60 | +Use Mermaid `C4Context` syntax. Template: |
| 61 | + |
| 62 | +```markdown |
| 63 | +# C4 — System Context |
| 64 | + |
| 65 | +> Last updated: YYYY-MM-DD |
| 66 | +> Source: docs/discovery.md, docs/features/completed/ |
| 67 | +
|
| 68 | +```mermaid |
| 69 | +C4Context |
| 70 | + title System Context — <project-name> |
| 71 | +
|
| 72 | + Person(actor1, "<role name>", "<one-line description from feature As a clauses>") |
| 73 | +
|
| 74 | + System(system, "<project-name>", "<3–5 word system description from discovery.md Scope>") |
| 75 | +
|
| 76 | + System_Ext(ext1, "<external system name>", "<what it provides>") |
| 77 | +
|
| 78 | + Rel(actor1, system, "<verb from When clause>") |
| 79 | + Rel(system, ext1, "<verb from architecture.md decision>") |
| 80 | +``` |
| 81 | +``` |
| 82 | + |
| 83 | +Rules: |
| 84 | +- One `Person(...)` per distinct actor found in completed feature files |
| 85 | +- One `System_Ext(...)` per external dependency identified in `docs/architecture.md` decisions |
| 86 | +- Relationships (`Rel`) use verb phrases from feature `When` clauses or architecture decision labels |
| 87 | +- If no external systems are identified in `docs/architecture.md`, omit `System_Ext` entries |
| 88 | +- If the file already exists: update only — add new actors/systems, update relationship labels. Never remove an existing entry unless the feature it came from has been explicitly superseded |
| 89 | + |
| 90 | +--- |
| 91 | + |
| 92 | +## Step 3 — Update C4 Container Diagram (Level 2) |
| 93 | + |
| 94 | +File: `docs/c4/container.md` |
| 95 | + |
| 96 | +The Container diagram answers: **what are the major runnable/deployable units and how do they communicate?** |
| 97 | + |
| 98 | +Only generate this diagram if `docs/architecture.md` contains at least one decision identifying a distinct container boundary (e.g., a CLI entry point separate from a library, a web server, a background worker, an external service adapter). If the project is a single-container system, note this in the file and skip the diagram body. |
| 99 | + |
| 100 | +Use Mermaid `C4Container` syntax. Template: |
| 101 | + |
| 102 | +```markdown |
| 103 | +# C4 — Container Diagram |
| 104 | + |
| 105 | +> Last updated: YYYY-MM-DD |
| 106 | +> Source: docs/architecture.md |
| 107 | +
|
| 108 | +```mermaid |
| 109 | +C4Container |
| 110 | + title Container Diagram — <project-name> |
| 111 | +
|
| 112 | + Person(actor1, "<role>", "") |
| 113 | +
|
| 114 | + System_Boundary(sys, "<project-name>") { |
| 115 | + Container(container1, "<name>", "<technology>", "<responsibility from architecture.md>") |
| 116 | + Container(container2, "<name>", "<technology>", "<responsibility>") |
| 117 | + } |
| 118 | +
|
| 119 | + System_Ext(ext1, "<external system>", "") |
| 120 | +
|
| 121 | + Rel(actor1, container1, "<action>") |
| 122 | + Rel(container1, container2, "<protocol or method>") |
| 123 | + Rel(container1, ext1, "<protocol>") |
| 124 | +``` |
| 125 | +``` |
| 126 | + |
| 127 | +Rules: |
| 128 | +- Container names and responsibilities come directly from `docs/architecture.md` decisions — do not invent them |
| 129 | +- Technology labels come from `pyproject.toml` dependencies when identifiable (e.g., "Python / fire CLI", "Python / FastAPI") |
| 130 | +- If the file already exists: update incrementally — do not regenerate from scratch |
| 131 | + |
| 132 | +--- |
| 133 | + |
| 134 | +## Step 4 — Update Living Glossary |
| 135 | + |
| 136 | +File: `docs/glossary.md` |
| 137 | + |
| 138 | +The glossary answers: **what does each domain term mean in this project's context?** |
| 139 | + |
| 140 | +### Format |
| 141 | + |
| 142 | +```markdown |
| 143 | +# Glossary — <project-name> |
| 144 | + |
| 145 | +> Living document. Updated after each completed feature by the `living-docs` skill. |
| 146 | +> Source: docs/discovery.md (Domain Model), docs/features/completed/, docs/architecture.md |
| 147 | +
|
| 148 | +--- |
| 149 | + |
| 150 | +## <Term> |
| 151 | + |
| 152 | +**Type:** Noun | Verb | Domain Event | Concept | Role | External System |
| 153 | + |
| 154 | +**Definition:** <one sentence, plain English, no jargon> |
| 155 | + |
| 156 | +**Bounded context:** <name of the bounded context where this term is defined; required when the project has more than one bounded context; omit only for single-context projects> |
| 157 | + |
| 158 | +**First appeared:** <YYYY-MM-DD discovery session or feature name> |
| 159 | + |
| 160 | +--- |
| 161 | +``` |
| 162 | + |
| 163 | +### Rules |
| 164 | + |
| 165 | +- Extract all nouns and verbs from every `### Domain Model` table in `docs/discovery.md` |
| 166 | +- Extract all roles from `As a <role>` clauses in completed `.feature` files |
| 167 | +- Extract all external system names from `docs/architecture.md` decisions |
| 168 | +- Extract any term defined or clarified in architectural decision `Reason:` fields |
| 169 | +- **Do not remove existing glossary entries** — if a term's meaning has changed, add a `**Superseded by:**` line pointing to the new entry and write a new entry |
| 170 | +- **Every term must have a traceable source** — completed feature files or `docs/architecture.md` decisions. If a term appears in sources but is never defined, write `Definition: Term appears in [source] but has not been explicitly defined.` Do not invent a definition. |
| 171 | +- Terms are sorted alphabetically within the file |
| 172 | + |
| 173 | +### Merge with existing glossary |
| 174 | + |
| 175 | +If `docs/glossary.md` already exists: |
| 176 | +1. Read all existing entries |
| 177 | +2. For each new term found in sources: check if it already exists in the glossary |
| 178 | + - Exists, definition unchanged → skip |
| 179 | + - Exists, definition changed → append `**Superseded by:** <new-term-or-date>` to old entry; write new entry |
| 180 | + - Does not exist → append new entry in alphabetical order |
| 181 | + |
| 182 | +--- |
| 183 | + |
| 184 | +## Step 5 — Commit |
| 185 | + |
| 186 | +After both C4 diagrams and glossary are updated: |
| 187 | + |
| 188 | +``` |
| 189 | +docs(living-docs): update C4 and glossary after <feature-name> |
| 190 | +``` |
| 191 | + |
| 192 | +If this is a stakeholder-requested update without a specific feature trigger: |
| 193 | + |
| 194 | +``` |
| 195 | +docs(living-docs): refresh C4 diagrams and glossary |
| 196 | +``` |
| 197 | + |
| 198 | +--- |
| 199 | + |
| 200 | +## Checklist |
| 201 | + |
| 202 | +- [ ] Read all five source files before writing anything |
| 203 | +- [ ] Context diagram reflects all actors from completed feature files |
| 204 | +- [ ] Context diagram reflects all external systems from `docs/architecture.md` |
| 205 | +- [ ] Container diagram present only if multi-container architecture confirmed in `docs/architecture.md` |
| 206 | +- [ ] Glossary contains all nouns and verbs from `docs/discovery.md` Domain Model tables |
| 207 | +- [ ] No existing glossary entry removed |
| 208 | +- [ ] Every new term has a traceable source in completed feature files or `docs/architecture.md`; no term is invented |
| 209 | +- [ ] No edits made to `docs/architecture.md` or `docs/discovery.md` |
| 210 | +- [ ] Committed with `docs(living-docs): ...` message |
0 commit comments