viepilot 1.0.0

package/skills/vp-crystallize/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: vp-crystallize
+description: "Chuyển đổi brainstorm thành executable artifacts"
+version: 0.3.0
+---
+
+<cursor_skill_adapter>
+## 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}}`
+
+## B. User Prompting
+Prompt user conversationally với numbered list options.
+
+## C. Tool Usage
+Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
+</cursor_skill_adapter>
+
+<objective>
+Chuyển đổi brainstorm sessions thành structured artifacts để AI có thể autonomous execution.
+
+**Creates:**
+```
+.viepilot/
+├── AI-GUIDE.md          # Navigation cho AI
+├── PROJECT-META.md      # Metadata dự án
+├── ARCHITECTURE.md      # System design
+├── PROJECT-CONTEXT.md   # Domain knowledge
+├── SYSTEM-RULES.md      # Coding rules & standards
+├── ROADMAP.md           # Phases & tasks
+├── 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`
+
+**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`
+</objective>
+
+<execution_context>
+@$HOME/.cursor/viepilot/workflows/crystallize.md
+@$HOME/.cursor/viepilot/templates/project/
+</execution_context>
+
+<process>
+Execute workflow from `@$HOME/.cursor/viepilot/workflows/crystallize.md`
+
+Key steps:
+
+### Step 0: Collect Project Metadata
+Ask user for:
+- 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
+- Validate completeness
+
+### Step 1A: Consume UI direction (if present)
+- Read `.viepilot/ui-direction/{session-id}/notes.md`, `index.html`, `style.css`
+- Carry approved layout/component decisions into architecture + roadmap artifacts
+- Mark assumptions explicitly if direction artifacts are missing
+
+### 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
+
+### Step 3: Generate PROJECT-META.md
+- Project info
+- Organization info
+- Package structure
+- Developer info
+- File headers template
+
+### Step 4: Generate ARCHITECTURE.md
+- System overview
+- Services definitions
+- Data flow
+- Technology decisions
+
+### Step 5: Generate PROJECT-CONTEXT.md
+- Domain knowledge
+- Business rules
+- Conventions
+- Constraints
+
+### 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
+- Break into phases
+- Define tasks per phase
+- Set acceptance criteria
+- Add verification checkpoints
+
+### 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`
+</process>
+
+<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
+- [ ] ROADMAP.md has phases with tasks
+- [ ] TRACKER.md initialized
+- [ ] Project files created
+- [ ] Git committed
+</success_criteria>

package/skills/vp-debug/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: vp-debug
+description: "Systematic debugging with persistent state tracking across sessions"
+version: 0.1.0
+---
+
+<cursor_skill_adapter>
+## A. Skill Invocation
+- Skill được gọi khi user mention `vp-debug`, `/vp-debug`, "debug", "gỡ lỗi"
+- Treat all user text after the skill mention as `{{VP_ARGS}}`
+
+## B. User Prompting
+Prompt user conversationally. Guide through systematic debugging steps.
+
+## C. Tool Usage
+Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
+</cursor_skill_adapter>
+
+<objective>
+Systematic debugging với persistent state tracking. Giúp track vấn đề qua nhiều sessions.
+
+**Creates/Updates:**
+- `.viepilot/debug/session-{id}.json` - Debug session state
+- `.viepilot/debug/CURRENT.json` - Active session pointer
+
+**Modes:**
+- `new` - Start new debug session
+- `continue` - Continue current session
+- `list` - List all sessions
+- `close` - Close current session with resolution
+</objective>
+
+<execution_context>
+@$HOME/.cursor/viepilot/workflows/debug.md
+</execution_context>
+
+<context>
+Optional flags:
+- `--new` : Force new session
+- `--continue` : Continue current session
+- `--list` : List all sessions
+- `--close [resolved|unresolved|wontfix]` : Close session
+- `--id <session_id>` : Work with specific session
+</context>
+
+<process>
+Execute workflow from `@$HOME/.cursor/viepilot/workflows/debug.md`
+
+### Debug Session Structure
+```json
+{
+  "id": "debug-{timestamp}",
+  "status": "active|resolved|unresolved|wontfix",
+  "created_at": "ISO timestamp",
+  "updated_at": "ISO timestamp",
+  "problem": {
+    "description": "User's problem description",
+    "symptoms": ["symptom1", "symptom2"],
+    "error_messages": ["error1"],
+    "affected_files": ["file1.js"]
+  },
+  "investigation": {
+    "hypotheses": [
+      {"id": 1, "description": "...", "status": "testing|confirmed|rejected"}
+    ],
+    "tests_run": [
+      {"command": "...", "output": "...", "timestamp": "..."}
+    ],
+    "findings": ["finding1", "finding2"]
+  },
+  "resolution": {
+    "root_cause": "Description of root cause",
+    "fix_applied": "Description of fix",
+    "files_changed": ["file1.js"],
+    "verification": "How it was verified"
+  }
+}
+```
+
+### Key Steps
+1. **Start Session**: Gather problem description
+2. **Hypothesize**: Generate possible causes
+3. **Test**: Run tests to confirm/reject hypotheses
+4. **Track**: Log all findings
+5. **Resolve**: Document fix and root cause
+6. **Close**: Mark session complete
+</process>
+
+<success_criteria>
+- [ ] Session created with problem description
+- [ ] Hypotheses tracked with status
+- [ ] Tests logged with outputs
+- [ ] Findings documented
+- [ ] Resolution recorded (if resolved)
+- [ ] State persists across sessions
+</success_criteria>

