COMPAID — Companion Package

This is the companion package to the paper "Towards Component-based Development for the Era of AI Coding Agents".

COMPAID is a specification-first, component-based approach to software development with AI coding agents. Instead of having AI agents work directly with source code, the method uses YAML-based component specifications as the single source of truth. Code, tests, and build artifacts are derived from these specifications through a templated, rules-based process called skills.

Repository Structure

• compaid/ — The COMPAID tool implementation.
• example/ — An example ESP-IDF application used in the paper.

Installation

The COMPAID tool is installed using uv:

cd compaid
uv sync

Running COMPAID

From the compaid/ directory, run:

uv run compaid -C ../example develop

API Keys

COMPAID requires Anthropic and OpenAI API keys. Configure them in example/.compaid/config-local.yml:

anthropic_api_key: <your-anthropic-api-key>
openai_api_key: <your-openai-api-key>

This file is gitignored and must be created locally.

Example Application

The example/ directory contains only the component specifications in example/architecture/. These YAML files define four components of a simple ESP-IDF application:

• heartbeat.yaml — Periodic heartbeat event publisher
• wifi_manager.yaml — WiFi STA connection manager
• http_server.yaml — HTTP server wrapper
• heartbeat_status.yaml — Web page displaying heartbeat status

The source code is not provided — it is meant to be generated using the COMPAID method. Running the tool as described above will invoke the AI agents to derive the implementation from these specifications.

The ESP-IDF Skill

The skill referenced in the paper is located in compaid/compaid/platforms/esp_idf/skill/. It contains:

• SKILL.md — The master skill document defining all rules, constraints, and workflow groups.
• references/ — Detailed reference guides for each development phase (component design, design review, code generation, implementation review, build and test).
• assets/ — Template skeletons (e.g., the canonical component YAML structure).