From 22b591ab3a634930010276412e3748319fdca3ff Mon Sep 17 00:00:00 2001 From: Dieter Baier Date: Mon, 31 Aug 2026 13:55:53 +0200 Subject: [PATCH 1/2] issue_80: Present the toolkit through capabilities MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A flat skill list explains the building blocks and hides the strongest claim: eight skills together already deliver an architecture-aware Spec-Driven Development workflow, and nothing in the README said so. The new section sits above everything else, because presentation was the problem. Each capability names the moment it starts from, the outcome, and the skills that collaborate — as navigation, never as a second copy of the rules. Two findings from validating the proposed map against the current skills: - Decision and Impact Management is a strict subset of Spec-Driven Development by membership. It is a real capability only when framed by entry point: a feature request versus an architecture question arriving on its own. Framed by skill list it would teach a distinction that does not exist. - Session Continuity is a group of its own. clock-in and clock-out are the only skills a user invokes by name, daily, and a feature view that omits them describes the toolkit as less usable than it is. presentation is named outside the map rather than stretched into a group it does not belong to. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01USXp58FoRppFK6FUht8K7u --- README.md | 112 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) diff --git a/README.md b/README.md index 0e1bac1..faf2667 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,115 @@ without making AI a required dependency. AI may suggest architecture artifacts and relationships, but the repository owns the truth. Reviewed metadata and source documents are the authoritative record. +## Capabilities + +A list of skills explains the building blocks. This explains what they add up +to: each capability names the moment it starts from, the outcome it produces, +and the canonical skills that collaborate to produce it. + +This section is **navigation, not rules**. Every rule lives in the linked skill +or contract, which stays the single source of truth; nothing here restates one. + +Underneath all of them: +[`skills/architecture-core`](/skills/architecture-core/SKILL.md) is the baseline +every architecture-sensitive task reads first, and +[`general-semantic-contracts.md`](general-semantic-contracts.md) is the +engine-agnostic contract it applies. + +### Architecture-aware Spec-Driven Development + +**Starts from** a feature request. **Produces** a specified, sliced, and +architecturally assessed change whose issues, behaviour spec, and architecture +documentation stay aligned as it is built. + +The toolkit's fullest capability, and the one no single skill shows: a feature +request is classified as an Epic or a reviewable UserStory, its intended value +expressed as a User Story, its new observable behaviour specified as +language-agnostic Gherkin bridged to automated verification, its impact on the +existing architecture analysed, the affected ADRs, quality scenarios, risks, +components, runtime and deployment views updated, and the work sliced into +reviewable issues — which then flow into *Reviewable Architecture Delivery* +below. + +[`architecture-impact`](/skills/architecture-impact/SKILL.md) · +[`bdd-specification`](/skills/bdd-specification/SKILL.md) · +[`slice-issues`](/skills/slice-issues/SKILL.md) · +[`adr`](/skills/adr/SKILL.md) · +[`quality-scenario`](/skills/quality-scenario/SKILL.md) · +[`risk`](/skills/risk/SKILL.md) · +[`traceability-review`](/skills/traceability-review/SKILL.md) + +### Architecture Decision and Impact Management + +**Starts from** an architecture question arriving on its own — a constraint that +changed, a risk that surfaced, a decision worth revisiting. **Produces** a +recorded decision with its impact traced through the affected artifacts. + +The same skills as above serve a different entry point here, and the difference +is the trigger rather than the toolkit: no feature request, no behaviour to +specify, no slicing — an architecture concern that must be assessed, decided, +and linked. + +[`architecture-impact`](/skills/architecture-impact/SKILL.md) · +[`adr`](/skills/adr/SKILL.md) · +[`quality-scenario`](/skills/quality-scenario/SKILL.md) · +[`risk`](/skills/risk/SKILL.md) · +[`traceability-review`](/skills/traceability-review/SKILL.md) + +### Domain Discovery and Domain Modeling + +**Starts from** a vague plan or an unsettled vocabulary. **Produces** a +sharpened domain model, a glossary that survives contact with edge cases, and +the decisions that came out of the argument. + +[`grill-me`](/skills/grilling/me/SKILL.md) · +[`grill-with-docs`](/skills/grilling/with-docs/SKILL.md) · +[`domain-modeling`](/skills/domain-modeling/SKILL.md) · +[`adr`](/skills/adr/SKILL.md) + +### Architecture Knowledge Bootstrap and Adoption + +**Starts from** a repository with no architecture documentation, or one whose +documentation is a single generic file. **Produces** a Docs-as-Code knowledge +base with metadata, traceability, validators, generators, and agent adapters +that route to this toolkit instead of copying it. + +[`bootstrap-project`](/skills/bootstrap-project/SKILL.md) · +[`general-semantic-contracts.md`](general-semantic-contracts.md) · +[`metamodel/`](metamodel/) and [`templates/`](templates/) · +generated adapters via `scripts/build-agent-adapters.js` · +native skill loading via [`adapters/shared/install-skills.sh`](adapters/shared/install-skills.sh) + +### Reviewable Architecture Delivery + +**Starts from** an issue ready to implement — sliced by the capability above, or +arriving already specified. **Produces** a reviewed, integrated change with a +linear history and a checkout ready for the next one. + +[`implement-issue-workflow`](/skills/implement-issue-workflow/SKILL.md) · +[`commit-message`](/skills/commit-message/SKILL.md) · +[`pr-review`](/skills/pr-review/SKILL.md) · +[`traceability-review`](/skills/traceability-review/SKILL.md) · +[`post-merge-sync`](/skills/post-merge-sync/SKILL.md) + +### Session Continuity + +**Starts from** "clock in". **Produces** a session resumed from repository +evidence rather than from what anyone remembers, and — at clock-out — a +repository the next session can pick up without asking, with the day's findings +carried into the user's private journal when one is bound. + +[`clock-in`](/skills/clock-in/SKILL.md) · +[`clock-out`](/skills/clock-out/SKILL.md) · +[private journal binding](#private-journal) + +### Outside the map + +[`presentation`](/skills/presentation/SKILL.md) creates Docs-as-Code slide decks +and event material under [`talks/`](talks/). It is a genuine capability with no +place in the architecture knowledge flow above, and it is named here rather than +stretched into a group it does not belong to. + ## Relationship to docToolchain This project is not intended to compete with @@ -244,6 +353,9 @@ change, that is a defect in the generator or environment. ## AI Skills +The reference list of every skill. [Capabilities](#capabilities) above shows how +they combine; this is where you look up an individual one. + Use the skill contracts under `skills/` for focused architecture workflows: - [`skills/bootstrap-project`](/skills/bootstrap-project/SKILL.md) for bootstrapping new project architecture documentation in the toolkit structure. From 529d61cdd67497a3567b2a3a688c8ddb8b396fdd Mon Sep 17 00:00:00 2001 From: Dieter Baier Date: Mon, 31 Aug 2026 14:49:07 +0200 Subject: [PATCH 2/2] issue_80: Close the arc through the Convergence Check MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review on #83: the Spec-Driven Development entry stopped at Reviewable Architecture Delivery while #80 requires the workflow to be described "from feature request to convergence", and the PR closes that slice. The criterion would have been closed unmet. The gate exists now that #81 has landed, so the entry says what the capability actually produces: a change whose request, specification, architecture knowledge, implementation, tests and delivery metadata tell one consistent story — checked rather than assumed, with the four result states named and the non-repair rule stated. Reviewable Architecture Delivery gains the same gate before a pull request is declared mergeable, which is the second place the check applies. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01USXp58FoRppFK6FUht8K7u --- README.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index faf2667..fdedca8 100644 --- a/README.md +++ b/README.md @@ -31,9 +31,9 @@ engine-agnostic contract it applies. ### Architecture-aware Spec-Driven Development -**Starts from** a feature request. **Produces** a specified, sliced, and -architecturally assessed change whose issues, behaviour spec, and architecture -documentation stay aligned as it is built. +**Starts from** a feature request. **Produces** a delivered change whose request, +behaviour specification, architecture knowledge, implementation, tests and +delivery metadata tell one consistent story — checked, not assumed. The toolkit's fullest capability, and the one no single skill shows: a feature request is classified as an Epic or a reviewable UserStory, its intended value @@ -41,8 +41,13 @@ expressed as a User Story, its new observable behaviour specified as language-agnostic Gherkin bridged to automated verification, its impact on the existing architecture analysed, the affected ADRs, quality scenarios, risks, components, runtime and deployment views updated, and the work sliced into -reviewable issues — which then flow into *Reviewable Architecture Delivery* -below. +reviewable issues — which flow into *Reviewable Architecture Delivery* below. + +It ends where most workflows stop without noticing: each artifact was reviewed on +its own, and nothing looked across them. The **Convergence Check** closes the arc +by asking whether they still agree, and reports *converged*, *converged with +recorded waivers*, *not converged*, or *blocked* — never repairing an artifact to +make the answer come out better. [`architecture-impact`](/skills/architecture-impact/SKILL.md) · [`bdd-specification`](/skills/bdd-specification/SKILL.md) · @@ -50,7 +55,8 @@ below. [`adr`](/skills/adr/SKILL.md) · [`quality-scenario`](/skills/quality-scenario/SKILL.md) · [`risk`](/skills/risk/SKILL.md) · -[`traceability-review`](/skills/traceability-review/SKILL.md) +[`traceability-review`](/skills/traceability-review/SKILL.md) · +[`convergence-check`](/skills/convergence-check/SKILL.md) ### Architecture Decision and Impact Management @@ -97,12 +103,14 @@ native skill loading via [`adapters/shared/install-skills.sh`](adapters/shared/i **Starts from** an issue ready to implement — sliced by the capability above, or arriving already specified. **Produces** a reviewed, integrated change with a -linear history and a checkout ready for the next one. +linear history and a checkout ready for the next one, gated by the same +Convergence Check before the pull request is declared mergeable. [`implement-issue-workflow`](/skills/implement-issue-workflow/SKILL.md) · [`commit-message`](/skills/commit-message/SKILL.md) · [`pr-review`](/skills/pr-review/SKILL.md) · [`traceability-review`](/skills/traceability-review/SKILL.md) · +[`convergence-check`](/skills/convergence-check/SKILL.md) · [`post-merge-sync`](/skills/post-merge-sync/SKILL.md) ### Session Continuity