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

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.sh

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

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

0. 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)

   • Read each file's YAML frontmatter: extract name and description
   • Filter out non-agent reference files (skip files with description containing "Reference documentation" or "NOT an executable agent")
   • Build a list of available project agents with their names and capabilities

2. Read agent-mapping from Session Config (optional):

   • Field: agent-mapping — a JSON object mapping role keys to agent names
   • Role keys: impl, test, db, ui, security, compliance, docs, perf
   • Example: agent-mapping: { impl: code-editor, test: test-specialist, db: database-architect }
   • 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

3. Build Agent Registry (resolution priority):

   • Priority 1: Project agents (from <state-dir>/agents/ — see Platform Note) — matched by name
   • Priority 2: Plugin agents (session-orchestrator:code-implementer, session-orchestrator:test-writer, session-orchestrator:ui-developer, session-orchestrator:db-specialist, session-orchestrator:security-reviewer)
   • Priority 3: general-purpose (fallback)

4. Match tasks to agents: For each task from Step 1:

   • If agent-mapping config specifies a mapping for the task's domain → use that agent
   • Else, match task description against agent descriptions (keyword overlap: database/schema/migration → db agent, test/coverage/spec → test agent, UI/component/style/page → ui agent, security/auth/OWASP → security agent)
   • Else, use role-based default: Impl-Core/Impl-Polish → code-implementer, Quality → test-writer
   • Record the resolved subagent_type for each task

No agents found? If no project agents exist and plugin agents are available, use plugin agents. If neither, fall back to general-purpose for all tasks. The system works at every level.

Step 1.8: Task-to-Role Classification

For each task from Step 1, assign exactly one role. Use these signal-to-role mappings:

Disambiguation rules:

