viepilot 2.4.0 → 2.15.0

package/docs/user/features/interactive-prompts.md

@@ -0,0 +1,83 @@
+# Interactive Prompts (AskUserQuestion)
+
+> **ENH-048** — Introduced in v2.15.0
+
+ViePilot skills that ask user questions now use **adapter-aware interactive prompts**.
+In Claude Code (terminal), questions appear as structured click-to-select UI.
+All other adapters fall back to plain-text numbered lists automatically.
+
+---
+
+## How It Works
+
+When a vp-* skill needs input (e.g. "What type of request?"), it checks whether
+the `AskUserQuestion` tool is available in the current adapter:
+
+| Adapter | Experience |
+|---------|------------|
+| **Claude Code (terminal)** | Click-to-select options with descriptions, optional multi-select, preview panels |
+| **Claude Code (VS Code ext)** | Terminal mode — same as above (VS Code interactive UI pending [#12609](https://github.com/anthropics/claude-code/issues/12609)) |
+| **Cursor — Plan Mode** | `AskQuestion` available in Plan Mode only |
+| **Cursor — Agent/Skills** | Text fallback (AskQuestion not in Agent Mode) |
+| **Codex CLI** | Text fallback (native tool N/A) |
+| **Antigravity native** | Text fallback (Artifact model, no raw tool calls) |
+
+No configuration needed. The fallback is automatic.
+
+---
+
+## Affected Skills and Prompts
+
+### /vp-crystallize
+| Prompt | AUQ Options |
+|--------|-------------|
+| License selection | MIT / Apache-2.0 / GPL-3.0 / Proprietary |
+| Brownfield overwrite confirm | Yes, continue / No, abort |
+| Polyrepo related-repos | Yes, I'll list them / Skip for now |
+| UI direction gate | Return to brainstorm / Continue with assumptions |
+| Architect mode suggestion | Yes, architect mode / No, continue now |
+
+### /vp-brainstorm
+| Prompt | AUQ Options |
+|--------|-------------|
+| Session intent | Continue recent / Review specific / New session |
+| Landing page layout | Layout A (Hero) / Layout B (Problem-Solution) / Layout C (Storytelling) / Layout D (SaaS) |
+
+### /vp-request
+| Prompt | AUQ Options |
+|--------|-------------|
+| Request type | Bug / Feature / Enhancement / Tech Debt |
+| Bug severity | Critical / High / Medium / Low |
+| Feature priority | Must-have / Should-have / Nice-to-have |
+
+### /vp-evolve
+| Prompt | AUQ Options |
+|--------|-------------|
+| Evolve intent | Add Feature / New Milestone / Refactor |
+| Complexity | S (Small) / M (Medium) / L (Large) / XL (Extra Large) |
+| Brainstorm routing | Yes, brainstorm first / No, plan directly |
+
+---
+
+## AskUserQuestion Tool Constraints
+
+When using Claude Code, the tool has these constraints:
+- **1–4 questions** per call
+- **2–4 options** per question
+- Optional `multiSelect: true` for non-exclusive choices
+- Optional `preview` field for visual comparisons (code/layout mockups)
+- Automatic "Other" option always appended by the UI
+
+---
+
+## Research Notes (Adapter Support)
+
+Research conducted 2026-04-13 confirmed:
+
+- **Cursor Agent/Skills Mode** does not expose `AskQuestion` — it only works in Plan Mode
+  ([community request](https://forum.cursor.com/t/allow-askquestion-tool-calls-in-agent-mode-or-any-mode/152517))
+- **Codex CLI** `ask_user_question` is a community MCP skill, not a native tool
+  ([openai/codex#9926](https://github.com/openai/codex/issues/9926))
+- **Antigravity** uses an "Artifacts" model for agent output — no raw tool execution for interactive UI
+
+All non-Claude-Code adapters receive identical plain-text prompts as before ENH-048.

package/docs/user/features/proposal.md

@@ -0,0 +1,196 @@
+# vp-proposal — Proposal Package Generator
+
+Generate professional proposal packages directly from your ViePilot brainstorm sessions.
+
+---
+
+## Overview
+
+`/vp-proposal` converts a brainstorm session (or a direct brief) into three synchronized files:
+
+| File | Format | Purpose |
+|------|--------|---------|
+| `{slug}-{date}.md` | Markdown | Source of truth, version-controlled |
+| `{slug}-{date}.pptx` | PowerPoint | Presentation (direct delivery) |
+| `{slug}-{date}.docx` | Word | Detailed supporting document |
+| `{slug}-{date}-slides.txt` | Text | Google Slides URL (with `--slides` flag) |
+
+All files are written to `docs/proposals/` in your project.
+
+---
+
+## Quick Start
+
+```bash
+# Auto-detects latest brainstorm session
+/vp-proposal
+
+# Specify type directly
+/vp-proposal --type product-pitch
+
+# With Google Slides upload
+/vp-proposal --type project-proposal --slides
+
+# Preview slide manifest without writing files
+/vp-proposal --dry-run
+```
+
+---
+
+## Proposal Types
+
+| Type ID | Name | Slides | Best for |
+|---------|------|--------|----------|
+| `project-proposal` | Project Proposal | 10 | Client delivery — scope, timeline, budget |
+| `tech-architecture` | Technical Architecture | 12 | Technical partners — system design |
+| `product-pitch` | Product Pitch Deck | 12 | Investors / partners — pitch |
+| `general` | General Proposal | 8 | Any audience — flexible structure |
+
+---
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--type <id>` | Proposal type (see table above). If omitted: guided menu. |
+| `--from <file>` | Explicit brainstorm session: `--from docs/brainstorm/session-2026-04-11.md` |
+| `--slides` | Upload generated .pptx to Google Slides after generation |
+| `--dry-run` | Show slide manifest (JSON) without writing any files |
+
+---
+
+## Context Detection
+
+`/vp-proposal` automatically loads the most recent brainstorm session:
+
+1. Scans `docs/brainstorm/session-*.md`
+2. Sorts descending by filename (ISO date format)
+3. Loads the latest session as proposal content
+
+**Override:** use `--from <session-file>` to specify a different session.
+
+**Standalone mode:** if no session exists, you'll be prompted for a brief:
+- Project name
+- One-line description
+- Target audience
+- 3–5 key points
+
+---
+
+## Template Override
+
+ViePilot ships stock templates (dark navy/charcoal, ViePilot branded).
+To use your own branded templates for a specific project:
+
+```
+your-project/
+└── .viepilot/
+    └── proposal-templates/
+        ├── project-proposal.pptx    ← overrides stock
+        ├── tech-architecture.pptx
+        ├── product-pitch.pptx
+        ├── general.pptx
+        └── project-detail.docx
+```
+
+**Resolution order:**
+1. `.viepilot/proposal-templates/{type}.pptx` (project-level override)
+2. `{viepilot-install}/templates/proposal/pptx/{type}.pptx` (ViePilot stock)
+
+The override only applies to the project where the file is placed.
+
+---
+
+## Output Structure
+
+```
+docs/proposals/
+├── my-project-2026-04-11.md      # Markdown source of truth
+├── my-project-2026-04-11.pptx    # Presentation
+├── my-project-2026-04-11.docx    # Detailed document
+└── my-project-2026-04-11-slides.txt  # Google Slides URL (if --slides)
+```
+
+The `.md` file is the diff-friendly source. The `.pptx` and `.docx` are generated from it and can be regenerated at any time.
+
+---
+
+## Google Slides Export
+
+Use the `--slides` flag to automatically upload the generated `.pptx` to Google Slides.
+
+### Setup (one-time)
+
+**Step 1: Create a Google Cloud project**
+1. Go to [console.cloud.google.com](https://console.cloud.google.com)
+2. Create a new project (or select an existing one)
+
+**Step 2: Enable APIs**
+1. Navigate to **APIs & Services → Library**
+2. Enable **Google Drive API**
+3. Enable **Google Slides API**
+
+**Step 3: Create a Service Account**
+1. Go to **APIs & Services → Credentials**
+2. Click **Create Credentials → Service Account**
+3. Fill in name (e.g., `viepilot-proposal`)
+4. Click **Done**
+5. Click the new service account → **Keys** tab → **Add Key → Create new key (JSON)**
+6. Save the downloaded JSON file securely (e.g., `~/.config/viepilot-gcp-key.json`)
+
+**Step 4: Set environment variable**
+```bash
+export GOOGLE_APPLICATION_CREDENTIALS=/path/to/your-service-account-key.json
+
+# Add to ~/.zshrc or ~/.bashrc to persist:
+echo 'export GOOGLE_APPLICATION_CREDENTIALS=~/.config/viepilot-gcp-key.json' >> ~/.zshrc
+```
+
+**Step 5: Install the optional dependency**
+```bash
+npm install @googleapis/slides
+```
+
+### Usage
+```bash
+/vp-proposal --type product-pitch --slides
+# Output: docs/proposals/my-project-2026-04-11-slides.txt
+# Content: https://docs.google.com/presentation/d/{id}/edit
+```
+
+### Notes
+- The uploaded presentation retains the `.pptx` layout (converted by Google Drive)
+- Upload failures are non-fatal — the `.pptx`, `.docx`, and `.md` files are always written first
+- The service account needs no special permissions beyond the API scopes
+
+---
+
+## Examples
+
+### Client proposal from brainstorm session
+```
+/vp-proposal --type project-proposal
+→ Auto-loads docs/brainstorm/session-2026-04-11.md
+→ Generates 10-slide project proposal
+```
+
+### Investor pitch standalone
+```
+/vp-proposal --type product-pitch
+→ No session found — prompts for brief
+→ Generates 12-slide pitch deck
+```
+
+### Architecture review with Google Slides
+```
+/vp-proposal --type tech-architecture --slides
+→ Generates 12-slide architecture proposal + uploads to Google Slides
+→ Writes URL to docs/proposals/*-slides.txt
+```
+
+### Preview without writing files
+```
+/vp-proposal --dry-run
+→ Prints JSON slide manifest to console
+→ No files written
+```

package/lib/google-slides-exporter.cjs

@@ -0,0 +1,80 @@
+'use strict';
+/**
+ * google-slides-exporter.cjs
+ * Uploads a .pptx file to Google Drive and converts it to a Google Slides presentation.
+ *
+ * Requirements (optional — only needed when --slides flag is used):
+ *   npm install @googleapis/slides
+ *   export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
+ *
+ * See docs/user/features/proposal.md → "Google Slides Export" for setup guide.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+/**
+ * Upload a local .pptx file to Google Drive and convert to Google Slides.
+ *
+ * @param {string} pptxPath  Absolute path to the .pptx file
+ * @param {string} title     Title for the Google Slides presentation
+ * @returns {Promise<string>} Public edit URL of the created presentation
+ */
+async function uploadToSlides(pptxPath, title) {
+  // Lazy-load @googleapis/slides — it is an optionalDependency.
+  // Provide a clear, actionable error when the package is not installed.
+  let googleApis;
+  try {
+    googleApis = require('googleapis');
+  } catch {
+    throw new Error(
+      'Google Slides export requires the @googleapis/slides package.\n\n' +
+      'Install it:\n' +
+      '  npm install @googleapis/slides\n\n' +
+      'Then set your service account credentials:\n' +
+      '  export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json\n\n' +
+      'See: docs/user/features/proposal.md → "Google Slides Export"'
+    );
+  }
+
+  const { google } = googleApis;
+
+  // Verify credentials env var is set before attempting auth
+  if (!process.env.GOOGLE_APPLICATION_CREDENTIALS) {
+    throw new Error(
+      'GOOGLE_APPLICATION_CREDENTIALS environment variable is not set.\n\n' +
+      'Set it to the path of your Google service account JSON key:\n' +
+      '  export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json\n\n' +
+      'See: docs/user/features/proposal.md → "Google Slides Export"'
+    );
+  }
+
+  // Authenticate via service account (no browser interaction required)
+  const auth = new google.auth.GoogleAuth({
+    scopes: [
+      'https://www.googleapis.com/auth/drive',
+      'https://www.googleapis.com/auth/presentations',
+    ],
+  });
+
+  const authClient = await auth.getClient();
+  const drive = google.drive({ version: 'v3', auth: authClient });
+
+  // Upload .pptx and request conversion to Google Slides format
+  const { data: file } = await drive.files.create({
+    requestBody: {
+      name: title,
+      mimeType: 'application/vnd.google-apps.presentation',
+    },
+    media: {
+      mimeType:
+        'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+      body: fs.createReadStream(pptxPath),
+    },
+    fields: 'id',
+  });
+
+  return `https://docs.google.com/presentation/d/${file.id}/edit`;
+}
+
+module.exports = { uploadToSlides };

package/lib/proposal-generator.cjs

@@ -0,0 +1,249 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Proposal type definitions
+// ─────────────────────────────────────────────────────────────────────────────
+const PROPOSAL_TYPES = {
+  'project-proposal':  { slides: 10, label: 'Project Proposal' },
+  'tech-architecture': { slides: 12, label: 'Technical Architecture' },
+  'product-pitch':     { slides: 12, label: 'Product Pitch Deck' },
+  'general':           { slides: 8,  label: 'General Proposal' },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Template resolution — 2-tier
+//   Tier 1: {projectRoot}/.viepilot/proposal-templates/{type}.{ext}  (project override)
+//   Tier 2: {packageRoot}/templates/proposal/{ext}/{type}.{ext}       (stock)
+// ─────────────────────────────────────────────────────────────────────────────
+function resolveTemplate(type, ext, projectRoot) {
+  const override = path.join(projectRoot, '.viepilot', 'proposal-templates', `${type}.${ext}`);
+  if (fs.existsSync(override)) return override;
+  // Stock fallback — lives next to this file at ../templates/proposal/{ext}/
+  return path.join(__dirname, '..', 'templates', 'proposal', ext, `${type}.${ext}`);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Context detection — auto-load latest brainstorm session
+// ─────────────────────────────────────────────────────────────────────────────
+function detectBrainstormSession(projectRoot) {
+  const dir = path.join(projectRoot, 'docs', 'brainstorm');
+  if (!fs.existsSync(dir)) return null;
+  const files = fs.readdirSync(dir)
+    .filter(f => f.startsWith('session-') && f.endsWith('.md'))
+    .sort()
+    .reverse();
+  return files.length ? path.join(dir, files[0]) : null;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Proposal type validation
+// ─────────────────────────────────────────────────────────────────────────────
+function validateType(type) {
+  if (!PROPOSAL_TYPES[type]) {
+    throw new Error(
+      `Unknown proposal type "${type}". Valid types: ${Object.keys(PROPOSAL_TYPES).join(', ')}`
+    );
+  }
+  return PROPOSAL_TYPES[type];
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Manifest meta schema (ENH-040)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Manifest meta object — collected via Step 2C quality brief.
+ *
+ * @typedef {Object} ProposalMeta
+ * @property {string} cta           - Decision/action the proposal should drive
+ * @property {string} [budget]      - Approximate budget range (optional)
+ * @property {string} [timeline]    - Key deadline or constraint (optional)
+ * @property {string} decisionMaker - Who is the primary audience/decision-maker
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Output path builder
+// ─────────────────────────────────────────────────────────────────────────────
+function buildOutputPaths(slug, projectRoot) {
+  const date = new Date().toISOString().slice(0, 10);
+  const base = path.join(projectRoot, 'docs', 'proposals', `${slug}-${date}`);
+  return {
+    md:     `${base}.md`,
+    pptx:   `${base}.pptx`,
+    docx:   `${base}.docx`,
+    slides: `${base}-slides.txt`,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Language instruction builder (ENH-039)
+// ─────────────────────────────────────────────────────────────────────────────
+
+const LANG_NAMES = {
+  vi: 'Vietnamese', ja: 'Japanese', fr: 'French', zh: 'Chinese',
+  ko: 'Korean', de: 'German', es: 'Spanish', pt: 'Portuguese',
+  it: 'Italian', th: 'Thai', ar: 'Arabic', hi: 'Hindi',
+};
+
+/**
+ * Build a language instruction string to prepend to the AI content generation prompt.
+ *
+ * @param {string} lang - ISO 639-1 code (e.g. 'vi', 'en', 'ja')
+ * @param {boolean} [contentOnly=false] - if true, translate content only; keep structural labels English
+ * @returns {string} Instruction to inject into AI prompt (empty string for English)
+ */
+function buildLangInstruction(lang, contentOnly = false) {
+  if (!lang || lang === 'en') {
+    return '';  // English is default — no explicit instruction needed
+  }
+  const langName = LANG_NAMES[lang] || lang.toUpperCase();
+
+  if (contentOnly) {
+    return (
+      `LANGUAGE INSTRUCTION: Generate all slide content (bullet points, body text, ` +
+      `speaker notes, and paragraph content) in ${langName}. ` +
+      `Keep structural labels, section names, and template placeholders in English.`
+    );
+  }
+  return (
+    `LANGUAGE INSTRUCTION: Generate ALL content — slide headings, bullet points, ` +
+    `body text, speaker notes, document section titles, and paragraph content — in ${langName}. ` +
+    `Do not mix languages.`
+  );
+}
+
+/** @type {Record<string, string[]>} */
+const DIAGRAM_TYPES_BY_PROPOSAL = {
+  'project-proposal':  ['flowchart', 'gantt'],
+  'tech-architecture': ['flowchart', 'sequenceDiagram', 'classDiagram'],
+  'product-pitch':     ['flowchart', 'sequenceDiagram'],
+  'general':           ['flowchart'],
+};
+
+/**
+ * Returns the list of Mermaid diagram types to generate for a given proposal type.
+ * @param {string} typeId - Proposal type ID (e.g. 'project-proposal')
+ * @returns {string[]} Array of Mermaid diagram type identifiers
+ */
+function getDiagramTypes(typeId) {
+  return DIAGRAM_TYPES_BY_PROPOSAL[typeId] || ['flowchart'];
+}
+
+/** Known architect workspace page filenames (from vp-brainstorm --architect) */
+const ARCHITECT_PAGES = [
+  'architecture.html',
+  'erd.html',
+  'sequence-diagram.html',
+  'feature-map.html',
+  'user-use-cases.html',
+  'deployment.html',
+  'apis.html',
+  'tech-notes.html',
+  'data-flow.html',
+  'decisions.html',
+];
+
+/**
+ * Detect available HTML visual artifacts for screenshot embedding in PPTX slides.
+ * Scans the ui-direction session directory for index.html, pages/*.html, and
+ * architect workspace pages (architecture.html, erd.html, etc.).
+ *
+ * @param {string} [sessionDir] - Absolute path to a .viepilot/ui-direction/{session}/ dir.
+ *   If omitted, auto-detects the latest session by scanning CWD/.viepilot/ui-direction/.
+ * @returns {{ uiPages: string[], architectPages: string[], sessionDir: string|null }}
+ */
+function detectVisualArtifacts(sessionDir) {
+  const fs   = require('fs');
+  const path = require('path');
+
+  // Auto-detect latest session when no dir provided
+  let resolvedDir = sessionDir || null;
+  if (!resolvedDir) {
+    const uiBase = path.join(process.cwd(), '.viepilot', 'ui-direction');
+    if (fs.existsSync(uiBase)) {
+      const entries = fs.readdirSync(uiBase)
+        .filter(e => {
+          try { return fs.statSync(path.join(uiBase, e)).isDirectory(); } catch { return false; }
+        })
+        .sort()
+        .reverse();  // ISO date dirs: latest first
+      if (entries.length > 0) resolvedDir = path.join(uiBase, entries[0]);
+    }
+  }
+
+  const result = { uiPages: [], architectPages: [], sessionDir: resolvedDir };
+  if (!resolvedDir || !fs.existsSync(resolvedDir)) return result;
+
+  // ui-direction index page
+  const indexHtml = path.join(resolvedDir, 'index.html');
+  if (fs.existsSync(indexHtml)) result.uiPages.push(indexHtml);
+
+  // ui-direction sub-pages
+  const pagesDir = path.join(resolvedDir, 'pages');
+  if (fs.existsSync(pagesDir)) {
+    const pageFiles = fs.readdirSync(pagesDir)
+      .filter(f => f.endsWith('.html'))
+      .sort()
+      .map(f => path.join(pagesDir, f));
+    result.uiPages.push(...pageFiles);
+  }
+
+  // Architect workspace pages (in same session dir)
+  for (const page of ARCHITECT_PAGES) {
+    const p = path.join(resolvedDir, page);
+    if (fs.existsSync(p)) result.architectPages.push(p);
+  }
+
+  return result;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Design configs — ENH-045
+// ─────────────────────────────────────────────────────────────────────────────
+const DESIGN_CONFIGS = {
+  'modern-tech': {
+    colorPalette: 'navy-electric',
+    layoutStyle:  'modern-tech',
+    fontPair:     'Calibri / Calibri Light',
+  },
+  'enterprise': {
+    colorPalette: 'navy-gold',
+    layoutStyle:  'enterprise',
+    fontPair:     'Georgia / Calibri',
+  },
+  'creative': {
+    colorPalette: 'dark-vibrant',
+    layoutStyle:  'creative',
+    fontPair:     'Calibri / Calibri',
+  },
+};
+
+/**
+ * Choose design config based on project context signals (ENH-045).
+ * @param {Object} ctx - { sector?, audience?, tone?, proposalType? }
+ * @returns {{ colorPalette: string, layoutStyle: string, fontPair: string }}
+ */
+function getDesignConfig(ctx = {}) {
+  const { sector = '', audience = '', tone = '' } = ctx;
+  const lower = `${sector} ${audience} ${tone}`.toLowerCase();
+  if (/bank|financ|enterprise|corp|legal|compliance|government/.test(lower))
+    return DESIGN_CONFIGS['enterprise'];
+  if (/startup|creative|design|game|media|agency|art/.test(lower))
+    return DESIGN_CONFIGS['creative'];
+  return DESIGN_CONFIGS['modern-tech'];
+}
+
+module.exports = {
+  PROPOSAL_TYPES,
+  resolveTemplate,
+  detectBrainstormSession,
+  validateType,
+  buildOutputPaths,
+  buildLangInstruction,
+  getDiagramTypes,
+  detectVisualArtifacts,
+  DESIGN_CONFIGS,
+  getDesignConfig,
+};