# Orchestration

> MANDATORY - Your default operating system. Adaptive workflow that routes simple tasks to direct execution and complex tasks to PRD iterations with agent swarms. Auto-creates skills when patterns emerge.

- Skill: `diegosouzapw/orchestration` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/orchestration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/orchestration/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/diegosouzapw/orchestration

---


# 🚨 CC3 ENFORCEMENT ACTIVE 🚨

**Before doing ANYTHING, read these mandatory rules:**

## RULE 1: NAMED AGENTS ONLY (ENFORCED)

When spawning agents, you **MUST** use named agents. Generic agents are **BLOCKED**.

```
✅ ALLOWED:
Task(subagent_type: "kraken", prompt: "...", run_in_background: true)
Task(subagent_type: "sleuth", prompt: "...")
Task(subagent_type: "scout", prompt: "...")

❌ BLOCKED (will fail):
Task(subagent_type: "general-purpose", ...)
```

**Agent Selection:**
| Task Type | Agent | Model |
|-----------|-------|-------|
| Implementation | **kraken** | opus |
| Debugging | **sleuth** | opus |
| Exploration | **scout** | sonnet |
| Planning | **architect** | opus |
| Quick fixes | **spark** | sonnet |
| Testing | **arbiter** | opus |
| Refactoring | **phoenix** | opus |
| Code review | **critic** | sonnet |

## RULE 2: STORE LEARNINGS (CHECKED EVERY PROMPT)

After completing significant work, store to PostgreSQL:
```bash
docker exec opc-postgres psql -U opc -d opc -c "
INSERT INTO temporal_facts (session_id, fact_type, content, metadata, created_at)
VALUES ('session', 'learning', 'What was learned', '{}', NOW());
"
```

## RULE 3: MAINTAIN LEDGERS (CHECKED EVERY PROMPT)

Keep session progress in `~/.claude/thoughts/ledgers/`

---


```
╔═══════════════════════════════════════════════════════════════╗
║                                                               ║
║   This is how you operate.                                   ║
║                                                               ║
║   Every request flows through this system:                   ║
║   • ASSESS complexity                                        ║
║   • ROUTE to appropriate approach                            ║
║   • EXECUTE (directly or via agents)                         ║
║   • LEARN and improve                                        ║
║                                                               ║
║   Simple tasks: just do them.                                ║
║   Complex tasks: break down, iterate, swarm.                 ║
║   Repetitive patterns: create skills automatically.          ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝
```

---

## First: Know Your Role

```
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   Are you the ORCHESTRATOR or a WORKER?                    │
│                                                             │
│   Check your prompt. If it contains:                       │
│   • "You are a WORKER agent"                               │
│   • "Do NOT spawn sub-agents"                              │
│   • "Complete this specific task"                          │
│                                                             │
│   → You are a WORKER. Skip to Worker Mode below.           │
│                                                             │
│   If you're in the main conversation with a user:          │
│   → You are the ORCHESTRATOR. Continue reading.            │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### Worker Mode

If you were spawned by an orchestrator:

1. **Execute** the specific task in your prompt
2. **Use tools directly** — Read, Write, Edit, Bash, etc.
3. **Do NOT spawn sub-agents** — you are the worker
4. **Do NOT manage tasks** — the orchestrator handles TaskCreate/TaskUpdate
5. **Report results clearly** — file paths, code snippets, what you did

Then stop. The orchestrator takes it from here.

---

## The Core Flow: Assess → Route → Execute

```
User Request
     │
     ▼
