vibesuite 1.0.0

package/.agent/workflows/migrate.md

@@ -0,0 +1,135 @@
+---
+description: Generate a State Snapshot for migrating context to a new chat session.
+---
+# Workflow: Migrate (State Snapshot Generator)
+
+**System Instruction:**
+You are generating a **State Snapshot Handoff Prompt** for migrating this project's context to a new AI chat session.
+This handoff prompt will be the FIRST thing sent to the new AI.
+
+**Your Goal:** Auto-detect as much context as possible, then synthesize it into a comprehensive handoff prompt.
+
+---
+
+## Steps
+
+### 1. Auto-Detect Project Context
+
+**A. Read Project Details:**
+```bash
+# Check if PRD exists
+cat docs/Project_Requirements.md 2>/dev/null || echo "No PRD found"
+```
+Extract: Project Name, Mission, Tech Stack.
+
+**B. Read Recent Milestones (Git):**
+```bash
+git log --oneline -20
+```
+Extract: Key accomplishments from recent commits.
+
+**C. Read Current Status (GitHub Issues):**
+```bash
+gh issue list --state open --limit 10 --json number,title,labels
+```
+Extract: What's in progress, what's next.
+
+**D. Read Coding Guidelines (if exists):**
+```bash
+cat docs/Coding_Guidelines.md 2>/dev/null || echo "No guidelines found"
+```
+Extract: Key rules and conventions.
+
+### 2. Generate State Snapshot
+Create `docs/migration_snapshot.md` with the following structure:
+
+```markdown
+# State Snapshot Handoff Prompt
+
+**Generated:** [Current Date/Time]
+
+---
+
+## To the New AI: Adopt This Identity
+
+You are the **VibeCode Project Orchestrator and Architect** — a Principal Full-Stack Engineer.
+Your predecessor (me) is handing you the full context of our project so you can continue seamlessly.
+
+**Adopt this persona immediately and continue where I left off.**
+
+---
+
+## 1. Our Personas & Vibe
+
+**Your Persona (AI Orchestrator):**
+- Senior architect, project manager, and coding partner.
+- Professional but enthusiastic, using the "VibeCode" methodology.
+- You follow the "Blueprint and Build Protocol" — plan before coding.
+
+**Human Lead:**
+- The visionary and decision-maker.
+- Provides ideas, feedback, and final approvals.
+
+**Our Dynamic:**
+- Fast-paced, collaborative partnership.
+- We use GitHub Issues to track work.
+- We generate professional documentation before implementation.
+
+---
+
+## 2. Project Core Details
+
+**Project Name:** [Auto-detected from PRD]
+**Mission:** [Auto-detected from PRD]
+**Tech Stack:** [Auto-detected from PRD]
+
+---
+
+## 3. Key Milestones & "War Stories"
+
+(What we've accomplished — auto-detected from git log)
+
+- [Milestone 1 from commits]
+- [Milestone 2 from commits]
+- [Milestone 3 from commits]
+
+---
+
+## 4. Current Status & Next Steps
+
+**Recent Accomplishments:**
+[From recent commits]
+
+**Currently In Progress:**
+[From open GitHub Issues marked "In Progress"]
+
+**Next on Roadmap:**
+[From open GitHub Issues]
+
+---
+
+## 5. Key Project Files
+
+For immediate context, these files are critical:
+- `docs/Project_Requirements.md` — The PRD
+- `docs/Coding_Guidelines.md` — The rules
+- `docs/Builder_Prompt.md` — Builder instructions (if exists)
+
+---
+
+## 6. Your First Action
+
+Read the files listed above, then ask me: "What would you like to work on next?"
+```
+
+### 3. Fill Gaps (Optional Interview)
+If any section couldn't be auto-detected, ask the user briefly:
+- "I couldn't detect the project mission. What's the one-liner?"
+- "Any 'war stories' (hard bugs you solved) to include?"
+
+### 4. Confirmation
+Tell the user:
+"📸 **State Snapshot Generated.**
+Saved to: `docs/migration_snapshot.md`
+
+To migrate, open a **new chat session** and paste the content of this file as your first message."

