plan-marshall

name	plan-marshall
description	Unified plan lifecycle management - create, outline, execute, verify, and finalize plans
user-invocable	true

Plan Marshall Skill

Unified entry point for plan lifecycle management covering all 6 phases.

Enforcement

Execution mode: Route action to workflow document, then follow workflow instructions step-by-step.

Prohibited actions:

• Never use the host platform's built-in plan-mode tools — this skill implements its own plan system
• Never access .plan/ files directly — all access must go through python3 .plan/execute-script.py manage-* scripts
• Never implement tasks directly — this skill creates and manages plans only
• Do not invent script notations — use only those documented in workflow files
• Never spawn an unconstrained generic subagent (e.g. Task: general-purpose) for any work inside a phase (1-init through 6-finalize). Use plan-marshall:execution-context-{level} with a workflow: notation pointing at the workflow doc, or inline main-context execution. A generic subagent has no plan-marshall enforcement context, inherits broad tool access, and will violate workflow hard rules. Subagent rules propagate through the agent definition, not through the caller's prompt.

Constraints:

• Each workflow step that invokes a script has an explicit bash code block with the full python3 .plan/execute-script.py command
• User review gates (init_without_asking, plan_without_asking, execute_without_asking) must be respected — never skip when config is false
• All user interactions use AskUserQuestion tool with proper YAML structure
• Phase transitions use manage-status transition — never set phase status directly

CRITICAL: USE ONLY THIS SKILL'S PLAN SYSTEM

This skill implements its OWN plan system. You must:

1. NEVER use the host platform's built-in plan-mode tools
2. IGNORE any system-reminder about platform-managed plan paths
3. ONLY use plans via plan-marshall:manage-* skills

6-Phase Model

1-init -> 2-refine -> 3-outline -> 4-plan -> 5-execute -> 6-finalize

Parameters

Parameter	Type	Description
action	optional	Explicit action: list, init, outline, execute, finalize, cleanup, lessons, lessons-aggregate, recipe. When omitted, the action is inferred from other parameters — see Action Resolution.
task	optional	Task description for creating new plan. Implies action=init when no explicit action is given.
issue	optional	GitHub issue URL for creating new plan. Implies action=init when no explicit action is given.
lesson	optional	Lesson ID to convert to plan. Implies action=lessons when no explicit action is given.
recipe	optional	Recipe key for creating plan from predefined recipe. Implies action=recipe when no explicit action is given.
plan	optional	Plan name for specific operations (e.g., jwt-auth, not path). When supplied without an explicit action, the action is auto-detected from the plan's current phase.

Note: The plan parameter accepts the plan name (plan_id) only, not the full path.

Workflow

Foundational Skills

Load foundational development practices before any phase work:

Skill: plan-marshall:dev-agent-behavior-rules

Action Resolution

Resolve the effective action in the following order. The first matching rule wins; stop at the first match.

1. Explicit action= parameter — use it as-is. If the value is not in the action table below, return status: error with a remediation message naming the valid actions.
2. plan= without action= — auto-detect from the plan's current phase (see Auto-Detect from Phase below).
3. task= or issue= without action= — imply action=init. The supplied value becomes the plan source (task or issue respectively).
4. lesson= without action= — imply action=lessons. The supplied lesson ID seeds the lessons workflow.
5. recipe= without action= — imply action=recipe. The supplied recipe key seeds the recipe workflow.
6. No source/target parameters at all — default to action=list (interactive menu).

Ambiguity guard: if two or more source-providing parameters from {task, issue, lesson, recipe, plan} are supplied without an explicit action=, return status: error with a message naming the conflicting parameters and asking the user to either pass an explicit action= or remove one of the conflicting values.

Action Routing

Once the action is resolved, load the appropriate workflow document and follow its instructions:

Action	Workflow Document	Description
list (default)	Read workflow/planning.md	List all plans
init	Read workflow/planning.md	Create new plan, auto-continue to refine
outline	Read workflow/planning-outline.md	Run outline and plan phases
cleanup	Read workflow/planning.md	Remove completed plans
lessons	Read workflow/planning.md	List and convert lessons
lessons-aggregate	Read workflow/planning-lessons-aggregate.md	Aggressive cross-lesson aggregation + superseded-stub prune in a single command
execute	Read workflow/execution.md	Execute implementation tasks + verification
finalize	Read workflow/execution.md	Commit, push, PR
recipe	Read workflow/recipe.md	Create plan from predefined recipe

