plan-round

name	plan-round
description	Use when starting a new round (substrate-touching / fix-round / admin) to generate a complete handoff doc from scope + prior-round context. Dispatches the planner sub-agent and validates output before writing.

plan-round

Generates a round handoff at docs/superpowers/plans/{YYYY-MM-DD}-{round_name}-handoff.md by dispatching the planner sub-agent with a self-contained brief, then validating its output against the corresponding handoff template (18 / 12 / 10 section).

When to invoke

• User says "let's plan R{N}" or "create handoff for R{N}"
• User runs /plan-round slash-command
• A new round-name appears in conversation without a corresponding handoff doc

Prerequisites

Requires the arcgentic CLI installed (the Python toolkit):

• Stable: pipx install arcgentic (post-v0.2.0 PyPI release)
• Dev (in this repo): cd toolkit && pip install -e ".[dev]"

The CLI runs in a subprocess; this markdown skill is the thin shim that invokes it.

For V1 rounds with external workflow inputs, first validate source/spec context:

arcgentic source-intake validate docs/source-intake/*.yaml
arcgentic capability-registry build <marketplace-catalog.json>
arcgentic spec-governance status <change-dir>

For projects with project.session_mode already set, include the inherited mode and dispatch order in the handoff instead of asking again:

arcgentic orchestrator-dispatch \
  --round <round_name> \
  --handoff <handoff-path> \
  --mode <single-session|multi-session>

Inputs

Parse from $ARGUMENTS (passed by Claude Code):

• round_name — e.g. "R10-L3-aletheia" or "R1.6.1"
• round_type — one of: substrate-touching | fix-round | entry-admin | close-admin | meta-admin-sweep
• prior_round_anchor — full 40-char SHA of prior round's last commit
• scope_description — optional 1-3 sentence scope (can be filled later in handoff)

If any required input is missing, ASK the user before proceeding.

Workflow

When invoked with all inputs:

1. Validate round_name matches the pattern R<phase>[.<round>[.<fix>]] or R<phase>-<name>.

2. Validate prior_round_anchor is a full 40-character hex SHA (NOT short).

3. Shell out to the CLI:

   arcgentic plan-round-impl \
     --round=<round_name> \
     --type=<round_type> \
     --anchor=<prior_round_anchor> \
     --scope=<scope_description>
   

4. Read the CLI's stdout — it contains either:

   • plan-round succeeded: wrote <path> + section_count + loc + (optional) warnings
   • FAILED: <error> (exit code 1 or 2)

5. Report to the user: handoff path, section count, dispatch order, and any warnings.

6. If validation failed (exit code 1 or 2): explain the failure + suggest a fix (re-run with correct anchor, etc.).

Failure modes

• Missing args: ask the user.
• CLI not installed: instruct user to pipx install arcgentic or pip install -e toolkit/.
• CLI returns FAILED with TBD/TODO/XXX warning: this is the planner self-check working — the planner's output had unfilled placeholders. Re-run with more specific --scope=... OR open the handoff file at the reported path and fill the placeholders manually.
• Section count mismatch: the planner produced wrong number of sections. Possible causes: template files (templates/handoff_*) updated but skill cache stale — surface as a bug.

See also

• agents/planner.md — the sub-agent dispatched by this skill (defines the planner's role + output contract)
• templates/handoff_18_section.md / handoff_12_section.md / handoff_10_section.md — section templates
• toolkit/src/arcgentic/skills_impl/plan_round.py — Python algorithm (full validation logic + adapter dispatch)
• skills/source-intake/SKILL.md — V1 external source record workflow
• skills/spec-governance/SKILL.md — V1 spec artifact workflow
• spec § 4.1 — full algorithm specification
• spec § 5.1 — planner agent contract
• spec § 7 — handoff doc templates (authoritative)