┌────────────────────────────────────────────────────────────┐
│              MULTI-DIMENSIONAL COMPLEXITY ASSESSMENT        │
│                                                             │
│  Score 6 dimensions + 4 context modifiers (0-2 each)       │
│                                                             │
│  Total 0-4   → SIMPLE  (execute directly)                  │
│  Total 5-10  → MEDIUM  (spawn agents)                      │
│  Total 11-20 → LARGE   (PRD + iterate with swarms)         │
│                                                             │
└────────────────────────────────────────────────────────────┘
```

### The 6 Core Dimensions

Score each **0** (low) / **1** (medium) / **2** (high):

```
┌─────────────────────────────────────────────────────────────┐
│  1. SCOPE CLARITY                                           │
│     How clear are the requirements?                         │
│     0 = Crystal clear, known solution                       │
│     1 = Mostly clear, some decisions needed                 │
│     2 = Ambiguous, needs exploration/clarification          │
│     Examples:                                               │
│       "Fix typo on line 42" → 0                             │
│       "Add logout button" → 1 (where? what happens?)        │
│       "Improve the UX" → 2                                  │
│                                                             │
│  2. BLAST RADIUS                                            │
│     How much of the codebase is affected?                   │
│     0 = Single file, isolated change                        │
│     1 = Multiple files in same module/feature               │
│     2 = Cross-cutting, multiple systems/layers              │
│     Examples:                                               │
│       "Update this constant" → 0                            │
│       "Add API endpoint + tests" → 1                        │
│       "Change authentication flow" → 2                      │
│                                                             │
│  3. RISK LEVEL                                              │
│     What's the impact if something goes wrong?              │
│     0 = Safe, easily reversible, non-critical path          │
│     1 = Moderate, affects functionality but recoverable     │
│     2 = Critical path (auth, payments, data), hard to undo  │
│     Examples:                                               │
│       "Update README" → 0                                   │
│       "Add new feature flag" → 1                            │
│       "Migrate database schema" → 2                         │
│                                                             │
│  4. COGNITIVE LOAD                                          │
│     How many concepts must be held in mind simultaneously?  │
│     0 = Simple logic, single concept                        │
│     1 = Multiple components, moderate state                 │
│     2 = Complex coordination, novel patterns, state machines│
│     Examples:                                               │
│       "Add a field to form" → 0                             │
│       "Add form with validation" → 1                        │
│       "Implement real-time sync with conflict resolution" → 2│
│                                                             │
│  5. UNCERTAINTY                                             │
│     How much do we need to discover vs execute?             │
│     0 = Known pattern, clear path, done this before         │
│     1 = Some unknowns, may need to explore options          │
│     2 = Significant unknowns, research/spike needed first   │
│     Examples:                                               │
│       "Follow existing pattern for new endpoint" → 0        │
│       "Add caching (which strategy?)" → 1                   │
│       "Why is this slow? Fix it." → 2                       │
│                                                             │
│  6. DEPENDENCIES                                            │
│     Does this work stand alone or require coordination?     │
│     0 = Self-contained, no external dependencies            │
│     1 = Depends on stable interfaces, minimal coordination  │
│     2 = Requires API changes, cross-team sync, migrations   │
│     Examples:                                               │
│       "Add utility function" → 0                            │
│       "Use existing service in new way" → 1                 │
│       "Change shared API contract" → 2                      │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### The 4 Context Modifiers

Add these based on situational factors:

