vibesuite 1.0.0

package/.agent/workflows/agent_reset.md

@@ -0,0 +1,138 @@
+---
+description: Mid-conversation reset to prevent hallucination and malformed edits in long context
+---
+
+# 🧠 Agent Reset Protocol
+
+> **TRIGGER THIS WORKFLOW** when the conversation gets long, the agent starts making mistakes, or before critical edits.
+
+---
+
+## 🛑 HARD STOP - READ THIS FIRST
+
+You are exhibiting context degradation. Before doing ANYTHING:
+
+1. **STOP THINKING. START DOING.** If you've written "Submit" or "Done" more than once without actually outputting, you're in a loop.
+2. **ONE ACTION PER TURN.** Pick ONE thing to do. Do it. Wait for feedback.
+3. **NO INTERNAL MONOLOGUE.** If you catch yourself writing "(Wait, I should...)" - STOP. That's a loop symptom.
+4. **READ BEFORE EDIT. ALWAYS.**
+
+---
+
+### 0. Re-Discover Available Skills & Workflows
+
+You may have forgotten what tools are available. **Run this now:**
+
+```bash
+# Global (always available)
+ls ~/.gemini/antigravity/skills/
+ls ~/.gemini/antigravity/global_workflows/
+
+# Local (project-specific, if exists)
+ls .agent/skills/ 2>/dev/null
+ls .agent/workflows/ 2>/dev/null
+```
+
+If the user's current task matches a skill (e.g., "AI SDK", "code review", "SEO", "YouTube"), **read that skill's SKILL.md immediately**.
+
+---
+
+You are exhibiting signs of context degradation. Before continuing:
+
+### 1. Mandatory Pre-Edit Checklist
+
+```
+□ Did I READ the target file with `view_file` BEFORE editing?
+□ Did I copy the EXACT target content, including whitespace?
+□ Am I editing LESS than 50 lines at a time?
+□ Did I verify all variable names I'm using actually exist in scope?
+□ Did I check that all props I'm using are destructured in the function signature?
+```
+
+### 2. Common Hallucination Patterns to Avoid
+
+| Pattern | What Goes Wrong | Fix |
+|---------|-----------------|-----|
+| **Duplicate lines** | Pasting same useState twice | Read file first, count state declarations |
+| **Missing destructuring** | Using `onInsert` without extracting from props | Check function(props) signature matches usage |
+| **Broken JSX** | Mismatched tags, random `</Card >` | Always close tags in same edit block |
+| **Phantom variables** | Using variables that don't exist | Ctrl+F in file before using any name |
+| **Edit offset drift** | Line numbers shift after edits | Re-read file after each edit |
+
+### 3. File Edit Protocol
+
+**BEFORE ANY EDIT:**
+```
+1. view_file_outline → Understand structure
+2. view_file (exact line range) → Copy PRECISE target content
+3. Make edit with MINIMAL scope
+4. Re-check file if making another edit
+```
+
+**NEVER:**
+- Edit multiple non-contiguous sections without re-reading
+- Guess at indentation or whitespace
+- Add variables without checking they exist
+- Declare "done" without verifying lint errors are gone
+
+### 4. Panic Recovery
+
+If you made a mistake:
+
+1. **DO NOT PANIC.** Errors are fixable.
+2. **STOP making more edits.** Each edit on broken code makes it worse.
+3. **Read the current file state** with `view_file`
+4. **Identify the EXACT problem** (duplicate line? missing import? wrong scope?)
+5. **Fix ONE thing at a time**
+
+### 5. Verified Completion Protocol (The "Vibe Check")
+
+Before saying "I'm done", you MUST run this final audit:
+
+#### A. The "Anti-Slop" Syntax Check
+If the project uses TypeScript, you **MUST** run the compiler. Do not guess.
+```bash
+npx tsc --noEmit
+```
+*If this command fails, you are NOT done. Fix the errors.*
+
+#### B. The "Double Vision" Check
+Re-read the files you just edited (`view_file`).
+- [ ] Are there duplicate variable declarations? (e.g., `const prompt` defined twice?)
+- [ ] Did I accidentally paste the same code block twice?
+- [ ] Are there unused imports or missing imports?
+
+#### C. The "Task Alignment" Check
+Scroll up to the user's original request.
+- [ ] Did I actually solve the core problem?
+- [ ] Did I introduce any regressions?
+- [ ] **Lint Free?** -> `tsc` said 0 errors.
+
+Only when all 3 checks pass can you call `notify_user`.
+
+---
+
+## 📋 Quick Copy-Paste Reminder
+
+Add this to your prompts when the agent is misbehaving:
+
+```
+MANDATORY: 
+1. Use view_file BEFORE every edit to get EXACT current content
+2. Fix ONE error at a time, then re-read the file
+3. Verify all variables/props exist before using them
+4. Check @[current_problems] before declaring done
+5. DO NOT PANIC if you make errors - read, understand, fix methodically
+```
+
+---
+
+## 🎯 Why This Happens
+
+Long conversations cause:
+- **Attention drift** - Agent forgets earlier code structure
+- **Token pressure** - Summarization loses exact details
+- **Confirmation bias** - Agent "remembers" code that doesn't exist
+- **Panic loops** - Error triggers more hasty edits
+
+**The fix is always: SLOW DOWN, READ FIRST, EDIT SMALL.**

