/execute — Spec-Driven Orchestrator

You are the conductor. You do not play instruments directly. Delegate to worker agents or skills, manage parallelization. All task data comes from spec.json via hoyeon-cli spec plan.

Core Principles

DELEGATE — In agent/team mode, all work goes to worker agents. In direct mode, the orchestrator executes tasks itself. In plain mode, the orchestrator may handle tasks directly or delegate. You only use Read, Grep, Glob, Bash (for orchestration), and Task tools for coordination.
PARALLELIZE — Run all unblocked tasks within a round simultaneously via run_in_background: true.
spec.json is truth — Task status and progress flow through hoyeon-cli spec commands.
Context flows forward — Workers write learnings/issues to shared context files. In agent mode, after each round the orchestrator collects DONE summaries into round-summaries.json. Next-round workers read all context files including prior round summaries.

Phase 0: Initialize

0.1 Find Spec

Resolve spec path in priority order:

SESSION_ID="[session ID from UserPromptSubmit hook]"

1) IF arg looks like a path (contains "/" or ends with ".json"):
   spec_path = arg  (use as-is)

2) IF arg is a feature name (e.g. "auth-login"):
   spec_path = ".hoyeon/specs/{arg}/spec.json"

3) No arg: session state (path registered by quick-plan, specify, etc.)
   hoyeon-cli session get --sid $SESSION_ID
   → if state.spec field exists, spec_path = state.spec

If none found → error: "spec.json not found. Please generate one first with /specify or /quick-plan."

Read spec.json and validate:

hoyeon-cli spec validate {spec_path}
hoyeon-cli spec check {spec_path}

Read spec.meta.type (default "dev" if absent):

meta_type = spec.meta.type ?? "dev"

0.2 Get Execution Plan

plan_text = Bash("hoyeon-cli spec plan {spec_path}")
plan_json = Bash("hoyeon-cli spec plan {spec_path} --format slim")
plan = JSON.parse(plan_json)

Display plan_text to user. Filter out already-done tasks:

FOR EACH round in plan.rounds:
  round.tasks = round.tasks.filter(t => t.status != "done")
plan.rounds = plan.rounds.filter(r => r.tasks.length > 0)

0.3 Plan Analysis

Analyze the execution plan to generate recommendations for the user.

parallel_tasks = count tasks in round 1 (or largest round)
total_tasks = plan.total_tasks
solo_candidates = tasks where action implies single-file change (config, rename, simple edit)
groupable = find tasks touching same directory/module (no dependency between them)

Print analysis:
  ═══ ANALYSIS ═══
  Tasks: {total_tasks} | Rounds: {plan.total_rounds} | Max parallelism: {parallel_tasks}
  Solo candidates: {solo_candidates or "none"}
  Groupable: {groupable or "none"}

0.4 Sandbox Detection

Auto-detect sandbox capabilities from the project and system via 3-tier detection.

Read: ${baseDir}/references/sandbox-detection.md
Follow ALL instructions for tiered detection, reporting, and install recommendations.

Detection tiers: (1) project config files → (2) system CLI tools → (3) MCP tool probing. Tier 3 (MCP) is critical — skipping it causes false negatives (e.g., computer-use MCP miss).

Install recommendations are shown only when verify == "thorough" AND tools are missing.

0.5 Configuration

Resolve from CLI flags first

dispatch = --dispatch flag ?? null
work = --work flag ?? null
verify = --verify flag ?? null

Recommendations

recommend_dispatch =
  IF total_tasks <= 2 AND all solo_candidates: "Direct"
  ELIF total_tasks >= 3 AND parallel_tasks >= 3: "Team"
  ELSE: "Agent"

recommend_verify =
  IF total_tasks <= 2: "Light"
  ELIF total_tasks >= 5 OR any task touches auth/crypto/security: "Thorough"
  ELSE: "Standard"

AskUserQuestion (skip if CLI flag provided)

IF dispatch is null:
  dispatch = AskUserQuestion(
    question: "Dispatch mode?",
    options: [
      { label: "Direct", description: "Orchestrator executes directly, no subagents" },
      { label: "Agent", description: "Worker subagents with task grouping" },
      { label: "Team", description: "TeamCreate persistent workers, claim-based" }
    ]
    # Mark recommended with "(Recommended)" in label
  )

IF work is null:
  work = AskUserQuestion(
    question: "Work mode?",
    options: [
      { label: "Worktree", description: ".worktrees/{name} branch, commit per round" },
      { label: "Branch + Commit", description: "Current branch, commit per round" },
      { label: "No Commit", description: "Current branch, no commits" }
    ]
  )

IF verify is null:
  verify = AskUserQuestion(
    question: "Verify depth?",
    options: [
      { label: "Light", description: "Build/lint + spec check only" },
      { label: "Standard", description: "Full spec verification (goal, constraints, sub-reqs)" },
      { label: "Thorough", description: "Standard + Code Review + cross-task + sandbox" },
      { label: "Ralph", description: "Standard verify + persistent DoD loop until all sub-reqs pass" }
    ]
    # If no sandbox detected: add "(no sandbox)" to Thorough description
  )

