# Design: turn an agreed feature brief into a decision record and spec items the client signs off before any code

Roles:

- Architect
- Advocate

The account lead (Boss) supplies, as the caller input, the agreed feature brief.
Until the account lead approves, the design exists only as the complete draft in Architect's replies: drafting, review, and revision leave the repository unchanged, and only the account lead's approval writes the design to the repository and commits it.
There are at most two review rounds.
Captain retains the account lead's complete reply to the sign-off question as <sign-off-reply>.
On approval, `design` returns the commit, taken from the repository-effect receipt, and the decision record's ID; on rejection, it commits nothing and returns the account lead's reason and the final draft.

## Behaviors

### DESIGN-1

Where Architect asks the account lead a question before drafting, the account lead's answer resumes this same behavior.

When the account lead gives a feature brief, Captain shall prompt Architect:

> You are the Architect in Northwind Mobile's design stage: turn the agreed feature brief below into a design the client can sign off before any code is written.
> Read @specs/map.md, the specs under @specs/ that the feature touches, and the relevant code before deciding anything.
> If the design depends on something the brief leaves unclear and the specs and code cannot settle, ask the account lead before drafting: at most two questions in this design, each one whose answer would change the options or the recommendation.
> Draft the design as a new decision record for @specs/decisions/ in the form @specs/meta.md requires, numbered after the highest existing record, with its Status set to Proposed.
> In it, state the context, including each question you asked the account lead and their answer; present two or three real options in a table comparing their effort, risk, and user impact; recommend one option and give the reason; and list the spec items it changes or adds.
> Draft those spec items in GEARS form for the affected packages under @specs/packages/, following @specs/meta.md, and note the @specs/map.md entry if you add a package.
> Do not write, edit, or create any file in the repository, and do not commit: the draft lives only in your reply until the account lead approves it.
> Reply with the complete draft, exact enough to be written to the repository unchanged: the decision record's ID, path, and full content; then, for each spec file you would change or add, its path and the exact items to add, or each changed item's current and new text; then any @specs/map.md change.
>
> > Feature brief: <caller-input>

Results:
- `drafted`: Architect replied with the complete draft and left the repository unchanged. Output shall include `architectOutput: <verbatim final text>`.

### DESIGN-2

When Architect has drafted the design, at the first review round, Captain shall prompt Advocate:

> A new design review begins.
> The Architect's complete draft is below and is not yet in the repository; read it, and read the current specs it changes under @specs/ to judge each change.
>
> You are the Advocate, speaking for the client: review the design as the client would before signing it off.
> Check that the options are real alternatives, not straw men set beside the recommendation.
> Check that the recommendation's trade-offs in effort, risk, and user impact are stated honestly.
> Check that every spec item is testable and matches the brief: nothing the brief asks for is missing and nothing it does not ask for is added.
> Return numbered findings, each naming the record section or spec item and what the client would object to.
> Raise only what the client would materially object to; if nothing remains, say plainly that the design is ready for sign-off.
> Do not edit files or commit.
>
> > Feature brief: <caller-input>
> > Architect draft: <architect-output>

Results:
- `hasFindings`: Advocate returned one or more findings; this outcome does not depend on finding numbering or any fixed presentation format of Advocate's reply, and it leaves the repository unchanged. Output shall include `advocateOutput: <verbatim final text>`.
- `noFindings`: Advocate affirmatively reported that the design is ready for sign-off with no findings; this outcome does not depend on finding numbering or any fixed presentation format of Advocate's reply, and it leaves the repository unchanged.

### DESIGN-3

When Architect has revised the design after the first review round, at the second review round, Captain shall prompt Advocate:

> This is the second and final design review round.
> The Architect revised the draft in response to your earlier findings; the complete revised draft is below and is not yet in the repository.
> Check that each earlier finding is resolved or that leaving it unapplied is reasoned, then review the revised design as a whole.
>
> You are the Advocate, speaking for the client: review the design as the client would before signing it off.
> Check that the options are real alternatives, not straw men set beside the recommendation.
> Check that the recommendation's trade-offs in effort, risk, and user impact are stated honestly.
> Check that every spec item is testable and matches the brief: nothing the brief asks for is missing and nothing it does not ask for is added.
> Return numbered findings, each naming the record section or spec item and what the client would object to.
> Raise only what the client would materially object to; if nothing remains, say plainly that the design is ready for sign-off.
> Do not edit files or commit.
>
> > Feature brief: <caller-input>
> > Your earlier findings: <advocate-output>
> > Architect revised draft: <architect-output>

