Gf Architect

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

ls .gateflow/map/CODEBASE.md 2>/dev/null

If exists: Check for changes since last map:

# 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

mkdir -p .gateflow/map/modules

Scan files with token counts:

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:

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):

# 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)

---
last_mapped: YYYY-MM-DDTHH:MM:SSZ
total_files: N
total_tokens: N