viepilot 1.0.0

package/workflows/crystallize.md

@@ -0,0 +1,418 @@
+<purpose>
+Chuyển đổi brainstorm sessions thành structured artifacts để AI có thể autonomous execution.
+</purpose>
+
+<process>
+
+<step name="collect_metadata">
+## Step 0: Collect Project Metadata
+
+Hỏi user các thông tin dự án:
+
+### Basic Info
+```
+1. Tên dự án?
+   Default: (extract from brainstorm)
+   
+2. Mô tả ngắn gọn (1-2 câu)?
+```
+
+### Organization Info
+```
+3. Tên công ty/tổ chức phát triển?
+
+4. Website công ty? (optional)
+```
+
+### Package Info
+```
+5. Package Base ID (Java package)?
+   Example: com.acme.smarttrack
+   Validation: ^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)*$
+   
+6. Maven Artifact ID?
+   Default: {project-name-kebab-case}
+   
+7. Maven Group ID?
+   Default: {package_base_id}
+```
+
+### Developer Info
+```
+8. Tên người phát triển chính?
+
+9. Email người phát triển chính?
+
+10. GitHub username? (optional)
+```
+
+### Repository Info
+```
+11. Repository URL? (optional)
+
+12. Issue Tracker URL?
+    Default: {repository_url}/issues
+```
+
+### License & Year
+```
+13. License?
+    Options: MIT, Apache-2.0, GPL-3.0, BSD-3-Clause, Proprietary
+    Default: MIT
+    
+14. Năm bắt đầu dự án?
+    Default: {current_year}
+```
+
+Store all metadata for template generation.
+</step>
+
+<step name="analyze_brainstorm">
+## Step 1: Analyze Brainstorm
+
+```bash
+ls docs/brainstorm/session-*.md
+```
+
+For each session file:
+1. Extract decisions (look for "Decision:" patterns)
+2. Extract architecture info
+3. Extract database schemas
+4. Extract features/requirements
+5. Extract tech stack choices
+
+Validate completeness:
+- [ ] Tech stack defined
+- [ ] Core features identified
+- [ ] Database schema exists
+- [ ] API requirements clear
+
+If gaps found → ask user to clarify or return to brainstorm.
+</step>
+
+<step name="consume_ui_direction">
+## Step 1A: Consume UI Direction Artifacts (for UI/UX projects)
+
+If brainstorm indicates frontend/UI scope, check for direction artifacts:
+
+```bash
+ls -la .viepilot/ui-direction/ 2>/dev/null
+```
+
+When available, for the selected/latest session:
+- Read `.viepilot/ui-direction/{session-id}/notes.md` first (source of design decisions)
+- Read `index.html` + `style.css` to extract:
+  - layout hierarchy
+  - component candidates
+  - interaction expectations
+- Record how each UI direction item maps into target tech stack implementation plan.
+
+If UI scope is present but artifacts are missing:
+- Warn user and request either:
+  1. generate UI direction via `/vp-brainstorm --ui`, or
+  2. explicitly continue with assumptions.
+</step>
+
+<step name="research_stack_official">
+## Step 1B: Research Official Stack Guidance (mandatory)
+
+For each selected stack extracted in Step 1:
+1. Use `WebSearch` to find official documentation and authoritative references.
+2. Use `WebFetch` to read and verify each selected source before summarizing.
+3. Prefer source priority in this order:
+   - Official framework docs/specification
+   - Official project GitHub org docs
+   - Maintainer-authored references
+   - Community articles (only as supplemental context)
+4. Reject weak sources (outdated, anonymous, unclear version, no technical detail).
+5. Build a concise implementation guide that can be reused by `vp-auto`.
+6. Capture "Do / Don't" rules and common anti-patterns.
+
+Required output per stack:
+- Quick summary (token-light)
+- Best practices
+- Anti-patterns
+- Source links + checked date
+- Version compatibility note (e.g. MyBatis 3.x, Spring Boot 3.x integration notes)
+
+Recommended structure:
+```yaml
+stack: mybatis
+official_sources:
+  - https://mybatis.org/mybatis-3/
+guideline:
+  do:
+    - Prefer XML mapper for complex SQL and reusable fragments
+  dont:
+    - Avoid large inline SQL annotations for complex queries
+```
+
+If official sources cannot be verified, pause crystallize and ask user to confirm temporary assumptions.
+</step>
+
+<step name="write_stack_cache">
+## Step 1C: Write Global Stack Cache
+
+Persist stack guidance globally for cross-project reuse:
+
+```bash
+mkdir -p "$HOME/.viepilot/stacks/{stack}"
+```
+
+Files per stack:
+- `~/.viepilot/stacks/{stack}/SUMMARY.md` (short checklist for fast lookup)
+- `~/.viepilot/stacks/{stack}/BEST-PRACTICES.md`
+- `~/.viepilot/stacks/{stack}/ANTI-PATTERNS.md`
+- `~/.viepilot/stacks/{stack}/SOURCES.md` (official docs + last validated date)
+
+Also create project-local index for traceability:
+- `.viepilot/STACKS.md` listing stacks used and cache paths.
+</step>
+
+<step name="generate_ai_guide">
+## Step 2: Generate AI-GUIDE.md
+
+Create `.viepilot/AI-GUIDE.md` using template:
+`@$HOME/.cursor/viepilot/templates/project/AI-GUIDE.md`
+
+Customize with:
+- Project-specific file references
+- Context loading strategy based on project size
+- Quick lookup for project-specific terms
+- Fast stack lookup section:
+  - Read `.viepilot/STACKS.md`
+  - For each task stack, read cache `SUMMARY.md` first
+  - Expand to `BEST-PRACTICES.md` only if task complexity requires
+</step>
+
+<step name="generate_project_meta">
+## Step 3: Generate PROJECT-META.md
+
+Create `.viepilot/PROJECT-META.md` using template:
+`@$HOME/.cursor/viepilot/templates/project/PROJECT-META.md`
+
+Fill with collected metadata:
+- Project info
+- Organization info
+- Package structure (generate from base ID)
+- Developer info
+- File headers (generate from metadata)
+</step>
+
+<step name="generate_architecture">
+## Step 4: Generate ARCHITECTURE.md
+
+Create `.viepilot/ARCHITECTURE.md` using template:
+`@$HOME/.cursor/viepilot/templates/project/ARCHITECTURE.md`
+
+Extract from brainstorm:
+- System overview diagram
+- Services definitions
+- Data flow
+- Technology decisions with rationale
+- Integration points
+</step>
+
+<step name="generate_context">
+## Step 5: Generate PROJECT-CONTEXT.md
+
+Create `.viepilot/PROJECT-CONTEXT.md` using template:
+`@$HOME/.cursor/viepilot/templates/project/PROJECT-CONTEXT.md`
+
+Extract:
+- Domain knowledge
+- Key concepts
+- Business rules
+- Naming conventions
+- Constraints
+</step>
+
+<step name="generate_rules">
+## Step 6: Generate SYSTEM-RULES.md
+
+Create `.viepilot/SYSTEM-RULES.md` using template:
+`@$HOME/.cursor/viepilot/templates/project/SYSTEM-RULES.md`
+
+Include:
+- Architecture rules
+- Coding rules (language-specific)
+- Comment standards (good/bad examples)
+- Versioning (SemVer)
+- Git conventions (Conventional Commits)
+- Changelog standards (Keep a Changelog)
+- Contributor standards
+- Quality gates
+- Forbidden patterns
+- Stack-specific enforcement:
+  - Must follow cached stack `Do/Don't` guidance
+  - Require official-source alignment for framework-specific implementation
+</step>
+
+<step name="generate_roadmap">
+## Step 7: Generate ROADMAP.md
+
+Create `.viepilot/ROADMAP.md` using template:
+`@$HOME/.cursor/viepilot/templates/project/ROADMAP.md`
+
+From brainstorm features/MVP breakdown:
+1. Create phases
+2. For each phase:
+   - Define goal
+   - Break into tasks
+   - Set acceptance criteria
+   - Add verification checkpoints
+   - Estimate complexity (S/M/L/XL)
+3. Define dependencies between phases
+</step>
+
+<step name="generate_schemas">
+## Step 8: Generate schemas/
+
+Create `.viepilot/schemas/`:
+
+**database-schema.sql**
+- Extract from brainstorm
+- Add proper comments
+- Include indexes, constraints
+
+**kafka-topics.yaml**
+- List all topics
+- Define message schemas
+- Include examples
+
+**api-contracts.yaml** (OpenAPI stub)
+- Endpoint definitions
+- Request/Response schemas
+- Auth requirements
+</step>
+
+<step name="generate_tracker">
+## Step 9: Initialize TRACKER.md
+
+Create `.viepilot/TRACKER.md` using template:
+`@$HOME/.cursor/viepilot/templates/project/TRACKER.md`
+
+Initialize:
+- Current state (all phases not_started)
+- Progress overview (0%)
+- Decision log (import from brainstorm)
+- Version info (0.1.0-alpha)
+- Next action
+
+Create empty `.viepilot/HANDOFF.json`
+</step>
+
+<step name="generate_phase_dirs">
+## Step 10: Create Phase Directories
+
+For each phase in ROADMAP.md:
+```bash
+mkdir -p .viepilot/phases/{NN}-{phase-slug}/tasks/
+```
+
+Create:
+- `SPEC.md` - Phase specification
+- `PHASE-STATE.md` - Initial state (not_started)
+- `tasks/` directory with task files
+</step>
+
+<step name="generate_project_files">
+## Step 11: Generate Project Files
+
+**CHANGELOG.md**
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial project setup
+
+## [0.1.0] - {date}
+
+### Added
+- Project initialization via ViePilot
+- Architecture documentation
+- Development roadmap
+
+[Unreleased]: {repo}/compare/v0.1.0...HEAD
+[0.1.0]: {repo}/releases/tag/v0.1.0
+```
+
+**CONTRIBUTING.md** - From template with org info
+**CONTRIBUTORS.md** - With lead developer
+**LICENSE** - Based on chosen license
+**README.md** - Project overview with links to docs
+</step>
+
+<step name="commit_confirm">
+## Step 12: Commit & Confirm
+
+```bash
+git add .viepilot/ CHANGELOG.md CONTRIBUTING.md CONTRIBUTORS.md LICENSE README.md
+git commit -m "feat: initialize project with ViePilot
+
+- Add project documentation (.viepilot/)
+- Add architecture and coding standards
+- Add development roadmap
+- Add changelog and contributing guidelines"
+git push
+```
+
+Display summary:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VIEPILOT ► CRYSTALLIZE COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Project: {project_name}
+ Package: {package_base_id}
+ License: {license}
+
+ Created:
+ ├── .viepilot/
+ │   ├── AI-GUIDE.md
+ │   ├── PROJECT-META.md
+ │   ├── ARCHITECTURE.md
+ │   ├── PROJECT-CONTEXT.md
+ │   ├── SYSTEM-RULES.md
+ │   ├── ROADMAP.md ({phase_count} phases)
+ │   ├── TRACKER.md
+ │   └── schemas/
+ │
+ ├── CHANGELOG.md
+ ├── CONTRIBUTING.md
+ ├── CONTRIBUTORS.md
+ ├── LICENSE
+ └── README.md
+
+ Phases: {phase_count}
+ Tasks: {total_task_count}
+ 
+ Next step: /vp-auto
+ 
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Note: global stack cache at `~/.viepilot/stacks/` is machine-level knowledge and is not committed to project git.
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] All metadata collected
+- [ ] Official research completed for each selected stack
+- [ ] Global stack cache written under ~/.viepilot/stacks/{stack}/
+- [ ] All artifacts created in .viepilot/
+- [ ] PROJECT-META.md complete
+- [ ] SYSTEM-RULES.md has all standards
+- [ ] ROADMAP.md has phases with tasks
+- [ ] Phase directories created
+- [ ] Project files created
+- [ ] Git committed
+</success_criteria>

package/workflows/debug.md

@@ -0,0 +1,241 @@
+<purpose>
+Systematic debugging workflow với persistent state tracking.
+Giúp organize debugging process và track progress qua nhiều sessions.
+</purpose>
+
+<process>
+
+<step name="initialize">
+## 1. Initialize Debug Environment
+
+```bash
+mkdir -p .viepilot/debug
+```
+
+Check for active session:
+```bash
+cat .viepilot/debug/CURRENT.json 2>/dev/null
+```
+
+Parse `{{VP_ARGS}}` for flags:
+- `--new` : Force new session
+- `--continue` : Continue current
+- `--list` : List sessions
+- `--close` : Close session
+- `--id <id>` : Specific session
+</step>
+
+<step name="route_action">
+## 2. Route Action
+
+**If --list:**
+```bash
+ls -la .viepilot/debug/session-*.json
+```
+Display sessions with status and dates.
+
+**If --close:**
+Go to step 7 (Close Session).
+
+**If --continue or active session exists:**
+Load session and go to step 4 (Continue Investigation).
+
+**If --new or no active session:**
+Go to step 3 (New Session).
+</step>
+
+<step name="new_session">
+## 3. New Debug Session
+
+Ask user:
+```
+Mô tả vấn đề bạn đang gặp:
+1. Vấn đề là gì?
+2. Triệu chứng? (error messages, behavior)
+3. Khi nào xảy ra? (điều kiện)
+4. Files liên quan?
+```
+
+Create session:
+```json
+{
+  "id": "debug-{YYYYMMDD-HHMMSS}",
+  "status": "active",
+  "created_at": "{ISO}",
+  "updated_at": "{ISO}",
+  "problem": {
+    "description": "{user input}",
+    "symptoms": [],
+    "error_messages": [],
+    "affected_files": []
+  },
+  "investigation": {
+    "hypotheses": [],
+    "tests_run": [],
+    "findings": []
+  },
+  "resolution": null
+}
+```
+
+Save to `.viepilot/debug/session-{id}.json`
+Update `.viepilot/debug/CURRENT.json`:
+```json
+{"active_session": "debug-{id}"}
+```
+</step>
+
+<step name="continue_investigation">
+## 4. Continue Investigation
+
+Load current session state.
+
+Display status:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ DEBUG SESSION: {id}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Problem: {description}
+ Status: {status}
+ 
+ Hypotheses:
+ {list with status}
+ 
+ Findings:
+ {list}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Offer actions:
+1. Add hypothesis
+2. Test hypothesis
+3. Add finding
+4. Mark hypothesis confirmed/rejected
+5. Resolve issue
+6. Close session
+</step>
+
+<step name="generate_hypotheses">
+## 5. Generate/Add Hypotheses
+
+If user requests, AI generates hypotheses based on:
+- Problem description
+- Error messages
+- Affected files content
+- Common patterns
+
+Add to session:
+```json
+{
+  "id": {next_id},
+  "description": "Hypothesis description",
+  "status": "pending",
+  "created_at": "{ISO}"
+}
+```
+
+Display updated hypotheses list.
+</step>
+
+<step name="test_hypothesis">
+## 6. Test Hypothesis
+
+For selected hypothesis:
+1. Suggest test approach
+2. Run test commands
+3. Log results:
+
+```json
+{
+  "hypothesis_id": {id},
+  "command": "command run",
+  "output": "output captured",
+  "conclusion": "supports|contradicts|inconclusive",
+  "timestamp": "{ISO}"
+}
+```
+
+Update hypothesis status based on results.
+</step>
+
+<step name="close_session">
+## 7. Close Session
+
+Ask for resolution type:
+1. **resolved** - Problem fixed
+2. **unresolved** - Giving up for now
+3. **wontfix** - Not going to fix
+
+**If resolved:**
+Ask for:
+- Root cause
+- Fix applied
+- Files changed
+- How verified
+
+Update session:
+```json
+{
+  "status": "resolved",
+  "resolution": {
+    "root_cause": "...",
+    "fix_applied": "...",
+    "files_changed": [...],
+    "verification": "..."
+  }
+}
+```
+
+**If unresolved/wontfix:**
+```json
+{
+  "status": "unresolved|wontfix",
+  "resolution": {
+    "notes": "Why closing without fix"
+  }
+}
+```
+
+Remove CURRENT.json pointer.
+
+Display summary:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ DEBUG SESSION CLOSED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Session: {id}
+ Status: {status}
+ Duration: {time}
+ 
+ Hypotheses tested: {count}
+ Findings: {count}
+ 
+ {Resolution summary if resolved}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</step>
+
+</process>
+
+<commands>
+User commands during debug session:
+
+- `/hypothesis <description>` - Add new hypothesis
+- `/test <hypothesis_id>` - Test specific hypothesis
+- `/finding <description>` - Add finding
+- `/confirm <hypothesis_id>` - Mark hypothesis confirmed
+- `/reject <hypothesis_id>` - Mark hypothesis rejected
+- `/resolve` - Start resolution process
+- `/close` - Close session
+- `/status` - Show current status
+</commands>
+
+<success_criteria>
+- [ ] Session state persists across tool restarts
+- [ ] Hypotheses tracked with status
+- [ ] Tests logged with outputs
+- [ ] Resolution documented
+- [ ] Clean session lifecycle (create → investigate → close)
+</success_criteria>