to-plan

name	to-plan
description	Trigger only when a coding task requires a written implementation plan before execution, especially multi-file or multi-step work needing dependency analysis, wave classification, and file-isolation-safe task partitioning; dispatches Planner to write a timestamped plan under ~/.yi-workflow/docs/plans/ and performs no implementation.
requires	[]

to-plan — Deterministic Planning Skill

1. Trigger Boundary

Use this skill only when all conditions hold:

• The user needs a coding implementation plan, not immediate implementation.
• The task is multi-step, multi-file, risky, ambiguous, or requires task partitioning.
• The expected deliverable is a structured plan file with waves, tasks, dependencies, file ownership, and verification criteria, stored under ~/.yi-workflow/docs/plans/.

Do not use this skill for:

• Simple one-file edits or obvious mechanical fixes.
• Executing an already-approved plan; use execute-plan instead.
• Reviewing an existing diff; use review-diff instead.
• Verifying completed work; use verification instead.

2. Non-Negotiable Constraints

• Planning only. Do not modify product source, tests, docs, config, or dependencies while this skill is active.
• No implementation leakage. Do not write patches, apply fixes, or run mutation commands.
• Main agent must not inspect product source. Do not use Read, Grep, Glob, Bash search, or similar tools on product source files. For normal planning, if evidence is insufficient, dispatch Explorer again with a narrower question. For the bounded cleanup fast path, a non-empty first Explorer result is sufficient evidence; dispatch Planner with conservative sequencing and risks instead of dispatching any follow-up Explorer.
• Main agent is orchestration-only. The main agent dispatches subagents, validates their structured outputs, and emits the final YAML summary. It must not call Write/write, Bash, shell, ctx_execute, scripts, Python, Node, date, mkdir, or equivalent tools for plan artifact writing, timestamp generation, path probing, directory creation, filesystem preparation, or fallback plan creation.
• Guard violations are workflow failures. If a tool is blocked by the workflow guard, do not retry the same blocked operation. If the blocked operation was command execution for timestamp generation, path probing, directory creation, filesystem preparation, plan writing, or plan-path construction, stop with status: blocked; never continue with a guessed, placeholder, or fallback path. For evidence gaps, switch to Explorer only when the fast-path state machine still permits exploration.
• No user-visible text before the final YAML. During this skill, every assistant message before the final response must contain tool calls only and no text content. The main agent must stay silent except for tool calls until it emits the final YAML summary. Do not print progress updates, Explorer summaries, task-merging explanations, Planner-dispatch narration, validation commentary, approval prompts, headings, or any other text before the final response; do not include commentary in the same message as a tool call. Place all human-readable explanation only inside final YAML fields.
• Final output is YAML-only summary. The final user-visible response must contain exactly one YAML document using the final summary schema only. It must start with status: and end immediately after the final YAML field. It must contain no prose, headings, bullets, approval requests, summaries, separators, markdown tables, fenced code blocks, progress text, or full PLAN.md body before or after it. Any final response containing triple backticks, markdown separators such as ---, or markdown table separators such as |--- is invalid. If approval is needed, encode it only as nextAction: approve-plan.
• Every task must declare file scope. A task without files: [] is invalid unless it is explicitly verification-only or research-only.
• Every wave must declare execution type. Valid values are only concurrent or sequential.
• Concurrency requires proof. A concurrent wave is valid only when task file sets are pairwise disjoint and no task depends on another task in the same wave.
• Same-file inferred tasks must be merged or sequenced. Before declaring a concurrent wave, group inferred tasks by file set. If two tasks edit the same file or overlapping file sets, merge them into one task or classify them as sequential; never place overlapping file scopes in a concurrent wave.
• Uncertainty is sequential. If dependency or file isolation cannot be proven, classify the wave as sequential.
• Plan validation is mandatory. Do not present a plan until all required fields pass the validation checklist below.
• Canonical plan storage is global and Planner-owned. Planner must write the approved-planning artifact under ~/.yi-workflow/docs/plans/ with a real second-precision timestamped filename: plan-YYYYMMDD-HHMMSS-{slug}.md. The main agent must not write this artifact, create parent directories, or construct fallback paths. Do not use project-root ./PLAN.md, project-local docs/plans/, singular ~/.yi-workflow/docs/plan/, or any product-repo path as the canonical plan path, and never use placeholder, rounded, copied, guessed, or hard-coded timestamp values such as 000000, 120000, 123456, or example dates.

