--- name: pstack-vision preamble-tier: 3 version: 0.3.0 description: | Strategic brainstorming via `superpowers:brainstorming`, persisted as a research doc under `docs/research/` and posted to the project's pinned Vision GitHub Issue via GitHub MCP. Self-contained — no external CLIs, no `~/.gstack/` indirection. Use when asked to "brainstorm the vision", "what's our vision", "update project vision", or when starting to define what a project is about. triggers: - /pstack-vision - update project vision - brainstorm project vision - what's our vision allowed-tools: - Bash - Read - Write - Edit - Skill --- # pstack-vision ## Preamble — pstack upgrade check Before doing the skill's actual work, run: ```bash "${CLAUDE_SKILL_DIR}/../../scripts/pstack-update-check.sh" 2>/dev/null || true ``` Silent unless a pstack upgrade is available. When it fires it prints one line ("ℹ pstack vX is available...") that the user can act on at their convenience — it does not block the rest of this skill. Strategic brainstorming with the result posted to a project-pinned Vision GitHub Issue. The Vision Issue is editable by anyone with repo write access via the GitHub web UI — no PR ceremony. The raw brainstorm is also persisted locally as `docs/research/-vision-.md` so the team has a version-controlled record alongside the team-shared Issue. ## Dependencies - **`superpowers` plugin** — provides the `brainstorming` skill that drives the structured Q&A. - **GitHub MCP server** — for all GitHub operations. No `gh` CLI required. Both ship as plugin dependencies declared in `plugins/pstack/.claude-plugin/plugin.json`. ## Args ``` /pstack-vision # default: brainstorm fresh, write doc, import /pstack-vision --topic "" # seed the topic slug (defaults to "core") /pstack-vision --import # skip brainstorm; import an existing doc ``` ## Pre-conditions Before running this skill, verify: 1. Current directory is a project root (`.pstack-version` exists from `pstack-init`). 2. GitHub MCP is loaded — call `mcp__github__get_me` to verify auth. 3. The project has a GitHub remote: `git remote get-url origin`. 4. **The active project has `structure.use_vision: true` in `~/.pstack/config.json`.** Vision capture is opt-in per the right-sizing principle — small / solo projects (like pstack itself) don't need a captured Vision and should skip this skill entirely. If `use_vision: false` or the key is absent, surface: > "This project has `use_vision: false` (or unset) in `~/.pstack/config.json`. Capturing Vision adds value when multiple stakeholders or async contributors need a shared anchor; small focused projects usually don't. To opt in, re-run `/pstack-add-project` and answer yes to the Vision question. Or pass `--force` to proceed anyway." If any check fails, surface a clear error and stop. ## Workflow ### 1. Capture context ```bash test -f .pstack-version || { echo "Not a pstack project. Run pstack-init first."; exit 1; } PROJECT_NAME=$(node -e "console.log(require('./package.json').name||'')" 2>/dev/null || basename "$PWD") ORIGIN_URL=$(git remote get-url origin) # Parse owner/repo from URL — https://github.com/owner/repo(.git) or git@github.com:owner/repo(.git) DATE=$(date +%Y-%m-%d) TOPIC="${TOPIC:-core}" # from --topic arg SLUG=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9-' '-' | tr -s '-' | sed 's/^-//;s/-$//') RESEARCH_PATH="docs/research/${DATE}-vision-${SLUG}.md" ``` ### 2. Brainstorm via superpowers (skipped with `--import`) Invoke `superpowers:brainstorming` to drive the conversation. The brainstorm targets the Vision template's six anchors: - Who is this for? - What problem are we solving? - Why now? - What's the narrowest wedge? - Where could this be in three years? - What's explicitly out of scope? ``` Use the Skill tool to invoke `superpowers:brainstorming` with a focus on those six anchors. Let it run to completion; do not summarize or short-circuit it. ``` When the brainstorm returns, hold its structured output in conversation context for Steps 3–4. ### 3. Write the research doc Render the brainstorm result into a markdown doc: ```bash mkdir -p docs/research ``` Doc structure: ```markdown --- date: topic: type: vision-brainstorm project: --- # Vision brainstorm — () ## Who … ## Problem … ## Why now … ## Narrowest wedge … ## Future-fit (3 years) … ## Out of scope … ## Raw brainstorm
Full Q&A (click to expand)
``` Write to `$RESEARCH_PATH`. Do not commit — that's the user's call when they review the PR. Print the path so the user can open it. ### 4. Distill (or use the doc as-is) Ask the user: > "Research doc written to `$RESEARCH_PATH`. > > The Vision Issue body should be tighter than the raw brainstorm. Two options: > 1. Distill into the Vision template structure (recommended) > 2. Use the doc's six-anchor sections as-is" If 1: read `${CLAUDE_SKILL_DIR}/../../templates/vision.md`, fill in placeholders from the six anchors. Show the distilled version to the user; ask for approval/edits. If 2: extract the six top-level sections from the research doc as the Vision body (without the `## Raw brainstorm` block — that stays local). Replace template placeholders: - `{{PROJECT_NAME}}` → `$PROJECT_NAME` - `{{DATE}}` → `$DATE` Hold the final body content as a string for the next step. ### 5. Find or create the Vision Issue via MCP Search for an existing Vision Issue using **`mcp__github__search_issues`**: - query: `repo:/ label:vision is:open` - limit: 5 Identify any open issue labeled `vision`. Fall back to title-match (`Vision: $PROJECT_NAME`) for legacy issues without the label. **If EXISTING:** ask the user before overwriting: > "A Vision Issue already exists at #N. Three options: > 1. Replace its body with the new content > 2. Append new content as a comment (keeps existing body) > 3. Skip — show me the new content but don't update GitHub" - If 1: call **`mcp__github__issue_write`** with `operation=update`, the existing issue number, and `body=new content`. - If 2: call **`mcp__github__add_issue_comment`** with the new content. - If 3: print body content; stop. **If no existing Vision Issue:** create one. Note on labels: GitHub MCP doesn't expose a `create_label` operation. The `vision` label must exist on the repo before the first run. If creation fails with "label not found": > "Create a 'vision' label in the repo settings (color #5319E7 > recommended), then re-run. With `gh` CLI: > `gh label create vision --color '5319E7'`." Call **`mcp__github__issue_write`** with: - operation: `create` - title: `Vision: $PROJECT_NAME` - body: the final body content - labels: `["vision"]` - **type:** omit. Vision is not Epic / Feature / User Story / Task / Bug — it's strategic context. The pin + the `vision` label + the title prefix `Vision:` identify it; no issue type is needed or appropriate. Save the returned issue number and URL. ### 6. Pin the Vision Issue GitHub MCP doesn't expose a `pin_issue` tool. Print instructions for the user: > "Vision Issue created at . To pin it: > > 1. Open the issue > 2. Click the three-dot menu (top right) → 'Pin issue' > > Up to 3 issues can be pinned per repo." ### 7. Append archive comment To preserve the raw brainstorm in a team-visible spot, call **`mcp__github__add_issue_comment`** with: - issue number: from Step 5 - body content (template): ```markdown ## Office-hours session — Local research doc: `docs/research/-vision-.md`
Raw brainstorm output (click to expand)
``` Reviewers get the full thinking without bloating the issue body. ### 8. Print the result ``` ✓ Vision imported. Research doc: Issue: https://github.com///issues/N Label: vision Pinned: [user action required — see Step 6] Next: when /pstack-plan is invoked, it will discover this Vision Issue automatically (by label) and load it as strategic context. ``` ## How other skills discover the Vision Other pstack skills (`/pstack-plan`, etc.) find the Vision Issue via **`mcp__github__search_issues`** with query `repo:/ label:vision is:open`, returning the first open issue. The `vision` label is the discovery mechanism — no `CLAUDE.md` URL writeback needed. Works equally in Claude Code and Claude Desktop. ## When Vision already exists (re-run scenario) If the user runs `/pstack-vision` again later: - Step 5's "existing issue found" branch handles it. - Recommended: choose option 2 (append as comment) for incremental refinements; option 1 (replace) only when doing a full strategic reset. - The new research doc lands at a date-stamped path, so historical brainstorms accumulate under `docs/research/` without overwriting. ## Failure modes and recovery | Failure | Response | |---|---| | Not a pstack project (no `.pstack-version`) | Halt, suggest `pstack-init` | | `superpowers` plugin not loaded | Halt, point at the plugin marketplace | | GitHub MCP not loaded | Halt, link install instructions | | `mcp__github__get_me` fails | Halt, suggest re-auth via host config | | No GitHub remote / ambiguous repo | Halt, ask user for owner/repo | | Brainstorm cancelled by user | Halt cleanly; the partial research doc (if any) stays on disk for inspection | | `--import ` but file missing | Halt, suggest running without flag to invoke brainstorm | | Issue creation fails (`vision` label missing) | Surface the create-label instruction (above) | | Issue creation fails (permissions) | Halt, print body content so user can paste manually via web UI | ## Do not - Do not call `gh` CLI — use GitHub MCP. - Do not auto-commit the research doc. The user reviews and commits as part of their normal workflow. - Do not overwrite an existing Vision body without explicit user confirmation. - Do not write the Vision URL into the project's `CLAUDE.md` — the `vision` label is the discovery mechanism. ## See also - `templates/vision.md` — the body template applied to the Vision Issue. - `docs/research/` — local archive of brainstorm transcripts. Per-date, per-topic; never overwritten. - `superpowers:brainstorming` — the underlying conversational pattern.