package/skills/vp-docs/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: vp-docs
+description: "Generate comprehensive documentation cho dự án"
+version: 0.1.0
+---
+
+<cursor_skill_adapter>
+## A. Skill Invocation
+- Skill được gọi khi user mention `vp-docs`, `/vp-docs`, "docs", "documentation", "tài liệu"
+- Treat all user text after the skill mention as `{{VP_ARGS}}`
+
+## B. User Prompting
+Prompt user conversationally với options.
+
+## C. Tool Usage
+Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
+</cursor_skill_adapter>
+
+<objective>
+Generate comprehensive documentation từ code và artifacts.
+
+**Creates/Updates:**
+```
+docs/
+├── api/
+│   ├── rest-api.md
+│   ├── graphql-schema.md
+│   ├── kafka-events.md
+│   └── websocket-api.md
+├── dev/
+│   ├── getting-started.md
+│   ├── architecture.md
+│   ├── contributing.md
+│   ├── testing.md
+│   └── deployment.md
+├── user/
+│   ├── quick-start.md
+│   └── features/
+└── README.md (index)
+
+docs/skills-reference.md (incremental update — add missing skills by scanning skills/ dir)
+README.md (Documentation table, Project Structure section)
+CHANGELOG.md (updated)
+```
+
+**Context resolved at runtime (never hardcoded):**
+- GitHub owner/repo from `git remote get-url origin`
+- Skills count from `ls skills/*/SKILL.md | wc -l`
+- Workflows count from `ls workflows/*.md | wc -l`
+</objective>
+
+<execution_context>
+@$HOME/.cursor/viepilot/workflows/documentation.md
+</execution_context>
+
+<context>
+Optional flags:
+- `--all` : Generate all documentation
+- `--api` : API documentation only
+- `--dev` : Developer guide only
+- `--user` : User guide only
+- `--changelog` : Update changelog only
+</context>
+
+<process>
+
+### Step 0: Resolve Project Context (ALWAYS first)
+```bash
+# Read actual GitHub URL — never use hardcoded placeholder
+REMOTE_URL=$(git remote get-url origin 2>/dev/null || echo "")
+GITHUB_SLUG=$(echo "$REMOTE_URL" | sed 's|.*github\.com[:/]||; s|\.git$||')
+GITHUB_OWNER=$(echo "$GITHUB_SLUG" | cut -d'/' -f1)
+GITHUB_REPO=$(echo "$GITHUB_SLUG" | cut -d'/' -f2)
+# Fallback: use searchable placeholder, not 'your-org'
+[ -z "$GITHUB_OWNER" ] && GITHUB_OWNER="{GITHUB_OWNER}" && GITHUB_REPO="{GITHUB_REPO}"
+
+ACTUAL_SKILLS=$(ls skills/*/SKILL.md 2>/dev/null | wc -l | tr -d ' ')
+ACTUAL_WORKFLOWS=$(ls workflows/*.md 2>/dev/null | wc -l | tr -d ' ')
+```
+
+> Use `$GITHUB_OWNER/$GITHUB_REPO` in all generated files.
+> Use `$ACTUAL_SKILLS` and `$ACTUAL_WORKFLOWS` for counts.
+> **Never write** `your-org`, `YOUR_USERNAME`, `YOUR_ORG` into generated files.
+
+### Step 1: Ask Documentation Scope
+```
+Which documentation would you like to generate?
+
+1. All - Generate complete documentation
+2. API - REST, GraphQL, Kafka, WebSocket docs
+3. Developer Guide - Setup, architecture, contributing
+4. User Guide - Quick start, feature guides
+5. Changelog - Update from git history
+```
+
+### Step 2A: API Documentation
+```yaml
+sources:
+  - Code annotations (@OpenAPI, @GraphQL)
+  - .viepilot/schemas/api-contracts.yaml
+  - Controller/Resolver classes
+  - Kafka topic definitions
+
+generate:
+  rest-api.md:
+    - Endpoints grouped by resource
+    - Request/Response examples
+    - Authentication requirements
+    - Error codes
+    
+  graphql-schema.md:
+    - Types and queries
+    - Mutations
+    - Subscriptions
+    - Example queries
+    
+  kafka-events.md:
+    - Topic list with descriptions
+    - Message schemas
+    - Producer/Consumer examples
+    
+  websocket-api.md:
+    - Connection flow
+    - Event types
+    - Message formats
+```
+
+### Step 2B: Developer Guide
+```yaml
+sources:
+  - .viepilot/ARCHITECTURE.md
+  - .viepilot/SYSTEM-RULES.md
+  - .viepilot/PROJECT-CONTEXT.md
+  - README.md
+  - Docker/deployment configs
+
+generate:
+  getting-started.md:
+    - Prerequisites
+    - Local setup steps
+    - Running the project
+    - Common issues
+    
+  architecture.md:
+    - System overview (from ARCHITECTURE.md)
+    - Service descriptions
+    - Data flow diagrams
+    
+  contributing.md:
+    - Development workflow
+    - Code standards
+    - PR process
+    - Testing requirements
+    
+  testing.md:
+    - Test structure
+    - Running tests
+    - Writing new tests
+    - Coverage requirements
+    
+  deployment.md:
+    - Environments
+    - Deployment steps
+    - Configuration
+    - Monitoring
+```
+
+### Step 2C: User Guide
+```yaml
+sources:
+  - Feature specs from phases
+  - UI components (if frontend)
+  - Business rules from PROJECT-CONTEXT.md
+
+generate:
+  quick-start.md:
+    - Getting started
+    - Basic usage
+    - Common tasks
+    
+  features/:
+    - One file per major feature
+    - Screenshots if UI
+    - Step-by-step guides
+    
+  faq.md:
+    - Common questions
+    - Troubleshooting
+```
+
+### Step 2D: Changelog Update
+```yaml
+sources:
+  - Git commits since last version
+  - .viepilot/TRACKER.md decision log
+  - Phase SUMMARY.md files
+
+process:
+  1. Parse commits by type (feat, fix, etc.)
+  2. Group by category (Added, Changed, Fixed, etc.)
+  3. Add to [Unreleased] section
+  4. Include commit references
+```
+
+### Step 3: Generate Files
+Use templates and extracted content to generate markdown files.
+
+### Step 3B: Update skills-reference.md (incremental)
+```bash
+# Scan skills/ directory — source of truth
+SKILLS=$(ls skills/*/SKILL.md 2>/dev/null | sed 's|skills/||; s|/SKILL.md||' | sort)
+DOCUMENTED=$(grep "^## /vp-" docs/skills-reference.md 2>/dev/null | sed 's|## /||' | sort)
+MISSING=$(comm -23 <(echo "$SKILLS") <(echo "$DOCUMENTED"))
+```
+For each skill in `$MISSING`: append section to `docs/skills-reference.md`.
+Do NOT overwrite existing sections (preserve manual edits).
+
+### Step 4: Create Index
+Update `docs/README.md` with:
+- Documentation index
+- Quick links
+- Last updated date
+
+Also update root `README.md`:
+- Documentation table: add links to newly generated docs
+- Project Structure `docs/` tree: reflect actual subdirectories
+
+### Step 5: Commit
+```bash
+git add docs/ CHANGELOG.md
+git commit -m "docs: update documentation"
+```
+
+### Step 6: Confirm
+```
+✓ Documentation generated
+
+Files created/updated:
+- docs/api/ ({count} files)
+- docs/dev/ ({count} files)
+- docs/user/ ({count} files)
+- CHANGELOG.md
+
+View at: docs/README.md
+```
+</process>
+
+<success_criteria>
+- [ ] Requested documentation generated
+- [ ] Code examples included where relevant
+- [ ] Cross-references added between docs
+- [ ] Index updated
+- [ ] Changelog reflects recent changes
+- [ ] GitHub URLs use actual repo (no `your-org`/`YOUR_USERNAME` placeholders)
+- [ ] skills-reference.md has sections for all skills in skills/ directory
+- [ ] Root README.md Documentation table updated
+- [ ] Git committed
+</success_criteria>