3. Progressive Disclosure

Load auxiliary files only when needed:

• For non-fast-path planning, read assets/plan-template.yaml before writing or validating PLAN.md structure.
• Read reference/wave-classification.md only when file overlap, semantic dependency, broad glob scope, or concurrency ambiguity exists.
• Read reference/dispatch-contracts.md only when composing a non-standard subagent prompt or when Explorer output quality was insufficient.
• Read reference/tool-boundaries.md only when actor permissions are ambiguous.
• Read examples/wave-classification-cases.md only when an edge case needs comparison.

Do not inline large templates, examples, or reference tables into the active reasoning unless they are required for the current decision.

4. Fast Path for Bounded Text-Reference Cleanup

Use this fast path when the user names an explicit search term or obsolete reference and asks to clean, update, or plan removal across the repository.

Eligibility requires all assertions:

• The task is bounded by a concrete string, symbol, feature name, or obsolete dependency.
• The requested deliverable is a cleanup/update plan, not immediate edits.
• Expected changes are documentation, comments, config references, dead code references, or narrowly scoped symbol cleanup.
• No external research, bug diagnosis, or architecture redesign is required.

Fast-path hard state machine:

1. Activate this fast path as soon as all eligibility assertions hold.
2. Dispatch exactly one Explorer using the inline reference-cleanup prompt below.
3. Wait for Explorer once.
4. If Explorer returns any non-empty matches or inferredTasks, set explorationClosed: true; the only valid next state is Dispatch Planner.
5. Before Planner dispatch, group inferred tasks by identical or overlapping files and instruct Planner to merge same-file cleanup actions into one task unless a sequential dependency is explicitly required.
6. Dispatch exactly one Planner with the original user goal, the first non-empty Explorer result, fastPathReferenceCleanup: true, explorationClosed: true, plannerEvidenceBoundary: use Explorer payload only; do not search/read/grep/find product source, requiredNextAction: approve-plan when planned, revise-plan when blocked, planDirectory: ~/.yi-workflow/docs/plans/, canonicalPathPattern: plan-YYYYMMDD-HHMMSS-{slug}.md, writeResponsibility: planner, and forbidLocalFallback: true. Planner must write the canonical artifact, return raw unfenced YAML whose first visible characters are exactly status:, return the exact planPath string for the written artifact, and include counts, validation, blockedReason, and nextAction.
7. The main agent must not write the plan, call Write/write, call command execution tools, create directories, probe paths, generate timestamps, construct fallback paths, normalize planPath, patch missing Planner metadata, or write project-local plans during this fast path. If Planner cannot write a canonical artifact, returns status: blocked, returns singular ~/.yi-workflow/docs/plan/, returns a product-repo path, returns any metadata whose first visible characters are not exactly status: (including prose-wrapped or fenced YAML), omits nextAction, omits any other required metadata, or returns a planPath whose timestamp component matches a known artificial placeholder pattern (000000, 120000, 123456, 201500, 235959, or any obviously not-real second-precision time), return the blocked final summary branch with planPath: null, all counts 0, a non-empty blockedReason, and nextAction: revise-plan. Do not scrape, recover, repair, or parse YAML out of prose-wrapped Planner output. A placeholder-timestamped planPath means Planner did not write a real canonical artifact; the main agent must reject it rather than echo it.
8. If explorationClosed: true, do not dispatch Explorer again for any reason, including missing confidence, unsafe action, exact context, usage checks, line verification, or output cleanup.
9. Explorer should return raw JSON with first visible character { and last visible character }. The main agent must not manually scrape arbitrary JSON from prose, fences, headings, bullets, or malformed output. Planner dispatch is allowed only when the runtime guard has observed and accepted exactly one schema-valid Explorer payload; the guard may mechanically canonicalize one unambiguous reference-cleanup JSON object from tool-result transport. If the runtime guard blocks Planner dispatch, stop with the blocked final summary branch; do not ask for restatement, retry, or perform a new repository search. Set blockedReason to explain that Explorer payload validation failed and nextAction: revise-plan. Do not read Explorer/subagent output files or task transcript files to diagnose the guard block — the guard's blocked reason is sufficient; probing guard-blocked read operations is a protocol deviation. Do not propose bypassing the planning workflow (e.g., "skip planning, execute directly") as a recovery path; a blocked fast path means nextAction: revise-plan, not find-another-way-to-proceed.
10. If Explorer returns zero matches and low confidence, stop with status: blocked using the blocked final summary branch with planPath: null, all counts 0, and nextAction: answer-clarifying-questions; ask for a narrower search term only inside blockedReason or notes.
11. Complete the workflow in at most four main-agent model turns after skill activation.