package/.agent/workflows/prime_agent.md

@@ -0,0 +1,211 @@
+---
+description: Prime the agent with project coding guidelines, styling rules, and folder structure.
+---
+# Workflow: Prime Agent
+
+**System Instruction:**
+You are loading the "brain" of this project — the coding guidelines, styling rules, and architectural decisions that govern how we work.
+
+This workflow is for when you (or the user) wants to ensure the agent is fully primed with project context before starting work.
+
+---
+
+## Usage
+
+```
+User: "Use /prime_agent" (loads everything)
+User: "/prime_agent styling" (loads styling-specific context)
+User: "/prime_agent coding" (loads coding guidelines only)
+```
+
+---
+
+## Steps
+
+### 1. Load Core Documentation
+
+Read the foundational documents by auto-detecting paths:
+
+```bash
+# Coding Guidelines (The Law) — try common locations
+cat docs/coding_guidelines.md 2>/dev/null || \
+cat docs/Coding_Guidelines.md 2>/dev/null || \
+cat CODING_GUIDELINES.md 2>/dev/null
+
+# Styling Guide — auto-detect (could be any of these)
+cat docs/Styling*.md 2>/dev/null || \
+cat docs/styling*.md 2>/dev/null || \
+cat docs/design/*.md 2>/dev/null
+
+# Project-Specific Styling Addendum (if exists)
+cat docs/Styling-Addendum.md 2>/dev/null || \
+cat docs/styling-addendum.md 2>/dev/null
+```
+
+### 2. Check for UI Mockups & Design System
+
+```bash
+# List available mockups (the source of truth for UI implementation)
+ls docs/mockups/ 2>/dev/null || ls docs/design/mockups/ 2>/dev/null
+
+# Check for design system HTML (generated by /init_vibecode_design)
+ls docs/design/design-system.html 2>/dev/null || \
+ls docs/design-system.html 2>/dev/null
+```
+
+> [!IMPORTANT]
+> **If mockups exist**, they are the **UNQUESTIONABLE source of truth** for UI.
+> Before implementing any page, check if a mockup exists at:
+> - `docs/mockups/[page-name].html`
+> - `docs/design/mockups/[page-name].html`
+> 
+> Replicate the mockup's layout, colors, and components exactly.
+
+> [!TIP]
+> The styling doc name varies by project. Common patterns:
+> - `docs/Styling-in-Next-and-Tailwind-v4.md`
+> - `docs/styling-guide.md`
+> - `docs/design/design-system.md`
+> - `docs/ui-guidelines.md`
+> 
+> The workflow will auto-detect any `Styling*.md` or `styling*.md` in `docs/`.
+
+### 2. Extract Key Rules
+
+**From Coding Guidelines — Internalize:**
+- **Blueprint Protocol**: Plan before code, docs in `docs/features/`
+- **200-Line Rule**: Refactor if exceeded
+- **File Structure**: Feature-sliced design (`src/features/[Name]/`)
+- **Server vs Client**: RSCs by default, `'use client'` sparingly
+- **Service Pattern**: Route Handlers = controllers, Services = business logic
+- **Validation**: Zod for all inputs
+
+**From Styling Guide — Internalize:**
+- **Tailwind v4**: CSS-first with `@theme` tokens
+- **Core Tokens**: `--color-background`, `--color-foreground`, `--color-border`, `--color-ring`
+- **Dark Mode**: `@theme .dark { }` overrides, `dark` class on `<html>`
+- **Animations**: Define in CSS with `@keyframes`, use `.animate-*` classes
+
+### 4. Acknowledge Context
+
+**After loading, state aloud:**
+
+"✅ **Agent Primed.** I have internalized:
+
+**Coding Guidelines:**
+- Blueprint Protocol: Plan → Approve → Build → Document
+- 200-line component limit
+- Feature-sliced architecture (`src/features/[Name]/`)
+- Server Components default, Client sparingly
+- Zod validation for all API inputs
+
+**Styling Rules:**
+- Tailwind v4 with `@theme` tokens
+- Core tokens: background, foreground, border, ring
+- Dark mode via `.dark` class + `@theme .dark { }`
+- Utility-first, no custom CSS unless necessary
+
+**UI Mockups:** [List any found, or 'None found']
+- Before implementing UI, I will check `docs/mockups/` for templates
+
+I will follow these rules. What would you like to build?"
+
+---
+
+## Optional: Generate Styling Addendum
+
+If the project doesn't have `docs/Styling-Addendum.md`, offer to create one:
+
+```
+"I notice there's no project-specific Styling Addendum. Would you like me to generate one?
+This will probe your repo for:
+- Design tokens in globals.css
+- Dark mode configuration
+- Animation definitions
+- File path map
+
+Reply 'yes' to generate."
+```
+
+**If user says yes, follow these steps:**
+
+1. **Probe the repository:**
+   - Find `postcss.config.*` → verify `@tailwindcss/postcss` plugin
+   - Find global CSS with `@import "tailwindcss"`
+   - Find `@theme` tokens and dark overrides
+   - List custom keyframes and animations
+
+2. **Generate `docs/Styling-Addendum.md`:**
+   ```markdown
+   # Styling Addendum – [PROJECT_NAME] (Tailwind CSS v4)
+   
+   *Based on: [docs/Styling-in-Next-and-Tailwind-v4.md](file:///path/to/file)*
+   
+   ## 1. Project Entry Points
+   - App entry: `src/app/layout.tsx`
+   - Global CSS: `src/app/globals.css`
+   
+   ## 2. Tailwind v4 Setup
+   - PostCSS: `postcss.config.mjs` with `@tailwindcss/postcss`
+   - Global CSS imports: `@import "tailwindcss"`
+   
+   ## 3. Design Tokens
+   [List all @theme tokens found]
+   
+   ## 4. Dark Mode Policy
+   [Document how dark mode works in this project]
+   
+   ## 5. Animations
+   [List custom keyframes and animation classes]
+   
+   ## 6. File Path Map
+   | Purpose | Path |
+   |---------|------|
+   | Global CSS | `src/app/globals.css` |
+   | PostCSS | `postcss.config.mjs` |
+   | Tailwind Config | `tailwind.config.ts` |
+   
+   ## 7. Gotchas
+   [Project-specific issues to watch for]
+   ```
+
+---
+
+## Quick Reference Card
+
+After priming, you can also generate a quick reference card:
+
+```markdown
+# [PROJECT_NAME] - Agent Quick Reference
+
+## File Structure
+```
+src/
+├── app/           # Next.js App Router pages
+├── features/      # Feature-sliced modules
+│   └── [Name]/    # Components, hooks, services for each feature
+├── components/    
+│   └── ui/        # Reusable UI components (Button, Card, etc.)
+├── lib/           # Utilities, API clients
+└── scripts/       # Build/automation scripts
+```
+
+## Key Commands
+- `npm run dev` — Start development
+- `npm run build` — Production build
+- `npm run db:seed` — Seed database
+
+## Style Tokens
+- `bg-background` / `text-foreground` — Base colors
+- `bg-primary` / `text-primary` — Brand colors
+- `dark:` prefix for dark mode variants
+```
+
+---
+
+## When to Use This Workflow
+
+- **Start of session**: When you want the agent fully briefed
+- **Before complex work**: When implementing features that touch styling + architecture
+- **New agent onboarding**: When switching to a fresh chat session
+- **After `/migrate`**: Supplement the migration snapshot with this priming

