# Plan: Whole Plan Default Execution

## Overview

Update the plan execution skills so a missing selector means the target is the
whole plan, not Sprint 1 or a single next task. Preserve engineering control by
separating target scope from the current execution window, requiring a
suitability assessment before narrowing work, and keeping sequential and
parallel execution ownership distinct.

## Read First

- Primary source: `docs/plans/whole-plan-default-execution/whole-plan-default-execution-discussion-source.md`
- Source type: discussion-to-implementation-doc
- Open questions carried into execution: none

## Scope

- In scope:
  - `skills/workflows/plan/execute-from-plan/SKILL.md`
  - `skills/workflows/plan/execute-plan-parallel/SKILL.md`
  - `skills/workflows/plan/README.md` if shared role wording needs to reflect the default target.
  - Focused text tests under `skills/workflows/plan/**/tests/` or `tests/test_plan_workflow_lifecycle_docs.py`.
- Out of scope:
  - Global policy files such as `AGENTS.md` and `CODEX_AGENTS.md`.
  - `plan-tooling` feature work.
  - Durable artifact cleanup behavior.
  - Commit, push, or PR delivery.

## Assumptions

1. This is a docs and text-test change unless existing validation exposes a
   mechanical parser requirement.
2. `execute-plan-parallel` remains explicit permission to use subagents because
   the skill itself is a parallel execution mode.
3. `execute-from-plan` remains non-delegating by default and may only spawn
   subagents when the user explicitly invokes another delegation mode.
4. Existing dirty changes in plan workflow files are user-owned until proven
   otherwise and must be reconciled before editing overlapping files.

## Sprint 1: Sequential Execution Contract

**Goal**: Make `execute-from-plan` and shared plan workflow docs describe the
whole plan as the default target while retaining staged execution checkpoints.
**Demo/Validation**:

- Command(s):
  - `scripts/check.sh --tests -- -k execute_from_plan`
  - `scripts/check.sh --tests -- -k plan_workflow_lifecycle_docs`
  - `scripts/check.sh --markdown`
- Verify:
  - `execute-from-plan` no longer presents "next unblocked task" as the default
    output boundary.
  - The execution-state template records target scope, execution window, and
    staged-execution confirmation.
  - Shared plan workflow docs preserve the source doc, plan, and execution-state
    role split.

**PR grouping intent**: per-sprint
**Execution Profile**: serial

### Task 1.1: Reconcile current worktree overlap

- **Location**:
  - `skills/workflows/plan/execute-from-plan/SKILL.md`
  - `skills/workflows/plan/README.md`
  - `tests/test_plan_workflow_lifecycle_docs.py`
  - `skills/workflows/plan/execute-from-plan/tests/test_workflows_plan_execute_from_plan.py`
- **Description**: Inspect existing dirty changes in plan workflow files before
  editing. Decide whether implementation should build on those changes, avoid a
  file, or stop for user confirmation when overlap is unsafe.
- **Dependencies**:
  - none
- **Complexity**: 2
- **Acceptance criteria**:
  - `git status --short` and focused `git diff -- <paths>` are inspected.
  - No unrelated user-owned changes are reverted or overwritten.
  - Any unsafe overlap is recorded in execution state before stopping.
- **Validation**:
  - `git diff -- skills/workflows/plan/execute-from-plan/SKILL.md skills/workflows/plan/README.md`
  - `git diff -- tests/test_plan_workflow_lifecycle_docs.py skills/workflows/plan/execute-from-plan/tests/test_workflows_plan_execute_from_plan.py`

### Task 1.2: Update shared workflow role wording

- **Location**:
  - `skills/workflows/plan/README.md`
  - `tests/test_plan_workflow_lifecycle_docs.py`
- **Description**: Clarify that plan execution defaults to whole-plan target
  scope, while execution state tracks staged windows and resume progress. Keep
  source doc, plan, and execution-state roles separate.
- **Dependencies**:
  - Task 1.1
- **Complexity**: 2
- **Acceptance criteria**:
  - README distinguishes target scope from current execution window.
  - README states that narrowing from whole-plan target requires explicit user
    selector or confirmed staged execution.
  - Existing artifact-role guidance remains intact.
- **Validation**:
  - `scripts/check.sh --tests -- -k plan_workflow_lifecycle_docs`

### Task 1.3: Make `execute-from-plan` whole-plan by default

- **Location**:
  - `skills/workflows/plan/execute-from-plan/SKILL.md`
  - `skills/workflows/plan/execute-from-plan/tests/test_workflows_plan_execute_from_plan.py`
- **Description**: Change the sequential executor contract so its default target
  scope is the whole plan. Replace the single next-task output boundary with a
  loop that continues through unblocked tasks until the target scope is complete,
  blocked, unsafe, validation fails, or a confirmed checkpoint is reached.
