jg-plan

Invocation

This skill runs only when the developer invokes it. Execute its workflow with the available tools. Do not explain it, simulate it, return equivalent shell commands, or ask for confirmation of actions this skill already authorizes.

Treat the text supplied with the invocation as arguments, constraints, or context, and honor qualifications that limit or defer execution.

If repository access or a capability the workflow needs is unavailable, or one of its stopping conditions is reached, report the blocker and stop. Never simulate success.

Release runtime resources and remove disposable scratch output this skill deliberately created, including after a failure, while preserving evidence needed to investigate unresolved failures. Report anything retained within this skill’s output format. This cleanup is a narrow exception to the skill’s write limits. It does not authorize creating other resources, changing reviewed or pre-existing files, removing unexpected changes, or cleaning up earlier work. Every other write is defined by this skill’s workflow.

This skill’s own rules about supplied material take precedence over this section.

Workflow

Perform a planning-only workflow for the concrete engineering change currently being discussed, including a new module, package, feature, bug fix, refactor, migration, or other implementation. This skill authorizes proportional repository inspection, non-writing analysis, and only the planning-file writes defined in this skill. It does not authorize editing source code, tests, snapshots, configuration, dependencies, migrations, generated artifacts, ordinary project documentation, Git state, or any file outside the plan’s planning directory, and it does not authorize committing, pushing, or beginning implementation. Treat the current discussion, including the user’s objective, decisions, constraints, exclusions, and acceptance criteria, as the task contract. If an inspection command unexpectedly changes files, preserve and report those changes without cleaning, reverting, or claiming them as part of the plan.

1. Read the root README.md and its project blueprint when present, then the repository’s coding instructions (such as AGENTS.md or CLAUDE.md) and the implicit jg skills that apply to the affected files, and follow every applicable domain-specific section of those instructions and skills. When sources conflict, follow the repository’s coding instructions. Without them, apply this order: the explicit developer request and acceptance criteria, unless they would create safety, security, privacy, data-integrity, or production-correctness risk; then safety, security, privacy, data integrity, and production correctness; then established codebase behavior, public contracts, and patterns; then repository tooling. Reuse repository evidence already established during the current task only when it remains current; otherwise inspect the smallest complete affected path (entry points, callers, validation, persistence, side effects, tests, configuration, and integration points) needed to ground the plan in the existing architecture, conventions, behavior, contracts, tests, tooling, and documentation.

2. Settle every decision the plan depends on before writing it. Identify the decisions the plan would make and sort each by who owns it:

   • decided in the discussion: use it as agreed
   • answered by the repository, such as an established convention or pattern: decide it and cite the evidence; look facts up instead of asking for them
   • the developer’s: behavior users see, what is in or out of scope, public contracts, schemas and persisted data, security and authorization, new dependencies or infrastructure, anything hard to undo, and tradeoffs the repository has no precedent for
   • low-stakes and easy to undo: choose a default

   Ask about every decision that belongs to the developer in one numbered message, each question with your recommended answer and what it changes, so a plain yes accepts them all, then stop without writing plan.md. Ask only questions whose answers change the plan. When the developer answers, continue this workflow without a new invocation, and ask again only when the answers or further inspection raise new decisions that belong to the developer. When the request is too open to recommend answers, because the goal or the approach itself is unsettled rather than a few choices within it, ask nothing: say briefly what is missing, suggest thinking it through with jg-brainstorm first, show an example invocation of it built from the developer’s request, and stop. When the codebase is unavailable or cannot be inspected, state the limitation, keep every assumption explicit, and do not claim alignment with repository-specific conventions.

3. Produce a highly detailed, implementation-ready plan that remains strictly bounded by the task contract. Cover each of the following when applicable:

   • the current behavior and the repository evidence that establishes it
   • the desired final behavior, in-scope deliverables, explicit exclusions, and acceptance criteria
   • the proposed architecture, module ownership, data flow, integration points, and public-contract implications
   • the exact files, modules, symbols, exports, schemas, configuration, documentation, and tests to add, modify, or remove
   • the ordered strategic implementation steps, dependencies between them, and the review checkpoints that matter to the overall implementation; keep these steps detailed enough to guide implementation, but do not decompose them into independently executable milestones unless the user invokes jg-breakdown
   • validation, error handling, security, authorization, persistence, concurrency, migration, deployment, compatibility, and rollback considerations
   • focused tests, broader regression checks, and the exact repository verification commands that should be run
   • every decision the plan rests on and its source: the developer, the repository (with its evidence), or your own default, so the developer can check your defaults before approving; never leave a decision open, ask under step 2 instead
   • risks, edge cases, assumptions, and blockers

