---

description: Universal entry point - delegates to appropriate workflow argument-hint: <requirement> allowed-tools: Read, Glob, Grep, Task, AskUserQuestion

/do - Universal Workflow Entry Point

Single command interface for all workflows. Analyzes requirements and directly orchestrates expert agents through plan-build-improve cycles.

CRITICAL: Orchestration-First Approach

ABSOLUTE RULE: DELEGATE EVERYTHING

IMPORTANT: First and foremost, remember that you should delegate as much as possible to subagents. Even reading and writing single files MUST be delegated to subagents.

This command exists to orchestrate workflows—NOT to do work directly. You are a dispatcher, not a worker.

Your ONLY responsibilities:

1. Parse and classify requirements
2. Select the appropriate pattern (A, B, or C)
3. Spawn expert agents via Task tool
4. Wait for results
5. Synthesize and report outcomes

You MUST NOT:

• Read files directly (delegate to agents)
• Write files directly (delegate to agents)
• Make code changes (delegate to agents)
• Make implementation decisions (delegate to plan-agent)
• Answer domain questions directly (delegate to question-agent)

Why This Matters:

• Expert agents have domain-specific context in their prompts
• Expert agents have access to expertise.yaml knowledge
• Direct work bypasses the plan-build-improve learning cycle
• Direct work doesn't update expertise for future improvements

The Golden Rule

If you're about to use Read, Write, Edit, or Grep—STOP. Spawn an agent instead.

The actual work happens in expert agents via the plan-build-improve cycle. You orchestrate. They execute.

Purpose

The /do command is the universal orchestrator for all workflows. It analyzes your requirement, determines the appropriate workflow pattern, and directly orchestrates expert agents through plan-build-improve cycles with user approval gates.

How It Works

1. Parse Requirement: Extract what you need done
2. Classify Type: Determine workflow (expert domain or simple operation)
3. Route to Handler:
   • For expert implementations: Spawn plan-agent - user approval - build-agent - improve-agent
   • For questions: Spawn question-agent
   • For simple workflows: Spawn specialized agent
4. Orchestrate Workflow: Manage plan-build-improve cycle with approval gates
5. Report Results: Synthesize and present outcomes

CRITICAL: Execution Control Rules

IMPORTANT: The base /do agent MUST wait for all subagent work to complete before responding. Premature exit causes incomplete results and user confusion.

Rule 1: Never Use Background Execution for Task Tool

Task tool calls MUST NOT use run_in_background: true.

