Design-architecture workflow

Product capability: the design-architecture workflow of the merlon-docs skill records architecture and design decisions as Merlon Docs shards so agents and humans can load one concern at a time instead of growing one large architecture document.

Workflow file: skills/merlon-docs/references/workflows/design-architecture.md. Skill workflows covers the shared workflow contract: intake, atomic commit groups, guide placement, the glossary, and concept removal.

End-user value

Contributors find the right design note (components, contracts, ADR) in one shard read. Architecture intent stays linked through feature and ADR indexes instead of living only in chat or a thousand-line wiki page.

What this workflow is for

Obligation	As-built expectation
One design scope	Create a branch for one WORK_ITEM before drafting design shards; do not mix unrelated designs
Capture architecture intent	Draft system diagrams, API/data contracts, and boundaries as shards under docs/features/
Land durable decisions	Record accepted choices as ADRs under docs/features/adr/ when the repo uses that layout
Keep docs sharded	Prefer one primary concern per shard; update feature/ADR index.md so new shards are discoverable
Brownfield hygiene	Split or retire legacy architecture docs and superseded plans; keep a replaced ADR, marked superseded
Stay design-doc scoped	No product/CLI/TypeScript implementation, no unit tests as delivery, no primary docs/client/ work
Skill QA	Current intended architecture only; no large code dumps in shards; run repo merlon check / docs scripts

What this workflow is not

• Deep design critique / multi-option trade-off workshops — pair with a separate design-thinking skill or human review, then record the agreed intent as shards.
• Implementing CLI flags, packages, or unit tests — use the feature-level workflow.
• End-user / client journey and workflow design — use the ux workflow.
• Docs-only cleanup with no architecture change — use the doc-only workflow.
• Bootstrapping Merlon Docs in an empty or legacy repo — use the getting-started workflow.
• Grading “good systems design” brilliance — out of scope; this workflow owns Merlon Docs documentation-system behavior (sharding, indexes, design-doc scope).

When the user asks for end-to-end delivery (design + client guide + code + tests) in one session, this workflow MUST stay on design shards (or ask to narrow scope) and state next steps for the other workflows.

Acceptance (as-built)

A successful design-architecture session typically:

1. Creates or updates focused Markdown under docs/features/ and/or docs/features/adr/
2. Updates the relevant guide indexes so shards link together
3. Leaves packages/ / product src/ unchanged
4. Avoids multi-function code dumps in durable shards
5. When deep design critique is requested, advises pairing and still records the agreed intent as shards
6. Links WORK_ITEM in review

Optional local with/without-skill grading for this workflow: design-architecture workflow live evals (maintainer workflow — not a CI gate). See Live skill evals.