Design to implementation¶

Hand an approved design to implementation with the evidence, work record and checks that let the implementer proceed without inventing behavior.

A design explains intent, journeys, constraints, boundaries and decisions. It does not duplicate a PRD, formal specification, tracker or implementation diff. Begin with a shaped outcome: evidence, assumptions, alternatives, and the next worthwhile increment. UI/UX exploration applies when the increment changes an interface; API, infrastructure and migration work use suitable design methods. Use the product brief and delivery slice to carry that intent forward without a second specification system.

The handoff contract¶

An implementation-ready design answers the following questions or links to the artifact that does:

The source templates live at agents/templates/design.md, agents/templates/adr.md, and agents/templates/runbook.md; generated projects receive them under docs/templates/. Update docs/architecture.md only when the durable system view changes.

Handoff flow¶

flowchart TD
    R[Reviewed requirements] --> D[Design document]
    D --> A[Architecture and ADR updates]
    A --> N{Material behavior needs formal specification?}
    N -->|Yes| S[Current formal specification and scenarios]
    N -->|No| E[Recorded no-spec decision]
    S --> W[Reviewed ai-dlc work record]
    E --> W
    W --> P[Implementation slices and test plan]
    P --> B[Bound work branch]
    B --> PR[Code, tests, docs, pull request]

The work record is the traceability bridge. It binds approved scope and remote artifacts before implementation mutates the tracker or creates branch state. It should link durable sources rather than paste their contents.

From requirements to finishable work¶

Use spec-from-prd with a reviewed canonical brief or PRD. Keep OUT/RQ IDs owned by that source. Link requirement → formal scenario (when required) → deliverable work ID → implementation step → observed verification. Product rationale belongs in the brief or design, behavior with the specification provider, delivery status in the tracker, and implementation steps inside the work item.

One behavior ticket owns one independently finishable OpenSpec change. A parent epic coordinates children without one shared specification gate. Tests, parser, docs and refactoring checkboxes are steps, not automatic extra tickets. A verification-only item records requires_spec=false and its reviewed reason, references existing behavior and retains all applicable completion gates.

See localized export and compatibility rehearsal. These synthetic examples propose local IDs and document destinations; they do not install records, create remote work or establish actual approval/live results.

Create a draft with ai-dlc work new WORK_ID --from-issue REF, or use explicit --title, --scope and repeated --acceptance values for offline work. The command copies the configured binding roles and issue acceptance bullets when present; missing source content and the default specification decision remain explicit TODOs. Explicit flags override derived fields.

New records are always unreviewed: replace TODOs and link the formal artifacts, then run ai-dlc work review WORK_ID before publishing or starting. Existing records and unsafe IDs are refused without being overwritten; offline drafting creates no mutation state.

Work records accept optional requirements and depends_on lists, defaulting to empty for older work. Requirements are nonblank single-token IDs, not copied spec prose or paths automatically interpreted as source documents. Put canonical source, plan, specification and evidence references in artifacts. Dependencies name local work IDs in .ai-dlc/work/; preserve their pinned providers and binding identity.

Run ai-dlc work validate WORK_ID --root . before publication. It returns valid (exit 0) or invalid (exit 1), reads only the selected dependency closure, and initializes no mutation journal. Missing or unsafe IDs, cycles, invalid records, binding drift and missing local artifact files fail before publish or start effects. Unrelated drafts do not block the selected work.

Local artifact paths must remain in the repository without symlinks. Fragments are retained as references without interpreting specification text. HTTP(S) references are not probed, and tracker, PR, branch, deployment and knowledge references remain provider-owned.

A suffix-less specification path whose first segment is a repository directory (such as an OpenSpec change directory) stays a local artifact. After the directory is moved it is reported as absent. An opaque slash ID or provider URI that is not anchored in the repository stays provider-owned.

ai-dlc work validate --all --root . validates every record's shape, local artifacts and dependency graph together, offline. It does not resolve provider bindings, so finished records with historical fingerprints do not fail it. Run it as a required project check so archiving cannot leave a dangling reference undetected.

Binding drift is a mutation-time refusal, also surfaced by single-record validation. For active work, review the record against current provider configuration, remove only the drifted binding under [bindings], and run ai-dlc work validate WORK_ID. The next work mutation persists the reviewed binding. Preserve finished records' historical bindings. project rebind migrates a provider role and is not a binding-drift repair command.

Validation does not approve scope or prove completion. work start freshly reads every reachable dependency through its pinned tracker and requires canonical closed. Cancelled, duplicate, incomplete, unpublished or unavailable statuses block before branch creation, work saves or tracker changes. Resolve missing interfaces/status with their owners; prepare independent local drafts meanwhile.

First issue creation includes scope, requirement/dependency references, artifacts, specification decision and acceptance. Re-publication reconciles the existing mapping/correlation without overwriting authored descriptions or changing prior journal identities. It does not publish updated scope into an existing issue. Keep unresolved product semantics and unperformed live checks visible. Review, merge, exact-revision evidence and ai-dlc work finish remain the completion path.

Greenfield handoff¶

For a new application, design begins with the first deployable boundary and one end-to-end user outcome. Define the minimum architecture needed for that slice, then identify which interfaces are intentionally stable and which are still internal. Avoid designing hypothetical services, extension systems, or configuration until a requirement needs them.

The first slice must leave a reproducible setup, lockfile, baseline checks, and one observable behavior. Its tests prove both the language/toolchain baseline and the user outcome.

Brownfield handoff¶

