vp-crystallize

name	vp-crystallize
description	Convert brainstorm sessions into executable artifacts
version	0.8.0

## Invocation Banner

Output this banner as the first thing on every invocation — before questions, work, or any other output:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 VIEPILOT ► VP-CRYSTALLIZE  v0.8.0 (fw 2.19.0)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## Version Update Check (ENH-072)

After displaying the greeting banner, run:

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:

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>

## A. Skill Invocation - Skill được gọi khi user mention `vp-crystallize`, `/vp-crystallize`, hoặc "crystallize", "setup project" - Treat all user text after the skill mention as `{{VP_ARGS}}`

Flags:

• --no-stakeholders : Skip the Step 1G Stakeholder Review Gate (ENH-098)

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)

## 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

## A. Skill Invocation Same trigger keywords as claude-code adapter. Skill discovery: LLM-driven (automatic, no slash command needed).

C. Tool Usage

Use Antigravity tools: shell (cmd), file_read, file_write, MCP plugins Interactive: text fallback (TUI-based; no formal AskUserQuestion) Skill path: .agents/skills/<skill>/SKILL.md (project) or ~/.gemini/antigravity/skills/ (global) Note: Gemini CLI deprecated June 18, 2026 — use Antigravity CLI.

## 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

## 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 <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>

Implementation routing guard (ENH-021)

• Creates artifacts in .viepilot/ (and template copy) from brainstorm — does not replace /vp-auto for implementing application code / framework shipping. Backlog feature code: /vp-evolve + /vp-auto. See workflows/request.md. </implementation_routing_guard>

Convert brainstorm sessions into structured artifacts for autonomous AI execution.

Creates:

.viepilot/
├── AI-GUIDE.md          # AI navigation guide
├── PROJECT-META.md      # Project metadata
├── ARCHITECTURE.md      # System design
├── architecture/        # ENH-022: *.mermaid sidecars (mirror fenced diagrams)
├── PROJECT-CONTEXT.md   # Domain knowledge + `<product_vision>` (phased scope)
├── SYSTEM-RULES.md      # Coding rules & standards
├── ROADMAP.md           # Phases & tasks in order from phases_inventory
├── TRACKER.md           # Progress tracking
├── HANDOFF.json         # Machine-readable state
└── schemas/             # Database, API, Kafka schemas

Also creates:

• CHANGELOG.md
• CONTRIBUTING.md
• CONTRIBUTORS.md
• LICENSE
• Updated README.md

ViePilot profile (FEAT-009):

