viepilot 3.10.0 → 3.12.0

package/CHANGELOG.md

@@ -9,6 +9,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [3.12.0] - 2026-05-25
+### Changed
+- `workflows/autonomous.md`: tracker-agent now rewrites Current State block (find-and-replace)
+  instead of appending — TRACKER.md stays ≤ 20 lines regardless of phase count (DEBT-002)
+- `workflows/autonomous.md`: auto-compact size guard — if TRACKER.md > 400 lines, runs
+  `vp-tools tracker compact` before reading (DEBT-002)
+- `workflows/autonomous.md`: Decision Log capped at 20 rows; older rows archived to TRACKER-HISTORY.md
+
+### Added
+- `lib/tracker-compact.cjs`: compact() + rewriteCurrentState() — rescue tool for bloated TRACKER.md files
+- `bin/vp-tools.cjs`: `tracker compact [--keep N]` subcommand — compact bloated TRACKER.md, archive history to TRACKER-HISTORY.md
+
+---
+
+## [3.11.0] - 2026-05-25
+
+### Added
+- ENH-100: New `/vp-qa` skill — scan-first QA agent team generator
+- ENH-100: Phase 1 (Research) reads codebase structure, detects stack, samples source files,
+  reads stack reference docs, then LLM decides domains + agent count
+- ENH-100: Phase 2 (Generate) — LLM writes agent files directly using Write tool;
+  content fully determined by research output (no templates)
+- ENH-100: Adapter-specific output — Claude Code: `.claude/agents/` (multi-agent
+  orchestrator + subagents); Codex: `AGENTS.md` append; Cursor: `.cursor/rules/` MDC;
+  Antigravity: `.agents/skills/`; Copilot: `.github/agents/`
+- ENH-100: `lib/qa-router.cjs` — adapter path mapping (resolveOutputSpec, expectedPaths)
+- ENH-100: `agents/qa-templates/rules/` — stack reference docs for Node.js, Python,
+  Java, Go, Ruby (LLM reads during research phase for stack-specific anti-patterns)
+- ENH-100: Generated `qa-orchestrator` creates `.viepilot/requests/BUG-{N}.md` entries
+  with AskUserQuestion accept/decline + `/vp-evolve` suggestion
+
+---
+
 ## [3.10.0] - 2026-05-25
 
 ### Added

package/bin/vp-tools.cjs

@@ -1389,6 +1389,70 @@ ${colors.cyan}Examples:${colors.reset}
     console.log();
   },
 
