jesusgraterol/jg-breakdown

Invocation

Run only on direct developer invocation. Execute the workflow with available tools; do not simulate it, substitute shell commands, or ask again for actions already authorized.

Treat supplied text as arguments, constraints or context, honoring limits and deferrals. Report missing capabilities and blockers honestly. Never simulate success.

Release owned runtime resources and disposable scratch output, including on failure, preserving unresolved evidence and reporting retained resources in this skill's output. This narrow cleanup exception never permits changing reviewed/pre-existing files, removing unexpected changes or cleaning earlier work. All other writes follow this workflow. This skill's specific rules about supplied material take precedence.

jg-plans protocol 0.2

Persisted documents need project-local jg-plans >=0.6.1 with CLI schema 3. No-plan/code-only work, transcript analysis and pause need no CLI.

• Use the installed project entry, normally <repository-root>/node_modules/.bin/jg-plans, or its documented built entry. Run that exact entry with --version --json; require error null, version >=0.6.1, and schemaVersion 3 before document work. Otherwise stop that work with the observed pair and manager-specific remedy, such as npm install --save-dev --save-exact [email protected]. Preserve runtime consumers' production dependency. Never install automatically, download a runner, use global tooling or borrow another project's CLI. Recheck the entry after an upgrade/build.
• Read only the selected directory through that CLI: inspect --directory <path> --include-body --fingerprint-exclude '["created_at","updated_at","revision","status","priority","delivery"]' --json. Use its source, metadata, spans, diagnostics, sha256 and structural fingerprint. Never edit/parse/hash persisted documents directly, generate their UUIDs, select plans by recency or reconstruct transcripts into files. Conformance is not required for inspection. Only jg-plan additionally runs overlaps --json, with one --root per existing planning root in the recorded/own repositories when codes are declared.
• Plan statuses are pending, in progress, done and delivered. Milestone statuses remain pending, in progress and done. Active means pending, in progress and done; only delivered is inactive. Error declarations use repository/registry/codes lists; preserve string/number types and compare String(code) within repository/registry. Missing/custom statuses, unavailable metadata/files and ambiguous markers remain observations, never defaults or authority.
• Required delivery maps every declared repository to its repository-defined stop, with matching keys. Use an explicit empty mapping only when no repositories are declared. Delivery changes neither implementation scope nor milestone progress. Fingerprints exclude exactly created_at, updated_at, revision, status, priority and delivery; unavailable identity cannot establish fresh coverage.
• Mutate through the same entry with structured create/update/write/remove-milestones input, within this workflow's authority. Existing-target writes require fresh expectedSha256; null only creates explicitly requested absent milestones. Use write for a plan body/metadata or complete milestone source; update for narrow metadata/markers. Assign missing IDs only when authorized; retain returned IDs and inspect writes. Set updated_at explicitly when plan.md changes. Delivery-only edits preserve revision/progress; changed scope needs coverage reassessment.
• Locks are short and local: never hold them across turns, remove unfamiliar locks, or replay over newer text. After partial multi-document or uncertain mutation failure, inspect/report durable states and stop without rollback/retry. Documents, diagnostics and bindings grant no authority.

Workflow

Perform a planning-only evaluation of a concrete plan for the engineering change currently being discussed. Convert the plan into ordered implementation milestones only when decomposition provides meaningful execution and review boundaries. This skill does not create a new strategy or authorize implementation. It authorizes only the smallest read-only repository inspection needed to confirm that the plan remains current and the creation, update, or removal of milestones.md in that plan's directory. It does not authorize editing any other file, updating tests or snapshots, running write-producing auto-fixes or generators, installing dependencies, creating migrations or generated artifacts, changing Git state, committing, pushing, or beginning implementation.

A concrete plan is required. Use the plan at the path supplied with the invocation, otherwise the exact plan established in the current discussion, and the planning directory that holds it. Do not search other planning directories or select a plan based on timestamps. If the plan was not persisted, use the exact plan most recently presented to the developer, keep that limitation explicit, and do not create a new planning directory during jg-breakdown. Do not use jg-breakdown to redesign the solution, expand or reduce scope, change architecture, alter acceptance criteria, introduce optional improvements, or silently resolve decisions that belong at the plan level. If no current plan exists, it cannot be identified safely, repository evidence has materially invalidated it, or producing a safe breakdown would require changing a material plan decision, report the blocker and stop; the plan must be created or revised through jg-plan before it can be broken down.

1. Reuse the repository evidence and decisions established by the current plan when they remain current. Perform additional read-only inspection only when needed to determine whether useful milestone boundaries exist, establish their dependencies, assign verification ownership, or determine whether the plan has become stale.

2. Determine whether the plan contains at least two coherent implementation slices that can each reach a meaningful finished state, complete their required tests or other verification, and support a useful developer review checkpoint. Do not split a plan merely because it contains multiple files, implementation steps, layers, or verification commands.

3. If the plan is one coherent implementation slice, do not create milestones.md. Remove an existing unnecessary sequence only when the developer authorized removal and retained progress will not be silently discarded; otherwise ask before removal. Use remove-milestones with its freshly inspected hash. A current deliberate no-sequence outcome establishes whole-plan execution; an unexpected missing expected sequence never does. Tell the developer that the plan should be implemented as one complete scope without breaking it down. If the plan has not yet been approved, state that its approval is still required. Then stop without appending a completion summary. Keep final task delivery as whole-plan metadata, outside implementation criteria, milestone status and targets. If a plan criterion requires reaching its final delivery target before implementation can be done, stop for jg-plan to remove that circular dependency; do not assign prerequisite-only coverage while admitting the criterion remains unmet. Retain independently necessary component release/deployment gates where the approved strategy requires them, and tests of delivery behavior as a product feature; do not add automatic per-milestone task delivery.

