--- name: pstack-plan preamble-tier: 3 version: 0.3.0 description: | Full feature/refactor ceremony: brainstorm → spec → eng-review → decompose → file Epic + sub-issues. Drafty spec lives in the Epic issue body (web-UI editable); it's frozen to docs/specs/ by /pstack-execute on first story. Can promote an existing Feature Request into an Epic. Uses GitHub MCP — runs from Claude Desktop or Claude Code without `gh` CLI. Use when asked to "spec a feature", "plan a feature", "/pstack-plan", "promote this feature request", or "start a new feature". triggers: - spec a feature - new feature - /pstack-plan - plan a feature - refactor spec - promote feature request allowed-tools: - Bash - Read - Write - Edit - Glob - Grep - Skill --- # pstack-plan End-to-end feature spec workflow. Outputs a domain doc (if new) and a GitHub Epic whose body **is** the drafty spec. Sub-stories are filed as linked sub-issues. The spec remains live and editable in the Epic body until `/pstack-execute` freezes it into `docs/specs/.md` on the first story. **Requires GitHub MCP server** for all GitHub operations. `Bash` stays in allowed-tools for local file operations (templates, tempfiles, GitNexus helper) and optional gstack invocations. ## Skills orchestrated | Skill | When | |---|---| | `superpowers:brainstorming` | Step 2 — frame the feature with the user | | gstack `/plan-eng-review` | Step 4 — architecture / data-flow / edge-case review of the composed spec | | gstack `/plan-ceo-review` | Step 5.5 — optional, for high-ambition / broad-user-impact specs | | gstack `/plan-design-review` | Step 5.5 — optional, audit-only for UI-heavy specs | | gstack `/plan-devex-review` | Step 5.5 — optional, for developer-facing surfaces (APIs, CLIs, SDKs) | | gstack `/autoplan` | Step 5.5 — one-shot "run all applicable reviews" pipeline | ## Args - `/pstack-plan` — greenfield brainstorm - `/pstack-plan ` — promote an existing Feature Request (or any brain-dump issue) into a full Epic. Loads the issue body as starting context, then closes the original with a link to the new Epic when filing completes. ## Modes - **feature** (default) — new product capability - **refactor** — full ceremony for risky internal changes; requires ADR + no-behavior-change criterion + preparatory-refactor decomposition Ask the user which mode at the start. ## Steps ### 0. Determine repo target - **Claude Code with a local repo:** parse `owner/repo` from `git remote get-url origin`. - **Claude Desktop or no local repo:** ask the user for `owner/repo`. Cache for the session. ### 0.5. Load context If invoked with ``, fetch the source issue via MCP: Call **`mcp__github__issue_read`** with `owner`, `repo`, `issue_number=`. Save the returned title, body, and URL as `SOURCE_ISSUE_TITLE`, `SOURCE_ISSUE_BODY`, `SOURCE_ISSUE_URL`. The Feature Request author (often a non-technical user) captured the "what" and "why" — the brainstorm in Step 2 fills in the "how" and decomposition. Find the project's Vision Issue for strategic context. Call **`mcp__github__search_issues`** with query `repo:/ label:vision is:open` and pick the first result. If found, call **`mcp__github__issue_read`** to fetch its body as `VISION_BODY`. Surface to the user: "Loaded Vision context from issue #N. Strategic anchors: [Narrowest wedge / Future-fit / Out of scope]." Use throughout the brainstorm to keep scope aligned. ### 1. Domain check Ask: "Is this a new domain or extension of an existing one?" - **Existing:** locate the domain doc. - With a local repo: `ls docs/domains/`, read the relevant file (including `paths:` frontmatter for code locations and `depends_on:` / `consumers:`). - Without a local repo: call **`mcp__github__get_file_contents`** with `path=docs/domains/.md` to read it. - **New:** call `pstack-domain` skill (or inline: copy `templates/domain.md`, fill in via brainstorm). Note: `pstack-domain` is currently filesystem-based and requires a local repo. In Desktop, draft the content in conversation and ask the user to commit it via the engineer later. ### 2. Brainstorm Use `superpowers:brainstorming` skill to clarify scope. If `` was provided, seed the brainstorm with the source issue body and any Vision context loaded in Step 0.5. Capture the result as the basis for the spec. ### 3. Compose spec content Render `${CLAUDE_SKILL_DIR}/../../templates/spec.md` filling in: - Problem, goals, non-goals, acceptance criteria, approach - For `mode=refactor`: no-behavior-change criterion, regression test plan, preparatory-refactor decomposition, required ADR placeholder **Do not write the spec to `docs/specs/.md`.** The spec lives in the Epic issue body (Step 6) and remains editable via GitHub web UI until `/pstack-execute` freezes it on first story. Hold the composed spec content in conversation context (or a tempfile if running locally and the spec is long enough to warrant it): ```bash SPEC_BODY=$(mktemp -t pstack-spec.XXXXXX.md) # write composed content to $SPEC_BODY ``` ### 4. Engineering review Run gstack `/plan-eng-review` against the composed spec content. Iterate based on findings before filing. If running in Claude Desktop (no gstack), skip this step and note in the Epic body: `> Eng review: not run (Desktop session); recommend running before implementation begins.` ### 5. Decompose Target 2–3 stories per feature. Each story: - Acceptance criteria - Files likely to touch - Reviewer focus - Estimated diff size (~300–500 lines per story) Apply the right decomposition pattern for the feature shape: | Shape | Pattern | |---|---| | Standard feature | types → migration → API → UI → wiring (collapse to 2–3 stories) | | Cross-cutting UI change | refactor to abstraction → change abstraction | | Refactor | preparatory-refactor → behavior change | | Bug fix | failing test → fix | ### 5.5. Optional: review escalations Ask the user: > "Decomposition complete. Want any optional reviews before filing issues? > > 1. CEO review (`gstack /plan-ceo-review`) — strategic scope critique > 2. Design review (`gstack /plan-design-review`) — for UI-heavy features (audit-only; won't impose new visual patterns) > 3. DevEx review (`gstack /plan-devex-review`) — for developer-facing specs (APIs, CLIs, SDKs, libraries, platforms, docs) > 4. All applicable reviews via `gstack /autoplan` — runs CEO + eng + design + devex sequentially with auto-decisions > 5. Multiple from 1–3 (specify which) > 6. None — proceed to file issues" - If 1: invoke `/plan-ceo-review` against the spec; iterate before continuing. - If 2: invoke `/plan-design-review`; iterate. (Audit-only — never invoke `/design-shotgun`, `/design-consultation`, or `/design-html`; those impose patterns rather than observing yours.) - If 3: invoke `/plan-devex-review`; iterate. Use when the spec describes a public API surface, CLI, SDK, library, or developer-facing tool — these specs benefit from persona/competitive/magical-moment lens that generic reviews miss. - If 4: invoke `/autoplan` — one-shot pipeline that runs CEO + eng + design + devex reviews with auto-decisions, surfacing only taste calls. Recommended for high-ambition specs where running all reviews individually is heavy. - If 5: invoke the specified subset. - If 6: skip. Default for routine specs: 6 (none). Default to **ask explicitly** for: - High-ambition specs (mode=feature with broad user impact) — recommend 1 or 4 - UI-heavy features — recommend 2 or 4 - Developer-facing surfaces (APIs/CLIs/SDKs) — recommend 3 or 4 If running in Claude Desktop (no gstack), these reviews aren't available. Print: "Skipping optional reviews — gstack not available. Recommended for high-ambition / UI-heavy specs; run them in Claude Code before implementation." ### 6. File Epic with spec as body, then sub-stories The composed spec becomes the Epic's issue body. This keeps the spec live and team-editable until freeze time. **Create the Epic** — call **`mcp__github__issue_write`** with: - operation: `create` - owner / repo: from Step 0 - title: `` (e.g., the feature name) - body: the composed spec content - labels: `["MVP"]` if relevant per project conventions; otherwise omit - issue_type: `Epic` Save the returned issue number as `EPIC_NUM` and URL as `EPIC_URL`. **For each sub-story** — call **`mcp__github__issue_write`** with: - operation: `create` - owner / repo: same - title: per shape (User Story: `As a [user], I want to [action]` — no "So that" tail) - body: rendered from `${CLAUDE_SKILL_DIR}/../../templates/story-.md`, **with `Parent Epic: #` appended** so `/pstack-execute` can locate the spec body to freeze - issue_type: `User Story` / `Task` / `Bug` (per shape) - labels: only `MVP` if relevant Save each sub-story's issue number. **Link sub-issues to the Epic** — call **`mcp__github__sub_issue_write`** for each child, setting the Epic as parent. **If `` was provided (promote-from-feature-request mode),** close the original source issue with a linking comment: - Call **`mcp__github__add_issue_comment`** on `SOURCE_ISSUE_NUM` with body: `Promoted to Epic # with a full spec and sub-stories. Closing this issue; track progress on the Epic.` - Call **`mcp__github__issue_write`** with operation=`update`, issue_number=`SOURCE_ISSUE_NUM`, state=`closed`, state_reason=`completed`. ### 7. Update domain doc Append the new feature to the domain doc's "Planned" section. Link the Epic Issue URL (not a `docs/specs/.md` path — that file doesn't exist yet; it'll be created by `/pstack-execute` on first story). ```markdown ## Planned - [Epic #N: ](https://github.com///issues/N) — drafty spec lives in the Epic body ``` If running with a local repo: edit the file directly; the developer commits alongside the next PR. If running in Desktop without a local repo: skip this step and note in Step 8's summary that the domain doc update needs to be done by a developer later. (Future enhancement: commit via `mcp__github__create_or_update_file` on a feature branch + PR.) ### 8. Summarize Print: - Epic issue URL (where the drafty spec body lives, web-UI editable) - Sub-issue URLs - Domain doc update path (if changed) - Source issue URL closed as promoted (if `` was provided) - Note: "When the first story for this Epic is executed via `/pstack-execute`, the Epic body will be frozen to `docs/specs/.md` as part of that story's PR." ## GitNexus integration If GitNexus is running locally (Claude Code only), use it during decomposition (Step 5) to surface cross-module impact per story: ```bash GITNEXUS=$(${CLAUDE_SKILL_DIR}/../../scripts/gitnexus-check.sh) || GITNEXUS="" ``` If `$GITNEXUS` is set: - For each story's "Files likely to touch", run `${CLAUDE_SKILL_DIR}/../../scripts/gitnexus-query.sh affected ` and include the deduplicated result in the story body as an "Affected dependencies (GitNexus)" section. - If two stories share a high overlap of affected modules, reconsider the boundary — that's a signal the decomposition cuts are wrong. - If a query returns exit 2 (unsupported), fall back to `grep` and note `GitNexus query unsupported` in the body. If GitNexus is unreachable (or running in Desktop), skip this and note in the Epic body: `> Cross-module impact: GitNexus unavailable; verify with grep before implementation.` ## Do not - Do not call `gh` CLI — use GitHub MCP. - Do not start implementation. This skill ends at filed issues. - Do not write `docs/specs/.md` — that's `/pstack-execute`'s responsibility at first-story freeze time. - Do not commit. The developer reviews and commits the domain doc update (if any) at PR time. The Epic body and sub-issues are the artifacts.