```
┌─────────────────────────────────────────────────────────────┐
│  7. CODEBASE FAMILIARITY                                    │
│     How well do you know this codebase?                     │
│     0 = Deep familiarity, worked here extensively           │
│     1 = Some familiarity, know the patterns                 │
│     2 = First time, need to learn conventions               │
│     Note: Resets per-project, not per-session               │
│                                                             │
│  8. TIME PRESSURE                                           │
│     How urgent is this task?                                │
│     0 = No rush, quality over speed                         │
│     1 = Normal priority                                     │
│     2 = Urgent, but DON'T skip steps—flag if incompatible   │
│     Note: Urgency may LOWER threshold but doesn't skip PRD  │
│     for genuinely complex work (that would be reckless)     │
│                                                             │
│  9. USER EXPERTISE                                          │
│     How technical is the user?                              │
│     0 = Expert, wants minimal hand-holding                  │
│     1 = Competent, appreciates context                      │
│     2 = Learning, needs more explanation                    │
│     Effect: Adjusts verbosity, not routing                  │
│                                                             │
│  10. HISTORICAL PATTERNS                                    │
│     Have similar tasks been done before?                    │
│     0 = Yes, and they were simple (trust the pattern)       │
│     1 = Yes, but mixed results                              │
│     2 = No precedent, or past attempts were painful         │
│     Check: ~/.claude/regi-state/global-learnings.md         │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### Quick Mental Assessment

For fast routing, ask yourself:

```
┌─────────────────────────────────────────────────────────────┐
│                     QUICK CHECK                             │
│                                                             │
│  Can I mass all of this at once without context switches?  │
│  YES → Likely SIMPLE                                        │
│                                                             │
│  Do I need to explore before I can estimate scope?          │
│  YES → Likely MEDIUM or LARGE                               │
│                                                             │
│  Could this break something important if done wrong?        │
│  YES → Add +2 to score, consider more careful approach      │
│                                                             │
│  Am I uncertain about the right approach?                   │
│  YES → Add +2, may need exploration agents first            │
│                                                             │
│  Does this touch auth, payments, or user data?              │
│  YES → Add +2, never rush critical paths                    │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### Scoring Examples

| Task | Clarity | Radius | Risk | Cognitive | Uncertainty | Deps | Familiar | Time | Expertise | Historical | **Total** | **Route** |
|------|---------|--------|------|-----------|-------------|------|----------|------|-----------|------------|-----------|-----------|
| Fix typo line 42 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | - | 0 | **0** | Simple |
| Add health endpoint | 0 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | - | 0 | **1** | Simple |
| Add dark mode | 1 | 2 | 0 | 1 | 1 | 0 | 1 | 0 | - | 1 | **7** | Medium |
| Debug slow query | 1 | 1 | 1 | 1 | 2 | 0 | 1 | 1 | - | 1 | **9** | Medium |
| Add user auth | 1 | 2 | 2 | 2 | 1 | 1 | 1 | 0 | - | 1 | **11** | Large |
| New codebase + feature | 1 | 2 | 1 | 1 | 1 | 1 | 2 | 0 | - | 2 | **11** | Large |
| Migrate to microservices | 2 | 2 | 2 | 2 | 2 | 2 | 1 | 0 | - | 2 | **15** | Large |

*Note: User Expertise affects communication style, not routing score*

### Threshold Adjustments

The base thresholds can shift:

```
Default:     0-4 Simple | 5-10 Medium | 11+ Large

Urgent + Expert User:
             0-5 Simple | 6-12 Medium | 13+ Large
             (Slightly more aggressive, but still respect complexity)

New Codebase + Learning User:
             0-3 Simple | 4-8 Medium | 9+ Large
             (More conservative, more explanation)

Critical System (auth/payments/data):
             0-2 Simple | 3-8 Medium | 9+ Large
             (Much more conservative, always prefer caution)
```

---

## Execution Mode: Direct vs Agents

This is critical. The routing score determines not just HOW to work, but WHETHER you spawn agents.

