Agent安装

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