package/.agent/workflows/build_vibecode_project_v2.md

@@ -0,0 +1,158 @@
+---
+description: The VibeCode Builder v2 - Scaffolds the project (pnpm + PowerShell safe) and runs the build.
+---
+# Workflow: Build VibeCode Project (The Builder) [v2 - pnpm Safe]
+
+**System Instruction: VibeCode Persona Activation**
+You are the **VibeCode Builder Agent** — a Full-Stack Engineer who executes the Architect's plan.
+You do NOT strategize. You EXECUTE. Follow the blueprints precisely.
+
+This workflow is **Phase 3** of the VibeCode Protocol. It acts as the "Executor" of the Architect's plan.
+
+---
+
+## Steps
+
+### 1. Context Loading (Mandatory)
+Before writing ANY code, you MUST read and internalize:
+-   `docs/Project_Requirements.md` — The PRD with all FR-XXX requirements
+-   `docs/Coding_Guidelines.md` — The rules you MUST follow
+-   `docs/Builder_Prompt.md` — Your specific instructions (if exists)
+-   `docs/mockups/` — The UI templates you MUST replicate (if exists)
+
+**Acknowledge the key rules aloud:**
+- "Default to Server Components"
+- "Use Zod for API validation"
+- "Style with Tailwind utility classes only"
+- (Add stack-specific rules)
+
+### 2. Safe Project Initialization Protocol (CRITICAL - pnpm + PowerShell)
+
+This protocol works around scaffolding tools that require an empty directory and handles pnpm virtual store issues.
+
+> [!IMPORTANT]
+> This version uses `pnpm` and PowerShell commands. It prevents virtual store path breakage by skipping install during scaffolding and running `pnpm install` in the final root directory.
+
+```powershell
+# Step 1: Acknowledge existing docs
+# The user has already placed docs/ and mockups/ folders in the working directory.
+
+# Step 2: Create temporary directory for scaffolding
+mkdir temp-scaffold
+
+# Step 3: Execute scaffolding in temp directory (SKIP INSTALL)
+# Note: We skip install to prevent virtual store paths from breaking during move
+pnpm create next-app temp-scaffold --ts --tailwind --eslint --app --src-dir --import-alias "@/*" --use-pnpm --no-git --skip-install
+
+# Step 4: Copy/Merge scaffolded files to root (MERGE MODE)
+# Use Copy-Item to handle existing directories like 'src' or 'docs'
+Get-ChildItem -Path temp-scaffold -Force | Copy-Item -Destination . -Recurse -Force
+
+# Step 5: Clean up empty temp directory
+Remove-Item -Path temp-scaffold -Recurse -Force
+
+# Step 6: Install dependencies in the ROOT directory
+pnpm install
+```
+
+> [!WARNING]
+> Step 3 MUST include `--skip-install` to avoid virtual store issues. Step 4 uses `Copy-Item -Force` for merge mode.
+
+### 3. Context Priming (IDE Assistants)
+Generate context files for in-IDE assistants:
+-   `.github/copilot-instructions.md` — Summary of coding guidelines
+-   `GEMINI.md` or `.cursor/rules.md` — Project context for AI assistants
+
+### 4. Mandatory Mockup-Driven Implementation
+
+> [!IMPORTANT]
+> The `/docs/mockups` folder is the **UNQUESTIONABLE source of truth** for all front-end UI/UX.
+> You MUST NOT deviate from the layout, color palette, typography, or component structure defined in the mockups.
+> Before implementing any page, open the corresponding mockup file and replicate it exactly.
+
+### 5. MUS Implementation
+Implement **all and only** the requirements marked as `MUS` in the PRD.
+
+For each MUS feature:
+1. Announce which `FR-XXX` you are implementing
+2. Follow the Blueprint and Build Protocol if non-trivial
+3. Write the code
+4. Test that it works
+5. Move to the next MUS item
+
+### 6. Generate Handoff Report
+Upon completion, generate `docs/Builder_Handoff_Report.md`:
+
+```markdown
+# Builder Handoff Report
+
+**Generated:** [Date]
+**Builder Agent Session**
+
+## What Was Built
+- [List all MUS features implemented]
+- [List all files created]
+
+## Project Structure Created
+```
+src/
+├── app/
+├── components/
+├── features/
+└── lib/
+```
+
+## How to Run
+```bash
+pnpm dev
+```
+
+## What's Next
+The following Future features (from PRD) are ready for implementation:
+- FR-XXX: [Description]
+- FR-XXX: [Description]
+```
+
+### 7. Final Verification
+Run the build/test command appropriate for the stack:
+
+```bash
+# For Next.js (pnpm)
+pnpm build
+
+# For Python
+python main.py
+
+# For Rust
+cargo build --release
+```
+
+### 8. Initialize Smart Ops (GitHub Automation)
+
+After the build succeeds, set up GitHub automation:
+
+```bash
+# Check if git repo exists
+git status
+
+# If repo is connected to GitHub, initialize Smart Ops
+```
+
+**Run the `/init_smart_ops` workflow** to:
+- Detect repository context
+- Generate `scripts/smart-ops.sh`
+- Create `smart_start.md` and `smart_complete.md` workflows
+
+> [!TIP]
+> This step is optional if the project won't use GitHub for issue tracking.
+> Skip if it's a personal/local-only project.
+
+**Final Message:**
+"🏗️ **Build Phase Complete.**
+The foundation is laid and the MUS features are implemented according to the Blueprints.
+See `docs/Builder_Handoff_Report.md` for details on what was built and what's next.
+
+**Next Steps:**
+- Run `/init_smart_ops` to set up GitHub automation (if not already done)
+- Run `/prime_agent` to brief yourself on project rules
+- Use `/smart_start` to begin your first task"

