Initial commit: AirCoding V1.0.0 Alpha architecture baseline
Complete architecture document set with multi-model review remediation: - Frozen interface contracts, runtime semantics, DB schemas - Event/tool/error/provider registries - Scheduler and main agent state machines - C4 module/code views, solution architecture, baseline V1 - Multi-model review reports and joint assessment - Phase-gate remediation complete (P0/P1/P2/UX resolved) - Implementation plan with T-000A through T-045 - Reference folders kept as placeholders only
This commit is contained in:
AirCoding
528
AirPlan/docs/architecture/prompt-layering-v1.md
Normal file
528
AirPlan/docs/architecture/prompt-layering-v1.md
Normal file
@@ -0,0 +1,528 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user