/quick-plan — Session Task Planner

Take user's session goals and produce an optimized execution plan that maximizes parallelism.

Workflow

Phase 1: Gather Context

Read CLAUDE.md and recent git log to understand project state
If user's goals are vague, ask up to 2 clarifying questions via AskUserQuestion
If goals are clear, skip straight to Phase 2

Phase 1.5: Quick Discovery (conditional)

Run a lightweight codebase scan to improve touch zone accuracy and discover verification commands.

IF user's goals involve code changes (likely type: dev tasks):
  Agent(subagent_type="code-explorer",
        prompt="Find: project structure, key directories, test/lint/build commands (package.json scripts, Makefile, etc.), and files related to [user's goal areas]. Report as file:line format.")

  → Store results for Phase 5 (tool discovery) and Phase 9 (context.research merge)

IF goals are purely non-code (research, analysis, documentation):
  → Skip discovery entirely

Cost: ~10-15 seconds for 1 agent. Benefit: touch zones reference real files, verification commands auto-discovered.

Phase 2: Task Decomposition

Break goals into atomic tasks. Each task must be:

Single-responsibility: one clear deliverable
Verifiable: has a clear done condition
Assignable: can be given to one agent

Sweet spot: 3-8 tasks per session. Prefer fewer larger tasks over many tiny ones.

Phase 3: Dependency Analysis

For each task determine:

blockedBy: what must complete first?
blocks: what does this unblock?
parallel?: can it run alongside other tasks?

Build a DAG. Minimize sequential depth — maximize parallel width.

Phase 3.5: Overlap Analysis

For each task, identify its touch zone — the files and modules it will modify.

List touch zones: For each task, enumerate target files/directories
Detect overlaps: If two tasks modify the same file or tightly-coupled module:
- Merge: Combine into one task if small enough
- Serialize: Make one block the other if merging is too large
- Never: Let overlapping tasks run in parallel (guaranteed merge conflicts)
No overlap → mark as parallel-safe

Output an overlap matrix in Phase 7 if any overlaps were found.

Phase 3.7: Context Sharing Strategy

Even when tasks are orthogonal in code, agents benefit from shared context.

For each task, determine:

Needs to know: What context from other tasks improves this agent's decisions?
Produces: What results/decisions should be shared with downstream agents?

Patterns:

Summary injection: Give each agent a 1-line summary of what sibling agents are doing
Result forwarding: Pass prior round outputs as read-only context to next round agents
Shared decisions doc: If multiple agents need the same architectural decision, resolve it in Round 0

Rule: Code changes = orthogonal, Information = shared.

Phase 4: Coordination Mode Decision

Decide between two modes:

	Agent spawn (default)	Team mode
Pattern	Fan-out/fan-in	Persistent agents
Communication	Orchestrator relays results	Agents message each other directly
Task discovery	Static (all known upfront)	Dynamic (new tasks found during execution)
Agent lifecycle	Spawn → result → done	Spawn → work → idle → pick up next task

Rule: Orchestrator relay sufficient → agent-spawn. Agents need direct communication → team.

Phase 5: Tool Discovery

For each task, perform priority-based tool discovery by scanning skill and agent directories in order:

Scan order (highest priority first):

Plugin scope: ${baseDir}/.claude/skills/ and ${baseDir}/.claude/agents/
- Read each SKILL.md / agent.md description field
Project scope: {project_root}/.claude/skills/ and {project_root}/.claude/agents/
- {project_root} = directory containing the project's CLAUDE.md
User scope: ~/.claude/skills/ and ~/.claude/agents/
Default fallback: Agent tool's subagent_type list → general-purpose

Matching logic per task:

Match the task description against skill/agent description fields (semantic similarity)
First match wins (plugin scope takes priority over project, project over user, user over default)
Record both the matched tool and where it was found (source)

Assignment rules:

Match result	task.tool	task.type
Skill found	`/skill-name` (e.g., `/bugfix`)	`plain` (unless skill does code changes → `dev`)
Agent found	`agent-subtype` (e.g., `worker`)	`dev` if code changes, else `plain`
Code changes needed, no match	`worker`	`dev`
No code changes, no match	`general-purpose`	`plain`

type inference heuristics:

