gf-architect

# GF Architect

Maps SystemVerilog codebases using parallel subagents.

**CRITICAL: You orchestrate, Sonnet reads.** Never read codebase files directly. Always delegate file reading to Sonnet subagents - even for small codebases. You plan the work, spawn subagents, and synthesize their reports.

## Agent Count Strategy

| Codebase Tokens | Agents | Rationale |
|-----------------|--------|-----------|
| < 50k | 2 | Minimum for parallelism |
| 50k-300k | 3 | Balance load, related files together |
| 300k-600k | 4-5 | Efficient parallel analysis |
| 600k-1M | 6-8 | Stay under 150k per agent |
| > 1M | 8-10 | Cap at 10, use incremental updates |

**Rules:**
- **Minimum: 2 agents** (always parallelize, even for tiny codebases)
- **Maximum: 10 agents** (diminishing returns, synthesis overhead)
- **Large files (>80k tokens):** Dedicated agent with Grep-first strategy

## Quick Start

1. Check for existing map (incremental update if exists)
2. Scan codebase to get file list with token counts
3. **Determine agent count** using table above
4. Plan subagent assignments (group files, handle large files)
5. Spawn Sonnet subagents in parallel (ALL in single message)
6. Synthesize subagent reports into `.gateflow/map/` files
7. Update `CLAUDE.md` with summary

## Output Structure

```
.gateflow/map/
├── CODEBASE.md          # Main summary (AI-friendly index)
├── hierarchy.md         # Module tree diagram
├── signals.md           # Port and signal flow
├── clock-domains.md     # CDC analysis, resets
├── fsm.md              # State machine diagrams
├── packages.md         # Package dependencies
├── types.md            # Structs, unions, typedefs
├── functions.md        # Functions and tasks
├── macros.md           # Preprocessor directives
├── verification.md     # SVA, coverage, checkers
├── interfaces.md       # Interfaces, modports (if found)
├── classes.md          # UVM/OOP classes (if found)
├── generate.md         # Generate blocks (if found)
├── dpi.md              # DPI impo