vibesuite 1.0.0

package/.agent/skills/agent-recovery/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: agent-recovery
+description: Recovery protocols when agent is stuck—escalate to new agent, migrate context to new session, or reset mid-conversation.
+---
+
+# Agent Recovery Skill
+
+Protocols for when the agent is stuck, context is degraded, or session needs migration.
+
+## When to Use
+- Agent is making repeated mistakes
+- Long conversation causing hallucinations
+- Need to hand off to fresh agent
+- Context window is full
+
+---
+
+## Option 1: Escalate (Handoff Report)
+
+**Use when**: Agent is stuck and can't solve the problem.
+
+### Steps
+
+1. **Undo broken changes**:
+```bash
+git status
+git checkout -- .
+```
+
+2. **Generate `docs/escalation_report.md`**:
+
+```markdown
+# Escalation Handoff Report
+
+**Generated:** [Date/Time]
+**Original Issue:** [GitHub Issue # or description]
+
+## PART 1: THE DAMAGE REPORT
+
+### 1.1 Original Goal
+[The task you were asked to complete]
+
+### 1.2 Observed Failure
+[EXACT error message]
+
+### 1.3 Failed Approach
+[Strategy you attempted]
+
+### 1.4 Key Files Involved
+- `path/to/file1.ts`
+
+### 1.5 Best-Guess Diagnosis
+[Why approach failed]
+
+## PART 2: FULL FILE CONTENTS
+[EMBED entire content of each file]
+
+## PART 3: DIRECTIVE FOR ORCHESTRATOR
+1. Analyze the failure
+2. Formulate a new plan
+3. Execute or hand off
+```
+
+3. **Open new session** and paste the report content.
+
+---
+
+## Option 2: Migrate (Context Snapshot)
+
+**Use when**: Chat is stale, need fresh session with same context.
+
+### Auto-Detect Context
+```bash
+cat docs/Project_Requirements.md 2>/dev/null
+git log --oneline -20
+gh issue list --state open --limit 10 --json number,title
+cat docs/Coding_Guidelines.md 2>/dev/null
+```
+
+### Generate `docs/migration_snapshot.md`:
+
+```markdown
+# State Snapshot Handoff Prompt
+
+## To the New AI: Adopt This Identity
+You are the **VibeCode Project Orchestrator**...
+
+## Project Details
+- **Name:** [from PRD]
+- **Stack:** [from PRD]
+
+## Milestones
+[From git log]
+
+## Current Status
+- In Progress: [from GitHub]
+- Next: [from roadmap]
+
+## Key Files
+- `docs/Project_Requirements.md`
+- `docs/Coding_Guidelines.md`
+
+## First Action
+Read files above, then ask: "What would you like to work on next?"
+```
+
+---
+
+## Option 3: Reset (Mid-Conversation)
+
+**Use when**: Agent is making mistakes but can recover.
+
+### 🛑 HARD STOP 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 exist in scope?
+□ Did I check props are destructured in function signature?
+```
+
+### Common Mistakes
+| Pattern | Fix |
+|---------|-----|
+| Duplicate lines | Read file first, count declarations |
+| Missing destructuring | Check props signature |
+| Broken JSX | Close tags in same edit |
+| Phantom variables | grep in file before using |
+| Edit offset drift | Re-read file after each edit |
+
+### File Edit Protocol
+1. `view_file_outline` → Understand structure
+2. `view_file` (exact range) → Copy PRECISE content
+3. Make edit with MINIMAL scope
+4. Re-check file before next edit
+
+### Verified Completion
+Before saying "done":
+```bash
+npx tsc --noEmit  # MUST pass
+```
+- No duplicate declarations?
+- No missing imports?
+- Task actually solved?
+
+**If errors persist after 3 fix attempts → use Escalate.**

package/.agent/skills/code-review/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: code-review
+description: Run J-Star code review on staged changes. Analyze, fix P0/P1 issues, and iterate until clean.
+---
+
+# Code Review Skill
+
+Run the J-Star Reviewer on staged changes, allowing iterative fixing of issues.
+
+## When to Use
+- Before committing code changes
+- When code quality issues are mentioned
+- As a quality gate before merging
+- When user asks to "review this code"
+
+## Quick Start
+
+### 1. Build the Brain (First Time Only)
+```bash
+jstar init
+```
+
+### 2. Stage Changes
+```bash
+git add .
+```
+
+### 3. Run Review
+```bash
+# Standard review (staged changes)
+jstar review
+
+# Retroactive (already committed)
+jstar review --last
+
+# Branch/PR review (against main)
+jstar review --pr
+```
+
+## Fix Loop Protocol
+
+1. **Read Output**: Check `.jstar/last-review.md` or console
+2. **Prioritize**: Focus on **P0_CRITICAL** and **P1_HIGH** only
+3. **Loop Strategy**:
+   - If P0/P1 found → Fix → Stage → Re-review
+   - If only P2_MEDIUM → Consider "Good Enough"
+   - **MAX LOOPS: 3** — If issues persist, stop and ask user
+
+## Handling False Positives (Headless Mode)
+
+```bash
+# Start headless session
+jstar chat --headless
+
+# List issues
+echo '{"action": "list"}' | jstar chat --headless
+
+# Debate an issue
+echo '{"action": "debate", "issueId": 0, "argument": "This is correct because..."}' | jstar chat --headless
+
+# Exit
+echo '{"action": "exit"}' | jstar chat --headless
+```
+
+## 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
+```
+
+## 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 |