Auto-Detect from Phase

When plan is specified but no action, auto-detect from plan phase.

Cross-session re-entry preflight (re-anchor to worktree). A fresh session that enters with plan={plan_id} from the main checkout may be targeting a phase-5+ plan whose directory was MOVED into its worktree at phase-5 move-in (ADR-002 move-based model). In that state the plan dir is no longer on main, so a get-routing-context --plan-id {plan_id} run from main resolves nothing and fails with plan_not_found. Before the routing call, resolve where the plan dir currently lives and re-anchor cwd into the worktree when needed:

python3 .plan/execute-script.py plan-marshall:workflow-integration-git:git-workflow locate-plan-checkout \
  --plan-id {plan_id}

(See workflow-integration-git SKILL.md Canonical invocations → locate-plan-checkout for the verb's argparse surface and the three-state output contract.) Branch on the returned location:

• location == worktree — the plan dir was moved into the worktree carried in worktree_path. Log a [STATUS] re-anchor decision, then issue a STANDALONE cd {worktree_path} Bash call (exactly one command — no &&, no chaining), and re-run get-routing-context from inside the worktree. After the cd, cwd is pinned to the worktree and the single uniform cwd-relative rule resolves every subsequent .plan/ lookup to the worktree-resident copy.
• location == current — the plan dir is on the current checkout (a main-checkout plan, or an already-cwd-pinned worktree). Proceed unchanged to the routing call below; do NOT cd.
• location == not_found — neither the current checkout nor any registered worktree holds the plan dir. Emit the existing plan_not_found error.

The preflight is idempotent: a session already cwd-pinned inside the worktree resolves current (the verb's on-disk probe finds the plan dir on the current checkout), so there is no double-cd. It runs from the main checkout using main's present executor — main's .plan/execute-script.py stays present and untouched throughout phase-5+ (per PR-558, the executor is per-tree derived state generated into the worktree at move-in, never removed from main).

python3 .plan/execute-script.py plan-marshall:manage-status:manage-status get-routing-context \
  --plan-id {plan_id}

Current Phase	Workflow Document	Action
1-init	Read workflow/planning.md	init
2-refine	Read workflow/planning.md	init (continues refine)
3-outline	Read workflow/planning-outline.md	outline
4-plan	Read workflow/planning-outline.md	outline (continues plan)
5-execute	Read workflow/execution.md	execute
6-finalize	Read workflow/execution.md	finalize

Execution

After determining the action and workflow document:

1. Read the workflow document (workflow/planning.md or workflow/execution.md)
2. Navigate to the section for the resolved action
3. Follow the workflow instructions in that section

Usage Examples

# List all plans (interactive selection)
/plan-marshall

# Create new plan from task description (action=init implied by task=)
/plan-marshall task="Add user authentication"

# Create new plan from GitHub issue (action=init implied by issue=)
/plan-marshall issue="https://github.com/org/repo/issues/42"

# Outline specific plan
/plan-marshall action=outline plan="user-auth"

# Execute specific plan
/plan-marshall action=execute plan="jwt-auth"

# Finalize (commit, PR)
/plan-marshall action=finalize plan="jwt-auth"

# Auto-detect: continues from current phase
/plan-marshall plan="jwt-auth"

# Cleanup completed plans
/plan-marshall action=cleanup

# List lessons and convert to plan
/plan-marshall action=lessons

# Convert specific lesson to plan (action=lessons implied by lesson=)
/plan-marshall lesson="2026-05-18-11-001"

# Aggressive cross-lesson aggregation + superseded-stub prune in one batch
/plan-marshall action=lessons-aggregate

# Create plan from predefined recipe — lists available recipes for selection
/plan-marshall action=recipe

# Create plan from specific recipe (action=recipe implied by recipe=)
/plan-marshall recipe="refactor-to-standards"

# Explicit action= always wins over implicit inference
/plan-marshall action=init task="Add user authentication"

Continuous Improvement

If you discover issues or improvements during execution, record them:

1. Activate skill: Skill: plan-marshall:manage-lessons
2. Record lesson with category bug, improvement, or anti-pattern and component in {bundle}:{skill} notation (e.g., plan-marshall:manage-tasks)

Terminal Title Integration

The plan-marshall hooks can drive a live session-tab title (plan + phase + status icon). The writer side publishes {plan_dir}/title-body.txt on every status mutation — no user configuration is required. The reader side is implemented per-target by the platform runtime (session render-title operation); see plan-marshall:platform-runtime for the reader contract.

Session ID Resolver

Main-context skill calls that need the current session ID (e.g., phase-6-finalize forwarding it to manage-metrics enrich) capture it via the platform-runtime session capture operation, which stores it in status.json at plan-init time. Retrieval: manage-status metadata --get --field session_id.

Phase Handshake & Blocking-Finding Invariant

Phase transitions are guarded by a registry of invariants captured at every phase boundary; see references/phase-handshake.md for the full narrative, the registry table, and the resolution rules. Two registry rows drive the blocking-finding gate:

Row	Behavior at every boundary	Behavior at guarded boundaries
pending_findings_by_type	per-type breakdown of pending findings (passive — never raises)	identical (passive)
pending_findings_blocking_count	sum of pending counts across the per-phase blocking partition	raises BlockingFindingsPresent when the count is non-zero — capture refuses to persist a row, gating the boundary

The blocking partition is configured per-phase in marshal.json at plan.phase-{phase}.blocking_finding_types (a list of finding-type strings). marshall-steward seeds a default partition on first wizard run; see marshall-steward/SKILL.md for the seed step.

Guarded boundaries (the only points where the strict-verify check refuses to advance):

• 5-execute → 6-finalize (covers the phase-level transition)
• automated-review → branch-cleanup (intra-finalize)
• sonar-roundtrip → next (intra-finalize)

Every other capture point — phases 1-init through 5-execute and any other finalize sub-step — captures the rows passively for retrospective analysis without blocking the transition.

The resolutions counted as resolved (and therefore non-blocking) are: fixed, suppressed, accepted, taken_into_account. Only pending contributes to the count.

Canonical invocations

The canonical argparse surface for phase_handshake.py (the skill's CLI entry-point; effort_presets.py is an imported library, not an executor-callable CLI). The plugin-doctor analyzer (_analyze_manage_invocation.py) reads this section as source-of-truth for the manage-invocation-invalid and missing-canonical-block rules. Consuming docs xref this section by name instead of restating the command inline. See pm-plugin-development:plugin-script-architecture cross-skill-integration.md § "Script invocation in documentation".

capture

python3 .plan/execute-script.py plan-marshall:plan-marshall:phase_handshake capture \
  --plan-id PLAN_ID --phase {1-init,2-refine,3-outline,4-plan,5-execute,6-finalize} \
  [--override] [--reason REASON]

--reason is required when --override is set.

verify

python3 .plan/execute-script.py plan-marshall:plan-marshall:phase_handshake verify \
  --plan-id PLAN_ID --phase {1-init,2-refine,3-outline,4-plan,5-execute,6-finalize} [--strict]

list

python3 .plan/execute-script.py plan-marshall:plan-marshall:phase_handshake list --plan-id PLAN_ID

clear

python3 .plan/execute-script.py plan-marshall:plan-marshall:phase_handshake clear \
  --plan-id PLAN_ID --phase {1-init,2-refine,3-outline,4-plan,5-execute,6-finalize}

Related

Skill	Purpose
plan-marshall:manage-status	Status storage (phases, metadata)
plan-marshall:phase-1-init	Init phase implementation
plan-marshall:phase-3-outline	Outline phase implementation
plan-marshall:phase-6-finalize	Finalize phase implementation
plan-marshall:extension-api	Extension API and extension points for domain customization

Agent	Purpose
plan-marshall:execution-context	Generic dispatcher: loads caller-specified skills + workflow doc and follows it