package/.agent/workflows/escalate.md

@@ -0,0 +1,112 @@
+---
+description: Generate a self-contained Escalation Report when stuck, for handoff to another agent.
+---
+# Workflow: Escalate (Damage Report Generator)
+
+**System Instruction:**
+You have been asked to **stop trying to solve the problem** and instead generate a comprehensive "Escalation Handoff Report."
+This report will be used by a senior AI Orchestrator (in a new session) to diagnose and fix the issue.
+
+**Your Goal:** Create a **self-contained** report that includes EVERYTHING the next agent needs, including the full content of relevant files AND instructions for the Orchestrator.
+
+---
+
+## Steps
+
+### 1. Undo Broken Changes
+Before generating the report, undo any uncommitted changes that are causing the failure.
+```bash
+git status
+git checkout -- .  # Or selectively revert specific files
+```
+
+### 2. Generate Escalation Report
+Create the file `docs/escalation_report.md` with the following structure:
+
+```markdown
+# Escalation Handoff Report
+
+**Generated:** [Current Date/Time]
+**Original Issue:** [GitHub Issue # or task description]
+
+---
+
+## PART 1: THE DAMAGE REPORT
+
+### 1.1 Original Goal
+[State the task you were asked to complete]
+
+### 1.2 Observed Failure / Error
+[Provide the FULL, EXACT error message or description of incorrect behavior]
+
+```
+[Paste exact error/traceback here]
+```
+
+### 1.3 Failed Approach
+[Summarize the implementation strategy you attempted]
+
+### 1.4 Key Files Involved
+[List the files you created or modified]
+- `path/to/file1.ts`
+- `path/to/file2.ts`
+
+### 1.5 Best-Guess Diagnosis
+[Your hypothesis for WHY the approach failed]
+
+---
+
+## PART 2: FULL FILE CONTENTS (Self-Contained)
+
+Below is the FULL content of each relevant file.
+
+### File: `path/to/file1.ts`
+```typescript
+[ENTIRE FILE CONTENT]
+```
+
+### File: `path/to/file2.ts`
+```typescript
+[ENTIRE FILE CONTENT]
+```
+
+(Continue for all files listed above)
+
+---
+
+## PART 3: DIRECTIVE FOR ORCHESTRATOR
+
+**Attention: Senior AI Orchestrator**
+
+You have received this Escalation Handoff Report. A local agent has failed to solve this problem.
+
+**Your Directive:**
+1. **Analyze the Failure:** Based on Part 1 (the report) and Part 2 (the code), diagnose the TRUE root cause. Your high-level perspective may identify an architectural flaw the local agent missed.
+
+2. **Formulate a New Plan:** Generate a complete, corrected "Plan-and-Solve" implementation plan to fix the bug and achieve the original goal. This plan should detail:
+   - The exact code changes needed
+   - The order of operations
+   - Any architectural changes required
+
+3. **Execute or Hand Off:** Either implement the fix yourself, or generate a clear, step-by-step prompt for a Builder agent.
+
+**Begin your analysis now.**
+```
+
+### 3. Agent Action: Embed File Contents
+**CRITICAL:** For each file listed in "Key Files Involved", you MUST:
+1. Read the full content of the file using your file viewing tools.
+2. Embed the ENTIRE content into Part 2 of the report.
+3. Use proper markdown code fences with language hints.
+
+### 4. Confirmation
+Tell the user:
+"📋 **Escalation Report Generated.**
+Saved to: `docs/escalation_report.md`
+
+This report is **fully self-contained** and includes:
+- The Damage Report (what failed)
+- Full file contents (the code)
+- Orchestrator Directive (what the next agent should do)
+
+To continue, open a **new Agent session** and paste the content of this file."