package/skills/vp-evolve/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: vp-evolve
+description: "Nâng cấp, thêm features, hoặc bắt đầu milestone mới"
+version: 0.2.0
+---
+
+<cursor_skill_adapter>
+## A. Skill Invocation
+- Skill được gọi khi user mention `vp-evolve`, `/vp-evolve`, "evolve", "thêm feature", "milestone mới", "upgrade"
+- Treat all user text after the skill mention as `{{VP_ARGS}}`
+
+## B. User Prompting
+Prompt user conversationally với options.
+
+## C. Tool Usage
+Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
+</cursor_skill_adapter>
+
+<objective>
+Nâng cấp hoặc mở rộng dự án sau khi hoàn thành milestone hoặc cần thêm features.
+
+**Modes:**
+1. **Add Feature** - Thêm feature vào milestone hiện tại
+2. **New Milestone** - Bắt đầu milestone mới
+3. **Refactor** - Cải thiện code hiện có
+
+**Routing intelligence:**
+- Với yêu cầu thiên về khám phá ý tưởng (đặc biệt landing page), ưu tiên route qua `/vp-brainstorm` nâng cao trước khi crystallize phase.
+- Hỗ trợ route brainstorm có in-session research để user quyết định ngay trong một phiên.
+
+**Updates:**
+- `.viepilot/ROADMAP.md`
+- `.viepilot/TRACKER.md`
+- `.viepilot/ARCHITECTURE.md` (nếu có changes)
+- `CHANGELOG.md`
+</objective>
+
+<execution_context>
+@$HOME/.cursor/viepilot/workflows/evolve.md
+</execution_context>
+
+<context>
+Optional flags:
+- `--feature` : Add feature mode
+- `--milestone` : New milestone mode
+- `--refactor` : Refactor mode
+</context>
+
+<process>
+
+### Step 1: Detect Current State
+```bash
+cat .viepilot/TRACKER.md
+```
+- Check milestone progress
+- Check if current milestone complete
+
+### Step 2: Ask User Intent
+```
+How would you like to evolve the project?
+
+1. Add Feature - Add new feature to current milestone
+2. New Milestone - Start a new milestone (archive current)
+3. Refactor - Improve existing code without new features
+```
+
+### Step 3A: Add Feature Mode
+```yaml
+flow:
+  1. Ask feature description
+  2. Mini brainstorm:
+     - What does it do?
+     - Which services affected?
+     - Dependencies on existing code?
+  3. If landing-page or research-heavy:
+     - route: /vp-brainstorm --new --landing --research
+     - return here after brainstorm summary
+  4. Check architecture compatibility
+  5. Generate new phase in ROADMAP.md
+  6. Create phase directory with SPEC.md
+  7. Update TRACKER.md
+  
+output:
+  - New phase added to ROADMAP.md
+  - Phase directory created
+  - Ready for /vp-auto
+```
+
+### Step 3B: New Milestone Mode
+```yaml
+flow:
+  1. Archive current milestone:
+     - Move ROADMAP.md → milestones/v{X}/
+     - Create MILESTONE-SUMMARY.md
+     - Tag git: v{X}.0.0
+  2. Start brainstorm for new scope:
+     - Default: /vp-brainstorm --new
+     - If landing-page oriented: /vp-brainstorm --new --landing --research
+  3. After brainstorm, route to /vp-crystallize
+  4. Carry over:
+     - PROJECT-META.md (unchanged)
+     - SYSTEM-RULES.md (unchanged)
+     - Learnings and patterns
+     
+output:
+  - Previous milestone archived
+  - New ROADMAP.md created
+  - Version bumped (MAJOR or MINOR)
+```
+
+### Step 3C: Refactor Mode
+```yaml
+flow:
+  1. Analyze code for improvement areas:
+     - Code duplication
+     - Performance issues
+     - Architecture violations
+     - Technical debt
+  2. Create refactor tasks
+  3. Ensure backward compatibility
+  4. Generate refactor phase
+  5. Update ARCHITECTURE.md if structure changes
+
+output:
+  - Refactor phase added
+  - Backward compatibility documented
+  - Ready for /vp-auto
+```
+
+### Step 4: Update Version
+Based on changes:
+- **Add Feature** → MINOR bump
+- **New Milestone** → MAJOR or MINOR bump
+- **Refactor** → PATCH bump (no behavior change)
+
+Update in:
+- TRACKER.md
+- pom.xml / package.json
+- CHANGELOG.md [Unreleased] section
+
+### Step 5: Confirm & Suggest Next
+```
+✓ Evolution complete
+
+Mode: {mode}
+Changes:
+- {list changes}
+
+Version: {old} → {new}
+
+Next action: /vp-auto --from {new_phase}
+```
+</process>
+
+<success_criteria>
+- [ ] User intent correctly identified
+- [ ] Architecture compatibility checked
+- [ ] ROADMAP.md updated with new phases
+- [ ] TRACKER.md updated
+- [ ] Version bumped appropriately
+- [ ] CHANGELOG.md updated
+- [ ] Landing-page requests are routed to enhanced brainstorm flow
+- [ ] Research-heavy requests can be handled inside brainstorm session
+- [ ] Ready for execution
+</success_criteria>