| name | arch:design-review |
| argument-hint | [issue_number] |
| description | Posts design artefacts listed in design.yaml to GitHub one at a time, polls the issue for a reviewer reply, handles rejections with clarification comments, and marks the story ready-for-dev when all artefacts are approved. Fully driven through GitHub comments — no re-run required.
|
| context | fork |
| allowed-tools | ["Read","Bash","Write"] |
| write-paths | ["docs/"] |
Design Review Orchestrator
Manages the GitHub review and approval loop for all design artefacts produced by the
architect. Posts each artefact as a separate GitHub comment, then polls the issue for
a reviewer reply before posting the next one. The entire approval conversation happens
inside the GitHub issue — no re-run needed between artefacts.
Callable standalone (after manual edits to any artefact) or from
/arch:design-implementation.
Invocation:
/arch:design-review 460 # for a specific issue
/arch:design-review # uses $AGENT_DOCS_DIR/active-story.yaml
Constraints
- Write:
docs/ only (updates design.yaml approval state)
- Read: everything else — read-only
- Does not modify artefact files — only tracks approval state
- Does not self-approve; requires a non-bot commenter (issue author may approve)
Workflow
Step 1 — Resolve issue number
if [ -n "$ARGUMENT" ]; then
ISSUE_NUMBER="$ARGUMENT"
else
ISSUE_NUMBER=$(yq e '.issueNumber' "${AGENT_DOCS_DIR:-docs}/active-story.yaml" 2>/dev/null)
fi
if [ -z "$ISSUE_NUMBER" ] || [ "$ISSUE_NUMBER" = "null" ]; then
echo "ERROR No issue number. Pass one or run /github:story-fetch first."
exit 1
fi
REPOSITORY=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
DESIGN_YAML="docs/stories/${ISSUE_NUMBER}/design.yaml"
Guard: if $DESIGN_YAML does not exist → exit with error:
ERROR design.yaml not found: docs/stories/{id}/design.yaml
Run /arch:design-implementation {id} first to generate design artefacts.
Step 2 — Read design.yaml
Parse design.yaml to get:
design.artefacts[] — full list with id, type, file, rationale, comment_id, approval_statusdesign.approval_summary
If all artefacts already have approval_status: approved:
arch:design-review: all artefacts already approved — nothing to do
Exit 0.
Step 3 — Post summary comment (first run only)
If this is the first run (no summary comment previously posted — check by searching issue
comments for <!-- design-implementation-summary -->):
<!-- design-implementation-summary -->
## Architecture Design Summary — Issue #{issue_number}
**{N} artefact(s) require approval before development can start.**
| # | Type | File | Status |
|---|------|------|--------|
| 1 | {type_label} | {file_path} | Pending |
...
**Reviewers:** reply `approved` (or `lgtm` / `yes`) or `rejected: <reason>` on each
artefact comment to proceed through the review.
Apply label architecture-in-review:
gh label create "architecture-in-review" --color "0075ca" --repo $REPOSITORY 2>/dev/null || true
gh issue edit $ISSUE_NUMBER --repo $REPOSITORY --add-label "architecture-in-review"
Step 4 — Artefact loop (repeat until all approved or a rejection exits)
Repeat the following sub-steps for each artefact in priority order:
4a — Gate check
Only proceed if every previously posted artefact has approval_status: approved. If any
artefact is still pending or rejected, skip to Step 5 (status report) and exit.
Find the first artefact in design.artefacts[] order where comment_id is null and
approval_status is not rejected. If none exists, all are posted — go to Step 4c
(poll the last pending one) or Step 5 if none are pending.
4b — Post the artefact comment
Read the artefact file content.
Format the comment body:
<!-- design-approval-{artefact_id} -->
## Design Review: {type_label} — {artefact_id}
**Story:** #{issue_number} | **File:** `{file_path}`
**Rationale:** {rationale from design.yaml}
---
{file content inline:
- ```mermaid fence for diagram_c4 / diagram_erd / diagram_flow
- ```yaml fence for api_openapi / api_asyncapi / adr / implementation_plan
}
---
Reply **`approved`** (or `lgtm` / `yes`) to proceed, or **`rejected: <reason>`** to
request changes.
_Generated by /arch:design-review on {YYYY-MM-DD} — artefact {N} of {total}_
Type labels: adr → ADR | diagram_c4 → C4 Container Diagram | diagram_erd → ERD Diagram |
diagram_flow → Flow Diagram | api_openapi → OpenAPI Contract | api_asyncapi → AsyncAPI Contract |
implementation_plan → Implementation Plan
Post the comment and capture the ID and creation timestamp:
COMMENT_URL=$(gh issue comment $ISSUE_NUMBER \
--repo $REPOSITORY \
--body "$COMMENT_BODY" \
--json url --jq '.url')
COMMENT_ID=$(echo "$COMMENT_URL" | grep -oE '[0-9]+$')
ARTEFACT_POSTED_AT=$(gh api \
"repos/${REPOSITORY}/issues/comments/${COMMENT_ID}" \
--jq '.created_at')
Update design.yaml — set comment_id: {COMMENT_ID} for the artefact.
4c — Poll for reviewer reply
Identify the bot user (excluded from approval authority):
BOT_USER=$(gh api user --jq '.login' 2>/dev/null || echo "")
Poll in a loop until a qualifying reply appears. Between each check, sleep 30 seconds.
Print a status line each iteration:
arch:design-review: waiting for review of {artefact_id} … (elapsed: {Nm})
On each iteration:
REPLIES=$(gh api "repos/${REPOSITORY}/issues/${ISSUE_NUMBER}/comments" \
--jq "[.[] | select(
.created_at > \"${ARTEFACT_POSTED_AT}\"
and .user.login != \"${BOT_USER}\"
)]")
Scan each reply body (trimmed, leading whitespace removed) for signals:
Approval signal matches ^(approved|lgtm|yes)\b (case-insensitive) → go to 4d.
Rejection signal matches ^(rejected|changes requested|nack|no)[:\s.] (case-insensitive) → go to 4e.
Continue polling if no signal found.
4d — On approval
Update design.yaml:
approval_status: approved
approved_by: "{commenter_login}"
approved_at: "{comment_created_at}"
Update approval summary (Step 5). Loop back to 4a for the next artefact.
4e — On rejection
Set approval_status: rejected in design.yaml. Reset comment_id: null (forces
reposting on next run after revision).
Post clarification comment:
<!-- design-clarification-{artefact_id} -->
## Design Clarification Needed — {artefact_id}
Feedback received:
> {rejection_reason}
**Next steps:**
1. Revise `{file_path}` based on the feedback above
2. Re-run `/arch:design-review {id}` to repost the updated artefact for re-review
_Awaiting response before this story can proceed to development._
Update approval summary (Step 5). Exit the loop — do not post the next artefact.
Step 5 — Update approval summary in design.yaml
approval_summary:
total_artefacts: {N}
approved: {count approved}
pending: {count pending}
rejected: {count rejected}
ready_for_dev: {true if approved == total_artefacts}
Step 6 — Complete or exit
If approved == total_artefacts:
gh label create "ready-for-dev" --color "0e8a16" --repo $REPOSITORY 2>/dev/null || true
gh issue edit $ISSUE_NUMBER --repo $REPOSITORY \
--add-label "ready-for-dev" \
--remove-label "architecture-in-review"
Post final summary:
<!-- design-approved -->
## All Design Artefacts Approved — Issue #{issue_number}
All {N} design artefacts have been approved. Story is ready for development.
| Artefact | Approved By | At |
|----------|-------------|----|
| {id} | {reviewer} | {timestamp} |
Next: assign the story and start implementation.
Update design.yaml:
status: approved
If a rejection was recorded in Step 4e: Print status table and exit.
arch:design-review: issue #{id} — review paused on rejection
[x] adr-0014 — approved by alice (2026-03-29 14:03)
[!] c4-container — rejected by bob (2026-03-29 14:21)
[ ] api-payments — queued
[ ] implementation-plan — queued
Revise {file_path}, then re-run /arch:design-review {id}.
Output
Updates docs/stories/{id}/design.yaml with comment_id, approval_status, approved_by, approved_at for each artefact.
No new files written — artefact files are read-only from this skill's perspective.
Error Handling
| Condition | Behaviour |
|---|
design.yaml missing | Error: run /arch:design-implementation first |
gh auth unavailable | Print gh auth login instructions and exit |
| Comment post fails | Log warning; comment_id stays null; retried on next run |
| All artefacts already approved | Print status and exit 0 |
Related Skills
| Skill | Role |
|---|
/arch:design-implementation | Orchestrator — calls this skill as final step |
/arch:openapi-contract | Produces api_openapi artefacts reviewed here |
/arch:asyncapi-contract | Produces api_asyncapi artefacts reviewed here |
/arch:implementation-plan | Produces implementation_plan artefact reviewed here |
/arch:adr-yaml + /arch:adr-render | Produce adr artefacts reviewed here |
/github:mermaid-diagram | Produces diagram artefacts reviewed here |
