viepilot 1.0.0

package/workflows/autonomous.md

@@ -0,0 +1,425 @@
+<purpose>
+Autonomous execution của project phases. Cho mỗi phase: analyze → execute tasks → verify → iterate.
+Pauses at control points cho user decisions.
+</purpose>
+
+<process>
+
+<step name="initialize">
+## 1. Initialize
+
+Parse `{{VP_ARGS}}` for flags:
+- `--from N` : Start từ phase N
+- `--phase N` : Chỉ chạy phase N
+- `--fast` : Skip optional verifications
+- `--dry-run` : Plan only
+
+Load context:
+```bash
+cat .viepilot/AI-GUIDE.md
+cat .viepilot/TRACKER.md
+cat .viepilot/ROADMAP.md
+```
+
+Display startup banner:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VIEPILOT ► AUTONOMOUS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Project: {project_name}
+ Milestone: {milestone}
+ Phases: {total} total, {completed} complete
+```
+</step>
+
+<step name="discover_phases">
+## 2. Discover Phases
+
+Parse ROADMAP.md for phases.
+
+Filter to incomplete phases:
+- Status != "complete"
+- Apply --from filter if provided
+- Sort by phase number
+
+If no incomplete phases:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VIEPILOT ► COMPLETE 🎉
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ All phases complete! 
+
+ Next steps:
+ - /vp-docs to generate documentation
+ - /vp-evolve to add more features
+```
+Exit cleanly.
+</step>
+
+<step name="execute_phase">
+## 3. Execute Phase
+
+Display progress:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VIEPILOT ► Phase {N}/{T}: {Name} [████░░░░] {P}%
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### 3a. Load Phase Context
+```bash
+cat .viepilot/phases/{phase}/SPEC.md
+cat .viepilot/phases/{phase}/PHASE-STATE.md
+```
+
+Check if phase already has completed tasks → resume from next task.
+
+### 3b. Execute Tasks Loop
+
+For each task in phase:
+
+#### Load Task Context
+```yaml
+read:
+  - .viepilot/AI-GUIDE.md
+  - .viepilot/TRACKER.md
+  - .viepilot/phases/{phase}/PHASE-STATE.md
+  - .viepilot/phases/{phase}/tasks/{task}.md
+  - context_required files from task file
+```
+
+#### Validate Task Contract (required before code)
+Task must include execution-grade details:
+- Objective (specific outcome)
+- Exact file paths to create/modify
+- Per-file implementation notes (what + why)
+- Best practices to apply (stack + code quality)
+- Verification commands with expected results
+
+If task file is missing required sections:
+- Mark task as `blocked`
+- Record missing sections in PHASE-STATE.md
+- Stop and request task refinement (do not start coding)
+
+#### Pre-execution documentation gate (doc-first; BUG-001)
+
+**Hard stop** before **any implementation work** (creating/modifying product code, configs, or docs that ship with the product—anything you would commit as “the task deliverable”):
+
+Canonical order for every task: **Validate contract → Doc-first gate → Stack preflight → Start checkpoint → Execute → Verify → State updates.**
+
+1. **Written plan in the task file** — The active `.viepilot/phases/{phase}/tasks/{task}.md` MUST already contain real, task-specific content (not template placeholders) in:
+   - `## Paths` (or equivalent), listing concrete files/dirs, and
+   - `## File-Level Plan` **or** `## Implementation Notes` with an explicit bullet list of paths + what will change and why.
+   If only `{{PLACEHOLDER}}` tokens remain → **blocked**; refine the task file first.
+2. **PHASE-STATE visibility** — Set the current task row to `in_progress` in `PHASE-STATE.md` **before** the first implementation commit for this task (timestamp/note optional but recommended).
+
+**Allowed before this gate passes:** Read-only exploration, contract checks, and **editing the task `.md`** to record the plan (that edit is not “implementation” of the deliverable).
+
+If any check fails:
+- Mark task `blocked` in `PHASE-STATE.md` and list what is missing under **Notes**
+- **Do not** create `vp-p{phase}-t{task}`
+- **Do not** proceed to **Execute Task**
+
+#### Stack Preflight (token-efficient lookup)
+Before implementing, detect relevant stacks for the current task and load guidance in this order:
+1. `.viepilot/STACKS.md` (project stack map)
+2. `~/.viepilot/stacks/{stack}/SUMMARY.md` (quick checklist, always first)
+3. `~/.viepilot/stacks/{stack}/BEST-PRACTICES.md` (only if task is medium/high complexity)
+4. `~/.viepilot/stacks/{stack}/ANTI-PATTERNS.md` (for review before finalizing)
+
+If stack cache is missing:
+- warn and optionally run quick research
+- then continue with explicit assumptions noted in task logs
+
+#### Task start checkpoint (after doc-first gate + preflight)
+
+Only after **Validate Task Contract**, **Pre-execution documentation gate**, and **Stack Preflight** (or explicit waiver logged in the task file with reason):
+
+Create git tag: `vp-p{phase}-t{task}`  
+Ensure `PHASE-STATE.md` already shows current task `in_progress` (set during the gate if not already).
+
+#### Execute Task
+1. Read task objective and acceptance criteria
+2. Read SYSTEM-RULES.md for coding standards
+3. Apply stack cache guidance from preflight
+4. Load any required schemas
+5. Split into sub-tasks (30-90 minutes each) if scope is non-trivial
+6. Before each sub-task, write/update plan notes in task file:
+   - files touched
+   - implementation intent
+   - best-practice checklist
+7. Implement according to task specification
+6. Atomic commits per logical unit:
+   ```bash
+   git add {relevant files}
+   git commit -m "{type}({scope}): {description}"
+   git push
+   ```
+8. Log notes in task file after each sub-task
+
+#### Verify Task
+```yaml
+automated:
+  - Run commands from task verification section
+  - Check expected outputs
+
+manual:
+  - Present to user if defined
+  - Ask for confirmation
+
+quality_gate:
+  - acceptance_criteria_met: true
+  - automated_tests_pass: true
+  - no_lint_errors: true
+```
+
+#### Handle Result
+
+**PASS:**
+- Create git tag: `vp-p{phase}-t{task}-done`
+- Update PHASE-STATE.md immediately: task → done, append files changed by this task to Files Changed table (individual files, no glob patterns)
+- Update TRACKER.md immediately
+- Update HANDOFF.json immediately
+- Update CHANGELOG.md if feature/fix
+- Move to next task
+
+**PARTIAL (some checks fail):**
+- Attempt auto-fix
+- Re-verify
+- If still fail → control point
+
+**FAIL:**
+→ Go to handle_blocker
+</step>
+
+<step name="update_state">
+## 4. Update State
+
+After each PASS task and PASS sub-task (state-first, then continue):
+```yaml
+update:
+  - PHASE-STATE.md: task status, timestamp
+  - TRACKER.md: current state, progress
+  - HANDOFF.json: latest position
+  - ROADMAP.md: sync when phase status/progress changed
+  - CHANGELOG.md: if feature/fix completed
+```
+
+Rule:
+- Never defer state updates to end-of-phase only.
+- If interrupted, HANDOFF.json must still point to exact in-progress task/sub-task.
+</step>
+
+<step name="phase_complete">
+## 5. Phase Complete
+
+When all tasks in phase are done/skipped:
+
+1. Run phase-level verification
+2. Check phase quality gate
+3. Write SUMMARY.md using `templates/phase/SUMMARY.md` as base.
+
+   Populate `{{CREATED_FILES}}`, `{{MODIFIED_FILES}}`, `{{DELETED_FILES}}` from git:
+   ```bash
+   # Get ALL individual files changed since phase start tag
+   git diff vp-p{phase}-t1..HEAD --name-status | sort
+   ```
+   List **every file individually** — do NOT use glob patterns or summarize.
+   Correct example:
+   ```
+   ### Created
+   | File | Task |
+   |------|------|
+   | pom.xml | 1.1 |
+   | smarttrack-api/pom.xml | 1.1 |
+   | smarttrack-common/pom.xml | 1.1 |
+   | smarttrack-common/src/main/java/Foo.java | 1.1 |
+   | docker-compose.yml | 1.2 |
+   ```
+   Incorrect (do not do this):
+   ```
+   | smarttrack-*/pom.xml (8 files) | 1.1 |   ← WRONG: glob pattern
+   | smarttrack-*/src/** (7 files)  | 1.1 |   ← WRONG: summarized
+   ```
+4. Create git tag: `vp-p{phase}-complete`
+5. Check version bump needed:
+   - Features added → MINOR
+   - Fixes only → PATCH
+6. Update TRACKER.md
+7. Push all changes:
+   ```bash
+   git push
+   git push --tags
+   ```
+
+### 5a. Sync ROADMAP.md (after every phase complete)
+
+Update `.viepilot/ROADMAP.md` to reflect current phase status:
+
+```markdown
+# Find phase section and update:
+- Phase status line: "Not Started" → "✅ Complete"  (or "🔄 In Progress")
+- Progress Summary table row: 0% → 100%, Completed count → actual
+
+Example:
+  Before: | 5. vp-docs Enhancements | ⏳ Not Started | 2 | 0 | 0% |
+  After:  | 5. vp-docs Enhancements | ✅ Complete    | 2 | 2 | 100% |
+```
+
+Commit: `chore: update ROADMAP.md — phase {N} complete`
+
+### 5b. Update skills-reference.md if new skills added (viepilot framework only)
+
+> **Guard**: Only run this step if `skills/` directory exists in the project root.
+> Skip entirely for non-framework projects (Java, Node, Python apps, etc.).
+
+```bash
+# Skip if not a viepilot framework repo
+if [ ! -d "skills" ]; then
+  echo "→ Skipping skills-reference update (not a viepilot framework repo)"
+else
+  NEW_SKILLS=$(git diff vp-p{phase}-t1..HEAD --name-only | grep 'skills/.*/SKILL\.md' | sed 's|skills/||; s|/SKILL\.md||')
+  if [ -n "$NEW_SKILLS" ]; then
+    # Append new sections to docs/skills-reference.md
+    # (same incremental logic as workflows/documentation.md step 3B)
+    git add docs/skills-reference.md
+    git commit -m "docs: add {skill} to skills-reference.md"
+    git push
+  fi
+fi
+```
+</step>
+
+<step name="iterate">
+## 6. Iterate
+
+After phase complete:
+1. Re-read ROADMAP.md (catch inserted phases)
+2. Check TRACKER.md for blockers
+3. If more phases → loop to step 3
+4. If all complete → milestone complete
+
+Milestone complete — Sync ROOT documents:
+
+### 6a. Sync README.md (milestone complete only)
+
+Detect project version from the appropriate version file:
+```bash
+# Generic version detection — works for any project type
+if [ -f "package.json" ]; then
+  ACTUAL_VERSION=$(node -p "require('./package.json').version" 2>/dev/null)
+elif [ -f "pom.xml" ]; then
+  ACTUAL_VERSION=$(grep -m1 "<version>" pom.xml 2>/dev/null | sed 's/.*<version>//;s/<.*//' | tr -d ' ')
+elif [ -f "pyproject.toml" ]; then
+  ACTUAL_VERSION=$(grep '^version' pyproject.toml 2>/dev/null | head -1 | cut -d'"' -f2)
+elif [ -f ".viepilot/TRACKER.md" ]; then
+  # Fallback: read from TRACKER.md (viepilot-managed version)
+  ACTUAL_VERSION=$(grep -A1 "Current Version" .viepilot/TRACKER.md | tail -1 | tr -d '`' | tr -d ' ')
+fi
+```
+
+Update README.md — **generic updates (all projects)**:
+1. Any version number mentions: update to `$ACTUAL_VERSION`
+2. Any "last updated" or "as of" date references
+
+**viepilot framework only** (skip if `skills/` directory does not exist):
+```bash
+if [ -d "skills" ]; then
+  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 ' ')
+  # Update: version badge, skills badge, workflows badge
+  # Update: Skills Reference table, Workflows table, Project Structure skills/ list
+fi
+```
+
+Commit: `docs: sync README.md to v{ACTUAL_VERSION}`
+```bash
+git add README.md
+git commit -m "docs: sync README.md to v{ACTUAL_VERSION}"
+git push
+```
+
+### 6b. Display milestone complete banner
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VIEPILOT ► MILESTONE COMPLETE 🎉
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Milestone: {name}
+ Phases: {count} complete
+ Version: {version}
+ README.md: synced ✓
+ ROADMAP.md: synced ✓
+
+ Next steps:
+ - /vp-docs to generate documentation
+ - /vp-evolve to start next milestone
+```
+</step>
+
+<step name="handle_blocker">
+## 7. Handle Blocker
+
+At any control point:
+```
+⚠ Phase {N} ({Name}): Issue Encountered
+
+{description of issue}
+
+Options:
+1. Fix and retry - Attempt to fix the issue
+2. Skip task - Mark as skipped and continue
+3. Rollback task - Undo changes from this task
+4. Stop autonomous - Exit with progress summary
+```
+
+**Fix and retry:**
+- Re-attempt the failed step
+- If still fails → re-present options
+
+**Skip task:**
+- Ask for skip reason
+- Log in PHASE-STATE.md
+- Continue to next task
+
+**Rollback:**
+```bash
+git revert --no-commit $(git rev-list vp-p{phase}-t{task}..HEAD)
+```
+- Reset task → not_started
+- Continue or stop
+
+**Stop:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VIEPILOT ► STOPPED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Progress saved.
+ 
+ Completed: {list}
+ Skipped: {list}
+ Remaining: {list}
+
+ Resume with: /vp-resume
+ Or continue: /vp-auto --from {next_phase}
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Phases executed in order
+- [ ] Tasks tracked with git tags
+- [ ] State updated after each task
+- [ ] Quality gates enforced
+- [ ] CHANGELOG updated for features/fixes
+- [ ] Checkpoints created for recovery
+- [ ] ROADMAP.md synced after each phase complete
+- [ ] skills-reference.md updated when new skills added in a phase
+- [ ] README.md badges and counts synced on milestone complete
+- [ ] Clean stop with summary on pause/error
+</success_criteria>

