16gagent/docs/AGENTS-PROTOCOL-FULL.md

Execution Protocol — Planning Layer 🔵

This is the execution engine. Every agent turn MUST follow this protocol. It replaces reactive execution with structured planning. No new code. No new agents. Pure protocol enforcement via this prompt.

0. Complexity Classification (MUST run first)

Before ANY action, classify the task:

Simple → Direct Execution

Criteria (ANY ONE)	Example
Single file read/write	"Read schema.ts"
Single command	"npm test"
Pure query	"What time is it?"
Conversation	"Hello"

Complex → MUST Use Task Tree

Criteria (ANY ONE)	Example
3+ files to modify	"Fix all FK references"
Multi-step workflow	"Generate project → install → build → test"
Schema/database change	"Add inspection_records table"
Cross-project operation	"Fix all 3 generated projects"
Auth/security change	"Add RBAC"
New feature	"Add file upload"
Bug root-cause analysis	"Why does FK constraint fail?"
2+ tool categories (read+write+exec)	"Read schema, fix it, rebuild"
Estimated > 45 min or > 2 systems	"Epic-level task"

Decision rule: if uncertain → treat as Complex.

---

1. Task Tree Construction (Complex Tasks ONLY — MANDATORY)

⚠️ Complex tasks MUST build a Task Tree BEFORE entering §2 PLAN. No flat task lists. Task Tree is the only valid entry to Planning.

1a. Task Tree Definition

Task Tree is an execution tree, not a feature tree.

Wrong (module tree):

Project
├── User
├── Order
└── Payment

Correct (execution tree):

Project
├── T1 Architecture Setup
├── T2 Database Schema     [depends_on: T1]
├── T3 Backend API         [depends_on: T2]
├── T4 Frontend            [depends_on: T3]
└── T5 Verification        [depends_on: T4]

1b. Mandatory Output Format

Before §2 PLAN, output:

### Task Tree

| Task ID | Name | Depends On | Parallelizable | Est. Size |
|---------|------|------------|----------------|-----------|
| T1 | Project Bootstrap | NONE | NO | Small |
| T2 | Database Schema | T1 | NO | Medium |
| T3 | Auth Service | T2 | YES | Medium |
| T4 | User Service | T2 | YES | Medium |
| T5 | API Gateway | T3,T4 | NO | Medium |

Each Task ID maps to a subtask in §2 PLAN.

1c. Dependency Rules

Hard Dependency — upstream task MUST finish before starting:

T3 Backend API depends_on: T2 Database Schema

Soft Dependency — can start in parallel, must integrate before final:

T4 UI Pages depends_on: Design Tokens (soft)

1d. Parallelism Optimization

Agent MUST identify parallelizable tasks. Output:

### Parallel Groups

**Group A (can run simultaneously):**
- T3 Auth Service
- T4 User Service

**Group B (can run simultaneously):**
- T6 Unit Tests
- T7 Integration Tests

If all tasks form a serial chain (T1→T2→T3→...), must explain why parallelism is impossible.

1e. Learning Context Integration

For each task, inject relevant lessons from the Learning Loop:

### Per-Task Injected Risks

**T3: Backend Generator**
- [R1] AP-3 DDL Constraint Leakage — add isConstraintLine() before column parsing
  Source: reflections/2026-06-05-ddl-leakage.md
- [R2] FK REPLACE → use ON CONFLICT DO UPDATE
  Source: best-practices.md #11

1f. Task Tree Quality Gate

Before proceeding to §2 PLAN, verify ALL:

• Root Task exists (exactly one task with depends_on: NONE)
• No orphan tasks (every non-root task has a valid parent chain to root)
• No circular dependency (A→B→C→A)
• No XL Task (if estimated > 4h, split into sub-tasks)
• No unjustified serial chain (if T1→T2→T3→T4 with no hard deps, explain or parallelize)
• Every task has Injected Risks populated (§1e)
• Agent can independently complete every task (no external human dependency)

If ANY gate fails: do NOT proceed to §2 PLAN. Re-split the tree.

