AirCoding/AirPlan/docs/architecture/prompt-layering-v1.md

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:

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:

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:

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:

~/.air/permissions.yaml
<project>/.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:

built-in default project rules template
~/.air/rules or global profile
<project>/.air/shared/rules/project-rules.md
<project>/.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:

<project>/.air/shared/plan/AGENTS.md
<project>/.air/shared/plan/plan.md
<project>/.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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

TaskGraph summary
write areas
dependency graph
resource snapshot
failure/retry history
architecture constraints

Output must be structured:

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:

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:

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:

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:

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:

L0 compaction invariant
L1 compactor role
compaction rules
message range snapshot
existing summaries
current plan/rules for terminology

Output:

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:

L0 memory policy
L1 experience_miner role
project rules and skill docs
verified debug records
repeated patterns
user confirmations

Output:

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

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:

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:

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:

learned retrieval ranking
semantic code retrieval
skill auto-selection
multi-provider prompt optimization
UI prompt visualization/debugger