dev: task modifies source files, writes code, runs tests → requires dev pipeline
plain: task reads, analyzes, documents, or invokes a skill that handles its own execution

Phase 6: Execution Plan

Group tasks into parallel rounds:

Round 1: All tasks with no dependencies (launch simultaneously)
Round 2: Tasks unblocked by Round 1
Round N: Continue until all scheduled

For each round specify:

Which agents launch in parallel
What context/results they need from prior rounds
Whether they need isolation: "worktree" (code changes that might conflict)

Phase 7: Present Plan

Output the complete plan in this format:

## Task Breakdown

1. **{task-name}**: {description} → Done when: {condition} | Touch: `{files/dirs}`
2. ...

## Dependency DAG

{ASCII diagram}

## Overlap Matrix (if any)

| Task A | Task B | Shared files | Resolution |
|--------|--------|-------------|------------|
| 1 | 3 | types.ts | Serialize (1→3) |

## Context Sharing

| Round | Agent | Receives context from |
|-------|-------|----------------------|
| 2 | C | A's output summary |

## Coordination Mode

mode: agent-spawn | team
rationale: {one-line reason}

## Agent Mapping

| # | Task | Tool | Type | Source | Rationale |
|---|------|------|------|--------|-----------|
| 1 | ... | worker | dev | default | ... |

## Execution Plan

### Round 1 (Parallel)
- Agent A: {task} — no dependencies | context: sibling summary
- Agent B: {task} — no dependencies | context: sibling summary

### Round 2 (After Round 1)
- Agent C: {task} — needs results from A | context: A's output + sibling summary

## Estimated Parallelism

- Total tasks: N
- Sequential depth: M rounds
- Max parallel width: K agents

After presenting the plan, proceed immediately to Phase 8 (do NOT wait for approval).

Phase 8: Next Action

Ask user via AskUserQuestion:

The plan is ready. What would you like to do?

1. Execute — generate spec.json and run /execute immediately
2. Revise plan — let me know what you'd like to change
3. Discuss further — let me know if anything needs more review

If user chooses 1 (Execute): proceed to Phase 9
If user chooses 2 or 3: handle feedback, revise plan, then re-ask Phase 8

Phase 9: Generate spec.json & Execute

Only runs when user explicitly chooses to execute.

9.1 Session Directory

SESSION_ID="[session ID from UserPromptSubmit hook]"
SESSION_DIR="$HOME/.hoyeon/$SESSION_ID"
SPEC_PATH="$SESSION_DIR/spec.json"

9.2 Initialize spec.json

Determine the plan type based on task composition from Phase 5:

If any task has type: dev → use --type dev (dev pipeline with worktree isolation)
If all tasks have type: plain → use --type plain (lightweight skill-only pipeline)

hoyeon-cli spec init {plan-name} --goal "{user's goal}" --type dev|plain --schema v1 ${SPEC_PATH}

{plan-name}: derive from user's goal (kebab-case, max 30 chars).

9.2.5 Merge lightweight requirements

Before merging tasks, generate lightweight requirements from the task breakdown. Each task's "Done when" condition becomes a requirement with one sub-requirement.

Rules:

One requirement per task (R1 maps to T1, R2 to T2, etc.)
Each requirement has exactly one sub-requirement with id and behavior
When the done-when condition has clear precondition/action/outcome structure, add optional GWT fields (given, when, then)
- Example: { "id": "R1.1", "behavior": "Config file validates on load", "given": "Config file exists with valid YAML", "when": "Application starts", "then": "Config is parsed without errors" }
Keep it minimal — no gap analysis, no multi-sub-requirement requirements

⚠️ Merge Convention: All spec merge --json '...' examples below show JSON inline for readability. In practice:

Always run hoyeon-cli spec guide <section> before constructing merge JSON to verify field names and types

Always use file-based passing: write JSON to /tmp/spec-merge.json via << 'EOF' heredoc, then pass via --json "$(cat /tmp/spec-merge.json)", then rm /tmp/spec-merge.json

On merge failure: run spec guide <failed-section>, fix JSON to match schema, retry once

# 1. Check field structure
hoyeon-cli spec guide requirements

