| name | project-architecture |
| description | Foundational rules and layout for the declarative agent platform. Read this before any change, regardless of area; it anchors every other skill. |
| generated | true |
| source | .ai/skills/project-architecture.md |
Skill: Project Architecture
When to use this skill
Always. Read this before any change, regardless of area. It anchors every other
skill in the project's non-negotiable rules and layout.
Files to read first
AGENTS.mddocs/ARCHITECTURE.mddocs/ROADMAP.mddocs/adr/
Architecture rules
- The pipeline is one-directional:
config.yml → validate → compile → CompiledAgentGraph → RuntimeEngine → ExecutionContext (per request) → execution → response + trace.
- YAML is declarative specification, never executable business logic.
- Validate before compile; compile before run. The runtime sees only compiled,
typed models — never raw YAML dicts.
RuntimeEngine is created once at startup; ExecutionContext is per request.- Client-specific auth/business logic lives in customer plugins, not the runtime.
- Prompts are templates rendered per request; security is enforced at the
tool/data layer, not via prompt text.
- Secrets never live in YAML or prompts.
Implementation rules
- Follow the planned package layout in
AGENTS.md (src/agentplatform/<layer>).
No giant single-file modules.
- Keep each module to one architectural responsibility.
- Respect layer boundaries: a layer depends only on the typed outputs of the
layers before it.
- Do not change public contracts (YAML schema, plugin contracts, API shape)
without an ADR and approval.
- Stay within the current task's scope; propose new tasks for discovered work.
Validation checklist
Common mistakes to avoid
- Reading raw YAML in the runtime instead of compiled models.
- Adding request state to
RuntimeEngine or the compiled graph.
- Putting customer auth/business logic in the runtime.
- Expanding scope beyond the current task or doing large uncontrolled rewrites.
- Relying on prompt wording for security.
