---
name: pstack-issue
preamble-tier: 3
version: 0.3.0
description: |
  File a single GitHub issue with shape selector mapped to existing issue
  templates. Uses GitHub MCP — runs from Claude Desktop or Claude Code
  without `gh` CLI or a local repo clone. Skips full /pstack-plan ceremony.
  Shapes: story, task, bug, feature, epic, docs. Use when asked to "file an
  issue", "/pstack-issue", "open a bug", "open a task".
triggers:
  - /pstack-issue
  - file an issue
  - open a bug
  - open a task
  - quick story
allowed-tools:
  - Read
  - Write
  - Skill
---

# pstack-issue

Single-issue creation via GitHub MCP. No spec, no decomposition.

**Requires GitHub MCP server** (installed in Claude Desktop / Claude Code).
If `mcp__github__*` tools are unavailable, install it first:
https://github.com/github/github-mcp-server

## Shape selector

| Flag | GitHub template | Use case |
|---|---|---|
| `--type=story` | 📖 user_story.yml | User-visible behavior change |
| `--type=task` | 🛠️ technical_task.yml | Tech debt, internal tooling, sub-task |
| `--type=bug` | 🐞 bug_report.yml | Defect (not yet in production) |
| `--type=feature` | ✨ feature_request.yml | Small feature; ≤500 lines, no full ceremony |
| `--type=epic` | 🚀 epic.yml | Rare — usually `/pstack-plan` creates epics |
| `--type=docs` | 🛠️ technical_task.yml + lighter exec | Doc-only changes |

If no `--type` provided, ask.

## Steps

### 1. Pick template body

Read the matching `${CLAUDE_SKILL_DIR}/../../templates/story-<type>.md` from
the local pstack install. Templates ship with pstack and are always available
locally — they aren't fetched via MCP.

### 2. Fill in

Brainstorm with the user to fill in placeholders. Required:
- Title (per type — for story: `As a [user], I want to [action]`)
- Description / repro / scope as the template demands
- Acceptance criteria
- Files likely to touch
- Reviewer focus
- Estimated diff size

### 3. 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 the target repo
  (format: `owner/repo`). Cache the answer for the session so subsequent
  /pstack-* commands don't re-ask.

### 4. Apply project conventions

Read project's `CLAUDE.md` (if accessible locally) or ask the user for
conventions. Honor `github_issues_*.md` saved memory entries when working
on the matching repo (e.g., periant):
- Project: as configured (e.g., "Periant Platform")
- Issue type: explicit (User Story / Task / Bug / Feature / Epic)
- Labels: only `MVP` if relevant
- No assignee, no milestone

### 5. File the issue via MCP

Call **`mcp__github__issue_write`** with:
- operation: `create`
- owner / repo: from Step 3
- title: from Step 2
- body: filled body content from Step 2
- labels: e.g., `["MVP"]` if applicable; otherwise omit
- issue type: per the shape selector (User Story / Task / Bug / Feature / Epic)

If the repo uses GitHub Projects (e.g., periant's "Periant Platform"),
add the issue to the project via the appropriate MCP project tool if
available; otherwise note that the user should add it manually via the web UI.

The tool returns the created issue's number and URL.

### 6. Print the URL

Report back the issue URL from the MCP response.

## Doc-only mode

If `--type=docs`, mark the issue body with `lighter execution: doc-only`.
`/pstack-execute` picks this up and skips TDD + `/codex` review, running
link/spell check instead.

## Do not

- Do not call `gh` CLI — the skill uses GitHub MCP for portability across
  Claude Desktop / Claude Code.
- Do not invent labels.
- Do not auto-assign.