ob-userstory

name	ob-userstory
description	Parse GitHub Issue URL and create OpenSpec change. Use when user provides a GitHub Issue URL.
license	MIT
compatibility	Requires openspec CLI and gh CLI.
metadata	{"author":"copilots","version":"1.1"}

ALL GitHub data MUST come from gh CLI. NEVER use webfetch, HTTP requests, or browser MCP tools to fetch GitHub URLs, even if gh CLI fails. If gh is unavailable, report it as a blocker.

---

GitHub CLI Setup (One-Time)

gh auth login
# Follow prompts, authenticate via browser or token

Verify:

gh auth status

---

Steps

1. Extract owner, repo, and issue number from URL

   • https://github.com/{owner}/{repo}/issues/42 → owner: {owner}, repo: {repo}, number: 42

2. Fetch Issue, always pass --repo explicitly, never rely on git context:

   gh issue view 42 --repo {owner}/{repo} --json number,title,body,labels,milestone,state
   

   If this returns an auth error or 404, report as a blocker, do NOT fall back to webfetch or web search.

3. Extract Key Fields from JSON response:

   • number → Issue number
   • title → Title
   • body → Description / acceptance criteria
   • labels → Labels
   • milestone → Milestone / sprint equivalent
   • state → State (open/closed)

4. Create OpenSpec Change

   openspec new change "gh-{number}-{slug}"
   

---

Full GitHub CLI Reference

Use these for ALL GitHub operations, browser MCP and webfetch are FORBIDDEN. Always pass --repo {owner}/{repo}, never rely on git context.

Issues

# Read issue
gh issue view <number> --repo {owner}/{repo}

# List open issues
gh issue list --repo {owner}/{repo} --state open --limit 10

# Update issue
gh issue edit <number> --repo {owner}/{repo} --add-label "in-progress"

---

Screenshot / Image Strategy

Never embed images as attachments. Save to openspec change folder and reference via GitHub blob URL pinned to commit SHA.

Save location

openspec/changes/{change-name}/images/{screenshot}.png

Blob URL format (preferred: keep ?raw=true when embedding in markdown)

https://github.com/{owner}/{repo}/blob/{sha}/openspec/changes/{change}/images/{file}.png?raw=true

---

URL Formats Reference

# Issue
https://github.com/{owner}/{repo}/issues/{number}

# PR
https://github.com/{owner}/{repo}/pull/{number}

# Blob file
https://github.com/{owner}/{repo}/blob/{sha}/{path}

---

Output Format

## Issue Parsed

**Issue:** #{number}
**Title:** {title}
**State:** {state}
**Milestone:** {milestone}

**Change Created:** gh-{number}-{slug}

After outputting the above, the lead MUST run /plan-propose to generate the proposal, specs, and tasks. After /plan-propose completes, STOP and ask the user: "Ready to implement? (yes/no)", do NOT proceed to /plan-apply until confirmed.

---

Guardrails

• ✅ Parse GitHub Issue URL and create OpenSpec change
• ✅ Use gh CLI for all GitHub operations
• ✅ Always run /plan-propose after parsing, never skip to implementation
• ✅ Always stop and confirm with user after propose, before running /plan-apply
• ❌ webfetch or HTTP requests to GitHub URLs, FORBIDDEN, use gh CLI only
• ❌ Browser MCP tools for GitHub operations, FORBIDDEN
• ❌ Jump to implementation without user confirmation, FORBIDDEN