speq-plan-pr
Headless, non-interactive version of /speq-plan for CI or agent-driven runs. Plans a feature without a live interview, commits the result to a feat/plan-name branch, and opens a draft 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.
marconae · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add marconae/speq-skill --skill speq-plan-pr技能说明
name: speq-plan-pr description: "Headless, non-interactive version of /speq-plan for CI or agent-driven runs. Plans a feature without a live interview, commits the result to a feat/plan-name branch, and opens a draft 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:
- Turn a feature intent, or an existing plan branch/PR, into a validated plan authored entirely by
planner-agentin headless mode. - Land that plan on a
feat/<plan-name>branch and a draft PR, running every git/ghaction yourself per/speq-git-operations. - Hand any irreducible decision to a human as a PR comment and stop there.
Rules:
- Delegate all planning judgment to
planner-agent. Run every git/GitHub action yourself, per/speq-git-operations. Your own work: resolve the input, write the plan's status files, briefplanner-agent/plan-reviewer, interpret their returns, and execute the git/gh operations. - 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.create-pr(per/speq-git-operations) reuses an existing PR.
Required Skills (for the orchestrator)
Invoke before starting:
/speq-cli: spec discovery and search/speq-writing-guardrails: prose style for artifacts and GitHub text/speq-git-operations: the git/gh operation-to-command mapping, safety rules, and return formats — you run every operation directly
planner-agent and plan-reviewer invoke their own required skills.
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 can add to, change, or override any part of this workflow. If the hook conflicts with this workflow, the hook wins.
- Absent: continue without mention.
1. Resolve Target
Resolve what to work on and land on the right branch:
Run — operation: checkout (per /speq-git-operations)
target: <the raw argument the caller passed>
If checkout reports not-found, the argument is free-text feature intent for a new plan. Derive <plan-name> per the verb table and create its branch:
Run — operation: create-branch (per /speq-git-operations)
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 from <plan-name> as a conventional-commit title <type>(<scope>): <slug>:
- type: map the verb:
add/change→feat,remove→chore,refactor→refactor,fix→fix; fallbackchorefor 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:
Run — operation: read-comments (per /speq-git-operations)
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 run.
3. Discovery (orchestrator)
Gather 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
<the exact `speq domain list` / `speq feature list` / `speq search query "..."` calls you ran, each followed by its output — name the query, not just the result>
## 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:; step 6 handles that. Otherwise spawn plan-reviewer to challenge the plan. Maximum 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>/*
阅读完整来源 ↗