+  /**
+   * Compact bloated TRACKER.md and archive history (DEBT-002)
+   * Usage: vp-tools tracker compact [--keep N] [--dry-run] [--path <file>]
+   */
+  tracker: (args) => {
+    const sub = args[0];
+
+    if (!sub || sub === 'help') {
+      console.log(`${colors.cyan}Usage:${colors.reset}
+  vp-tools tracker compact [--keep N] [--dry-run] [--path <file>]
+
+${colors.cyan}Subcommands:${colors.reset}
+  compact   Compact bloated TRACKER.md, archive history
+
+${colors.cyan}Options:${colors.reset}
+  --keep N       Number of rows to keep (default: 5)
+  --dry-run      Preview changes without writing
+  --path <file>  Path to TRACKER.md (default: .viepilot/TRACKER.md)
+
+${colors.cyan}Examples:${colors.reset}
+  ${colors.gray}$${colors.reset} vp-tools tracker compact
+  ${colors.gray}$${colors.reset} vp-tools tracker compact --keep 10 --dry-run
+  ${colors.gray}$${colors.reset} vp-tools tracker compact --path /path/to/TRACKER.md`);
+      return;
+    }
+
+    if (sub === 'compact') {
+      // Parse options
+      const keepIdx = args.indexOf('--keep');
+      const keepN = keepIdx !== -1 ? parseInt(args[keepIdx + 1], 10) : 5;
+      const isDryRun = args.includes('--dry-run');
+
+      const pathIdx = args.indexOf('--path');
+      const argPath = pathIdx !== -1 ? args[pathIdx + 1] : null;
+
+      const trackerPath = argPath || path.join(process.cwd(), '.viepilot', 'TRACKER.md');
+
+      try {
+        const { compact } = require(path.join(__dirname, '../lib/tracker-compact.cjs'));
+        const result = compact(trackerPath, { keep: keepN, dryRun: isDryRun });
+
+        if (isDryRun) {
+          console.log(`[dry-run] Would compact ${trackerPath}`);
+          console.log(`  Lines to remove:  ${result.linesRemoved}`);
+          console.log(`  Rows to archive:  ${result.rowsArchived}`);
+          console.log('  No files written.');
+        } else {
+          console.log(formatSuccess(`Compacted ${trackerPath}`));
+          console.log(`  Lines removed:  ${result.linesRemoved}`);
+          console.log(`  Rows archived:  ${result.rowsArchived}`);
+          console.log(`  History file:   ${result.historyFile}`);
+          console.log(`  Result:         ${result.trackerLines} lines remaining`);
+        }
+        process.exit(0);
+      } catch (err) {
+        console.error(formatError('tracker compact error:', err.message));
+        process.exit(1);
+      }
+    }
+
+    console.error(formatError(`Unknown tracker subcommand: ${sub}`, 'Use: compact'));
+    process.exit(1);
+  },
+
   /**
    * Validate adapter capability requirements (FEAT-021 Phase 127)
    * Usage: vp-tools validate --adapter <id>
@@ -1618,6 +1682,20 @@ ${colors.cyan}Examples:${colors.reset}
           'vp-tools update --global --dry-run',
         ],
       },
+      'tracker': {
+        usage: 'vp-tools tracker compact [--keep N] [--dry-run] [--path <file>]',
+        description: 'Compact bloated TRACKER.md and archive history',
+        options: [
+          '--keep N: Number of rows to keep (default: 5)',
+          '--dry-run: Preview changes without writing',
+          '--path <file>: Path to TRACKER.md (default: .viepilot/TRACKER.md)',
+        ],
+        examples: [
+          'vp-tools tracker compact',
+          'vp-tools tracker compact --keep 10 --dry-run',
+          'vp-tools tracker compact --path /path/to/TRACKER.md',
+        ],
+      },
     };
 
     if (command && commandHelp[command]) {
@@ -1669,6 +1747,7 @@ ${colors.cyan}Commands:${colors.reset}
   ${colors.bold}persona${colors.reset} <op>              Manage user personas (get|infer|list|set|auto-switch|context)
   ${colors.bold}detect-adapter${colors.reset} [--json]   Detect active adapter (claude-code/cursor/antigravity/codex/copilot)
   ${colors.bold}validate${colors.reset} --adapter <id>   Validate adapter capability requirements; exits 1 on critical gaps
+  ${colors.bold}tracker${colors.reset} compact [--keep N] Compact bloated TRACKER.md, archive history
   ${colors.bold}help${colors.reset} [command]           Show help (optionally for specific command)
 
 ${colors.cyan}Examples:${colors.reset}

package/docs/skills-reference.md

@@ -643,3 +643,39 @@ controls output style, stack preferences, and team-size assumptions injected int
 ### Output
 - `~/.viepilot/config.json` updated
 - `## User Persona` injected into each skill session
+
+---
+
+## /vp-qa
+
+**Version**: v1.0.0 (fw 2.19.0)
+**Phase**: 148 (ENH-100)
+
+Scan-first QA agent team generator. Researches the codebase first (stack detection, file sampling,
+domain mapping), then generates a context-tailored QA agent team using the Write tool directly — no
+templates. Number of agents and their domains are determined by research output.
+
+### Triggers
+`vp-qa`, `/vp-qa`, "qa agents", "generate qa team", "quality assurance agents"
+
+### Flags
+- `/vp-qa` — auto-detect adapter + stack, generate QA team
+- `/vp-qa --run` — generate + immediately invoke qa-orchestrator
+- `/vp-qa --focus sec` — bias research toward security domains
+- `/vp-qa --focus perf` — bias research toward performance domains
+- `/vp-qa --target <id>` — override adapter detection (claude-code / cursor-agent / antigravity / codex / copilot)
+
+### Output by Adapter
+| Adapter | Output Location | Format |
+|---------|----------------|--------|
+| claude-code | `.claude/agents/qa-orchestrator.md` + `*-scanner.md` | Multi-file, parallel fan-out |
+| cursor-agent | `.cursor/rules/qa-checklist.mdc` | Single MDC rule file |
+| codex | `AGENTS.md` (appended) | `## QA Agent Instructions` section |
+| antigravity | `.agents/skills/qa-orchestrator/SKILL.md` | Multi-file skill |
+| copilot | `.github/agents/qa-orchestrator.agent.md` | Single agent file |
+
+### Flow
+1. **Research phase**: reads codebase, detects stack, samples files, reads `agents/qa-templates/rules/{stack}.md`
+2. **Adapter routing**: `lib/qa-router.cjs` determines output spec
+3. **LLM generates**: Write tool creates agent files directly from research output
+4. **Post-scan**: generated `qa-orchestrator` creates `.viepilot/requests/BUG-{N}.md` entries; `AskUserQuestion` for accept/decline

package/lib/qa-router.cjs

@@ -0,0 +1,72 @@
+'use strict';
+const path = require('path');
+
+/**
+ * Resolve the output spec for QA agent files given an adapter.
+ *
+ * @param {string} adapterId - 'claude-code'|'cursor-agent'|'codex'|'antigravity'|'copilot'
+ * @param {string} projectRoot - Absolute path to the target project root
+ * @returns {object} outputSpec
+ */
+function resolveOutputSpec(adapterId, projectRoot) {
+  switch (adapterId) {
+    case 'claude-code':
+      return {
+        mode: 'multi-file',
+        dir: path.join(projectRoot, '.claude', 'agents'),
+        orchestratorFile: 'qa-orchestrator.md',
+        subagentSuffix: '-scanner.md',
+        description: '.claude/agents/ (Claude Code native agents)',
+      };
+    case 'cursor-agent':
+      return {
+        mode: 'single-file',
+        dir: path.join(projectRoot, '.cursor', 'rules'),
+        file: 'qa-checklist.mdc',
+        frontmatterRequired: true,
+        description: '.cursor/rules/qa-checklist.mdc (Cursor MDC rule)',
+      };
+    case 'codex':
+      return {
+        mode: 'append',
+        dir: projectRoot,
+        file: 'AGENTS.md',
+        sectionHeader: '## QA Agent Instructions',
+        description: 'AGENTS.md (Codex system instructions)',
+      };
+    case 'antigravity':
+      return {
+        mode: 'multi-file',
+        dir: path.join(projectRoot, '.agents', 'skills'),
+        orchestratorFile: 'qa-orchestrator/SKILL.md',
+        description: '.agents/skills/ (Antigravity skills)',
+      };
+    case 'copilot':
+      return {
+        mode: 'single-file',
+        dir: path.join(projectRoot, '.github', 'agents'),
+        file: 'qa-orchestrator.agent.md',
+        description: '.github/agents/ (Copilot custom agent)',
+      };
+    default:
+      // Fallback to claude-code
+      return resolveOutputSpec('claude-code', projectRoot);
+  }
+}
+
+/**
+ * List the expected output file paths for a given adapter + domain list.
+ * Useful for pre-flight checks and test assertions.
+ */
+function expectedPaths(adapterId, projectRoot, domains = []) {
+  const spec = resolveOutputSpec(adapterId, projectRoot);
+  if (spec.mode === 'multi-file') {
+    return [
+      path.join(spec.dir, spec.orchestratorFile),
+      ...domains.map(d => path.join(spec.dir, `qa-${d}${spec.subagentSuffix || '.md'}`)),
+    ];
+  }
+  return [path.join(spec.dir, spec.file)];
+}
+
+module.exports = { resolveOutputSpec, expectedPaths };

