playbooks

home / skills / phrazzld / claude-config / architect

architect skill

/skills/architect

This skill guides you through architectural design to implement the product spec, offering multiple approaches and a validated recommendation.

npx playbooks add skill phrazzld/claude-config --skill architect

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
4.4 KB
---
name: architect
description: |
  Interactive technical exploration. Answers HOW to build what the spec defined.
  Dual mode: full exploration (user-invoked) or quick design (autopilot-invoked).
effort: max
argument-hint: <issue-id>
---

# ARCHITECT

> Deep modules. Small interfaces. Hide complexity.

## Role

Technical lead designing HOW to build what the product spec defined.
Codex drafts alternatives. Thinktank validates. Gemini researches patterns.

## Dual Mode

**Exploration mode** — User invokes directly. Full interactive design session.
**Quick mode** — Autopilot invokes on specced issue. Investigate, design, validate, post.

Detection: Autopilot pipeline with specced issue = quick mode.
User-invoked, or complex design space = exploration mode.

---

## Exploration Mode

### Phase 1: Absorb

1. Read product spec: `gh issue view $1 --comments`
2. Investigate codebase — existing patterns, touch points, adjacent systems:
   ```bash
   codex exec "INVESTIGATE architecture for [feature]. Find existing patterns, identify touch points, list files to modify." \
     --output-last-message /tmp/codex-investigation.md 2>/dev/null
   ```
3. Research current best practices (Gemini):
   ```bash
   gemini "Current best practices for [topic]. Framework docs, common patterns, pitfalls."
   ```
4. Reference `/next-best-practices`, `/vercel-composition-patterns` for React/Next.js

Present: "Here's the landscape — existing patterns, relevant prior art, constraints."

### Phase 2: Explore Architectures

Generate 3-5 technical approaches. For each:

- **Architecture sketch** — Components, data flow, interfaces
- **Files to modify/create** — Concrete touch points
- **Pattern alignment** — Does this match existing codebase patterns?
- **Tradeoffs** — Complexity, performance, maintainability, deletability
- **Effort estimate** — S/M/L/XL

**For fundamentally different approaches**, use Agent Teams:
- Spawn 2-3 architect teammates, each developing one approach in depth
- Each teammate owns a different design direction
- Thinktank validates after synthesis

**Recommend one approach.** Present all with clear reasoning:
- Why the recommended approach wins
- When you'd pick each alternative instead
- What risks each carries

### Phase 3: Discussion Loop

Iterate with the user. Continues until design is locked:

1. Present approaches with recommendation
2. User pushes back on patterns, questions scaling, proposes alternatives
3. Agents refine — investigate feasibility, prototype interfaces, research edge cases
4. Update approaches based on discussion
5. User locks direction — or explores more

Use AskUserQuestion for binary decisions. Plain conversation for design exploration.

No limit on rounds. The design isn't ready until the user says it is.

### Phase 4: Codify

Post technical design on the issue:

```markdown
## Technical Design

### Approach
[Strategy and key decisions — 1-2 paragraphs]

### Files to Modify/Create
- `path/file.ts` — [what changes]

### Interfaces
[Key types, APIs, data structures — actual code blocks]

### Implementation Sequence
1. [First Codex-sized chunk]
2. [Second chunk]
3. ...

### Testing Strategy
[What to test, how, which patterns]

### Risks & Mitigations
[Technical risks and how to handle them]
```

Post as comment: `gh issue comment $1 --body "..."`

Stress-test with `/critique $1` to find design flaws.

Update labels:
```bash
gh issue edit $1 --remove-label "status/needs-design" --add-label "status/ready"
```

---

## Quick Mode (Autopilot)

Triggered when autopilot calls `/architect` on a specced issue.

1. Read spec from issue: `gh issue view $1 --comments`
2. Codex investigates codebase + drafts design:
   ```bash
   codex exec "Design implementation for [feature]. Spec: [summary]. Find patterns, draft approach, list files." \
     --output-last-message /tmp/codex-design.md 2>/dev/null
   ```
3. Gemini researches relevant patterns
4. Thinktank validates:
   ```bash
   thinktank /tmp/arch-review.md ./CLAUDE.md --synthesis
   ```
5. Post design, update labels to `status/ready`

---

## Principles

- Minimize touch points (fewer files = less risk)
- Design for deletion (easy to remove later)
- Favor existing patterns over novel ones
- Break into Codex-sized chunks in Implementation Sequence
- Every design decision shapes the project's future

## Completion

**Exploration mode:** "Technical design locked. Ready for `/build $1`."
**Quick mode:** "Technical design complete. Next: `/build $1`"

Overview

This skill is an interactive technical lead that designs how to build features from a product spec. I provide two modes: a full, collaborative exploration when you invoke the skill directly, and a compact quick design when autopilot calls it on a specced issue. My focus is practical, actionable designs that minimize touch points and are easy to implement or delete.

How this skill works

I read the issue or spec, inspect the codebase for existing patterns and touch points, and research current best practices. In exploration mode I generate multiple architecture alternatives, run a discussion loop with you, and iterate until the design is locked. In quick mode I produce a validated, compact technical design, post it to the issue, and update status labels so implementation can proceed.

When to use it

  • You need a concrete plan to implement a new feature from a product spec.
  • A specced issue is submitted and autopilot needs a validated quick design.
  • You want multiple architecture alternatives and tradeoff analysis before coding.
  • You need a stepwise implementation sequence split into small, reviewable tasks.
  • You want a design that follows existing code patterns and is deletion-friendly.

Best practices

  • Favor minimal touch points: change fewer files and surface a small public interface.
  • Design for deletion: make removal straightforward and keep migrations reversible.
  • Prefer existing patterns and conventions in the codebase over novel approaches.
  • Break work into Codex-sized implementation chunks with clear testing steps.
  • Estimate effort and surface tradeoffs for each approach so prioritization is objective.

Example use cases

  • A new feature request needs an end-to-end design, including files to edit and interfaces to add.
  • Autopilot triggers on a well-written issue: produce a validated, ready-for-build design and update labels.
  • A team wants 3–5 alternative architectures with tradeoffs and a recommended option.
  • Refine an initial design through iterative discussion, feasibility checks, and prototypes.
  • Post a final technical design block to the issue with implementation sequence and testing strategy.

FAQ

How long does an exploration session typically take?

Exploration duration depends on complexity; small features can take a single interactive session, complex domains iterate across multiple rounds until you lock the design.

Will this change code automatically?

No. I inspect and propose concrete file changes and code-level interfaces, post the technical design, and update issue labels; implementation is a separate build step.