# 2661 Issue Stories Fd287dc9 > GitHub Issues as User Stories — Workflow and Templates - Skill: `tools-only/2661-issue-stories-fd287dc9` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add tools-only/2661-issue-stories-fd287dc9` - Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/2661-issue-stories-fd287dc9/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: tools-only (https://skillmd.com/u/tools-only) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/tools-only/2661-issue-stories-fd287dc9 --- # GitHub Issues as User Stories — Workflow and Templates ## Issue as Story Model Each issue represents one backlog item and follows a story format with: - **Title**: short, imperative, `[type]: description` prefix (conventional commits style) - **Body**: user story + acceptance criteria + context - **Labels**: priority + type + status (see [labels.md](./labels.md)) - **Milestone**: release or theme grouping (see [milestones.md](./milestones.md)) - **Project**: board item for visualization (see [projects-v2.md](./projects-v2.md)) --- ## Issue Title Convention ```text feat: add priority labels to issue taxonomy fix: correct task_output variable reference in log_functions.sh refactor: replace hardcoded corporate URL in validate_glfm.py docs: document GitHub Projects V2 workflow chore: bump marketplace.json version after plugin removal ``` Mirrors Conventional Commits to link commits to issues naturally. --- ## Issue Body Template ```markdown ## Story As a **{role}**, I want **{goal}** so that **{benefit}**. ## Description {detailed description from backlog item} ## Acceptance Criteria - [ ] {criterion 1} - [ ] {criterion 2} - [ ] {criterion 3} ## Context - **Source**: {where this item came from} - **Priority**: {P0 / P1 / P2 / Idea} - **Added**: {YYYY-MM-DD} - **Research questions**: {any open questions, or "None"} ## Notes {optional: links to related issues, PRs, skills, or research} ``` --- ## Issue Lifecycle ```text Open → label: status:needs-grooming ↓ after grooming label: status:in-progress (when work starts) ↓ during work PR created → PR body: "Closes #N" ↓ PR merged Issue auto-closed by GitHub Milestone completion tracked ``` --- ## gh CLI — Quick Commands ```bash # Create issue gh issue create -R Jamie-BitFlight/claude_skills \ --title "fix: correct task_output variable in log_functions.sh" \ --body "..." \ --label "priority:p1" \ --label "type:bug" \ --label "status:needs-grooming" \ --milestone "v1.0 — Skills Foundation" # List open issues by priority gh issue list -R Jamie-BitFlight/claude_skills \ --label "priority:p1" --state open \ --json number,title,labels,milestone # View issue gh issue view 42 -R Jamie-BitFlight/claude_skills # Close with comment gh issue close 42 -R Jamie-BitFlight/claude_skills \ --comment "Implemented in PR #45. Checklist 12/12, acceptance criteria verified." # Edit labels gh issue edit 42 -R Jamie-BitFlight/claude_skills \ --add-label "status:in-progress" --remove-label "status:needs-grooming" ``` --- ## PyGithub — Scripted Operations (Python) Use `PyGithub` in Python scripts — never shell out to `gh`. ```python #!/usr/bin/env -S uv run --quiet --script # /// script # requires-python = ">=3.11" # dependencies = ["PyGithub>=2.1.1"] # /// from __future__ import annotations import os from github import Auth, Github gh = Github(auth=Auth.Token(os.environ["GITHUB_TOKEN"])) repo = gh.get_repo("Jamie-BitFlight/claude_skills") # Create issue with labels and milestone issue = repo.create_issue( title="fix: correct task_output variable in log_functions.sh", body="## Story\n\nAs a developer...", labels=[ repo.get_label("priority:p1"), repo.get_label("type:bug"), repo.get_label("status:needs-grooming"), ], milestone=repo.get_milestone(1), ) print(f"Created #{issue.number}: {issue.html_url}") # Close issue issue = repo.get_issue(42) issue.edit(state="closed") issue.create_comment("Implemented in PR #45.") ``` --- ## @octokit/rest — Claude Code Hooks (JavaScript) ```javascript const { Octokit } = require('@octokit/rest'); const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN }); // Create issue const { data: issue } = await octokit.rest.issues.create({ owner: 'Jamie-BitFlight', repo: 'claude_skills', title: 'fix: correct task_output variable', body: '## Story\n\nAs a developer...', labels: ['priority:p1', 'type:bug', 'status:needs-grooming'], milestone: 1, }); // Close issue await octokit.rest.issues.update({ owner: 'Jamie-BitFlight', repo: 'claude_skills', issue_number: 42, state: 'closed', }); ``` --- ## Automation Script ```bash uv run .claude/skills/gh/scripts/github_project_setup.py issue list --priority p1 uv run .claude/skills/gh/scripts/github_project_setup.py issue create \ --title "fix: correct task_output variable" \ --priority-label priority:p1 \ --type-label type:bug \ --milestone 1 ``` --- ## Backlog Item ↔ GitHub Issue Field Mapping | Per-item file field | GitHub Issue field | |---|----| | `name` frontmatter | Issue title | | `metadata.priority` frontmatter (P0/P1/P2) | `priority:*` label | | Item description body | Issue body | | `metadata.status` frontmatter | `status:*` label | | `metadata.plan` frontmatter | Issue body Notes section | | `metadata.issue` frontmatter | Issue number (written back by `work-backlog-item`) | | `last-completed` frontmatter | Issue closed date | When `work-backlog-item` creates a GitHub Issue, it writes the issue number back to the per-item file in `.claude/backlog/` as `metadata.issue: '#N'`. SOURCE: GitHub Issues documentation — (accessed 2026-02-21) SOURCE: GitHub CLI issue manual — (accessed 2026-02-21) SOURCE: PyGithub Issue API — (accessed 2026-02-21) SOURCE: Octokit.js REST — (accessed 2026-02-21)