!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,workflow,docs.density,team.size
Resolved above — use as-is; --review overrides review_mode. No block →
defaults in .claude/docs/config-resolution.md.
Architecture Decision
When this skill is invoked:
0. Parse Arguments — Detect Retrofit / Acceptance Mode
See .claude/docs/director-gates.md for the full check pattern. Individual gate definitions live in .claude/docs/director-gates/[gate-id].md — the spawned agent reads its own gate file; do not read it in the parent session.
Every AskUserQuestion call follows .claude/docs/automation-modes.md
(collaborative asks always · guided major-only · autonomous logs and proceeds;
automation_always_ask categories always prompt).
team.size: which agents validate this ADR (orthogonal to review_mode/workflow).
individual (default): technical-director (TD-ADR) + the engine-specialist.small and studio: the same two. This skill spawns no engine
sub-specialist and no adversarial reviewer at any size.
docs.density — it controls the depth of the ADR's prose sections, not
which sections the skeleton emits (that is fixed). modes.rigor sets it
alongside workflow; set docs.density explicitly to vary ADR verbosity alone:
terse (the default, via rigor: minimal) = decision + alternatives as bullets, one line of rationale each;
balanced = paragraph per section with light rationale (rigor: standard); thorough =
full prose with trade-offs and worked rationale in Decision, Alternatives, and
Consequences. Apply it to the prose sections; the Engine Compatibility, ADR
Dependencies, and GDD Requirements tables are structural and stay whole at every
density.
workflow (see .claude/docs/workflow-modes.md):
full — all ADRs on the required ADR list must be completed.standard — critical ADRs only (Foundation-layer systems).minimal — not required. Can still be run voluntarily.
If the argument starts with retrofit followed by a file path
Read references/0-retrofit.md now and follow it — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
If the argument starts with accept followed by an ADR id
Read references/0-accept.md now and follow it — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
If NOT in retrofit or acceptance mode, proceed to Step 1 below (normal ADR authoring).
No-argument guard: If no argument was provided (title is empty), ask before
running Phase 0:
"What technical decision are you documenting? Please provide a short title
(e.g., event-system-architecture, physics-engine-choice)."
Use the user's response as the title, then proceed to Step 1.
1. Load Engine Context (ALWAYS FIRST)
Read references/1-engine-context.md now and follow it — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
2. Determine the next ADR number
Scan docs/architecture/ for existing ADRs to find the next number.
3. Gather context
Read references/3-gather-context.md now and follow it — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
4. Guide the decision collaboratively
Read references/4-decide.md now and follow it — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
5. Generate the ADR
Read references/5-generate.md now and follow it — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
6. Closing Next Steps
After the ADR is written (and registry optionally updated), close with AskUserQuestion.
Before generating the widget:
- Read
docs/registry/architecture.yaml — check if any priority ADRs are still unwritten (look for ADRs flagged in technical-preferences.md or systems-index.md as prerequisites)
- Check if all prerequisite ADRs are now written. If yes, include a "Start writing GDDs" option.
- List ALL remaining priority ADRs as individual options — not just the next one or two.
Widget format:
ADR-[NNNN] written and registry updated. What would you like to do next?
[1] Write [next-priority-adr-name] — [brief description from prerequisites list]
[2] Write [another-priority-adr] — [brief description] (include ALL remaining ones)
[N] Start writing GDDs — run `/design-system [first-undesigned-system]` (only show if all prerequisite ADRs are written)
[N+1] Stop here for this session
If there are no remaining priority ADRs and no undesigned GDD systems, offer only "Stop here" and suggest running /architecture-review in a fresh session.
Always include this fixed notice in the closing output (do NOT omit it):
To validate ADR coverage against your GDDs, open a fresh Claude Code session
and run /architecture-review.
Never run /architecture-review in the same session as /architecture-decision.
The reviewing agent must be independent of the authoring context to give an unbiased
assessment. Running it here would invalidate the review.
Do NOT unblock stories here. This ADR is Proposed — Step 5 guarantees it,
and a story blocked pending this decision is still pending it. Unblocking on
authoring is how the deadlock stayed invisible: it defeated the guard at the
moment the guard became relevant, so the pipeline appeared to flow while running
on decisions nobody had accepted.
Instead, tell the user what is now waiting on acceptance:
"ADR-NNNN is written and Proposed. [N] stories remain Blocked pending it.
Run /architecture-decision accept ADR-NNNN when the decision is settled —
that is what moves them to Ready."
List the blocked stories by path so the cost of leaving it Proposed is visible.
(Acceptance has consequences enforced across many skills and an authority
recorded in only a few, so the route between them must stay explicit.)