RTL Pipeline Orchestrator

This skill IS the plan — execute each stage immediately using Read/Write/Bash/Agent tools. Do NOT plan before executing.

Project directory path: $PROJECT_DIR

If $PROJECT_DIR is empty, ask the user for it.

Optional flags:

• --benchmark — After the pipeline completes, automatically run benchmark_runner.py and generate a JSON report at logs/benchmark_report.json.

Variable: ${CLAUDE_SKILL_DIR} is set by Claude Code to the skill's installed directory.

Argument parsing (run once at the top):

# Parse $ARGUMENTS: project_dir [flags]
# e.g. "/path/to/project" or "/path/to/project --benchmark"
PROJECT_DIR="${ARGUMENTS%%--*}"
PROJECT_DIR="$(echo "$PROJECT_DIR" | xargs)"  # trim trailing space
RUN_BENCHMARK=""
if echo "$ARGUMENTS" | grep -q "\-\-benchmark"; then
    RUN_BENCHMARK="1"
fi

Step 0: Initialization

Run the initialization script:

PY_INIT="${PYTHON_EXE:-python}"
cd "$PROJECT_DIR" && "$PY_INIT" "${CLAUDE_SKILL_DIR}/init.py" "$PROJECT_DIR"
[ -f "$PROJECT_DIR/.veriflow/eda_env.sh" ] && source "$PROJECT_DIR/.veriflow/eda_env.sh"

Read the output to determine: new project or resuming. If resuming, skip stages in stages_completed.

Stale-Stage Recovery (resume only)

When resuming, if a stage is STARTED but not COMPLETE, the pipeline may have been interrupted or crashed. Before re-dispatching that stage, check if the output files already exist by looking for completion markers (.veriflow/done_<stage>*):

cd "$PROJECT_DIR"
# For spec_golden: check if both outputs exist and marker is present
if [ -f ".veriflow/done_spec_golden" ] && [ -f "workspace/docs/spec.json" ] && [ -f "workspace/docs/golden_model.py" ]; then
    echo "[RECOVERY] spec_golden outputs exist — running hook to mark complete"
    python3 "${CLAUDE_SKILL_DIR}/state.py" "$PROJECT_DIR" "spec_golden" \
        --hook="test -f workspace/docs/spec.json && test -f workspace/docs/golden_model.py"
fi

# For codegen: check if ALL module .v files and TB files exist
if ls .veriflow/done_codegen_* >/dev/null 2>&1; then
    echo "[RECOVERY] codegen completion markers found — verifying outputs"
    python3 "${CLAUDE_SKILL_DIR}/state.py" "$PROJECT_DIR" "codegen" \
        --hook="ls workspace/rtl/*.v >/dev/null 2>&1 && (test -f workspace/tb/test_*.py || test -f workspace/tb/tb_*.v)" \
        --journal-outputs="workspace/rtl/*.v, workspace/tb/test_*.py, workspace/tb/tb_*.v" \
        --journal-notes="Recovered from interrupted codegen via completion markers"
fi

If the hook passes, the stage is marked COMPLETE and the pipeline advances. If it fails, stale markers are cleaned up and the stage is re-dispatched normally:

rm -f .veriflow/done_codegen_* .veriflow/done_spec_golden .veriflow/done_tb_gen

Permission Check (sub-agent tools)

Sub-agents cannot interact with the user — any permission prompt will hang the pipeline. Check that the following tools are pre-approved in the project's .claude/settings.json:

Heads-up — the allow-list below is the minimum. Sub-agents also run shell commands like source, cd, iverilog, vvp, yosys, mkdir, ls, xargs. Those are NOT auto-added here because the right scope is environment- dependent. Two ways to keep the pipeline from hanging on a permission prompt:

1. Launch Claude Code with --permission-mode acceptEdits (or rely on ~/.claude/settings.json setting skipDangerousModePermissionPrompt: true).
2. Or, extend .claude/settings.json allow-list with the patterns above (e.g. "Bash(source*)", "Bash(iverilog*)", "Bash(yosys*)").

If Stage 2/3/4 hangs silently, the cause is almost always one of these unlisted commands waiting on an invisible permission dialog.

SETTINGS=".claude/settings.json"
if [ ! -f "$SETTINGS" ]; then
    echo '{"permissions":{"allow":[]}}' > "$SETTINGS"
