viepilot 2.50.1 → 3.7.3

package/docs/skills-reference.md

@@ -547,3 +547,99 @@ Full guide: `docs/user/features/proposal.md`
 - Fallback: `~/.cursor/viepilot/bin/vp-tools.cjs` for Cursor adapter.
 - Registry file: `~/.viepilot/skill-registry.json` — shared across all projects.
 - Confirmation AUQ prompt before destructive `uninstall` (Claude Code terminal only).
+
+---
+
+## /vp-design
+
+Visual/UI direction skill. Generates UI architecture: component map, color system, typography,
+responsive breakpoints, and Pencil design file integration.
+
+### Triggers
+`vp-design`, `/vp-design`, "thiết kế UI", "UI direction", "design system"
+
+### Flags
+- `--new` : Start fresh UI direction session
+- `--component <name>` : Design a specific component
+- `--mobile` : Mobile-first emphasis
+- `--architect` : Generate Architect HTML view alongside
+
+### Flow
+1. Collect product goals + target audience + brand constraints
+2. Generate UI direction: color palette, typography, spacing scale, component inventory
+3. Output Pencil design stubs (if Pencil MCP available) or Architect HTML fallback
+4. Write `docs/ui-direction.md` and `PROJECT-CONTEXT.md ## UI Direction`
+
+### Output
+- `docs/ui-direction.md` (created/updated)
+- `PROJECT-CONTEXT.md` UI Direction section (locked by `/vp-crystallize` Step 1E)
+- Optional: Pencil `.pen` file stubs via `mcp__pencil__batch_design`
+
+### Adapter-Aware Prompts
+Uses `AskUserQuestion` on Claude Code terminal for design-direction questions.
+
+---
+
+## /vp-intake
+
+Structured intake from Google Sheets, Excel (M365), CSV files, and browser URLs. Reads rows
+from a configured source, creates ViePilot request files, and optionally writes results back.
+
+### Triggers
+`vp-intake`, `/vp-intake`, "đọc intake", "intake từ sheet", "load requests from sheet"
+
+### Flags
+- `--channel <id>` : Force a specific intake channel (sheets/excel/csv/browser)
+- `--dry-run` : Parse and triage without writing request files
+- `--no-writeback` : Skip writing results back to source
+- `--setup` : Launch AUQ-driven channel configuration wizard (ENH-084)
+
+### Flow
+1. Load intake manifest (`~/.viepilot/intake-manifests/<project>.json`) or prompt setup
+2. Read rows from configured channel (Google Sheets via API, Excel via M365 Graph, CSV, or browser-agent for public URLs)
+3. Triage each row: detect type (bug/feature/enhancement/debt), extract title/description
+4. Create `.viepilot/requests/{TYPE}-{N}.md` for each valid row
+5. Write-back status column to source row (if writable channel)
+
+### Output
+- `.viepilot/requests/{TYPE}-{N}.md` per intake row
+- Intake manifest updated with last-read cursor
+- Source row status updated (write-back, if enabled)
+
+### Adapters
+Full support: Claude Code. Partial: Cursor (no AUQ). Text fallback: Codex/Copilot/Antigravity.
+
+---
+
+## /vp-persona
+
+Manages the global developer persona profile stored in `~/.viepilot/config.json`. Persona
+controls output style, stack preferences, and team-size assumptions injected into every skill.
+
+### Triggers
+`vp-persona`, `/vp-persona`, "cấu hình persona", "set persona", "developer profile"
+
+### Flags
+- `--set` : Interactively set persona fields
+- `--show` : Print current active persona
+- `--auto-switch` : Switch persona based on current project stack (used internally by skills)
+- `--context` : Print persona as `## User Persona` block (used by skill banners)
+
+### Persona Fields
+| Field | Values | Default |
+|-------|--------|---------|
+| `role` | backend / frontend / fullstack / devops / data / mobile | backend |
+| `domain` | web-saas / mobile / api / data / infra / other | web-saas |
+| `stacks` | comma-separated list | — |
+| `outputStyle` | lean / verbose | lean |
+| `phaseTemplate` | lean-startup / enterprise / research | lean-startup |
+| `teamSize` | solo / small / medium / large | solo |
+
+### Flow
+1. `vp-tools persona auto-switch` — detects stack from package.json / pyproject.toml / build.gradle
+2. `vp-tools persona context` — outputs `## User Persona` markdown block
+3. Skills inject this block silently before task execution
+
+### Output
+- `~/.viepilot/config.json` updated
+- `## User Persona` injected into each skill session