package/.agent/workflows/reverse_genesis.md

@@ -0,0 +1,132 @@
+---
+description: Onboard an AI to an existing codebase by generating an "Autopsy Report".
+---
+# Workflow: Reverse Genesis (Codebase Onboarding)
+
+**System Instruction:**
+This workflow is the OPPOSITE of `/init_vibecode_genesis`.
+Instead of planning a NEW project, you are **onboarding to an EXISTING codebase**.
+
+Your job is to generate a **Project Autopsy Report** — a comprehensive analysis of the current state of the code.
+
+---
+
+## Steps
+
+### 1. Reconnaissance (Auto-Scan)
+
+**A. Project Overview:**
+```bash
+cat README.md 2>/dev/null || echo "No README found"
+cat docs/Project_Requirements.md 2>/dev/null || echo "No PRD found"
+```
+
+**B. Tech Stack Detection:**
+```bash
+# Node/JS
+cat package.json 2>/dev/null | head -50
+# Python
+cat requirements.txt 2>/dev/null || cat pyproject.toml 2>/dev/null
+# Rust
+cat Cargo.toml 2>/dev/null
+```
+
+**C. Architecture Scan:**
+```bash
+# List top-level structure
+ls -la
+# List source structure
+find src -type f -name "*.ts" -o -name "*.py" -o -name "*.rs" 2>/dev/null | head -30
+```
+
+**D. Database Schema (if applicable):**
+```bash
+cat prisma/schema.prisma 2>/dev/null | head -100
+```
+
+**E. Recent Activity:**
+```bash
+git log --oneline -10
+```
+
+### 2. Generate Autopsy Report
+Create `docs/autopsy_report.md` with the following:
+
+```markdown
+# Project Autopsy Report
+
+**Generated:** [Current Date/Time]
+**Purpose:** Onboard a new AI Orchestrator to this existing codebase.
+
+---
+
+## 1. Project Elevator Pitch
+[One-sentence purpose of this application]
+
+## 2. Core Technology Stack
+| Category | Technology |
+| :--- | :--- |
+| Language | TypeScript / Python / etc. |
+| Framework | Next.js / FastAPI / etc. |
+| Database | PostgreSQL / SQLite / etc. |
+| Key Libraries | [List major dependencies] |
+
+## 3. Inferred Architecture
+[Describe the architectural pattern observed]
+- e.g., "Next.js App Router with Feature-Sliced Design"
+- e.g., "Modular Python with central event bus"
+
+## 4. Key Modules & Responsibilities
+| File/Module | Responsibility |
+| :--- | :--- |
+| `src/app/` | Next.js pages and routes |
+| `src/features/` | Domain-specific logic |
+| `src/lib/` | Shared utilities |
+
+## 5. Inferred Coding Conventions
+- **Naming:** snake_case / PascalCase / camelCase
+- **Components:** Server Components by default
+- **Validation:** Zod for all inputs
+- **Styling:** Tailwind CSS utility-first
+
+## 6. Entry Points
+- Main: `src/app/page.tsx` or `main.py`
+- API: `src/app/api/`
+
+## 7. Current State
+**Recent Commits:**
+[List from git log]
+
+**Open Issues:**
+[List from gh issue list]
+
+---
+
+## MISSION BRIEFING (For Orchestrator)
+
+You have now assimilated this codebase.
+
+**Your Directive:**
+1. Acknowledge you understand the existing architecture.
+2. Adopt the project's coding conventions.
+3. Ask the user: "What would you like to build or fix?"
+```
+
+### 3. Full File Embedding (Optional)
+If the project is complex, embed key files directly:
+- `src/lib/utils.ts`
+- Main config files
+- Core business logic
+
+### 4. Confirmation
+Tell the user:
+"🔬 **Autopsy Report Generated.**
+Saved to: `docs/autopsy_report.md`
+
+This report contains:
+- Tech stack analysis
+- Architecture breakdown
+- Coding conventions
+- Current state
+
+To onboard a new AI, paste this report into the new session."