package/lib/tracker-compact.cjs

@@ -0,0 +1,124 @@
+const fs = require('fs');
+const path = require('path');
+
+function rewriteCurrentState(content, newBlock) {
+  const match = content.match(/^## Current State\n/m);
+  if (!match) return content;
+  const start = match.index + match[0].length;
+  const after = content.slice(start).search(/^## /m);
+  const before = content.slice(0, match.index);
+  const nextSection = after === -1 ? '' : content.slice(start + after);
+  return before + '## Current State\n' + newBlock + nextSection;
+}
+
+function parseStanzas(lines) {
+  const stanzas = [];
+  let current = [];
+  for (const line of lines) {
+    if (line.match(/\*\*Current Phase\*\*/)) {
+      if (current.length > 0) stanzas.push(current);
+      current = [line];
+    } else if (current.length > 0) {
+      current.push(line);
+    }
+  }
+  if (current.length > 0) stanzas.push(current);
+  return stanzas;
+}
+
+function compact(trackerPath, options = {}) {
+  if (!fs.existsSync(trackerPath)) {
+    throw new Error('TRACKER.md not found: ' + trackerPath);
+  }
+
+  const { keep = 5, dryRun = false } = options;
+  const maxRows = Math.max(keep * 4, 20);
+  const content = fs.readFileSync(trackerPath, 'utf8');
+  const lines = content.split('\n');
+
+  let linesRemoved = 0;
+  let rowsArchived = 0;
+  let archiveBlock = '';
+
+  // Process Current State
+  const csIdx = lines.findIndex(l => l === '## Current State');
+  const nextIdx = lines.findIndex((l, i) => i > csIdx && l.match(/^## /));
+
+  if (csIdx !== -1 && nextIdx !== -1) {
+    const csLines = lines.slice(csIdx + 1, nextIdx);
+    const stanzas = parseStanzas(csLines);
+    if (stanzas.length > 1) {
+      const archived = stanzas.slice(0, -1).map(s => s.join('\n')).join('\n');
+      linesRemoved = archived.split('\n').length;
+      archiveBlock += '## Archived Current State\n' + archived + '\n\n';
+    }
+  }
+
+  // Process Decision Log
+  const dlIdx = lines.findIndex(l => l === '## Decision Log');
+  const dlEnd = nextIdx > dlIdx ? nextIdx : lines.length;
+
+  if (dlIdx !== -1) {
+    const tlines = lines.slice(dlIdx + 1, dlEnd);
+    let hIdx = -1, sIdx = -1;
+    for (let i = 0; i < tlines.length; i++) {
+      if (tlines[i].match(/\|\s*Date\s*\|/)) hIdx = i;
+      if (hIdx !== -1 && tlines[i].match(/^\|\s*[-:]+/)) {
+        sIdx = i;
+        break;
+      }
+    }
+    if (hIdx !== -1 && sIdx !== -1) {
+      const rows = tlines.slice(sIdx + 1).filter(l => l.trim().match(/^\|/));
+      if (rows.length > maxRows) {
+        rowsArchived = rows.length - maxRows;
+        archiveBlock += '## Archived Decision Log Rows\n' + rows.slice(0, -maxRows).join('\n') + '\n';
+      }
+    }
+  }
+
+  if (!dryRun && archiveBlock) {
+    const histPath = path.join(path.dirname(trackerPath), 'TRACKER-HISTORY.md');
+    fs.appendFileSync(histPath, '\n---\n# TRACKER Archive — ' + new Date().toISOString().split('T')[0] + '\n\n' + archiveBlock);
+
+    // Rewrite TRACKER.md
+    let newContent = content;
+    if (csIdx !== -1 && nextIdx !== -1) {
+      const stanzas = parseStanzas(lines.slice(csIdx + 1, nextIdx));
+      if (stanzas.length > 0) {
+        newContent = rewriteCurrentState(newContent, stanzas[stanzas.length - 1].join('\n') + '\n');
+      }
+    }
+
+    if (dlIdx !== -1) {
+      const tlines = lines.slice(dlIdx + 1, dlEnd);
+      let hIdx = -1, sIdx = -1;
+      for (let i = 0; i < tlines.length; i++) {
+        if (tlines[i].match(/\|\s*Date\s*\|/)) hIdx = i;
+        if (hIdx !== -1 && tlines[i].match(/^\|\s*[-:]+/)) {
+          sIdx = i;
+          break;
+        }
+      }
+      if (hIdx !== -1 && sIdx !== -1) {
+        const rows = tlines.slice(sIdx + 1).filter(l => l.trim().match(/^\|/));
+        const kept = rows.slice(-maxRows);
+        const newTable = [tlines[hIdx], tlines[sIdx], ...kept].join('\n');
+        const before = lines.slice(0, dlIdx + 1).join('\n');
+        const after = lines.slice(dlEnd).join('\n');
+        newContent = before + '\n' + newTable + '\n' + after;
+      }
+    }
+
+    fs.writeFileSync(trackerPath, newContent, 'utf8');
+  }
+
+  return {
+    linesRemoved,
+    rowsArchived,
+    historyFile: path.join(path.dirname(trackerPath), 'TRACKER-HISTORY.md'),
+    trackerLines: lines.length - linesRemoved
+  };
+}
+
+module.exports = { compact, rewriteCurrentState };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viepilot",
-  "version": "3.10.0",
+  "version": "3.12.0",
   "description": "**Autonomous Vibe Coding Framework / Bộ khung phát triển tự động có kiểm soát**",
   "main": "index.js",
   "bin": {

package/skills/vp-qa/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: vp-qa
+description: "LLM-driven QA agent team generator — research codebase, generate context-aware QA scanning agents"
+version: 1.0.0
+---
+
+<greeting>
+## Invocation Banner
+
+Output this banner as the **first** thing on every invocation — before questions, work, or any other output:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VIEPILOT ► VP-QA  v1.0.0 (fw 2.19.0)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</greeting>
+
+<version_check>
+## Version Update Check (ENH-072)
+
+After displaying the greeting banner, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" check-update --silent
+```
+
+**If exit code = 1** (update available — new version printed to stdout):
+Display notice banner before any other output:
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ ✨ ViePilot {latest_version} available  (installed: {current})   │
+│    npm i -g viepilot && vp-tools install --target {adapter_id}   │
+└──────────────────────────────────────────────────────────────────┘
+```
+Replace `{latest_version}` with stdout from the command, `{current}` with the installed
+version, `{adapter_id}` with the active adapter (claude-code / cursor / antigravity / codex / copilot).
+
+**If exit code = 0 or command unavailable**: silent, continue.
+
+**Suppression rules:**
+- `--no-update-check` flag on skill invocation → skip this step entirely
+- `config.json` → `update.check: false` → skip this step entirely
+- Show at most once per session (`update_check_done` session guard)
+</version_check>
+
+<persona_context>
+## Persona Context Injection (ENH-073)
+
+At skill start, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona auto-switch
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona context
+```
+Inject the output as `## User Persona` context before any task execution.
+Silent if command unavailable or errors.
+</persona_context>
+
+<adapter id="claude-code">
+## A. Skill Invocation
+- Skill được gọi khi user mention `vp-qa`, `/vp-qa`, "qa", "scan", "kiểm tra chất lượng"
+- Treat all user text after the skill mention as `{{VP_ARGS}}`
+
+## B. User Prompting
+Prompt user conversationally with numbered list options.
+
+## C. Tool Usage
+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)
+
+**Phase 1 research tools:**
+- `Read` — parse .viepilot/PROJECT-META.md, STACKS.md, package.json, requirements.txt, etc.
+- `Bash` — find backend directories, count files
+- `Grep` — search for patterns in source code
+
+**Phase 3 generation tools:**
+- `Write` — create agent files directly (qa-orchestrator.md, qa-{domain}-scanner.md)
+</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 `~/.agents/skills/` (global)
+</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.
+- External skills (`non vp-*`) are out of framework scope unless user explicitly opts in.
+- If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
+</scope_policy>
+
+<implementation_routing_guard>
+## Primary implementation lane (ENH-021)
+
+- **`/vp-qa`** generates context-aware QA scanning agents for the current project.
+- Output location determined by adapter via `lib/qa-router.cjs`.
+- Generated agents invoke `qa-orchestrator` (claude-code) or execute sequential scans (others).
+</implementation_routing_guard>
+
+<objective>
+Generate a team of QA scanning agents tailored to the project's stack, structure, and detected patterns.
+
+**LLM-generates-directly approach:**
+- Phase 1: LLM researches target codebase structure, stack, patterns, existing issues
+- Phase 2: LLM determines output location via adapter routing (lib/qa-router.cjs)
+- Phase 3: LLM writes agent files directly using Write tool (no template system)
+- Phase 4: Show generated files and offer to run qa-orchestrator immediately (claude-code only)
+
+**No templates:** Each agent's content is fully determined by research output. LLM tailors
+scanning instructions to detected backend dirs, framework patterns, and known issues from `.viepilot/requests/`.
+
+**After generation:** Generated agents (`qa-orchestrator` on claude-code or combined scanner on others)
+will create `.viepilot/requests/BUG-{N}.md` for any QA issues found, and prompt user to accept/decline.
+</objective>
+
+<context>
+Optional flags:
+- `/vp-qa` — auto-detect adapter + stack, generate QA team
+- `/vp-qa --run` — generate + immediately invoke qa-orchestrator
+- `/vp-qa --focus sec` — bias research toward security domains
+- `/vp-qa --focus perf` — bias research toward performance domains
+- `/vp-qa --target <id>` — override adapter detection (claude-code / cursor-agent / antigravity / codex / copilot)
+</context>
+
+<process>
+### Phase 1: Research (REQUIRED — do not skip)
+
+Before writing any agent file, understand the project:
+
+1. Read `.viepilot/PROJECT-META.md`, `STACKS.md`, `PROJECT-CONTEXT.md` (silent if missing)
+2. Detect stack from: `package.json` / `pom.xml` / `go.mod` / `requirements.txt` / `Gemfile`
+3. List backend directory structure: find `src/` `app/` `lib/` `services/` `api/` `routes/` (whichever exist)
+4. Read 5-10 representative source files from backend dirs (understand patterns)
+5. Count file sizes, service count, DB layer presence
+6. Read `.viepilot/requests/` to list known existing issues (avoid duplicate reporting)
+7. Read `agents/qa-templates/rules/{stack}.md` from project lib (if exists) for stack-specific patterns
+
+**Build research summary:**
+```
+- projectName: string
+- stack: (node / python / java / go / ruby / etc.)
+- stackVersion: string (from version file)
+- backendDirs: string[] (actual dirs found in project)
+- detectedPatterns: string[] (anti-patterns spotted in sampling)
+- recommendedDomains: string[] (scan areas relevant to this project)
+- recommendedAgentCount: number (2 for small, 4-5 for large/complex)
+- knownIssues: string[] (from .viepilot/requests/, avoid duplicates)
+```
+
+### Phase 2: Determine Output Location
+
+Use `lib/qa-router.cjs` to resolve adapter-specific output paths:
+```
+- claude-code  → .claude/agents/
+- cursor-agent → .cursor/rules/
+- codex        → AGENTS.md (single file, append mode)
+- antigravity  → .agents/skills/
+- copilot      → .github/agents/
+```
+
+Call or reference lib/qa-router.cjs to map the current adapter to output directory.
+
+### Phase 3: Generate Agent Files (LLM writes directly)
+
+Based on research summary, generate agent content and write using Write tool.
+
+**For claude-code (multi-agent):**
+- Write `qa-orchestrator.md` — orchestrator that fan-outs to specialist subagents
+  - Name: "vp-qa orchestrator"
+  - Description: "Coordinate QA scanning across multiple domains for {projectName}"
+  - Model: claude-opus (or latest)
+  - maxTurns: 30
+  - Knows about backend dirs found, stack version, patterns to look for
+  - References each specialist subagent by name
+  - Receives domain reports, groups by severity
+  - Creates `.viepilot/requests/BUG-{N}.md` for accepted issues
+  - Uses AskUserQuestion for critical/high severity group acceptance
+  - Final AskUserQuestion: "N issues logged. Run /vp-evolve to plan fixes?"
+
+- Write `qa-{domain}-scanner.md` for each recommended domain (e.g., qa-security-scanner, qa-performance-scanner)
+  - Name: "vp-qa {domain} scanner"
+  - Description: "Scan {projectName} for {domain} concerns"
+  - Model: claude-haiku-4 (efficient)
+  - maxTurns: 15
+  - Content references ACTUAL backend dirs found, ACTUAL patterns to look for
+  - Produces structured report of issues found in that domain
+  - Returns report to orchestrator
+
+- Each file has correct YAML frontmatter (name, description, model, maxTurns, tools)
+- Content NOT generic — references specific dirs, patterns, concerns found during Phase 1
+
+**For other adapters (single-file mode):**
+- Write one combined file with all domain instructions
+- Sequential scanning procedure using that adapter's shell tools
+- Same vp-request output format (BUG-{N}.md files)
+- Single AskUserQuestion for all issues found at end
+
+### Phase 4: AskUserQuestion (claude-code only)
+
+After writing files, show what was generated:
+```
+Generated {N} agent files in {output_dir}:
+  - qa-orchestrator.md (coordinates scanning across domains)
+  - qa-security-scanner.md (scans for security concerns)
+  - qa-performance-scanner.md (scans for performance concerns)
+  ... (other domain files)
+```
+
+**AskUserQuestion:**
+```
+question: "What would you like to do next?"
+options:
+  - label: "Run QA scan now"
+    description: "Invoke qa-orchestrator immediately to start scanning"
+  - label: "Done for now"
+    description: "Exit — agents are ready in {output_dir}"
+```
+
+**On selection:**
+- "Run QA scan now": invoke qa-orchestrator immediately (or equivalent for non-claude-code adapters)
+- "Done for now": print "QA agents ready in {output_dir}. Run qa-orchestrator to start scanning." and exit
+
+**Text fallback (Cursor/Codex/Copilot/Antigravity):**
+```
+QA agents generated in {output_dir}
+
+Next actions:
+  1. Review generated agent files
+  2. Run qa-orchestrator to start the QA scan
+  3. Adjust scanning domains as needed
+```
+
+### Generated qa-orchestrator Behavior (in target project, when run)
+
+When user runs the generated `qa-orchestrator`:
+1. Fan out to specialist subagents (claude-code) or scan sequentially (others)
+2. Collect issue reports from each domain scanner
+3. Group issues by severity (critical/high/medium/low)
+4. For critical/high: AskUserQuestion per group (accept → create vp-request BUG-{N}, decline → skip)
+5. For medium/low: one batch confirm
+6. Create `.viepilot/requests/BUG-{N}.md` for each accepted issue
+7. Final AskUserQuestion: "N issues logged. Run /vp-evolve to plan fixes?"
+</process>
+
+## Adapter Compatibility
+
+### AskUserQuestion Tool (ENH-059)
+After generation, use `AskUserQuestion` on Claude Code (terminal) for Phase 4 prompt.
+
+| Adapter | Interactive Prompts | Notes |
+|---------|---------------------|-------|
+| Claude Code (terminal) | ✅ `AskUserQuestion` — **REQUIRED** at end of Phase 3 | Preload schema via ToolSearch first |
+| Cursor / Codex / Copilot / Antigravity | ❌ Text fallback | Plain numbered list for next actions |
+
+**Claude Code (terminal) — AUQ preload required (ENH-059):**
+Before the first interactive prompt (Phase 4), call `ToolSearch` with `query: "select:AskUserQuestion"` to load the deferred tool schema. Only after `ToolSearch` succeeds can `AskUserQuestion` be invoked. If `ToolSearch` returns an error, fall back to plain-text numbered list for that session.
+
+<success_criteria>
+- [ ] Phase 1 research completed (read project structure, stack, patterns)
+- [ ] Phase 2 output location determined via lib/qa-router.cjs
+- [ ] Phase 3 agent files written using Write tool (content tailored to research output)
+- [ ] Phase 4 AskUserQuestion shown (claude-code) or text fallback (others)
+- [ ] Generated agents ready to execute qa-orchestrator
+- [ ] Generated qa-orchestrator creates .viepilot/requests/BUG-{N}.md for found issues
+</success_criteria>

package/workflows/autonomous.md

@@ -74,6 +74,13 @@ Parse `{{VP_ARGS}}` for flags:
 Load context:
 ```bash
 cat .viepilot/AI-GUIDE.md
+
+# Size guard — auto-compact if TRACKER.md is bloated (> 400 lines)
+if [ -f ".viepilot/TRACKER.md" ] && [ "$(wc -l < .viepilot/TRACKER.md)" -gt 400 ]; then
+  echo "⚠️ TRACKER.md is large ($(wc -l < .viepilot/TRACKER.md) lines) — auto-compacting..."
+  node bin/vp-tools.cjs tracker compact --keep 5
+fi
+
 cat .viepilot/TRACKER.md
 cat .viepilot/ROADMAP.md
 ```
@@ -907,9 +914,10 @@ After phase quality gate passes, send a desktop + phone alert:
    ```
    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}."
+     prompt: "operation: rewrite-current-state. data: Last completed phase {N} — {phase_name}. version: {version}. IMPORTANT: REPLACE the entire '## Current State' section (find the section, overwrite it) — do NOT append new lines. The section must stay ≤ 20 lines total. Also cap '## Decision Log' table at 20 rows — if > 20 rows exist, archive older rows to .viepilot/TRACKER-HISTORY.md."
    })
    ```
+   > Rescue bloated TRACKER.md: `node bin/vp-tools.cjs tracker compact [--keep N]` (DEBT-002)
 7. Push branch + tags — spawn vp-git-agent:
    ```
    Agent({ subagent_type: "vp-git-agent",