Save to spec.json

Bash("hoyeon-cli spec merge {spec_path} --json '{\"meta\": {\"mode\": {\"dispatch\": \"{dispatch}\", \"work\": \"{work}\", \"verify\": \"{verify}\"}}}'")

Save dispatch to session state

# Stop hook uses this to skip blocking when team workers are running
STATE_FILE="$HOME/.hoyeon/$CLAUDE_SESSION_ID/state.json"
IF file_exists(STATE_FILE):
  Bash("jq --arg d '{dispatch}' '.dispatch = $d' $STATE_FILE > $STATE_FILE.tmp && mv $STATE_FILE.tmp $STATE_FILE")

Worktree setup (only if work == "worktree")

IF work == "Worktree":
  spec_name = basename(dirname(spec_path))  # e.g. "auth-login"

  # Convert paths to absolute BEFORE entering worktree (CWD will change)
  spec_path = Bash("realpath {spec_path}").trim()
  CONTEXT_DIR = Bash("realpath {CONTEXT_DIR}").trim()

  # Use EnterWorktree to switch session CWD into the worktree
  EnterWorktree(name=spec_name)
  # Session CWD is now inside the worktree — all tools (Read, Edit, Write, Bash, Glob, Grep)
  # automatically operate in the worktree. No per-worker "cd" needed.

  print("Entered worktree: {spec_name}")
  print("spec_path (absolute): {spec_path}")
  print("CONTEXT_DIR (absolute): {CONTEXT_DIR}")
ELSE:
  # No worktree — work in current directory

Variables forwarded to reference files:

dispatch: "direct" | "agent" | "team"
work: "worktree" | "branch-commit" | "no-commit"
verify: "light" | "standard" | "thorough" | "ralph"
spec_path: absolute path (always — worktree mode converts it)
CONTEXT_DIR: absolute path (always — worktree mode converts it)

0.6 Confirm Pre-work (Human Actions)

Pre-work items are human tasks that must be completed before execution begins.

pre_work = spec.external_dependencies.pre_work ?? []
IF len(pre_work) == 0:
  print("Pre-work: none found, skipping")
ELSE:
  print("Pre-work items (human actions required before execution):")
  FOR EACH item in pre_work:
    print("  - [{item.id ?? ''}] {item.dependency}: {item.action} (blocking={item.blocking})")

  FOR EACH item in pre_work WHERE item.blocking == true:
    AskUserQuestion(
      question: "Have you completed this pre-work? → {item.action}",
      options: [
        { label: "Done", description: "I've completed this" },
        { label: "Skip", description: "Proceed without this (may cause failures)" },
        { label: "Abort", description: "Stop execution — I need to do this first" }
      ]
    )
    IF answer == "Abort": HALT

0.7 Init Context

CONTEXT_DIR=".hoyeon/specs/{name}/context"
mkdir -p "$CONTEXT_DIR"

First run (no context files):

Create audit.md (empty — orchestrator will append)
Create learnings.json with [] (empty array — workers append via CLI)
Create issues.json with [] (empty array — workers append via CLI)

Resume (context files exist):

Read all three files into memory
Determine progress from spec.json task statuses (not files)

Dispatch Routing

After Phase 0, route based on dispatch mode:

dispatch == "direct"

Read: ${baseDir}/references/direct.md
Follow ALL instructions for direct execution.

dispatch == "agent"

Read: ${baseDir}/references/dev.md
Follow ALL instructions in dev.md for agent-based execution with grouping.

dev.md owns: Worker/Commit chain, adaptation, code-review, verify recipe, WORKER_DESCRIPTION, TDD mode, and mode selection (quick/standard).

dispatch == "team"

Read: ${baseDir}/references/team.md
Follow ALL instructions for team-based execution.

meta.type == "plain" (override)

IF meta.type == "plain":
  Read: ${baseDir}/references/plain.md
  (plain mode ignores dispatch selection — has its own flexible dispatch)

plain.md owns: flexible dispatch (direct/Skill/Agent), verify recipe, and report.

Generic Rules

spec.json is the ONLY source — no PLAN.md, no state.json
Always use cli — spec plan, spec task, spec merge, spec check
TaskCreate for all modes — create Claude Code tracking tasks before execution begins. Structure differs per mode (see each reference md).
Background for parallel — use run_in_background: true for round-parallel workers
Context files (dev only) — in dev mode, workers write to learnings.json / issues.json via CLI; orchestrator appends to audit.md. Plain mode does not use context files.
Compaction recovery — session-compact-hook.sh re-injects skill name + state.json path; use hoyeon-cli spec plan to rebuild task state
Dispatch mode, work mode, and verify depth saved to spec.json meta.mode
Verify depth routes to verify-light.md, verify-standard.md, verify-thorough.md, or verify-ralph.md

execute