project-architecture

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