Development guidelines for Circuitron — AI-powered PCB design accelerator using multi-agent orchestration, SKiDL, KiCad, and Docker isolation
Development assistant for Circuitron — an AI-powered PCB design accelerator that converts natural language requirements into SKiDL scripts, KiCad schematics, and PCB layouts using a multi-agent orchestration pipeline.
Circuitron uses a sophisticated multi-stage agent workflow with nested correction loops:
1. **Planner** → **Plan Editor** (optional user feedback loop)
2. **Part Finder** → **Part Selector**
3. **Documentation Agent** (gathers context via RAG)
4. **Code Generator**
5. **Validation & Correction Loop** (Validator → Corrector)
6. **Runtime Check & Correction Loop** (Docker execution → Runtime Corrector)
7. **ERC & Handling Loop** (ERC Handler with auto-fix)
8. **Final Execution** (produces KiCad files)
**CRITICAL: Always reference official documentation before implementing or changing anything.**
**Primary Sources:**
1. Use `context7` MCP server tools for documentation on any library/framework (if available locally)
2. If not available, use official documentation from the internet
3. **SKiDL Documentation**: https://devbisme.github.io/skidl/
**Before using any API, class, method, or tool:**
1. Look up the relevant section in official documentation
2. Verify syntax, arguments, return types, and intended behavior
3. Follow usage patterns from official examples
4. Never guess or hallucinate API usage — ask for clarification if uncertain
Create agents in `circuitron/agents.py` as pure functions with prompt, model, output type, tools, and settings:
```python
def create_planning_agent() -> Agent:
"""Create and configure the Planning Agent."""
model_settings = ModelSettings(tool_choice="required")
tools: list[Tool] = [execute_calculation]
return Agent(
name="Circuitron-Planner",
instructions=PLAN_PROMPT,
model=settings.planning_model,
output_type=PlanOutput,
tools=tools,
input_guardrails=[pcb_query_guardrail],
model_settings=model_settings,
)
```
**Notes:**
Define agent tools in `circuitron/tools.py` using `@function_tool` decorator or wrapper:
```python
@function_tool
async def search_kicad_libraries(query: str, max_results: int = 50) -> str:
"""Search KiCad libraries using skidl.search."""
# implementation using DockerSession
async def run_runtime_check(...) -> str:
# implementation
run_runtime_check_tool = function_tool(run_runtime_check)
```
All external tool execution (KiCad, calculations) occurs in isolated Docker containers:
Attach shared MCP server for agents needing documentation/RAG or validation:
```python
def _tool_choice_for_mcp(model: str) -> str:
return "auto" if model == "o4-mini" else "required"
def create_documentation_agent() -> Agent:
model_settings = ModelSettings(
tool_choice=_tool_choice_for_mcp(settings.documentation_model)
)
return Agent(
name="Circuitron-DocSeeker",
instructions=DOC_AGENT_PROMPT,
model=settings.documentation_model,
output_type=DocumentationOutput,
mcp_servers=[mcp_manager.get_server()],
model_settings=model_settings,
)
```
Always activate the virtual environment before running Python commands:
```powershell
& C:/Users/shaur/circuitron/circuitron_venv/Scripts/Activate.ps1
```
**Notes:**
- Functions/variables: `snake_case`
- Classes: `PascalCase`
- All arguments and their types
- Return type
- Concise usage example
**You are the sole implementation agent for this repository. Follow strict Test-Driven Development:**
1. **Write failing test first** for any new behavior before production code
2. **Write minimal production code** to pass the test
3. **Refactor** for clarity after passing
4. **Coverage**: Maintain ≥90% branch coverage on backend utilities
5. **Test Framework**: `pytest`
6. **Every new Agents-SDK tool** must have unit test with mocked LLM outputs
7. **Run tests after every logical change**:
```bash
pytest -q
```
8. **Never commit** if tests fail or coverage decreases
**Before starting any task:**
**After completing significant changes:**
**This protocol is mandatory for all AI coding assistants.**
> Treat the project as a green-field codebase:
> - Generate all source files, config, and docs needed to meet requirements
> - Follow strict TDD workflow for all changes
> - Keep coverage ≥90% with edge/corner-case tests for every feature
> - Refuse to commit code if tests fail or coverage decreases
1. Review official documentation for relevant APIs/libraries
2. Write failing test for new feature
3. Implement minimal code to pass test
4. Refactor for clarity
5. Run `pytest -q` to verify all tests pass
6. Update `collab_progress/` documentation
7. Verify coverage remains ≥90%
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/circuitron-pcb-design-development-guide/raw