Skip to content

skill · phase: design

Design Phase

Purpose

Produce a technical design that satisfies the requirements. Define architecture, interfaces, data models, and integration points before writing code.

Entry Criteria

{{glossary:instance}}

  • Requirements phase complete
  • The instance is claimed by this session

Entering in a fresh session

Read only:

  • instance.yaml
  • requirements.md — in full; the acceptance criteria are what the design is traced against
  • the always-read guidance layers named in .aidlc/guidance/index.yaml (see The always-read rule (.aidlc/resources/rules/always-read.md))
  • .aidlc/context/architecture.md and style-guide.md
  • .aidlc/context/constitution.md, when it exists
  • the ## Decisions section of roadmap-item.md, when the item has one — answers its author gave at capture
  • the spec corpus files in .aidlc/specs/ named by requirements.md's ## Spec delta section — the current spec, which is what the design is built against. Not a past instance's requirements.md: it describes a change, and later instances may have changed it again.

The seams the requirements touch are then read from the source, as step 3 of the instructions says — a handful of files, not a survey, and not the previous phase's transcript. See The context rule (.aidlc/resources/rules/context.md).

Required Artifacts

  • design.md — Architecture overview, component design, interfaces, data flow, and design decisions with rationale

Instructions

{{glossary:gate}}

  1. Review requirements. Read requirements.md (or its summary if one exists). Identify the key technical challenges. When requirements carry AC-n IDs, note in each design section which criteria it addresses — that linkage is what reviewers and the testing phase trace against.
  2. Consult the knowledge graph, then check it against the source. If the project has a knowledge graph (.aidlc/knowledge/ exists), run aidlc knowledge context --scope phase --phase design for existing architecture, decisions, and conventions. The graph is an index into the code, not an authority over it: an entry naming a component, table, column, function, or registry is a pointer to open, and an entry written by an earlier instance may name something a later one renamed or deleted. Confirm a named symbol exists in the source before designing against it — aidlc knowledge verify <id> records that you did, and aidlc knowledge update <id> corrects an entry that no longer matches. A design built on a symbol that is not there produces code against an API nobody has, and nothing downstream catches it until implementation. Also read the always-read guidance layers from .aidlc/guidance/index.yaml — see The always-read rule (.aidlc/resources/rules/always-read.md) for which layers those are and when to reach for the full lessons.md. Read .aidlc/context/constitution.md when it exists and apply the constitution rule in .aidlc/resources/rules/constitution.md.
  3. Find the seams before proposing structure. A project is brownfield from its second instance onwards, so start from the assumption that something in the codebase already does part of what the requirements ask for. For each capability in requirements.md, locate and read the existing code that carries any of it — the scheduler that already fires, the settings shape that already persists, the registry that already dispatches — and name those files in design.md before describing a single new component. Keep it narrow: the seams the requirements actually touch, a handful of files, not a survey. When nothing exists, write that down — "no existing seam" is a finding, and stating it is what separates a genuinely new component from one designed alongside the code that should have absorbed it.
  4. Define architecture. Describe the high-level structure: components, their responsibilities, and how they communicate. Say for each one whether it extends a seam found in step 3 or is new.
  5. Specify interfaces. For each component boundary, define the contract (function signatures, API shapes, data types).
  6. Data flow. Document how data moves through the system — inputs, transformations, storage, outputs.
  7. Design decisions. Record each significant decision with rationale and alternatives considered. Persist accepted decisions as decision entities: aidlc knowledge add --type decision --id <slug> --name "<title>" --description "<rationale>". A decision that would build other than what was agreed — in requirements.md, the roadmap item or a person's answer — is asked before it is recorded, as The departure rule (.aidlc/resources/rules/departures.md) says. A design question the roadmap item's ## Decisions section answers is not asked: write the answer into design.md, citing roadmap-item.md ## Decisions.
  8. Address non-functional concerns. Map performance, security, and accessibility requirements to design choices.
  9. Identify risks. Note technical risks and mitigation strategies.
  10. Produce the task breakdown. For templates that require it (full-feature, quick-feature), write tasks.md in the instance state directory as the final design step — the design is not done until it is actionable. Decompose the design into commit-sized tasks: each one reviewable in one sitting and independently verifiable. One task per line, in this exact grammar:
- [ ] T<n>: <title>
- [ ] T<n>: <title> (AC-1, AC-2)
- [x] T<n>: <title> (AC-3)
- [>] T<n>: <title> (AC-4) (deferred YYYY-MM-DD: <reason>)
- [ ] T<n>: <title> (AC-5) (wave: 2)

Number tasks sequentially (T1, T2, ...) — IDs are never renumbered or reused; a task overtaken by events is deferred with a reason, never deleted. Reference the acceptance criteria each task satisfies where any apply; chore or infrastructure tasks may legitimately have none (the implementation gate surfaces them as warnings, never failures).

Mark tasks that can run at the same time with (wave: <n>), <n> a whole number from 1. Tasks sharing a wave may be handed to separate agents at once, so give two tasks the same wave only when they touch different files and neither needs the other's output. A wave is a run of consecutive tasks — T4, T5 and T6, never T4 and T6 with T5 between them; the parser warns on a split wave. A task with no wave runs alone, in number order. Leave waves out when nothing can run alongside anything else: they matter only when implementation runs one agent per task.

Exit Criteria

  • design.md exists with architecture, interfaces, and at least one design decision with rationale
  • design.md names the existing code the change extends, or states that no such code exists
  • Every knowledge-graph symbol the design builds on was checked against the source
  • The design addresses all acceptance criteria from requirements.md
  • For templates requiring it: tasks.md exists and every active acceptance criterion is claimed by at least one task, or the gap is deliberate
  • The phase ends by naming each open design decision — asked through the Question Protocol (.aidlc/resources/rules/question-protocol.md) in .aidlc/state/<instance>/design-questions.md — or by saying "Nothing open", written into design.md as a line of its own: autopilot reads that line to skip a pause with nothing to decide. Do not ask the user to confirm the design as a whole. Unattended (AIDLC_UNATTENDED=1): nothing is confirmed or logged; hard-stop when the design reaches beyond the roadmap item, per .aidlc/resources/rules/unattended.md.

Guidance

{{context:architecture}} {{context:style-guide}} {{guidance:secure-defaults}} {{guidance:accessibility}}

Security Confirmation

If the design involves:

  • New authentication or authorization flows
  • Data storage of sensitive information
  • External service integrations with credentials
  • Infrastructure provisioning

You MUST flag these explicitly in the design document and note that implementation will require security confirmation before proceeding.

Completion

When exit criteria are met, update phase-design.yaml status to complete and append a transition record to transitions.log.

Then end the turn as The next-steps rule (.aidlc/resources/rules/next-steps.md) says.

Changing a completed phase's artifact. Do it only through an amendment — append an ## Amendment <n> — YYYY-MM-DD section to requirements.md with Retires:, Issues:, Reopens: and Reason: bullets, then run aidlc amend <instance> (start with --impact to see what still cites the retired criteria). Editing the artifact directly leaves every gate passing while the requirements and the code disagree.