--- name: zplan description: "Turn a rough development request or issue into a repository-grounded plan with acceptance criteria and a self-contained user handoff. Supports zdev planning; UI direction goes through zproto." --- # zplan Read [the workflow contract](../zdev/references/workflow-contract.md). Use `zgh` for read-only repository research. Read [execution environments](../zdev/references/execution-environments.md) before selecting executable scope. Resolve the deduplicated allowed set, task requirements and selected host or portable result; exclude incompatible tasks and carry their unmet acceptance requirements. Read [Project execution](../zdev/references/claude-code-cloud-project.md) only when Project is selected, not merely a candidate. For `-a`, read [continuous development](../zdev/references/continuous-development.md) and reapply the same environment filter each wave on every supported host. Local CLI child work uses substantive-topic subagents when available. Plan the first ready wave and continuation policy separately. Environment choice, continuous scope and merge authority are independent. During the current ChatGPT planning session, GitHub and repository history are read-only: do not create or update issues, epics, labels, comments, branches or PRs; do not commit, push, close or merge. This applies to all helpers delegated from this session. Do not initiate GitHub-write approval requests here. Prepare a complete handoff and proposed tracking content without posting it. The separate implementation prompt must require creation/reuse of tracking issues before implementation and ongoing development notes, as described in [implementation tracking](../zdev/references/implementation-tracking.md). 1. Read repository instructions, current source/config, related issues/PRs, and relevant accessible sibling-chat decisions. Validate claimed root causes against current source; retain the issue's intent when its proposed fix is stale. 2. Resolve the default branch from GitHub unless the user or accepted handoff specifies another. Record base name and inspected commit. A random current feature branch is not an implicit target. 3. Capture problem, outcome, scope, non-goals, accepted decisions, affected components, dependencies, risks, and measurable acceptance criteria. Resolve ordinary choices with a stated recommendation. Ask only when competing interpretations materially change the work. 4. For `-pr` or a selected task whose UI direction must be settled, run zproto before freezing that direction. Under `-a` alone, park unresolved design topics with precise questions and continue independent ready work; do not force a prototype round for every held issue. Accepted feedback supersedes rejected ideas; record Added/Removed/Superseded requirements explicitly. 5. A focused task uses one complete brief and a proposed single tracker. Decompose larger plans into named tasks with scope, acceptance criteria, tests and dependencies per task, ready for an epic and linked sub-issues. Identify matching existing records for reuse and draft missing content inside the handoff. Require the implementation agent to establish tracking before code changes and maintain milestone notes throughout; do not create issues here. A sweep records accepted dispositions without GitHub writes. 6. When a task graph is useful, each task carries its wave, dependencies, execution mode and difficulty with a reason. Dependencies gate execution; waves are descriptive only. Use these as implementation guidance, not requirements for a private orchestration skill or host-specific model. The implementing Codex, Claude Code, or Grok agent chooses from available tools/workers unless the user specifies otherwise. Do not require delegation for a simple task. Use `none` or stable local task keys (for example `task-a`) during planning; the implementing agent maps them to actual issue URLs after creation/reuse. Existing issue URLs are evidence. Never invent IDs. Serialize shared-file/resource conflicts through dependencies. 7. Define focused checks, integration checkpoints, and platform-specific verification. When feasible, establish the baseline; otherwise label it unverified. Record existing failures separately; under `-a`, triage in-scope baseline failures into the queue and preserve unrelated exclusions. Distinguish a human decision from missing access, native evidence or a CI/review gate; do not count unavailable verification as a pass. 8. Review the whole plan, including edge cases and contrary evidence; use an independent reviewer when available, otherwise do a distinct inline review. Verify complete requirement coverage, valid references, and an acyclic dependency graph before handoff. Check that resource ordering actually prevents simultaneous conflicting tasks. 9. Use the complete prompt or maintain `brief.md`, `decisions.md`, and `plan.md` when files improve the handoff. Put all accepted requirements and prototype decisions in readable Chat and prompt text. Never require a ZIP or manifest just to recover the plan, or another session to discover an undocumented local scratch log. 10. Return to zdev for a standalone Codex, Claude Code, or Grok implementation prompt and available artifacts. Resolve normalized flags into explicit accepted scope, UI decisions, tracking steps and merge permissions in plain language. For continuous work, include repeatable backlog refresh, manager/worker ownership when selected, acceptance and integration gates, decision/blocker records, a fresh-sweep end condition and a durable resume point; completion of the first PR is not the stopping condition. The prompt must not contain plugin/private skill invocations, app links, raw planner flags or planning-Chat permissions. Planning does not automatically become implementation.