# Whole Plan Default Execution Implementation Handoff

## Status

- Date: 2026-05-18
- Source: User discussion in the current Codex thread.
- Intended next step: Execute the sibling plan.
- Recommended plan: docs/plans/whole-plan-default-execution/whole-plan-default-execution-plan.md
- Recommended execution state: docs/plans/whole-plan-default-execution/whole-plan-default-execution-execution-state.md

## Purpose

Change the plan execution skills so the default target is the whole plan, while
still allowing the agent to propose a staged execution window when full-plan
execution is too risky, too large, or not currently verifiable.

## Confirmed Facts

- `execute-from-plan` currently describes output as the next unblocked task and
  resumes by picking the next unblocked task that matches a selector.
- `execute-plan-parallel` currently allows whole-plan execution in output text,
  but its workflow says that a missing sprint or phase selector should ask the
  user or default to Sprint 1.
- The desired direction is Option B plus Option C:
  - Treat the whole plan as the default target.
  - Keep execution windows stageable after an explicit assessment and user
    confirmation.
  - Clarify the split between the sequential executor and the parallel executor.
- Existing delegation policy stays opt-in and mode-based. Whole-plan default
  scope must not become implicit permission to spawn subagents outside
  `execute-plan-parallel` or another explicit delegation mode.
- This repository uses `agent-docs` preflight, project validation through
  `scripts/check.sh`, and plan linting through `plan-tooling`.

## Decisions

1. The default target scope for plan execution is the whole plan when the user
   provides no task, sprint, phase, priority, or stop-condition selector.
2. The agent may choose a smaller execution window only after a suitability
   assessment explains why full-plan execution is not appropriate for the
   current run.
3. If full-plan execution is unsuitable, the agent must ask the user to confirm
   either:
   - keep the whole plan as the target with staged checkpoints, or
   - agree on a narrower phase, sprint, batch, or task window with acceptance
     gates.
4. `execute-from-plan` should be the sequential whole-plan executor with durable
   execution state. It should loop across tasks until the target scope is
   complete, blocked, unsafe, validation fails, or a confirmed checkpoint is
   reached.
5. `execute-plan-parallel` should be the explicit parallel executor. It may
   delegate independent tasks to subagents, but the main agent owns plan-wide
   scope, dispatch, integration, validation, and the final answer.
6. Execution state should record target scope, current execution window,
   confirmation status for staged execution, and enough status to resume.

## Scope

- Update `execute-from-plan` to make whole-plan the default target scope and to
  describe a loop over unblocked tasks instead of a single next-task default.
- Update `execute-plan-parallel` to make no-selector execution mean whole-plan
  execution, with a suitability assessment before narrowing scope.
- Update nearby plan workflow documentation and tests only where needed to keep
  the skill contract discoverable and mechanically checked.

## Non-Scope

- Do not change global delegation policy in `AGENTS.md` or `CODEX_AGENTS.md`.
- Do not add new `plan-tooling` functionality unless existing plan validation
  or tests reveal a required repository-local docs contract.
- Do not change unrelated durable artifact cleanup, source-doc, or create-plan
  behavior.
- Do not commit or stage changes unless a later user request explicitly asks for
  it.

## Requirements

- A missing selector must not silently narrow execution to Sprint 1 or one next
  task.
- Narrowing from whole-plan target to a staged execution window must be explicit,
  reasoned, and confirmed by the user before execution proceeds.
- Selector behavior remains available: a user-provided task, sprint, phase,
  priority, validation command, scope limit, branch policy, or stop condition can
  intentionally narrow the target.
- The sequential and parallel skills must state different execution ownership:
  `execute-from-plan` runs without subagents unless another explicit delegation
  mode is requested; `execute-plan-parallel` uses subagents because the skill was
  explicitly invoked.
- Execution-state template changes must be stable enough for future tests and
  execution resumes.
- Repository text must stay English-only.

## Acceptance Criteria

- `execute-from-plan` states that the default target scope is the whole plan.
- `execute-from-plan` describes a repeat-until-complete/blocker/checkpoint
  execution loop and no longer presents the next task as the default output
  boundary.
- `execute-from-plan` execution-state template includes target scope, execution
  window, and staged-execution confirmation fields.
- `execute-plan-parallel` states that a missing sprint or phase selector means
  whole-plan target scope.
- `execute-plan-parallel` requires a whole-plan suitability assessment before
  proposing narrower staged execution.
- Tests or text guards cover the new default target and the old Sprint 1 /
  next-task default does not remain as active guidance.
- `plan-tooling validate` passes for this plan.
- The smallest relevant project validation passes after implementation, or any
  failure is recorded with concrete evidence.

## Validation Plan

- `plan-tooling validate --file docs/plans/whole-plan-default-execution/whole-plan-default-execution-plan.md`
- `scripts/check.sh --markdown`
- Targeted tests for changed skill docs, expected to include:
  - `scripts/check.sh --tests -- -k execute_from_plan`
  - `scripts/check.sh --tests -- -k plan_workflow_lifecycle_docs`
- Run `scripts/check.sh --all` before reporting maintenance complete when the
  implementation is finished.

## Risks And Guardrails

- The current worktree may contain unrelated or user-owned changes in plan
  workflow files. Implementation must inspect and preserve existing changes
  before editing.
- Whole-plan default wording can accidentally imply uncontrolled long-running
  execution. The skills must distinguish target scope from current execution
  window.
- Whole-plan default wording can accidentally imply automatic delegation. The
  skill docs must preserve opt-in delegation boundaries.
- Text-only skill changes can drift from tests. Add or update focused text tests
  where the repository already uses them.

## Execution

- Execution state recommendation: docs/plans/whole-plan-default-execution/whole-plan-default-execution-execution-state.md
- Status: ready for sibling plan execution.
- Next-task source: docs/plans/whole-plan-default-execution/whole-plan-default-execution-plan.md

## Retention Intent

This source document is a plan-created coordination artifact. It can be cleaned
up after execution is complete unless its wording is promoted into durable skill
documentation.

## Open Questions

- None. Implementation may still stop for confirmation if dirty worktree overlap
  makes the exact edit base unsafe.

## Read-First References

- skills/workflows/plan/execute-from-plan/SKILL.md
- skills/workflows/plan/execute-plan-parallel/SKILL.md
- skills/workflows/plan/README.md
- skills/workflows/plan/_shared/references/PLAN_AUTHORING_BASELINE.md
- DEVELOPMENT.md
