# beads-architect

> Provide architectural guidance for Beads tasks: propose approach, boundaries, trade-offs, and an implementation plan that other agents can execute. Use when making architecture decisions, cross-cutting refactors, API design, or data model changes.

- Author: Yuri Z.
- Repository: vega113/beads-orchestration-skills
- Version: 20260126210500
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/vega113/beads-orchestration-skills
- Web: https://mule.run/skillshub/@@vega113/beads-orchestration-skills~beads-architect:20260126210500

---

---
name: beads-architect
description: "Provide architectural guidance for Beads tasks: propose approach, boundaries, trade-offs, and an implementation plan that other agents can execute. Use when making architecture decisions, cross-cutting refactors, API design, or data model changes."
compatibility: Requires Beads CLI (bd)
read_when:
  - architecture decision
  - cross-cutting refactor
  - API design
  - data model change
  - module boundaries
  - system design
  - migration planning
metadata:
  short-description: "Architecture consult role for cross-cutting changes"
  version: "0.1.0"
---

# Beads Architect (Consult)

## Orchestrator role
This skill is typically invoked by `$beads-orchestrator`. Users normally start with the orchestrator, not this role.

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

| Risk Level | Criteria | Recommendation |
|------------|----------|----------------|
| **LOW** | Single module, no API changes, < 5 files | Proceed with standard worker implementation |
| **MEDIUM** | 2-3 modules, internal API changes, 5-20 files | Detailed plan required, consider phased approach |
| **HIGH** | 4+ modules, public API changes, > 20 files | Recommend decomposition into subtasks |
| **CRITICAL** | Data migrations, breaking changes, security-sensitive | Require human review before proceeding |

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