---

2. Planning Protocol (Complex Tasks ONLY)

Before any tool call on a complex task:

## PLAN
### Goal
<one sentence>

### Subtasks
1. <step> → Verify: <how to check>
2. <step> → Verify: <how to check>
...

### Risks
- <potential pitfall>
- <dependency risk>

### Verification Strategy
- Build: <yes/no>
- Tests: <yes/no>
- Lint: <yes/no>

Then use update_plan if >3 subtasks. Then execute.

3. Pre-flight Check (Complex Tasks ONLY)

Before executing step 1, MUST complete ALL of the following:

3a. Dependency Scan

• Which files/tables/modules are involved?
• What are their dependencies (FK, imports, types)?
• What's the blast radius if I get it wrong?

Anti-pattern: "I'll fix this FK error" → "Oh wait, here's another FK error" → "And another..." Correct pattern: "Let me scan ALL FK references first, then fix them all at once."

3b. Learning Context Injector (MANDATORY — 3 searches)

Search 1: Similar failures

ctx_search(queries: ["<task_type> failure pattern lesson"], source: "reflections", sort: "timeline")

Search 2: Relevant best practices

memory_search(query: "<task_domain> best practice checklist pattern")

Search 3: Relevant playbook

Check playbooks/ for matching task type

Inject top findings into PLAN > Risks. Format:

### Injected Risks (from Learning Context)
- [R1] <lesson from past failure> — source: <reflection/pattern file>
- [R2] <relevant best practice violation> — source: best-practices.md #N
- [R3] <playbook recommendation> — source: playbooks/<name>.md

3c. Domain Checklist Injection

Based on task type, append the relevant checklist to PLAN:

SQL / Schema tasks:

• □ FK 引用：所有 FK 用 ON CONFLICT DO UPDATE，不用 REPLACE（SQLite REPLACE = DELETE+INSERT）
• □ DDL 解析：PRIMARY KEY / CONSTRAINT 行不能当数据字段
• □ 迁移安全：先检查所有引用方，再改 schema
• □ WAL 模式：多进程读写不阻塞

JavaScript / TypeScript tasks:

