@josstei/maestro 1.6.4-nightly.20260430

package/src/skills/shared/execution/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: execution
+description: Phase execution methodology for orchestration workflows with error handling and completion protocols
+---
+
+# Execution Skill
+
+Activate this skill during Phase 3 (Execution) of Maestro orchestration. This skill defines how Maestro executes implementation phases through native subagent delegation.
+
+## Execution Mode Gate
+
+### Step 0 — Express bypass (early return)
+
+If `workflow_mode` is `express` in the current session, STOP HERE. Do not proceed
+to the execution mode gate. Do not prompt the user. Do not resolve execution mode.
+Express always dispatches sequentially. Return to the Express Workflow and continue
+from the delegation step.
+
+<HARD-GATE>
+This gate MUST resolve before ANY delegation proceeds. Do not skip it. Do not defer it. Do not begin delegating to subagents until execution_mode is recorded in session state. If you reach a delegation step and execution_mode is not set, STOP and return here.
+</HARD-GATE>
+
+### Step 1 — Read the configured mode
+
+Read `MAESTRO_EXECUTION_MODE` (default: `ask`).
+
+- If `parallel`: call `update_session` with `{ execution_mode: 'parallel', execution_backend: 'native' }` to record in session state. Skip to delegation.
+- If `sequential`: call `update_session` with `{ execution_mode: 'sequential', execution_backend: 'native' }` to record in session state. Skip to delegation.
+- If `ask`: proceed to Step 2.
+
+### Step 2 — Analyze the implementation plan
+
+Before prompting the user, analyze the approved plan to generate a recommendation:
+
+1. Count total phases in the plan
+2. Count phases marked `parallel: true` (parallelizable phases)
+3. Count distinct parallel batches (groups of parallelizable phases at the same dependency depth)
+4. Count sequential-only phases (phases with `blocked_by` dependencies that prevent parallelization)
+5. Cross-check file ownership across all phases. If any two phases share a file in their `files` arrays, those phases CANNOT be parallel-eligible — subtract them from the parallelizable count. Report each overlap as an Overlapping-file Warning in the prompt.
+
+6. If `validate_plan` was called during planning and returned a `parallelization_profile`, use its `parallel_eligible` and `effective_batches` counts as the authoritative source for items 1-5 above. These are computed from actual dependency depths and override any manual flag-based counts. If `parallelization_profile` is not available, use the counts from items 1-5 as-is.
+
+Record these counts — they feed into the prompt.
+
+### Step 3 — Determine the recommendation
+
+- If parallelizable phases ≤ 1 → auto-select **sequential**. Call `update_session` with `{ execution_mode: 'sequential', execution_backend: 'native' }`. Inform the user: "All phases are sequential — no parallel batches available." Skip to delegation. Do NOT prompt with a choice. Do NOT call `ask_user`. Do NOT present options. (Parallelism requires at least 2 phases at the same dependency depth; a single parallel-eligible phase has nothing to batch with.)
+
+<ANTI-PATTERN>
+WRONG — 1 parallel-eligible phase but user still prompted:
+  Parallel-eligible Phases: 1
+  → Presented choice: "Sequential (Recommended)" / "Parallel"
+
+When parallelizable phases ≤ 1, there is NO choice to make. Auto-select sequential
+and skip directly to delegation. Do not show a picker.
+</ANTI-PATTERN>
+
+- If parallelizable phases > 50% of total phases → recommend **parallel**
+- If parallelizable phases ≤ 50% but > 1 → recommend **sequential** (limited benefit)
+- The recommended option appears first in the `ask_user` options list with "(Recommended)" appended to its label. The non-recommended option MUST NOT include "(Recommended)" in its label.
+
+### Step 4 — Prompt the user
+
+Call `ask_user` with `type: 'choice'` using exactly one of these option sets:
+
+**When recommending parallel:**
+  options:
+    - label: "Parallel (Recommended)"
+      description: "Spawn child agents for each ready batch where file ownership does not overlap."
+    - label: "Sequential (High Precision)"
+      description: "Spawn one child agent at a time in dependency order."
+
+**When recommending sequential:**
+  options:
+    - label: "Sequential (Recommended)"
+      description: "Spawn one child agent at a time in dependency order."
+    - label: "Parallel"
+      description: "Spawn child agents for each ready batch where file ownership does not overlap."
+
+<ANTI-PATTERN>
+WRONG — Both options labeled "(Recommended)":
+  options:
+    - label: "Parallel (Recommended)"
+    - label: "Sequential (High Precision) (Recommended)"
+
+Only ONE option receives the "(Recommended)" suffix. Never both.
+</ANTI-PATTERN>
+
+Prompt the user for a choice using the user-prompt tool from runtime context. Replace `[N]`, `[M]`, and `[B]` with actual counts from Step 2. The prompt should convey the execution mode analysis and offer two options as described above.
+### Step 5 — Record and proceed
+
+1. Call `update_session` with the selected `execution_mode` and `execution_backend: native`
+2. The tool atomically persists both fields
+3. Use the selected mode for the remainder of the session unless the user changes it
+
+### Mode-specific behavior
+
+- If `parallel` is selected and a ready batch has only one phase, execute it sequentially
+- If `sequential` is selected, preserve plan order even when phases are parallel-safe
+
+### Safety fallback
+
+If `execution_mode` is not present in session state at the point where delegation is about to begin, STOP. Do not default to sequential. Return to this gate and resolve it. This catches any edge case where the gate was skipped.
+
+## State File Access
+
+When MCP state tools (`get_session_status`, `update_session`, `transition_phase`) are available, prefer them for state operations. They provide structured I/O and atomic transitions.
+
+When MCP tools are not available, state lives inside `<MAESTRO_STATE_DIR>` and is accessible through `read_file` and `write_file`.
+
+Helper scripts remain available for shell-injected command prompts:
+
+```bash
+node <runtime-script-root>/read-state.js <relative-path>
+node <runtime-script-root>/read-active-session.js
+```
+
+## Hook Lifecycle During Execution
+
+Hooks fire automatically at agent boundaries. The orchestrator does not invoke them directly.
+
+The hooks system tracks which agent is currently executing. Before each agent dispatch, a hook resolves the active agent identity from the required `Agent:` header first, then falls back to legacy env/regex detection, and injects compact session context. After completion, a hook validates that the response contains both `Task Report` and `Downstream Context`; it requests one retry on the first malformed response.
+
+The hook state directory under `${MAESTRO_HOOKS_DIR:-<os.tmpdir()>/maestro-hooks-<uid>}/<session-id>/` is transient and separate from orchestration state.
+
+## Sequential Execution Protocol
+
+For a sequential phase:
+
+1. Verify all `blocked_by` dependencies are completed
+2. Mark the phase `in_progress`
+3. Update `current_phase`
+4. Set `current_batch: null`
+5. Update the progress-tracking tool (use the tool names from `get_runtime_context`) before delegation
+6. Delegate to the assigned agent with the required header and full context
+7. Parse the returned handoff
+8. Update session state
+9. Mark the phase `completed` or `failed`
+10. Update the progress-tracking tool after the state update
+
+## Native Parallel Execution Protocol
+
+Use native parallel execution only for sibling phases at the same dependency depth with non-overlapping file ownership.
+
+### Batch Rules
+
+1. Verify all blocking phases for every phase in the batch are completed
+2. Slice the ready batch into the current dispatch chunk using `MAESTRO_MAX_CONCURRENT`
+3. Mark only the current chunk phases `in_progress`
+4. Set `current_batch` in session state for that chunk
+5. Write one in-progress todo item for the chunk
+6. In the next turn, emit only agent tool calls for that chunk
+7. Do not mix shell commands, validation commands, file writes, or narration between those agent calls
+8. `MAESTRO_MAX_CONCURRENT=0` means emit the entire ready batch in one turn
+
+### Native Constraints
+
+- The runtime only parallelizes contiguous agent calls in one turn
+- Native subagents currently run without user approval gates
+- `ask_user` remains available; a batch may pause while waiting for user input
+- If execution is interrupted, restart unfinished `in_progress` phases on resume instead of attempting to restore in-flight subagent interactions
+
+## Progress Context
+
+Include the following in every delegation query body:
+
+```text
+Progress: Phase [N] of [M]: [Phase Name]
+Session: [session_id]
+```
+
+For native parallel batches, also include the batch identifier in the required header:
+
+```text
+Agent: <agent_name>
+Phase: <id>/<total>
+Batch: <batch_id>
+Session: <session_id>
+```
+
+## Error Handling Protocol
+
+Record all errors in session state with:
+
+- `agent`
+- `timestamp`
+- `type`
+- `message`
+- `resolution`
+
+### Retry Logic
+
+- Maximum retries per phase: `MAESTRO_MAX_RETRIES` (default `2`)
+- First failure: analyze, adjust context/scope, retry automatically
+- Subsequent failures up to the limit: continue retrying with clearer constraints
+- Limit exceeded: mark the phase `failed` and escalate to the user
+
+Increment `retry_count` on each retry.
+
+### Recovery Protocol
+
+When a subagent terminates early, times out, returns malformed output, or when `delegation.constraints.result_surface` is `deferred` and the agent's text cannot be retrieved:
+
+1. **Poll**: For deferred-result runtimes (Codex), call the runtime's wait tool (`wait_agent` equivalent) with a bounded timeout. For synchronous runtimes, the initial dispatch return IS the result.
+2. **Detect drift**: Call `scan_phase_changes(session_id, phase_id)`. If the returned `candidates.created` or `candidates.modified` arrays are non-empty, the agent produced filesystem output without a handoff.
+3. **Ask the user to confirm**: Using the runtime's user-prompt tool, present the scan candidates and ask the user to confirm which files belong to this phase. For a parallel batch, include the `planned_files` from each phase's session state to assist attribution. If the scan surfaces files beyond any phase's `planned_files`, raise a blocker and surface the ambiguity to the user rather than silently attributing.
+4. **Reconcile**: Call `reconcile_phase(session_id, phase_id, files_created, files_modified, files_deleted, downstream_context, reason)` with the user-confirmed manifest. This clears `requires_reconciliation`.
+5. **Retry or advance**: If the user chose to retry the agent, re-delegate with the original scope plus the scan results as context. If the user accepted the work as delivered, advance to the next phase.
+
+Record all recovery events in session state with `{agent, timestamp, type: 'recovery', resolution: 'retry'|'reconciled'|'aborted'}`.
+
+### File Conflict Handling
+
+When a subagent reports a file conflict:
+
+1. Stop execution immediately
+2. Record the conflicting files and phases
+3. Do not attempt automatic merge resolution
+4. Ask the user how to proceed
+
+## Subagent Output Processing
+
+Native subagent results are wrapped. Do not assume the handoff begins at byte 0.
+
+### Parsing Rules
+
+1. Locate `## Task Report` (or `# Task Report`) inside the returned text
+2. Locate `## Downstream Context` (or `# Downstream Context`) inside the returned text
+3. Parse:
+   - status
+   - files created / modified / deleted
+   - downstream context fields
+   - validation result
+   - reported errors
+4. Persist the full raw output plus the parsed fields into session state
+
+### State Update Sequence
+
+After processing each handoff:
+
+1. Update the phase file manifests
+2. Update `downstream_context`
+3. Append any errors
+4. Aggregate token usage
+5. If validation passed, mark the phase `completed`
+6. If validation failed, trigger retry logic
+7. Update `updated`
+8. Advance or clear `current_batch` as each chunk finishes
+
+## Completion Protocol
+
+When all phases are completed:
+
+1. Verify there are no `failed` or `pending` phases
+2. Confirm plan deliverables are accounted for
+3. Run the final code-review gate for non-documentation changes
+4. Archive the session through `session-management`
+5. Present a final summary with deliverables, files changed, token usage, deviations, and review status

