Skip to content

Commit edd2587

Browse files
nullhacknullhack
committed
chore(release): bump version to v6.1.20260419 - Contextual Ambystoma
1 parent 2c57611 commit edd2587

File tree

18 files changed

+476
-609
lines changed

18 files changed

+476
-609
lines changed

‎.opencode/skills/create-skill/SKILL.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,5 +141,6 @@ Add the skill name to the agent's "Available Skills" section so the agent knows
141141
| `code-quality` | software-engineer | Quick reference — redirects to verify |
142142
| `pr-management` | software-engineer | Step 5: create PR with squash merge |
143143
| `git-release` | software-engineer | Step 5: calver versioning and release |
144+
| `living-docs` | product-owner | Step 5 (after acceptance) + on stakeholder demand: C4 diagrams + glossary |
144145
| `create-skill` | software-engineer | Create new skills |
145146
| `create-agent` | human-user | Create new agents with research-backed design |

‎.opencode/skills/implementation/SKILL.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -44,9 +44,10 @@ Design correctness is far more important than lint/pyright/coverage compliance.
4444
### Read Phase (all before writing anything)
4545

4646
1. Read `docs/discovery.md` (project-level synthesis changelog) and optionally `docs/discovery_journal.md` (Q&A history for context)
47-
2. Read **ALL** `.feature` files in `docs/features/backlog/` (discovery + entities sections)
48-
3. Read in-progress `.feature` file (full: Rules + Examples + @id)
49-
4. Read **ALL** existing `.py` files in `<package>/` — understand what already exists before adding anything
47+
2. Read `docs/glossary.md` if it exists — use existing domain terms when naming classes, methods, and modules; do not invent synonyms for terms already defined
48+
3. Read **ALL** `.feature` files in `docs/features/backlog/` (discovery + entities sections)
49+
4. Read in-progress `.feature` file (full: Rules + Examples + @id)
50+
5. Read **ALL** existing `.py` files in `<package>/` — understand what already exists before adding anything
5051

5152
### Domain Analysis
5253

‎.opencode/skills/living-docs/SKILL.md‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
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

‎.opencode/skills/scope/SKILL.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -143,7 +143,7 @@ If a feature is new (just created as a stub): write its initial description now.
143143
After all `.feature` files are updated, append one `## Session: YYYY-MM-DD` block to `docs/discovery.md`. The block contains:
144144
- `### Feature List` — which features were added or changed (0–N entries); if nothing changed, write "No changes"
145145
- `### Domain Model` — new or updated domain entities and verbs; if nothing changed, write "No changes"
146-
- `### Scope` (first session only) — 3–5 sentence synthesis of who the users are, what the product does, why it exists, success/failure conditions, and explicit out-of-scope
146+
- `### Context` (first session only) — 3–5 sentence synthesis of who the users are, what the product does, why it exists, success/failure conditions, and explicit out-of-scope
147147

148148
**Step D — Mark session complete**
149149

@@ -429,7 +429,7 @@ Rules:
429429

430430
## Session: YYYY-MM-DD
431431

432-
### Scope
432+
### Context
433433
<3–5 sentence synthesis of who the users are, what the product does, why it exists,
434434
success/failure conditions, and out-of-scope boundaries.>
435435
(First session only. Omit this subsection in subsequent sessions.)

‎AGENTS.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ STEP 5: ACCEPT (product-owner) → demo, validate, move .feature to com
6060
| `code-quality` | software-engineer | pre-handoff (redirects to `verify`) |
6161
| `pr-management` | software-engineer | 5 |
6262
| `git-release` | software-engineer | 5 |
63+
| `living-docs` | product-owner | 5 (after acceptance) + on stakeholder demand |
6364
| `create-skill` | software-engineer | meta |
6465
| `create-agent` | human-user | meta |
6566

