AgentSkillsCN

beads-architect

为Beads任务提供架构指导：提出方法论、明确边界与权衡取舍，并制定可供其他智能体执行的实施方案。适用于进行架构决策、跨领域重构、API设计，或数据模型调整时使用。

SKILL.md
--- frontmatter
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.

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 LevelCriteriaRecommendation
LOWSingle module, no API changes, < 5 filesProceed with standard worker implementation
MEDIUM2-3 modules, internal API changes, 5-20 filesDetailed plan required, consider phased approach
HIGH4+ modules, public API changes, > 20 filesRecommend decomposition into subtasks
CRITICALData migrations, breaking changes, security-sensitiveRequire 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.