takomi 2.0.4

package/assets/.agent/workflows/README.md

@@ -0,0 +1,537 @@
+---
+description: A Detailed Explanation of what the vibe code protocol is
+---
+
+# VibeCode Workflow Guide
+
+This document explains how all workflows in `.agent/workflows/` relate to each other, which ones are "parent" workflows, the recommended order of operations, and the relationship between **workflows** and **skills**.
+
+---
+
+## 📦 Workflows vs Skills
+
+Understanding the difference:
+
+| Type | Location | Invocation | Purpose |
+|------|----------|------------|---------|
+| **Workflow** | `.agent/workflows/*.md` | `/workflow-name` (slash command) | Step-by-step procedures the agent follows |
+| **Skill** | `.agent/skills/*/SKILL.md` | Auto-loaded by context | Reusable protocols with scripts/templates |
+
+**Why migrate to a skill?**
+- Skills can include **scripts**, **templates**, and **resources**
+- Skills are **portable** across projects (can be installed globally via `uipro`)
+- Skills are **auto-loaded** when relevant context is detected
+
+---
+
+## Workflow Hierarchy
+
+```
+┌──────────────────────────────────────────────────────────────────────────────┐
+│                         PROJECT LIFECYCLE (V3)                                │
+├──────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│  NEW PROJECT                         EXISTING PROJECT                        │
+│       │                                    │                                 │
+│       ▼                                    ▼                                 │
+│  ╔═══════════════════════╗          /reverse_genesis                         │
+│  ║ /init_vibecode_       ║                │                                  │
+│  ║     genesis_v3        ║                │                                  │
+│  ║                       ║                │                                  │
+│  ║ • Creates PRD         ║                │                                  │
+│  ║ • 1:1 FR↔Issues       ║                │                                  │
+│  ║ • Copies templates    ║                │                                  │
+│  ╚══════════╤════════════╝                │                                  │
+│             ▼                             │                                  │
+│  ┌───────────────────────┐                │                                  │
+│  │ /vibe-design │ (Optional)     │                                  │
+│  │ • Design system       │                │                                  │
+│  │ • UI mockups          │                │                                  │
+│  └───────────┬───────────┘                │                                  │
+│              ▼                            │                                  │
+│  ╔═══════════════════════╗                │                                  │
+│  ║ /build_vibecode_      ║◄───────────────┘                                  │
+│  ║     project_v3        ║                                                   │
+│  ║                       ║                                                   │
+│  ║ • Scaffolds project   ║                                                   │
+│  ║ • tsc after EVERY edit║                                                   │
+│  ║ • Marks FR progress   ║                                                   │
+│  ╚══════════╤════════════╝                                                   │
+│             │                                                                │
+│             ▼                                                                │
+│  ┌────────────────────────────────────────────────────────────────────────┐  │
+│  │                    CONTINUATION LOOP (New Sessions)                     │  │
+│  │                                                                         │  │
+│  │   ╔═════════════════════╗      ╔═════════════════════╗                  │  │
+│  │   ║   /vibe-continueBuild   ║─────►║   /vibe-finalize   ║                  │  │
+│  │   ║                     ║      ║                     ║                  │  │
+│  │   ║ • Context recovery  ║      ║ • Full verification ║                  │  │
+│  │   ║ • Verify prev work  ║      ║ • Acceptance audit  ║                  │  │
+│  │   ║ • Resume next FR    ║      ║ • Handoff report    ║                  │  │
+│  │   ║ • tsc after edit    ║      ║                     ║                  │  │
+│  │   ╚══════════╤══════════╝      ╚═════════════════════╝                  │  │
+│  │              │                                                          │  │
+│  │              └──────────────────┐                                       │  │
+│  │                                 │ (repeat until all FRs done)           │  │
+│  │              ┌──────────────────┘                                       │  │
+│  │              ▼                                                          │  │
+│  │   ┌─────────────────────────────────────────────────────────┐           │  │
+│  │   │ IF AGENT MISBEHAVES:                                    │           │  │
+│  │   │    /agent_reset ──► /vibe-primeAgent ──► resume work        │           │  │
+│  │   └─────────────────────────────────────────────────────────┘           │  │
+│  └────────────────────────────────────────────────────────────────────────┘  │
+│                                                                              │
+│  ┌────────────────────────────────────────────────────────────────────────┐  │
+│  │                           VERIFICATION GATES                            │  │
+│  │                                                                         │  │
+│  │  After EVERY TypeScript/TSX edit:     npx tsc --noEmit                  │  │
+│  │  Before handoff:                      python scripts/vibe-verify.py     │  │
+│  │                                                                         │  │
+│  │  ❌ If verification fails → STOP, fix, re-run, only then continue       │  │
+│  └────────────────────────────────────────────────────────────────────────┘  │
+│                                                                              │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## V3 Workflow Lifecycle (RECOMMENDED)
+
+```
+/vibe-genesis    → Creates PRD, Issues (1 per FR), Guidelines template
+         ↓
+/vibe-design        → (Optional) Creates mockups
+         ↓
+/vibe-build   → Scaffolds, builds MUS with verification gates
+         ↓
+[New chat or continue]
+         ↓
+/vibe-continueBuild              → Picks up where last agent left off
+         ↓
+(repeat /vibe-continueBuild)
+         ↓
+/vibe-finalize              → Final verification, handoff report
+```
+
+**Key V3 Features:**
+- `tsc --noEmit` after every file edit
+- 1:1 FR↔Issue correlation
+- Templates from `nextjs-standards` skill
+- `vibe-verify.py` for verification
+
+---
+
+## Workflow Categories
+
+### 🏗️ Project Initialization (Run Once)
+
+| Workflow | Purpose | When to Use | Generates |
+|----------|---------|-------------|-----------|
+| `/vibe-genesis` | **V3 Architect** — Plans with templates | Starting new project | PRD, Issues (1 per FR), Guidelines template |
+| `/vibe-design` | The Designer — Creates visual system | After Genesis, before Build | `docs/design/design-system.html`, `docs/mockups/*.html` |
+| `/vibe-build` | **V3 Builder** — With verification gates | After Genesis (and optionally Design) | Project structure, MUS features with verification |
+| `/vibe-continueBuild` | **Resume work** — Post-build sessions | New chat after initial build | Continues from incomplete FRs |
+| `/vibe-finalize` | **Final handoff** — Verification + report | When MUS complete | `docs/Builder_Handoff_Report.md` |
+| `/reverse_genesis` | Onboards to existing codebase | Joining an existing project | `docs/autopsy_report.md` |
+| `/spawn-jstar-code-review` | Adds J-Star Reviewer to project | Any project needing code review | `.jstar/` directory, `.env.example` |
+
+### 🎯 Mode Workflows (Specialized Roles)
+
+Inspired by KiloCode's mode system, these workflows provide specialized capabilities:
+
+| Workflow | Purpose | When to Use |
+|----------|---------|-------------|
+| `/mode-orchestrator` | **Coordinate complex projects** — Delegate to sub-agents | Multi-step projects requiring coordination across domains |
+| `/mode-architect` | **Plan and design** — Create technical specifications | Before implementation, designing systems, breaking down complex problems |
+| `/mode-code` | **Write and refactor code** — Full implementation access | Implementing features, fixing bugs, creating files |
+| `/mode-debug` | **Diagnose issues** — Systematic problem solving | Troubleshooting errors, investigating bugs, analyzing failures |
+| `/mode-ask` | **Explain and analyze** — Answer questions without changes | Understanding concepts, analyzing code, getting recommendations |
+| `/mode-review` | **Code review** — Quality assessment before commits | Reviewing changes, pre-commit checks, PR analysis |
+
+**Mode Workflow Relationships:**
+```
+/mode-orchestrator ──► delegates to ──► /mode-architect, /mode-code, /mode-debug, /mode-review
+     │
+     └── monitors completion ◄─── .done files in docs/tasks/completed/
+
+/mode-architect ──► designs ──► hands off to ──► /mode-code
+
+/mode-code ──► implements ──► requests review ──► /mode-review
+
+/mode-debug ──► investigates ──► hands off fix to ──► /mode-code
+
+/mode-ask ──► analyzes ──► can switch to ──► /mode-code (if implementation needed)
+```
+
+### 🔄 Daily Development (Run Often)
+
+| Workflow | Purpose | When to Use |
+|----------|---------|-------------|
+| `/vibe-primeAgent` | Load project context | Start of session, before complex work |
+| `/vibe-spawnTask` | Create detailed task prompt | Complex features needing breakdown |
+| `/vibe-syncDocs` | Update feature documentation | After completing code changes |
+
+### 🔍 Code Quality & Review
+
+| Workflow | Purpose | When to Use | Requires |
+|----------|---------|-------------|----------|
+| `/mode-review_code` | Run J-Star review loop | Before commits, quality gates | **J-Star CLI** (`jstar` command) |
+| `/mode-review` | Manual code review | Pre-commit review without J-Star | Nothing — pure AI review |
+
+> [!TIP]
+> For **deep security audits**, use the `security-audit` skill instead of searching for `/deep_code_audit`. See [Skill Migrations](#-skill-migrations) below.
+> 
+> For **manual code review** without J-Star CLI setup, use `/mode-review` mode workflow.
+
+### 🆘 Recovery & Migration
+
+| Workflow | Purpose | When to Use |
+|----------|---------|-------------|
+| `/agent_reset` | Reset agent mid-conversation | Agent is hallucinating or stuck |
+| `/escalate` | Generate handoff report | Agent is stuck, need fresh perspective |
+| `/migrate` | Transfer context to new chat | Chat is stale, losing context |
+
+---
+
+## ⚠️ Important Clarifications
+
+### `/smart_start` and `/smart_complete` — NOT Standalone Workflows
+
+These are **shell script commands**, not slash-command workflows.
+
+| What They Are | How to Use |
+|---------------|------------|
+| Commands from the **Smart Ops** system | Run via `./scripts/smart-ops.sh` or `.ps1` |
+| Generated by `/init_smart_ops` | **Must run `/init_smart_ops` first** |
+| GitHub-dependent | Requires `gh` CLI + authenticated repo |
+
+**Setup Required:**
+```bash
+# Step 1: Initialize Smart Ops (generates the scripts)
+/init_smart_ops
+
+# Step 2: Use the commands
+./scripts/smart-ops.sh start     # Start a task
+./scripts/smart-ops.sh complete  # Complete a task
+```
+
+> [!IMPORTANT]
+> If you haven't run `/init_smart_ops`, the commands `smart_start` and `smart_complete` will not exist.
+
+### `/mode-review_code` vs Deep Security Audit
+
+| Tool | Automation | When to Use | Requires |
+|------|------------|-------------|----------|
+| `/mode-review_code` | ✅ Automated (J-Star CLI) | Before commits, quick PR checks | `jstar` CLI installed |
+| `security-audit` skill | ❌ Manual phases | Major releases, security reviews | Nothing — pure AI protocol |
+
+**Use `/mode-review_code` for:**
+- Daily commits
+- PR quality gates
+- Quick feedback loops
+
+**Use `security-audit` skill for:**
+- Before major releases
+- Auditing auth/payment flows
+- When manual logic probing is needed
+
+---
+
+## 🛠️ Skill Migrations
+
+These workflows have been **migrated to skills** for better portability and added scripts/resources:
+
+| Old Workflow (Legacy) | New Skill | Why Migrated |
+|----------------------|-----------|--------------|
+| `/analyze_component` | `component-analysis` | Better as protocol, no scripts needed |
+| `/deep_code_audit` | `security-audit` | Manual protocol, no tooling dependency |
+| `/git_worktree` | `git-worktree` | Reusable across projects |
+| `/seo_ready` | `seo-ready` | Portable, includes templates |
+| `/init_smart_ops` + `/smart_start` + `/smart_complete` | `github-ops` | Now includes `publish_issues.ps1` script |
+| YouTube Phase 1-5 workflows | `youtube-pipeline` | Includes scripts + resources folder |
+
+**To use migrated skills:**
+```
+# Skills are auto-loaded by context, but you can invoke directly:
+User: "Audit this component for compliance"  → Loads component-analysis skill
+User: "Run a security audit on this repo"    → Loads security-audit skill
+User: "Set up git worktrees for parallel dev" → Loads git-worktree skill
+```
+
+---
+
+## 📁 LEGACY Folder
+
+The `LEGACY/` folder contains workflows that are:
+1. **Superseded by V3 versions** (e.g., `build_vibecode_project.md` → `build_vibecode_project_v3.md`)
+2. **Migrated to skills** (e.g., `deep_code_audit.md` → `security-audit` skill)
+3. **Deprecated/Broken** (e.g., `vibe-orchestrator.md` — requires non-existent `vibecode` CLI)
+
+| Legacy Workflow | Status | Replacement |
+|-----------------|--------|-------------|
+| `build_vibecode_project.md` | Superseded | `/vibe-build` |
+| `build_vibecode_project_v2.md` | Superseded | `/vibe-build` |
+| `init_vibecode_genesis_v1.md` | Superseded | `/vibe-genesis` |
+| `analyze_component.md` | Migrated | `component-analysis` skill |
+| `deep_code_audit.md` | Migrated | `security-audit` skill |
+| `git_worktree.md` | Migrated | `git-worktree` skill |
+| `seo_ready.md` | Migrated | `seo-ready` skill |
+| `init_smart_ops.md` | Migrated | `github-ops` skill |
+| `vibe-orchestrator.md` | ⚠️ Broken | Requires `vibecode` CLI that doesn't exist |
+| `orchestrate.md` | ⚠️ Broken | Requires `vibecode` CLI that doesn't exist |
+| `gemini-orchestrate.md` | ⚠️ Broken | Requires `vibecode` CLI that doesn't exist |
+| `multi_agent_strategy.md` | Reference | Architecture docs only |
+| YouTube Phase 1-5 workflows | Migrated | `youtube-pipeline` skill |
+
+> [!CAUTION]
+> **`vibe-orchestrator.md`** references a `vibecode spawn` CLI command that was never built. This workflow is **non-functional**. If you want autonomous multi-agent orchestration, it requires building the CLI first.
+
+---
+
+## Recommended Flows
+
+### Flow 1: New Project (V3 - RECOMMENDED)
+
+```
+1. /vibe-genesis → Get PRD, Issues (1 per FR), Templates
+2. /vibe-design     → Get design system, mockups (UI projects)
+3. /vibe-build → Scaffold and build MUS with verification
+4. /vibe-continueBuild           → Resume in new sessions
+5. /vibe-finalize           → Final verification and handoff
+6. /spawn-jstar-code-review  → Add code review tooling (optional)
+```
+
+### Flow 2: Joining Existing Project
+
+```
+1. /reverse_genesis          → Generate autopsy report
+2. /vibe-primeAgent              → Load coding/styling context
+3. Start working             → Reference the autopsy for architecture
+```
+
+### Flow 3: Daily Work Session
+
+```
+1. /vibe-primeAgent              → (Optional) Refresh context
+2. ... do the work ...
+3. /mode-review_code              → Check code quality before commit
+4. git commit                → Commit clean code
+```
+
+### Flow 4: Complex Feature Implementation
+
+```
+1. /vibe-spawnTask               → Generate detailed task prompt
+2. ... implement phases ...
+3. /mode-review_code              → Quality gate before merge
+4. /vibe-syncDocs                → Update feature documentation
+```
+
+### Flow 5: Agent Recovery
+
+```
+# If agent is stuck:
+/escalate                    → Generate damage report for fresh agent
+
+# If chat is stale:
+/migrate                     → Generate state snapshot for new session
+
+# If agent is hallucinating:
+/agent_reset                 → Mid-conversation reset
+```
+
+### Flow 6: Code Review Loop (Quality Gate)
+
+```
+1. git add .                 → Stage changes
+2. /mode-review_code              → Run J-Star review
+3. Fix P0/P1 issues          → Address critical findings
+4. Repeat until clean        → Max 3 loops
+5. Commit                    → Code is ready
+```
+
+### Flow 7: Deep Security Audit
+
+```
+# Use the security-audit skill (auto-loaded when "security audit" mentioned)
+1. Define scope (FULL/FEATURE/DIFF)
+2. Phase 1: Static analysis (Detective)
+3. Phase 2: Data flow tracing (Graph)
+4. Phase 3: Spec vs Code (Auditor)
+5. Phase 4: Logic probing (Judge)
+6. Phase 5: Quality checks (Architect)
+7. Generate report → .jstar/audit_report.md
+8. Fix CRITICAL/HIGH issues
+```
+
+### Flow 8: Documentation Sync
+
+```
+1. Complete code changes     → Feature/fix is done
+2. /vibe-syncDocs                → Identify impacted docs
+3. UPDATE or CREATE          → Modify existing or add new doc
+4. Follow template           → Consistent structure
+5. Verify file paths         → Ensure links work
+```
+
+### Flow 9: Multi-Agent Orchestration (NEW)
+
+For complex projects requiring coordination across multiple specialized agents:
+
+```
+1. /mode-orchestrator             → Break down project into subtasks
+2. Create session folder       → docs/tasks/orchestrator-sessions/[ID]/
+3. Create task files           → pending/01_subtask_name.task.md
+4. Spawn sub-agents            → User opens new chats with task assignments
+5. Sub-agents work             → Each completes their task, creates .result.md file
+6. Review completions          → Return to orchestrator, review all .result.md files
+7. Synthesize results          → Orchestrator creates summary report
+8. Iterate if needed           → Create new tasks for remaining work
+```
+
+**Session ID Format:** `orch-YYYYMMDD-HHMMSS` (e.g., `orch-20250131-143022`)
+
+**Task Folder Structure:**
+```
+docs/tasks/
+└── orchestrator-sessions/           # All orchestrator sessions
+    ├── orch-20250131-143022/       # Session 1 (timestamp-based ID)
+    │   ├── master_plan.md          # Overview of all tasks
+    │   ├── pending/                # Tasks waiting to start
+    │   │   └── 01_genesis.task.md
+    │   ├── in-progress/            # Tasks currently being worked on
+    │   └── completed/              # Finished tasks with .result.md files
+    │       ├── 01_genesis.result.md
+    │       └── 02_design.result.md
+    ├── orch-20250131-154511/       # Session 2
+    └── ...
+```
+
+**Task File Naming Convention:**
+- **Pending:** `01_subtask_name.task.md` (sequential number + descriptive name)
+- **Completed:** `01_subtask_name.result.md` (same name, `.result.md` extension)
+
+**Workflow:**
+1. **Orchestrator** creates tasks in `pending/` with `.task.md` extension
+2. **User** spawns sub-agents in new chats, assigning specific task files
+3. **Sub-agents** work on tasks and create `.result.md` files in `completed/`
+4. **Orchestrator** reviews all `.result.md` files and synthesizes results
+5. **Iterate** if needed by creating new tasks
+
+**Key Features:**
+- **Isolation:** Each orchestrator session has its own folder
+- **Continuity:** Easy to resume by referencing session ID
+- **Organization:** All related tasks grouped under one session
+- **Tracking:** `master_plan.md` shows progress across all tasks
+
+---
+
+## Parent-Child Relationships
+
+### `/vibe-genesis` is Parent of:
+- `/vibe-design` (uses the PRD)
+- `/vibe-build` (uses PRD, Guidelines, Issues)
+
+### `/vibe-build` is Parent of:
+- `/vibe-continueBuild` (resumes incomplete FRs)
+- `/vibe-finalize` (generates final handoff)
+
+### `/vibe-continueBuild` Loops Into:
+- Itself (repeat until all FRs done)
+- `/vibe-finalize` (when MUS complete)
+
+### `/spawn-jstar-code-review` Enables:
+- `/mode-review_code` (requires J-Star to be set up)
+
+### Standalone (No Parent):
+- `/vibe-primeAgent` — Reload context anytime
+- `/agent_reset` — Reset when agent misbehaves
+- `/vibe-continueBuild` — Resume in any session
+- `/vibe-spawnTask` — Break down complex features
+- `/vibe-syncDocs` — Update documentation
+- `/escalate` — Hand off to fresh agent
+- `/migrate` — Move context to new session
+- `/reverse_genesis` — Onboard to existing project
+
+---
+
+## Available Skills Reference
+
+These skills are auto-loaded based on context. Location: `.agent/skills/`
+
+| Skill | Description | Trigger Context |
+|-------|-------------|-----------------|
+| `code-review` | J-Star review on staged changes | "review code", before commits |
+| `component-analysis` | Audit React/TS components | "analyze component", refactoring |
+| `git-worktree` | Parallel agent development | "worktree", multi-agent |
+| `github-ops` | Issue sync, projects, labels | GitHub automation, issue creation |
+| `google-trends` | Automated trend research | YouTube research, topic validation |
+| `nextjs-standards` | Coding standards + templates | Next.js projects (auto-detect) |
+| `security-audit` | Deep manual security audit | Security review, major releases |
+| `seo-ready` | SEO optimization for Next.js | SEO, metadata, sitemap |
+| `spawn-task` | Generate detailed task prompts | Complex features |
+| `sync-docs` | Update feature documentation | After code changes |
+| `youtube-pipeline` | Full YouTube production pipeline | Video creation, scripting |
+| `vercel-ai-sdk` | AI SDK patterns for Next.js | Building AI features |
+
+---
+
+## Quick Reference
+
+| I want to... | Use this |
+|--------------|----------|
+| **Start a new project** | `/vibe-genesis` |
+| **Design the UI** | `/vibe-design` |
+| **Build the foundation** | `/vibe-build` |
+| **Resume work (new session)** | `/vibe-continueBuild` |
+| **Finish and hand off** | `/vibe-finalize` |
+| **Coordinate multi-agent work** | `/mode-orchestrator` |
+| **Plan before coding** | `/mode-architect` |
+| **Implement features** | `/mode-code` |
+| **Debug issues** | `/mode-debug` |
+| **Ask questions** | `/mode-ask` |
+| **Review code (manual)** | `/mode-review` |
+| Join an existing project | `/reverse_genesis` |
+| Reload agent context | `/vibe-primeAgent` |
+| Reset misbehaving agent | `/agent_reset` |
+| Break down a complex feature | `/vibe-spawnTask` |
+| Run code review (J-Star) | `/mode-review_code` (requires J-Star) |
+| Add code review tooling | `/spawn-jstar-code-review` |
+| Deep security audit | Use `security-audit` skill |
+| Analyze a component | Use `component-analysis` skill |
+| SEO optimization | Use `seo-ready` skill |
+| Set up parallel agents | Use `git-worktree` skill |
+| Bulk sync GitHub issues | Use `github-ops` skill |
+| Update documentation | `/vibe-syncDocs` |
+| Hand off to fresh agent | `/escalate` |
+| Move to new chat | `/migrate` |
+| YouTube video pipeline | Use `youtube-pipeline` skill |
+| Learn AI SDK patterns | `/Vercel Ai SDK` |
+
+---
+
+## Stack-Specific Notes
+
+### Universal Shell Script (All Stacks)
+The Smart Ops system (via `github-ops` skill) uses **shell scripts** that work with ANY project stack:
+
+| Stack | Works? | Notes |
+|-------|--------|-------|
+| Node.js/TypeScript | ✅ | Shell script runs in any terminal |
+| Python | ✅ | Shell script works |
+| Rust | ✅ | Shell script works |
+| Go | ✅ | Shell script works |
+| Any Unix/Linux/macOS | ✅ | Native bash |
+| Windows | ✅ | Git Bash, WSL, or PowerShell |
+
+### J-Star Code Reviewer (All Languages)
+The J-Star Reviewer works with **any programming language**:
+
+| Language | Works? | Notes |
+|----------|--------|-------|
+| TypeScript/JavaScript | ✅ | Full support |
+| Python | ✅ | Full support |
+| Rust | ✅ | Full support |
+| Go | ✅ | Full support |
+| Any other | ✅ | Uses Gemini for analysis |
+