chipforge

name	chipforge
description	AI-powered FPGA development toolkit. Use when user asks to "check verilog", "run simulation", "analyze waveform", "create knowledge graph", "add signal", "query relations" or "design analysis".
allowed-tools	Bash, Read, Write
user-invocable	true

ChipForge AI

AI-powered FPGA development toolkit for Verilog simulation and design analysis.

---

FPGA Development Workflow (MUST FOLLOW)

When user requests to design/implement a Verilog module, follow this workflow:

Phase 1: Knowledge Graph Setup

1. Initialize knowledge graph: chipforge-kg.exe init <project>
2. Add module nodes with properties (Signal type)
3. Add state machine nodes if applicable (StateTransition type)
4. Add relations between modules (RELATED, STATETRANSITION)

Phase 2: Implementation

5. Create project directory structure: rtl/, tb/
6. Write RTL code in rtl/ directory
7. Write testbench in tb/ directory (include $dumpfile and $dumpvars)

Phase 3: Verification Loop

8. Syntax check → Fix errors if any
9. Compile → Fix errors if any
10. Simulate → Generate VCD
11. Analyze VCD → Check waveforms
12. Fix issues → Repeat from step 8 if needed

Phase 4: Documentation

13. Add simulation results to knowledge graph (SignalExample type)
14. Link results to modules (EXAMPLES relation)
15. Report final status to user

Workflow Diagram

[Init KG] → [Write Code] → [Syntax Check]
                                ↓
                [Fix Code] ← [Errors?]
                    ↓            ↓ No
                   Yes      [Compile]
                    ↑            ↓
                [Fix Code] ← [Errors?]
                                ↓ No
                           [Simulate]
                                ↓
                          [Analyze VCD]
                                ↓
                [Fix Code] ← [Issues?]
                                ↓ No
                         [Update KG] → [Done]

IMPORTANT Rules

• NEVER skip syntax check before simulation
• ALWAYS generate VCD in testbench ($dumpfile, $dumpvars)
• ALWAYS analyze VCD after simulation
• ALWAYS update knowledge graph with results

---

Available Tools (ONLY use these, do NOT guess other tool names)

Tool	Purpose
iverilog.exe	Verilog compiler
vvp.exe	Simulation runtime
vcd2wavedrom.exe	VCD to WaveJSON converter
chipforge-kg.exe	Knowledge graph CLI

Execution Rules (IMPORTANT)