• □ Falsy 陷阱：0、''、false 用 ?? 替代 ||（|| 会把 0 判为 falsy）
• □ 类型生成：entity names 复数→单数（Albums→Album），但不碰 status/bus 等词根
• □ 模板语法：模板字面量内嵌反引号用 ` 转义或字符串拼接
• □ 启发式检测：必须 2+ 信号同时匹配，单信号不可靠

Next.js / Frontend tasks:

• □ 路径：Next.js App Router 用 app/ 不是 src/app/
• □ Tailwind content 路径匹配实际目录
• □ tsconfig paths 匹配实际目录结构
• □ JSX：三元表达式嵌套使用括号包裹，避免 {} 嵌套错误

Backend / API tasks:

• □ generateTypes 必须包含 User 实体 → CreateUserInput 类型
• □ 所有 resource types 生成完整的 CRUD Input 类型
• □ route params 命名与 service 函数签名一致

Generator / Builder tasks:

• □ 输出路径：验证生成目录结构与实际 runtime 预期一致
• □ DDL→TS：schema.ts 中 CONSTRAINT/FK 行不能被解析为 interface 字段
• □ Type mapping：SQL types 到 TS types 的映射表完整
• □ Template safety：模板字面量不输出裸反引号

Release / CI tasks:

• □ Exit code 规范：PASS/WARN→0, FAIL→1
• □ 回退路径：每个 destructive 操作有对应回退步骤
• □ backward compat：新代码不改老接口

If no checklist matches, add:

• □ No domain-specific checklist available — proceed with extra caution

4. Failure Replanning Protocol

When a step fails:

DO NOT fix the immediate error and continue blindly.

DO:

1. Log: what failed, error message, which step

2. Analyze: is this a local fix or does it invalidate the plan?

3. If local → fix, verify, continue

4. If structural → REPLAN — output a revised PLAN section

5. If same step fails 3 times → PAUSE and ask user

6. Auto-Capture Check (after fix, before continuing): → See complete trigger rules in §6 Auto-Capture Trigger (T1-T7) → If ANY trigger matches → write structured Reflection to reflections/YYYY-MM-DD-<task>.md → Reflection MUST contain ALL 7 required fields (Context/Root Cause/Fix/Pattern Class/Future Trigger/Checklist/Recurrence Count) → Skip only when: fix < 5 min + first occurrence + no test/build/lint failure

7. Promotion Check (after Reflection written):

   Appearances	Action	Destination
   1st	Reflection	reflections/
   2nd	Pattern	patterns/design-patterns.md (new section)
   3rd	Best Practice	patterns/best-practices.md (numbered entry)
   4th	Checklist Item	AGENTS.md §3c Domain Checklists
   5th	Hard Rule	AGENTS.md §3c (bolded, marked ⚠️ HARD RULE)

5. Verification Protocol (Complex Tasks ONLY)

After all subtasks complete:

## VERIFICATION
- Build: [PASS/FAIL]
- Tests: [PASS/FAIL / N suites / N tests]
- Lint: [PASS/FAIL]
- Regression risk: [NONE/LOW/MEDIUM/HIGH]
- Manual changes needed: [NONE / <description>]

MANDATORY GATE: Pre-flight Compliance Check

Before closing any complex task, verify ALL of:

• PLAN contains ### Injected Risks (from Learning Context) section
• At least 2 knowledge sources were searched (ctx_search / memory_search / playbooks)
• Matching domain checklist from §3c is included in PLAN
• If failure occurred: structured Reflection was written to reflections/YYYY-MM-DD-<task>.md
• Reflection contains ALL 7 required fields (Context/Root Cause/Fix/Pattern Class/Future Trigger/Checklist/Recurrence)

If ANY gate fails: task is NOT complete. Go back and fill the gap.

6. Governance Compliance 🔒

Compliance is mandatory for all complex task execution.

• State machine, heartbeat, blocker, replan, scope detection, health score, auto-stop, recovery mode → see GOVERNANCE.md
• Multi-project portfolio management → see PORTFOLIO.md
• MANDATORY Governance Quality Gate must run before project output (GOVERNANCE.md §9)

7. Auto-Capture Trigger — COMPLETE Rule Set (after ANY failure)

ALWAYS check these conditions after fixing a failure. Write Reflection when ANY condition matches:

#	Trigger Condition	Why
T1	build command failed	Build failure always indicates systemic error
T2	test command returned non-zero or unexpected failures	Test failure = regression risk
T3	lint / tsc --noEmit failed	Syntax/type errors in generated code
T4	Fix time > 30 minutes elapsed	Long fix = complex root cause worth documenting
T5	Same error class appeared before (check ctx_search / Promotion Log)	Recurrence → must upgrade
T6	Generated output path/format/structure mismatched target convention	E.g. src/app/ vs app/, wrong SQL dialect, missing types
T7	Generated content caused runtime crash or data corruption	Silent data corruption is highest severity

Skip reflection (not worth recording) when:

• Fix < 5 min AND never seen before AND no test/build/lint failure
• Typo fix (single character, no logic change)
• Expected external service failure (network timeout, API rate limit)

Reflection write checklist (ALL 7 fields REQUIRED):

[ ] Context — what task was being performed
[ ] Root Cause — the bug, not the symptom (banned: "以后注意", "下次小心")
[ ] Fix — exact change, with code diff if applicable
[ ] Pattern Class — abstract category (e.g. "SQLite FK", "JS Falsy Coercion", "Path Convention")
[ ] Future Trigger — when to inject this lesson (e.g. "any SQL schema change")
[ ] Checklist — ≥2 actionable checks for next time
[ ] Recurrence Count — 1 (update on each recurrence)

---

Learning Loop 🔄

Knowledge stored in reflections/patterns/playbooks MUST flow back into Planning. This section closes the loop.

Loop Architecture

Failure/Success
    ↓
Reflection (structured, with Pattern Class)
    ↓
Promotion Check (1→2→3→4→5 appearances)
    ↓
Pattern → Best Practice → Checklist → Hard Rule
    ↓
Pre-flight Injector (§3b) + Domain Checklists (§3c)
    ↓
Next Plan includes past lessons
    ↓
Execution
    ↓
Verification → triggers new Reflection if needed
    ↓
(loop closes)

Promotion Rules

Count	Promotion To	Location
1st	Reflection	reflections/YYYY-MM-DD-<task>.md
2nd	Design Pattern	patterns/design-patterns.md (new Anti-Pattern section)
3rd	Best Practice	patterns/best-practices.md (numbered entry)
4th	Domain Checklist	AGENTS.md §3c (update matching checklist, or create new)
5th	Hard Rule	AGENTS.md §3c (bolded, marked ⚠️ HARD RULE)

Quality Gate for Reflections

A valid Reflection MUST include ALL of:

• Context (what task)
• Root Cause (the bug, not the symptom)
• Fix (exact change)
• Pattern Class (abstract category)
• Future Trigger (when to re-inject)
• Checklist (actionable items)
• Recurrence Count

Rejected: "以后注意", "下次小心", "当时没想清楚", "应该多测试" Accepted: "SQLite FK: REPLACE=DELETE+INSERT, use ON CONFLICT DO UPDATE"

Storage Locations

reflections/              ← First occurrence of a failure pattern
patterns/design-patterns  ← Abstract reusable anti-patterns (≥2 occurrences)
patterns/best-practices   ← Validated rules (≥3 occurrences)
AGENTS.md §3c             ← Domain Checklists (≥4 occurrences)
AGENTS.md §3c ⚠️          ← Hard Rules (≥5 occurrences)

playbooks/                ← Successful multi-step workflows (not failure-driven)
vault.md §Self-Evolution  ← History of promotions (timeline)

---

Agent Package Context Budget ⚠️ HARD RULE

Established 2026-06-05. Every Agent Package MUST declare its token budget before execution. This prevents context overflow, KV cache thrashing, and mid-task truncation in multi-agent workflows.

Size → Token Budget Mapping

Level	Reading	Modifying	New Code	Dependencies	Token Budget
Small	≤3 files	≤2 files	≤300 lines	≤1	≤30K tokens
Medium	≤8 files	≤5 files	≤800 lines	≤3	≤80K tokens
Large	≤15 files	≤10 files	≤1500 lines	≤5	≤200K tokens
XL	❌ FORBIDDEN	❌	❌	❌	❌

Input Size Pre-check (MANDATORY)

Before dispatching any Agent Package, pre-compute:

1. File inventory — list every file the agent will read
2. Token estimate — for code: bytes / 3; for Chinese text: chars / 1.5; round up 10% for safety
3. Budget check — sum(estimated_input_tokens) + prompt_overhead(2K) + output_buffer(20% of budget) ≤ Token Budget

### Context Budget Declaration

**AP-N**: <name>
- Files to read: N (total ~X lines / ~Y estimated tokens)
- Prompt overhead: ~2K tokens
- Output buffer: ~Z tokens (20% of budget)
- Total estimated: ~W tokens
- Budget: V tokens
- Utilization: (W/V) × 100%
- ⚠️ OVER BUDGET: <yes/no> → if YES, split further

Over-budget Resolution

If estimated utilization > 90%:

1. Split the package into sub-packages
2. Pre-index large reference files instead of reading them inline (use ctx_index → ctx_search)
3. Provide only relevant snippets, not entire files
4. Re-check budget after split

Token Estimation Constants

Content Type	Token Ratio	Notes
TypeScript/JS	1 token ≈ 3.5 chars	conservative estimate
Python	1 token ≈ 3.5 chars
SQL	1 token ≈ 3.0 chars	shorter tokens
Chinese text	1 token ≈ 1.5 chars	CJK characters are token-heavy
English prose	1 token ≈ 4.0 chars
JSON/YAML	1 token ≈ 3.0 chars	punctuation-heavy