Inline Explorer prompt for this fast path:

Use this prompt shape directly; do not invent a narrative search prompt and do not load reference/dispatch-contracts.md just to compose it. The exclude array is an exact literal contract. Unless the user explicitly names additional paths to exclude before this skill is activated, the Explorer prompt must contain exactly these five entries, in this order, and no others: node_modules, venv, .git, dist, build. Do not add common cache, language, framework, generated, or project-specific directories by default, including .cache, __pycache__, .pytest_cache, .pytest_dbs, .ruff_cache, .mypy_cache, coverage, tmp, logs, ui, frontend, backend, docs, or tests unless the user explicitly requested them.

mode: reference-cleanup
searchTerms:
  - "{concrete obsolete string, dependency, feature name, or symbol}"
goal: "{cleanup/update planning goal}"
exclude:
  - node_modules
  - venv
  - .git
  - dist
  - build

Return raw JSON only. The first character of your response must be `{` and the last character must be `}`. Do not use markdown, fenced code blocks, headings, bullets, prose, or tables.

Use one broad repository search for the requested terms, classify matches, infer compact cleanup tasks, and stop. Do not perform dependency analysis, usage investigation, exact-context expansion, or confirmation searches unless explicitly requested by the user before this skill was activated.

Return this JSON object only:
{
  "summary": "string",
  "searchedScopes": ["string"],
  "excludedScopes": ["string"],
  "matches": [
    {
      "file": "string",
      "line": null,
      "snippet": "string",
      "classification": "active-code|dead-code|migration|config|documentation|comment|test|generated|plan-artifact|unknown",
      "recommendedAction": "remove|update|retain|verify-before-change",
      "risk": "low|medium|high",
      "rationale": "string"
    }
  ],
  "inferredTasks": [
    {
      "idHint": "string",
      "description": "string",
      "files": ["string"],
      "dependsOnHints": ["string"],
      "canRunConcurrently": true
    }
  ],
  "verificationHints": ["string"],
  "confidence": "high|medium|low",
  "unansweredQuestions": ["string"]
}

Before dispatching Explorer, validate the composed prompt. If the user did not explicitly provide extra exclusions, the exclude array must equal exactly ["node_modules", "venv", ".git", "dist", "build"]. If extra exclusions were accidentally added, remove them before dispatch. Do not mention or pass implicit exclusions to Explorer.

Fast-path deterministic transitions:

