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

- Skill: `vega113/beads-architect` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds add vega113/beads-architect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vega113/beads-architect/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: vega113 (https://skillmd.com/u/vega113)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/vega113/beads-architect

---


# Beads Architect (Consult)

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

## Parallel architect stage
- Pick a ready task and claim it by updating its state/tag (e.g., `bd update "$TASK_ID" state=architecting`). Mark the rest of the team when you start so other architects can choose different tasks in parallel.
- Use `scripts/tmux-orchestrator.sh add-worker "$TASK_ID" "<command>"` to create a dedicated tmux pane for your plan work; include the path/commands needed to work on the repo.
- Once the plan is ready, post an **Architect Plan** update (see `beads-orchestrator/references/beads-update-templates.md`), include acceptance criteria and milestones, and set the task to `state=plan-ready` before handing it back for implementation.
- Signal completion by leaving a status update and tagging the task (e.g., `bd update "$TASK_ID" state=plan-ready`). The orchestrator checks for this before starting the worker.

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