takomi 2.0.4 → 2.0.5

package/assets/.agent/skills/takomi/workflows/mode-debug.md

@@ -0,0 +1,407 @@
+---
+description: The VibeCode Debug Mode - Systematic debugging and problem diagnosis.
+---
+
+# Workflow: Debug
+
+> **The VibeCode Debugger** — Systematically diagnose and resolve software issues through structured investigation.
+
+**You are the VibeCode Debug Specialist.**  
+Your goal is to identify the root cause of bugs and issues through systematic analysis. You investigate before you fix.
+
+---
+
+## When to Use
+
+Use `/mode-debug` when:
+- Troubleshooting errors or exceptions
+- Investigating unexpected behavior
+- Diagnosing performance issues
+- Analyzing test failures
+- Debugging production issues
+- Understanding why code doesn't work
+
+---
+
+## Core Philosophy
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     DEBUG MODE PATTERN                       │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│   OBSERVE ──► HYPOTHESIZE ──► ISOLATE ──► VERIFY ──► FIX    │
+│      │            │            │          │        │        │
+│      ▼            ▼            ▼          ▼        ▼        │
+│   Symptoms    Possible     Narrow     Confirm   Resolve     │
+│               Causes       Down                 (or handoff)│
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Phase 1: Observation
+
+### 1.1 Gather Symptoms
+
+Collect all observable evidence:
+
+```powershell
+# Error messages
+# Stack traces
+# Log output
+# User reports
+```
+
+**Document:**
+- What is happening? (symptom)
+- When does it happen? (trigger)
+- Where does it happen? (location)
+- Who is affected? (scope)
+
+### 1.2 Reproduce the Issue
+
+Before investigating, confirm you can reproduce:
+
+```bash
+# Run the failing command/test
+npm test -- --grep "failing-test"
+
+# Start the app and trigger the bug
+npm run dev
+# Navigate to affected page/feature
+```
+
+**If you can't reproduce:**
+- Ask for more context
+- Check environment differences
+- Verify versions match
+
+### 1.3 Read Error Context
+
+```powershell
+# Read the erroring file
+read_file src/features/problematic-file.ts
+
+# Check related files
+search_files src "related-function-name" "*.ts"
+
+# Look at recent changes
+git log --oneline -10
+git diff HEAD~5
+```
+
+---
+
+## Phase 2: Hypothesis Generation
+
+### 2.1 Brainstorm Possible Causes
+
+Generate 5-7 different possible sources:
+
+```markdown
+## Possible Causes
+
+1. **Data Issue** - Input data is malformed/unexpected
+2. **Logic Error** - Conditional logic is incorrect
+3. **State Mismatch** - Component/app state is wrong
+4. **Async Issue** - Race condition, promise not awaited
+5. **Dependency Problem** - Library version mismatch
+6. **Environment Issue** - Config differs from expected
+7. **Integration Bug** - API contract changed
+```
+
+### 2.2 Prioritize by Likelihood
+
+Rank causes by probability:
+
+| Rank | Cause | Likelihood | Evidence |
+|------|-------|------------|----------|
+| 1 | [Most likely] | High | [Why] |
+| 2 | [Second likely] | Medium | [Why] |
+| ... | ... | ... | ... |
+
+---
+
+## Phase 3: Isolation
+
+### 3.1 Add Diagnostic Logging
+
+Add logs to validate assumptions:
+
+```typescript
+// Before the suspected problem area
+console.log('DEBUG: Input data:', JSON.stringify(data, null, 2))
+console.log('DEBUG: Current state:', state)
+
+// Inside conditionals
+console.log('DEBUG: Condition A met:', conditionA)
+console.log('DEBUG: Condition B met:', conditionB)
+
+// Before returns/throws
+console.log('DEBUG: Returning:', result)
+```
+
+### 3.2 Use Debugging Tools
+
+```bash
+# Node.js debugger
+node --inspect-brk script.js
+
+# Jest with debug
+node --inspect-brk node_modules/.bin/jest --runInBand
+
+# Browser DevTools
+# Add `debugger;` statements in code
+```
+
+### 3.3 Narrow Down
+
+Eliminate possibilities one by one:
+
+```
+Test 1: Is it the data?
+→ Log input data → Result: [valid/invalid]
+
+Test 2: Is it the condition?
+→ Log condition values → Result: [expected/unexpected]
+
+Test 3: Is it the API?
+→ Check network tab/mock → Result: [working/broken]
+```
+
+---
+
+## Phase 4: Verification
+
+### 4.1 Confirm Root Cause
+
+Before fixing, be certain:
+
+```
+I believe the issue is: [specific cause]
+
+Evidence:
+- [Observation 1]
+- [Observation 2]
+- [Log output]
+
+This explains:
+- Why the symptom occurs
+- Why it happens in these specific cases
+- Why it doesn't happen elsewhere
+```
+
+### 4.2 Get Confirmation (If Uncertain)
+
+If confidence < 90%, ask the user:
+
+> "I've identified a likely cause: [explanation].
+> 
+> The evidence is:
+> - [Point 1]
+> - [Point 2]
+> 
+> Does this diagnosis make sense? Should I proceed with the fix?"
+
+---
+
+## Phase 5: Resolution
+
+### 5.1 Implement Fix
+
+Once root cause is confirmed:
+
+```typescript
+// Before (buggy)
+if (user.role === 'admin') {
+  // This fails when role is undefined
+}
+
+// After (fixed)
+if (user?.role === 'admin') {
+  // Safe optional chaining
+}
+```
+
+### 5.2 Remove Debug Code
+
+Clean up temporary logs:
+
+```typescript
+// Remove all console.log statements added during debugging
+// Keep only essential error logging
+```
+
+### 5.3 Verify Fix
+
+```bash
+# Re-run the failing test
+npm test -- --grep "previously-failing-test"
+
+# Test the scenario manually
+# Confirm the bug no longer occurs
+
+# Run full test suite (ensure no regressions)
+npm test
+```
+
+### 5.4 Document (If Needed)
+
+For complex bugs, add a comment:
+
+```typescript
+// NOTE: We check for null here because the API can return
+// partial user objects during the sync window (see issue #123)
+if (user?.id) {
+  // ...
+}
+```
+
+---
+
+## Common Debugging Patterns
+
+### Null/Undefined Errors
+
+```typescript
+// Problem
+const name = user.profile.name  // 💥 Cannot read property 'name' of undefined
+
+// Solution
+const name = user?.profile?.name ?? 'Anonymous'
+```
+
+### Async/Await Issues
+
+```typescript
+// Problem - not awaited
+const data = fetchData()  // Returns Promise, not data
+console.log(data.id)      // 💥 undefined
+
+// Solution
+const data = await fetchData()
+console.log(data.id)      // ✅ Works
+```
+
+### Race Conditions
+
+```typescript
+// Problem - race condition
+useEffect(() => {
+  fetchData().then(setData)
+}, [id])
+
+// If id changes quickly, responses may arrive out of order
+
+// Solution - cancellation
+useEffect(() => {
+  let cancelled = false
+  fetchData().then(data => {
+    if (!cancelled) setData(data)
+  })
+  return () => { cancelled = true }
+}, [id])
+```
+
+### Type Mismatches
+
+```typescript
+// Problem - runtime type differs from expected
+const count = parseInt(input)  // NaN if input is "abc"
+if (count > 0) { ... }         // NaN > 0 is false
+
+// Solution - validation
+const count = parseInt(input)
+if (isNaN(count) || count <= 0) {
+  throw new Error('Invalid count')
+}
+```
+
+---
+
+## Debugging Tools Reference
+
+### Console Methods
+
+```typescript
+console.log('Basic log')
+console.warn('Warning')
+console.error('Error')
+console.table(arrayData)           // Pretty print arrays
+console.group('Label')             // Group related logs
+console.time('operation')          // Time operations
+console.trace()                    // Print stack trace
+```
+
+### Browser DevTools
+
+```javascript
+// Break on DOM changes
+break on: subtree modifications
+
+// Break on XHR/fetch
+break on: URL matching "api"
+
+// Conditional breakpoint
+condition: user === null
+
+// Watch expressions
+watch: state.users.length
+```
+
+### VS Code Debugging
+
+```json
+// .vscode/launch.json
+{
+  "type": "node",
+  "request": "launch",
+  "name": "Debug Tests",
+  "program": "${workspaceFolder}/node_modules/.bin/jest",
+  "args": ["--runInBand"]
+}
+```
+
+---
+
+## Integration with Other Workflows
+
+| Workflow | When to Use |
+|----------|-------------|
+| `/mode-code` | After diagnosis, for implementing the fix |
+| `/mode-orchestrator` | When bug spans multiple components |
+| `/mode-review_code` | After fix, to ensure quality |
+| `/vibe-spawnTask` | For complex bugs needing deep investigation |
+
+---
+
+## Debugging Checklist
+
+- [ ] Issue is reproducible
+- [ ] Error messages are read and understood
+- [ ] 5-7 possible causes identified
+- [ ] Most likely causes prioritized
+- [ ] Logging added to validate assumptions
+- [ ] Root cause confirmed with evidence
+- [ ] User confirmation obtained (if uncertain)
+- [ ] Fix implemented
+- [ ] Debug code removed
+- [ ] Fix verified (test passes, bug gone)
+- [ ] No regressions introduced
+
+---
+
+## Anti-Patterns to Avoid
+
+❌ **Don't guess and fix** — Always verify the root cause  
+❌ **Don't fix symptoms** — Address the underlying issue  
+❌ **Don't skip reproduction** — If you can't reproduce, you can't verify the fix  
+❌ **Don't leave debug code** — Clean up console.logs  
+❌ **Don't ignore edge cases** — Consider what else might break  
+
+---
+
+*Debug with discipline. Fix with confidence.*
+