```
┌─────────────────────────────────────────────────────────────┐
│                    EXECUTION RULES                          │
│                                                             │
│  DIRECT EXECUTION ALLOWED (you do it yourself):            │
│  ✓ Score 0-4 (Simple)                                      │
│  ✓ Single file changes                                     │
│  ✓ Obvious, mechanical edits                               │
│  ✓ Quick lookups or reads                                  │
│  ✓ Running a single command                                │
│                                                             │
│  AGENTS REQUIRED (you MUST spawn):                         │
│  ✗ Score 5+ (Medium/Large)                                 │
│  ✗ Multiple files need changing                            │
│  ✗ Exploration needed before implementation                │
│  ✗ Any story in a PRD (even "simple" ones)                │
│  ✗ Tasks that benefit from parallel work                   │
│                                                             │
│  SWARMING REQUIRED (multiple agents on SAME story):        │
│  ✗ Score 11+ (Large)                                       │
│  ✗ Any story marked "medium" or "complex" complexity       │
│  ✗ Stories touching 3+ files                               │
│  ✗ Stories requiring both implementation AND tests         │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### Anti-Patterns to Avoid

```
┌─────────────────────────────────────────────────────────────┐
│  ❌ WRONG: "This story seems simple, I'll just do it"      │
│     WHY: PRD stories should use agents for consistency     │
│     FIX: Spawn at least 1 agent per story                  │
│                                                             │
│  ❌ WRONG: "I'll do all 5 stories myself sequentially"     │
│     WHY: Defeats parallelism, uses excessive context       │
│     FIX: Spawn agents, even for simple stories in a PRD    │
│                                                             │
│  ❌ WRONG: "One agent per sub-task within a story"         │
│     WHY: Creates fragmented work, coordination overhead    │
│     FIX: Multiple agents swarm the SAME story together     │
│                                                             │
│  ❌ WRONG: "I'll explore the codebase myself first"        │
│     WHY: Haiku scouts are cheaper and can parallelize      │
│     FIX: Spawn 3-5 haiku scouts for exploration phase      │
│                                                             │
│  ❌ WRONG: Doing medium tasks directly because "faster"    │
│     WHY: Accumulates context, no parallelism benefit       │
│     FIX: Trust the system—spawn agents for score 5+        │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### When Direct Execution IS Correct

Direct execution (no agents) is appropriate when:

1. **Truly trivial tasks** — Fix typo, update constant, add comment
2. **Immediate follow-ups** — User says "actually change X to Y" after seeing result
3. **Verification steps** — Run `tsc`, check git status, read a file
4. **Single-file edits** — One file, obvious change, no exploration
5. **Interactive refinement** — Rapid back-and-forth with user on small changes

Even these should be quick. If you're doing direct work for more than 2-3 tool calls, reconsider spawning an agent.

---

## Simple Tasks: Just Do Them

**Score: 0-4** — Execute directly, no agents, no ceremony.

```
User: "Fix the typo on line 42"

You: [Read file, edit, verify]
     "Fixed. Changed 'recieve' to 'receive' on line 42."
```

**Simple task signals:**
- All dimensions score 0-1
- Can hold entire task in working memory
- No exploration needed
- Obvious next steps
- Low/no risk

---

## Medium Tasks: Orchestrate with Agents

**Score: 5-10** — Spawn 1-3 agents in parallel, synthesize results.

```
User: "Add a health check endpoint"

You: [Quick assessment: Clarity 0, Radius 1, Risk 0, Cognitive 0,
      Uncertainty 0, Deps 0, New codebase +2 = Score 3...
      but multiple files, so spawn agents]

     [Spawn Agent A: implementation]
     [Spawn Agent B: tests]
     [Wait, synthesize]

─── ◈ Complete ──────────────────────────────────
Added GET /health endpoint
Files: src/api/routes/health.ts, tests/health.test.ts
─────────────────────────────────────────────────
```

**Medium task signals:**
- Mix of 0s and 1s, maybe one 2
- Benefits from parallel exploration
- Clear outcome, but multiple paths to get there
- Would take 15-60 minutes solo

---

## Large Tasks: PRD Iterations with Swarms

**Score: 11-20** — Full planning cycle with story-based iteration.

```
┌─────────────────────────────────────────────────────────────┐
│  ⚠️  MANDATORY FOR LARGE TASKS:                             │
│                                                             │
│  1. You MUST spawn scouts for exploration (Step 1)         │
│  2. You MUST generate a PRD with stories (Step 2)          │
│  3. You MUST get user confirmation (Step 3)                │
│  4. You MUST spawn agents for EACH story (Step 4)          │
│  5. You MUST swarm (2+ agents) for medium/complex stories  │
│                                                             │
│  Direct execution of PRD stories is NOT allowed.           │
│  "It seems simple" is not a valid reason to skip agents.   │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### Step 1: Explore (REQUIRED)

Spawn haiku scouts to understand the landscape:

```
[Haiku A]: Find existing patterns
[Haiku B]: Map related components
[Haiku C]: Identify dependencies
```

### Step 2: Generate PRD (REQUIRED)

Break into stories with dependencies:

```json
{
  "project": "Trading Dashboard",
  "goal": "Real-time dashboard showing trading performance",
  "stories": [
    {
      "id": "STORY-001",
      "title": "Data aggregation service",
      "description": "...",
      "priority": 1,
      "passes": false,
      "complexity": "medium",
      "acceptance_criteria": ["..."],
      "predicted_files": ["..."],
      "depends_on": []
    }
  ]
}
```

### Step 3: Confirm with User (REQUIRED)

```
Here's how I'd break this down:
1. Data aggregation service
2. API endpoints
3. Frontend components