The Task tool is inherently blocking—it waits for the subagent to complete before returning. There is no run_in_background parameter for Task (that's a Bash tool feature).

Correct Task Usage:

Task(
  subagent_type: "claude-config-plan-agent",
  prompt: |
    USER_PROMPT: {requirement}
)

Incorrect (DO NOT USE):

Task(
  subagent_type: "claude-config-plan-agent",
  prompt: |
    USER_PROMPT: {requirement}
  run_in_background: true  # NOT a valid Task parameter
)

Rule 2: Wait for ALL Task Results Before Responding

You MUST collect and process the full output from EVERY Task call before generating your final response.

The Task tool blocks until the subagent completes. However, you must explicitly:

1. Wait for the Task call to return (don't interrupt or respond prematurely)
2. Capture the full output from the subagent
3. Process the results (synthesize, extract file paths, etc.)
4. Only then generate the final report

Anti-Pattern:

# WRONG: Responding before Task completes
Use Task(...) to spawn claude-config-plan-agent

## `/do` - Complete
Handler: claude-config
Results: Working on it...

Correct Pattern:

# CORRECT: Wait, collect, then respond
Use Task(...) to spawn claude-config-plan-agent
[WAIT for Task to complete and return results]
[CAPTURE the full output]
[EXTRACT file paths, status, next steps]

## `/do` - Complete
Handler: claude-config
Results: [synthesized from actual output]
Files Modified: [extracted from output]
Next Steps: [from handler recommendations]

Rule 3: Parallel Execution Must Still Block

For parallel subagent execution, spawn ALL agents in a SINGLE message, then wait for ALL to complete.

Parallel Pattern:

# Spawn multiple in parallel (single message, multiple Task calls)
Use Task(subagent_type: "claude-config-question-agent", prompt: ...)
Use Task(subagent_type: "agent-authoring-question-agent", prompt: ...)

# Task tool executes these in parallel but blocks until ALL complete
# Now collect results from both:
[CAPTURE claude-config output]
[CAPTURE agent-authoring output]

# Now synthesize and respond

The Task tool handles parallelism automatically when you make multiple calls in one message. You don't need (and must not use) run_in_background.

Why This Matters

In --print mode and other execution contexts:

• The base agent's output is the user's only feedback
• If you exit before subagents complete, their work is lost
• Results appear empty even though subagents ran successfully
• User sees "complete" but no actual results

Always wait. Always collect. Always synthesize before reporting.

Rule 4: Orchestration Sequence for Expert Implementations

For expert domain implementation requests, /do MUST orchestrate the plan-build-improve cycle directly.

Orchestration Pattern:

# Step 1: Plan Phase
Use Task(subagent_type: "<domain>-plan-agent", prompt: "USER_PROMPT: {requirement}")
[WAIT for plan-agent to complete]
[EXTRACT spec_path from output]

# Step 2: User Approval Gate
Use AskUserQuestion(
  question: "Plan complete. Spec saved to {spec_path}. Proceed with implementation?",
  options: ["Yes, continue to build", "No, stop here - I'll review first"]
)
[WAIT for user response]

# If user says "No":
#   Report spec location, suggest resuming with /do "build from {spec_path}"
#   Exit gracefully

# Step 3: Build Phase (if approved)
Use Task(subagent_type: "<domain>-build-agent", prompt: "PATH_TO_SPEC: {spec_path}")
[WAIT for build-agent to complete]
[EXTRACT files modified from output]

# Step 4: Improve Phase (always run, but non-blocking on failure)
Use Task(subagent_type: "<domain>-improve-agent", prompt: "Review recent changes for domain expertise updates")
[WAIT for improve-agent to complete]
[CAPTURE expertise updates, but don't fail workflow if this fails]

# Step 5: Synthesize and Report

Why This Pattern:

• Plan must complete before user can approve
• Build must wait for approval (prevents unwanted implementations)
• Improve is opportunistic (workflow succeeds even if improve fails)
• All phases block on Task completion before proceeding

Sequential Dependencies: Build depends on spec_path from plan. Improve depends on build completing (changes to analyze). User approval depends on spec being ready to review.

Error Handling:

• Plan fails - report error, exit (no spec to build from)
• User declines - save spec location, exit gracefully (valid outcome)
• Build fails - preserve spec, report error, skip improve
• Improve fails - log error, but workflow succeeds (improvement is bonus)

---

Step 1: Parse Arguments

Extract requirement from $ARGUMENTS:

• Remove any flags (future: --background, --plan-only, etc.)
• Capture the core requirement description

Step 2: Classify Requirement

Analyze the requirement to determine type and pattern. Expert domains take priority when implementation is needed.

---

Expert Domain Requests (Priority - Check First)

Claude Config Expert

• Keywords: "slash command", "command", "hook", "settings.json", ".claude config", "settings", "frontmatter"
• Locations: References to .claude/commands/, .claude/hooks/, .claude/settings.json
• Indicators: Command creation, hook implementation, .claude/ directory organization
• Examples: "Create new slash command for X", "Add hook for Y event", "Configure settings"

Agent Authoring Expert

• Keywords: "create agent", "new agent", "agent config", "tool selection", "agent description", "agent frontmatter", "agent registry"
• Locations: References to .claude/agents/, agent creation, expert domain setup
• Indicators: Agent file creation, tool set decisions, model selection for agents
• Examples: "Create a new scout agent", "Configure tools for the build agent", "Add new expert domain"

Database Expert

• Keywords: "schema", "migration", "SQLite", "FTS5", "database", "query", "index", "table"
• Locations: References to app/src/db/, sqlite-schema.sql
• Indicators: Database schema changes, migrations, query optimization
• Examples: "Create migration for X", "Optimize query for Y", "Add FTS5 search"

API Expert

• Keywords: "endpoint", "route", "MCP tool", "API", "HTTP", "server", "OpenAPI"
• Locations: References to app/src/api/, app/src/mcp/
• Indicators: API endpoint creation, MCP tool implementation, server routes
• Examples: "Add endpoint for X", "Create MCP tool for Y", "Update OpenAPI spec"

Testing Expert

• Keywords: "test", "antimocking", "Bun test", "sqlite test", "test lifecycle"
• Locations: References to app/tests/, tests/
• Indicators: Test creation, test fixes, testing strategy
• Examples: "Write tests for X", "How do I test Y", "Add integration test"

Indexer Expert

• Keywords: "AST", "parser", "symbol", "reference", "indexing", "code analysis"
• Locations: References to app/src/indexer/
• Indicators: Code indexing, symbol extraction, AST parsing
• Examples: "Extract symbols from X", "Index repository", "Parse AST for Y"

GitHub Expert

• Keywords: "issue", "PR", "pull request", "branch", "commit", "gh CLI", "GitHub"
• Locations: References to .github/, issues commands
• Indicators: GitHub workflow operations, issue management, PR creation
• Examples: "Classify issue", "Create PR for X", "Branch naming for Y"

Documentation Expert

• Keywords: "docs", "README", "documentation", "API reference", "architecture docs", "CLAUDE.md", "user guide", "installation docs"
• Locations: References to web/docs/content/, .claude/agents/, CLAUDE.md
• Indicators: Documentation updates, README changes, API docs, user guides
• Examples: "Update README for X", "Add API documentation", "Fix installation docs"

Web Expert

• Keywords: "web", "homepage", "blog", "CSS", "design system", "Liquid Glass", "kotadb.io", "marketing site", "static site"
• Locations: References to web/, web/docs/, web/blog/
• Indicators: Homepage updates, blog posts, CSS changes, design system work
• Examples: "Update homepage", "Add blog post", "Fix CSS styling", "Update design system"

Pattern Classification (After Domain Identified)

Once expert domain is identified, determine which pattern:

Implementation Request (Pattern A):

• Verbs: fix, add, create, implement, update, configure, refactor
• Objects: Concrete things to build/change
• Pattern: Use Pattern A (Plan-Build-Improve)

Question Request (Pattern B):

• Phrasing: "How do I...", "What is...", "Why...", "Explain...", "When should I..."
• Pattern: Use Pattern B (Question-Agent)

Simple Operation (Pattern C):

• Verbs: regenerate, format, lint, compile
• Objects: Single-purpose operations
• Pattern: Use Pattern C (Simple Workflow)
• Examples: "Format file X", "Run linter"

Ambiguous - Ask user for clarification

• Multiple possible interpretations
• Use AskUserQuestion to disambiguate

---

Step 3: Determine Handler Type

Based on classification, determine which orchestration pattern to use:

Pattern A: Expert Implementation (Plan-Build-Improve)

• Triggers: Expert domain + implementation request
• Examples: "Create new slash command for X", "Add hook for logging", "Create new agent", "Create migration for X", "Add MCP tool for Y", "Write tests for X", "Ind