package/.agent/skills/component-analysis/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: component-analysis
+description: Analyze a React/TypeScript component for compliance with coding guidelines and suggest improvements.
+---
+
+# Component Analysis Skill
+
+Analyze components for coding standards compliance and provide actionable improvements.
+
+## When to Use
+- Refactoring discussions
+- Before major component changes
+- When asked to "analyze" or "audit" a component
+- Code review of specific files
+
+## Analysis Process
+
+### 1. Identify Component
+Get from user or extract:
+- **Component Path**: Full file path
+- **Component Name**: The component name
+
+### 2. Initial Examination
+Read file and check:
+- Code structure and organization
+- Purpose and functionality
+- Immediate issues
+- **Total lines** (check 200-line rule)
+
+### 3. Coding Guidelines Check
+
+| Check | What to Look For |
+|-------|------------------|
+| **Size** | < 200 lines (refactor if exceeded) |
+| **Single Responsibility** | Does one thing well |
+| **TypeScript** | Proper types, interfaces for props |
+| **Naming** | PascalCase components, camelCase functions, handle* events |
+| **Hooks** | Proper use of React hooks and effects |
+| **Documentation** | TSDoc/JSDoc comments |
+| **Imports** | Organized, no unused imports |
+
+### 4. Styling Check
+
+| Check | What to Look For |
+|-------|------------------|
+| **Tailwind v4** | Using @theme integration |
+| **Color Tokens** | Using primary, accent, semantic tokens |
+| **Responsive** | Mobile-first (sm:, md:, lg:) |
+| **Dark Mode** | dark: variants |
+| **Performance** | Avoiding expensive backdrop-filter |
+
+### 5. Mobile-First Check
+- Mobile-first breakpoints
+- Touch-friendly interactions
+- Responsive typography
+- Container responsiveness
+
+### 6. Generate Report
+
+```markdown
+# Component Analysis: [Name]
+
+**File:** `[path]`
+**Lines:** [X] / 200 max
+**Score:** [X]/10
+
+## ✅ Compliant
+- [Things done well]
+
+## ⚠️ Warnings
+- [Minor issues]
+
+## ❌ Violations
+- [Critical issues]
+
+## 📋 Recommendations
+
+### High Priority
+1. [Critical fix]
+
+### Medium Priority
+1. [Improvement]
+
+## 🔧 Suggested Fixes
+[Before/After code examples]
+```
+
+### 7. Offer Next Steps
+- **A)** Implement high-priority fixes
+- **B)** Create feature documentation
+- **C)** Refactor if > 200 lines
+
+## Severity Levels
+- 🔴 **Critical**: Breaking functionality, security issues
+- 🟡 **Major**: Performance, accessibility violations
+- 🟢 **Minor**: Code style, documentation
+
+## Common Violations
+1. No TypeScript interface for props → Define `interface ComponentProps`
+2. useEffect missing dependencies → Add to dependency array
+3. Hardcoded colors → Use Tailwind tokens
+4. No dark mode → Add `dark:` variants
+5. Missing alt text → Add descriptive alt attributes

