viepilot 2.50.1 → 3.7.2

package/skills/vp-update/SKILL.md

@@ -53,14 +53,63 @@ Silent if command unavailable or errors.
 </persona_context>
 
 
-<cursor_skill_adapter>
+<adapter id="claude-code">
 ## A. Skill Invocation
 - Skill được gọi khi user mention `vp-update`, `/vp-update`, "upgrade viepilot", "cập nhật viepilot npm"
 - Treat all user text after the skill mention as `{{VP_ARGS}}`
 
 ## B. Tool Usage
-Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
-</cursor_skill_adapter>
+Use Claude Code tools: `Bash` (shell), `Read` (file), `Edit` + `Write` (file write/patch),
+`Grep` (search), `Glob` (file patterns), `LS`, `WebSearch`, `WebFetch`,
+`Agent` (spawn subagent — multi-level nesting supported)
+Interactive: `AskUserQuestion` (deferred — preload via ToolSearch before first call)
+</adapter>
+
+<adapter id="cursor-agent">
+## A. Skill Invocation
+Same trigger keywords as claude-code adapter.
+
+## C. Tool Usage
+Use Cursor tools: `run_terminal_cmd` (shell), `read_file` (read), `edit_file` (write/edit),
+`grep_search` (search), `web_search`, `codebase_search`, `list_dir`, `file_search`
+Interactive: text list fallback (AskQuestion available in Plan Mode only; Agent Mode = text)
+Subagent: `/multitask` (user command, single-level only — not a callable tool)
+MCP limit: 40 tools
+</adapter>
+
+<adapter id="antigravity">
+## A. Skill Invocation
+Same trigger keywords as claude-code adapter.
+Skill discovery: LLM-driven (automatic, no slash command needed).
+
+## C. Tool Usage
+Use Antigravity tools: `shell` (cmd), `file_read`, `file_write`, MCP plugins
+Interactive: text fallback (TUI-based; no formal AskUserQuestion)
+Skill path: `.agents/skills/<skill>/SKILL.md` (project) or `~/.gemini/antigravity/skills/` (global)
+Note: Gemini CLI deprecated June 18, 2026 — use Antigravity CLI.
+</adapter>
+
+<adapter id="codex">
+## A. Skill Invocation
+Same trigger keywords as claude-code adapter.
+
+## C. Tool Usage
+Use Codex tools: `container.exec` (sandboxed shell), `apply_patch` (file write), `web_search`
+Interactive: text fallback (TUI Tab/Enter injection)
+Config: `~/.codex/config.toml`
+</adapter>
+
+<adapter id="copilot">
+## A. Skill Invocation
+Same trigger keywords as claude-code adapter.
+Discovery: User-driven (`@agent-name` in GitHub Copilot Chat).
+
+## C. Tool Usage
+Use Copilot tools: `runCommands` (shell), `read`/`readfile` (read), `edit`/`editFiles` (write),
+`code_search`, `find_references`
+Interactive: `askQuestions` (main agent only — NOT available in subagents; VS Code issue #293745)
+Skill path: `.github/agents/<name>.agent.md`
+</adapter>
 <scope_policy>
 ## ViePilot Namespace Guard (BUG-004)
 - Default mode: only use and reference `vp-*` skills in ViePilot workflows.

package/workflows/autonomous.md

@@ -37,6 +37,27 @@ Agent({
 
 See `agents/` directory for full agent specifications.
 
+## v3 Orchestration Agents (Phase 130 — FEAT-021)
+
+On Claude Code adapter (when `ADAPTER_CONTEXT.orchestration.parallel == true`), three dedicated
+subagent definitions in `agents/claude-code/` handle orchestrated execution:
+
+| Agent | File | Model | Role |
+|-------|------|-------|------|
+| vp-task-executor | `agents/claude-code/vp-task-executor.md` | claude-haiku-4-5 | Implements a single task contract; fresh context window per task |
+| vp-phase-planner | `agents/claude-code/vp-phase-planner.md` | claude-sonnet-4-6 | Reads phase, builds dependency graph, identifies parallel clusters |
+| vp-quality-gate | `agents/claude-code/vp-quality-gate.md` | claude-sonnet-4-6 | Runs verification commands; reports PASS/FAIL/PARTIAL |
+
+**Fan-out pattern** (implemented in Phase 133):
+```
+vp-phase-planner → clusters → Agent(vp-task-executor) × N (parallel) → Agent(vp-quality-gate)
+```
+
+**PreToolUse/PostToolUse hooks** (Claude Code only, registered via `vp-tools hooks install --adapter claude-code`):
+- `PreToolUse` on `Write`/`Edit` in task scope: validates path is repo-relative (BUG-009 gate)
+- `PostToolUse` on `Bash`: captures command output for quality-gate evidence log
+- Hook config lives in `~/.claude/settings.json` → `hooks` array
+
 <process>
 
 > **AUQ preload — Claude Code adapter (ENH-059):** At session start, before any interactive prompt, call `ToolSearch` with `query: "select:AskUserQuestion"` to load the deferred schema. Required on Claude Code (terminal). Skip only if `ToolSearch` returns an error → use text fallback for that session.
@@ -95,6 +116,39 @@ Build `SKILL_CONTEXT_MAP` in session memory:
 
 **If `## Skills` section absent or empty**: silent no-op — `SKILL_CONTEXT_MAP = { required: [], optional: [] }`.
 
+### ADAPTER_CONTEXT Injection (FEAT-021 Phase 127)
+
+Detect the active adapter and inject its capability map into session context. Skills use
+ADAPTER_CONTEXT to select correct tool names and fallback chains — no inline compat tables.
+
+```bash
+ADAPTER_CONTEXT_JSON=$(node "$HOME/.claude/viepilot/bin/vp-tools.cjs" detect-adapter --json 2>/dev/null \
+  || node "$(pwd)/bin/vp-tools.cjs" detect-adapter --json 2>/dev/null \
+  || echo '{"adapter":"claude-code","interactive_mode":"AUQ","orchestration":{"parallel":true,"teams":true},"capabilities":["shell","read","write","edit","search","agent","interactive"]}')
+```
+
+Parse into session variables:
+- `ADAPTER_ID` — e.g. `"claude-code"`
+- `ADAPTER_INTERACTIVE` — `"AUQ"` | `"text"` | `"none"`
+- `ADAPTER_PARALLEL` — `true` | `false` (orchestration.parallel)
+- `ADAPTER_TOOLS` — tools{} map (use `ctx.tools.shell` → correct tool name)
+
+**Shell tool resolution** (use `ADAPTER_TOOLS.shell` for all bash/cmd execution in tasks):
+| Adapter | Shell tool |
+|---|---|
+| claude-code | `Bash` |
+| cursor-agent | `run_terminal_cmd` |
+| antigravity | `shell` |
+| codex | `container.exec` |
+| copilot | `runCommands` |
+
+**Interactive fallback chain** (based on `ADAPTER_INTERACTIVE`):
+1. `"AUQ"` → call `AskUserQuestion` (preload via ToolSearch first)
+2. `"text"` → show numbered list in plain text
+3. `"none"` → proceed with defaults (log decision)
+
+Silent on error — do not fail the phase. Fallback: assume `claude-code` defaults.
+
 ### Tag Prefix Resolution (ENH-050)
 Resolve the enriched git tag prefix once at session start. All task/phase tags use `${TAG_PREFIX}`.
 
@@ -170,9 +224,137 @@ cat .viepilot/phases/{phase}/PHASE-STATE.md
 
 Check if phase already has completed tasks → resume from next task.
 
+### 3b. Orchestration Mode Selection (Phase 133 — FEAT-021)
+
+> ⛔ **ORCHESTRATOR STOP — Implementation Delegation Rule (ENH-096)**
+>
+> On Claude Code adapter, the main orchestrator agent MUST NOT:
+> - Call `Edit`, `Write`, or `MultiEdit` on implementation files (`lib/`, `bin/`, `tests/`, `agents/`, `skills/`, `workflows/` shipping content)
+> - Run `Bash` commands that write source code (e.g. `cat >`, `tee`, compiler/bundler invocations for production output)
+> - Implement features, fix bugs, or write tests inline in this context
+>
+> **Inline implementation is a framework violation.** It fills the orchestrator's context with
+> implementation tokens (file diffs, test output, compile logs), degrading orchestration quality
+> across subsequent tasks.
+>
+> The orchestrator is permitted ONLY to:
+> - `Read` — read PHASE-STATE.md, TRACKER.md, HANDOFF.json, task files, ROADMAP.md (read-only)
+> - `Bash` — read-only git checks ONLY: `git status --porcelain` (BUG-013: `??` lines = untracked, not dirty), `git rev-list --count @{u}..HEAD`, `node bin/vp-tools.cjs git-persistence --strict`
+> - `Agent` — spawn vp-task-executor, vp-quality-gate, vp-phase-planner, tracker-agent, vp-git-agent, changelog-agent
+>
+> The orchestrator MUST NOT call Edit, Write, or Bash for ANY writes — including state files.
+> All writes and git operations go through subagents (ENH-097).
+>
+> All implementation (file edits, test runs for implementation, commits) MUST go through
+> `vp-task-executor`. This applies even when there is only one task in the phase.
+
+Before entering the task loop, check `ADAPTER_PARALLEL` (set in ADAPTER_CONTEXT Injection step):
+
+```
+IF ADAPTER_PARALLEL == true AND ADAPTER_ID == "claude-code":
+  → ORCHESTRATOR MODE: fan-out dispatch via Agent tool (section 3b-orch)
+ELSE:
+  → SEQUENTIAL MODE: single-agent serial execution (section 3b-seq)
+```
+
+**Agent Teams mode** (when `ADAPTER_CONTEXT.orchestration.teams == true` AND pending task count ≥ 8):
+- Set `TEAMS_MODE = true`
+- Activate shared TodoWrite task list for teammate coordination
+- Each Agent worker reads from the shared list rather than receiving an explicit task prompt
+
+#### 3b-orch: Orchestrator Fan-out (Claude Code only)
+
+When `ADAPTER_PARALLEL == true`:
+
+**Step 1 — Dependency resolution** (via `vp-phase-planner` agent):
+```
+Agent(
+  subagent_type: "vp-phase-planner",
+  prompt: "Analyze phase {N} tasks in .viepilot/phases/{dir}/PHASE-STATE.md.
+           Return JSON: { clusters: [ { tasks: [id,...], can_parallel: bool,
+           sequential_fallback: [id,...] } ] }
+           Only include incomplete tasks."
+)
+```
+
+Parse `clusters` JSON from agent output. Each cluster is a set of independent tasks that can run in parallel.
+
+**Step 2 — Fan-out dispatch** (parallel `Agent` calls per cluster):
+```
+FOR each cluster in clusters:
+  IF cluster.can_parallel == true AND cluster.tasks.length > 1:
+    → Dispatch tasks in parallel:
+    FOR EACH task_id in cluster.tasks (simultaneously):
+      Agent(
+        subagent_type: "vp-task-executor",
+        prompt: "Execute task {task_id} in phase {N}.
+                 Task file: .viepilot/phases/{dir}/tasks/{task_id}.md
+                 PHASE-STATE: .viepilot/phases/{dir}/PHASE-STATE.md
+                 Repo root: {cwd}
+                 Return: TASK_RESULT: PASS|FAIL|PARTIAL + summary"
+      )
+    Collect all TASK_RESULT outputs before advancing.
+  ELSE:
+    → Execute tasks in sequence (cluster.sequential_fallback order)
+    Agent(vp-task-executor, single task)
+```
+
+**Spawn Template (copy-paste verbatim — do not paraphrase):**
+```
+Agent({
+  subagent_type: "vp-task-executor",
+  description: "Execute task {task_id} — phase {N}",
+  prompt: `Execute ViePilot task {task_id} for phase {N}.
+
+Task file: {task_path}
+Phase state: {phase_dir}/PHASE-STATE.md
+Repo root: {cwd}
+
+Read the task file completely, implement all acceptance criteria, run verification
+commands, commit with message format: {projectPrefix}-vp-p{N}-t{task_id}: <summary>,
+then report:
+TASK_RESULT: PASS|FAIL|PARTIAL
+Committed: <sha> — <message>
+Criteria: ✅/❌ per item`
+})
+```
+
+Replace `{task_id}`, `{N}`, `{task_path}`, `{phase_dir}`, `{cwd}`, `{projectPrefix}` with actual values.
+The orchestrator MUST NOT call Edit/Write/Bash for implementation — the subagent handles all of that.
+
+**Model tiering** (`ADAPTER_CONTEXT.orchestration.model_override`):
+- Worker agent (vp-task-executor): `claude-haiku-4-5` — routine file edits, low token cost
+- Planner/gate agent (vp-phase-planner, vp-quality-gate): `claude-sonnet-4-6` — reasoning, dependency analysis
+- Orchestrator (main agent): retains current model — coordination only, no implementation
+
+**Step 3 — Quality gate** (after each cluster completes):
+```
+Agent(
+  subagent_type: "vp-quality-gate",
+  prompt: "Run verification for phase {N} cluster {C}.
+           Tasks completed: {task_ids}
+           Check: acceptance criteria, tests, lint.
+           Return: QUALITY_GATE: PASS|FAIL|PARTIAL + findings"
+)
+```
+
+On `QUALITY_GATE: FAIL` or `PARTIAL` → route to control point (retry cluster / skip / stop).
+On `QUALITY_GATE: PASS` → update PHASE-STATE.md (all cluster tasks → done), update TRACKER.md, continue.
+
+**Teams mode** (when `TEAMS_MODE == true`):
+- Write all pending task IDs to shared `TodoWrite` list at phase start
+- Each `Agent(vp-task-executor)` reads next available task from shared list
+- Prevents duplicate execution when dispatching ≥ 8 tasks concurrently
+
+#### 3b-seq: Sequential Mode (non-Claude Code adapters)
+
+When `ADAPTER_PARALLEL == false` (Cursor / Antigravity / Codex / Copilot):
+
+Execute tasks one at a time in the main agent context. No fan-out, no subagent dispatch.
+
 ### 3b. Execute Tasks Loop
 
-For each task in phase:
+For each task in phase (sequential mode) or per cluster (orchestrator mode):
 
 #### Load Task Context
 ```yaml
@@ -449,9 +631,9 @@ IF (Paths block contains ≥5 files of the same type, e.g., skills/*/SKILL.md)
   OR (task description matches: "update all N files", "add row to all skills", "sync across N files")
 → Invoke doc-sync-agent instead of N sequential edits:
 
-   Agent({ subagent_type: "general-purpose",
+   Agent({ subagent_type: "doc-sync-agent",
      description: "doc-sync-agent: {change_mode} across {file_pattern}",
-     prompt: "Load agents/doc-sync-agent.md. Pattern: {glob}. Mode: {change_mode}. Anchor: {anchor}. Content: {content}."
+     prompt: "file_pattern: {glob}. change_mode: {change_mode}. anchor: {anchor}. content: {content}."
    })
    Non-Claude Code: apply changes sequentially inline.
 
@@ -507,6 +689,21 @@ quality_gate:
   - no_lint_errors: true
 ```
 
+#### Test Generation — test-generator-agent (ENH-057, BUG-028 fix)
+
+**Trigger**: current task is the last task in the phase AND task.md contains `## Acceptance Criteria`
+
+**Claude Code — invoke test-generator-agent:**
+```
+Agent({ subagent_type: "test-generator-agent",
+  description: "test-generator-agent: generate + run contract tests for phase {phase}",
+  prompt: "task_file: {task_md_path}. test_output_path: tests/unit/phase{phase}-{task}-contract.test.js. phase_number: {phase}. task_number: {task}."
+})
+```
+Non-Claude Code: generate test file inline from acceptance criteria, then run `npm test`.
+
+If test-generator-agent reports FAIL: **do NOT** mark task complete — fix failing criteria first.
+
 #### Git Persistence Gate (BUG-003)
 Before marking a task PASS, require durable git persistence:
 
@@ -540,6 +737,30 @@ If any check fails:
 - Update TRACKER.md immediately
 - Update HANDOFF.json immediately
 - Update CHANGELOG.md if feature/fix
+
+**Post-PASS: Intake Write-back (ENH-095)**
+
+After the above state updates, check the task `.md` for an `## Intake Source` block:
+```
+## Intake Source
+- channel_id:    trip-tracking-bug
+- sheet_name:    BUG
+- source_row:    1
+- manifest_path: .viepilot/intake/trip-tracking-bug-manifest.json
+- channel_type:  excel_m365
+- workbook_id:   {workbook_id or null}
+- sharing_url:   {sharing_url or null}
+```
+
+If the block is present:
+1. Parse the fields from the block
+2. Load manifest from `manifest_path` via `lib/intake/manifest.cjs → loadManifest()`
+3. Call `getWriteBackConfig(manifest, sheet_name)` → get `response_col`
+4. Build `response = { status: 'Fixed ✓', phaseTask: 'vp-p{N}-t{M}', version: currentVersion, date: YYYY-MM-DD }`
+5. Call `lib/intake/writeback.cjs → writebackIntakeResponse(channel, source_row, response, projectRoot, sheet_name, response_col)`
+6. Log: `[vp-auto] Intake write-back: row {source_row} → col {response_col}: "{text}" — {success|failed}`
+7. **Write-back failure is non-fatal** — log to stderr and continue to next task regardless
+
 - Move to next task
 
 **PARTIAL (some checks fail):**
@@ -564,14 +785,28 @@ update:
   - CHANGELOG.md: if feature/fix completed  ← via changelog-agent at end of phase (ENH-057)
 ```
 
-**Tracker updates — invoke tracker-agent:**
+**State updates — spawn subagents (Claude Code, ENH-097):**
+
 ```
-Agent({ subagent_type: "general-purpose",
-  description: "tracker-agent: update task {phase}.{task} → {status}",
-  prompt: "Load agents/tracker-agent.md. Operation: update-task-status. Phase: {phase}. Task: {task}. Status: {status}."
+# Task status (PHASE-STATE.md + TRACKER.md current state):
+Agent({ subagent_type: "tracker-agent",
+  description: "Update task {N}.{task_id} → {status}",
+  prompt: "operation: update-task-status. phase: {N}. task: {task_id}. status: {status}."
+})
+
+# HANDOFF.json update:
+Agent({ subagent_type: "tracker-agent",
+  description: "Update HANDOFF.json — phase {N} task {task_id}",
+  prompt: "operation: update-handoff. phase: {N}. phase_name: {phase_name}. task: {task_id}. task_name: {task_name}. status: {status}. version: {version}. tasks_total: {T}. tasks_completed: {C}. notes: [\"{note}\"]."
+})
+
+# ROADMAP.md phase status sync (after phase complete):
+Agent({ subagent_type: "tracker-agent",
+  description: "Update ROADMAP.md — phase {N} done",
+  prompt: "operation: update-roadmap-phase. phase_number: {N}. status: ✅ done. completed_date: {today}."
 })
 ```
-Non-Claude Code: update TRACKER.md inline as before.
+Non-Claude Code: update TRACKER.md, HANDOFF.json, ROADMAP.md inline as before.
 
 Rule:
 - Never defer state updates to end-of-phase only.
@@ -633,15 +868,21 @@ Before phase-level verification, run a UI stub check:
    | smarttrack-*/pom.xml (8 files) | 1.1 |   ← WRONG: glob pattern
    | smarttrack-*/src/** (7 files)  | 1.1 |   ← WRONG: summarized
    ```
-4. Create git tag: `{TAG_PREFIX}-vp-p{phase}-complete` (e.g. `git tag "${TAG_PREFIX}-vp-p${PHASE}-complete"`)
+4. Create phase-complete git tag — spawn vp-git-agent:
+   ```
+   Agent({ subagent_type: "vp-git-agent",
+     description: "Tag phase {N} complete",
+     prompt: "operation: create-tag. tag_name: {TAG_PREFIX}-vp-p{N}-complete."
+   })
+   ```
 5. Check version bump needed — apply `.viepilot/SYSTEM-RULES.md → Version Bump Rules`:
    - Features added → MINOR; Fixes only → PATCH; Mixed → MINOR; Breaking → MAJOR
 
    **Version bump — invoke changelog-agent (ENH-057, ENH-053 fix):**
    ```
-   Agent({ subagent_type: "general-purpose",
-     description: "changelog-agent: bump to {version} + CHANGELOG [{version}]",
-     prompt: "Load agents/changelog-agent.md. Version: {version}. Date: {today}. Entries: {phase_summary_bullets}. Files: package.json + CHANGELOG.md."
+   Agent({ subagent_type: "changelog-agent",
+     description: "Bump to {version} + CHANGELOG [{version}]",
+     prompt: "version: {version}. date: {today}. entries: {phase_summary_bullets}."
    })
    ```
    Non-Claude Code: update CHANGELOG.md + package.json inline as before.
@@ -649,13 +890,22 @@ Before phase-level verification, run a UI stub check:
    > changelog-agent is the **single authority** for version bumps. Both autonomous.md and
    > evolve.md invoke it — never do inline version bumps (resolves ENH-053).
 
-6. Update TRACKER.md
-7. Push all changes:
-   ```bash
-   git push
-   git push --tags
-   node bin/vp-tools.cjs git-persistence --strict
+6. Update TRACKER.md current state — spawn tracker-agent:
+   ```
+   Agent({ subagent_type: "tracker-agent",
+     description: "Update TRACKER.md — phase {N} complete",
+     prompt: "operation: update-current-state. data: Last completed phase {N} — {phase_name}. version: {version}."
+   })
+   ```
+7. Push branch + tags — spawn vp-git-agent:
+   ```
+   Agent({ subagent_type: "vp-git-agent",
+     description: "Push phase {N} complete",
+     prompt: "operation: push-all."
+   })
    ```
+   Then verify persistence (orchestrator may call this read-only check directly):
+   `node bin/vp-tools.cjs git-persistence --strict`
 
 ### 5a. Sync ROADMAP.md (after every phase complete)