viepilot 3.9.1 → 3.11.0

package/CHANGELOG.md

@@ -9,6 +9,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [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
+- ENH-101: `vp-crystallize` now generates adapter-specific AI context files at Step 1F
+- ENH-101: New `vp-tools context-files` subcommand generates CLAUDE.md (Claude Code),
+  GEMINI.md (Antigravity), AGENTS.md (Codex), .cursorrules + .cursor/rules/ (Cursor),
+  .github/copilot-instructions.md (Copilot) from `.viepilot/` sources
+- ENH-101: `--all` flag generates all 5 adapter files simultaneously
+- ENH-101: Content sourced from AI-GUIDE.md, PROJECT-CONTEXT.md, SYSTEM-RULES.md, STACKS.md
+
+---
+
 ## [3.9.1] - 2026-05-25
 
 ### Fixed

package/bin/vp-tools.cjs

@@ -1210,6 +1210,44 @@ ${colors.cyan}Examples:${colors.reset}
       });
   },
 
+  /**
+   * ENH-101: Generate adapter context files (CLAUDE.md, GEMINI.md, AGENTS.md, .cursorrules, .github/copilot-instructions.md)
+   * Usage: vp-tools context-files [--all]
+   */
+  'context-files': (args) => {
+    const { generateAll, generateClaudeMd, generateGeminiMd, generateAgentsMd,
+            generateCursorRules, generateCursorMdc, generateCopilotInstructions }
+      = require('../lib/context-file-generators.cjs');
+    const allFlag = args.includes('--all');
+    const projectRoot = process.cwd();
+
+    // detect adapter
+    const adapterCtx = require('../lib/adapter-context.cjs');
+    const adapterId = adapterCtx.detectAdapter ? adapterCtx.detectAdapter() : 'claude-code';
+
+    const targets = allFlag ? generateAll(projectRoot) : (() => {
+      const map = {
+        'claude-code':  [{ path: 'CLAUDE.md', content: generateClaudeMd(projectRoot) }],
+        'antigravity':  [{ path: 'GEMINI.md',  content: generateGeminiMd(projectRoot) }],
+        'codex':        [{ path: 'AGENTS.md',  content: generateAgentsMd(projectRoot) }],
+        'cursor-agent': [
+          { path: '.cursorrules', content: generateCursorRules(projectRoot) },
+          { path: '.cursor/rules/viepilot-context.mdc', content: generateCursorMdc(projectRoot) },
+        ],
+        'copilot': [{ path: '.github/copilot-instructions.md', content: generateCopilotInstructions(projectRoot) }],
+      };
+      return map[adapterId] || map['claude-code'];
+    })();
+
+    for (const { path: relPath, content } of targets) {
+      const absPath = require('path').join(projectRoot, relPath);
+      require('fs').mkdirSync(require('path').dirname(absPath), { recursive: true });
+      require('fs').writeFileSync(absPath, content, 'utf8');
+      console.log(formatSuccess(`Written: ${relPath}`));
+    }
+    process.exit(0);
+  },
+
   /**
    * ENH-073: Manage cross-project personas.
    * persona get            → print active persona JSON
@@ -1627,6 +1665,7 @@ ${colors.cyan}Commands:${colors.reset}
   ${colors.bold}get-registry${colors.reset} [--id <id>] Output global skill registry as JSON
   ${colors.bold}scan-skills${colors.reset}               Scan installed skills → ~/.viepilot/skill-registry.json
   ${colors.bold}check-update${colors.reset} [--silent]   Check for latest ViePilot version on npm (24h cached)
+  ${colors.bold}context-files${colors.reset} [--all]     Generate adapter context files (CLAUDE.md, GEMINI.md, etc.)
   ${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

package/lib/context-file-generators.cjs

@@ -0,0 +1,147 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Read a .viepilot/ source file, return '' if missing.
+ */
+function readSource(projectRoot, relPath) {
+  try {
+    return fs.readFileSync(path.join(projectRoot, relPath), 'utf8');
+  } catch { return ''; }
+}
+
+/**
+ * Build the shared core block used by all adapters.
+ * Sources: AI-GUIDE.md, PROJECT-CONTEXT.md, SYSTEM-RULES.md, STACKS.md
+ */
+function buildCoreBlock(projectRoot) {
+  const meta    = readSource(projectRoot, '.viepilot/PROJECT-META.md');
+  const guide   = readSource(projectRoot, '.viepilot/AI-GUIDE.md');
+  const context = readSource(projectRoot, '.viepilot/PROJECT-CONTEXT.md');
+  const rules   = readSource(projectRoot, '.viepilot/SYSTEM-RULES.md');
+  const stacks  = readSource(projectRoot, '.viepilot/STACKS.md');
+
+  // Extract project name from PROJECT-META.md header or package.json
+  let projectName = 'Project';
+  const nameMatch = meta.match(/^#\s+(.+)/m);
+  if (nameMatch) projectName = nameMatch[1].trim();
+  else {
+    try {
+      projectName = require(path.join(projectRoot, 'package.json')).name || 'Project';
+    } catch { /* noop */ }
+  }
+
+  return { projectName, guide, context, rules, stacks };
+}
+
+/**
+ * CLAUDE.md — Claude Code context file (full Markdown, no frontmatter)
+ */
+function generateClaudeMd(projectRoot) {
+  const { projectName, guide, context, rules, stacks } = buildCoreBlock(projectRoot);
+  const sections = [];
+  sections.push(`# ${projectName} — Claude Code Context\n`);
+  if (guide)   sections.push(`## Navigation\n\n${guide}`);
+  if (context) sections.push(`## Domain Context\n\n${context}`);
+  if (rules)   sections.push(`## Coding Standards\n\n${rules}`);
+  if (stacks)  sections.push(`## Stack\n\n${stacks}`);
+  sections.push(`\n## ViePilot Workflow\n\n` +
+    `- Run \`/vp-auto\` to execute planned phases\n` +
+    `- Run \`/vp-request\` to log bugs or features\n` +
+    `- Current state: \`.viepilot/TRACKER.md\`\n`);
+  return sections.join('\n\n---\n\n');
+}
+
+/**
+ * GEMINI.md — Antigravity / Gemini CLI context file
+ */
+function generateGeminiMd(projectRoot) {
+  // Same structure as CLAUDE.md; different header note
+  const content = generateClaudeMd(projectRoot);
+  return content.replace('Claude Code Context', 'Gemini / Antigravity Context');
+}
+
+/**
+ * AGENTS.md — Codex CLI context file
+ * Codex is patch-based + sequential; emphasize apply_patch conventions
+ */
+function generateAgentsMd(projectRoot) {
+  const { projectName, context, rules, stacks } = buildCoreBlock(projectRoot);
+  const sections = [];
+  sections.push(`# ${projectName} — Codex Agent Instructions\n`);
+  sections.push(`## Conventions\n\n` +
+    `- Use \`apply_patch\` for all file edits\n` +
+    `- No interactive prompts — work sequentially\n` +
+    `- Commit after each logical unit\n`);
+  if (context) sections.push(`## Domain Context\n\n${context}`);
+  if (rules)   sections.push(`## Coding Standards\n\n${rules}`);
+  if (stacks)  sections.push(`## Stack\n\n${stacks}`);
+  sections.push(`\n## ViePilot\n\nPhase state: \`.viepilot/TRACKER.md\`\n`);
+  return sections.join('\n\n---\n\n');
+}
+
+/**
+ * .cursorrules — Cursor legacy flat-file format
+ */
+function generateCursorRules(projectRoot) {
+  const { projectName, context, rules, stacks } = buildCoreBlock(projectRoot);
+  const parts = [`# ${projectName} — Cursor Rules\n`];
+  if (rules)   parts.push(rules);
+  if (context) parts.push(`## Domain\n\n${context}`);
+  if (stacks)  parts.push(`## Stack\n\n${stacks}`);
+  return parts.join('\n\n');
+}
+
+/**
+ * .cursor/rules/viepilot-context.mdc — Cursor new MDC format
+ */
+function generateCursorMdc(projectRoot) {
+  const body = generateCursorRules(projectRoot)
+    .replace(/^# .+\n/, ''); // strip header — MDC description field covers it
+  const { projectName } = buildCoreBlock(projectRoot);
+  return `---
+description: ${projectName} coding standards and architecture context
+globs: ["**/*"]
+alwaysApply: true
+---
+
+${body}`;
+}
+
+/**
+ * .github/copilot-instructions.md — GitHub Copilot
+ * Copilot has shorter context; be concise, focus on coding standards
+ */
+function generateCopilotInstructions(projectRoot) {
+  const { projectName, rules, stacks } = buildCoreBlock(projectRoot);
+  const parts = [`# Copilot Instructions — ${projectName}\n`];
+  if (rules)  parts.push(rules);
+  if (stacks) parts.push(`## Stack\n\n${stacks}`);
+  return parts.join('\n\n');
+}
+
+/**
+ * Generate all 5 adapter context files.
+ * Returns { path: string, content: string }[] — caller writes them.
+ */
+function generateAll(projectRoot) {
+  return [
+    { path: 'CLAUDE.md',                             content: generateClaudeMd(projectRoot) },
+    { path: 'GEMINI.md',                             content: generateGeminiMd(projectRoot) },
+    { path: 'AGENTS.md',                             content: generateAgentsMd(projectRoot) },
+    { path: '.cursorrules',                          content: generateCursorRules(projectRoot) },
+    { path: '.cursor/rules/viepilot-context.mdc',   content: generateCursorMdc(projectRoot) },
+    { path: '.github/copilot-instructions.md',       content: generateCopilotInstructions(projectRoot) },
+  ];
+}
+
+module.exports = {
+  generateClaudeMd,
+  generateGeminiMd,
+  generateAgentsMd,
+  generateCursorRules,
+  generateCursorMdc,
+  generateCopilotInstructions,
+  generateAll,
+};

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viepilot",
-  "version": "3.9.1",
+  "version": "3.11.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/crystallize.md

@@ -2172,8 +2172,40 @@ Append to `.viepilot/PROJECT-CONTEXT.md`:
 **Lock semantics**: once written, `## Skills` is the authoritative skill decision for the project. `vp-auto` reads it and **never re-prompts**.
 </step>
 
+<step name="adapter_context_files">
+## Step 1F: Generate Adapter Context Files (ENH-101)
+
+Generate the native AI context file for the active adapter so it starts with full project context.
+
+**Detect adapter and generate:**
+```bash
+node bin/vp-tools.cjs context-files
+# or with --all to generate all 5 adapters at once:
+node bin/vp-tools.cjs context-files --all
+```
+
+**What gets generated:**
+| Adapter | File |
+|---------|------|
+| Claude Code | `CLAUDE.md` (project root) |
+| Cursor | `.cursorrules` + `.cursor/rules/viepilot-context.mdc` |
+| Codex | `AGENTS.md` (project root) |
+| Antigravity | `GEMINI.md` (project root) |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+
+**Content sources** (from `.viepilot/` — skip if not yet generated):
+- `AI-GUIDE.md` → navigation + architecture summary
+- `PROJECT-CONTEXT.md` → domain knowledge, business rules
+- `SYSTEM-RULES.md` → coding standards, patterns
+- `STACKS.md` → tech stack, versions
+
+**Note**: Re-running overwrites existing files with latest `.viepilot/` content.
+Step 1F is non-blocking — if `.viepilot/` sources are incomplete, outputs a partial file
+with a `<!-- viepilot: incomplete -->` comment at the top as a re-run reminder.
+</step>
+
 <step name="cross_reference_gate">
-## Step 1F: Cross-Reference Gate (ENH-064)
+## Step 1G: Cross-Reference Gate (ENH-064)
 
 Run when BOTH `architect_read_complete: true` AND `ui_direction_read_complete: true` are set in working notes:
 
@@ -2208,9 +2240,9 @@ Run when BOTH `architect_read_complete: true` AND `ui_direction_read_complete: t
 <step name="stakeholder_review_gate">
 ---
 
-## Step 1G: Stakeholder Review Gate (ENH-098)
+## Step 1H: Stakeholder Review Gate (ENH-098)
 
-**Trigger**: Runs automatically after Step 1F, before Step 2.
+**Trigger**: Runs automatically after Step 1G, before Step 2.
 
 **Skip conditions**:
 - `--no-stakeholders` flag passed to `/vp-crystallize`