- **Dependencies**:
  - Task 1.1
- **Complexity**: 4
- **Acceptance criteria**:
  - Inputs define optional selectors as intentional target-scope narrowing, not
    required execution selectors.
  - Outputs describe whole-plan progress rather than one next unblocked task.
  - Workflow includes a whole-plan suitability assessment before narrowing the
    execution window.
  - Workflow explicitly asks the user to confirm staged execution when the whole
    plan target is unsuitable for a single run.
  - The no-subagent default remains unless an explicit delegation mode is
    requested.
- **Validation**:
  - `scripts/check.sh --tests -- -k execute_from_plan`
  - `rg -n "next unblocked task|whole plan|execution window|staged" skills/workflows/plan/execute-from-plan/SKILL.md`

### Task 1.4: Extend execution-state template fields

- **Location**:
  - `skills/workflows/plan/execute-from-plan/SKILL.md`
  - `skills/workflows/plan/execute-from-plan/tests/test_workflows_plan_execute_from_plan.py`
- **Description**: Add stable execution-state fields for target scope, current
  execution window, staged-execution confirmation, and direct source-doc
  execution waiver.
- **Dependencies**:
  - Task 1.3
- **Complexity**: 3
- **Acceptance criteria**:
  - Template includes `Target scope`.
  - Template includes `Execution window`.
  - Template includes `Staged execution confirmation`.
  - Existing direct source-doc waiver field remains stable.
  - Tests assert the new stable labels.
- **Validation**:
  - `scripts/check.sh --tests -- -k execute_from_plan`

## Sprint 2: Parallel Execution Contract

**Goal**: Make `execute-plan-parallel` default to whole-plan target scope and
only narrow to staged parallel windows after assessment and user confirmation.
**Demo/Validation**:

- Command(s):
  - `scripts/check.sh --tests -- -k execute_plan_parallel`
  - `scripts/check.sh --markdown`
- Verify:
  - Missing sprint or phase selector no longer defaults to Sprint 1.
  - The parallel skill records that subagents implement task-scoped lanes while
    the main agent owns plan-wide scope, integration, and validation.

**PR grouping intent**: per-sprint
**Execution Profile**: serial

### Task 2.1: Reconcile current parallel skill test coverage

- **Location**:
  - `skills/workflows/plan/execute-plan-parallel/SKILL.md`
  - `skills/workflows/plan/execute-plan-parallel/tests/test_workflows_plan_execute_plan_parallel.py`
- **Description**: Check whether focused tests already exist for
  `execute-plan-parallel`. If not, add a small text test matching the repository
  pattern for skill contract assertions.
- **Dependencies**:
  - Task 1.1
- **Complexity**: 2
- **Acceptance criteria**:
  - Existing or new test path is identified before editing.
  - Test coverage verifies no-selector whole-plan behavior and absence of the
    Sprint 1 default.
  - Test coverage verifies main-agent ownership of integration and validation.
- **Validation**:
  - `rg -n "execute-plan-parallel|Sprint 1|whole plan" tests skills/workflows/plan`

### Task 2.2: Update `execute-plan-parallel` default scope

- **Location**:
  - `skills/workflows/plan/execute-plan-parallel/SKILL.md`
  - `skills/workflows/plan/execute-plan-parallel/tests/test_workflows_plan_execute_plan_parallel.py`
- **Description**: Replace no-selector Sprint 1 behavior with whole-plan target
  behavior. Update parsing guidance so the agent can parse all sprints by
  default and use sprint or phase selectors only when the user provides them or
  confirms staged execution.
- **Dependencies**:
  - Task 2.1
- **Complexity**: 4
- **Acceptance criteria**:
  - Inputs state that the plan path is required and selectors are optional
    narrowing controls.
  - Workflow says no selector means whole-plan target scope.
  - Workflow no longer says to default to Sprint 1.
  - `plan-tooling` examples distinguish all-plan validation from per-sprint
    batch computation.
- **Validation**:
  - `scripts/check.sh --tests -- -k execute_plan_parallel`
  - `rg -n "default to Sprint 1|whole-plan target|whole plan" skills/workflows/plan/execute-plan-parallel/SKILL.md`

### Task 2.3: Add suitability assessment and staged confirmation

- **Location**:
  - `skills/workflows/plan/execute-plan-parallel/SKILL.md`
  - `skills/workflows/plan/execute-plan-parallel/tests/test_workflows_plan_execute_plan_parallel.py`
- **Description**: Add an explicit whole-plan suitability assessment before
  parallel dispatch. If full-plan execution is unsuitable, require the main
  agent to summarize risk, propose staged windows and acceptance gates, and ask
  the user to confirm before narrowing execution.
- **Dependencies**:
  - Task 2.2