• If a task involves BOTH exploration AND implementation → split it: Discovery agent reads/validates, Impl-Core agent implements. Create two separate task entries.
• If a task is "fix something from a previous session" (not from this session's Impl-Core) → classify as Impl-Core (it is new work for this session).
• If a task is "write tests for new feature code being built this session" → classify as Quality (not Impl-Core). Tests run after implementation.
• If unsure between Impl-Core and Impl-Polish → if the task is on the critical path (other tasks depend on it), it is Impl-Core. If independent polish, it is Impl-Polish.
• Housekeeping sessions: skip Steps 1.8, 2, and 3 — all tasks go into a single consolidated wave:
  • No role classification — all tasks treated as generic housekeeping work
  • Agent count: fixed at 1-2 per task (from wave-template.md housekeeping row), capped by agents-per-wave
  • File-scope deconfliction (Step 3.5) still applies within the single wave
  • Wave plan output uses: ### Wave 1: Housekeeping ([N agents])

Record the assigned role next to each task before proceeding to Step 2.

Step 2: Wave Assignment

Distribute tasks across waves using 5 named roles. Read waves from Session Config (default: 5) and map roles to wave numbers.

Wave Roles

Role-to-Wave Mapping

Map roles to the configured wave count:

When roles are combined into a single wave, agents from both roles execute in that wave. The combined wave inherits the more restrictive verification level.

Cross-role constraint in combined waves: Tasks from different roles within a combined wave CANNOT be merged into a single agent (different scope permissions — e.g., Discovery is read-only, Impl-Core has write access). If the combined wave exceeds agents-per-wave, defer the lower-priority role's tasks: in W1=Discovery+Impl-Core, defer Impl-Core tasks to the next applicable wave. In W2=Impl-Polish+Quality, defer Quality tasks to a separate phase within the same wave.

Example: When Discovery+Impl-Core are combined (3-wave config), the wave runs Incremental quality checks (Impl-Core's level) rather than no verification (Discovery's level).

Splitting criteria for 6+ waves: When Impl-Core or Impl-Polish span multiple waves, split by module or dependency boundary. Tasks with shared file dependencies go in the same wave; tasks touching independent modules go in separate waves. If no clear boundary exists, split by task count (distribute evenly).

Empty roles: If a role has 0 tasks, skip its wave entirely. Do NOT dispatch an empty wave. Remaining waves retain their original role names but are renumbered sequentially (e.g., if Discovery has 0 tasks and waves=5: W1=Impl-Core, W2=Impl-Polish, W3=Quality, W4=Finalization). Update total-waves in the plan output to reflect the actual wave count.

Role Details

Discovery

• Explore-type subagents (read-only, fast)
• Tasks: Audit affected code paths, verify assumptions, check test coverage, identify edge cases
• Output: Validated understanding, updated task scope if discoveries warrant it
• Tools: Read, Grep, Glob, Bash (read-only commands only) — do NOT use Edit or Write
• Scope enforcement: set allowedPaths to [] (empty) for Discovery waves. Include in agent prompts: "You are READ-ONLY. Do NOT use Edit or Write tools."

Impl-Core

• Full implementation agents with Write/Edit/Bash access
• Tasks: Core feature code, database changes, API endpoints, primary UI components
• Output: Working implementation (may have rough edges)

Impl-Polish

• Targeted fix agents + new implementation agents
• Tasks: Bug fixes from Impl-Core, secondary features, integration, edge cases
• Output: Complete implementation with integrations working

Quality

• Simplification agents + test writers + quality reviewers
• Tasks: Simplify AI-generated code patterns (using slop-patterns.md from discovery skill), write/update tests (test files only — **/*.test.*, **/*.spec.*, **/__tests__/**), run full quality checks per quality-gates skill, security review
• Scope restriction: Simplification agents may edit production files changed in this session. Test/review agents restricted to test file patterns and test configuration.
• Output: Simplified code, all tests passing, 0 TypeScript errors, no lint violations

Finalization

• 1-2 specialized agents
• Tasks: Update SSOT files, close issues, write session handover, prepare commits
• Output: Clean git state, updated documentation, issues resolved

Step 3: Complexity Assessment

Score the session scope to determine optimal agent counts per wave. Skip for housekeeping sessions (use fixed counts from Step 4).

Scoring Formula

Total score = sum of all factors (0-6 range).

Cross-module scope counts top-level source directories (e.g., src/auth/, src/api/, lib/utils/). Nested subdirectories under the same parent count as one directory. Non-source directories (docs, config, scripts) don't count unless they contain modified production code.

Complexity Tiers

Agent Count by Tier

Housekeeping sessions skip Discovery (tasks are predefined) and use fixed agent counts regardless of complexity.

The agents-per-wave Session Config value caps the maximum regardless of tier.

If project intelligence (learnings) suggests different sizing based on historical data, prefer the historical recommendation over the formula.

Step 3.5: Task-to-Agent Distribution

For each role's wave, distribute its classified tasks across the allocated agent count from Step 3:

Distribution algorithm:

1. Group by file affinity: Tasks touching the same files or the same directory MUST go to the same agent (prevents parallel merge conflicts).
2. One task per agent (preferred): If task count ≤ agent count, assign one task per agent. Leave unused agent slots empty — do not invent tasks to fill them.
3. Merge small tasks: If task count > agent count, merge the smallest tasks (by file count) that share a directory. Never merge tasks that touch different top-level modules.
4. Split large tasks: If a single task touches 6+ files across 3+ directories, split it by immediate parent directory boundary into sub-tasks for separate agents. Each parent directory becomes a separate sub-task scope, even if all parents fall under a single top-level source directory. Each sub-agent gets a clear file-boundary scope with no overlap.
5. File-scope deconfliction: After assignment, verify that NO two agents in the same wave modify the same file. If overlap exists, apply this resolution:

• If both tasks share >50% of their file scope → merge them into one agent
• If the overlapping task is NOT on the critical path (no downstream dependencies) → move it to Impl-Polish
• If both are on the critical path → merge into one agent and note in Risk Mitigation

Constraint check: If the final agent count for any wave exceeds agents-per-wave from $CONFIG, either merge more tasks or defer lower-priority tasks to Impl-Polish. Log any such adjustments in Risk Mitigation.

Step 4: Agent Specification

Template Reference: See wave-template.md in this skill directory for the agent specification format, isolation settings, and count tables.

For each wave, define agents using the template format in wave-template.md. Apply the agent count table based on session type, capped by agents-per-wave from Session Config.

If project intelligence (learnings) suggests different sizing based on historical data, prefer the historical recommendation over the formula.

Step 5: Issue Updates

Before presenting the plan:

VCS Reference: Use CLI commands per the "Common CLI Commands" section of the gitlab-ops skill.

1. Mark all selected issues as status:in-progress (use the issue update/edit command for the detected VCS platform)
2. Add a comment to each issue noting the session and planned wave (use the issue note/comment command for the detected VCS platform)

Step 6: Present Plan for Approval

Present the plan in this format:

## Wave Plan (Session: [type], [N] waves, isolation: [worktree|none])

### Wave 1: Discovery ([N agents], parallel, read-only)
- Agent 1: [task] → [files] → [acceptance criteria] → `subagent_type: Explore`
...
- File scope overlap: none (read-only wave)

### Wave 2: Impl-Core ([N agents], parallel, isolation: [worktree|none])
- Agent 1: [task] → [files] → [acceptance criteria] → `subagent_type: [resolved agent]`
...
- File scope overlap: [none | list conflicting files and which agents]

### Wave 3: Impl-Polish ([N agents], parallel, isolation: [worktree|none])
...
- File scope overlap: [none | list]

### Wave 4: Quality ([N agents], parallel, isolation: [worktree|none])
...

### Wave 5: Finalization ([N agents])
...

### Agent Registry
- [list which agents were discovered and how they map to tasks]
- Example: "database-architect (project) → DB tasks, session-orchestrator:code-implementer (plugin) → API tasks"

### Inter-Wave Checkpoints
- After Discovery: Validate discoveries, adjust Impl-Core scope if needed
- After Impl-Core: Incremental quality checks per quality-gates. **If `pencil` configured: design review.**
- After Impl-Polish: Incremental quality checks + integration verification. **If `pencil` configured: final design-code alignment check.**
- After Quality: Full Gate per quality-gates — if failing, create fix tasks for Finalization
- After Finalization: Final review before session-end

### Project Intelligence Applied
- [list of learnings that influenced this plan, with confidence scores]
- Or: "No project intelligence available yet"

### Risk Mitigation
- [identified risks and how each wave handles them]

### Execution Config
- Waves: [N] | Agents-per-wave cap: [M] | Isolation: [worktree|none|auto]
- Enforcement: [strict|warn|off] | Max turns: [N per session type]
- Persistence: [true|false] | Pencil: [path|none]
- Parallel dispatch: All agents within each wave execute simultaneously via Agent() tool
- Total agents planned: [sum across all waves]

Ready to execute? Use /go to begin.

Step 7: Handle Plan Changes

If the user requests changes:

• Re-scope affected waves
• Re-assign agents
• Update issue comments if scope changes
• Re-present the modified plan

Sub-File Reference

Anti-Patterns

• DO NOT create waves with circular dependencies — if wave N depends on wave N+1 output, the plan is broken
• DO NOT assign Discovery and Implementation roles to the same wave — read-only and write agents must be separated
• DO NOT create agent prompts that reference other agents' work — each agent must be fully self-contained
• DO NOT over-split simple tasks into many waves — a 2-file change doesn't need 5 waves
• DO NOT plan without reading the actual codebase — plans based on assumptions produce wasted waves

Critical Rules

• NEVER put independent tasks in the same agent — each agent gets ONE focused task
• ALWAYS order waves by dependency — never schedule a task before its dependency completes
• TypeScript check only in Discovery (baseline) and Quality/Finalization roles — not during implementation roles
• Build commands only in housekeeping sessions — never during feature/deep work mid-session
• Agent prompts must be self-contained — include ALL context the agent needs (file paths, issue details, acceptance criteria). The agent starts with zero context.
• If a task is too large for one agent, split it across multiple agents with clear file-boundary separation