@@ -117,6 +118,10 @@ docs/
117118
discovery_journal.md ← raw Q&A, PO appends after every session
118119
discovery.md ← synthesis changelog, PO appends after every session
119120
architecture.md ← all architectural decisions, SE appends after Step 2
121+
glossary.md ← living glossary, PO updates via living-docs skill
122+
c4/
123+
context.md ← C4 Level 1 diagram, PO updates via living-docs skill
124+
container.md ← C4 Level 2 diagram, PO updates via living-docs skill
120125
features/
121126
backlog/<feature-name>.feature ← narrative + Rules + Examples
122127
in-progress/<feature-name>.feature
@@ -230,7 +235,7 @@ Use `@software-engineer /skill git-release` for the full release process. When r
230235

231236
Every session: load `skill session-workflow`. Read `TODO.md` first, update it at the end.
232237

233-
`TODO.md` is a session bookmark — not a project journal. See `docs/workflow.md` for the full structure including the Cycle State block used during Step 3.
238+
`TODO.md` is a session bookmark — not a project journal. See `.opencode/skills/session-workflow/SKILL.md` for the full structure including the Cycle State block used during Step 3.
234239

235240
## Setup
236241

‎CHANGELOG.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,29 @@
22

33
All notable changes to this template will be documented in this file.
44

5+
## [v6.1.20260419] - Contextual Ambystoma - 2026-04-19 (hotfix)
6+
7+
### Added
8+
- **living-docs skill**: new PO skill for generating C4 architecture diagrams (`docs/c4/context.md`, `docs/c4/container.md`) and maintaining the living glossary (`docs/glossary.md`) after each feature acceptance (Step 5) or on stakeholder demand
9+
- **docs/c4/**: new directory for C4 Level 1 (Context) and Level 2 (Container) Mermaid diagrams; placeholder `.gitkeep` added
10+
- **docs/glossary.md**: new living glossary file owned by `living-docs` skill (PO); terms sourced from completed feature files, `docs/discovery.md` Domain Model, and `docs/architecture.md` decisions
11+
- **Scientific research — documentation.md**: new file with 4 entries (#59–62): Ko et al. 2007 (information needs), Winters et al. 2020 (docs-as-code), Procida 2021 (Diátaxis framework), Allspaw 2012 (blameless post-mortems)
12+
- **Scientific research — domain-modeling.md**: 6 new DDD entries (#63–68): Evans DDD Reference CC-BY, Fowler UbiquitousLanguage bliki, Fowler BoundedContext bliki, Vernon IDDD, Verraes "UL is not a glossary", Evans Whirlpool process
13+
- **Scientific research — architecture.md**: 4 new entries (#55–58): Nygard ADRs, Kruchten 4+1 View Model, Brown C4 Model, Parnas information hiding
14+
15+
### Changed
16+
- **discovery.md template**: `### Scope` section renamed to `### Context` — the section is a session-level general-context synthesis, not a complete project scope definition
17+
- **scope/SKILL.md**: updated `### Scope` references to `### Context` in Step C instructions and template block
18+
- **living-docs/SKILL.md**: glossary entry format updated — `**Context:**` renamed to `**Bounded context:**` (mandatory for multi-context projects); `Domain Event` added as a distinct Type value; secondary-artifact note added to preamble; source-traceability rule replaces "do not invent" rule; checklist updated accordingly
19+
- **implementation/SKILL.md**: Step 2 Read Phase now includes `docs/glossary.md` as item 2 — SE reads existing domain terms before naming classes, methods, and modules to avoid inventing synonyms
20+
- **create-skill/SKILL.md**: `living-docs` added to available skills table
21+
- **AGENTS.md**: skills table updated with `living-docs`; filesystem structure section updated (`docs/c4/`, `docs/glossary.md` added; `docs/architecture/` subtree removed; TODO.md reference updated)
22+
23+
### Removed
24+
- **docs/architecture/**: folder deleted; the ADR log lives at `docs/architecture.md` (SE-owned); the old `adr-template.md` inside the folder was redundant
25+
- **docs/workflow.md**: deleted; canonical workflow reference is `AGENTS.md` and the skills under `.opencode/skills/`
26+
- **Dockerfile / docker-compose.yml**: removed as unused template artifacts
27+
528
## [v6.0.20260419] - Declarative Nautilus - 2026-04-19
629

730
### Added

‎Dockerfile‎

Lines changed: 0 additions & 51 deletions
This file was deleted.

0 commit comments

Comments
 (0)