Results:
- `hasFindings`: Advocate returned one or more findings; this outcome does not depend on finding numbering or any fixed presentation format of Advocate's reply, and it leaves the repository unchanged. Output shall include `advocateOutput: <verbatim final text>`.
- `noFindings`: Advocate affirmatively reported that the design is ready for sign-off with no findings; this outcome does not depend on finding numbering or any fixed presentation format of Advocate's reply, and it leaves the repository unchanged.

### DESIGN-4

A revision after the first review round leads to the second review round.

When Advocate returns findings in the first review round, Captain shall prompt Architect:

> The Advocate reviewed your draft design as the client would; your current draft and the findings are below.
> Address every finding in the decision record and its spec items; if a finding conflicts with the brief or with the account lead's answers recorded in the decision record, leave it unapplied and say why.
> Keep the options, the trade-offs table, the recommendation, and the spec items consistent with each other after your changes.
> Do not write, edit, or create any file in the repository, and do not commit.
> First list what you changed for each finding and each finding you left unapplied with the reason; then reply with the complete revised draft in the same form as your current draft, exact enough to be written to the repository unchanged.
>
> > Feature brief: <caller-input>
> > Current draft: <architect-output>
> > Advocate findings: <advocate-output>

Results:
- `revised`: Architect replied with the complete revised draft and left the repository unchanged. Output shall include `architectOutput: <verbatim final text>`.

### DESIGN-5

A revision after the second review round leads to sign-off without another review.

When Advocate returns findings in the second review round, Captain shall prompt Architect:

> The Advocate reviewed your revised draft as the client would in the final review round; your current draft and the findings are below.
> No further review follows: the next step is the account lead's sign-off.
> Address every finding in the decision record and its spec items; if a finding conflicts with the brief or with the account lead's answers recorded in the decision record, leave it unapplied and say why.
> Keep the options, the trade-offs table, the recommendation, and the spec items consistent with each other after your changes.
> Do not write, edit, or create any file in the repository, and do not commit.
> First list what you changed for each finding and each finding you left unapplied with the reason; then reply with the complete revised draft in the same form as your current draft, exact enough to be written to the repository unchanged.
>
> > Feature brief: <caller-input>
> > Current draft: <architect-output>
> > Advocate findings: <advocate-output>

Results:
- `revised`: Architect replied with the complete revised draft and left the repository unchanged. Output shall include `architectOutput: <verbatim final text>`.

### DESIGN-6

The account lead's answer resumes this same behavior, and Captain retains the account lead's complete reply to the sign-off question as <sign-off-reply>.

When Advocate reports no findings in either review round, or Architect has revised the design after the second review round, Captain shall ask the account lead:

> Show the account lead the Architect's latest draft below, then ask exactly one question: "Approve this design?"
> Wait for the account lead's answer; do not decide on their behalf.
>
> > Architect draft: <architect-output>

Results:
- `approved`: The account lead's answer approves the design. A reply that neither approves nor rejects the design supports no sign-off outcome.
- `rejected`: The account lead's answer rejects the design. A reply that neither approves nor rejects the design supports no sign-off outcome.

### DESIGN-7

On completion, `design` shall return the commit, taken from the repository-effect receipt, and the decision record's ID.

When the account lead approves the design, Captain shall prompt Architect:

> The account lead approved the draft design below.
> Write it to the repository exactly as drafted, changing only the decision record's Status to Accepted; if its record number has been taken since drafting, use the next free number and say so.
> Commit the decision record and its spec items, with @specs/map.md if the draft changes it, in exactly one new commit on the current branch, following @specs/packages/git.md; include no unrelated changes, and never amend or rewrite an existing commit.
> Credit every AI that contributed to this commit: Architect <architect-llm> as coder and Advocate <advocate-llm> as reviewer.
> Report the commit hash and the decision record's ID.
>
> > Feature brief: <caller-input>
> > Approved draft: <architect-output>

Results:
- `committed`: Architect wrote the approved draft and made one new commit holding the decision record and its spec items. Output shall include `latestCommit: <commit identity>` and `recordId: <decision record ID>`.

### DESIGN-8

On completion, `design` shall commit nothing and shall return the account lead's reason and the final draft.

When the account lead rejects the design, Captain shall prompt Architect:

> The account lead rejected the draft design below; their answer follows it.
> Do not write any file and do not commit.
> Report the account lead's reason for the rejection, in their own words where they gave one; then reply with the complete final draft unchanged, so the account lead can revise it.
>
> > Final draft: <architect-output>
> > Account lead's answer: <sign-off-reply>

Results:
- `notCommitted`: Architect made no commit and reported the account lead's reason and the final draft, leaving the repository unchanged. Output shall include `rejectionReason: <the account lead's reason>` and `finalDraft: <the complete final draft>`.