package/lib/adapter-context.cjs

@@ -0,0 +1,294 @@
+'use strict';
+
+/**
+ * ADAPTER_CONTEXT — per-adapter capability map for ViePilot v3.
+ *
+ * Each adapter entry defines:
+ *   tools{}          — canonical tool name for each abstract operation
+ *   interactive      — "AUQ" | "text" | "text-plan-only" | "none"
+ *   orchestration{}  — parallel dispatch capability
+ *   hooks{}          — hook event support
+ *   mcp{}            — MCP support constraints
+ *   subagent         — "multi-level" | "single-level" | "command-only" | "none"
+ *
+ * Skills read ADAPTER_CONTEXT instead of maintaining inline compat tables.
+ */
+
+const ADAPTER_CONTEXTS = {
+
+  'claude-code': {
+    id: 'claude-code',
+    name: 'Claude Code',
+    tools: {
+      shell:        'Bash',
+      read:         'Read',
+      write:        'Write',
+      edit:         'Edit',
+      multi_edit:   'MultiEdit',
+      search:       'Grep',
+      glob:         'Glob',
+      ls:           'LS',
+      web_search:   'WebSearch',
+      web_fetch:    'WebFetch',
+      notebook_read: 'NotebookRead',
+      notebook_edit: 'NotebookEdit',
+      tool_search:  'ToolSearch',
+      todo_read:    'TodoRead',
+      todo_write:   'TodoWrite',
+      agent:        'Agent',
+      interactive:  'AskUserQuestion',   // deferred — preload via ToolSearch first
+    },
+    interactive:  'AUQ',               // must call ToolSearch before first AUQ
+    subagent:     'multi-level',        // Agent tool supports nested spawning
+    orchestration: {
+      mode:            'agent-tool',    // Agent tool = callable from skill
+      parallel:        true,
+      teams:           true,            // CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
+      background:      true,
+      model_override:  {
+        worker:        'claude-haiku-4-5',
+        orchestrator:  'claude-sonnet-4-6',
+      },
+      max_parallel_tasks: 5,
+    },
+    hooks: {
+      count: 28,
+      supported_events: [
+        'SessionStart', 'SessionEnd', 'Stop', 'StopFailure',
+        'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'PostToolUseFailure',
+        'FileChanged', 'SubagentStart', 'SubagentStop',
+        'TaskCreated', 'TaskCompleted', 'PreCompact', 'PostCompact',
+      ],
+    },
+    mcp: { supported: true, tool_limit: null },
+    skill_path_project: '.claude/skills',
+    skill_path_global:  '~/.claude/skills',
+    agents_dir: '.claude/agents',
+  },
+
+  'cursor-agent': {
+    id: 'cursor-agent',
+    name: 'Cursor (Agent Mode)',
+    tools: {
+      shell:        'run_terminal_cmd',
+      read:         'read_file',
+      write:        'edit_file',
+      edit:         'edit_file',
+      multi_edit:   'edit_file',
+      search:       'grep_search',
+      glob:         'file_search',
+      ls:           'list_dir',
+      web_search:   'web_search',
+      web_fetch:    null,              // not available
+      notebook_read: null,
+      notebook_edit: null,
+      tool_search:  null,
+      todo_read:    null,
+      todo_write:   null,
+      agent:        null,              // /multitask is user command, not callable tool
+      interactive:  null,              // AskQuestion only in Plan Mode
+    },
+    interactive:  'text',              // plain-text numbered list fallback
+    subagent:     'command-only',      // /multitask user cmd, single-level, not callable
+    orchestration: {
+      mode:            'sequential',
+      parallel:        false,
+      teams:           false,
+      background:      false,
+      model_override:  null,
+      max_parallel_tasks: 1,
+    },
+    hooks: {
+      count: 5,
+      supported_events: [
+        'beforeShellExecution', 'beforeMCPExecution',
+        'beforeReadFile', 'afterFileEdit', 'stop',
+      ],
+    },
+    mcp: { supported: true, tool_limit: 40 },
+    skill_path_project: '.cursor/skills',
+    skill_path_global:  '~/.cursor/skills',
+    agents_dir: null,
+  },
+
+  'antigravity': {
+    id: 'antigravity',
+    name: 'Antigravity (Google)',
+    tools: {
+      shell:        'shell',
+      read:         'file_read',
+      write:        'file_write',
+      edit:         'file_write',
+      multi_edit:   'file_write',
+      search:       null,              // via shell or MCP
+      glob:         null,              // via shell
+      ls:           null,              // via shell
+      web_search:   null,              // via MCP plugin
+      web_fetch:    null,              // via MCP plugin
+      notebook_read: null,
+      notebook_edit: null,
+      tool_search:  null,
+      todo_read:    null,
+      todo_write:   null,
+      agent:        null,              // async TUI dispatch only
+      interactive:  null,             // TUI-based, no formal AUQ
+    },
+    interactive:  'none',
+    subagent:     'none',
+    orchestration: {
+      mode:            'sequential',
+      parallel:        false,
+      teams:           false,
+      background:      false,
+      model_override:  null,
+      max_parallel_tasks: 1,
+    },
+    hooks: {
+      count: 3,
+      supported_events: ['before_tool', 'after_file_edit', 'session_start'],
+    },
+    mcp: { supported: true, tool_limit: null },
+    skill_path_project: '.agents/skills',
+    skill_path_global:  '~/.gemini/antigravity/skills',
+    agents_dir: null,
+    deprecation_notice: 'Gemini CLI was deprecated June 18, 2026. Use Antigravity CLI instead.',
+  },
+
+  'codex': {
+    id: 'codex',
+    name: 'OpenAI Codex CLI',
+    tools: {
+      shell:        'container.exec',  // sandboxed shell
+      read:         null,              // patch-based — no explicit read tool
+      write:        'apply_patch',
+      edit:         'apply_patch',
+      multi_edit:   'apply_patch',
+      search:       null,              // via shell
+      glob:         null,              // via shell
+      ls:           null,              // via shell
+      web_search:   'web_search',      // native or MCP
+      web_fetch:    null,
+      notebook_read: null,
+      notebook_edit: null,
+      tool_search:  null,
+      todo_read:    null,
+      todo_write:   null,
+      agent:        'subagent',        // subagents supported
+      interactive:  null,             // TUI Tab/Enter injection only
+    },
+    interactive:  'none',
+    subagent:     'single-level',
+    orchestration: {
+      mode:            'sequential',
+      parallel:        false,
+      teams:           false,
+      background:      false,
+      model_override:  null,
+      max_parallel_tasks: 1,
+    },
+    hooks: {
+      count: 0,
+      supported_events: [],
+    },
+    mcp: { supported: true, tool_limit: null },
+    skill_path_project: null,
+    skill_path_global:  '~/.codex',
+    agents_dir: null,
+  },
+
+  'copilot': {
+    id: 'copilot',
+    name: 'GitHub Copilot',
+    tools: {
+      shell:        'runCommands',
+      read:         'read',
+      write:        'editFiles',
+      edit:         'edit',
+      multi_edit:   'editFiles',
+      search:       'code_search',
+      glob:         null,
+      ls:           null,
+      web_search:   null,
+      web_fetch:    null,
+      notebook_read: null,
+      notebook_edit: null,
+      tool_search:  null,
+      todo_read:    null,
+      todo_write:   null,
+      agent:        null,             // explore/task are built-in agents, not callable
+      // askQuestions available in main agent ONLY — not in subagents (VS Code #293745)
+      interactive:  'askQuestions',
+    },
+    interactive:  'text',             // askQuestions not available in subagents
+    subagent:     'none',
+    orchestration: {
+      mode:            'sequential',
+      parallel:        false,
+      teams:           false,
+      background:      false,
+      model_override:  null,
+      max_parallel_tasks: 1,
+    },
+    hooks: {
+      count: 0,
+      supported_events: [],
+    },
+    mcp: { supported: true, tool_limit: null },
+    skill_path_project: '.github/agents',
+    skill_path_global:  null,
+    agents_dir: '.github/agents',
+  },
+};
+
+// Aliases
+ADAPTER_CONTEXTS['cursor'] = ADAPTER_CONTEXTS['cursor-agent'];
+ADAPTER_CONTEXTS['cursor-ide'] = ADAPTER_CONTEXTS['cursor-agent'];
+
+/**
+ * Get ADAPTER_CONTEXT for a given adapter ID. Throws if unknown.
+ */
+function getAdapterContext(id) {
+  const ctx = ADAPTER_CONTEXTS[id];
+  if (!ctx) {
+    throw new Error(`Unknown adapter: "${id}". Known: ${Object.keys(ADAPTER_CONTEXTS).filter(k => !['cursor','cursor-ide'].includes(k)).join(', ')}`);
+  }
+  return ctx;
+}
+
+/**
+ * List all canonical adapter IDs (no aliases).
+ */
+function listAdapterIds() {
+  return ['claude-code', 'cursor-agent', 'antigravity', 'codex', 'copilot'];
+}
+
+/**
+ * Detect the active adapter from environment heuristics.
+ * Returns the adapter ID string.
+ */
+function detectAdapter() {
+  const env = process.env;
+
+  // Env-var signals (strongest signals first)
+  if (env.CURSOR_TRACE || env.CURSOR_CHANNEL || env.CURSOR_ENABLED) return 'cursor-agent';
+  if (env.ANTIGRAVITY_SESSION || env.GEMINI_ANTIGRAVITY_SESSION) return 'antigravity';
+  if (env.CODEX_SESSION || env.OPENAI_CODEX_SESSION) return 'codex';
+  if (env.GITHUB_COPILOT_AGENT || env.COPILOT_AGENT) return 'copilot';
+
+  // TERM_PROGRAM / process name signals
+  const termProgram = (env.TERM_PROGRAM || '').toLowerCase();
+  if (termProgram === 'claude' || termProgram === 'claude-code') return 'claude-code';
+
+  // ~/.claude directory exists → likely Claude Code
+  const os = require('os');
+  const fs = require('fs');
+  const path = require('path');
+  const home = os.homedir();
+  if (fs.existsSync(path.join(home, '.claude', 'settings.json'))) return 'claude-code';
+  if (fs.existsSync(path.join(home, '.claude'))) return 'claude-code';
+
+  // Fallback: claude-code (most common in ViePilot context)
+  return 'claude-code';
+}
+
+module.exports = { ADAPTER_CONTEXTS, getAdapterContext, listAdapterIds, detectAdapter };