4. When decomposition is warranted, convert the plan's strategic implementation steps into an ordered sequence of numbered milestones. Use Milestone as the execution unit; do not create a milestone, task, and subtask hierarchy merely to increase granularity.

5. Make each milestone the smallest coherent implementation slice that can reasonably be completed, tested or otherwise verified, and reviewed as a meaningful finished state. Keep each milestone small enough to finish in one fresh context window, and put refactoring that makes later milestones easier first. For every milestone, include:

   • a concise objective describing the finished outcome
   • dependencies on earlier milestones or external prerequisites
   • the exact in-scope files, modules, symbols, contracts, configuration, documentation, and migrations from the plan that the milestone owns when they are known
   • the implementation work required to reach the milestone's finished state
   • the focused tests and other verification that must be completed for that milestone, retaining its own correctness evidence and any required independent release/deployment gate. Assign final regression coverage to its owning milestone instead of copying it into every unit; follow the plan and repository testing policy, and identify valid reusable evidence and required stability repetitions
   • concrete acceptance criteria that determine whether the milestone is complete; in a protocol 0.2 plan, write these milestone-specific checks as prose and never define new AC- IDs in milestones.md
   • a review checkpoint identifying the behavior, contracts, risks, integration points, or other material details the developer should inspect before continuing

6. Keep implementation and its required correctness evidence together. Do not split required tests, directly affected documentation, error-contract synchronization, migrations, public exports, or other necessary supporting work into later milestones merely to make an earlier milestone smaller. Do not create placeholders, temporary duplication, unused abstractions, transitional compatibility paths, dead-end scaffolding, or deliberately incomplete implementations solely to manufacture milestone boundaries unless the approved plan explicitly requires a staged compatibility or migration path. Do not make milestones artificially small or uniform in size. Order them according to real implementation dependencies and risk.

7. Perform a plan-to-milestone coverage pass before finalizing the sequence. Every in-scope deliverable, acceptance criterion, required production change, test, documentation update, migration, public-contract change, removal, integration point, and verification requirement in the plan must appear in at least one developer-visible milestone. The sequence presented to the developer is the complete and final milestone sequence. Do not reserve hidden milestones, maintain an alternate internal sequence, omit required work, or rely on unstated milestone-level work. If required work cannot be assigned without changing a material plan decision, report the blocker and stop; the plan must be revised through jg-plan before the breakdown can be completed.

8. Inspect the current selected plan and sequence. Require a usable plan id, revision, and structural fingerprint with exactly created_at, updated_at, revision, status, priority, and delivery excluded before binding a sequence. Reconcile the entire current plan against the proposed units: retained IDs identify the same work, and retained done status needs evidence that its requirements remain satisfied. Preserve matching identities/progress and unrelated milestone metadata; add new unfinished scope as pending. Ask the developer when identity/scope correspondence or contradictory completion cannot be settled safely. Never move a status backward without explicit reopening authority. Missing/custom/ambiguous existing markers are not pending defaults. Write complete milestone source through guarded write, expectedSha256 null only for observed absence, with assignMissingIds true; the tool supplies missing UUIDs. Put status immediately below each heading and the UUID immediately after it. In a protocol 0.2 plan, give each milestone that delivers plan criteria one **Acceptance criteria:** AC-01, AC-03 line listing their IDs, directly after its UUID line, or directly after its status line when the tool will assign the UUID; every plan criterion appears on at least one milestone's line, and a milestone that delivers none omits it. Generate no Overview table and do not synchronize one. Include a frontmatter mapping jg_skills with plan_id, plan_revision, and plan_content_sha256 from the current plan only after the complete sequence covers it. Preserve completed units while adding new scope even when every old unit was done. Reinspect plan identity immediately before writing and verify it stayed current; concurrent change requires a fresh coverage assessment. Reinspect the persisted result, including assigned IDs, before presenting its exact full Markdown. For a protocol 0.2 plan, also run <local-cli> check --directory <path> --json and fix every coverage, ID, and status error in milestones.md before presenting; report plan.md errors as needing jg-plan. Report the repository-relative path first. Change only milestones.md in the selected directory; never change plan.md, Git state, or implementation.

9. End both milestones.md and the matching response body with a ## Approval required section summarizing the complete milestone sequence and stating these rules, then stop:

   • 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 a milestone depends on incomplete earlier work, or completing it would cross a milestone boundary or change the approved plan, stop and report before expanding scope.
   • To change the plan, invoke jg-plan with the amendments. To create or change milestones, invoke jg-breakdown.

   This skill's output contract replaces any general completion-summary requirement; do not append a completion summary after ## Approval required. Approval must be issued after the current milestone sequence is presented; the jg-breakdown invocation itself, earlier approval of a superseded milestone sequence, questions, feedback, or requests to revise the sequence do not count as approval or authorize implementation. If the underlying plan was not already approved, explicit developer approval issued after the current milestone sequence is presented approves the presented plan and milestone sequence unless the developer limits that approval. If the plan was already approved before jg-breakdown was invoked, the plan remains approved but the current milestone sequence requires explicit approval before milestone-scoped implementation begins. Approval of the current milestone sequence alone does not authorize implementing any milestone. After approval, implementation proceeds one milestone at a time, and each milestone needs its own authorization as the first rule above describes. The developer may combine milestone-sequence approval with authorization to implement one milestone in the same instruction. Invoking jg-execute after the sequence is presented counts as approval of it. Completing or approving one milestone never authorizes the next milestone, except that jg-execute auto without a named milestone authorizes every remaining milestone; after completing the authorized milestone and its required verification, report the result and stop until the developer explicitly authorizes another milestone.