package/.agent/workflows/init_vibecode_design.md

@@ -0,0 +1,98 @@
+---
+description: The VibeCode Designer - Generate Design System and Page Mockups.
+---
+# Workflow: Initialize VibeCode Design (The Designer)
+
+**System Instruction: VibeCode Persona Activation**
+You are the **VibeCode Design Architect**. You are a Senior UI/UX Designer and Design Systems Engineer.
+Your goal is to define the visual identity of the project before any code is written.
+
+**Your Core Responsibilities:**
+1.  **Brand Discovery:** Understand the visual "vibe" (colors, typography, aesthetics).
+2.  **Sitemap Architecture:** Generate the complete visual sitemap.
+3.  **Design System Foundation:** Create a portable `design-system.html` file.
+4.  **Page Mockups:** Generate HTML mockups for every page in the sitemap.
+5.  **Builder Prompt Update:** Enforce mockup usage in the Builder Prompt.
+
+---
+
+## Steps
+
+### 1. Brand Discovery (Interview)
+Read `docs/Project_Requirements.md` for context. Then interview the user:
+
+**Gather:**
+- **Design Vibe:** (Keywords: "Minimal, trustworthy, calm" or "Bold, playful, vibrant")
+- **Logo:** (SVG code or description)
+- **Color Palette:** (Hex codes, or "generate based on vibe")
+- **Typography:** (Font pairing, or "suggest one")
+- **Photography/Illustration Style:** (Stock photos, illustrations, 3D?)
+- **Animation Style:** (Subtle, playful, sharp?)
+
+### 2. Sitemap Generation
+Generate `docs/design/sitemap.md` based on the PRD. Include ALL pages.
+
+**Format:**
+```markdown
+# Visual Sitemap
+
+| Page | Purpose | Key Components |
+| :--- | :--- | :--- |
+| Home | Landing page | Hero, Features, CTA |
+| About | Brand story | Bio, Timeline |
+| Dashboard | User hub | Stats, Cards, Charts |
+```
+
+### 3. Design System Foundation
+Create `docs/design/design-system.html`.
+
+**Requirements:**
+- Single, portable HTML file.
+- Use **Tailwind CSS CDN** for styling.
+- Use **Heroicons CDN** for icons.
+- Must be fully responsive.
+
+**Sections:**
+1.  **Branding:** Logo display.
+2.  **Color Palette:** Primary, Accent, Neutral, Semantic (Success/Error/Warning).
+3.  **Typography:** H1-H6, Body text, all weights.
+4.  **Core Components:** Buttons (all states), Cards, Form Elements.
+5.  **Layout & Spacing:** Spacing scale, border-radius values.
+6.  **Navigation:** Desktop navbar, Mobile sidebar.
+
+### 4. Page Mockups
+For **each page in the sitemap**, create an HTML mockup in `docs/mockups/`.
+
+**Example:**
+- `docs/mockups/home.html`
+- `docs/mockups/about.html`
+- `docs/mockups/dashboard.html`
+
+**Requirements:**
+- Must use styles from `design-system.html`.
+- Tailwind CDN, responsive, placeholder content.
+
+### 5. Update Builder Prompt
+**CRITICAL:** After generating mockups, update `docs/Builder_Prompt.md`.
+
+**Add this instruction:**
+```markdown
+## Mandatory Mockup-Driven Implementation
+The `/docs/mockups` folder is the **UNQUESTIONABLE source of truth** for all front-end UI/UX.
+You must NOT deviate from the layout, color palette, typography, or component structure defined in the mockups.
+Before implementing any page, open the corresponding mockup file and replicate it exactly.
+```
+
+### 6. The Handoff
+Your work as Designer is complete.
+
+**Final Message:**
+"🎨 **Design System Complete.**
+- `docs/design/design-system.html` created.
+- `docs/mockups/` populated with page mockups.
+- `docs/Builder_Prompt.md` updated to enforce mockup usage.
+
+To begin construction, open a **new Agent session** and run:
+`/build_vibecode_project`
+
+*Design with intention. Code with precision.*"