package/lib/adapters/antigravity.cjs

@@ -6,16 +6,21 @@ const fs = require('fs');
 module.exports = {
   id: 'antigravity',
   name: 'Antigravity',
+  // Global install path (unchanged)
   skillsDir:   (home) => path.join(home, '.gemini', 'antigravity', 'skills'),
   viepilotDir: (home) => path.join(home, '.gemini', 'antigravity', 'viepilot'),
+  // Phase 131 (FEAT-021): project-level install path (Antigravity v1 uses .agents/skills/)
+  projectSkillsDir: '.agents/skills',
   // {envToolDir} in SKILL.md files resolves to this value at install time (ENH-035)
   executionContextBase: '.gemini/antigravity/viepilot',
   // Post-install hint shown in "Next actions" after viepilot install
   postInstallHint: 'Open project and run /vp-status',
+  // Phase 131 (FEAT-021): Gemini CLI was deprecated June 18, 2026
+  deprecationNotice: '⚠️  Gemini CLI was deprecated June 18, 2026. This installs for Antigravity CLI (the successor). Skill path: .agents/skills/ (project) or ~/.gemini/antigravity/skills/ (global).',
   hooks: {
     configFile: null,       // Antigravity has no programmatic hooks system
     schema: 'antigravity',
-    supportedEvents: []
+    supportedEvents: ['before_tool', 'after_file_edit', 'session_start']
   },
   installSubdirs: [
     'workflows',
@@ -30,6 +35,7 @@ module.exports = {
   isAvailable: (home) => {
     const h = home || os.homedir();
     return fs.existsSync(path.join(h, '.gemini', 'antigravity'))
-      || fs.existsSync(path.join(h, '.antigravity'));
+      || fs.existsSync(path.join(h, '.antigravity'))
+      || fs.existsSync(path.join(process.cwd(), '.agents'));
   }
 };

package/lib/adapters/claude-code.cjs

@@ -35,6 +35,10 @@ module.exports = {
     'ui-components',
     'agents'
   ],
+  // Phase 130 (FEAT-021): native Claude Code subagent definitions (.claude/agents/)
+  // Installed to ~/.claude/agents/ (Claude Code's native agent directory)
+  claudeAgentsDir: (home) => path.join(home, '.claude', 'agents'),
+  claudeAgentsSrc: 'agents/claude-code',
   // Detection: is this platform available on the current machine?
   isAvailable: (home) => {
     const h = home || os.homedir();

package/lib/audit/browser-runner.cjs

@@ -0,0 +1,102 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+const DEFAULT_BASE_URL = 'http://localhost:3000';
+
+/**
+ * Resolve base URL for browser audit.
+ * Priority: options.baseUrl → config.json audit.baseUrl → DEFAULT_BASE_URL
+ * @param {object} options - { baseUrl?: string }
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+function resolveBaseUrl(options, projectRoot) {
+  if (options && options.baseUrl) return options.baseUrl;
+  try {
+    const configPath = path.join(projectRoot, '.viepilot', 'config.json');
+    if (fs.existsSync(configPath)) {
+      const cfg = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      if (cfg.audit && cfg.audit.baseUrl) return cfg.audit.baseUrl;
+    }
+  } catch { /* config missing or malformed — use default */ }
+  return DEFAULT_BASE_URL;
+}
+
+/**
+ * Write a Markdown audit report to .viepilot/audit/visual-report-{timestamp}.md
+ * @param {object} report - structured audit report from browser-audit-agent
+ * @param {string} projectRoot
+ * @returns {string} absolute path to report file
+ */
+function writeAuditReport(report, projectRoot) {
+  const auditDir = path.join(projectRoot, '.viepilot', 'audit');
+  fs.mkdirSync(auditDir, { recursive: true });
+
+  const timestamp = Date.now();
+  const reportPath = path.join(auditDir, `visual-report-${timestamp}.md`);
+
+  const routes = report.routes || [];
+  const routeTable = routes.map(r => {
+    const status = r.status === 'ok' ? '✅ ok' : `❌ ${r.status}`;
+    const issues = (r.errors && r.errors.length > 0) ? r.errors.join(', ') : '—';
+    return `| ${r.url} | ${status} | ${issues} |`;
+  }).join('\n');
+
+  const accessibilitySection = routes
+    .filter(r => r.accessibility_issues && r.accessibility_issues.length > 0)
+    .map(r => `### ${r.url}\n${r.accessibility_issues.map(i => `- **${i.type}**: ${i.description}`).join('\n')}`)
+    .join('\n\n') || '_No accessibility issues found._';
+
+  const screenshotSection = routes
+    .filter(r => r.screenshot)
+    .map(r => `- \`${r.url}\`: \`${r.screenshot}\``)
+    .join('\n') || '_No screenshots captured._';
+
+  const content = `# Browser Audit Report — ${new Date(timestamp).toISOString()}
+
+**Base URL**: ${report.baseUrl || DEFAULT_BASE_URL}
+**Routes checked**: ${routes.length}
+**Op**: ${report.op || 'audit_routes'}
+
+## Routes
+
+| Route | Status | Issues |
+|-------|--------|--------|
+${routeTable}
+
+## Accessibility Issues
+
+${accessibilitySection}
+
+## Screenshots
+
+${screenshotSection}
+`;
+
+  fs.writeFileSync(reportPath, content, 'utf8');
+  return reportPath;
+}
+
+/**
+ * Run browser audit by dispatching browser-audit-agent (CC adapter only).
+ * On non-CC: throws with install instructions.
+ * @param {object} options - { baseUrl?, routes?, op?, updateBaseline? }
+ * @param {string} projectRoot
+ * @returns {Promise<object>} - report object
+ */
+async function runBrowserAudit(options, projectRoot) {
+  const baseUrl = resolveBaseUrl(options, projectRoot);
+  const op = (options && options.op) || 'audit_routes';
+
+  // CC adapter: Agent dispatch is handled by vp-audit SKILL.md (orchestrator layer).
+  // This module is for direct Node callers — emit clear error.
+  throw new Error(
+    `Browser audit requires Claude Code with the agent-browser skill.\n` +
+    `Install: npx skills add vercel-labs/agent-browser\n` +
+    `Then run: /vp-audit --visual --browser ${baseUrl}`
+  );
+}
+
+module.exports = { runBrowserAudit, resolveBaseUrl, writeAuditReport, DEFAULT_BASE_URL };

package/lib/intake/adapters/browser.cjs

@@ -0,0 +1,58 @@
+'use strict';
+
+const URL_PATTERNS = {
+  'google-sheets':   /docs\.google\.com\/spreadsheets/,
+  'github-issues':   /github\.com\/[^/]+\/[^/]+\/issues/,
+  'jira':            /atlassian\.net\/browse\/[A-Z]+-\d+|atlassian\.net\/jira\/software\/projects/,
+  'trello':          /trello\.com\/[bc]\//,
+  'notion':          /notion\.so\/[a-f0-9]{8,}/,
+  'sharepoint-xlsx': /sharepoint\.com\/:[a-z]:\/[a-z]\//,
+};
+
+/**
+ * Detect source type from URL string.
+ * @param {string} url
+ * @returns {'google-sheets'|'github-issues'|'jira'|'trello'|'notion'|'sharepoint-xlsx'|'generic-table'}
+ */
+function detectUrlType(url) {
+  if (!url || typeof url !== 'string') return 'generic-table';
+  for (const [type, pattern] of Object.entries(URL_PATTERNS)) {
+    if (pattern.test(url)) return type;
+  }
+  return 'generic-table';
+}
+
+/**
+ * Read ticket rows from a public URL via browser-intake-agent (CC adapter only).
+ * Non-CC adapters receive a clear unsupported error.
+ * @param {object} channel - channel config with `url` field
+ * @param {string} projectRoot - absolute path to project root
+ * @returns {Promise<Array<{title,description,labels,priority,status}>>}
+ */
+async function readBrowserUrl(channel, projectRoot) {
+  if (!channel || !channel.url) {
+    throw new Error('browser channel requires a "url" field in channel config');
+  }
+
+  const sourceType = detectUrlType(channel.url);
+
+  // CC adapter: Agent dispatch is handled by vp-intake SKILL.md (orchestrator layer).
+  // This module is used by non-CC adapters or direct Node callers — emit clear error.
+  throw new Error(
+    `Browser channel (${sourceType}) requires Claude Code with the agent-browser skill.\n` +
+    `Install: npx skills add vercel-labs/agent-browser\n` +
+    `Then run vp-intake from Claude Code.`
+  );
+}
+
+/**
+ * Check whether a URL appears to be a publicly accessible intake source.
+ * Does not make network requests — pattern-match only.
+ * @param {string} url
+ * @returns {boolean}
+ */
+function isKnownPublicSource(url) {
+  return detectUrlType(url) !== 'generic-table';
+}
+
+module.exports = { readBrowserUrl, detectUrlType, isKnownPublicSource, URL_PATTERNS };