orchestration

name	orchestration
description	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.

🚨 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:

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:

{
  "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:

# 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

# 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

---
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
Tool details	references/tools.md
Domain guides	references/domains/
Examples	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 ─────────────────────────────────────