Present toolkit features and formalize architecture-aware SDD convergence

[dieterbaier]

Context

The toolkit already provides more than a collection of independent architecture skills. Several skills form coherent end-to-end capabilities.

A feature request is already handled through an architecture-aware Spec-Driven Development workflow:

1. classify the request as an Epic or a reviewable UserStory;
2. express the intended value as a User Story;
3. specify new or changed observable behaviour as language-agnostic Gherkin;
4. analyze the impact on the existing architecture;
5. update or create ADRs, quality scenarios, risks, components, runtime views, and deployment views where necessary;
6. slice the work into reviewable issues;
7. implement and verify the slices;
8. keep issues, implementation, tests, and architecture documentation aligned.

This workflow is currently distributed across architecture-impact, bdd-specification, slice-issues, implement-issue-workflow, adr, quality-scenario, risk, and traceability-review. The individual skills are documented, but the README does not yet present the resulting capability clearly.

The same applies to other combinations of skills. A flat skill list explains the available building blocks, but not what a user can achieve with them.

Issue #31 also concerns README discoverability, but has a narrower focus on agent instruction templates. Coordinate the placement of both changes without merging the scopes.

Goal

Present the toolkit through user-facing features/capabilities in the main README and make Architecture-aware Spec-Driven Development an explicit feature.

Add a final Convergence Check to the feature workflow. The check must determine whether the request, behavioural specification, architecture knowledge, implementation, tests, and delivery metadata tell one consistent story before the work is considered complete.

The feature view supplements the skill reference; it does not replace it or create a second source of truth for skill rules.

Proposed feature map

Validate the names and exact grouping during implementation. At minimum, consider:

Architecture-aware Spec-Driven Development

Possible participating skills:

• architecture-impact
• bdd-specification
• slice-issues
• implement-issue-workflow
• adr
• quality-scenario
• risk
• traceability-review
• proposed convergence-check

Architecture Decision and Impact Management

Possible participating skills:

• architecture-impact
• adr
• quality-scenario
• risk
• traceability-review

Domain Discovery and Domain Modeling

Possible participating skills:

• grilling/me
• grilling/with-docs
• domain-modeling
• adr

Architecture Knowledge Bootstrap and Adoption

Possible participating skills:

• bootstrap-project
• semantic contracts
• generated agent adapters
• validators and generators

Reviewable Architecture Delivery

Possible participating skills:

• slice-issues
• implement-issue-workflow
• pr-review
• traceability-review
• post-merge-sync
• proposed convergence-check

Avoid forcing every skill into exactly one feature. A skill may contribute to several capabilities. Keep the canonical instructions in the individual skill and contract files; the README should link to them and explain their collaboration.

Convergence Check

The Convergence Check is not another implementation phase and does not mean that all artifacts must contain the same information. It is a final consistency and completeness gate across artifacts at their appropriate abstraction levels.

Questions to answer

The check should verify at least:

1. Intent and scope

   • Does the implemented slice still match the Epic/UserStory and its acceptance intent?
   • Are scope changes reflected in the issue and specification?

2. Behaviour

   • Is every added or changed observable behaviour described by a Gherkin scenario, or covered by an explicit recorded waiver?
   • Is each scenario mapped to at least one automated verification according to the BDD bridge rules?
   • Do implemented edge cases contradict the feature specification?

3. Architecture impact

   • Were affected boundaries, components, interfaces, dependencies, runtime interactions, deployment elements, quality attributes, risks, and constraints assessed?
   • Were only genuinely affected architecture artifacts changed?

4. Decisions

   • Are conflicts with existing ADRs resolved?
   • Are new architecture-significant decisions recorded as proposed or accepted ADRs rather than hidden in code or PR discussion?
   • Are remaining human decisions explicit?

5. Traceability

   • Can the path from Epic/UserStory through feature specification and architecture impact to implementation, tests, and PR be followed?
   • Are authoritative outgoing relations valid and are derived views regenerated?

6. Implementation and verification

   • Do code and configuration implement the specified behaviour and decisions?
   • Do relevant tests, validators, generators, render checks, and builds pass?
   • Are unavailable checks and residual risks reported?

7. Documentation and delivery state

   • Do the issue, PR, source documentation, and code describe the same resulting state?
   • Are superseded assumptions or stale references removed or explicitly retained with a valid lifecycle status?
   • Are follow-up issues created for deliberately deferred work?

Result

Define a small, explicit result model, for example:

• Converged — no unresolved contradiction or missing mandatory evidence;
• Converged with recorded waivers — deviations were explicitly accepted by a human and their rationale is traceable;
• Not converged — contradictions, missing links, missing verification, or undocumented decisions remain;
• Blocked — the check requires unavailable evidence or a pending human decision.

