# AirCoding Prompt Layering Model V1 Date: 2026-05-27 Status: Canonical prompt/context layering model for V1.0.0 Alpha skeleton This document defines how AirCoding assembles prompts and context for Main Agent, Architecture Designer, Scheduler-facing planning, worker agents, Reviewer, Debugger, Compactor, and ExperienceMiner. AirCoding stores and assembles Anthropic canonical messages internally. Provider adapters convert only at the LLM boundary. ## 1. Goals Prompt layering must: 1. Preserve stable global behavior across providers. 2. Keep project/user rules visible and ordered. 3. Keep worker context bounded and task-specific. 4. Make architecture decisions explicit and traceable. 5. Prevent UI/progress/scheduling state from polluting coding instructions. 6. Support copy-on-write compaction without losing backtracking ability. 7. Keep Claude Code-like execution discipline at the execution layer. ## 2. Canonical Layer Order ContextAssembler builds messages in this order: ```text L0 Runtime invariant L1 Role / agent mode L2 Safety and permission policy L3 Project rules and user preferences L4 Architecture baseline and current plan L5 Task specification and acceptance criteria L6 Relevant code/artifacts/evidence L7 Recent conversation and decision context L8 Tool result history / diagnostics L9 Immediate instruction ``` Higher layers may specialize lower layers but must not silently contradict runtime invariants or safety policy. If a conflict is detected, ContextAssembler records an omission/conflict note and routes to Main Agent or Architecture Designer. ## 3. Layer Definitions ### L0 Runtime invariant Source: ```text built-in runtime prompts/resources packages/contracts baseline invariants ``` Contents: - internal message format is Anthropic canonical content blocks - tool use protocol and result expectations - read-before-edit discipline - exact/small edit discipline - no unrelated refactors - verify before declaring completion - escalate architecture/interface conflicts - respect PermissionEngine decisions Mutable: no, except by AirCoding release. ### L1 Role / agent mode Source: ```text built-in role prompt for main/architecture/scheduler/executor/reviewer/debugger/compactor/experience_miner ``` Defines: - responsibility boundary - allowed outputs - whether writing files is allowed - expected result schema - whether user-facing language is allowed ### L2 Safety and permission policy Source: ```text ~/.air/permissions.yaml /.air/shared/permissions.yaml runtime PermissionEngine ``` Contents: - path policy - system-sensitive policy - credential policy - network policy - high-permission announce-then-run behavior - explicit-confirmation boundaries ### L3 Project rules and user preferences Source order: ```text built-in default project rules template ~/.air/rules or global profile /.air/shared/rules/project-rules.md /.air/shared/rules/toolchain-rules.md relevant promoted memories/skills ``` Rules: 1. Project-local rules override default templates. 2. User-confirmed rules override inferred rules. 3. Stale rules discovered during execution route to ExperienceMiner/Curator; workers do not silently rewrite rules unless assigned that task. ### L4 Architecture baseline and current plan Source: ```text /.air/shared/plan/AGENTS.md /.air/shared/plan/plan.md /.air/shared/plan/todo.md ADR/C4 docs current Architecture Designer output TaskGraph ``` Contents: - current architecture constraints - accepted ADR decisions - interfaces and module boundaries - active plan/todo - impact assessment summaries Workers receive only relevant excerpts or references, not the entire architecture corpus by default. ### L5 Task specification and acceptance criteria Source: ```text TaskSpec Scheduler wave plan Worker runtime context ``` Contents: - task title and description - scope/write area - allowed/denied paths - dependencies and parent results - acceptance criteria - verification requirements - retry/model policy This is the primary steering layer for workers. ### L6 Relevant code/artifacts/evidence Source: ```text fs.read outputs artifact refs command/tool reports diagnostics debug records review findings ``` Rules: 1. Prefer exact snippets with file paths and line ranges. 2. Large content is passed by artifact reference. 3. Binary/screenshot/pcap/core evidence is summarized plus referenced. 4. Diagnostics include semantic signatures when available. ### L7 Recent conversation and decision context Source: ```text messages summaries requirement.changed events architecture.impact.completed events ``` Rules: 1. Include recent user intent and decision changes. 2. Include summary ranges when raw history is too large. 3. Preserve raw message backtracking through copy-on-write compaction. ### L8 Tool result history / diagnostics Source: ```text tool_runs command_runs diagnostics evidence_refs ``` Contents: - recent tool calls relevant to the task - build/test/debug evidence - failed command excerpts - previous retry attempts and failure signatures ### L9 Immediate instruction Source: ```text Main Agent instruction Scheduler worker start message user's latest request ``` This layer states what the model should do now and the required output format. ## 4. Agent-Specific Context Profiles ### Main Agent Profile Purpose: user-facing coordination. Includes: ```text L0 runtime invariant L1 main role L2 permission policy summary L3 user/project rules summary L4 current plan/task graph summary L7 recent conversation L8 high-level evidence summaries L9 latest user request ``` Excludes by default: ```text large source files raw command logs worker-private scratch context ``` Main Agent must remain responsive and should delegate background work. ### Architecture Designer Profile Purpose: architecture/interface/impact decisions. Includes: ```text L0 L1 architecture role L3 project rules L4 full relevant baseline/ADR/C4/plan context L5 architecture task spec L6 code/interface excerpts when needed L7 requirement history L9 requested decision/output ``` Allowed outputs: ```text architecture plan impact assessment ADR/C4/doc updates TaskGraph/todo updates ``` It must not implement code directly. ### Scheduler Planning Profile The Scheduler is mostly deterministic code, but may use LLM classification for complex planning decisions. Includes: ```text TaskGraph summary write areas dependency graph resource snapshot failure/retry history architecture constraints ``` Output must be structured: ```ts interface SchedulerLLMDecision { decision_type: "wave_plan" | "retry" | "escalation" | "model_assignment" | "merge_strategy" decision: unknown reason: string risks?: string[] } ``` ### Executor Profile Purpose: implement/build/test within a bounded task. Includes: ```text L0 execution discipline L1 executor role L2 scoped permissions L3 relevant project/toolchain rules L4 relevant architecture excerpts L5 full TaskSpec L6 relevant files/artifacts L8 prior failures for this task L9 required WorkerResult format ``` Executor rules: 1. Read before edit. 2. Use exact/small edits. 3. Do not change architecture/interface unless TaskSpec or Architecture Designer authorizes it. 4. Verify with required commands unless impossible; if impossible, return blocked/failed with evidence. 5. Return structured WorkerResult. ### Reviewer Profile Purpose: inspect and validate. Includes: ```text L0 review discipline L1 reviewer role L3 project rules L4 architecture/acceptance constraints L5 review TaskSpec L6 diff/artifacts/evidence L8 verification results L9 review output schema ``` Reviewer is read-only. It may propose follow-up tasks but must not edit files. Review dimensions: ```text correctness security scope control architecture compliance test evidence regression risk ``` ### Debugger Profile Purpose: diagnose failures and either fix within scope or produce blocker evidence. Includes: ```text L0 debugging discipline L1 debugger role L2 permissions L3 toolchain rules L4 relevant architecture constraints L5 debug TaskSpec L6 failing logs/diagnostics/artifacts/code excerpts L8 retry/failure signatures L9 DebuggerResult schema ``` Debugger may modify code only when assigned a debug/fix task with write scope. ### Compactor Profile Purpose: summarize immutable message ranges. Includes: ```text L0 compaction invariant L1 compactor role compaction rules message range snapshot existing summaries current plan/rules for terminology ``` Output: ```text Markdown/frontmatter summary artifact summary.created / context.compaction.completed payload omissions and backtracking refs ``` Compactor must preserve decisions, constraints, open questions, tool evidence, and user preferences. ### ExperienceMiner Profile Purpose: extract durable rules/skills/debug knowledge candidates. Includes: ```text L0 memory policy L1 experience_miner role project rules and skill docs verified debug records repeated patterns user confirmations ``` Output: ```text memory candidate rule patch proposal skill patch proposal debug record promotion ``` Non-debug experience promotion requires user confirmation unless project policy says otherwise. ## 5. Conflict Handling Prompt/context conflicts are classified: | Conflict | Example | Action | |---|---|---| | policy conflict | project rule asks to bypass permission | Permission policy wins; report conflict | | architecture conflict | task asks to change public interface without ADR | block or Architecture Designer assessment | | user-rule conflict | old rule contradicts latest explicit user instruction | latest explicit user instruction wins for session; ExperienceMiner may update rule | | evidence conflict | stale summary contradicts current file | current file/evidence wins; update summary/rule if needed | | provider conflict | target model lacks required capability | route to provider/model selection or block | ## 6. Context Assembly Algorithm ```text 1. Resolve context profile from agent/task purpose. 2. Load immutable L0/L1 templates. 3. Load permission/project rules with precedence. 4. Load current architecture/plan refs. 5. Load TaskSpec and dependency results. 6. Retrieve relevant files/artifacts/evidence. 7. Add recent messages/summaries and requirement changes. 8. Add relevant tool/command/diagnostic history. 9. Fit to token budget using compaction rules. 10. Emit Anthropic canonical messages and omissions list. 11. If required context cannot fit, emit context.compaction.requested or block. ``` ## 7. Prompt Asset Locations Built-in prompt resources ship with binary distribution: ```text resources/prompts/ runtime-invariant.md roles/ main.md architecture-designer.md scheduler-decision.md executor.md reviewer.md debugger.md compactor.md experience-miner.md output-schemas/ ``` Project overrides are not allowed for L0 runtime invariants. Project rules belong in `.air/shared/rules/`, not in prompt resource replacement. ## 8. Provider Boundary ContextAssembler always returns Anthropic canonical messages: ```ts interface AssembledContext { canonical_format: "anthropic" messages: unknown[] omissions: string[] refs: string[] token_estimate?: number } ``` Provider adapters may convert to OpenAI/OpenRouter/ollama formats after assembly. Provider conversion must not change task semantics or drop tool contract requirements without recording an omission/blocker. ## 9. V1.0.0 Alpha Cut Line V1.0.0 Alpha skeleton must implement: 1. Built-in role prompt assets. 2. Context profile selection by agent/task type. 3. Layered assembly order L0-L9. 4. Project/global rule loading with precedence. 5. Architecture/plan/task/evidence reference loading. 6. Token-budget fitting with omission reporting. 7. Anthropic canonical output. 8. Provider-boundary conversion hook. 9. Conflict detection for policy, architecture, stale evidence, and provider capability. Post-MVP: ```text learned retrieval ranking semantic code retrieval skill auto-selection multi-provider prompt optimization UI prompt visualization/debugger ```