fi
python3 -c "
import json
s = json.load(open('$SETTINGS'))
allow = s.setdefault('permissions', {}).setdefault('allow', [])
# Tools that sub-agents need (must not trigger permission dialog):
# - WebSearch: main session only (sub-agents do not have it)
# - Bash(python*): all agents run python for hook validation
# - Bash(test*): agents run 'test -f ...' for file existence checks
# - Write: agents write output files (spec.json, golden_model.py, etc.)
needed = [
    'Bash(python*)',
    'Bash(python3*)',
    'Bash(test*)',
]
added = []
for tool in needed:
    if not any(tool in rule for rule in allow):
        allow.append(tool)
        added.append(tool)
if added:
    json.dump(s, open('$SETTINGS','w'), indent=2)
    print(f'[PERM] Added to allowlist: {added}')
else:
    print('[PERM] All sub-agent tools already allowed')
"

Step 0b: Requirements Clarification

Read ALL input files in parallel (single message with multiple Read calls):

• $PROJECT_DIR/requirement.md (required)
• $PROJECT_DIR/constraints.md (optional)
• $PROJECT_DIR/design_intent.md (optional)
• $PROJECT_DIR/context/*.md files

Check each category below. If input files already answer it → note "confirmed" and skip. Only ask about what's missing or ambiguous. Use AskUserQuestion with up to 4 questions per call.

A. Functional clarity: module functionality, interface protocol, data format, FSM behavior, clock domain crossings B. Constraint clarity: clock frequency, target platform, area/power budget, reset strategy, IO standards C. Design intent: architecture style, module partitioning, interface preferences, IP reuse, key decisions D. Algorithm & protocol: algorithm reference, pseudocode, key formulas, test vectors E. Timing completeness: cycle-level behavior, latency, throughput, interface timing, reset recovery, backpressure F. Domain knowledge: design domain, standard reference, prerequisite concepts, test vectors G. Information completeness: implicit assumptions, missing scenarios

After resolved, write $PROJECT_DIR/.veriflow/clarifications.md with all answers.

Step 0c: Create task list

Create one task per pipeline stage (skip if resuming and already completed):

• Stage 1: spec_golden
• Stage 2: codegen
• Stage 3: verify_fix
• Stage 4: lint_synth

Stage Pattern (ALL stages follow this)

Every stage MUST execute these 3 steps in order:

Pre-stage:

[ -f "$PROJECT_DIR/.veriflow/eda_env.sh" ] && source "$PROJECT_DIR/.veriflow/eda_env.sh" && $PYTHON_EXE "${CLAUDE_SKILL_DIR}/state.py" "$PROJECT_DIR" "<STAGE>" --start

Execute: dispatch agents (Stages 1/2/4) or run inline (Stage 3)

Post-stage:

[ -f "$PROJECT_DIR/.veriflow/eda_env.sh" ] && source "$PROJECT_DIR/.veriflow/eda_env.sh" && $PYTHON_EXE "${CLAUDE_SKILL_DIR}/state.py" "$PROJECT_DIR" "<STAGE>" --hook="<HOOK_CMD>" --journal-outputs="<FILES>" --journal-notes="<NOTES>"

Then: TaskUpdate mark the stage task as completed.

Stage 1: spec_golden

Pre-stage: Web Research

Read requirement.md (run in main session) to decide if WebSearch is needed. Do NOT read templates or other input files — the agent will read them itself.

Web Research (run in main session, only if needed):

After reading requirement.md, judge whether WebSearch is needed:

• If requirement.md + context/*.md already contain: algorithm specification, test vectors, pin/protocol definitions, and enough detail to build spec.json and golden_model.py → skip WebSearch. Write a note to $PROJECT_DIR/.veriflow/web_research.md:

  # Web research skipped — input files provide sufficient detail
  Algorithm: <name>, source: <which files had the info>
  

• Otherwise, extract the algorithm/design name from requirement.md, then use WebSearch:
  • "<algorithm_name> specification test vectors" — for spec.json constraints
  • "<algorithm_name> Verilog RTL reference" — for coder patterns Store results in $PROJECT_DIR/.veriflow/web_research.md

Agent Dispatch: Single spec-golden agent

**Build INP