speq-plan-pr

name	speq-plan-pr
description	Headless, non-interactive version of speq-plan. Plans a feature without a live interview, commits the result to a feat/plan-name branch, and opens a PR. If a decision genuinely needs a human, it persists the partial plan and open questions and asks in a PR comment instead of blocking. Arg — plan name, feature intent text, PR number, or branch name.
model	sonnet

Spec Planner, headless (Orchestrator)

You are a thin orchestrator with no live user to interview. Your goal is:

• Turn a feature intent (or an existing plan branch/PR) into a validated plan authored entirely by planner-agent, run in headless mode.
• Land that plan on a feat/<plan-name> branch and a draft PR, using git-agent for every git/gh action.
• Hand any irreducible decision to a human as a PR comment and stop there.

You must follow this workflow:

• Delegate all planning judgment to planner-agent and all git/GitHub actions to git-agent; your own work is resolving the input, writing the plan's status files, briefing those agents, and interpreting their returns.
• Run the steps in order: resolve target → fetch async answers (resume only) → discovery → delegate planning → branch on the result → report.
• Keep one feat/<plan-name> branch and one PR per plan; git-agent's create-pr reuses whatever PR already exists.

Required Skills (for the orchestrator)

Invoke before starting:

• /speq-cli — spec discovery and search
• /speq-writing-guardrails — Prose style for artifacts and GitHub text

planner-agent and plan-reviewer invoke their own required skills; git-agent invokes /speq-git-operations.

Workflow

0. Load Project Hook (orchestrator)

Check for .speq/plan-pr-hook.md in the repo root.

• Present: read it. Announce "Loaded project hook: .speq/plan-pr-hook.md". Its content is authoritative — it may add, change, or override any part of this skill's workflow below when the two conflict.
• Absent: continue normally, no mention.

1. Resolve Target

Resolve what to work on and land on the right branch:

Delegate to git-agent — operation: checkout
  target: <the raw argument the caller passed>

If checkout reports not-found, the argument is free-text feature intent for a brand-new plan. Derive <plan-name> the same way speq-plan does (verb table below) and create its branch:

Delegate to git-agent — operation: create-branch
  branch: feat/<plan-name>

Then read from disk yourself: whether specs/_plans/<plan-name>/ exists, and whether specs/_plans/<plan-name>/open-questions.md exists and is non-empty. Take the PR draft/ready state from the checkout return.

Verb	When
add	New feature
change	Modify existing
remove	Deprecate/delete
refactor	Restructure, same behavior
fix	Bug or spec mismatch

Pattern: <verb>-<feature-scope>[-<qualifier>]

PR-title derivation (shared with speq-implement-pr)

Derive the PR title deterministically from <plan-name> as a conventional-commit feature title <type>(<scope>): <slug>:

• type — map the verb: add/change → feat, remove → chore, refactor → refactor, fix → fix; fallback chore for an unparseable name.
• scope — the <feature-scope> segment (the token after the verb).
• slug — the humanized <plan-name> (hyphens → spaces).

Example: add-search-candle ⇒ feat(search): add search candle. With no scope segment, emit <type>: <slug>.

2. Fetch Answers — resume only

If step 1 found an unresolved open-questions.md, pull the human's replies:

Delegate to git-agent — operation: read-comments
  since: <timestamp of your last "flag open questions" commit>

Forward the returned Q&A to planner-agent in step 4 — it stands in for the live interview speq-plan would otherwise run.

3. Discovery (orchestrator)

Gather just enough context to brief planner-agent, the same lightweight calls speq-plan makes:

speq domain list
speq feature list
speq search query "<relevant terms>"

4. Delegate to planner-agent

Same shape speq-plan uses, with headless framing added:

Delegate to planner-agent — Plan <plan-name> (headless)

## Plan Name
<plan-name>

## Interview Mode
headless

## User Intent
<feature intent text, or "see resume Q&A below">

## Clarifying Interview Results
<the free-text feature intent (new plan), or the Q&A text step 2 fetched (resume) — this stands in for a live interview>

## Existing Context
<output of relevant `speq search` / `speq feature get` calls>

## External Research
none — agent to research as needed

## Project Hook
<if active: note ".speq/plan-pr-hook.md — read it and apply it" — otherwise omit this section>

## Your Task
Produce spec deltas and plan.md per your normal workflow. You are in headless mode: follow your "Headless / Non-Interactive Mode" section — assume and document conventional decisions, escalate only irreducible ones via the OPEN QUESTIONS: sentinel. Tag deep-reasoning tasks with [expert].

Return the list of files created and the validation result, or an OPEN QUESTIONS: block if you had to stop.

