---
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
---

<!--
This file is generated by tools/skills.
Do not edit this file directly.
Edit .ai/skills/project-architecture.md and run `make generate-ai`.
-->

# 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.md`
- `docs/ARCHITECTURE.md`
- `docs/ROADMAP.md`
- `docs/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

- [ ] Change fits the layered architecture and the planned layout.
- [ ] No architecture rule from `AGENTS.md` §3 is violated.
- [ ] No contract changed without an ADR.
- [ ] Tests added for new behavior.
- [ ] `make check` passes.

## 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.