create_plan_queue

You are tasked to produce a plan-queue.json that will start the forgectl planning phase — without a forgectl specifying session. Specs exist on disk as either uncommitted changes you will commit, or as the tip commit already on the branch — but the generate_planning_queue phase is not available because no specifying session was run. This is a FRESH context window — you have no memory of previous sessions. </role>

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

<step_0> Identify the specs to cover

Specs must come from a canonical commit — never from a directory scan and never from an arbitrary window of commit history. Determine the spec set with exactly two methods, tried in order, and a hard gate if neither applies. Once a method matches, its result is the spec set — do not broaden it by also scanning history or the filesystem.

Method 1 — specs provided to us, not yet committed.

Check for spec files that are staged, modified, or untracked, or that the user explicitly named in the invocation:

git status --porcelain -- '*specs/*.md'

If this returns files, or the user named specific spec files/a directory, those files ARE the spec set. Commit them now — group into one or more logically-coherent commits as appropriate (see the main session's own example: unrelated spec changes went into separate commits). These become the canonical commit(s); their hashes feed step_3. Do not add any other spec files after committing, even if related files exist elsewhere in the repo.

Method 2 — nothing provided, so the last commit only.

If Method 1 found nothing (git status is clean for spec paths and the user named no files), check only the single most recent commit — never a wider window:

git show --name-only --format=%H HEAD | grep 'specs/'

If the last commit touched one or more spec files, those files ARE the spec set, and HEAD's hash is the spec_commits value for all of them.

Hard gate — neither method found specs.

If Method 1 and Method 2 both find nothing, STOP. Do not fall back to git log -N, do not fall back to scanning specs/ directories with find. Ask the user which specs or which commit the queue should cover, and wait for their answer before continuing to step_1. </step_0>

<step_1> Group specs by domain

Each spec typically lives at <domain>/specs/<name>.md. The domain is the first path segment.

• Group all specs sharing the same first path segment into one plan entry.
• If specs live outside a <domain>/specs/ structure, ask the user how to group them before continuing.
• Cross-domain specs (e.g. a shared lib/) should be assigned to the domain whose plan will implement them, or split if genuinely separate.

Record the domain list and the specs assigned to each domain. </step_1>

<step_2> Research each domain in parallel

Spawn one sub-agent per domain. Each sub-agent reads the domain's spec files and returns:

1. Suggested plan name — something that describes the initiative, not just "<Domain> Implementation Plan". The name appears in forgectl status throughout the planning sessions.
2. Suggested code_search_roots — at minimum ["<domain>/"]. Add other directories only if the specs explicitly reference code outside the domain (e.g. a shared lib/, another domain's API layer). List the specific cross-domain refs the sub-agent found.
3. kind recommendation — "code" for backend/non-UI work; "ui" for any domain that will need visual QA and end-to-end verification loops after each batch (routes to ui_implementing instead of implementing). Default to "code" when ambiguous.

Instruct each sub-agent: "Read these spec files and return (1) a concise plan name that describes the initiative, (2) the code_search_roots this domain needs, (3) whether kind should be 'code' or 'ui', and brief reasoning for each." </step_2>

<step_3> Resolve spec_commits

Compute spec_commits only for the spec set step_0 determined — never expand it here. For each of those spec files, get its most recent commit hash:

git log -1 --format=%H -- <spec-path>

Under Method 1 this resolves to the commit(s) you just made in step_0. Under Method 2 it resolves to HEAD for every file. Collect the hashes into a deduplicated list per domain.

Run these in parallel; one command per spec file is fine. </step_3>

<step_4> Draft the plan-queue.json

Assemble one entry per domain using the results from steps 2 and 3:

{
  "plans": [
    {
      "name": "<initiative name from sub-agent>",
      "domain": "<domain>",
      "kind": "code",
      "file": "<domain>/.forge_workspace/implementation_plan/plan.json",
      "specs": ["<domain>/specs/foo.md", ...],
      "spec_commits": ["<hash>", ...],
      "code_search_roots": ["<domain>/", ...]
    }
  ]
}

Field notes:

• file path uses .forge_workspace — not .forgectl_workspace
• kind defaults to "code"; set "ui" only for domains that need the QA + e2e verification loop
• spec_commits may be []
• Entry order in plans is the order planning sessions will run — put the most foundational domains first

See ../shared/plan-queue-format.md for full schema and validation rules. </step_4>

<step_5> Present to the user for review

Show the full drafted JSON and a brief summary table:

Ask the user to confirm or adjust:

• Domain ordering
• Plan names
• kind assignments ("code" vs "ui")
• code_search_roots additions
• Any spec grouping changes

Do not write the file until the user approves. This is the last easy chance to adjust before forgectl init locks in the queue. </step_5>

<step_6> Write and validate the file

Write the approved JSON to .workspace/plan-queue.json (create .workspace/ if needed):

python3 -c "import json; d = json.load(open('.workspace/plan-queue.json')); print(f'{len(d[\"plans\"])} plans — JSON valid')"

Then initialize the planning phase:

forgectl init --phase planning --from .workspace/plan-queue.json

Forgectl validates strictly on init. If it exits with an error, it will print the expected schema and the specific field(s) that failed — fix and re-run. Common issues:

• Extra fields in an entry (only the 7 defined fields are allowed)
• plans array is empty
• kind value is not "code" or "ui"

After a successful init, run:

forgectl status

This confirms the session started and shows the first plan entry at planning ORIENT. Hand off to the implementation_planning skill to continue from here. </step_6>

<contextual_information>

Where this sits in the lifecycle

(specs on disk, no forgectl session)
         ↓
  create_plan_queue     ←  THIS skill
  (THIS skill: builds
   plan-queue.json)
         ↓
      planning  →  implementing / ui_implementing
  (one plan.json       (code, + QA/e2e for UI)
   per domain)

This skill is for the no-session entry path. If you have a completed forgectl specifying session, use the generate_planning_queue skill instead — forgectl will auto-generate the queue for you.

Schema reference

• ../shared/plan-queue-format.md — full schema, validation rules, and field definitions
• ../shared/plan-queue-format.json — template
• ../shared/creating-plan-queue.md — step-by-step reference (non-agent prose version)

kind and the downstream phase

kind is carried unchanged from this queue through planning into implementation. Set it correctly here.

</contextual_information>

<IMPORTANT_INFO>

999 This skill does NOT require a forgectl session. Do not run forgectl status or forgectl advance before step_6 — there is nothing to advance until after init.

999 Do not write the plan-queue.json until the user has approved the draft in step_5.

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 before writing.

9999 file paths use .forge_workspace (not .forgectl_workspace).

</IMPORTANT_INFO>