| name | arch:design-implementation |
| argument-hint | [issue_number] |
| description | Orchestrates the post-scout design phase. Determines required artefacts, generates ADRs and diagrams, then delegates to arch:openapi-contract, arch:asyncapi-contract, arch:implementation-plan, and arch:design-review. Marks story ready-for-dev once all artefacts are approved.
|
| context | fork |
| allowed-tools | ["Read","Glob","Grep","Bash","Write"] |
| write-paths | ["docs/"] |
Architecture Design Implementation
Post-scout design phase. Runs after /scout:prepare-for-dev. Synthesises all
context (scout report, GitHub story/comments, NFRs, constraints, risks) and
produces design artefacts optimised for non-functional requirements and long-term
risk mitigation. Posts each artefact to GitHub for reviewer approval, then labels
the story ready-for-dev once all artefacts are approved.
Invocation:
/arch:design-implementation 460 # design for a specific issue
/arch:design-implementation # uses $AGENT_DOCS_DIR/active-story.yaml
Constraints
- Write:
docs/ only (all subdirectories) — declared in frontmatter write-paths
- Read: everything else (source, tests, infrastructure, config) — read-only
- Do not change issue status to In Progress
- Do not create implementation branches
- Do not modify an accepted ADR — supersede it with a new one if there is strong evidence
Workflow
Step 1 — Resolve issue number and check resume state
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 found."
echo "Run /github:story-fetch first, or pass an issue number: /arch:design-implementation 123"
exit 1
fi
REPOSITORY=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
DESIGN_YAML="docs/stories/${ISSUE_NUMBER}/design.yaml"
If $DESIGN_YAML already exists, skip to Step 10 (approval poll — skill is resuming).
If $DESIGN_YAML does not exist, proceed to Step 2.
Step 2 — Guard: scout report required
SCOUT_YAML="docs/stories/${ISSUE_NUMBER}/scout.yaml"
if [ ! -f "$SCOUT_YAML" ]; then
echo "ERROR Scout report not found: $SCOUT_YAML"
echo "Run /scout:prepare-for-dev ${ISSUE_NUMBER} before /arch:design-implementation."
exit 1
fi
Step 3 — Load all inputs
Read in order:
docs/stories/{id}/scout.yaml — blast radius, dependencies, architecture review, tasks, open questions- GitHub issue + all comments:
gh issue view $ISSUE_NUMBER --repo $REPOSITORY \
--json title,body,labels,comments \
--jq '{title,body,labels,comments}'
- NFR registry via
/arch:maintain-nfr-registry (read operation)
- Constraints registry via
/arch:maintain-constraints-registry (read operation)
- Risk registry via
/arch:maintain-risk-registry (read operation)
- Each ADR listed under
scout.yaml > architecture.governing_adrs
Extract from scout:
change_list (files + tiers)dependencies (services, paths, confidence)architecture.sufficient, architecture.new_adrtasksopen_questions where owner: architecture
Architecture open questions must be resolved in design.yaml before artefacts are finalised.
Step 4 — Determine required artefacts
Apply each trigger rule. Log the decision (triggered / skipped + reason) for every type.
| Artefact | Trigger |
|---|
| ADR | architecture.sufficient: false OR architecture.new_adr is non-null |
| C4 container diagram | change_list has a file under infrastructure/ or cdk.json, OR a dependency references a new AWS/cloud service not mentioned in any governing ADR |
| ERD diagram | change_list has a file matching *schema*, *model*, *migration*, *dynamodb*, OR story body mentions "data model", "entity", "schema", "table" |
| Flow diagram | tasks has 4+ sequential steps crossing service boundaries, OR story body mentions "workflow", "multi-step", "state machine", "process flow" |
| OpenAPI spec | change_list has a handler/route/controller file AND a new or modified HTTP endpoint is detectable (grep for router., app.get, app.post, handler, @Get, @Post, etc.) |
| AsyncAPI spec | change_list or dependencies mentions SQS, SNS, EventBridge, Kafka, RabbitMQ, or event bus |
Minimum output rule: If no triggers fire, still write design.yaml with artefacts: [] and post a summary comment. The skill always completes — never silently exits.
Step 5 — Generate ADR(s) [conditional]
For each ADR warranted by Step 4:
5a. Invoke /arch:adr-yaml:
- Provide: story title, issue number, decision drivers drawn from NFRs and constraints, options synthesised from scout dependencies and gaps in governing ADRs.
- Do not recreate a decision already covered by an accepted ADR. Supersede only with strong evidence (reference the governing ADR explicitly).
5b. Invoke /arch:adr-render to convert the YAML to $ADR_DIR/NNNN-slug.md.
5c. Record in design.yaml artefacts list with type: adr, both file (YAML) and rendered (Markdown) paths.
Step 6 — Generate diagrams [conditional]
For each triggered diagram type, invoke /github:mermaid-diagram. No inline styles unless emphasising a new or changed node — let the project theme handle colours.
C4 Container Diagram → docs/stories/{id}/design/c4-container.mmd
- Use
graph TB with subgraphs per bounded context.
- Show containers only (services, databases, queues) — not components or code.
- Highlight new/changed containers with
stroke-width:3px.
- Labels: logical names only — no IDs, ARNs, PK/SK patterns, or schema detail.
- Multi-line labels: use
<br/> not \n — \n causes a GitHub mermaid parse error in graph diagrams.
ERD Diagram → docs/stories/{id}/design/erd.mmd
- Use
erDiagram syntax.
- Show only entities directly affected or newly introduced.
- Include attribute types and relationship cardinalities.
Flow Diagram → docs/stories/{id}/design/flow-{slug}.mmd
- Use
flowchart TD.
- Capture the new or modified business process end-to-end, including every external service call as a clearly labelled edge.
{slug} = 2–3 word process name, lowercase hyphenated.
Step 7 — Generate OpenAPI contract [conditional]
Triggered when change_list has a handler/route/controller file AND an HTTP endpoint
is detectable. Delegate entirely to the sub-skill:
invoke /arch:openapi-contract {issue_number}
The sub-skill writes docs/stories/{id}/design/api-{slug}.openapi.yaml and exits.
If no endpoints are detected it exits 0 silently — the orchestrator continues.
Step 8 — Generate AsyncAPI contract [conditional]
Triggered when change_list or dependencies reference SQS, SNS, EventBridge,
Kafka, RabbitMQ, or any event bus. Delegate entirely to the sub-skill:
invoke /arch:asyncapi-contract {issue_number}
The sub-skill writes docs/stories/{id}/design/async-{slug}.asyncapi.yaml and exits.
If no event channels are detected it exits 0 silently.
Step 9 — Produce phased implementation plan
Always runs (every story needs a plan). Delegate to the sub-skill:
invoke /arch:implementation-plan {issue_number}
The sub-skill reads scout.yaml tasks plus any design artefacts written in Steps 5–8,
builds the phased plan (multi-phase mandatory when total tasks > 20), and writes
docs/stories/{id}/design/implementation-plan.yaml.
Step 10 — Write design.yaml and run design review
10a. Create docs/stories/{id}/design/ if it does not exist.
10b. Collect all artefact paths written by Steps 5–9:
- ADRs from Step 5 (YAML + rendered MD paths)
- Diagrams from Step 6 (
.mmd paths)
- OpenAPI spec from Step 7 (if produced)
- AsyncAPI spec from Step 8 (if produced)
- Implementation plan from Step 9
10c. Write docs/stories/{id}/design.yaml with all artefacts listed,
comment_id: null, approval_status: pending for each.
10d. Delegate posting, polling, and label management to the sub-skill:
invoke /arch:design-review {issue_number}
/arch:design-review owns the full GitHub approval loop and applies ready-for-dev
when all artefacts are approved. Re-invoke /arch:design-review {id} directly after
reviewers post approvals — no need to re-run the full orchestrator.
Output Files
| File | Description |
|---|
docs/stories/{id}/design.yaml | Artefact index + approval state (canonical record) |
docs/stories/{id}/design/implementation-plan.yaml | Phased implementation plan with type annotations |
docs/stories/{id}/design/c4-container.mmd | C4 container diagram (Mermaid) |
docs/stories/{id}/design/erd.mmd | Entity/relationship diagram (Mermaid) |
docs/stories/{id}/design/flow-{slug}.mmd | Business process flow diagram (Mermaid) |
docs/stories/{id}/design/api-{slug}.openapi.yaml | OpenAPI 3.1.0 contract |
docs/stories/{id}/design/async-{slug}.asyncapi.yaml | AsyncAPI 2.6 event contract |
$ADR_DIR/NNNN-slug.adr.yaml | ADR YAML (via /arch:adr-yaml) |
$ADR_DIR/NNNN-slug.md | Rendered ADR Markdown (via /arch:adr-render) |
design.yaml Schema
design:
issue: <N>
title: "<issue title>"
designed: "<YYYY-MM-DD>"
status: pending_approval | approved | partial_approval
inputs:
scout_yaml: docs/stories/<N>/scout.yaml
governing_adrs: []
artefacts:
- id: adr-0014
type: adr
file: $ADR_DIR/0014-slug.adr.yaml
rendered: $ADR_DIR/0014-slug.md
rationale: "why this artefact was produced"
comment_id: null
approval_status: pending
approved_by: null
approved_at: null
open_questions_resolved:
- id: 1
question: "..."
resolution: "..."
risks_introduced: []
approval_summary:
total_artefacts: 0
approved: 0
pending: 0
rejected: 0
ready_for_dev: false
Label State Transitions
scouted
↓ (set by scout if needed)
architecture-review-needed
↓ (set by this skill on Step 8)
architecture-in-review
↓ (set by this skill on Step 10 — all approved)
ready-for-dev
Error Handling
| Condition | Behaviour |
|---|
| No active story + no argument | Error: run /github:story-fetch first |
scout.yaml missing | Error: run /scout:prepare-for-dev first |
gh auth unavailable | Print gh auth login instructions and exit |
| ADR child skill fails | Log error, continue remaining artefacts, set approval_status: generation_failed |
| Comment post fails | Log warning, continue; comment_id stays null so next run retries posting |
| All artefacts already approved | Print "already approved" and exit cleanly |
Related Skills
| Skill | Role |
|---|
/scout:prepare-for-dev | Must run before this skill; writes scout.yaml |
/arch:adr-yaml | Called in Step 5 to produce ADR YAML |
/arch:adr-render | Called in Step 5 to render ADR to Markdown |
/github:mermaid-diagram | Called in Step 6 to produce diagrams |
/arch:openapi-contract | Called in Step 7 — generates OpenAPI 3.1.0 spec |
/arch:asyncapi-contract | Called in Step 8 — generates AsyncAPI 2.6 spec |
/arch:implementation-plan | Called in Step 9 — produces phased plan |
/arch:design-review | Called in Step 10 — GitHub approval loop; also callable standalone |
/arch:maintain-nfr-registry | Read in Step 3 to get applicable NFRs |
/arch:maintain-constraints-registry | Read in Step 3 to get hard/soft constraints |
/arch:maintain-risk-registry | Read in Step 3 to get open risks |
