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 imports/exports (if found) ├── recipe.md # Compile order, filelists └── modules/ # Per-module detail pages └── <module_name>.md ``` --- ## Workflow ### Step 1: Check for Existing Map ```bash ls .gateflow/map/CODEBASE.md 2>/dev/null ``` **If exists:** Check for changes since last map: ```bash # Read last commit from metadata last_commit=$(cat .gateflow/map/.last_scan_commit 2>/dev/null) git diff --name-only $last_commit HEAD -- "*.sv" "*.svh" 2>/dev/null ``` - If no changes: "Map is up to date" - If changes: Proceed with incremental update (only remap changed files) **If not exists:** Proceed to full mapping. ### Step 2: Scan Codebase & Token Budgeting ```bash mkdir -p .gateflow/map/modules ``` **Scan files with token counts:** ```bash find . \( -name "*.sv" -o -name "*.svh" \) -not -path "./.gateflow/*" | while read f; do tokens=$(wc -c < "$f" | awk '{print int($1/4)}') echo "$tokens $f" done | sort -rn ``` **Build assignment table:** | File | Tokens | Assignment | |------|--------|------------| | top.sv | 50000 | Agent 1 | | uart_tx.sv | 8000 | Agent 1 | | hmac_core.sv | 120000 | Agent 2 (LARGE - use Grep) | ### Step 3: Handle Large Files (>80k tokens) **For files exceeding 80k tokens, use chunked analysis:** 1. **Use Grep to extract structure** (don't read full file): ```bash # Get module declaration grep -n "^\s*module\s" large_file.sv # Get ports grep -n "(input|output|inout)" large_file.sv # Get instances grep -n "^\s*\w\+\s\+\w\+\s*(" large_file.sv ``` 2. **Read in sections** using offset/limit: ``` Read file with offset=0, limit=500 (header, ports) Read file with offset=500, limit=500 (logic section 1) ... continue until covered ``` 3. **Assign to dedicated subagent** with Grep-first strategy ### Step 4: Spawn Parallel Subagents **CRITICAL: Spawn ALL subagents in a SINGLE message.** Use Task tool with: - `subagent_type: "Explore"` - (omit model to inherit the user’s session model) **Example - spawn 3 agents in ONE message:** ``` Task 1: description: "Analyze UART files" subagent_type: "Explore" prompt: | Read and analyze these SystemVerilog files: - rtl/uart_pkg.sv - rtl/uart_tx.sv - rtl/uart_rx.sv For EACH file, extract: 1. Module/Package name 2. Purpose (one-line) 3. Ports table: name, direction, width 4. Parameters: name, type, default 5. Instances: what it instantiates 6. FSM states (if any) 7. Clock/Reset signals 8. Package imports Return structured markdown. Task 2: description: "Analyze SHA files" subagent_type: "Explore" prompt: | Read and analyze these SystemVerilog files: - rtl/sha2_pad.sv - rtl/sha2_core.sv [Same extraction request...] Task 3: description: "Analyze large file with Grep" subagent_type: "Explore" prompt: | This file is large. Use Grep to extract structure first: - rtl/hmac_core.sv (120k tokens) 1. Grep for module declaration 2. Grep for ports 3. Grep for instances 4. Read specific sections if needed Return structured markdown. ``` ### Step 5: Synthesize Reports After all subagents complete: 1. **Merge** all reports 2. **Build hierarchy** from instance data 3. **Create diagrams** (Mermaid) 4. **Identify cross-cutting concerns** (clocks, CDC) 5. **Write output files** --- ## Output File Specifications ### CODEBASE.md (Main Index) ```markdown --- last_mapped: YYYY-MM-DDTHH:MM:SSZ total_files: N total_tokens: N commit: abc123 --- # Codebase Map: [Project Name] > Auto-generated by GateFlow Architect ## Quick Stats | Modules | Packages | Interfaces | FSMs | Clocks | |---------|----------|------------|------|--------| | N | N | N | N | N | ## Module Index | Module | Type | File | Ports | |--------|------|------|-------| | uart_ctrl | top | rtl/uart_ctrl.sv | clk,rst_n,tx_*,rx_* | | uart_tx | leaf | rtl/uart_tx.sv | clk,rst_n,data[7:0] | ## Package Index | Package | File | Exports | |---------|------|---------| | uart_pkg | rtl/uart_pkg.sv | state_t, BAUD_RATE | ## Key Files - [Hierarchy](hierarchy.md) - Module tree - [Signals](signals.md) - Port connections - [Clock Domains](clock-domains.md) - CDC analysis - [FSMs](fsm.md) - State machines - [Packages](packages.md) - Dependencies - [Types](types.md) - Structs, enums - [Verification](verification.md) - Assertions ## Navigation Guide **To trace data flow**: Start at top module, follow instances **To add new register**: Modify [module]_reg_top.sv **To add assertion**: See verification.md for patterns ``` ### hierarchy.md ```markdown # Module Hierarchy ## Top Modules Modules never instantiated by others: [list] ## Hierarchy Tree \`\`\`mermaid flowchart TD top[hmac] top --> core[u_core: hmac_core] top --> regs[u_regs: hmac_reg_top] core --> sha[u_sha: sha2_multimode] \`\`\` ## Instance Table | Parent | Instance | Module | Parameters | |--------|----------|--------|------------| | hmac | u_core | hmac_core | - | | hmac | u_regs | hmac_reg_top | - | ``` ### signals.md ```markdown # Signal Flow Analysis ## Port Summary by Module ### hmac_core | Port | Dir | Width | Connected To | |------|-----|-------|--------------| | clk_i | input | 1 | top.clk | | data_o | output | [31:0] | regs.wdata | ## Data Flow Diagram \`\`\`mermaid flowchart LR subgraph Input msg[msg_fifo] end subgraph Core pad[sha2_pad] hash[sha2_core] end subgraph Output digest[digest_reg] end msg --> pad --> hash --> digest \`\`\` ## Unconnected Ports - [none or list] ``` ### clock-domains.md ```markdown # Clock Domain Analysis ## Clocks Detected | Clock | Modules | |-------|---------| | clk_i | all | ## Resets Detected | Reset | Type | Modules | |-------|------|---------| | rst_ni | async active-low | all | ## Clock Domain Map \`\`\`mermaid flowchart LR subgraph clk_i_domain["clk_i domain"] core[hmac_core] regs[hmac_reg_top] end \`\`\` ## CDC Crossings | Source | Dest | Signal | Sync Type | |--------|------|--------|-----------| | [none or list] | ``` ### fsm.md ```markdown # State Machines ## FSM: tx_state in uart_tx **States:** IDLE, START, DATA, STOP **Encoding:** 2-bit \`\`\`mermaid stateDiagram-v2 [*] --> IDLE IDLE --> START: tx_valid START --> DATA: 1 cycle DATA --> DATA: bit_cnt < 7 DATA --> STOP: bit_cnt == 7 STOP --> IDLE: 1 cycle \`\`\` **Transitions:** | From | To | Condition | |------|-----|-----------| | IDLE | START | tx_valid | | START | DATA | always | | DATA | STOP | bit_cnt == 7 | ``` ### packages.md ```markdown # Packages ## uart_pkg **File:** rtl/uart_pkg.sv **Exports:** - Types: state_t, config_t - Parameters: BAUD_RATE, DATA_BITS - Functions: calc_divisor() ## Import Graph \`\`\`mermaid flowchart TD pkg[uart_pkg] tx[uart_tx.sv] -->|import| pkg rx[uart_rx.sv] -->|import| pkg \`\`\` ``` ### types.md ```markdown # Type Definitions ## Structs ### request_t