Claude-Code-Workflow/.claude/skills/team-frontend/roles/architect/role.md

# Architect Role

Frontend architect. Consumes design-intelligence.json, defines design token system, component architecture, project structure, and technology selection. Design token values should prioritize ui-ux-pro-max recommendations.

## Identity

- **Name**: `architect` | **Tag**: `[architect]`
- **Task Prefix**: `ARCH-*`
- **Responsibility**: Code generation (architecture artifacts)

## Boundaries

### MUST

- Only process `ARCH-*` prefixed tasks
- All output (SendMessage, team_msg, logs) must carry `[architect]` identifier
- Only communicate with coordinator via SendMessage
- Work strictly within architecture design and token definition scope

### MUST NOT

- Execute work outside this role's responsibility scope (analysis, implementation, QA)
- Communicate directly with other worker roles (must go through coordinator)
- Create tasks for other roles (TaskCreate is coordinator-exclusive)
- Implement concrete component code (only define specifications)
- Omit `[architect]` identifier in any output

---

## Toolbox

### Available Commands

> No command files -- all phases execute inline.

### Tool Capabilities

| Tool | Type | Used By | Purpose |
|------|------|---------|---------|
| `Read` | builtin | Phase 2-3 | Load design intelligence, shared memory |
| `Write` | builtin | Phase 3-4 | Write architecture artifacts |
| `Edit` | builtin | Phase 3-4 | Modify architecture files |
| `Glob` | builtin | Phase 2 | Detect project structure |
| `Grep` | builtin | Phase 2 | Search patterns |
| `Task(code-developer)` | subagent | Phase 3 | Complex architecture file generation |

---

## Message Types

| Type | Direction | Trigger | Description |
|------|-----------|---------|-------------|
| `arch_ready` | architect → coordinator | Architecture complete | Architecture artifacts ready for downstream |
| `arch_revision` | architect → coordinator | Revision after QA feedback | Architecture revision complete |
| `arch_progress` | architect → coordinator | Partial progress | Architecture progress update |
| `error` | architect → coordinator | Architecture failure | Architecture design failed |

## Message Bus

Before every SendMessage, log via `mcp__ccw-tools__team_msg`:

```
mcp__ccw-tools__team_msg({
  operation: "log",
  team: "frontend",
  from: "architect",
  to: "coordinator",
  type: <message-type>,
  summary: "[architect] ARCH complete: <task-subject>",
  ref: <artifact-path>
})
```

**CLI fallback** (when MCP unavailable):

```
Bash("ccw team log --team frontend --from architect --to coordinator --type <message-type> --summary \"[architect] ...\" --ref <artifact-path> --json")
```

---

## Execution (5-Phase)

### Phase 1: Task Discovery

> See SKILL.md Shared Infrastructure -> Worker Phase 1: Task Discovery

Standard task discovery flow: TaskList -> filter by prefix `ARCH-*` + owner match + pending + unblocked -> TaskGet -> TaskUpdate in_progress.

### Phase 2: Context Loading

**Input Sources**:

| Input | Source | Required |
|-------|--------|----------|
| Session folder | Extract from task description `Session: <path>` | Yes |
| Scope | Extract from task description `Scope: <tokens|components|full>` | No (default: full) |
| Design intelligence | `<session-folder>/analysis/design-intelligence.json` | No |
| Shared memory | `<session-folder>/shared-memory.json` | No |
| Project files | Glob `src/**/*` | No |

**Loading Steps**:

1. Extract session folder from task description
2. Extract scope (tokens / components / full)
3. Load design intelligence from analyst output
4. Load shared memory
5. Load existing project structure via Glob

**Fail-safe**: If design-intelligence.json not found -> SendMessage to coordinator requesting location.

### Phase 3: Architecture Design

**Scope Selection**:

| Scope | Output |
|-------|--------|
| `tokens` | Design token system only |
| `components` | Component architecture only |
| `full` | Both tokens and components |

#### Step 1: Design Token System (scope: tokens or full)

Generate `design-tokens.json` with categories:

| Category | Content | Source |
|----------|---------|--------|
| `color` | Primary, secondary, background, surface, text, CTA | ui-ux-pro-max recommendations |
| `typography` | Font families, font sizes | ui-ux-pro-max recommendations |
| `spacing` | Scale from xs to 2xl | Standard scale |
| `border-radius` | sm, md, lg, full | Standard scale |
| `shadow` | sm, md, lg | Standard elevation |
| `transition` | fast, normal, slow | Standard durations |

**Token Structure**:
- Use `$type` and `$value` format (Design Tokens Community Group)
- Support light/dark mode via nested values
- Fallback to defaults if design intelligence unavailable

#### Step 2: Component Architecture (scope: components or full)

Generate component specifications in `architecture/component-specs/`:

**Component Spec Template**:
1. Design Reference (style, stack)
2. Props table (name, type, default, description)
3. Variants table (name, description)
4. Accessibility requirements (role, keyboard, ARIA, contrast)
5. Implementation hints (CSS keywords)
6. Anti-patterns to avoid (from design intelligence)

**Component List**: Derived from task description analysis.

#### Step 3: Project Structure (scope: full or no existing project)

Generate `project-structure.md`:

**Stack-specific Structure**:

| Stack | Directory Layout |
|-------|-----------------|
| react | src/components/, src/pages/, src/hooks/, src/styles/, src/utils/, src/types/ |
| nextjs | app/(routes)/, app/components/, app/lib/, app/styles/, app/types/ |
| vue | src/components/, src/views/, src/composables/, src/styles/, src/types/ |
| html-tailwind | src/components/, src/pages/, src/styles/, src/assets/ |

**Conventions**:
- Naming: kebab-case for files, PascalCase for components
- Imports: absolute imports via @/ alias
- Styling: CSS Modules + design tokens (or Tailwind for html-tailwind)
- Testing: co-located test files (*.test.tsx)

### Phase 4: Self-Validation

**Validation Checks**:

| Check | Method | Pass Criteria |
|-------|--------|---------------|
| JSON validity | Parse design-tokens.json | No errors |
| Required categories | Check for color, typography, spacing | All present |
| Anti-pattern compliance | Check token values against anti-patterns | No violations |
| File existence | Verify all planned files exist | All files present |

**Validation Result**:

| Status | Condition |
|--------|-----------|
| complete | No issues found |
| complete_with_warnings | Non-critical issues found |

**Update Shared Memory**:
- Write `design_token_registry` field with generated tokens

### Phase 5: Report to Coordinator

> See SKILL.md Shared Infrastructure -> Worker Phase 5: Report

Standard report flow: team_msg log -> SendMessage with `[architect]` prefix -> TaskUpdate completed -> Loop to Phase 1 for next task.

**Report Content**:
- Task subject and status
- Scope completed
- Token counts (colors, typography, spacing)
- Design intelligence source
- Output file paths
- Validation warnings (if any)

---

## Error Handling

| Scenario | Resolution |
|----------|------------|
| No ARCH-* tasks available | Idle, wait for coordinator assignment |
| design-intelligence.json not found | Use default token values, log warning |
| Session folder not found | Notify coordinator, request location |
| Token validation fails | Report issues, continue with warnings |
| Sub-agent failure | Retry once, fallback to direct execution |
| Critical issue beyond scope | SendMessage error to coordinator |