• Once all four eligibility assertions initially hold, do not downgrade to normal planning because a match appears in source, migration, config, schema, tests, or documentation.
• Handle source, migration, config, or schema risk by marking the affected task sequential or adding a risk entry, not by leaving this fast path.
• After a non-empty Explorer result, set explorationClosed: true and do not dispatch any additional Explorer for repository search, usage checking, exact context, line excerpts, function behavior, dependency analysis, confirmation, safety validation, or confidence improvement.
• After explorationClosed: true, Planner must treat Explorer as the sole repository evidence source for this bounded cleanup fast path. Planner must not perform extra repository-wide search, grep, find, read, usage investigation, dependency analysis, or exact-context expansion against product source; it must encode Explorer uncertainty as risks, verification criteria, sequential ordering, or decision points.
• Treat Explorer recommendations such as verify-before-change, low confidence, or unanswered questions as plan risks or sequential tasks, not as permission for a follow-up Explorer.
• If multiple inferred tasks touch the same file, merge them into one task before placing them in a concurrent wave; if they cannot be merged safely, place them in a sequential wave with deterministic order values.
• If you realize an extra Explorer was already dispatched after explorationClosed: true, do not compensate with more exploration; immediately stop all further Explorer dispatches and dispatch Planner with the first non-empty Explorer result.
• If the first Explorer result is raw JSON but lacks optional details, pass it to Planner with instructions to use conservative task wording, sequential ordering, and risk entries instead of asking for more context.
• Planner must not claim it personally verified facts with grep/search/read unless that evidence is present in the Explorer payload. Verification commands may be listed as future verification criteria, not as already executed proof.
• If the user asks to clean, remove, or update obsolete references to a concrete term, do not treat retaining a matched occurrence as completed cleanup by default. Planner must either remove/reword the occurrence, encode a user decision point, or justify retention as explicitly user-approved; otherwise the plan is invalid.
• If removing the only obsolete reference from a small enclosing block would leave an empty no-op wrapper, such as an empty _ensure_columns(..., []) migration call or a vacuous conditional guard, Planner should encode a task instruction and verification/risk note to remove the whole now-empty obsolete block (including the enclosing call/conditional) when local Explorer evidence proves it has no remaining effect. Partial removal that leaves an empty but still-executed wrapper is incomplete cleanup. If local context is insufficient to prove the wrapper is truly no-op, preserve behavior and record a follow-up note instead of broadening scope.
• When dispatching Planner, do not include markdown-fenced YAML templates or fenced code blocks in the Planner prompt. Describe the required artifact fields as plain indented text or bullet requirements, and explicitly require Planner's final status response to be raw YAML only, with first visible characters exactly status:. If Planner output does not start exactly with status:, treat it as invalid and return status: blocked; do not scrape YAML from surrounding prose.

Fast-path forbidden actions:

