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:

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

```text
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:

```text
<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:

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