generate_planning_queue

You are tasked to produce the plan queue that the implementation-planning sessions will consume, using the forgectl scaffold to manage the workflow. This is a FRESH context window — you have no memory of previous sessions. You are continuing work on a long-running autonomous development task. </role>

This phase sits between the specifying session and the implementation-planning sessions. forgectl auto-groups the completed specs into one plan entry per domain and writes <state_dir>/plan-queue.json. Your job is to review that file, reorder and adjust it so each domain's plan covers the right specs and points at the right code, and hand a validated queue to the planning phase.

The queue you produce answers: "Which implementation plans will be produced, in what order, over which specs and code roots?" One downstream planning session then runs per entry in this queue. </task>

<step_0> Confirm prerequisites, then enter the phase

The generate_planning_queue phase cannot be initialized directly (init --phase generate_planning_queue is rejected). It only exists as a transition out of a completed specifying phase:

• The previous specifying session reached COMPLETE (spec reconciliation) and advanced to PHASE_SHIFT (specifying → generate_planning_queue).
• forgectl-state.json exists with completed specifying data (accepted specs grouped by domain, and any code_search_roots set via set-roots).

Run forgectl status first to confirm you are at the specifying PHASE_SHIFT or already inside generate_planning_queue.

If there was no forgectl specifying session (e.g. specs were authored or committed outside forgectl), this phase does not apply. Use the create_plan_queue skill instead — it walks through discovering specs, grouping by domain, resolving commits, and initializing planning directly (see ../create_plan_queue/SKILL.md):

forgectl init --phase planning --from <plan-queue.json>

Otherwise, from the specifying PHASE_SHIFT you have two options:

# Default: enter generate_planning_queue and let forgectl build the queue from completed specs
forgectl advance

# Override: skip this phase entirely with a pre-built queue (jumps straight to planning ORIENT)
forgectl advance --from <plan-queue.json>

Use the default unless you already have a hand-built queue. The override is for full manual control — it bypasses everything below. After the default advance, forgectl is at generate_planning_queue ORIENT.

See: ../shared/generate-planning-queue.md </step_0>

<step_1> ORIENT — forgectl generates the queue

On entry, forgectl:

1. Groups completed specs by domain. Domain order follows the spec queue (order of first appearance).
2. Produces one plan entry per domain:
   • name: "<Domain> Implementation Plan"
   • domain: the domain name
   • kind: "code" (the default) — you mark UI domains "ui" during REFINE
   • file: <domain>/.forgectl_workspace/implementation_plan/plan.json
   • specs: all completed spec file paths for the domain
   • spec_commits: deduplicated commit_hashes from the domain's completed specs
   • code_search_roots: from specifying.domains[<domain>].code_search_roots if set-roots was used, otherwise ["<domain>/"]
3. Writes the queue to <state_dir>/plan-queue.json (e.g. .forgectl/state/plan-queue.json).

Nothing for you to do but advance into review:

forgectl advance

</step_1>

<step_2> REFINE — review and adjust the generated queue

This is the one state where you shape the queue. Open <state_dir>/plan-queue.json and decide what (if anything) to change:

• Mark UI domains — set kind: "ui" (default "code") for any domain that needs the QA + e2e verification loops. This routes that domain's planning→implementation shift to ui_implementing instead of implementing. Leave it "code" for backend/non-UI domains.
• Reorder domains — entry order is the order the planning (and, in interleaved mode, implementation) sessions will run.
• Adjust plan names — make them describe the initiative, not just the domain.
• Edit code_search_roots — add cross-domain roots (e.g. a shared lib/) where a domain's specs reference code outside its own directory.
• Add or remove specs — correct the grouping if a spec belongs with a different domain's plan.
• Leave it unchanged — the generated grouping is often correct as-is.

The architect controls ordering, grouping, and kind here — the scaffold does not.

Advancing validates <state_dir>/plan-queue.json. If it fails, errors print and you stay at REFINE — fix and re-advance:

forgectl advance

</step_2>

<step_3> PHASE_SHIFT — hand off to planning

Advancing consumes the validated queue, sets phase to planning, pulls the first plan, and lands at planning ORIENT:

# Use the queue you just refined
forgectl advance

# Or, last-chance override with a different file
forgectl advance --from <custom-queue.json>

This phase is now done. The downstream implementation-planning session (skill: implementation_planning) takes over at planning ORIENT, processing one entry from this queue at a time. </step_3>

<contextual_information>

Where this sits in the lifecycle

specifying  →  generate_planning_queue  →  planning  →  implementing / ui_implementing
  (specs)        (THIS phase: builds        (one plan.json     (code, + QA/e2e for UI)
                  plan-queue.json)            per domain)

The artifact this phase produces, plan-queue.json, is exactly the queue the implementation-planning session consumes. Every plan entry becomes one planning session.

Plan queue schema

One entry per domain. kind selects the implementation phase ("code" → implementing, "ui" → ui_implementing); the rest identify the specs and code to plan over. Full reference and template:

• ../shared/plan-queue-format.md — schema and validation rules
• ../shared/plan-queue-format.json — template
• ../shared/generate-planning-queue.md — how auto-generation works
• ../shared/creating-plan-queue.md — building a queue by hand (for the --from / skip paths)

Defaults worth knowing

• A domain with no set-roots gets code_search_roots: ["<domain>/"].
• spec_commits may be empty (e.g. when commits were disabled during specifying).
• Domain order in the generated file follows the order domains first appeared in the spec queue.

</contextual_information>

<IMPORTANT_INFO>

999 This phase only produces and refines plan-queue.json. Do NOT write specs, plans, or code here.

999 generate_planning_queue cannot be initialized directly — it requires a completed specifying phase.

9999 The queue is the contract for the downstream planning sessions: one entry = one planning session. Get the grouping, ordering, kind, specs, and code roots right here.

9999 kind decides the downstream phase: "code" → implementing, "ui" → ui_implementing. Set it correctly here — it is carried unchanged through planning into implementation.

</IMPORTANT_INFO>