| 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. |
The Regi System
╔═══════════════════════════════════════════════════════════════╗
║ ║
║ 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:
- Execute the specific task in your prompt
- Use tools directly — Read, Write, Edit, Bash, etc.
- Do NOT spawn sub-agents — you are the worker
- Do NOT manage tasks — the orchestrator handles TaskCreate/TaskUpdate
- 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:
- Truly trivial tasks — Fix typo, update constant, add comment
- Immediate follow-ups — User says "actually change X to Y" after seeing result
- Verification steps — Run
tsc, check git status, read a file - Single-file edits — One file, obvious change, no exploration
- 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
- Run tests/typechecks
- Commit:
feat: [STORY-ID] - [Title] - Mark story
passes: true - Update progress file
- Progress update: "Story X complete. Moving to Story Y."
- 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 ─────────────────────────────────────