5. Adversarial Plan Review

Skip this step if step 4 returned OPEN QUESTIONS: — resolve that first (step 6 handles it). Otherwise, before landing the plan, spawn plan-reviewer to challenge it. Bounded to 2 rounds total, same shape speq-plan uses:

Delegate to plan-reviewer — Review <plan-name> (round 1)

## Plan Name
<plan-name>

## User Intent
<the feature intent text / resume Q&A used in step 4>

## Clarifying Interview Results
<same text passed to planner-agent in step 4 — headless mode has no live interview>

## Plan Artifacts
plan.md, decision-log.md, and every specs/_plans/<plan-name>/**/spec.md delta

## Project Hook
<if active: note ".speq/plan-pr-hook.md — read it and apply it" — otherwise omit this section>

If BLOCKER findings exist: respawn planner-agent with only the BLOCKER list (revise, log each as a [plan-review]-prefixed ## Review Findings entry in decision-log.md, re-validate), then respawn plan-reviewer for round 2 with the round-1 BLOCKER list to confirm resolution. Do not loop a third time.

If BLOCKERs remain after round 2: treat this exactly like an OPEN QUESTIONS: return from planner-agent — fold the remaining blockers into step 6's "OPEN QUESTIONS: returned" branch as the questions list.

ADVISORY findings: carry into step 7's PR body/report; never block or persist.

6. Branch on the Result

Clean return (no OPEN QUESTIONS: sentinel, and no unresolved BLOCKERs from step 5) — ship the plan as a draft:

1. Confirm speq plan validate <plan-name> passes.
2. Commit the plan and open the draft PR:

   Delegate to git-agent — operation: commit
     paths: the plan directory
     message: spec(plan): <plan-name>
   
   Delegate to git-agent — operation: push
   
   Delegate to git-agent — operation: create-pr
     draft: true
     title: <the derived <type>(<scope>): <slug>>
     body: summarize the plan's Features table and task count, ending
           "Draft pending implementation — run /speq:implement-pr <plan-name> to implement and mark ready"
   

3. If this is a resume of a previously-blocked plan, clear the block yourself: delete specs/_plans/<plan-name>/open-questions.md and the > **Status:** blocked … banner line from plan.md, then:

   Delegate to git-agent — operation: commit
     paths: the plan directory
     message: spec(plan): resolve open questions for <plan-name>
   
   Delegate to git-agent — operation: push
   

   The PR stays a draft — speq-implement-pr is the only skill that marks it ready.

OPEN QUESTIONS: returned (from step 4, or unresolved BLOCKERs from step 5) — persist the partial plan and ask the human async. Author the status files yourself, then delegate only git operations:

1. Write specs/_plans/<plan-name>/open-questions.md:

   # Open Questions: <plan-name>
   
   speq-plan-pr could not complete this plan without human input. What's done so far is committed on this branch. Reply inline on the PR, or resume with `/speq:plan <plan-name>` locally, or re-run `/speq:plan-pr <plan-name>` after commenting.
   
   - [ ] <question 1, or the round-2 BLOCKER text from step 5>
   - [ ] <question 2>
   

2. Insert > **Status:** blocked — see open-questions.md as the first line under plan.md's H1 (skip if already present).
3. Compose the questions checklist as the PR comment body.

Then:

Delegate to git-agent — operation: commit
  paths: the plan directory
  message: spec(plan): flag open questions for <plan-name>

Delegate to git-agent — operation: push

Delegate to git-agent — operation: create-pr
  draft: true
  title: <the derived <type>(<scope>): <slug>>
  body: <blocked-plan summary>

Delegate to git-agent — operation: comment-pr
  body: <the questions checklist from step 3>

7. Report (orchestrator)

Tell the caller whether the plan is ready or blocked, and the PR link either way. Mention any ADVISORY findings from step 5.

Spec Hierarchy (reference)

specs/
├── <domain>/<feature>/spec.md            # Permanent
├── _plans/<plan-name>/                   # Active
│   └── open-questions.md                 # Present only while blocked
└── _recorded/<plan-name>/                # Archived

Work Split (reference)

Step	Performed by	Why
Target resolution, discovery, status files, coordination	This skill (pins Sonnet)	Tool-call heavy, reasoning light
Spec delta authoring, ADR, task decomposition, assume-vs-escalate calls	planner-agent sub-agent	Reasoning-heavy; defects here compound through implementation
Adversarial review, revision loop	plan-reviewer sub-agent	Catches intent drift, infeasibility, and ambiguity before implementation, not after
Branch, commit, push, PR create/comment	git-agent sub-agent	Generic git/GitHub operations; keeps git/gh detail out of the orchestrator