package/.agent/workflows/review_code.md

@@ -0,0 +1,133 @@
+---
+description: Run the J-Star Code Reviewer loop to analyze and fix code quality issues.
+---
+
+# J-Star Code Review Workflow
+
+This workflow executes the J-Star Reviewer on staged changes, allowing the agent to iteratively fix issues.
+
+## 1. Build the Brain (Required once)
+If you haven't indexed the project yet, or if major files have changed, run:
+// turbo
+```bash
+jstar init
+```
+
+## 2. Stage Current Changes
+Ensure all recent changes are staged so the reviewer can see them.
+// turbo
+```bash
+git add .
+```
+
+## 3. Run Reviewer
+Execute the review pipeline.
+
+### Standard Review (Staged Changes)
+```bash
+jstar review
+```
+*Use this when changes are staged but not yet committed.*
+
+### Retroactive Review (Oops Mode)
+If you already committed changes but forgot to review:
+```bash
+jstar review --last
+```
+*Equivalent to checking the last commit `HEAD~1..HEAD`.*
+
+### Branch/PR Review
+If working on a feature branch, check against main:
+```bash
+jstar review --pr
+```
+*Equivalent to `git diff main...HEAD`. Use this for full feature verification.*
+
+## 4. Analyze and Fix
+**Agent Instructions:**
+1.  **Read the Output**: Check `.jstar/last-review.md` or the console summary.
+2.  **Prioritize**: Focus *only* on **P0_CRITICAL** and **P1_HIGH** issues first.
+3.  **Looping Strategy**:
+    - **IF** P0/P1 issues are found:
+        - Apply fixes to the code.
+        - Stage changes: `git add .`
+        - (Optional) Re-index if you added new files: `jstar init`
+        - Restart this workflow (Stage -> Review).
+    - **IF** only P2_MEDIUM issues remain:
+        - You may fix them if they are quick/obvious.
+        - Otherwise, consider the code "Good Enough" and stop.
+    - **MAX LOOPS**: 3. Do not run this cycle more than 3 times. If issues persist, stop and ask the user.
+
+## 5. Handling False Positives (Debate Mode)
+
+If the reviewer flags correct code as an issue (e.g., security false positives), use **Headless Chat** to resolve it.
+
+**Protocol:**
+1. **Start Session:**
+   Use the `run_command` tool to start the background process:
+   ```bash
+   jstar chat --headless
+   ```
+   *Note: Capture the `CommandId` returned by this tool.*
+
+2. **List Issues (Get IDs):**
+   Use `send_command_input` with the `CommandId`:
+   ```json
+   {"action": "list"}
+   ```
+   *Wait for output. Identify the numeric `id` of the issue you want to challenge.*
+
+3. **Debate:**
+   Use `send_command_input` to explain why it's a false positive:
+   ```json
+   {"action": "debate", "issueId": 0, "argument": "This is correct because..."}
+   ```
+   *Use the integer `id` from step 2.*
+
+4. **Verify Result:**
+   Check the output for `"status": "resolved"` and `"verdict": "LGTM"`.
+
+5. **Exit:**
+   Terminate the session cleanly:
+   ```json
+   {"action": "exit"}
+   ```
+
+---
+
+## AI Agent Mode (Headless)
+
+For programmatic interaction without TUI navigation, use headless mode.
+
+### JSON Review (One-Shot)
+Get findings as JSON for parsing:
+// turbo
+```bash
+jstar review --json > .jstar/report.json
+```
+
+### Headless Chat (Interactive Protocol)
+For debating specific issues via stdin/stdout:
+```bash
+echo '{"action": "list"}' | jstar chat --headless
+```
+
+**Commands:**
+| Action | Parameters | Description |
+|--------|------------|-------------|
+| `list` | — | List all current issues |
+| `debate` | `issueId`, `argument` | Challenge an issue |
+| `ignore` | `issueId` | Mark issue as ignored |
+| `exit` | — | End session, get final report |
+
+See [Headless Mode Docs](../docs/features/headless-mode.md) for full protocol.
+
+### AI Fix Cycle
+```
+1. jstar review --json  →  Parse findings
+2. Apply code fixes
+3. git add .            →  Stage changes
+4. jstar init           →  Update brain (if new files added)
+5. jstar review --json  →  Verify fixes
+6. Repeat until P0/P1 = 0
+```