Instruction file imported from Alex161202/VeriAgentAi (.github/instructions/agents.instructions.md). Copyright stays with the author.

Agents Instructions

Ingestion Agent (ingestion_agent.py)

• Pipeline: parse → regex metadata → structure analysis → LLM key-info extraction → markdown → index
• llm_powerful (max_tokens=4096): key-info extraction (JSON output)
• llm_cheap (max_tokens=1536): structure analysis fallback
• ProcessedSpecification model has: metadata, executive_summary, sections, key_features, verification_priorities, dependencies, acronyms, references, protocols, interfaces, timing_constraints, state_machines, register_maps
• Markdown builder must write ALL structured fields — never silently discard extracted data
• Supports PDF, DOCX, MD, YAML parsing

RTL Analysis Agent (planned — rtl_analysis_agent.py)

• Parser: pyslang (slang, IEEE 1800-2017 superset, handles Verilog-2001 too)
• Must use parser abstraction from src/veriassist/rtl/sv_parser.py
• Capabilities: module/port extraction, FSM detection, protocol inference via RAG, spec cross-check

General Agent Rules

• Always use LLMFactory.create_llm() — never instantiate LLMs directly
• Set explicit max_tokens for every LLM call to prevent truncation
• JSON output from LLMs must be parsed with fallback handling (LLM may truncate)

Verification Planning Agent (verification_planning_agent.py)

• 7-step async pipeline: load descriptor → gather spec context (RAG) → extract features → generate scenarios → plan coverage → specify assertions → synthesize strategy
• llm_fast (max_tokens=4096): feature extraction, scenario gap-fill
• llm_balanced (max_tokens=8192): scenario generation, assertion specification, strategy synthesis
• llm_powerful (max_tokens=16384): coverage planning (covergroups + cross-coverage)
• All LLM responses parsed via _parse_json_from_response() — handles code fences, leading/trailing prose, and nested JSON boundaries
• _build_design_summary() serialises DesignDescriptor into structured text for LLM context
• Entry point: async def plan(descriptor, scope_filter?) -> VerificationPlan
• Requires DesignDescriptor (from module_model.py) as input — never raw RTL
• Report output via VerificationPlanReportGenerator.write_reports() — produces both .md and .json

Chat Agent Plan Mode (chat_agent.py — ChatMode.PLAN)

• load_plan(path) reads a verification-plan JSON and parses into VerificationPlan
• _build_plan_system_prompt() serialises the plan into structured text sections for LLM context
• _ask_plan() follows the same pattern as _ask_rtl(): system prompt + optional RAG enrichment + truncation handling
• Plan refinement is conversational — user iterates via va chat --plan

Testbench Scaffolding Agent (testbench_scaffolding_agent.py)

• 10-step async pipeline: load/validate → analyse architecture → structural shells → seq_item constraints → driver/monitor bodies → verification components → tests/sequences + registry → build sim contract → assemble/write → compilation check + auto-fix
• Hybrid approach: deterministic TestbenchBuilder for structural code + LLM injection for behavioral code
• llm_fast (4096): architecture analysis (agent topology)
• llm_balanced (8192): seq_item constraints, verification components, test sequences, compilation error fixes
• llm_powerful (16384): driver/monitor run_phase() bodies (protocol-sensitive)
• Entry point: async def generate(verification_plan, design_descriptor, output_dir?, config?, rtl_dir?, run_compile_check?) -> TestbenchScaffold
• CLI: va generate-tb -p plan.json -d descriptor.json --simulator questa|vcs|xcelium
• Simulator is prompted interactively if --simulator is omitted
• --rtl-dir specifies design RTL source path for compilation
• --no-compile-check skips the post-generation compilation validation
• Step 10 runs the actual simulator compiler (vlog/vcs/xrun), parses errors, feeds them to LLM for fixes, and re-compiles — up to 3 iterations
• Output directory: Verif/Sim/{Tests,seq,metadata,sv,tb}
• TestbenchScaffold JSON includes: files[], test_registry[], compilation_config, simulation_config, coverage_map{} — full downstream contract for Simulation Agent
• Graceful degradation: if any LLM step fails, // TODO: implement placeholders keep scaffold compilable
• If compiler not found on PATH, Step 10 is skipped with a warning
• Protocol-agnostic — all protocol details flow from DesignDescriptor + VerificationPlan
• Report output via TestbenchReportGenerator.write_reports() — produces .md + .json in metadata/