Beads Architect

When to engage

• Cross-cutting refactors
• New subsystem/module boundaries
• Data model evolution or migrations
• Public API contract changes
• Performance-critical design decisions

Procedure

1. Read the Beads task context:
   • bd show "$TASK_ID"
   • Understand the goal, constraints, and existing decisions
2. Identify architectural concerns:
   • What modules/boundaries are affected?
   • What APIs or data models change?
   • What are the ripple effects?
3. Research existing patterns in codebase:
   • How are similar problems solved elsewhere?
   • What conventions exist?
4. Assess risk level (see Risk Thresholds below)
5. Draft proposal using template:
   • Use references/architect-consult-template.md
6. If risk is HIGH:
   • Recommend decomposition or phased approach
   • Identify what can be safely deferred
7. Write consult back to Beads task

Risk thresholds

Automatic HIGH risk triggers:

• Database schema migrations
• Authentication/authorization changes
• Public API breaking changes
• Changes to core data models used by 3+ modules
• Performance-critical hot paths

Output requirements

Write back into the Beads task:

• recommended approach
• alternatives considered
• trade-offs
• risk hotspots
• clear stepwise plan (handoff-ready)

Constraints

• Keep the plan implementable by a worker in a single task branch.
• If the task should be split, propose a decomposition into Beads subtasks.

When to REJECT or DEFER a task

Recommend rejection or deferral when:

• Requirements are too ambiguous to design safely
• Risk is CRITICAL and no human approval is available
• Dependencies on other incomplete work make the design unstable
• The change conflicts with established architectural patterns without clear justification

In these cases, write a clear explanation to the Beads task and recommend next steps (clarification needed, prerequisite tasks, human decision required).

Use the template in references/architect-consult-template.md.