package/workflows/brainstorm.md

@@ -0,0 +1,257 @@
+<purpose>
+Interactive brainstorm session để thu thập ý tưởng, requirements, và quyết định cho dự án.
+Cho phép research ngay trong cùng phiên brainstorm khi cần.
+</purpose>
+
+<process>
+
+<step name="detect_sessions">
+## 1. Detect Previous Sessions
+
+```bash
+ls -la docs/brainstorm/session-*.md 2>/dev/null | tail -5
+```
+
+Parse results to get list of existing sessions.
+</step>
+
+<step name="ask_intent">
+## 2. Ask User Intent
+
+**If previous sessions exist:**
+```
+Tôi tìm thấy các phiên brainstorm trước đó:
+{list sessions with dates}
+
+Bạn muốn:
+1. Tiếp tục phiên gần nhất
+2. Xem lại một phiên cụ thể  
+3. Tạo mới phiên brainstorm
+```
+
+**If no sessions:**
+Tự động tạo phiên mới.
+</step>
+
+<step name="load_context">
+## 3. Load Context (nếu tiếp tục)
+
+Nếu user chọn tiếp tục:
+1. Đọc file phiên trước đó
+2. Tóm tắt nội dung đã thảo luận
+3. Xác định các open questions / action items còn lại
+4. Tiếp tục từ điểm dừng
+</step>
+
+<step name="brainstorm_mode">
+## 4. Brainstorm Mode
+
+### Topics Template
+Gợi ý các topics để brainstorm:
+
+1. **Domain Analysis**
+   - Mục tiêu dự án
+   - User personas
+   - Core use cases
+
+2. **Architecture**
+   - System components
+   - Data flow
+   - Technology stack
+
+3. **Data Model**
+   - Core entities
+   - Relationships
+   - Storage strategy
+
+4. **API Design**
+   - Endpoint structure
+   - Authentication
+   - Real-time requirements
+
+5. **Infrastructure**
+   - Deployment strategy
+   - Monitoring
+   - Scaling
+
+### Interactive Q&A
+Cho mỗi topic:
+1. Đặt câu hỏi cụ thể
+2. Đợi user trả lời
+3. Tổng hợp và đặt follow-up questions
+4. Đề xuất alternatives nếu cần
+5. Ghi nhận decisions
+
+### Landing Page Deep-Dive (kích hoạt theo ngữ cảnh)
+Nếu user brainstorm về landing page / homepage / marketing page:
+
+1. Hỏi thêm để chốt bố cục:
+   - Goal chính của landing page? (signup, booking demo, download, contact)
+   - Audience chính?
+   - Tone visual? (minimal, modern, bold, enterprise, playful)
+   - CTA chính và CTA phụ?
+2. Đưa menu bố cục để user chọn:
+   - Layout A: Hero centric + trust logos + features + CTA
+   - Layout B: Problem/Solution + social proof + pricing + FAQ
+   - Layout C: Product storytelling + screenshots + testimonials + final CTA
+   - Layout D: SaaS conversion + integrations + comparison + onboarding steps
+3. Tham khảo `https://21st.dev` để đề xuất section/components phù hợp với layout đã chọn.
+4. Ghi rõ trong session:
+   - Layout user chọn
+   - Component candidates từ 21st.dev
+   - Lý do chọn theo objective + audience
+
+### In-session Research Mode
+User có thể yêu cầu research ngay trong brainstorm (không cần đổi skill):
+- Trigger phrases: "research cái này", "bạn research giúp", "cần research", "hãy tìm best practice"
+- Khi trigger:
+  1. Xác định scope research (1-3 câu)
+  2. Thu thập nhanh từ nguồn phù hợp (docs chính thức, reference sites, patterns)
+  3. Trả về tóm tắt ngắn: findings, trade-offs, recommendation
+  4. Quay lại topic brainstorm hiện tại với quyết định đề xuất
+
+Nếu assistant nhận thấy topic có độ mơ hồ cao hoặc rủi ro quyết định sai, assistant nên chủ động đề xuất:
+`Mục này nên research nhanh trước khi chốt, bạn muốn mình research luôn trong phiên này không?`
+
+### UI Direction Mode (design-in-the-loop; FEAT-002)
+Nếu user đang brainstorm cho dự án có UI/UX hoặc yêu cầu thiết kế trực quan:
+
+1. Tạo workspace direction cho phiên hiện tại:
+   - `.viepilot/ui-direction/{session-id}/index.html`
+   - `.viepilot/ui-direction/{session-id}/style.css`
+   - `.viepilot/ui-direction/{session-id}/notes.md`
+2. Mỗi lần user đổi requirement/layout/component:
+   - Cập nhật trực tiếp HTML/CSS direction
+   - Ghi decision + rationale vào `notes.md` (single source of truth)
+3. Nếu user gửi references/components (bao gồm 21st.dev prompt/link), ghi rõ:
+   - nguồn tham chiếu
+   - phần UI áp dụng
+   - điều chỉnh theo mục tiêu sản phẩm
+4. Giữ prototype ở mức mô tả định hướng (directional), không ép build production-ready code ở bước brainstorm.
+
+### Kết thúc mỗi topic
+- Tóm tắt decisions
+- List action items
+- Note open questions
+</step>
+
+<step name="save_session">
+## 5. Save Session
+
+Tạo/cập nhật file: `docs/brainstorm/session-{YYYY-MM-DD}.md`
+
+```markdown
+# Brainstorm Session - {YYYY-MM-DD}
+
+## Session Info
+- **Date**: {full date}
+- **Participants**: User, Claude
+- **Status**: In Progress | Completed
+
+## Topics Discussed
+
+### Topic 1: {Name}
+**Context**: {brief context}
+
+**Discussion**:
+- Point 1
+- Point 2
+
+**Decisions**:
+- [x] Decision 1
+- [x] Decision 2
+
+**Open Questions**:
+- Question 1?
+
+**Research Notes**:
+- Query: {what was researched}
+- Sources: {links / docs}
+- Findings: {key points}
+- Recommendation: {recommended direction}
+
+**Landing Page Decisions** (if applicable):
+- Chosen layout: {A|B|C|D|Custom}
+- Section order: {hero -> proof -> features -> pricing -> faq -> cta}
+- 21st.dev references:
+  - {component/pattern 1}
+  - {component/pattern 2}
+
+**UI Direction Artifacts** (if applicable):
+- Session id: {session-id}
+- Files:
+  - `.viepilot/ui-direction/{session-id}/index.html`
+  - `.viepilot/ui-direction/{session-id}/style.css`
+  - `.viepilot/ui-direction/{session-id}/notes.md`
+- Preview focus:
+  - {layout/flow summary}
+
+---
+
+## Summary
+
+### Key Decisions
+1. Decision summary
+
+### Action Items
+- [ ] Action 1
+- [ ] Action 2
+
+### Next Steps
+- What to do next
+
+### Open Questions
+- Unresolved questions
+```
+
+Commit:
+```bash
+mkdir -p docs/brainstorm
+git add docs/brainstorm/
+git commit -m "docs: brainstorm session {date}"
+git push
+```
+</step>
+
+<step name="suggest_next">
+## 6. Suggest Next Action
+
+```
+✓ Brainstorm session saved
+
+Summary:
+- Topics covered: {count}
+- Decisions made: {count}
+- Open questions: {count}
+
+Next step: /vp-crystallize
+This will transform your brainstorm into:
+- Project structure
+- Architecture documents
+- Development roadmap
+```
+</step>
+
+</process>
+
+<commands>
+User có thể dùng các lệnh trong phiên brainstorm:
+
+- `/topic {name}` - Chuyển sang topic mới
+- `/summary` - Xem tóm tắt phiên hiện tại
+- `/save` - Lưu tiến độ ngay
+- `/end` - Kết thúc và lưu phiên
+- `/questions` - Xem danh sách open questions
+- `/research {topic}` - Research nhanh ngay trong phiên và quay lại topic hiện tại
+</commands>
+
+<success_criteria>
+- [ ] Session file created với đầy đủ sections
+- [ ] Decisions có rationale
+- [ ] Open questions tracked
+- [ ] Action items captured
+- [ ] Landing page topics trigger layout follow-up questions
+- [ ] 21st.dev references được dùng khi thảo luận landing page
+- [ ] Research có thể chạy ngay trong brainstorm session khi user yêu cầu
+- [ ] Git committed
+</success_criteria>