session-plan

Platform Note: Project agents live in <state-dir>/agents/ where <state-dir> is .claude/ (Claude Code), .codex/ (Codex CLI), or .cursor/ (Cursor IDE). On Cursor IDE, parallel agent dispatch is not available — present wave tasks as a sequential execution list instead. See skills/_shared/platform-tools.md.

Session Plan Skill

Project-instruction file resolution: CLAUDE.md and AGENTS.md (Codex CLI) are transparent aliases — see [skills/_shared/instruction-file-resolution.md](../_shared/instruction-file-resolution.md). Wherever this skill mentions CLAUDE.md, the alias rule applies.

Phase 0.5: Parallel-Aware Preamble

Skip silently when persistence: false in Session Config.

Before any Phase 1 work, run the parallel-aware preamble per skills/_shared/parallel-aware-preamble.md. The preamble detects other active sessions in the worktree-family via findPeers(repoRoot, { mySessionId }), classifies the caller's mode via classifyMode(callerMode) against the exclusivity-matrix, and either:

• Returns PASS_THROUGH (no other session / always-ok mode) → continue to Phase 1
• Returns EXCLUSIVE_BLOCKED → fires Exclusive-Conflict AUQ from skills/_shared/parallel-aware-auq.md
• Returns PROMOTION_OFFER → fires Worktree-Promotion AUQ (via enterWorktree() from scripts/lib/autopilot/worktree-pipeline.mjs — see parallel-aware-auq.md outcome-handling)

On any non-PASS_THROUGH outcome that does not result in immediate exit, append a Deviation to STATE.md via appendDeviationOnDisk(repoRoot, isoTimestamp, message) from scripts/lib/state-md.mjs.

Implementation reference: skills/_shared/parallel-aware-preamble.md § Implementation. AUQ reference: skills/_shared/parallel-aware-auq.md.

Purpose

Transform the agreed session scope (from session-start Q&A) into an executable wave plan (using role-based assignment) with specific agent assignments, file scopes, and acceptance criteria per task.

Input: Session Scope

This skill receives the agreed session scope from session-start. The scope includes:

• Issue list: VCS issue numbers and titles selected by the user
• Session type: housekeeping, feature, or deep
• Recommended focus: the option the user selected in session-start Phase 7
• Session Config: parsed JSON from parse-config.mjs
• Express-path signal (optional): session-start Phase 8.5 may set EXPRESS_PATH=true in the handoff context when the activation conditions are met.

These are passed via the conversation context (not a file). Parse the preceding session-start output to extract the agreed scope.

Express Path Short-Circuit (#214)

Check this before Step 0. If the express path is active, this skill emits a minimal 1-wave plan and exits — no role decomposition, no wave splitting, no agent count computation.

Detect express-path activation: Search the conversation context for the banner line:

Express path activated — <N> tasks, coordinator-direct, no inter-wave checks.

If found AND express-path.enabled is true in Session Config (read via Step 0 below — skip only that field check if config read is needed):

Emit this 1-wave plan and exit the skill immediately (do not continue to Step 1 or beyond):

## Wave Plan (Session: housekeeping, 1 wave, isolation: none) [Express Path]

### Wave 1: Coordinator-Direct (<N> tasks)
- All agreed tasks executed sequentially by the coordinator — no subagents dispatched.
- Tasks: [list agreed issues/tasks]
- Isolation: none (coord-direct)
- Max-turns: N/A (coordinator executes directly)

### Execution Config
- Waves: 1 | Agents-per-wave: 0 (coordinator-direct) | Isolation: none
- Express path: active (housekeeping + scope ≤ 3 + no parallel agents needed)
- Total agents planned: 0

Express path — no inter-wave checks. Use /go to begin.

When express-path banner is absent or express-path.enabled: false: Proceed to Step 0 and the full planning flow as normal.

Step 0: Read Session Config

Read and parse Session Config per skills/_shared/config-reading.md. Store result as $CONFIG.

Extract these fields for planning:

• waves (default: 5) — number of execution waves
• agents-per-wave (default: 6, may have session-type overrides per config-reading.md) — max parallel agents per wave
• isolation (default: auto) — worktree / none / auto (auto = worktree for feature/deep, none for housekeeping)
• enforcement (default: warn) — strict / warn / off
• max-turns (default: auto) — agent turn budget (auto = housekeeping: 8, feature: 15, deep: 25)
• agent-mapping (optional) — explicit role-to-agent bindings
• persistence (default: true) — whether to use STATE.md and learnings

Fallback: If session-start already output a ## Session Config (active) block in the conversation context, extract values from there to avoid a redundant parse. If not present in context, parse independently.

Step 1: Task Decomposition

1. Check for resume context: > Skip if persistence is false in Session Config.

If <state-dir>/STATE.md exists with status: active or status: paused, read it to understand:

• Which waves were completed in the prior session
• Which agents completed, which were partial/failed
• What deviations were logged
• Use this to avoid re-doing completed work and to prioritize carryover tasks

If no STATE.md or status: completed, proceed with fresh planning.

0.5. Read project intelligence: > Skip if persistence is false in Session Config. If .orchestrator/metrics/learnings.jsonl exists, read active learnings (confidence > 0.3, not expired). Sort by confidence DESC (tiebreaker: created_at DESC) and slice to the first learnings-surface-top-n entries (default 15) before applying the four categories below. If the top-N slice is empty, skip the categories.

• Fragile files: if any planned task touches a known fragile file, note it as a warning in the agent spec
• Effective sizing: use historical sizing data to inform Step 3 complexity scoring
• Recurring issues: pre-populate risk mitigation with known issue patterns
• Scope guidance: validate planned scope against historical session capacity

For each agreed task/issue:

1. Read the VCS issue description and acceptance criteria
2. Identify affected files by searching the codebase (Grep/Glob — don't guess)
3. Map dependencies: which tasks must complete before others can start
4. Estimate complexity: small (1 agent), medium (2-3 agents), large (dedicated wave)
5. Identify synergies: tasks that touch the same files → same wave, same agent

Step 1.5: Agent Discovery

Before assigning tasks to waves, discover available agents for this session:

1. Scan for project-level agents: Glob <state-dir>/agents/.md (.claude/agents/.md for Claude Code, .codex/agents/.md for Codex CLI, .cursor/agents/.md for Cursor IDE)
2. Read each file's YAML frontmatter: extract name and description
3. Filter out non-agent reference files (skip files with description containing "Reference documentation" or "NOT an executable agent")
4. Build a list of available project agents with their names and capabilities

1. Read agent-mapping from Session Config (optional):
2. Field: agent-mapping — a JSON object mapping role keys to agent names
3. Role keys: impl, test, db, ui, security, compliance, docs, perf
4. Example: agent-mapping: { impl: code-editor, test: test-specialist, db: database-architect }
5. If present, these explicit mappings take priority over auto-matching

Validation: If agent-mapping specifies an agent name, verify the agent exists:

• For project agents: check <state-dir>/agents/<name>.md exists
• For plugin agents: check the agent is registered (contains : separator)
• If the agent doesn't exist: warn the user and fall back to auto-discovery for that role

1. Build Agent Registry (resolution pr