A failed check should produce concrete findings and follow-up actions. It must not silently rewrite accepted requirements or architecture decisions merely to make the artifacts agree.

Automation boundary

Separate checks into:

• deterministic checks that belong in validators or CI;
• semantic checks an AI assistant may propose findings for;
• decisions that require human review.

Do not present an AI assessment as deterministic proof.

Implementation considerations

• Decide whether Convergence Check should be:
  • a dedicated engine-independent skills/convergence-check/SKILL.md;
  • a reusable reference invoked by architecture-impact, implement-issue-workflow, and pr-review;
  • or a combination of both.
• Prefer one canonical definition and thin references from participating skills.
• Invoke the check at least before a feature PR is declared mergeable or an implementation issue is considered complete.
• Reuse existing validation, BDD bridge, traceability, and review rules rather than duplicating them.
• Update generated agent adapters if a new canonical skill is introduced.
• Add deterministic validation only where the rule can actually be established from repository data.

Acceptance criteria

• The main README contains a concise feature/capability overview.
• Each feature explains the outcome for the user and links to the participating canonical skills or contracts.
• Architecture-aware Spec-Driven Development is documented as an end-to-end workflow from feature request to convergence.
• The README makes clear that the feature view is navigation, not a duplicate source of skill rules.
• The proposed feature groups are checked against the current skill set and adjusted where necessary.
• A canonical Convergence Check workflow is defined.
• The Convergence Check distinguishes deterministic validation, AI-assisted semantic assessment, and human decisions.
• The result states and handling of waivers, blockers, contradictions, and follow-up work are explicit.
• Relevant feature workflow, implementation, and PR-review skills invoke the canonical Convergence Check.
• Any new skill is exposed through the supported agent adapters and adapter drift checks remain green.
• Existing validators, generators, tests, and documentation builds pass.
• The README change is coordinated with issue Link agent instruction templates from main README for discoverability #31 so both additions remain discoverable and do not duplicate each other.

Out of scope

• Replacing the individual skills with one monolithic SDD skill.
• Copying complete skill instructions into the README.
• Treating every code change as architecture-significant.
• Introducing GitHub Spec Kit, Kiro, or another agent-specific SDD runtime as a required dependency.
• Claiming deterministic convergence where only semantic or human review can establish it.

[dieterbaier]

All three slices are integrated: #80 (#83), #81 (#84), #82 (#85).

Acceptance criteria, checked individually against main rather than assumed from the slices:

Criterion	Where
Concise feature/capability overview in the README	## Capabilities, above everything else
Each feature explains the outcome and links participating skills	six entries, each with Starts from / Produces
Spec-Driven Development documented from feature request to convergence	closes with the gate, its result states and the non-repair rule
The feature view is navigation, not a duplicate of skill rules	stated in the section, and now enforced by test/skill-wiring.test.mjs
Proposed groups checked against the current skill set	audit on #80; five unplaced skills placed, one group added, one reframed by entry point
A canonical Convergence Check is defined	skills/convergence-check/SKILL.md
Deterministic / assisted / human tiers distinguished	stated with every finding; an assisted finding is never reported as proof
Result states, waivers, blockers, contradictions and follow-up explicit	four states, blockers split into pending and unavailable, four finding dispositions
Participating skills invoke the check	architecture-impact, implement-issue-workflow, pr-review — verified by test, not by inspection
New skill exposed through adapters, drift check green	all six adapters list it; check-adapters current
Validators, generators, tests and builds pass	39 JS tests, 157 Ruby assertions, 0 failures
README change coordinated with #31, scopes not merged	#31 closed on its own finding: templates/agents/ is a bootstrap implementation detail, not a user-facing entry point

What the epic produced beyond its plan

Three rules that were not in the original proposal. Each came from applying the gate rather than from designing it:

• A question that cannot fail is not applicable, never passed. bdd-specification: the strict default asks for a scenario that cannot fail when the defect is below the bridge layer #74's finding about the BDD default, one level up.
• Blockers split into pending and unavailable, and a waiver is a legitimate outcome of the first but never of the second. From review on issue_81: Define the canonical Convergence Check #84.
• A standing limitation is not this change's blocker. From review on issue_82: Invoke the Convergence Check from the participating skills #85, after I reported the absent execution layer for prose contracts as blocking — which would have stopped every prose-skill change until [EPIC] Establish Agent Skills conformance and evaluation #65.

One pattern worth carrying forward

Question 7 — do the issue, the pull request and the source documentation describe the same state? — caught a real defect twice in three pull requests, both times found by a human reviewer rather than by the agent that wrote the change. On #83 a stale skill count and an obsolete section; on #85 an entire behaviour assessment left behind after the change outgrew it.

Both times the code converged and the delivery metadata did not follow. Two instances in three pull requests is not chance, and #65 is where a mechanical guard for it would belong.