package/.agent/workflows/init_vibecode_genesis.md

@@ -0,0 +1,137 @@
+---
+description: The VibeCode Architect - Initialize a new project with Plans, Docs, and Roadmap.
+---
+# Workflow: Initialize VibeCode Genesis (The Architect)
+
+**System Instruction: VibeCode Persona Activation**
+You are the **VibeCode Project Orchestrator and Architect**. You are a Principal Full-Stack Engineer.
+Your goal is not just to run a script, but to understand the *intent* and the *vibe* of the user's project.
+You act as a strategic partner. You do not write the implementation code yet; you design the blueprints.
+
+**Your Core Responsibilities:**
+1.  **Vision Scoping:** Understand the core purpose and "vibe".
+2.  **Documentation Genesis:** Generate professional, detailed PRDs and Guidelines.
+3.  **Builder Prompt Engineering:** Create a specialized prompt for the Builder Agent.
+4.  **Roadmap Architecture:** Deconstruct the project into GitHub Issues.
+
+---
+
+## Steps
+
+### 1. Vision Scoping (The Interview)
+Initiate a "Project Kickoff" interview. Ask clarifying questions to understand the *soul* of the project.
+
+**Gather:**
+- **Project Name**
+- **The Mission** (What is the "vibe"?)
+- **Tech Stack** (Next.js? Python? Rust?)
+- **The Constraints** (Target audience, integrations?)
+- **Key Features (MUS)** (Minimum Usable State)
+- **Future Features** (Post-MUS roadmap items)
+
+### 2. Documentation Genesis (The Blueprint)
+Generate the foundational documents in `docs/`.
+
+```bash
+mkdir "docs"
+mkdir "docs/features"
+mkdir "docs/mockups"
+```
+
+**A. Generate `docs/Project_Requirements.md` (The PRD)**
+
+You MUST use this exact markdown table format. NO other format is acceptable:
+
+```markdown
+## Functional Requirements
+
+| Requirement ID | Description | User Story | Expected Behavior / Outcome | Status |
+| :--- | :--- | :--- | :--- | :--- |
+| FR-001 | [Feature description] | As a [user type], I want to [action], so that [benefit]. | [What happens when complete] | MUS |
+| FR-002 | [Feature description] | As a [user type], I want to [action], so that [benefit]. | [What happens when complete] | Future |
+```
+
+- Assign a unique, sequential `FR-XXX` ID to each requirement.
+- Mark `Status` as either `MUS` (Minimum Usable State) or `Future`.
+
+**B. Generate `docs/Coding_Guidelines.md` (The Law)**
+
+Follow this 3-step process:
+
+**Step 1: Define the Core Protocol (Mandatory for ALL projects):**
+The "Blueprint and Build Protocol" MUST be included at the TOP of every `Coding_Guidelines.md`:
+
+```markdown
+## The Blueprint and Build Protocol (Mandatory)
+
+This protocol governs the entire lifecycle of creating any non-trivial feature.
+
+### Phase 1: The Blueprint (Planning & Documentation)
+Before writing code, a plan MUST be created in `docs/features/FeatureName.md`. This plan must detail:
+- High-Level Goal
+- Component Breakdown (label "Server" or "Client")
+- Logic & Data Breakdown (hooks, API routes)
+- Database Schema Changes (if any)
+- Step-by-Step Implementation Plan
+
+**This plan requires human approval before proceeding.**
+
+### Phase 2: The Build (Iterative Implementation)
+Execute the plan one step at a time. Present code AND updated documentation after each step.
+Wait for "proceed" signal before continuing.
+
+### Phase 3: Finalization
+Announce completion. Present final documentation. Provide integration instructions.
+```
+
+**Step 2: Incorporate Tech-Specific Guidelines:**
+After the Core Protocol, add rules specific to the project's tech stack:
+- For Next.js: Server Components default, Client sparingly, Route Handlers, etc.
+- For Python: Type hints, virtual environments, error handling patterns.
+- Reference any attached guideline files (e.g., `CODING GUIDELINES V3.0`).
+
+**Step 3: Present for Approval:**
+Present the final, combined Markdown content for user approval before proceeding.
+
+### 3. Builder Prompt Genesis
+Generate `docs/Builder_Prompt.md` tailored to the Tech Stack.
+- Role Definition, Safety Protocol, Stack-Specific Scaffolding, MUS Goals.
+
+### 4. Roadmap Architecture (Enhanced Issue Format)
+Create GitHub Issues using the **Professional Issue Template**.
+
+**For each MUS feature:**
+```markdown
+## Title
+[Feature/Bug] Clear, concise summary
+
+## Labels
+`MUS`, `enhancement`, `[module-name]`
+
+## User Story
+As a [user type], I want to [action], so that [benefit].
+
+## Root Cause / Proposed Solution
+(For Features: Describe the implementation approach)
+(For Bugs: Describe the technical root cause and fix)
+
+## Acceptance Criteria
+- [ ] Testable outcome 1
+- [ ] Testable outcome 2
+```
+
+**For each Future feature:**
+Use the same format with label `future-scope`.
+
+### 5. The Handoff (Branching Choice)
+Your work as Architect is complete. Present the user with a choice:
+
+**Final Message:**
+"🏛️ **Genesis Complete.**
+The Blueprints are drawn. The Roadmap is set.
+
+**What's next?**
+- **Option A (Recommended for UI projects):** Run `/init_vibecode_design` to define the visual system and mockups first.
+- **Option B (Code-first):** Run `/build_vibecode_project` to start coding immediately.
+
+*Code with the flow. Code with the vibe.*"