For an existing application, design begins with evidence about current behavior. List affected interfaces, callers, data, operational procedures, and compatibility promises. Characterization tests protect important existing contracts. The design states how each slice moves from the current state to the target state and how to recover if the transition fails.

Do not use a broad rewrite as the handoff unit when an incremental change can be reviewed, verified, and rolled back independently.

Implementation expectations¶

Before coding, an implementer should be able to map each acceptance criterion or required scenario to a planned slice and verification method. During implementation:

• work only on the bound branch and within reviewed scope;
• use tests to drive new behavior and reproduce bugs;
• preserve unrelated user changes and existing contracts;
• update design, decisions, architecture, and runbooks when code invalidates them;
• make uncertainty visible instead of inventing product behavior;

• run required project checks before review.

• Start delivery with ai-dlc work start <work-id>. It commits only the bound work record; work link also commits its record by default. Use --no-commit when deliberately batching record edits. Neither command stages unrelated files.

• Archive the required OpenSpec change on its delivery branch before merge with ai-dlc work archive <work-id>. It promotes the specifications, repoints the record and any plan inside that change, and commits only affected specification files and the record. Commit or preserve any dirty shared specification before archiving; if the archive command fails, inspect its local changes before retrying. work status reports local specification state without a network call, and work pr warns about an active change.
• After implementation, specification finalization and required checks, push the branch explicitly and run ai-dlc work pr <work-id>. This creates the pull request, links its URL and commits the record; push that new link commit before review. Repeating work pr returns the linked URL without opening another pull request. If creation was interrupted before its result was recorded, inspect the provider and recover with work link <work-id> pr <url>; an uncertain create is never repeated.

The pull request should explain the outcome, design decisions, compatibility or migration effects, and evidence. Review compares implementation with the linked design and specification. ai-dlc work finish <work-id> then verifies the merged revision and remote evidence; it does not infer success from the local branch.

Change control¶

If implementation reveals a material product, interface, security, migration, or operational decision that the design does not answer, pause and update the reviewed artifact before continuing. Small implementation details may remain in code and tests. Decisions that future maintainers must understand belong in the repository.

Specification references may be provider-native IDs or explicit local documents. Native IDs (including slash IDs and provider URIs) are not interpreted as missing repository files. Use ./name for an ambiguous local directory; filesystem notation, document suffixes such as .md, and existing repository paths receive local containment/existence checks. This does not replace the specification provider's archive or finish validation.

Optional interface evaluation¶

When a shaped increment needs visual or interaction judgment, use design-brief with the canonical product brief and delivery slice/RQ IDs. Create a brief and versioned rubric before generation; keep proposed defaults and task-specific budget approval distinct. Small brand-constrained fixes may use one concise combined record and the existing component system.

Use the design brief, rubric, evaluation and selection. The original library-room examples show failed journeys, brand fit, static limitations and earlier-candidate selection. They contain synthetic observations, not executed UI or human preference evidence.

The chosen existing visual tool generates an identified candidate. Design-evaluate receives its revision or digest, brief, rubric and access instructions. A separate session or human is an available review route; same-session generator review is self-review. A required failure blocks design acceptance, and absent interaction evidence stays unverified regardless of visual scores. Keep reports and findings with their exact candidate and rubric; a new rubric requires reevaluation.

Retain docs/design/<work-id>/brief.md, rubric.md, iterations/<candidate-id>/evaluation.md and decision.md, or equivalent stable sections in a concise record. Stop on the declared budget/plateau/decision boundary without inferring success or more authorized rounds. Select an earlier revision when its matching evidence qualifies. Hand the selected design, remaining findings and behavior requirements to needs-spec and the existing delivery workflow.

The calibration protocol requires a separately approved experiment and human participation. It remains unrun; readable Markdown and packaging checks establish no client capability or design-quality gain. This optional route adds no service, model, CLI or finish gate.

Frontend smoke and capture evidence¶

Select --preset node --capability frontend when initializing or adopting a frontend project; repeat the other desired role capabilities explicitly. New projects pin @playwright/test to 1.58.2. Adoption preserves your package manifest; add that exact development dependency and update its lockfile during setup.

1. Run dependency setup with PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1.
2. Install the browser explicitly: npx --no-install playwright install chromium. Checks never install packages or browsers.
3. Start the app and set BASE_URL; the required frontend-smoke check fails when it is missing or empty.
4. Run ai-dlc project check --check frontend-smoke. The check visits the root, requires a nonempty title and records a screenshot under .ai-dlc/local/design/smoke/. A missing app or browser dependency remains a failure, not successful verification.

After browser setup, run ai-dlc design capture --url http://localhost:3000 --viewport 1280x800 --viewport 390x844 --state ready=#ready from the project. The default destination is a new timestamped .ai-dlc/local/design/ directory; --out selects another new or empty directory inside the repository. Output paths must not escape or traverse symlinks.

Capture records PNGs and a manifest.json with URL, timestamp, dimensions, named states and file references. A state selector waits for visible page content before taking a viewport screenshot; it does not click controls or prove an interaction journey. Cite the manifest and its images in the evaluation and keep uncaptured states unverified. On failure, inspect the partial capture directory; a complete manifest is written only after every screenshot succeeds.

Select both --capability backend --capability frontend for a node project that needs API contract validation and browser smoke. Both required checks remain active, setup prepares each pinned tool once, and frontend keeps Node 22.23.1. Adoption preserves an authored package manifest; add the documented Playwright dependency deliberately before running smoke.