package/src/skills/shared/implementation-planning/SKILL.md

@@ -0,0 +1,307 @@
+---
+name: implementation-planning
+description: Generates detailed implementation plans from finalized designs
+---
+
+# Implementation Planning Skill
+
+**Standard workflow only.** If `task_complexity` is `simple` and workflow mode is Express, do not activate this skill. Simple tasks use the Express workflow, which does not activate implementation-planning. Return to the Express Workflow section.
+
+Activate this skill during Phase 2 of Maestro orchestration, after the design document has been approved. This skill provides the methodology for generating detailed, actionable implementation plans that map directly to subagent assignments.
+
+## Codebase Grounding
+
+Do not generate an implementation plan from guesses about the repository.
+
+Use the built-in `codebase_investigator` before phase decomposition when:
+- The task modifies an existing codebase
+- File ownership, integration points, or validation commands are still unclear after reading the approved design
+- Parallelization decisions depend on understanding current module boundaries or likely file overlap
+
+Ask the investigator for:
+- The modules and files most likely to change
+- Existing architectural boundaries and conventions the plan must preserve
+- Integration seams, dependencies, and shared ownership hotspots
+- Validation commands and test entry points already used by the project
+- Parallelization or conflict risks that should prevent batching
+
+Skip the investigator only for greenfield tasks, documentation-only work, or plans where the current turn already established the relevant repo structure from direct reads.
+
+Reuse investigator findings directly in the implementation plan:
+- File inventories should reflect real candidate paths, not placeholders
+- Validation criteria should prefer repo-native commands the investigator surfaced
+- Parallel batches should account for actual ownership overlap and conflict risk
+
+## Plan Generation Methodology
+
+### Input Analysis
+Before generating the plan, thoroughly analyze the approved design document for:
+- Read `task_complexity` from the approved design document's frontmatter. Apply phase count guidance and domain analysis scaling accordingly. Record `task_complexity` in implementation plan frontmatter.
+- Components and their responsibilities
+- Interfaces and contracts between components
+- Data models and their relationships
+- External dependencies and integrations
+- Technology stack decisions
+- Quality requirements that influence implementation order
+
+### Phase Decomposition
+
+Break the implementation into phases following these principles:
+
+1. **Foundation First**: Infrastructure, configuration, and shared types/interfaces come first
+2. **Dependencies Flow Downward**: A phase can only depend on phases with lower IDs
+3. **Single Responsibility**: Each phase delivers a cohesive unit of functionality
+4. **Agent Alignment**: Each phase maps to one or two agent specializations
+5. **Agent Capability Match**: Verify the assigned agent's tool tier supports the phase deliverables (see compatibility check below)
+6. **Testability**: Each phase should be independently validatable
+
+### Phase Ordering Strategy
+
+```
+Layer 1: Foundation (types, interfaces, configuration)
+    |
+Layer 2: Core Domain (business logic, data models)
+    |
+Layer 3: Infrastructure (database, external services, API layer)
+    |
+Layer 4: Integration (connecting components, middleware)
+    |
+Layer 5: Quality (testing, security review, performance)
+    |
+Layer 6: Documentation & Polish
+```
+
+### Agent-Deliverable Compatibility Check
+
+Before finalizing agent assignments, verify each phase's agent can deliver its requirements:
+
+| Phase Deliverable | Required Tier | Compatible Agents |
+|-------------------|--------------|-------------------|
+| Creates/modifies files | Full Access or Read+Write | analytics-engineer, cobol-engineer, coder, copywriter, data-engineer, design-system-engineer, devops-engineer, hlasm-assembler-specialist, i18n-specialist, ibm-i-specialist, integration-engineer, ml-engineer, mlops-engineer, mobile-engineer, observability-engineer, platform-engineer, product-manager, prompt-engineer, refactor, release-manager, technical-writer, tester, ux-designer |
+| Runs shell commands | Full Access or Read+Shell | accessibility-specialist, analytics-engineer, cobol-engineer, coder, data-engineer, database-administrator, db2-dba, debugger, design-system-engineer, devops-engineer, hlasm-assembler-specialist, i18n-specialist, ibm-i-specialist, integration-engineer, ml-engineer, mlops-engineer, mobile-engineer, observability-engineer, performance-engineer, platform-engineer, refactor, security-engineer, seo-specialist, site-reliability-engineer, tester, zos-sysprog |
+| Analysis/review only | Any tier | All agents |
+
+<HARD-GATE>
+Read-Only agents (architect, api-designer, cloud-architect, code-reviewer, compliance-reviewer, content-strategist, solutions-architect)
+CANNOT be assigned to phases that create or modify files. If a phase requires file creation
+and domain expertise from a Read-Only agent, split it: the Read-Only agent produces a spec
+or analysis, then a write-capable agent (typically coder) implements the files based on that output.
+</HARD-GATE>
+
+### Phase Count Guidance
+
+Scale decomposition granularity to `task_complexity` (read from design document frontmatter):
+- **simple**: 1-3 phases. Prefer single-phase execution when feasible. Combine foundation + implementation. Skip separate documentation/polish phases.
+- **medium**: 3-5 phases. Use the layer model but combine Quality and Documentation into the final implementation phase where practical.
+- **complex**: No phase count cap. Full layer decomposition strategy applies.
+
+### Parallelization Identification
+
+Phases can run in parallel when:
+- They have no shared file dependencies (no overlapping files_created or files_modified)
+- They are at the same dependency depth (same layer)
+- They do not share data model ownership
+- Their validation can run independently
+
+Mark parallel-eligible phases with `parallel: true` and group them into execution batches.
+
+## Implementation Detail Requirements
+
+### Per-Phase Specification
+
+Each phase in the plan must include:
+
+#### Objective
+A clear, measurable statement of what this phase delivers.
+
+#### Agent Assignment
+Which agent(s) execute this phase, with rationale for selection.
+
+#### Files to Create
+For each new file:
+- Full relative path from project root
+- Purpose and responsibility
+- Key interfaces, classes, or functions to define
+- Complete type signatures for public APIs
+
+#### Files to Modify
+For each existing file:
+- Full relative path from project root
+- Specific changes required and why
+- Expected before/after for critical sections
+
+#### Implementation Details
+
+Provide sufficient detail for the assigned agent to execute without ambiguity:
+- Interface definitions with complete type signatures
+- Base class contracts with abstract method signatures
+- Dependency injection patterns and registration points
+- Error handling strategy (error types, propagation, recovery)
+- Configuration requirements (environment variables, config files)
+
+#### Validation Criteria
+Specific commands to run and expected outcomes:
+- Build/compile commands
+- Lint/format checks
+- Unit test commands
+- Integration test commands (if applicable)
+- Manual verification steps (if applicable)
+
+#### Dependencies
+- `blocked_by`: Phase IDs that must complete before this phase starts
+- `blocks`: Phase IDs that cannot start until this phase completes
+
+### Dependency Minimization
+
+List only **direct** blockers in `blocked_by`. Do not include transitive dependencies — they inflate dependency depth and prevent parallelism.
+
+Anti-pattern (over-specified):
+- Phase 2: blocked_by: [1]
+- Phase 3: blocked_by: [1, 2] — Phase 1 is redundant, already reachable via Phase 2
+- Phase 4: blocked_by: [1, 2, 3] — Phases 1, 2 are redundant
+
+Result: depths 0, 1, 2, 3 — zero parallel phases.
+
+Correct (minimized):
+- Phase 2: blocked_by: [1]
+- Phase 3: blocked_by: [1] — Only needs Phase 1 output, not Phase 2
+- Phase 4: blocked_by: [2, 3] — Needs both done
+
+Result: depths 0, 1, 2 — Phases 2 and 3 run in parallel at depth 1.
+
+Ask for each dependency: "Does this phase truly need the output of that specific phase, or is it transitively covered?"
+
+If `validate_plan` is available, review its `parallelization_profile` and `redundant_dependency` warnings before presenting the plan. Revise `blocked_by` to eliminate redundancies when possible.
+
+## Agent Assignment Criteria
+
+### Matching Tasks to Agents
+
+| Task Domain | Primary Agent | Secondary Agent | Rationale |
+|-------------|--------------|-----------------|-----------|
+| System design, architecture | `architect` | - | Read-only analysis, design expertise |
+| Cloud architecture, multi-region topology | `cloud-architect` | `devops-engineer` | Architecture first, implementation second |
+| Enterprise integration architecture | `solutions-architect` | `integration-engineer` | Cross-team design before implementation |
+| API contracts, endpoints | `api-designer` | `coder` | Design then implement |
+| Feature implementation | `coder` | - | Full implementation access |
+| Code quality review | `code-reviewer` | - | Read-only verification |
+| Database schema, queries | `data-engineer` | - | Schema + implementation |
+| RDBMS tuning, indexes, migration safety | `database-administrator` | `data-engineer` | DBA analysis before schema/code changes |
+| DB2 administration | `db2-dba` | `data-engineer` | DB2-specific operations and design |
+| Bug investigation | `debugger` | - | Read + shell for investigation |
+| CI/CD, infrastructure | `devops-engineer` | - | Full DevOps access |
+| Internal platforms, paved paths | `platform-engineer` | `devops-engineer` | Platform conventions and implementation |
+| B2B integrations, ETL, message brokers | `integration-engineer` | - | Full integration implementation |
+| SLOs, runbooks, reliability | `site-reliability-engineer` | `observability-engineer` | Reliability assessment plus telemetry implementation |
+| Observability, metrics, traces | `observability-engineer` | - | Full telemetry implementation |
+| Performance analysis | `performance-engineer` | - | Read + shell for profiling |
+| Code restructuring | `refactor` | - | Write + shell access (for validation) |
+| Security assessment | `security-engineer` | - | Read + shell for scanning |
+| Test creation | `tester` | - | Full test implementation |
+| Documentation | `technical-writer` | - | Write access for docs |
+| Release notes, changelogs, rollout | `release-manager` | - | Write access for release artifacts |
+| Technical SEO audit | `seo-specialist` | - | Read + shell + web search |
+| Marketing copy, content | `copywriter` | - | Read/write |
+| Content planning | `content-strategist` | - | Read + web search/fetch |
+| UX design, user flows | `ux-designer` | - | Read/write + web search |
+| WCAG compliance audit | `accessibility-specialist` | - | Read + shell + web search |
+| Requirements, product | `product-manager` | - | Read/write + web search |
+| Tracking, analytics | `analytics-engineer` | `coder` | Implement then instrument |
+| Internationalization | `i18n-specialist` | `coder` | Implement then localize |
+| Design tokens, theming | `design-system-engineer` | `coder` | Tokens then consume |
+| Legal, regulatory | `compliance-reviewer` | - | Read + web search/fetch |
+| Mobile platform work | `mobile-engineer` | `tester` | Mobile implementation plus validation |
+| Model training, inference integration | `ml-engineer` | `tester` | ML implementation plus evaluation |
+| Model registry, drift, model CI/CD | `mlops-engineer` | `devops-engineer` | Model operations and deployment |
+| Prompt design, few-shot, RAG tuning | `prompt-engineer` | `coder` | Prompt spec before integration |
+| Mainframe COBOL, JCL, CICS/IMS | `cobol-engineer` | `tester` | Mainframe implementation and validation |
+| IBM HLASM for z/OS | `hlasm-assembler-specialist` | - | Assembly implementation |
+| IBM i RPG/CL, DB2 for i | `ibm-i-specialist` | - | IBM i implementation |
+| z/OS systems programming, JCL, RACF | `zos-sysprog` | `security-engineer` | System-level analysis and controls |
+
+### Assignment Rules
+1. Match the primary task domain to the agent specialization
+2. Consider tool requirements — does the task need shell access? Write access?
+3. For parallel phases, assign non-overlapping file ownership to each agent
+4. Prefer single-agent phases for clarity; use multi-agent only when distinct specializations are needed
+5. Never assign more files to an agent than it can handle within its `max_turns` limit
+
+### Token Budget Estimation
+Estimate token consumption per phase based on:
+- Number of files to read (input tokens)
+- Complexity of output expected (output tokens)
+- Agent's max_turns limit as upper bound
+- Historical averages: ~500 input tokens per file read, ~200 output tokens per file written
+
+### Resource Estimation
+
+Do not invent provider pricing or model tiers. Agent model selection is runtime-owned through agent frontmatter and runtime configuration. Estimate execution size in stable, codebase-derived terms instead:
+
+- **Input complexity**: number of files likely to be read, average file size, and prior-phase context
+- **Output complexity**: number of files created or modified, validation output volume, and expected handoff detail
+- **Retry budget**: note phases likely to need retries because of broad file ownership, external dependencies, or uncertain validation
+
+Include a lightweight plan-level resource summary when useful:
+
+| Phase | Agent | Est. Files Read | Est. Files Written | Retry Risk | Notes |
+|-------|-------|-----------------|--------------------|------------|-------|
+| 1 | [agent] | [N] | [N] | LOW/MEDIUM/HIGH | [why] |
+
+## Plan Document Generation
+
+### Output Location
+
+The write path depends on whether your runtime provides a Plan Mode surface (check `get_runtime_context`, loaded at session start, step 0).
+
+- **Plan Mode active**: Some runtimes restrict writes to a temporary staging directory during Plan Mode. Write the plan there first, then copy to the permanent location after approval. Call `exit_plan_mode` with the plan path to present the plan for user approval.
+- **Plan Mode not active or not available**: Write the implementation plan directly to the project's plans directory.
+
+Permanent location: `<state_dir>/plans/YYYY-MM-DD-<topic-slug>-impl-plan.md` (where `<state_dir>` resolves from `MAESTRO_STATE_DIR`, default `docs/maestro`).
+
+If your runtime does not provide a Plan Mode transition, track planning progress using the plan-update mechanism from your runtime context, write directly to the final location, and use the user-prompt tool from runtime context for the approval gate.
+
+### Document Structure
+Use the `implementation-plan` template loaded via `get_skill_content`.
+
+### Required Sections
+
+1. **Plan Overview**: Summary of total phases, agents involved, estimated effort
+2. **Dependency Graph**: Visual representation showing phase dependencies and parallel opportunities
+3. **Execution Strategy Table**: Stage-by-stage breakdown with agent assignments and execution mode
+4. **Phase Details**: Full specification for each phase (objective, agent, files, details, validation, dependencies)
+5. **File Inventory**: Complete table mapping every file to its phase and purpose
+6. **Risk Classification**: Per-phase risk assessment (LOW/MEDIUM/HIGH) with rationale
+7. **Execution Profile**: Summary of parallel vs sequential characteristics to inform mode selection:
+   ```
+   Execution Profile:
+   - Total phases: [N]
+   - Parallelizable phases: [M] (in [B] batches)
+   - Sequential-only phases: [S]
+   - Estimated parallel wall time: [time estimate based on batch execution]
+   - Estimated sequential wall time: [time estimate based on serial execution]
+
+   Note: Native parallel execution currently runs agents in autonomous mode.
+   All tool calls are auto-approved without user confirmation.
+   ```
+
+### Completion Criteria
+The implementation plan is complete when:
+- Every component from the design document maps to at least one phase
+- All phase dependencies are acyclic (no circular dependencies)
+- Parallel opportunities are identified and marked
+- Each phase has clear validation criteria
+- File ownership is non-overlapping for parallel phases
+- The user has given explicit approval of the complete plan
+
+Before presenting the plan for approval, check whether `validate_plan` appears in your available tools. If it does, call it with the plan structure and `task_complexity` to verify phase count constraints, file ownership, acyclic dependencies, and agent validity. If it does not, self-check against the phase count limits above.
+
+### Post-Generation
+After writing the implementation plan:
+1. Confirm the file path to the user
+2. Present the dependency graph and execution strategy
+3. Highlight parallel execution opportunities
+4. Provide resource estimates when useful
+5. If your runtime provides Plan Mode, call `exit_plan_mode` with the plan path to present the plan for user approval. If Plan Mode is not available, present the completed plan for user approval using the user-prompt tool from runtime context.
+6. Ensure the approved plan is at `<state_dir>/plans/YYYY-MM-DD-<slug>-impl-plan.md` as the permanent project reference (copy from the staging directory if Plan Mode was used)
+7. Ask if the user is ready to proceed to execution (Phase 3)
+8. Upon approval, create the session state file via the session-management skill