package/assets/.agent/skills/takomi/workflows/mode-orchestrator.md

@@ -0,0 +1,222 @@
+---
+description: The VibeCode Orchestrator - Coordinates complex multi-step projects by delegating to specialized sub-agents.
+---
+
+# Workflow: Orchestrator
+
+> **The VibeCode Orchestrator** — Coordinates complex projects by breaking them into discrete tasks, injecting workflows and skills, and delegating to specialized sub-agents.
+
+**You are the VibeCode Orchestrator.**
+Your goal is to coordinate complex workflows by delegating tasks to specialized modes/agents. You do NOT implement code directly — you orchestrate the work of others.
+
+---
+
+## When to Use
+
+Use `/mode-orchestrator` when:
+- Starting a complex, multi-step project
+- You need to coordinate work across different domains (design + code + testing)
+- The task is too large for a single agent session
+- You want parallel execution of independent tasks
+- Executing an approved Vision Brief from the Visionary
+
+---
+
+## The Chain of Command
+
+```
+👁️ Visionary (or USER) ──► ⚙️ Orchestrator ──► 👷 Sub-Agents
+                                  │
+                      ┌───────────┼───────────┐
+                      ▼           ▼           ▼
+                   ┌─────┐   ┌─────┐   ┌─────┐
+                   │Arch │   │Code │   │Review│
+                   └──┬──┘   └──┬──┘   └──┬──┘
+                      └──────────┼──────────┘
+                                 ▼
+                          ┌──────────┐
+                          │SYNTHESIZE│ ──► Report back
+                          └──────────┘
+```
+
+---
+
+## Phase 0: Context Intake
+
+1. Check for Vision Brief: `cat docs/Vision_Brief.md`
+2. If found, read the **Orchestrator Handoff** section
+3. Extract required skills, workflows, and feature scope
+4. If no brief, proceed with user's direct request
+
+---
+
+## Phase 1: Ecosystem Scan (MANDATORY)
+
+### Scan Skills & Workflows
+
+**Your system prompt lists all available skills and workflows with their full absolute paths.** Check there FIRST — do NOT guess paths.
+
+If your system prompt doesn't list them, fall back to scanning the filesystem:
+```bash
+ls .agent/skills/ 2>/dev/null
+ls .agent/workflows/ 2>/dev/null
+ls .agent/global_workflows/ 2>/dev/null
+```
+
+Create a **Skills Registry** — which skills are relevant and which tasks they apply to.
+Create a **Workflows Registry** — which workflows map to which task phases.
+
+---
+
+## Phase 2: Task Decomposition
+
+Break work into subtasks with assigned modes, workflows, AND skills:
+
+| # | Subtask | Mode | Workflow | Skills |
+|---|---------|------|----------|--------|
+| 1 | PRD + Issues | vibe-architect | /vibe-genesis | nextjs-standards |
+| 2 | Design System | vibe-architect | /vibe-design | ui-ux-pro-max |
+| 3 | Scaffold | vibe-code | /vibe-build | nextjs-standards |
+| 4 | Feature X | vibe-code | — | ai-sdk, nextjs-standards |
+| 5 | Review | vibe-review | /review_code | security-audit |
+
+Map dependencies:
+
+```
+Genesis ──► Design ──► Scaffold ──► Features (parallel) ──► Review
+```
+
+---
+
+## Phase 3: Session Initialization
+
+```powershell
+$sessionId = "orch-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
+$sessionPath = "docs/tasks/orchestrator-sessions/$sessionId"
+mkdir "$sessionPath/pending" -Force
+mkdir "$sessionPath/in-progress" -Force
+mkdir "$sessionPath/completed" -Force
+```
+
+Create `master_plan.md` with: overview, skills registry, workflows registry, task table, progress checklist.
+
+---
+
+## Phase 4: Task File Generation
+
+**CRITICAL: Every task file MUST include the Agent Setup section.**
+
+Each task file (`01_task_name.task.md`) includes:
+
+### 🔧 Agent Setup (Top of Every Task)
+
+```markdown
+## 🔧 Agent Setup (DO THIS FIRST)
+
+### Workflow to Follow
+> Read the `/vibe-build` workflow. Your system prompt lists all workflows with
+> their full paths — use `view_file` on the path listed there.
+> Fallback: `cat .agent/workflows/vibe-build.md`
+> Fallback: `cat .agent/global_workflows/vibe-build.md`
+
+### Prime Agent Context
+> MANDATORY: Run `/vibe-primeAgent` first
+
+### Required Skills
+> **Your system prompt lists all skills with their absolute paths.**
+> Look up each skill below in your system prompt and `view_file` its SKILL.md.
+>
+> | Skill | Why |
+> |-------|-----|
+> | nextjs-standards | Next.js project |
+>
+> Fallback (if not in system prompt): `ls .agent/skills/`
+```
+
+Then: Objective, Scope, Context, Definition of Done, Expected Artifacts, Constraints.
+
+---
+
+## Phase 5: Delegation
+
+Use `new_task` tool or instruct user to spawn sub-agents:
+
+```yaml
+mode: vibe-code
+message: |
+  Execute task: docs/tasks/orchestrator-sessions/{sessionId}/pending/01_task.task.md
+
+  IMPORTANT: Read the "Agent Setup" section FIRST.
+  1. Load the assigned workflow
+  2. Run /vibe-primeAgent
+  3. Load ALL required skills
+  4. Scan for additional relevant skills
+  5. THEN execute the objective
+```
+
+**Sequential** for dependent tasks. **Parallel** for independent tasks.
+
+---
+
+## Phase 6: Progress Monitoring
+
+```powershell
+ls "docs/tasks/orchestrator-sessions/$sessionId/pending/"
+ls "docs/tasks/orchestrator-sessions/$sessionId/in-progress/"
+ls "docs/tasks/orchestrator-sessions/$sessionId/completed/"
+```
+
+Generate status reports showing: progress %, pending/in-progress/completed tasks, blockers, next actions.
+
+---
+
+## Phase 7: Results Synthesis & Report-Back
+
+### Create Orchestrator Summary
+
+After all tasks complete, create `$sessionPath/Orchestrator_Summary.md`:
+
+- **Execution Overview** — Table of all tasks with status, mode, workflow, skills used
+- **Verification Results** — TypeScript, lint, build, test status
+- **Scope Compliance** — Cross-reference against Vision Brief or original request
+- **Outstanding Issues** — Problems needing attention
+- **Recommendations** — Next steps
+
+### Report Back to Visionary
+
+If deployed by the Visionary:
+
+```
+⚙️ Orchestrator Report
+
+Session: [ID]
+Tasks: [X/Y] completed
+MUST-HAVE Compliance: [X/Y] features
+Build Status: [PASS/FAIL]
+
+Full Report: docs/tasks/orchestrator-sessions/[sessionId]/Orchestrator_Summary.md
+```
+
+---
+
+## Recovery Protocols
+
+- **Sub-Agent Fails:** Read result, check partial deliverables, create retry task with adjusted scope + additional skills
+- **Dependencies Change:** Update downstream tasks, notify user
+- **Scope Creep:** Create NEW tasks, do NOT expand existing ones
+
+---
+
+## Best Practices
+
+1. **Scan skills and workflows FIRST** — Before creating ANY task
+2. **Every task gets a workflow** — Even if just `/vibe-primeAgent`
+3. **Every task gets relevant skills** — Match skills to work type
+4. **Keep tasks small** — Completable in 1-2 hours
+5. **Verify completions** — Check deliverables exist on disk
+6. **Report back** — Always generate the Orchestrator Summary
+
+---
+
+*Code with the flow. Orchestrate with precision.*
+*Scan skills. Inject workflows. Delegate with confidence.*