package/.agent/skills/git-worktree/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: git-worktree
+description: Manage git worktrees for parallel agent development. Create, sync, and remove isolated dev environments.
+---
+
+# Git Worktree Skill
+
+Manage parallel development environments without manual path juggling.
+
+## When to Use
+- Setting up parallel agents
+- Multi-agent development
+- When "worktree" is mentioned
+- Need isolated environments for different features
+
+## Status Check
+```bash
+git worktree list
+git branch --list
+```
+
+## Actions
+
+### [NEW] Create Agent Environment
+
+1. **Name the Agent**: Short identifier (e.g., `frontend-refactor`, `agent-3`)
+2. **Define Paths**:
+   - Branch: `[agent-name]`
+   - Folder: `../[repo-name]-[agent-name]`
+
+3. **Execute**:
+```bash
+git branch [branch_name]
+git worktree add [folder_path] [branch_name]
+```
+
+4. **Validate**: `git worktree list`
+
+5. **Context Migration** (ask user):
+```bash
+cp .env [worktree_path]/.env
+# If SQLite:
+mkdir -p [worktree_path]/prisma
+cp prisma/dev.db [worktree_path]/prisma/dev.db
+```
+
+6. **Initialize**: `pnpm install` in new worktree
+
+---
+
+### [SYNC] Synchronize Agents
+
+1. Ask: Sync **ALL** or **SPECIFIC** worktree?
+2. Execute:
+```bash
+git fetch origin
+cd [worktree_path]
+git merge origin/main  # or rebase
+cd -
+```
+
+---
+
+### [KILL] Teardown Agent
+
+1. Select worktree from list
+2. Execute:
+```bash
+git worktree remove [worktree_path]
+git branch -d [branch_name]  # Ask before deleting!
+git worktree prune
+```
+
+## Troubleshooting
+
+- **"already checked out"**: Use a new branch name
+- **Stale entries**: Run `git worktree prune`
+- **Files still tracked**: Directory was deleted manually—prune first

