afc-architect

name	afc:architect
description	Architecture analysis and design review
argument-hint	[analysis target or design question]
context	fork
agent	afc-architect
allowed-tools	["Read","Write","Grep","Glob","Bash","Task","WebSearch"]
model	sonnet

/afc:architect — Architecture Analysis and Design Advice

Analyzes the codebase architecture and records design decisions. Ensures design quality through convergence-based Critic Loop. Does not modify source code. May write ADR files to .claude/afc/memory/decisions/.

Arguments

• $ARGUMENTS — (required) analysis target or design question (e.g., "review state management strategy", "where to add new entity")

Config Load

Read .claude/afc.config.md if CI commands are needed. Architecture, Code Style, and Project Context are auto-loaded via .claude/rules/afc-project.md.

If neither rules file nor config exists: read CLAUDE.md for architecture info. Assume "Layered Architecture" if no source has it.

Execution Steps

1. Determine Scope

Analyze $ARGUMENTS to identify the task type:

Type	Example	Output
Structure Analysis	"timeline module structure"	Dependency map + improvement suggestions
Design Question	"where to put new feature?"	Placement suggestion + rationale
ADR Recording	"Redis vs In-memory decision"	Architecture Decision Record
Refactoring Evaluation	"need to split store?"	Current issues + refactoring plan

2. Explore Codebase

1. Explore relevant directories/files (Glob, Grep, Read)
2. Trace dependency flow (import relationships)
3. Verify {config.architecture} structure
4. Identify existing patterns

Use Agent Teams for wide analysis scope (3+ modules) with parallel exploration:

Task("analyze features/timeline", subagent_type: "Explore")
Task("analyze widgets/timeline", subagent_type: "Explore")

Cross-Module Import Chain Verification (after Explore agents return):

When parallel Explore agents are used, the orchestrator must verify cross-module boundaries that no single agent can see:

1. From each agent's dependency map, extract outbound imports that cross module boundaries
2. For each cross-module import chain (e.g., widget → feature → shared), read the actual import statements at the boundary files
3. Verify against {config.architecture} rules: does the full chain respect layer direction, not just each module's internal imports?
4. Report any cross-module violations not surfaced by individual agents

Do not trust agent-summarized import relationships for cross-boundary chains — re-read the boundary files directly.

3. Write Analysis

Structure analysis results and print to console:

## Architecture Analysis: {topic}

### Current Structure
{dependency map, module relationships, data flow}

### Findings
| # | Area | Current | Suggested | Impact |
|---|------|---------|-----------|--------|
| 1 | {area} | {current approach} | {suggestion} | H/M/L |

### Design Decision (ADR)
**Decision**: {chosen approach}
**Status**: Proposed / Accepted / Deprecated
**Context**: {background}
**Options**:
1. {option1} — Pros: / Cons:
2. {option2} — Pros: / Cons:
**Rationale**: {why this choice}
**Consequences**: {expected impact}

### Architecture Consistency
{config.architecture} rule violations, import direction validation

4. Critic Loop

Read ${CLAUDE_SKILL_DIR}/../../docs/critic-loop-rules.md and follow it. Safety cap: 5 passes.

Criterion	Validation
FEASIBILITY	Is the suggestion achievable in the current codebase?
INCREMENTALITY	Can it be applied incrementally? (avoid big-bang refactoring)
COMPATIBILITY	Is it compatible with existing code? Are there breaking changes?
ARCHITECTURE	Does it comply with {config.architecture} rules?

5. Save ADR (for design decisions)

If ADR type, save to .claude/afc/memory/decisions/{YYYY-MM-DD}-{topic}.md:

# ADR: {title}
- **Date**: {YYYY-MM-DD}
- **Status**: Proposed
- **Context**: {background}
- **Decision**: {choice}
- **Rationale**: {reason}
- **Consequences**: {impact}

6. Final Output

Architecture analysis complete
├─ Type: {structure analysis | design question | ADR | refactoring evaluation}
├─ Findings: {count}
├─ Critic: converged ({N} passes, {M} fixes, {E} escalations)
├─ ADR: {saved | n/a}
└─ Suggestion: {key suggestion in one line}

Notes

• No source modification: Does not modify project source code. May write ADR files to .claude/afc/memory/decisions/.
• Based on actual code: Explore the actual codebase, not assumptions.
• Architecture first: All suggestions respect {config.architecture} rules.
• Incremental changes: Prefer incremental improvements over big-bang refactoring.