• Do not dispatch a second Explorer of any kind after any non-empty Explorer result.
• Do not ask for additional source context after Explorer returns any non-empty matches.
• Do not treat verify-before-change, uncertainty, or missing optional details as grounds for follow-up exploration; encode them as risks, sequential ordering, or verification criteria.
• Do not add extra Explorer exclude paths unless the user explicitly requested those exclusions. This includes seemingly reasonable cache or generated exclusions such as .cache, __pycache__, .pytest_cache, .pytest_dbs, .ruff_cache, .mypy_cache, coverage, tmp, and logs.
• Do not call Write/write, Bash, shell, ctx_execute, scripts, Python, Node, date, mkdir, path checks, or any filesystem preparation during this fast path; Planner owns canonical plan writing.
• Do not use placeholder, rounded, copied, guessed, or hard-coded timestamp values such as 000000, 120000, 123456, 201500, or dates copied from examples. The main agent must not generate the filename timestamp; Planner must either write a real canonical artifact or return blocked.
• Do not write or advertise project-root ./PLAN.md, product-repo docs/plans/, singular ~/.yi-workflow/docs/plan/, or any other fallback path as a valid plan.
• Do not put two tasks that edit the same file in a concurrent wave; merge same-file cleanup actions into one task or make the wave sequential.
• Do not load assets/plan-template.yaml; use the minimal PLAN.md schema listed below.
• Do not load reference/wave-classification.md unless candidate tasks overlap, use broad globs, or have unclear ordering.
• Do not load reference/dispatch-contracts.md for fast-path prompt composition; the required prompt is inline above.
• Prefer zero todos for this fast path; if todo tracking is mandatory, create at most two todos total: Explore references and Dispatch Planner, and do not create intermediate investigation todos.
• Do not inspect product source directly from the main agent.
• Do not emit any user-visible text before or after the final YAML response: no progress prose, intermediate summaries, validation commentary, task-merging explanation, Planner-dispatch narration, approval request, headings, markdown separators, markdown tables, bullets, or explanatory text. Before the final response, assistant messages must contain tool calls only; never combine a tool call with a visible text block such as "Good — ...", "Now dispatching Planner", or "Let me wait".
• Do not wrap final YAML in fenced code blocks such as yaml or ; any response containing ``` is invalid.
• Do not include markdown-fenced YAML examples in Planner prompts; fenced examples often cause fenced Planner output.
• Do not paste the full plan body into the final user-visible response; Planner writes it to the global timestamped plan path and the main agent returns only the final summary YAML schema from section 7.
• Do not add nextAction or any other missing metadata to Planner's returned status YAML. If Planner omits nextAction, treat the response as invalid and return the blocked final summary branch.
• Do not read Explorer/subagent output files, task transcript files, or temporary agent artifacts to diagnose a guard-blocked Planner dispatch; the guard-rejected reason in the tool result is the canonical diagnostic source.
• Do not read Planner/subagent output files, task transcript files, or temporary agent artifacts to diagnose a guard-blocked Planner output. The runtime guard now validates Planner output; a guard-blocked Planner output means the Planner returned prose-wrapped, fenced, or otherwise non-raw YAML that the guard rejected before the main agent could consume it. Do not scrape, recover, or parse YAML from the blocked output.
• Do not propose "skip planning, execute directly" or any other planning-workflow bypass when the fast path is blocked; blocked means the workflow cannot produce an approved plan, not that the workflow is optional.

Minimal PLAN.md schema for this fast path:

The following schema is for the written plan artifact only. It must never be pasted into the final user-visible response. The artifact is pure YAML and must start with plan:; do not add markdown fences or YAML document/frontmatter delimiters such as ---.

Plain schema shape:

• plan:
  • id: plan-{date}-{slug}
  • goal: string
  • title: string
• waves:
  • id: wave-1
  • type: concurrent | sequential
  • tasks:
    • id: task-1
    • description: string
    • files: [string]
    • order: number | null
    • dependsOn: []
• verificationCriteria:
  • string that explicitly runs from the product repository worktree only and excludes global plan artifacts, agent session logs, and execution logs
• estimatedEffort:
  • waves: number
  • tasks: number
  • concurrentTasks: number
  • sequentialTasks: number
  • duration: string
• risks:
  • description: string
  • mitigation: string

5. Planning State Machine

State A — Normalize Goal

1. Restate the implementation goal in one sentence.
2. Record user-provided constraints, acceptance criteria, target files, and known risks.
3. If the request lacks enough information to plan safely, ask the minimum required clarifying questions before dispatching subagents.

State B — Gather Evidence

Dispatch information-gathering subagents before planning:

• Explorer is required for codebase structure, dependency graph, and inferred task file scopes.
• Researcher is optional and allowed only when external APIs, libraries, platform behavior, or best practices materially affect the plan.
• Debugger is optional and allowed only when the task is bug, regression, failing test, stack trace, or incident related.

All gathered findings must be summarized as planning inputs. Do not let subagents implement code.

State C — Dispatch Planner to Synthesize PLAN.md

Dispatch Planner with gathered evidence and require it to write the canonical plan artifact at ~/.yi-workflow/docs/plans/plan-YYYYMMDD-HHMMSS-{slug}.md. The Planner prompt must not contain fenced YAML/code templates; describe required fields in plain text. The main agent must not create the plan file, generate the timestamp, probe paths, create directories, normalize Planner's returned path, or invent fallback paths. If Planner cannot write a canonical artifact or does not return a valid parseable raw-YAML planPath under ~/.yi-workflow/docs/plans/, stop with status: blocked. The plan must include:

• plan.id, plan.goal, and plan.title.
• Ordered waves[].
• For each wave: id, type, and tasks[].
• For each task: id, description, files, order, and dependsOn.
• verificationCriteria, estimatedEffort, and risks.

State D — Validate Plan

Before finalizing, assert all invariants:

1. Every wave has type: concurrent | sequential.
2. Every task has a non-empty files array unless it is explicitly research-only or verification-only.
3. Every task has dependsOn as an array.
4. Sequential waves have deterministic order values for every task.
5. Concurrent waves have order: null for every task.
6. Concurrent waves have no intra-wave dependencies.
7. Concurrent wave task file sets are pairwise disjoint.
8. Before concurrency validation, same-file or overlapping-file inferred tasks have been merged into one task or moved into a sequential wave.
9. Risks mention every intentional file overlap, dependency uncertainty, or sequencing constraint.

If any invariant fails, repair the plan before presenting it.

6. Negative Prompts

• Never implement the planned change.
• Never inspect product source from the main agent; dispatch Explorer for all code, docs, config, and test evidence.
• Never retry a guard-blocked Read/Grep/Glob/Bash operation from the main agent.
• Never probe the guard by reading Explorer/subagent output files, task transcript files, or temporary agent artifacts to diagnose a guard-blocked Planner dispatch; the guard-rejected reason is the sole diagnostic source.
• Never probe the guard by reading Planner/subagent output files, task transcript files, or temporary agent artifacts to diagnose a guard-blocked Planner output; a guard-blocked Planner output means the Planner produced prose-wrapped, fenced, or otherwise non-raw YAML, and the guard-rejected reason is the sole diagnostic source.
• Never scrape, recover, repair, or parse YAML out of prose-wrapped or fenced Planner output. If the guard blocks Planner output (first visible characters not exactly status:), return status: blocked — do not attempt to extract YAML from surrounding prose, commentary, artifact verification notes, or fences. The guard-level block means the entire Planner response is invalid; there is no valid YAML to salvage.
• Never propose bypassing the planning workflow (e.g., "skip planning, execute directly", "retry with normal planning", or "which approach would you prefer?") when the fast path is blocked. A blocked fast path must stop with final blocked YAML and nextAction: revise-plan; do not emit follow-up prose asking the user to choose a recovery path.
• Never accept long narrative, markdown-fenced, prose-wrapped, or otherwise non-raw Explorer output for bounded cleanup; the first visible Explorer character must be { and the last must be }.
• Never dispatch a second repository-search Explorer after fast-path Explorer returns non-empty matches.
• Never load assets/plan-template.yaml during the bounded cleanup fast path.
• Never emit any user-visible text before the final YAML, including progress prose, Explorer summaries, task-merging explanation, Planner-dispatch narration, headings, markdown tables, or explanatory text.
• Never wrap final YAML in markdown fences; any final response containing triple backticks is invalid.
• Never include markdown-fenced YAML/code examples in Planner prompts; use plain-text field requirements instead.
• Never include the full plan body in the final user-visible response; return only the section 7 summary schema with the Planner-returned global timestamped planPath.
• Never use placeholder, rounded, copied, guessed, or hard-coded timestamps in planPath; the main agent must use only Planner's successfully written canonical path or stop with status: blocked.
• Never accept a Planner-returned planPath whose timestamp component matches a known artificial pattern (000000, 120000, 123456, 201500, 235959). The main agent must detect placeholder timestamps in Planner's returned planPath and reject them the same way it rejects a missing nextAction field — return status: blocked, planPath: null, all counts 0, and nextAction: revise-plan. Echoing Planner's string does not override placeholder rejection; a placeholder timestamp means Planner did not write a real canonical artifact.
• Never write plan artifacts directly from the main agent, and never call Write/write, Bash, shell, ctx_execute, scripts, Python, Node, date, mkdir, or equivalent for plan writing, timestamp generation, path probing, directory creation, plan-path construction, fallback plan creation, or filesystem preparation.
• Never advertise project-root ./PLAN.md, product-repo docs/plans/, singular ~/.yi-workflow/docs/plan/, or any other local fallback path as a valid plan.
• Never add Explorer exclude paths beyond the inline prompt unless the user explicitly requested them; do not add .cache, __pycache__, .pytest_cache, .pytest_dbs, .ruff_cache, .mypy_cache, coverage, tmp, logs, or framework-specific directories as implicit defaults.
• Never omit file ownership for coding tasks.
• Never mark a wave concurrent because it is faster; concurrency is allowed only when isolation is proven after same-file tasks are merged or sequenced.
• Never hide uncertainty; convert uncertainty into sequential ordering and a risk entry.
• Never output a plan that requires the executor to infer missing dependencies.
• Never include long architecture diagrams, examples, or explanatory prose in the final response.

7. Final Output Format

Final response must be raw YAML text and nothing else, using only one of the final summary branches below. Before sending the final response, apply this output gate:

1. The first visible characters are exactly status:.
2. The first line is exactly status: planned or status: blocked.
3. The response contains exactly one YAML document.
4. There is no text before status: and the response ends immediately after the final YAML field.
5. Do not append approval requests, separators, summaries, markdown bullets, or prose after the YAML. nextAction: approve-plan is the only approval request.
6. If any explanatory paragraph exists, delete every character before status: and move the explanation into summary, notes, or blockedReason.
7. There are no headings, bullets outside YAML lists, markdown explanation, markdown separators such as ---, markdown tables, fenced code blocks, progress commentary, or prose outside YAML fields.
8. Any response containing triple backticks, markdown separators such as ---, or markdown table separators such as |--- is invalid and must be rewritten before sending.
9. Human-readable notes appear only inside summary, notes, or blockedReason fields.
10. Do not paste the full plan content here.
11. Never mention a fallback local path as a usable plan; if one was accidentally written, mention it only as a violation note while keeping planPath: null.

For status: planned, the final summary must follow this branch:

status: planned planPath: ~/.yi-workflow/docs/plans/plan-YYYYMMDD-HHMMSS-{slug}.md summary: string notes:

• string waves: number tasks: number concurrentWaves: number sequentialWaves: number validation: waveTypesPresent: true taskFilesPresent: true dependencyFieldsPresent: true concurrentIsolationProven: boolean sequentialOrdersPresent: boolean blockedReason: null nextAction: approve-plan

Planned branch rules:

• planPath must be non-null, copied exactly from Planner's parseable raw-YAML status response, and must be the written global timestamped path under ~/.yi-workflow/docs/plans/ or the resolved absolute equivalent under the user's home directory.
• The main agent must not normalize, shorten, expand, prettify, or rewrite Planner's planPath; echo the exact string Planner returned.
• planPath must not be project-root ./PLAN.md, bare PLAN.md, product-repo docs/plans/..., singular ~/.yi-workflow/docs/plan/..., or any other fallback path.
• The timestamp in planPath must come from Planner's successfully written canonical artifact, not from main-agent command execution and not a placeholder, rounded, guessed, hard-coded, or copied example.
• If Planner's planPath contains a known artificial timestamp pattern — 000000, 120000, 123456, 201500, 235959, or a segment that is obviously not a real second-precision wall-clock time (e.g. 000000 through 000059, exact-hour values at common placeholder boundaries) — treat it as Planner failing to write a real canonical artifact. Return status: blocked, planPath: null, all counts 0, blockedReason explaining the placeholder-timestamp rejection, and nextAction: revise-plan. Do not echo, normalize, or accept a placeholder-timestamped planPath; the main agent must not pass a placeholder-timestamped path through to the planned branch.
• waves, tasks, concurrentWaves, and sequentialWaves must match Planner output and the written plan.
• blockedReason must be null.
• nextAction must be approve-plan.

For status: blocked, the final summary must follow this branch:

status: blocked planPath: null summary: string notes:

• string waves: 0 tasks: 0 concurrentWaves: 0 sequentialWaves: 0 validation: waveTypesPresent: false taskFilesPresent: false dependencyFieldsPresent: false concurrentIsolationProven: false sequentialOrdersPresent: false blockedReason: string nextAction: answer-clarifying-questions | revise-plan

Blocked branch rules:

• status: blocked means no valid plan artifact is ready for approval.
• planPath must be null; never invent or report a guessed path.
• All plan-derived counts must be 0.
• All validation booleans must be false because there is no finalized plan to validate.
• blockedReason must be non-empty.
• nextAction must never be approve-plan.
• Use answer-clarifying-questions only when the user can unblock the workflow by providing missing input, such as a narrower search term.
• Use revise-plan when the block is caused by workflow, tool, or runtime constraints, such as a missing reliable second-precision timestamp.