package/.agent/skills/github-ops/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: github-ops
+description: GitHub automation patterns - issues, projects, labels. Includes smart-ops scripts and bulk issue sync.
+---
+
+# GitHub Ops Skill
+
+Complete GitHub automation toolkit using the `gh` CLI. Covers issue management, project boards, label systems, and bulk operations.
+
+## When to Use
+- User mentions "GitHub issues", "project board", or "gh cli"
+- Setting up automation for a new repo
+- Bulk-creating issues from markdown specs
+- Managing GitHub Projects (v2)
+
+## Prerequisites
+
+```bash
+# Install GitHub CLI
+winget install GitHub.cli   # Windows
+brew install gh             # macOS
+
+# Authenticate
+gh auth login
+
+# Verify
+gh auth status
+```
+
+---
+
+## 1. Bulk Issue Sync (publish_issues.ps1)
+
+**Location:** `$env:USERPROFILE\.gemini\antigravity\skills\github-ops\scripts\publish_issues.ps1`
+
+> [!TIP]
+> The script auto-detects the repository from the current working directory. Just `cd` to your project folder before running.
+
+### Features
+| Feature | Description |
+|---------|-------------|
+| **Smart Sync** | Only processes files that changed since last run (uses `.issue-sync-state.json`) |
+| **Auto-Close** | Closes issue when all checkboxes (`- [x]`) are ticked |
+| **Auto-Archive** | Moves completed `.md` files to `closed/` subfolder |
+| **Natural Sort** | Processes Issue_1, Issue_2... Issue_10 (not 1, 10, 11) |
+| **Date Sync** | Sets Start/Target dates on GitHub Projects |
+
+### Required Flags
+
+| Flag | Required? | Description |
+|------|-----------|-------------|
+| (none) | - | Creates new issues only (skips existing) |
+| `-Update` | For sync | Updates existing issues |
+| `-AutoArchive` | Optional | Moves completed issues to `closed/` folder |
+| `-DryRun` | Optional | Preview mode - no changes made |
+| `-Force` | Optional | Bypass change detection, sync all files |
+
+### Project Date Sync Flags (ALL required with -SyncDates)
+
+| Flag | Description | How to Get |
+|------|-------------|------------|
+| `-SyncDates` | Enable date sync | Just add the flag |
+| `-ProjectNumber` | Project board number | `gh project list --owner USERNAME` |
+| `-ProjectId` | Project node ID | See below |
+| `-StartDateFieldId` | Start Date field ID | See below |
+| `-TargetDateFieldId` | Target Date field ID | See below |
+
+### How to Get Project IDs
+
+```powershell
+# 1. List projects to get project number
+gh project list --owner USERNAME
+
+# 2. Get field IDs (replace NUMBER with project number)
+gh project field-list NUMBER --owner USERNAME --format json
+```
+
+Look for "Start Date" and "Target Date" in the JSON output. If they don't exist:
+```bash
+gh project field-create NUMBER --owner USERNAME --name "Start Date" --data-type DATE
+gh project field-create NUMBER --owner USERNAME --name "Target Date" --data-type DATE
+```
+
+### Agent Protocol: Before Running This Script
+
+**ALWAYS ask the user:**
+
+1. "Do you want to sync to a GitHub Project with dates?" 
+   - If YES → Need all project IDs
+   - If NO → Skip `-SyncDates` flag
+
+2. "Should completed issues be archived to a `closed/` subfolder?"
+   - If YES → Add `-AutoArchive`
+
+3. "First run or update existing?"
+   - First run → No flags needed (or just `-AutoArchive`)
+   - Update → Add `-Update`
+
+**ALWAYS run with `-DryRun` first** to preview changes.
+
+### Example Commands
+
+```powershell
+# Basic: Create new issues only
+powershell -ExecutionPolicy Bypass -File ~/.gemini/antigravity/skills/github-ops/scripts/publish_issues.ps1
+
+# Dry run preview
+powershell -ExecutionPolicy Bypass -File ~/.gemini/antigravity/skills/github-ops/scripts/publish_issues.ps1 -Update -DryRun
+
+# Update + archive completed
+powershell -ExecutionPolicy Bypass -File ~/.gemini/antigravity/skills/github-ops/scripts/publish_issues.ps1 -Update -AutoArchive
+
+# Full sync with project dates
+powershell -ExecutionPolicy Bypass -File ~/.gemini/antigravity/skills/github-ops/scripts/publish_issues.ps1 `
+    -Update -AutoArchive -SyncDates `
+    -ProjectNumber 7 `
+    -ProjectId "PVT_xxx" `
+    -StartDateFieldId "PVTF_xxx" `
+    -TargetDateFieldId "PVTF_yyy"
+```
+
+---
+
+## 2. Bulk Add Issues to Project
+
+To quickly add all existing issues to a project (faster than using the sync script):
+
+```powershell
+# Get issue numbers first
+$issues = gh issue list --repo OWNER/REPO --state all --limit 500 --json number | ConvertFrom-Json
+
+# Add each to project
+$issues | ForEach-Object { 
+    gh project item-add PROJECT_NUMBER --owner OWNER --url "https://github.com/OWNER/REPO/issues/$($_.number)"
+}
+```
+
+---
+
+## 3. Quick Commands Reference
+
+| Task | Command |
+|------|---------|
+| List issues | `gh issue list` |
+| Create issue | `gh issue create --title "X" --body "Y" --label "bug"` |
+| Close issue | `gh issue close 42 --comment "Fixed"` |
+| Delete issue | `gh issue delete 42 --yes` |
+| List labels | `gh label list` |
+| Create label | `gh label create "priority:high" --color "FF0000"` |
+| List projects | `gh project list --owner OWNER` |
+| Get project fields | `gh project field-list NUMBER --owner OWNER --format json` |
+| Add to project | `gh project item-add NUMBER --owner OWNER --url ISSUE_URL` |
+
+---
+
+## 4. Supported Issue Markdown Formats
+
+### Format A: YAML Frontmatter (Recommended)
+```markdown
+---
+title: "[Feature] Clear Issue Title"
+labels: enhancement, priority-high, module-name
+---
+
+## Acceptance Criteria
+- [ ] AC1
+- [ ] AC2
+```
+
+### Format B: Bold Markdown
+```markdown
+**Title:** [Feature] Clear Issue Title
+**Labels:** `enhancement`, `priority-high`
+
+## Acceptance Criteria
+- [ ] AC1
+```
+
+### Format C: Markdown Headers
+```markdown
+## Title
+[Feature] Clear Issue Title
+
+## Labels
+`enhancement`, `priority-high`
+```
+
+---
+
+## 5. Label System Setup
+
+```bash
+# Priority
+gh label create "priority-critical" --color "b60205"
+gh label create "priority-high" --color "d93f0b"
+gh label create "priority-medium" --color "fbca04"
+gh label create "priority-low" --color "0e8a16"
+
+# Type
+gh label create "type-feature" --color "0e8a16"
+gh label create "type-bug" --color "d73a4a"
+gh label create "type-refactor" --color "a2eeef"
+
+# Scope
+gh label create "MUS" --color "5319e7" --description "Minimum Usable Scope"
+gh label create "future-scope" --color "bfdadc"
+```
+
+---
+
+## 6. Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| `gh: command not found` | CLI not installed | `winget install GitHub.cli` |
+| `authentication required` | Not logged in | `gh auth login` |
+| Quote errors in titles | Special chars | Script auto-replaces `"` with `'` |
+| "No files changed" | Already synced | Use `-Force` flag |
+| Project commands fail | Wrong IDs | Run `gh project field-list` |
+| Rate limiting | Too many API calls | Wait or use `-DryRun` |