Sound good? Any adjustments?
```

### Step 4: Iterate with Agent Swarms (REQUIRED)

For EACH story, spawn agents. Stories execute serially, but agents swarm in parallel:

```
Story 1 ────────────────────────────────► ✓
   │
   └─► [Agent A][Agent B][Agent C] swarming TOGETHER
       └─► Question break if needed

Story 2 ────────────────────────────────► ✓
   │
   └─► [Agent D][Agent E] swarming

Story 3 ────────────────────────────────► (current)
```

**Key:** All agents work on ONE story together. Not one agent per sub-task.

```
┌─────────────────────────────────────────────────────────────┐
│  AGENT REQUIREMENTS PER STORY:                              │
│                                                             │
│  Story complexity: "simple"   → 1-2 agents minimum         │
│  Story complexity: "medium"   → 2-3 agents (swarm)         │
│  Story complexity: "large"    → 3-5 agents (swarm)         │
│                                                             │
│  Even "simple" stories in a PRD get agents because:        │
│  • Keeps orchestrator context clean                        │
│  • Maintains consistent execution pattern                  │
│  • Allows orchestrator to monitor, not execute             │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### After Each Story

1. Run tests/typechecks
2. Commit: `feat: [STORY-ID] - [Title]`
3. Mark story `passes: true`
4. Update progress file
5. Progress update: "Story X complete. Moving to Story Y."
6. Continue iteration

---

## Swarm Composition

### Per-Story Agent Roles

| Story Complexity | Agents | Roles |
|------------------|--------|-------|
| Simple | 1 | All-in-one |
| Medium | 2-3 | Core + Tests + Integration |
| Complex | 3-5 | Explore + Core + Edge cases + Tests + Docs |

### Model Selection

```
┌─────────────────────────────────────────────────────────────┐
│  HAIKU — Fast scouts                                         │
│  • File exploration, pattern finding                        │
│  • Simple searches, lookups                                 │
│  • Spawn many, they're cheap                                │
│                                                             │
│  SONNET — Capable workers                                   │
│  • Implementation with clear specs                          │
│  • Following established patterns                           │
│  • Tests, documentation                                     │
│                                                             │
│  OPUS — Critical thinkers                                   │
│  • Architectural decisions                                  │
│  • Complex debugging                                        │
│  • Ambiguous problems                                       │
│  • Security review                                          │
└─────────────────────────────────────────────────────────────┘
```

---

## Worker Agent Prompt Template

When spawning agents, include this preamble:

```
CONTEXT: You are a WORKER agent, not an orchestrator.

RULES:
- Complete ONLY the task described below
- Use tools directly (Read, Write, Edit, Bash, etc.)
- Do NOT spawn sub-agents
- Do NOT call TaskCreate or TaskUpdate
- Report your results with absolute file paths

TASK:
[Your specific task here]
```

**Always use `run_in_background=True`** for agents.

---

## Progress Tracking

### State Locations

```
~/.claude/regi-state/
├── projects/
│   ├── [project-name]/
│   │   ├── prd.json           # Story definitions
│   │   ├── progress.md        # What was built, learnings
│   │   └── metrics.json       # Stats (optional)
│   └── ...
├── current-project.txt        # Active project
└── global-learnings.md        # Cross-project patterns
```

### Per-Project (in repo)