4. Make every proposed step clean, clear, minimal but complete, easy to review, consistent with the current architecture and conventions, and compliant with the repository’s coding instructions. Explain material design choices using repository evidence. Keep optional enhancements, speculative abstractions, unrelated refactors, and broader cleanup outside the implementation steps unless the task contract requires them. Before presenting, reread the plan: cut lines that decide nothing, such as ‘handle edge cases’, make names and signatures match across steps, and describe changes instead of writing out the code.

5. Plan one authoritative final implementation. When the requested change replaces existing behavior, identify dead, superseded, transitional, compatibility, fallback, deprecated, or parallel paths made unnecessary by the change and include the removal of their code, exports, tests, configuration, and documentation. Preserve a compatibility path only when repository evidence shows that it is required by a supported public contract, rolling deployment, migration, persisted data, supported version, documented behavior, or explicit developer direction; state why it is required and, when temporary, the condition under which it can be removed. Do not include unrelated legacy cleanup.

6. Before presenting a new plan, create <repository-root>/coding-agent-planning/<unix-seconds>_<descriptive-slug>/, using a Unix timestamp captured when the directory is created followed by a concise kebab-case slug derived from the task. Examples: 1787592334_sign-in-flow/ and 1787592334_database-schema-refactor/. If the generated path already exists, capture a new timestamp instead of overwriting it. Write the complete plan to plan.md. When invoked while a current plan exists in this conversation, or with a path to one, revise that plan. Reuse its directory, update plan.md to reflect the current repository state, completed work, and remaining scope, and remove milestones.md if present, reporting that the breakdown must be regenerated. This applies even after approval or after implementation has started; do not create a new planning directory solely because development is underway. When a jg-challenge-plan result for this plan precedes the invocation, apply its required corrections and the developer’s answers to its numbered decisions, unless the developer limits or overrides them. When the invocation or the discussion since that plan clearly describes a different task, create a new plan. When it is unclear, ask. Do not create or modify any other file. Do not change .gitignore, .git/info/exclude, the Git index, commits, or other Git state; the developer decides whether the planning directory is tracked or ignored. If the repository root or required write capability is unavailable, present the complete plan, state that it was not persisted, and do not claim that the file or directory exists.

7. When plan.md is persisted, report its repository-relative path before presenting the plan body. The complete Markdown body presented to the developer must match plan.md exactly, without omitted sections, hidden steps, or materially different wording. End both plan.md and the matching response body with a ## Approval required section that summarizes the exact implementation scope awaiting approval and states these rules, then stop:

   • Implementation starts only after explicit approval given after this plan was presented.
   • When a milestone sequence exists, each milestone needs its own explicit authorization, is the complete scope of that request, and ends at its review checkpoint. Invoking jg-execute authorizes the milestone it runs; jg-execute auto authorizes every remaining milestone, or only the milestone it names.
   • If repository evidence would materially change the plan, stop and request a revision through jg-plan.
   • To change this plan, invoke jg-plan with the amendments. To create or change milestones, invoke jg-breakdown. To implement the plan, invoke jg-execute, or jg-execute auto to also review and push each milestone.
   • Only when the plan has at least two parts that can each be finished, verified, and reviewed on their own, such as separate packages, repositories, or releases, or this revision removed milestones.md, add a rule that names the reason and says to invoke jg-breakdown before jg-execute, because jg-execute otherwise runs the whole plan as one unit and doesn’t stop at the plan’s review checkpoints. Otherwise leave it out.

   This skill’s output contract replaces any general completion-summary requirement; do not append a completion summary after ## Approval required. Until the developer explicitly approves the presented plan, do not begin implementation or modify files except through an invocation of jg-plan or jg-breakdown, each limited to the planning-file writes authorized by its own instructions. Approval must be issued after the plan is presented; the jg-plan invocation itself, answers to its questions, earlier implementation intent, questions, feedback, or requests to revise the plan do not count as approval. Invoking jg-execute after the plan is presented counts as approval. After approval, treat the approved plan together with any developer amendments as the implementation contract. If later repository evidence would materially change that plan, stop and obtain approval for the revised plan before deviating.