viepilot 2.50.1 → 3.7.3

package/docs/brainstorm/session-2026-05-22.md

@@ -0,0 +1,472 @@
+# Brainstorm Session — 2026-05-22
+# FEAT-021: ViePilot v3 Per-Adapter Intelligence Refactor
+
+workflow_version: 2.51.0
+session_id: 2026-05-22
+topic: v3 Milestone — Per-Adapter Intelligence Refactor
+status: completed
+
+---
+
+## Context
+- **Trigger**: User reported agents not working on Claude Code adapter despite being configured
+- **Root cause confirmed by research**: `cursor_skill_adapter` block in all SKILL.md files uses Cursor-specific tool names (`Shell`, `ReadFile`, `rg`, `ApplyPatch`, `Subagent`) that **do not exist** on Claude Code. These tools are silently ignored, causing entire adapter-specific logic to fail.
+- **Scope**: New Milestone v3 — full adapter abstraction layer refactor
+
+---
+
+## Topic 1: Adapter Research Findings
+
+### Claude Code (Anthropic CLI)
+**Native tools (confirmed):**
+- `Bash` (not `Shell`), `Read` (not `ReadFile`), `Edit`, `MultiEdit`, `Write`
+- `Glob`, `Grep` (not `rg`), `LS`, `NotebookRead`, `NotebookEdit`
+- `WebFetch`, `WebSearch`, `TodoRead`, `TodoWrite`, `ToolSearch`
+- `exit_plan_mode`
+- **Agent/Task tool** — spawn subagents (multi-level nesting supported)
+- **AskUserQuestion** — deferred tool, must be loaded via `ToolSearch` first
+
+**Hooks system:** 28 events (PreToolUse, PostToolUse, Stop, SubagentStart, SubagentStop, SessionStart, SessionEnd, TaskCreated, TaskCompleted, UserPromptSubmit, etc.)
+- Handler types: `command`, `http`, `mcp_tool`, `prompt`, `agent`
+- Hooks can: block tool execution, modify tool input, inject context, approve/deny permissions
+
+**Skill system:** `.claude/skills/<name>/SKILL.md` or `.claude/commands/<name>.md`
+**Subagents:** `.claude/agents/<name>.md` with full frontmatter config (tools, model, hooks, maxTurns, permissionMode, skills)
+**MCP:** Full support (stdio, http, streamable-http); schemas deferred via ToolSearch
+**Settings:** `~/.claude/settings.json` — hooks, permissions.allow/deny, env, model, permissionMode, mcpServers
+
+**Key capability NOT in Cursor:** Multi-level subagent nesting, 28 hook events, dynamic hook context injection
+
+---
+
+### Cursor IDE
+**Native tools (Agent Mode, confirmed from March 2025 system prompt):**
+- `run_terminal_cmd` (not `Shell`)
+- `read_file` (not `ReadFile`)
+- `edit_file`, `delete_file`, `list_dir`, `file_search`
+- `grep_search` (not `rg`)
+- `web_search`, `codebase_search`, `reapply`, `diff_history`, `fetch_rules`
+- **Browser tool** (screenshots, DOM interaction)
+
+**Plan Mode only:** `AskQuestion` (interactive structured prompts)
+**Agent Mode:** Text clarification (non-blocking async); no formal `AskQuestion` tool
+
+**Rules:** `.cursorrules` (legacy) → `.cursor/rules/*.mdc` (current)
+- STATIC at runtime — agents cannot write rules dynamically
+
+**Subagents:** `/multitask` command (v3.2, April 2026) — single-level only, not a callable tool
+**Hooks:** 5 events: beforeShellExecution, beforeMCPExecution, beforeReadFile, afterFileEdit, stop
+**MCP:** Full support, **40-tool hard limit**
+**Skills:** `.cursor/skills/` (project) or `~/.cursor/skills/` (user) — SKILL.md format ✅
+
+---
+
+### Antigravity (Google Gemini CLI successor)
+**Status:** Gemini CLI deprecated June 18, 2026 → replaced by Antigravity CLI (Go-based)
+**Skills:** `.agents/skills/<skill-name>/SKILL.md` (project) or `~/.gemini/antigravity/skills/` (global)
+- LLM-driven discovery (no slash command required) ← different from Claude/Cursor
+- SKILL.md format compatible ✅
+
+**Native tools:** Shell/cmd execution, file read/write, MCP integration (plugins), hooks (before tool, after file edit, session start)
+**Interactive:** No formal `AskUserQuestion` confirmed — TUI-based interaction only
+**Subagents:** Async dispatch from TUI
+
+---
+
+### OpenAI Codex CLI
+**Native tools:** `container.exec`/shell (sandboxed), `apply_patch` (file writing), web search, MCP servers, subagents
+**Config:** `~/.codex/config.toml`
+**Interactive:** TUI-based (Tab to queue, Enter to inject) — no formal agent-initiated `AskUserQuestion`
+**Subagents:** Supported for parallel tasks; "Goal mode" for long-running autonomous operation
+
+---
+
+### GitHub Copilot (Custom Agents)
+**Skill format:** `.github/agents/<name>.agent.md` (YAML frontmatter + system prompt)
+**Available tools:** read, edit, editFiles, runCommands, code_search, readfile, find_references, codebase + explore/task built-in agents
+**AskQuestion:** Yes — `askQuestions` tool available in agent mode (NOT in subagents — VS Code issue #293745)
+**Discovery:** User-driven (@agent-name) — no auto-discovery
+**MCP:** Supported in `.agent.md` frontmatter
+
+---
+
+## Topic 2: Root Cause Analysis
+
+### Confirmed Bug: `cursor_skill_adapter` Tool Name Mismatch
+
+Current SKILL.md all contain:
+```xml
+<cursor_skill_adapter>
+## C. Tool Usage
+Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
+</cursor_skill_adapter>
+```
+
+**Problem:** Claude Code does NOT have these tools:
+| Cursor tool name | Claude Code equivalent | Status |
+|---|---|---|
+| `Shell` | `Bash` | ❌ Wrong name → silently ignored |
+| `ReadFile` | `Read` | ❌ Wrong name → silently ignored |
+| `rg` | `Grep` | ❌ Wrong name → silently ignored |
+| `ApplyPatch` | `Edit` or `Write` | ❌ Wrong name → silently ignored |
+| `Subagent` | `Agent` (Task tool) | ❌ Wrong name → silently ignored |
+| `WebSearch` | `WebSearch` | ✅ Same |
+| `WebFetch` | `WebFetch` | ✅ Same |
+| `Glob` | `Glob` | ✅ Same |
+
+**Result:** When running on Claude Code adapter:
+- All Cursor-specific tool references are silently ignored
+- Adapter-specific execution guidance is lost
+- The SKILL.md's `cursor_skill_adapter` block is rendered but Claude Code can't follow the tool instructions
+- There's ZERO `claude_code_adapter` block equivalent
+
+### Secondary Issues
+1. **No adapter detection** — vp-tools has no `detect-adapter` command
+2. **No capability validation** — `vp-tools validate --adapter <id>` doesn't exist
+3. **Inline compat tables are copy-paste** — every SKILL.md has its own adapter table (fragile, inconsistent)
+4. **AUQ fallback unclear** — the `ToolSearch` preload step (ENH-059) helps, but the fallback behavior for unsupported adapters is documented but not enforced
+5. **Antigravity path updated** — new path is `.agents/skills/` not the old `~/.gemini/antigravity/skills/` (though global install still uses the latter)
+
+---
+
+## Topic 3: v3 Architecture Design
+
+### Decision 1: Unified Adapter Block Standard
+
+Replace `<cursor_skill_adapter>` with per-adapter blocks in all SKILL.md files:
+
+```xml
+<adapter id="claude-code">
+Tools: Bash, Read, Edit, Write, Glob, Grep, WebFetch, WebSearch, Agent
+Interactive: AskUserQuestion (deferred — preload via ToolSearch before first AUQ call)
+Subagents: Task/Agent tool (multi-level nesting supported)
+Rules: .claude/settings.json permissions + hooks
+Skill path: ~/.claude/skills/ or .claude/skills/
+</adapter>
+
+<adapter id="cursor-agent">
+Tools: run_terminal_cmd, read_file, edit_file, grep_search, web_search, codebase_search, list_dir, file_search
+Interactive: Text fallback (AskQuestion Plan Mode only; Agent Mode: async text clarification)
+Subagents: /multitask (single-level only; not a callable tool)
+Rules: .cursor/rules/*.mdc (static — cannot be modified at runtime by agent)
+Skill path: ~/.cursor/skills/ or .cursor/skills/
+</adapter>
+
+<adapter id="antigravity">
+Tools: shell, file_read, file_write, MCP tools
+Interactive: Text fallback (TUI-based; no formal AskUserQuestion)
+Subagents: Async TUI dispatch
+Skill path: ~/.gemini/antigravity/skills/ (global) or .agents/skills/ (project)
+Discovery: LLM-driven (automatic, no slash command needed)
+</adapter>
+
+<adapter id="codex">
+Tools: container.exec (shell), apply_patch, web_search, MCP tools
+Interactive: Text fallback (TUI Tab/Enter injection)
+Subagents: Supported
+Config: ~/.codex/config.toml
+</adapter>
+
+<adapter id="copilot">
+Tools: read, edit, editFiles, runCommands, code_search, find_references
+Interactive: askQuestions (NOT available in subagents — VS Code issue #293745)
+Subagents: Limited
+Skill path: .github/agents/<name>.agent.md
+Discovery: User-driven (@agent-name)
+</adapter>
+```
+
+**Migration:** Replace ALL `<cursor_skill_adapter>` blocks across 21 SKILL.md files with the new 5-block standard.
+
+---
+
+### Decision 2: Adapter Auto-Detection (`vp-tools detect-adapter`)
+
+Heuristic detection at session start:
+```
+1. Check env: $CURSOR_TRACE → cursor-agent
+2. Check env: $ANTIGRAVITY_SESSION → antigravity
+3. Check env: $CODEX_SESSION → codex
+4. Check running process parent: /usr/local/bin/claude → claude-code
+5. Check env: $GITHUB_COPILOT_AGENT → copilot
+6. Fallback: claude-code (most common)
+```
+
+Output: JSON `{ adapter: "claude-code", capabilities: [...], interactive_mode: "AUQ" }`
+Stored in session context for all skills to read.
+
+---
+
+### Decision 3: ADAPTER_CONTEXT Injection (system-level)
+
+At every skill start, inject:
+```
+ADAPTER_CONTEXT = {
+  id: "claude-code",
+  tools: { shell: "Bash", read: "Read", write: "Write", search: "Grep", patch: "Edit", agent: "Agent" },
+  interactive: "AUQ",  // AUQ | text | none
+  subagent: "multi-level",  // multi-level | single-level | none
+  hooks: 28,
+  mcp: true
+}
+```
+
+Skills read ADAPTER_CONTEXT instead of maintaining their own compat tables.
+
+---
+
+### Decision 4: Capability-Gated Fallback Chain
+
+Universal fallback chain for interactive prompts:
+```
+1. ADAPTER_CONTEXT.interactive == "AUQ" → call AskUserQuestion (preload via ToolSearch first)
+2. ADAPTER_CONTEXT.interactive == "text" → show numbered list in plain text
+3. ADAPTER_CONTEXT.interactive == "none" → proceed with defaults (log decision)
+```
+
+Universal fallback chain for shell execution:
+```
+1. claude-code → Bash
+2. cursor-agent → run_terminal_cmd
+3. antigravity → shell
+4. codex → container.exec
+5. copilot → runCommands
+```
+
+No more per-skill if/else logic.
+
+---
+
+### Decision 5: `vp-tools validate --adapter <id>` Command
+
+Validates that the detected adapter can run all ViePilot capabilities:
+- Checks tool availability
+- Checks interactive mode support
+- Warns on limitations (e.g., "Cursor 40-tool MCP limit may conflict with N registered MCP servers")
+- Reports capability gaps
+
+---
+
+## Topic 4: v3 Scope & Phases
+
+### Milestone: v3.0.0 (from v2.51.0)
+
+**Phase structure:**
+- **Phase 127** (M): `vp-tools detect-adapter` + ADAPTER_CONTEXT injection + `vp-tools validate`
+- **Phase 128** (L): Replace `cursor_skill_adapter` with 5-block `<adapter>` standard across all 21 SKILL.md files
+- **Phase 129** (L): Update all workflows (brainstorm.md, crystallize.md, autonomous.md, design.md) with adapter-aware execution paths
+- **Phase 130** (M): Claude Code agent.md subagent definitions + hooks upgrade (validate PreToolUse/PostToolUse usage)
+- **Phase 131** (S): Fix Antigravity skill path (`.agents/skills/` project path support) + Gemini CLI deprecation notice
+- **Phase 132** (S): Tests (≥15) + CHANGELOG + version bump → v3.0.0
+
+**Estimated total:** ~6 phases, XL scope, ~35 tasks
+
+---
+
+## Topic 5: Key Breaking Changes in v3
+
+1. `cursor_skill_adapter` XML block removed from all SKILL.md — replaced by 5 `<adapter>` blocks
+2. `vp-tools install --target <adapter>` now validates adapter capability on install
+3. Hooks upgraded: Claude Code skills can now use PreToolUse/PostToolUse for workflow gates
+4. Antigravity skill path updated to `.agents/skills/` (project) notation alongside `~/.gemini/antigravity/skills/` (global)
+
+---
+
+---
+
+## Topic 6: Multi-Agent Orchestration for vp-auto
+
+### Problem: vp-auto Runs Everything on Main Agent
+
+Current vp-auto executes all tasks sequentially on the main agent thread:
+- Phase loop → task loop → implement → verify → commit → repeat
+- Each implementation turn consumes the full accumulated conversation context
+- By Phase 3-4 the context window is bloated with prior task output, file reads, bash results
+- Independent tasks that could run in parallel are serialized → slow + wasteful
+- No isolation between tasks — a large file read in Task 3 bloats context for Task 7
+
+**Symptom**: User described this as "xử lý Autonomous rất vụng về" (clumsy autonomous handling) with "token dư thừa rất nhiều" (excessive token waste).
+
+---
+
+### Claude Code Multi-Agent Architecture
+
+#### Orchestrator + Worker Pattern (Agent/Task tool)
+
+```
+Main Agent (Orchestrator)
+  ├─ reads phase plan
+  ├─ dispatches Task(worker_1) ← fresh context window
+  ├─ dispatches Task(worker_2) ← fresh context window (parallel)
+  └─ receives only final result from each worker
+```
+
+**Key property:** Each subagent spawned via the `Agent` tool gets a **completely fresh context window**. The parent only receives the worker's final output text — not the worker's intermediate tool calls, file reads, or bash output. This is the token efficiency win.
+
+**Fan-out/fan-in for independent tasks:**
+```
+Orchestrator reads PHASE-STATE.md
+  → identifies 3 independent tasks (T1, T2, T3)
+  → dispatches Agent(T1), Agent(T2), Agent(T3) in parallel
+  → waits for all 3 results
+  → writes PHASE-STATE.md with outcomes
+  → dispatches next batch
+```
+
+#### Agent Teams (Experimental)
+
+Enabled via `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` env var.
+
+```
+Team shared state:
+  - Shared task list (TodoRead/TodoWrite visible to ALL teammates)
+  - Mailbox per teammate (peer-to-peer messaging)
+  - No routing through parent for cross-agent communication
+```
+
+**Pattern:** Teammates claim tasks from shared list, execute independently, report done. Other teammates see completed items and pick next available.
+
+**Recommended team size:** 3-5 teammates, 5-6 tasks each. Beyond this, coordination overhead exceeds parallelism gains.
+
+**When to use teams vs. single orchestrator:**
+| Scenario | Approach |
+|---|---|
+| Tasks are independent, no shared state | Fan-out Agent tool calls |
+| Tasks share output / ordering matters | Single orchestrator sequential |
+| Many similar tasks (e.g., 21 SKILL.md edits) | Agent Team with shared task list |
+| Heterogeneous phases with mixed dependencies | Orchestrator dispatches mini-teams per cluster |
+
+#### `.claude/agents/` Subagent Definitions
+
+Subagents can be pre-configured as YAML-frontmatter `.md` files in `.claude/agents/`:
+
+```yaml
+---
+name: vp-task-executor
+description: Executes a single ViePilot implementation task from task.md contract
+model: claude-haiku-4-5  # cheaper model for routine tasks
+maxTurns: 30
+permissionMode: auto
+tools:
+  - Read
+  - Edit
+  - Write
+  - Bash
+  - Glob
+  - Grep
+disallowedTools:
+  - WebSearch
+  - WebFetch
+hooks:
+  PostToolUse:
+    - type: command
+      command: "node bin/vp-tools.cjs validate-task-output"
+---
+System prompt for the task executor subagent...
+```
+
+**Model selection strategy for vp-auto orchestration:**
+- Orchestrator (phase planner, dependency resolver): `claude-sonnet-4-6` (current)
+- Task executors (file edits, bash, tests): `claude-haiku-4-5` (faster, cheaper for routine work)
+- Reviewers / quality gate checkers: `claude-sonnet-4-6` (needs judgment)
+
+#### Background Agents
+
+- Spawned with `background: true` in agent frontmatter
+- Persist across terminal closes; continue in isolated git worktree
+- Use case: long-running phases (e.g., Phase 128 — 21 SKILL.md files) dispatched as background agent while user continues other work
+- Result surfaced via `vp-tools status` when complete
+
+---
+
+### Orchestration Strategy for vp-auto v3
+
+#### Phase Execution Model (Revised)
+
+```
+vp-auto (Orchestrator, main agent)
+  1. Read PHASE-STATE.md → build dependency graph
+  2. Identify runnable task clusters (tasks with no unmet dependencies)
+  3. For each cluster:
+     a. Dispatch each task as Agent(worker) in parallel
+     b. Worker: reads task.md → implements → commits → reports PASS/FAIL
+     c. Orchestrator: receives results → updates PHASE-STATE.md → next cluster
+  4. Phase complete → git tag → next phase
+```
+
+#### Adapter-Specific Orchestration
+
+| Adapter | Parallelism model | Notes |
+|---|---|---|
+| Claude Code | Agent/Task tool — true parallel subagents | Fresh context windows; can use Teams for large phases |
+| Cursor | `/multitask` command — single-level dispatch | Not a callable tool; limited to ~3-5 parallel |
+| Antigravity | Async TUI dispatch | Manual; limited control |
+| Codex | Subagents supported | Similar to Claude Code but no Teams |
+| Copilot | Serial only | No parallel dispatch in current .agent.md |
+
+#### ADAPTER_CONTEXT Extension for Orchestration
+
+```json
+{
+  "id": "claude-code",
+  "orchestration": {
+    "mode": "agent-tool",
+    "parallel": true,
+    "teams": true,
+    "background": true,
+    "model_override": {
+      "worker": "claude-haiku-4-5",
+      "orchestrator": "claude-sonnet-4-6"
+    },
+    "max_parallel_tasks": 5
+  }
+}
+```
+
+---
+
+### Decision: vp-auto Orchestration Refactor Scope
+
+**Phase 133** (L): vp-auto orchestration refactor
+- Rewrite autonomous.md phase loop to use orchestrator/worker model
+- Define `.claude/agents/vp-task-executor.md` (Haiku model, task impl worker)
+- Define `.claude/agents/vp-phase-planner.md` (dependency resolver)
+- Define `.claude/agents/vp-quality-gate.md` (test runner, output checker)
+- Fan-out dispatch for independent tasks within a cluster
+- Agent Teams pattern for large homogeneous phases (e.g., Phase 128 SKILL.md migration)
+- Adapter fallback: when `ADAPTER_CONTEXT.orchestration.parallel == false` → sequential mode (current behavior preserved)
+- Token budget target: ≥60% reduction vs. current single-agent execution for a typical 7-task phase
+
+---
+
+## Open Questions
+- [ ] Should adapter detection be done in vp-tools CLI or inline in SKILL.md at session start?
+- [ ] Should the `<adapter>` block format be a ViePilot standard or follow an open spec?
+- [ ] How to handle VS Code extension (Claude Code VS Code) — same as claude-code adapter or separate?
+- [x] Should Phase 130 also define `.claude/agents/` YAML-frontmatter subagent definitions for vp-auto parallel task execution? → **YES — moved to Phase 133 dedicated orchestration refactor**
+- [ ] Agent Teams `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` — stable enough for v3 GA? (consider gating behind `vp-tools config set orchestration.teams true`)
+- [ ] Should worker agents use claude-haiku-4-5 by default or let user configure per-phase model?
+
+## ## Phases
+- **Phase 1 (v3 Core):** Adapter detection + context injection + validation + SKILL.md migration + workflow adapter paths + Claude Code agent definitions + Antigravity path fix + orchestration refactor + tests → v3.0.0
+  - Phase 127: vp-tools detect-adapter + ADAPTER_CONTEXT + validate command
+  - Phase 128: SKILL.md 5-block adapter standard (21 files)
+  - Phase 129: Workflow adapter-aware execution paths
+  - Phase 130: Claude Code .claude/agents/ definitions + PreToolUse/PostToolUse hooks
+  - Phase 131: Antigravity path fix + deprecation handling
+  - Phase 132: Tests + CHANGELOG + v3.0.0 bump
+  - Phase 133: vp-auto orchestration refactor (orchestrator/worker model, Agent Teams, Haiku workers)
+
+**Estimated total:** ~7 phases, XL scope, ~42 tasks
+
+## Project meta intake (FEAT-009)
+Existing profile binding present — skip intake.
+
+---
+## Research sources
+- Claude Code docs: tools, hooks (28 events), subagents, MCP, skills
+- Claude Code docs: Agent tool / Task tool, Agent Teams (experimental), background agents, `.claude/agents/` frontmatter spec
+- Cursor docs: Agent mode tools (March 2025 system prompt), Plan mode, /multitask (v3.2), Rules, MCP (40-tool limit)
+- Antigravity docs: skill discovery, SKILL.md format, .agents/skills/ path
+- Codex CLI docs: container.exec, apply_patch, MCP support
+- GitHub Copilot docs: .agent.md frontmatter, askQuestions tool (not in subagents — VS Code #293745)

package/docs/dev/agents.md

@@ -18,77 +18,84 @@ that run in parallel or in sequence without polluting the calling skill's conver
 
 ## Architecture
 
+Since v3.2.0 (ENH-086), all 9 agents are **native Claude Code agent definitions** installed
+to `~/.claude/agents/` and visible in the `/agents` dialog.
+
 ```
-vp-* skill (orchestrator)
+~/.claude/agents/                        ← All 9 agents visible in /agents (v3.2.0+)
     │
-    ├── tracker-agent      ← .viepilot/TRACKER.md read/write
-    ├── research-agent     ← WebSearch + WebFetch (isolated context)
-    ├── file-scanner-agent ← Glob + Grep (repo-wide scanning)
-    ├── changelog-agent    ← CHANGELOG + version bump (single authority)
-    ├── test-generator-agent ← tests/*.test.js generation + run
-    └── doc-sync-agent     ← skills/*/SKILL.md bulk update
+    ├── vp-task-executor.md              ← Task implementation worker
+    ├── vp-phase-planner.md              ← Phase dependency + cluster planner
+    ├── vp-quality-gate.md               ← Verification runner
+    ├── tracker-agent.md                 ← .viepilot/TRACKER.md read/write
+    ├── research-agent.md                ← WebSearch + WebFetch (isolated context)
+    ├── file-scanner-agent.md            ← Glob + Grep (repo-wide scanning)
+    ├── changelog-agent.md               ← CHANGELOG + version bump (single authority)
+    ├── test-generator-agent.md          ← tests/*.test.js generation + run
+    └── doc-sync-agent.md                ← skills/*/SKILL.md bulk update
+
+~/.claude/viepilot/agents/               ← Spec files retained for non-CC adapters
+    └── (same 6 workflow agents, spec format for Cursor/Codex/Antigravity)
 ```
 
-Agent definitions live in `agents/` at the repo root. They are installed to
-`{viepilotDir}/agents/` alongside workflows and templates.
+Native definitions live in `agents/claude-code/` and spec files in `agents/`.
+Both are installed by `vp-tools install --target claude-code`.
 
 ## Agent Catalog
 
 ### tracker-agent
-**File**: `agents/tracker-agent.md`
+**Files**: `agents/tracker-agent.md` (spec), `agents/claude-code/tracker-agent.md` (native, v3.2.0+)
 **Purpose**: Read/write TRACKER.md — phase status, task status, decision log, request table.
 **When to invoke**: vp-auto (task start/complete/phase complete), vp-request (Step 5), vp-evolve (phase creation).
-**Claude Code subagent_type**: `general-purpose`
+**Claude Code subagent_type**: `tracker-agent` (native since v3.2.0)
 
 ### research-agent
-**File**: `agents/research-agent.md`
+**Files**: `agents/research-agent.md` (spec), `agents/claude-code/research-agent.md` (native, v3.2.0+)
 **Purpose**: WebSearch + WebFetch + summarize for feasibility studies and tech research.
 **When to invoke**: vp-request (Step 2B — auto-triggered for Feature/platform requests), vp-brainstorm (external validation).
-**Claude Code subagent_type**: `general-purpose`
+**Claude Code subagent_type**: `research-agent` (native since v3.2.0; uses claude-sonnet-4-6)
 
 ### file-scanner-agent
-**File**: `agents/file-scanner-agent.md`
+**Files**: `agents/file-scanner-agent.md` (spec), `agents/claude-code/file-scanner-agent.md` (native, v3.2.0+)
 **Purpose**: Glob + Grep across repo to find affected files, detect stale refs.
-**When to invoke**: vp-audit (Tier 1–4), vp-evolve (impact analysis), vp-rollback (state restore).
-**Claude Code subagent_type**: `Explore` (specialized for codebase scanning)
+**When to invoke**: vp-audit (Tier 1+2 scan steps), vp-evolve (impact analysis), vp-rollback (state restore).
+**Claude Code subagent_type**: `file-scanner-agent` (native since v3.2.0)
 
 ### changelog-agent
-**File**: `agents/changelog-agent.md`
+**Files**: `agents/changelog-agent.md` (spec), `agents/claude-code/changelog-agent.md` (native, v3.2.0+)
 **Purpose**: Atomically append CHANGELOG entry + bump package.json version.
 **When to invoke**: vp-auto post-phase (last task), vp-evolve (milestone ship).
-**Claude Code subagent_type**: `general-purpose`
+**Claude Code subagent_type**: `changelog-agent` (native since v3.2.0)
 **Note**: Single authority for version bumps — resolves ENH-053.
 
 ### test-generator-agent
-**File**: `agents/test-generator-agent.md`
+**Files**: `agents/test-generator-agent.md` (spec), `agents/claude-code/test-generator-agent.md` (native, v3.2.0+)
 **Purpose**: Generate contract tests from acceptance criteria, run suite, report pass/fail.
-**When to invoke**: Last task of each phase (the `N.last` contract-test task pattern).
-**Claude Code subagent_type**: `general-purpose`
+**When to invoke**: Last task of each phase — triggered by `autonomous.md` when task has `## Acceptance Criteria`.
+**Claude Code subagent_type**: `test-generator-agent` (native since v3.2.0)
 
 ### doc-sync-agent
-**File**: `agents/doc-sync-agent.md`
+**Files**: `agents/doc-sync-agent.md` (spec), `agents/claude-code/doc-sync-agent.md` (native, v3.2.0+)
 **Purpose**: Bulk-apply the same change to ≥5 `.md` files (adapter rows, banners, etc.).
 **When to invoke**: Auto-triggered by autonomous.md when task Paths block has ≥5 identical file types.
-**Claude Code subagent_type**: `general-purpose`
+**Claude Code subagent_type**: `doc-sync-agent` (native since v3.2.0)
 
 ## Invocation Patterns
 
-### Claude Code (terminal)
+### Claude Code (terminal) — v3.2.0+
 
-Use the `Agent` tool with the appropriate `subagent_type`:
+Use the agent's name directly as `subagent_type`:
 
 ```js
 Agent({
-  subagent_type: "general-purpose",  // or "Explore" for file-scanner
-  description: "{agent-name}: {operation-summary}",
-  prompt: `
-    Load agents/{agent-name}.md for the full specification.
-    Execute operation: {operation}
-    Inputs: {inputs}
-  `
+  subagent_type: "changelog-agent",   // direct native agent type
+  description: "Bump to {version} + CHANGELOG",
+  prompt: "version: {version}. date: {today}. entries: {entries}."
 })
 ```
 
+No "Load agents/X.md" preamble needed — the system prompt is baked into the native definition.
+
 ### Cursor / Codex / Antigravity
 
 Execute the equivalent operation inline in the same session. The agent `.md` file
@@ -98,12 +105,12 @@ describes the exact steps — follow them as a scoped sub-prompt.
 
 | Agent | Claude Code | Cursor | Codex | Antigravity |
 |-------|------------|--------|-------|-------------|
-| tracker-agent | Subagent (general-purpose) | Inline | Inline | Inline |
-| research-agent | Subagent (general-purpose) | Inline if web available | Inline if web available | Inline if web available |
-| file-scanner-agent | Subagent (Explore) | Inline | Inline | Inline |
-| changelog-agent | Subagent (general-purpose) | Inline | Inline | Inline |
-| test-generator-agent | Subagent (general-purpose) | Inline | Inline | Inline |
-| doc-sync-agent | Subagent (general-purpose) | Sequential inline | Sequential inline | Sequential inline |
+| tracker-agent | Native: `tracker-agent` (v3.2.0+) | Inline | Inline | Inline |
+| research-agent | Native: `research-agent` (v3.2.0+) | Inline if web available | Inline if web available | Inline if web available |
+| file-scanner-agent | Native: `file-scanner-agent` (v3.2.0+) | Inline | Inline | Inline |
+| changelog-agent | Native: `changelog-agent` (v3.2.0+) | Inline | Inline | Inline |
+| test-generator-agent | Native: `test-generator-agent` (v3.2.0+) | Inline | Inline | Inline |
+| doc-sync-agent | Native: `doc-sync-agent` (v3.2.0+) | Sequential inline | Sequential inline | Sequential inline |
 
 ## Adding a New Agent
 
@@ -115,12 +122,15 @@ describes the exact steps — follow them as a scoped sub-prompt.
    - `## Adapter Behavior` (table covering all 4 adapters)
    - `## Notes`
 
-2. Add the agent to the delegation table in `workflows/autonomous.md`
+2. Create `agents/claude-code/{name}-agent.md` with YAML frontmatter (name, description,
+   model, tools, disallowedTools) and focused system prompt. Reference `vp-task-executor.md`.
+
+3. Add the agent to the delegation table in `workflows/autonomous.md`
    under `## Agent Delegation`.
 
-3. Wire invocation into the relevant workflow steps.
+4. Wire invocation into the relevant workflow steps using `subagent_type: "{name}-agent"`.
 
-4. Add to `installSubdirs` in the adapter that should include `agents/`.
+5. `claudeAgentsSrc: 'agents/claude-code'` already covers all files — no install config change needed.
 
 5. Write a contract test in `tests/unit/` verifying the file exists and has required sections.
 

package/docs/dev/architecture.md

@@ -216,6 +216,32 @@ User Request
 | No external runtime | Works with any AI assistant |
 | CommonJS (no ESM) | Maximum Node.js compatibility |
 
+## Agent Orchestration Model (ENH-096/097)
+
+As of v3.7.2, the vp-auto orchestrator is **read + spawn only**. It never calls Edit, Write, or Bash for any write operation. All work is delegated to specialized subagents:
+
+| Agent | Role | Tools Permitted |
+|-------|------|-----------------|
+| vp-auto orchestrator | Read state, spawn workers, gate phase transitions | Read, Bash (read-only git only), Agent |
+| vp-task-executor | All implementation — code, docs, config edits | Read, Edit, Write, MultiEdit, Bash, Glob, Grep, LS |
+| vp-quality-gate | Run verification commands, report PASS/FAIL | Read, Bash, Grep, Glob, LS |
+| vp-phase-planner | Build dependency graph, identify parallel task clusters | Read, Glob, Grep, LS |
+| tracker-agent | Write state files: PHASE-STATE.md, TRACKER.md, HANDOFF.json, ROADMAP.md | Read, Edit, Write |
+| vp-git-agent | Git operations: create-tag, push-branch, push-tags, push-all, git-status | Bash only |
+| changelog-agent | Write CHANGELOG.md entries for features and fixes | Read, Edit, Write |
+
+**Result formats:**
+- `TASK_RESULT: PASS | FAIL | PARTIAL` — returned by vp-task-executor and vp-quality-gate
+- `GIT_RESULT: PASS | FAIL | SKIP` — returned by vp-git-agent
+
+**Orchestration flow:**
+1. Orchestrator reads PHASE-STATE.md + task contracts
+2. Spawns tracker-agent → set tasks `in_progress`
+3. Spawns vp-task-executor(s) — parallel fan-out for independent tasks
+4. Spawns vp-quality-gate for each completed task
+5. On PASS: spawns tracker-agent → mark task done, update HANDOFF.json
+6. On phase complete: spawns vp-git-agent (tag + push), tracker-agent (ROADMAP update), changelog-agent
+
 ## Extension Points
 
 | Point | How to Extend |