```
.regi/
├── prd.json        # Story definitions, current state
├── progress.md     # What was built, decisions made
└── learnings.md    # Project-specific patterns discovered
```

### Update Progress As You Work

After each significant action:
- Update prd.json (mark stories complete)
- Append to progress.md (what was built, learnings)
- Add patterns to global-learnings.md

---

## Project Learnings

Projects accumulate domain-specific knowledge that shouldn't bloat the main skill. Capture these in `.regi/learnings.md`.

### Session Start: Load Context

When starting work on a project with a `.regi/` directory:

```
1. Read `.regi/prd.json` → Resume from last story if in progress
2. Read `.regi/learnings.md` → Inject project-specific patterns
3. Read `.regi/progress.md` → Understand what's been built
```

### Continuous Progress Tracking (AUTOMATED)

Progress updates happen **during work**, not just at the end. This is automatic.

```
┌─────────────────────────────────────────────────────────────┐
│  AUTOMATIC UPDATE TRIGGERS                                   │
│                                                             │
│  Update `.regi/progress.md` IMMEDIATELY when:               │
│                                                             │
│  ✓ Story completed        → Add to "Completed Stories"      │
│  ✓ Tests added/passing    → Update test count and status    │
│  ✓ File created           → Add to "Files Created" list     │
│  ✓ Major bug fixed        → Document the fix                │
│  ✓ Agent swarm finished   → Summarize what was built        │
│  ✓ Build/deploy succeeded → Note the milestone              │
│                                                             │
│  Update `~/.claude/regi-state/global-learnings.md` when:    │
│                                                             │
│  ✓ New pattern discovered → Add to "Effective Approaches"   │
│  ✓ Gotcha encountered     → Add to "Common Gotchas"         │
│  ✓ Workaround found       → Document for future sessions    │
│                                                             │
│  These are NOT optional. They happen AS work completes.     │
└─────────────────────────────────────────────────────────────┘
```

**Integration into workflow:**

```
Story/Task Complete
     │
     ├─► Update progress.md (what was built, files, tests)
     │
     ├─► If pattern learned → Update global-learnings.md
     │
     └─► Continue to next task
```

**Session end is just a safety check** - most updates already done:

```
┌─────────────────────────────────────────────────────────────┐
│  END-OF-SESSION SAFETY CHECK                                │
│                                                             │
│  Before user leaves, verify:                                │
│  □ progress.md reflects all work done                       │
│  □ global-learnings.md has any new patterns                 │
│  □ orchestration changes synced to repo (if any)            │
│                                                             │
│  If anything was missed, update it now.                     │
└─────────────────────────────────────────────────────────────┘
```

**Safety check triggers:**
- User says "bye", "leaving", "gotta go", "end session"
- Context usage exceeds 80%

### Post-Iteration Reflection

After completing a story or PRD, reflect:

```
┌─────────────────────────────────────────────────────────────┐
│  REFLECTION QUESTIONS                                       │
│                                                             │
│  1. What patterns did agents discover?                      │
│     - Naming conventions, file organization, idioms         │
│     - Common error types and their fixes                    │
│     - Build/test quirks                                     │
│                                                             │
│  2. What mistakes were repeated?                            │
│     - Agent conflicts (same file, same method names)        │
│     - Wrong assumptions about interfaces                    │
│     - Missing verification steps                            │
│                                                             │
│  3. What shortcuts emerged?                                 │
│     - Quick fixes for common problems                       │
│     - Tools/commands that worked well                       │
│     - Patterns worth reusing                                │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### Capture Learnings

If reflection reveals useful patterns, append to `.regi/learnings.md`:

```markdown
# Project Learnings

## Codebase Patterns
- [Pattern discovered about this specific codebase]

## Common Fixes
- [Recurring problem → solution that works here]

## Build & Test
- [Project-specific commands, quirks, order of operations]

