dfg-inc/praxis-architect/design-package

Design Package

Single package Developer (and decompose-features) can implement against: structure, flows, decisions, contracts, budgets. Diagrams are text (Mermaid/ASCII) — no binary drawing tools required (WBS 4.11.1).

When to use

• After the WP’s binding ADRs are accepted (via record-decision).
• After relevant platform-contract and nfr-budget artifacts exist (or explicitly N/A).
• Before decompose-features / initial-estimate / context-slice.

Do not start a design package while intake-audit is fail.

Inputs

Target layout

design/<workPackageId>/
  index.md                 # overview + scope + non-goals
  diagrams/                # *.md with mermaid/ascii only
  decisions.md             # index of linked ADR ids + paths
  contracts.md             # linked contract paths + compatibility notes
  nfr-budgets.md           # linked budgets + verify moments
  open-questions.md        # prefer empty before handoff
  change-intent.json       # MACHINE: patches + features for Developer (required)

Project may relocate under .project design.root; default is design/<workPackageId>/.

Steps

1. Preflight

• Intake audit verdict pass or acknowledged pass-with-warnings.
• Machine ba.architect.handoff present (from BA wp approve-plan).
• Every divergence point that required a decision has an accepted ADR (or an explicit deferred open question with human ok).
• List ADR ids that bind this WP.

1. Create folder

design/<workPackageId>/ and diagrams/.

1. Write `index.md`

Required sections:

• Purpose / user-visible outcome (product language, not code dump).
• In-scope / out-of-scope.
• Systems/platforms touched (from context map).
• Pointers to decisions.md, contracts.md, nfr-budgets.md, diagrams/.
• Build order hint (optional until initial-estimate).

1. Text diagrams (diagrams/*.md)

At least:

• Context / container (C4-ish) for touched platforms.
• One key sequence or data-flow for the critical path.

Use fenced mermaid or ASCII. No PNG/SVG required. Each file starts with a one-line legend.

1. `decisions.md`

Table: ADR id | title | path | rule (one-liner). Link only accepted ADRs that apply. Orphans with no link → fix before handoff.

1. `contracts.md`

For each inter-platform exchange: path to contract, format, compatibility policy summary. If none: section None — single module with justification.

1. `nfr-budgets.md`

Metric | limit | measure how | measure when | budget file path. Missing measure/when → incomplete package.

1. `open-questions.md`

Prefer empty. Any remaining open must be severity-tagged; high severity blocks handoff readiness.

1. Write `change-intent.json` (machine, required)

Product-agnostic patch + feature intent consumed by emit-developer-handoff. Derive from BA scope + accepted decisions — never hardcode a sample product. Include at minimum:

``json { "decisionIds": ["ADR-…"], "requirementIds": ["…from ba handoff…"], "requiredMachineFiles": ["src/…", "package.json", "test/….test.js"], "features": [{ "id": "FEAT-…", "title": "…", "readyForDev": true }], "changes": [ { "file": "path/existing.js", "op": "edit", "description": "…", "match": "…", "replace": "…" }, { "file": "path/new.test.js", "op": "create", "description": "…", "content": "…" } ], "acceptanceChecks": [ { "file": "…", "contains": "…" }, { "type": "npm-test" } ], "verificationPolicy": { "requireTests": true }, "design": { "title": "…", "decision": "…", "machineRequirements": ["src/…", "package.json", "test/…"], "contextInScope": ["…"], "outOfScope": ["…"], "changeIntent": "one-liner" } } ``

• op: "edit" (default): deterministic match→replace on an existing file.
• op: "create": full file content (legacy write still accepted). Idempotent if content already matches; fails on conflicting existing content.
• Every path in requiredMachineFiles / ## Machine requirements / design.machineRequirements must appear in changes[].file or emit-developer-handoff refuses readyForDev.
• Do not leave required implementation only in Markdown.

1. Self-check

• Every diagram renders as text in a markdown viewer.
• Every ADR id resolves on disk.
• Non-goals explicit in index.md.
• change-intent.json parses and lists readyForDev: true features.

1. Handoff path

Record designPackagePath: "design/<workPackageId>/" for later architect.developer.handoff (filled fully in context-slice / emit).

Human gates

Done when

• Folder design/<workPackageId>/ contains index, decisions, contracts, budgets, ≥1 text diagram, and change-intent.json.
• Diagrams are text-only and self-contained.
• Binding ADR/contract/budget links resolve.
• Package is usable input to decompose-features without inventing architecture.

Failure modes