- **Complexity**: 3
- **Acceptance criteria**:
  - Suitability assessment covers plan size, dependency graph, file overlap,
    dirty worktree overlap, validation availability, credentials, migrations,
    external side effects, and rollback risk.
  - Staged execution confirmation offers either whole-plan target with
    checkpoints or an agreed narrower execution window.
  - Subagents remain task-scoped, and the main agent owns dispatch,
    integration, validation, and final synthesis.
- **Validation**:
  - `scripts/check.sh --tests -- -k execute_plan_parallel`

## Sprint 3: Final Validation And Documentation Consistency

**Goal**: Verify that the updated skill contracts are internally consistent and
pass the repository's docs and test gates.
**Demo/Validation**:

- Command(s):
  - `plan-tooling validate --file docs/plans/whole-plan-default-execution/whole-plan-default-execution-plan.md`
  - `scripts/check.sh --markdown`
  - `scripts/check.sh --tests -- -k "execute_from_plan or execute_plan_parallel or plan_workflow_lifecycle_docs"`
  - `scripts/check.sh --all`
- Verify:
  - Plan lint passes.
  - Focused tests pass.
  - Full repository gate passes before claiming maintenance complete.

**PR grouping intent**: per-sprint
**Execution Profile**: serial

### Task 3.1: Run focused validation

- **Location**:
  - `docs/plans/whole-plan-default-execution/whole-plan-default-execution-plan.md`
  - `skills/workflows/plan/README.md`
  - `skills/workflows/plan/execute-from-plan/SKILL.md`
  - `skills/workflows/plan/execute-from-plan/tests/test_workflows_plan_execute_from_plan.py`
  - `skills/workflows/plan/execute-plan-parallel/SKILL.md`
  - `skills/workflows/plan/execute-plan-parallel/tests/test_workflows_plan_execute_plan_parallel.py`
  - `tests/test_plan_workflow_lifecycle_docs.py`
- **Description**: Run the focused validation commands and fix docs/test drift
  that remains within scope.
- **Dependencies**:
  - Task 1.2
  - Task 1.3
  - Task 1.4
  - Task 2.2
  - Task 2.3
- **Complexity**: 2
- **Acceptance criteria**:
  - Plan validates with `plan-tooling`.
  - Markdown lint passes.
  - Focused tests for changed skill docs pass.
- **Validation**:
  - `plan-tooling validate --file docs/plans/whole-plan-default-execution/whole-plan-default-execution-plan.md`
  - `scripts/check.sh --markdown`
  - `scripts/check.sh --tests -- -k "execute_from_plan or execute_plan_parallel or plan_workflow_lifecycle_docs"`

### Task 3.2: Run final repository gate and update execution state

- **Location**:
  - `docs/plans/whole-plan-default-execution/whole-plan-default-execution-execution-state.md`
  - `skills/workflows/plan/README.md`
  - `skills/workflows/plan/execute-from-plan/SKILL.md`
  - `skills/workflows/plan/execute-from-plan/tests/test_workflows_plan_execute_from_plan.py`
  - `skills/workflows/plan/execute-plan-parallel/SKILL.md`
  - `skills/workflows/plan/execute-plan-parallel/tests/test_workflows_plan_execute_plan_parallel.py`
  - `tests/test_plan_workflow_lifecycle_docs.py`
- **Description**: Run the final repository gate and record validation evidence,
  blockers, or accepted risks in the execution state before reporting
  completion.
- **Dependencies**:
  - Task 3.1
- **Complexity**: 2
- **Acceptance criteria**:
  - `scripts/check.sh --all` passes, or failure is documented with command output
    and a concrete blocker.
  - Execution state records current status, completed tasks, validation commands,
    and next step.
  - Final response does not claim completion if validation remains blocked.
- **Validation**:
  - `scripts/check.sh --all`

## Testing Strategy

- Unit/text tests: Add or update focused Python tests that assert stable skill
  contract phrases for `execute-from-plan`, `execute-plan-parallel`, and shared
  workflow docs.
- Integration/docs checks: Run `scripts/check.sh --markdown` and plan linting.
- Full gate: Run `scripts/check.sh --all` before reporting implementation
  complete.

## Risks & gotchas

- Existing dirty changes already touch several plan workflow files. The first
  implementation task must reconcile overlap and preserve user changes.
- Whole-plan default is a target-scope default, not permission to ignore
  checkpoints, blockers, validation failures, or safety constraints.
- Parallel whole-plan execution should still dispatch task-scoped subagents.
  Main-agent ownership of scope, integration, and validation must stay explicit.
- Removing the Sprint 1 default may require new tests because no
  `execute-plan-parallel` test file may exist yet.
- Keep repository text English-only.

## Rollback plan

- Revert only the files changed by this plan's implementation.
- If the new default proves too broad, keep the whole-plan target wording but
  tighten the suitability assessment and staged confirmation requirements rather
  than restoring a silent Sprint 1 or next-task default.