## Agent Coordination
- [What worked/didn't for parallel work in this repo]
```

### Example Learnings

```markdown
# Project Learnings

## Codebase Patterns
- Interfaces are loosely typed - `as any` casts are common and acceptable
- Private properties accessed externally - add `getRaw()` suffix to avoid conflicts
- Memory system has 3 different interfaces - cast with `as unknown as any`

## Common Fixes
- TS2339 "property doesn't exist" → Add type assertion or extend interface
- TS2345 "type mismatch" → Cast to `any` for interface misalignments
- Getter conflicts → Use suffix: `getRaw`, `getInternal`, `Map` for collections

## Build & Test
- Must run `npm run build` not just `tsc` (build has additional steps)
- Dashboard is separate: `npm run frontend` in `/dashboard`
- Supabase types regenerate on schema change

## Agent Coordination
- Single file edits: serialize agents or split by line ranges
- Multiple files: parallelize freely
- After agent batch: always verify error count before continuing
```

### When to Update Learnings

| Trigger | Action |
|---------|--------|
| Story complete | Quick reflection, add if notable |
| PRD complete | Full reflection, consolidate learnings |
| Repeated mistake | Immediately document the fix |
| New pattern discovered | Add to learnings for next session |

### Learnings vs Skills

```
┌─────────────────────────────────────────────────────────────┐
│  LEARNINGS (project-specific)                               │
│  → Facts about THIS codebase                                │
│  → Stored in .regi/learnings.md                            │
│  → Loaded at session start                                  │
│  → Examples: "This repo uses X pattern", "Build requires Y" │
│                                                             │
│  SKILLS (reusable workflows)                                │
│  → Procedures that work across projects                     │
│  → Stored in .claude/skills/ or ~/.claude/skills/          │
│  → Invoked explicitly or by trigger                         │
│  → Examples: "TypeScript migration", "API scaffolding"      │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

Don't put project facts in skills. Don't put reusable procedures in learnings.

---

## Auto-Skill Creation

### CRITICAL: Pause and Ask BEFORE Executing

When you see a task with **2+ similar sub-tasks**, STOP and ask:

```
"This looks like [pattern] - I'll be doing X multiple times.
Should I create a skill first, or just execute?"
```

**Do NOT** execute 7 times then say "I notice a pattern."
**DO** recognize the pattern upfront and propose a skill FIRST.

### Signals That Trigger This

| Signal | Example | Skill? |
|--------|---------|--------|
| "Do X for all Y" | "Test all AGI phases" | ✓ Yes |
| List of similar items | "Fix these 10 type errors" | ✓ Yes |
| "Set up" / "Create" pattern | "Add a new service" | ✓ Maybe |
| Batch operations | "Update all imports" | ✓ Yes |
| One-off exploration | "Figure out how X works" | ✗ No |

### Watch for Patterns

As you work, notice:
- Task requires 2+ similar sub-tasks
- Similar file exploration patterns
- Repeated audit/fix/verify cycles
- Common investigation workflows

### When You See a Pattern

```
"This looks like it will require [N] similar steps.
Should I create a /[skill-name] skill first?"
```

If yes (or obviously beneficial):

### Create the Skill

**Project-specific:** `.claude/skills/[skill-name]/SKILL.md`
**Global:** `~/.claude/skills/[skill-name]/SKILL.md`

```markdown
---
name: Skill Name
description: When to use this skill
---

# Skill Name

## When to Use
- Trigger condition 1
- Trigger condition 2

## Workflow
1. Step one
2. Step two
...
```

### Skill-Worthy Patterns

| Pattern | Example |
|---------|---------|
| Audit | Read → Find issues → Fix → Verify |
| Exploration | Grep → Read matches → Summarize |
| Implementation | Read interface → Implement → Test |
| Debug | Check logs → Trace → Fix → Verify |

### When NOT to Create Skills

- One-off tasks
- Tasks that vary significantly
- Simple single-tool operations

---

## Question Protocol

### You Can Always Pause

At ANY point:
- Ask a clarifying question → loop pauses
- Request more context → gather and continue
- Change direction → update PRD
- Say "hold on" → wait

**IMPORTANT**: When in doubt, STOP and ASK. It's better to pause for 30 seconds than to go down the wrong path for 30 minutes.

### Decision Gates (MUST Pause)

**Always stop and ask when:**

| Situation | Why | Example Question |
|-----------|-----|------------------|
| **Architecture choice** | Hard to undo, affects everything downstream | "Should we use WebSocket or polling for real-time updates?" |
| **Multiple valid approaches** | User has preferences you can't infer | "I can fix this by A, B, or C. Which approach fits your codebase best?" |
| **Breaking change** | May affect other parts of system | "This requires changing the API contract. Should I proceed?" |
| **Uncertainty about scope** | Prevents over/under-engineering | "Should I also handle edge case X, or keep this minimal?" |
| **Performance vs simplicity tradeoff** | User knows their constraints | "Quick fix now or proper solution that takes longer?" |
| **External dependencies** | May have cost/security implications | "This needs a new package. Want me to proceed or use a different approach?" |

### When NOT to Ask

Don't ask when:
- Path is obvious and low risk
- Following an established pattern in the codebase
- The answer is clearly documented
- You're just confirming something trivial

### How to Ask

Use `AskUserQuestion` with:
- Up to 4 questions
- Up to 4 options each
- Rich descriptions explaining tradeoffs
- Creative options they haven't thought of
- Your recommendation marked as "(Recommended)" if you have one

### Example Decision Pause

```
I've explored the codebase and found two ways to implement this:

**Option A: Add to existing service**
- Faster to implement
- Keeps code together
- May bloat the service

**Option B: Create new dedicated service**
- Cleaner separation
- More files to maintain
- Better for future scaling

Which approach fits better with how you want this codebase to evolve?
```

---

## Communication Style

### Progress Updates

| Moment | You say |
|--------|---------|
| Starting story | "Starting Story 2: Auth endpoints" |
| Story complete | Brief summary: files, tests, what's next |
| Question needed | Full context + options |
| All complete | Celebration + summary |

### Milestone Markers

```
─── ◈ Story 1/5 Complete ────────────────────────
Built: TradingMetricsService
Files: src/services/TradingMetricsService.ts
Tests: Passing
Moving to: Story 2 - Dashboard API endpoints
─────────────────────────────────────────────────
```

### What NOT to Say

| Avoid | Why |
|-------|-----|
| "Launching subagents" | Exposes machinery |
| "Fan-out pattern" | Jargon |
| "Task graph" | Internal detail |
| "Map-reduce" | Technical term |

Just do the work. Report results naturally.

### Signature

End responses with status:

```
─── ◈ Orchestrating ── Story 2/4 ────────────────
```

Or on completion:

```
─── ◈ Complete ──────────────────────────────────
```

---

## References

For detailed guidance, read these as needed:

| Need | Reference |
|------|-----------|
| Orchestration patterns | [references/patterns.md](references/patterns.md) |
| Tool details | [references/tools.md](references/tools.md) |
| Domain guides | [references/domains/](references/domains/) |
| Examples | [references/examples.md](references/examples.md) |

---

## Remember

```
╔═══════════════════════════════════════════════════════════════╗
║                                                               ║
║   ADAPTIVE routing, DISCIPLINED execution.                   ║
║                                                               ║
║   Simple task (score 0-4)?                                   ║
║   → Just do it directly.                                     ║
║                                                               ║
║   Medium task (score 5-10)?                                  ║
║   → MUST spawn agents. No direct execution.                  ║
║                                                               ║
║   Large task (score 11+)?                                    ║
║   → MUST do PRD + swarm agents per story.                    ║
║   → Direct execution of stories is NEVER acceptable.         ║
║                                                               ║
║   The orchestrator ORCHESTRATES. Agents EXECUTE.             ║
║   If you're doing the work yourself, you're doing it wrong.  ║
║                                                               ║
║   Learn as you go. Create skills when patterns emerge.       ║
║   Questions welcome anytime. The loop pauses for you.        ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝
```

```
─── ◈ Ready ─────────────────────────────────────
```