• Reads .viepilot/META.md → file ~/.viepilot/profiles/<slug>.md (contract: docs/dev/global-profiles.md); pre-fills Step 0; merges into ARCHITECTURE (## ViePilot organization context), PROJECT-CONTEXT (## ViePilot active profile), AI-GUIDE quick context.

Stack intelligence (global cache):

• ~/.viepilot/stacks/{stack}/SUMMARY.md
• ~/.viepilot/stacks/{stack}/BEST-PRACTICES.md
• ~/.viepilot/stacks/{stack}/ANTI-PATTERNS.md
• ~/.viepilot/stacks/{stack}/SOURCES.md
• .viepilot/STACKS.md (project-local index to global cache)

After: Ready for /vp-auto

UI direction hard gate (ENH-026):

• Step 1A scans brainstorm for UI signal keywords; if ≥3 signals detected + no artifacts → STOP with 2-option dialogue (go back to brainstorm --ui OR proceed with assumptions written to ARCHITECTURE.md). Enforces direction-first workflow before crystallize proceeds.

Architect artifacts consumption (FEAT-011):

• Step 1D reads .viepilot/architect/{session}/notes.md YAML — imports decisions[] → ARCHITECTURE.md, uses tech_stack{} as authoritative stack (conflict → ask user), surfaces open_questions[] with status: open. Soft suggestion (not hard block) when architect dir missing but ≥5 services detected.

Admin & Governance Export (ENH-063):

• Step 1D item 7: if admin.html or notes.md ## admin exists in architect workspace → append ## Admin & Governance table to .viepilot/PROJECT-CONTEXT.md (columns: Capability | Required | Phase | Notes) + Admin Personas table. Records admin_imported and admin_capabilities_count in working notes.

Content Management Export (ENH-065):

• Step 1D item 8: if content.html or notes.md ## content exists in architect workspace → append ## Content Management table to .viepilot/PROJECT-CONTEXT.md (columns: Content Type | Created By | Lifecycle | Key Fields | Phase) + Media/Storage and Localization sub-tables. Records content_imported and content_types_count in working notes.

Admin Entity Management Export (ENH-068):

• Step 1D item 10: if entity-mgmt.html or notes.md ## entity_mgmt exists in architect workspace → append ## Admin Entity Management table to .viepilot/PROJECT-CONTEXT.md (columns: Entity | CRUD Ops | Soft Delete | Bulk Actions | Audit Trail | Scope) + Import/Export sub-table. Records entity_mgmt_imported and entity_mgmt_entity_count in working notes.

User Data Management Export (ENH-066):

• Step 1D item 9: if user-data.html or notes.md ## user_data exists in architect workspace → append ## User Data Management table to .viepilot/PROJECT-CONTEXT.md (columns: Capability | Supported | Notes) with 8 capability rows (profile editing, notification prefs, privacy settings, data export, right to erasure, connected accounts, session management, 2FA). Records user_data_imported and user_data_capabilities_count in working notes.

Crystallize version stamps (ENH-067):

• Generated PROJECT-CONTEXT.md includes <!-- crystallize_version: {semver} --> as its first line.
• HANDOFF.json records crystallize_version and crystallized_at fields.
• Used by --upgrade re-scan mode to compute delta on future runs.

Upgrade re-scan mode (--upgrade) (ENH-067):

• Detects crystallize_version delta; lists missing PROJECT-CONTEXT.md sections.
• Patch mode: appends only missing sections non-destructively; re-stamps crystallize_version.
• Full re-generate: backs up .viepilot/ → regenerates all artifacts using existing sessions.
• Integrates brainstorm ## Upgrade supplement sections when present.

Mandatory Workspace Read Gates (ENH-064):

• Architect workspace (Step 1D): if .viepilot/architect/ exists → reads ALL 12 pages front-to-back before any extraction. architect_read_complete: true required. Missing notes.md → STOP.
• UI Direction workspace (Step 1A strengthened): if .viepilot/ui-direction/ exists → reads ALL pages/*.html + ALL notes.md sections. ui_direction_read_complete: true required. Pages inventory mismatch → STOP.
• Cross-reference gate (Step 1F): when both workspaces present → validates coverage matrix; warns on Phase 1 features with no architect OR UI coverage.
• No silent skip: any workspace that exists MUST be fully read. Partial reads are not allowed.

Language configuration (ENH-032):

• Step 0-A reads ~/.viepilot/config.json → DOCUMENT_LANG (default: en) and COMMUNICATION_LANG (default: en).
• DOCUMENT_LANG controls content language for all generated files (ROADMAP, TRACKER, ARCHITECTURE, etc.).
• COMMUNICATION_LANG controls prompt/confirmation language for this session.
• Configure via: vp-tools config set language.document vi

Brownfield Mode (--brownfield) — FEAT-018:

Use when adopting ViePilot on an existing project (no brainstorm session required).

Flags:

• --brownfield : Explicit brownfield mode
• (auto-detected) : Triggers when docs/brainstorm/ is absent/empty AND .viepilot/ does not exist

Scanner runs 12 signal categories across the existing codebase:

1. Build manifests — package.json, pom.xml, pyproject.toml, Cargo.toml, go.mod, etc. (11 platforms) → infers project_name, version, language, deps
2. Framework detection — 40+ dependency patterns → backend/frontend/ORM/auth/broker/test frameworks
3. Architecture layers — 18 directory patterns → controller/service/repository/frontend/infra/etc.
4. Database schema signals — Flyway/Liquibase/Prisma/Rails migrations + docker-compose services
5. API contracts — OpenAPI, gRPC .proto, GraphQL schemas
6. Infrastructure — Dockerfile, docker-compose, k8s, Terraform, Vercel, Fly.io, etc. (16 patterns)
7. Environment config — .env.example key names (never reads .env)
8. Test coverage — Jest/pytest/JUnit/Cypress config + coverage report dirs
9. Code quality tools — ESLint/Prettier/SonarQube/pre-commit/golangci-lint/etc. (14 patterns)
10. Documentation — README, CHANGELOG, ADRs, docs/ (priority-ordered)
11. Git history — commit convention, version pattern, contributors, repo URL
12. Language survey — file extension glob → language distribution

Multi-repo / monorepo support (ENH-047):

• Git submodule detection — reads .gitmodules; scans each initialized submodule path (Signal Cat 1+2+4); records uninitialized paths as primary_language: MISSING. Never runs git submodule update — read-only.
• Polyrepo hints — detects docker-compose ../ build contexts, file:../ deps, CI cross-repo clones, README external links, Makefile cd ../ targets; outputs polyrepo_hints[]; prompts user to supply related_repos[] (optional).
• Per-module gap detection — every modules[] entry carries gap_tier (DETECTED/ASSUMED/MISSING), must_detect_status{} (evidence per field: value + source + tier), and open_questions[]. A module with gap_tier: MISSING blocks artifact generation with a targeted per-field prompt.

Scan Report contains:

• Root gap_tier (= worst tier across all modules: MISSING > ASSUMED > DETECTED)
• modules[] — one entry per workspace/submodule/root with gap_tier, must_detect_status{}, open_questions[]
• polyrepo_hints[] — polyrepo signals (omitted when empty, no empty arrays)
• related_repos[] — user-supplied sibling repos (omitted when empty)
• Root open_questions[] — includes rollup from all modules

Produces Scan Report (YAML) with DETECTED / ASSUMED / MISSING classification. MUST-DETECT gaps (root: project_name, primary_language, ≥1 framework, current_version; per-module: primary_language, framework, module_purpose, entry_point) block artifact generation until user fills interactively. Generates docs/brainstorm/session-brownfield-import.md stub for vp-audit compatibility. Safety: never reads .env; skips node_modules/, .git/, target/, build/, dist/.

<execution_context> @$HOME/{envToolDir}/workflows/crystallize.md @$HOME/{envToolDir}/templates/project/ </execution_context>

Execute workflow from `@$HOME/{envToolDir}/workflows/crystallize.md`

Key steps:

Step 0: Collect Project Metadata

• FEAT-009: Load .viepilot/META.md + global profile file first (workflows/crystallize.md); set profile_resolved or none; pre-fill org/website when profile is present. Ask user for (confirm proposals from profile if present):
• Project name, description
• Organization name, website
• Package Base ID (e.g., com.company.project)
• Maven Group ID, Artifact ID
• Lead developer info (name, email, GitHub)
• Repository URL
• License choice
• Inception year

Step 1: Analyze Brainstorm

• Load all brainstorm sessions
• Extract: decisions, architecture, schemas, features
• Extract selected tech stacks
• Phase assignment (ENH-030): parse ## Phases from brainstorm sessions; build phases_inventory; run phase assignment gate (all features must have a phase — full contract: workflows/crystallize.md Step 1)
• Validate completeness (tech stack, features, schema/API clarity, phase assignment gate)

Step 1A: Consume UI direction (if present)

• Read .viepilot/ui-direction/{session-id}/notes.md first, then style.css, then HTML:
  • Multi-page: if pages/*.html exists → require ## Pages inventory in notes.md, validate it lists every page file, read each pages/*.html plus hub index.html for navigation.
  • Legacy: no pages/ → read index.html + style.css as before.
• Carry approved layout/component decisions into architecture + roadmap artifacts; architecture must reference all pages from inventory when multi-page.
• Mark assumptions explicitly if direction artifacts are missing or inventory/files mismatch.

Step 1B: Official stack research (mandatory)

• For every selected stack, research official docs and authoritative sources
• Build concise "Do / Don't / Pitfalls" guidance
• If guidance is uncertain, ask user before locking decisions
• Tool policy:
  • Use WebSearch to discover candidate sources
  • Use WebFetch to read source content before extracting guidance
  • Prioritize official docs, specs, and maintainers' references over blog posts
  • Save source URLs and access date in SOURCES.md

Step 1C: Write stack cache

• Persist guidance to ~/.viepilot/stacks/{stack}/...
• Create .viepilot/STACKS.md for lookup mapping

Step 2: Generate AI-GUIDE.md

• Quick lookup table
• Context loading strategy
• File relationships
• FEAT-009: Quick context for profile_id + profile path when resolved

Step 3: Generate PROJECT-META.md

• Project info
• Organization info
• Package structure
• Developer info
• File headers template
• FEAT-009: Align Organization with confirmed profile content (public only)

Step 4: Generate ARCHITECTURE.md

• System overview
• FEAT-009: Section ## ViePilot organization context when profile is present (or none line)
• Services definitions
• Data flow
• Technology decisions
• Build diagram applicability matrix for:
  • system-overview, data-flow, event-flows, module-dependencies, deployment, user-use-case
• For each type assign status: required | optional | N/A
• Apply generation policy:
  • required => include concrete Mermaid block
  • optional => allow lightweight/merged representation
  • N/A => keep section heading + one-line rationale
• ENH-022: For each diagram type with real Mermaid, write .viepilot/architecture/<type>.mermaid (raw source) and keep it identical to the body inside the fenced ```mermaid block in ARCHITECTURE.md; omit files for N/A or no diagram — see workflows/crystallize.md Step 4.

Step 5: Generate PROJECT-CONTEXT.md

• FEAT-009: Block ## ViePilot active profile (FEAT-009) when binding is present
• Domain knowledge
• Business rules
• Conventions
• Constraints
• Fill <product_vision> from template (templates/project/PROJECT-CONTEXT.md): Project scope, Phase overview, anti-goals — aligned with brainstorm ## Phases + Step 1 phases_inventory

Step 6: Generate SYSTEM-RULES.md

• Architecture rules
• Coding rules
• Comment standards (good/bad examples)
• Versioning (SemVer)
• Git conventions (Conventional Commits)
• Changelog standards (Keep a Changelog)
• Quality gates
• Stack-specific rules from cache

Step 7: Generate ROADMAP.md

• Use templates/project/ROADMAP.md — phases in order (Phase 1, Phase 2...) from phases_inventory; no Post-MVP block
• Each phase: tasks, acceptance criteria, verification commands
• Self-check before finalize: all phases from phases_inventory appear in ROADMAP; if mismatch → stop and ask user — see workflows/crystallize.md Step 7

Step 8: Generate schemas/

• database-schema.sql
• kafka-topics.yaml
• api-contracts.yaml

Step 9: Initialize TRACKER.md

• Current state
• Progress overview
• Decision log
• Version info

Step 10: Generate Project Files

• CHANGELOG.md
• CONTRIBUTING.md
• CONTRIBUTORS.md
• LICENSE
• README.md (updated)

Step 11: Commit & Confirm

• Git commit all artifacts
• Display summary
• Suggest: /vp-auto

<success_criteria>

• UI direction artifacts consumed for UI/UX scopes (or assumptions documented)
• Official stack research completed before architecture lock
• Global cache created for all selected stacks
• Project-local stack index (.viepilot/STACKS.md) created
• All artifacts created in .viepilot/
• PROJECT-META.md has complete metadata
• SYSTEM-RULES.md has all standards
• Step 1 phase assignment gate satisfied (phases_inventory recorded, all features assigned)
• PROJECT-CONTEXT.md includes populated <product_vision> (template placeholders filled from brainstorm)
• ROADMAP.md has phases with tasks in order from phases_inventory
• TRACKER.md initialized
• Project files created
• Git committed
• ARCHITECTURE diagram matrix is present and consistent (required|optional|N/A)
• ENH-022: Every generated Mermaid diagram has a .viepilot/architecture/<canonical-name>.mermaid file in sync with ARCHITECTURE.md (no extra files created for N/A)
• FEAT-009: When profile is bound — ARCHITECTURE + PROJECT-CONTEXT record the profile source; if not — state none / not configured explicitly </success_criteria>

Adapter Compatibility

AskUserQuestion Tool (ENH-048)

This skill uses adapter-aware interactive prompts. Behavior depends on your adapter:

Adapter	Interactive Prompts	Notes
Claude Code (terminal)	✅ AskUserQuestion tool — REQUIRED	Must call AUQ; plain-text only if tool errors or is unavailable
Claude Code (VS Code ext)	⚠️ Partial	Terminal yes; VS Code UI pending anthropics/claude-code#12609
Cursor (Plan Mode)	⚠️ Partial	AskQuestion in Plan Mode only — not in Agent/Skills Mode
Cursor (Agent/Skills)	❌ Text fallback	AskQuestion not available in Agent Mode
Codex CLI	❌ Text fallback	Native tool N/A; community MCP available
Antigravity (native agent)	❌ Text fallback	Artifact model, no raw tool calls
GitHub Copilot	✅ /skill-name in Chat	Via .agent.md custom agent; AUQ not available — text fallback

Claude Code (terminal) — AUQ preload required (ENH-059): Before the first interactive prompt, 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.

When AskUserQuestion is not available on other adapters, the skill automatically falls back to plain-text numbered list prompts — no configuration required.

Prompts using AskUserQuestion in this skill:

• License selection (Step 0 metadata)
• Brownfield overwrite confirmation (Step 0-B)
• Polyrepo related-repos prompt (Step 0-B)
• UI direction gate choice (Step 1A)
• Architect mode suggestion (Step 1D)

Step 1E — Skill Decision Gate (FEAT-020)

After scope lock, before SPEC generation, crystallize checks for ## skills_used in the brainstorm session's notes.md:

• No skills_used found → step silently skipped
• Skills found → AUQ presents each skill (required / optional / exclude)
• Decision written to PROJECT-CONTEXT.md ## Skills

The ## Skills decision is final — /vp-auto reads it at execution time and injects skill best practices per task without re-prompting.

Install skills: vp-tools install-skill <source> Registry: vp-tools scan-skills Docs: docs/user/features/skill-registry.md

Step 1F — Cross-Reference Gate

Validates coverage matrix when both Architect and UI Direction workspaces are present. Warns on Phase 1 features with no architect OR UI coverage (non-blocking).

Step 1G — Stakeholder Review Gate (ENH-098)

After scope lock, spawns .claude/agents/ stakeholder agents in parallel fan-out, collects gap analysis (Gaps/Risks/Suggestions), synthesizes feedback to enrich PROJECT-CONTEXT.md before ROADMAP generation. Can be skipped with --no-stakeholders flag.