- On Windows, executable paths MUST use backslash `\`, NOT forward slash `/` - The ${SKILL_DIR} variable expands with forward slashes, you MUST convert to backslashes - Conversion: Replace all `/` with `\` in the path - Example: C:/Users/name/.claude/skills/chipforge → C:\Users\name\.claude\skills\chipforge - Source file paths (after cd) can use forward slash: rtl/module.v

Command Format:

cd "<working_dir>" && "<SKILL_DIR_WITH_BACKSLASH>\bin\iverilog\iverilog.exe" -B "<SKILL_DIR_WITH_BACKSLASH>\bin\iverilog\lib\ivl" <args>

Example:

cd "C:/Users/name/project" && "C:\Users\name\.claude\skills\chipforge\bin\iverilog\iverilog.exe" -B "C:\Users\name\.claude\skills\chipforge\bin\iverilog\lib\ivl" -o sim.vvp rtl/module.v tb/testbench.v

Part 1: Verilog Simulation

Syntax Check

cd "<working_dir>" && "<SKILL_DIR_BACKSLASH>\bin\iverilog\iverilog.exe" -B "<SKILL_DIR_BACKSLASH>\bin\iverilog\lib\ivl" -t null rtl/module.v

Compile and Simulate

# Step 1: Compile
cd "<working_dir>" && "<SKILL_DIR_BACKSLASH>\bin\iverilog\iverilog.exe" -B "<SKILL_DIR_BACKSLASH>\bin\iverilog\lib\ivl" -o sim.vvp rtl/module.v tb/testbench.v

# Step 2: Simulate
cd "<working_dir>" && "<SKILL_DIR_BACKSLASH>\bin\iverilog\vvp.exe" sim.vvp

Waveform Analysis (vcd2wavedrom)

Basic usage:

cd "<working_dir>" && "<SKILL_DIR_BACKSLASH>\bin\vcd2wavedrom.exe" -i sim.vcd --top

Parameters:

Param	Description	Example
-i	Input VCD file (required)	-i sim.vcd
-o	Output JSON file	-o wave.json
--top	Include top-level signals	--top
-r	Sample rate in time units	-r 1000
-t	Max time to analyze	-t 100000
-f	Time offset (start from)	-f 10000

Sampling Rate Strategy

Step 1: Run with default (no -r flag) first

Step 2: If no signal changes, use formula: sample_rate = simulation_end_time / 500

Step 3: For specific time range:

cd "<working_dir>" && "<SKILL_DIR_BACKSLASH>\bin\vcd2wavedrom.exe" -i sim.vcd --top -f <start> -t <end> -r <rate>

LIMIT: Do NOT retry more than 2 times.

Part 2: Knowledge Graph

IMPORTANT: Use exact command names below. Do NOT use shortcuts like "add" - use "add-node".

Node Types (use exactly as shown)

• Signal
• StateTransition
• SignalExample

Relation Types (use exactly as shown)

• EXAMPLES
• STATETRANSITION
• RELATED

JSON Props on Windows (IMPORTANT)

PowerShell has complex quote escaping. Use file method for JSON props:

# Step 1: Write JSON to file
echo '{"width":1,"desc":"clock"}' > props.json

# Step 2: Read and pass to command
powershell -Command "$json = Get-Content props.json -Raw; & '${SKILL_DIR}/bin/chipforge-kg.exe' add-node my_project clk Signal $json 2>&1"

Commands Reference

Initialize a graph

powershell -Command "& '${SKILL_DIR}/bin/chipforge-kg.exe' init my_project 2>&1"

Add a node (use file method for JSON on Windows)

# Write props to file first, then:
powershell -Command "$json = Get-Content props.json -Raw; & '${SKILL_DIR}/bin/chipforge-kg.exe' add-node <graph-id> <node-id> <type> $json 2>&1"

Add a relation (no JSON needed)

powershell -Command "& '${SKILL_DIR}/bin/chipforge-kg.exe' add-relation <graph-id> <from-id> <to-id> <relation-type> 2>&1"

Query related nodes (BFS traversal)

powershell -Command "& '${SKILL_DIR}/bin/chipforge-kg.exe' query <graph-id> <node-id> [depth] 2>&1"

List all nodes (optionally filter by type)

powershell -Command "& '${SKILL_DIR}/bin/chipforge-kg.exe' list <graph-id> [type] 2>&1"

Delete node/relation

powershell -Command "& '${SKILL_DIR}/bin/chipforge-kg.exe' delete-node <graph-id> <node-id> 2>&1"
powershell -Command "& '${SKILL_DIR}/bin/chipforge-kg.exe' delete-relation <graph-id> <from> <to> <type> 2>&1"

Update node properties (use file method for JSON)

powershell -Command "$json = Get-Content props.json -Raw; & '${SKILL_DIR}/bin/chipforge-kg.exe' update-node <graph-id> <node-id> $json 2>&1"

---

Cleanup (use cross-platform commands)

After completing tasks, clean up temporary files:

rm -f props.json sim.vvp

DO NOT use Windows-specific commands like del - they fail in Git Bash.

---

Common Mistakes to Avoid

Mistake	Correct Approach
Using \ in paths	Use / forward slash
Using del command	Use rm -f
Retrying waveform analysis >2 times	Use formula: rate = end_time / 500
Running iverilog without cd first	Always cd to working dir first
Using add instead of add-node	Use exact command names