DR-016 — Design documentation and the two workflows¶
Converted from
docs/decisions/DR-016-design-docs-and-two-workflows.mdto MADR (backlog B25). The text is unchanged; its sections are grouped under the MADR headings below, in their original order within each group.
Context¶
1. The problem¶
Atul needs design documents he can understand and steer. Agents need the same truth in a form that keeps them focused, not a pile of long documents. Today design lives in long Markdown files and chats, and agents read too much or too little.
2. Three layers of design truth (from the suggestion, adapted)¶
| Layer | Format | Atul sees | Agents use | Where |
|---|---|---|---|---|
| Architecture map (C4) | Structurizr DSL (text) | Diagrams (landscape, containers, components) rendered into the MkDocs site | The text as an exact dependency graph | architecture/workspace.dsl per repository; the estate-wide model in MMDEP (draft 1 committed today) |
| Decisions (ADRs) | MADR Markdown with YAML front matter (status: proposed / accepted / superseded, date, deciders, supersedes) |
One page per decision, a list by status on the site | A generated JSON index (docs/adr/index.json) to check what was decided or rejected before proposing changes |
docs/adr/NNNN-title.md per repository; MMDEP's DR-001 to DR-016 converted |
| Execution context | Rules file (under 200 lines) + skills (playbooks read on demand) + MCP tools | n/a | Rules: a map of where things are. Skills: loaded only for the task at hand. MCP: live state (GitHub, MMDEP hub) instead of pasted documents | AGENTS.md/CLAUDE.md (already generated from one source), docs/skills/<topic>/SKILL.md, the MMDEP MCP gateway (sprint 3) |
Adapted choices: - Log4brains: not now. It adds a Node toolchain; MADR files plus a small Python index generator (B25) give the same index. Revisit if we want its web UI. MkDocs (B23) already gives the site. - Structurizr rendering: the Structurizr CLI exports Mermaid or PlantUML in CI, and MkDocs shows the diagrams (B26). Structurizr Lite (Docker) on the laptop is for editing with a live preview. - Structurizr MCP server: sprint 3, together with the hosted MMDEP gateway.
Rule for every project (from sprint 2 preflight):
- A change to boundaries, data flows or contracts must update workspace.dsl and add an ADR in the same PR.
- Every routing block may cite adr: and c4: (element IDs), so the harness hands the agent only those, plus the scope files.
5. What Atul reads¶
- One site (MkDocs + Material, B23) with: the estate landscape and container diagrams; each project's components; decisions by status (proposed decisions waiting for you at the top); runbooks; the sprint status.
- One phone list (Actions): proposed ADRs and questions with one-tap choices.
Options¶
Not stated separately in the original record.
Decision¶
6. Decision for Atul¶
- ARCH-1: adopt the three layers for every project from sprint 2: Structurizr DSL for C4, MADR ADRs with a JSON index, rules under 200 lines plus skills plus MCP. Run the two workflows above. MMDEP goes first (estate model draft 1 is committed; DR conversion is B25).
Consequences¶
3. Workflow (i): Design and Code, for high-risk items¶
High risk means production, auth and keys, money or client data, cross-project contracts, schemas (DR-012 §5).
| Step | Who (primary) | Output, in the repository | Fallback |
|---|---|---|---|
| 1. Frame | Project agent (flow A or P) | Epic issue: goal, value, risk, links to the C4 elements touched | MMDEP-PM drafts it |
| 2. Design | Design agent: the project's ChatGPT agent, or Claude Opus for cross-project work | workspace.dsl diff, ADR (proposed) with 2–3 options and a recommendation, LLD section, contract tests written first (failing) |
Gemini Flash or Pro as architect (paid tier); MMDEP-PM |
| 3. Decide | Atul, one click | ADR becomes accepted (from an Actions item: options, recommendation, diagram link) |
After 48 h: if reversible, the recommended option goes ahead as ASSUMED; if irreversible, it waits |
| 4. Build | Strong coder: Claude Sonnet, or the project agent | Code in a worktree, tests passing, the ADR cited | Aider in architect mode (Gemini plans, Sonnet or a free ZDR model edits) |
| 5. Verify | Test harness plus a second model reviewing the diff against the ADR | Full suite, contract tests, security report-only checks; review notes on the PR | A second agent reviews |
| 6. Stage | Fabric task through the laptop runner | staging.deploy plus smoke tests; evidence on the PR |
Atul runs the one-line SSH script |
| 7. Release | Atul approves; Fabric prod.* task or a person |
Release note, ADR consequences confirmed | Ajay (server) |
4. Workflow (ii): Code and Test, for low and medium risk¶
| Step | Who (primary) | Output | Fallback |
|---|---|---|---|
| 1. Plan | Project agent, one PROCEED per epic | Issues with routing blocks (risk, cx, adr, c4, scope, tests); the epic split into harness-sized items |
MMDEP-PM, or the Sonnet backlog rule |
| 2. Code | Local harness between PROCEEDs: Gemini Flash-Lite (paid), then OpenRouter free (ZDR only), then local Ollama; built-in engine or Aider (architect + editor, repository map) | Branch auto/issue-N, focused tests |
Claude Sonnet takes items the harness fails twice |
| 3. Gates | Harness | Tests, full-suite regression, ruff (new findings), scope check, exact-string guard, no-placeholders, coverage must not drop, bandit/pip-audit report | — |
| 4. Merge | Harness or agent (DR-012) | Low: merge to main on green CI. Medium: merge to integration/sprint-N |
— |
| 5. Audit | MMDEP-PM check-in, or the MMDEP Assistant fallback | Post-merge audit; bugs filed; sprint status page updated | Assistant flags only |
Between two PROCEEDs the harness has already merged some small items. The agent's next PROCEED starts from harness/LATEST.md and the sprint page, then continues the epic. This is the "progress between PROCEEDs" Atul asked for.