# 2. Construct JSON with requirements.id, requirements.behavior, requirements.sub[]
#    Each sub-requirement needs: id, behavior
#    Optional GWT fields: given (precondition), when (action), then (expected outcome)
#    Example sub: { "id": "R1.1", "behavior": "Login rejects invalid credentials",
#                   "given": "User is on login page", "when": "User submits wrong password", "then": "Error message shown and login denied" }

# 3. Merge via file-based passing
cat > /tmp/spec-merge.json << 'EOF'
{ "requirements": [ ... ] }
EOF
hoyeon-cli spec merge ${SPEC_PATH} --json "$(cat /tmp/spec-merge.json)" && rm /tmp/spec-merge.json

This ensures:

fulfills[] in tasks reference real requirement IDs for behavior verification
Final Verify in /execute can check requirement sub-requirements via fulfills → req.sub[]

9.2.7 Merge context

Merge the context gathered during planning. Content is type-aware:

# 1. Check field structure
hoyeon-cli spec guide context

# 2. Construct JSON with context fields:
#    - confirmed_goal: user's confirmed goal statement
#    - decisions: key planning decisions (id, decision, rationale)
#    - known_gaps: assumptions and unknowns as string array
#    IF any task has type: dev → also include context.research (string array of key findings)

# 3. Merge via file-based passing
cat > /tmp/spec-merge.json << 'EOF'
{ "context": { "confirmed_goal": "...", "decisions": [...], "known_gaps": [...], "research": [...] } }
EOF
hoyeon-cli spec merge ${SPEC_PATH} --json "$(cat /tmp/spec-merge.json)" && rm /tmp/spec-merge.json

known_gaps to always capture (at minimum):

Task independence / overlap assumptions (e.g., "Assumes T1 and T2 have no file overlap")
Tool/skill availability assumptions (e.g., "Assumes existing test infra can be reused")
Scope assumptions (e.g., "Assumes no database migration needed")

These known_gaps give /execute triage context when things go wrong.

9.3 Merge tasks

Merge all tasks in a single call — this replaces the placeholder T1 from spec init. Do NOT call merge per task (without --append, each call overwrites the previous tasks array).

# 1. Check field structure
hoyeon-cli spec guide tasks

# 2. Construct JSON with all tasks in a single array
#    Each task needs: id, action, type, status, depends_on, fulfills
#    Optional: tool (dispatch hint for plain mode — skill name like /bugfix or agent subtype like worker)
#    Acceptance criteria = sub-req behaviors (+ GWT fields when available) from fulfills[] (Worker reads requirements directly)

# 3. Merge ALL tasks in one call via file-based passing
cat > /tmp/spec-merge.json << 'EOF'
{ "tasks": [ { "id": "T1", ... }, { "id": "T2", ... } ] }
EOF
hoyeon-cli spec merge ${SPEC_PATH} --json "$(cat /tmp/spec-merge.json)" && rm /tmp/spec-merge.json

Map from plan:

Task Breakdown → action (include implementation steps inline in the action description)
Done condition → fulfills[] (requirement IDs) → sub-req behaviors (+ GWT fields when available) as acceptance criteria
Dependency DAG → depends_on
Agent Mapping → tool (from Phase 5 discovery, optional — used for plain mode dispatch)

9.3.5 Auto-generate sandbox tasks

After all tasks are merged, check for sandbox sub-requirements and generate infra + verification tasks:

# Auto-generates T_SANDBOX (infra prep) + T_SV1~N (per-sub-requirement verification) tasks
# No-ops if no execution_env: sandbox sub-requirements exist
hoyeon-cli spec sandbox-tasks ${SPEC_PATH}

This command scans all sub-requirements for execution_env: "sandbox" and automatically creates the required infra and per-sub-requirement verification tasks with correct depends_on wiring.

9.4 Update state.json

Update the session state to point to the generated spec:

hoyeon-cli session set --sid $SESSION_ID --spec "$SPEC_PATH"

9.5 Validate

hoyeon-cli spec validate ${SPEC_PATH}

If validation fails, fix and retry once.

9.6 Hand off to /execute

Output: spec.json generated: ${SPEC_PATH}

Then invoke the /execute skill to begin execution.

Constraints

Do NOT directly execute tasks — delegate to /execute skill after spec.json generation
Do NOT create teams or spawn agents — only propose the structure
Do NOT modify project files — only write to ~/.hoyeon/{session}/
If a task is ambiguous, flag it and suggest clarification