# 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.

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

```markdown
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.
```

Captain shall append the brief in quotes (`>`):

> Feature brief: <caller-input>

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

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

```markdown
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.
```

Captain shall append the round's context in quotes (`>`):

> Feature brief: <caller-input>
> Architect draft: <architect-output>

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

```markdown
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.
```

Captain shall append the round's context in quotes (`>`):

> Feature brief: <caller-input>
> Your earlier findings: <advocate-output>
> Architect revised draft: <architect-output>

At the start of every review round, Captain shall append the following instruction to the end of the prompt:

```markdown
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.
```

Each review round has two outcomes: `hasFindings`, where Advocate returned one or more findings, with `advocateOutput: <verbatim final text>`; and `noFindings`, where Advocate affirmatively reported that the design is ready for sign-off with no findings.
Neither outcome depends on finding numbering or any fixed presentation format of Advocate's reply, and both leave the repository unchanged.

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

```markdown
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.
```

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

```markdown
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.
```

In both review rounds, Captain shall append the draft and findings in quotes (`>`):

> Feature brief: <caller-input>
> Current draft: <architect-output>
> Advocate findings: <advocate-output>

Each revision has one outcome, `revised`: Architect replied with the complete revised draft and left the repository unchanged, with `architectOutput: <verbatim final text>`.
A revision after the first review round leads to the second review round; a revision after the second review round leads to sign-off without another review.

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.

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>`.

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>`.
