From fa8247ee094851c519c59a6c312d5449bb9607c8 Mon Sep 17 00:00:00 2001 From: Nick Clarke Date: Tue, 25 Nov 2025 22:26:16 -0800 Subject: [PATCH 1/4] docs: add github-project-management skill design MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Design for a tactical workflow integration skill that manages GitHub issues and project items at natural development checkpoints (after brainstorming, plan creation, bug discovery, and branch completion). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- ...-11-25-github-project-management-design.md | 159 ++++++++++++++++++ 1 file changed, 159 insertions(+) create mode 100644 docs/plans/2025-11-25-github-project-management-design.md diff --git a/docs/plans/2025-11-25-github-project-management-design.md b/docs/plans/2025-11-25-github-project-management-design.md new file mode 100644 index 00000000..5951bcaf --- /dev/null +++ b/docs/plans/2025-11-25-github-project-management-design.md @@ -0,0 +1,159 @@ +# GitHub Project Management Skill Design + +## Overview + +A tactical workflow integration skill that manages GitHub issues and project items at natural development checkpoints. The agent proposes issue creation at key workflow moments, always with user confirmation. + +## Core Concepts + +### Repo Issues vs Project Drafts + +- **Repo issues** — For discrete, single-repo work (bugs, features tied to one codebase). Created with `gh issue create`, can be referenced in commits (`fixes #123`), linked to PRs automatically. + +- **Project draft items** — For cross-repo work, initiatives, spikes, and exploratory work with unclear repo scope. Created with `gh project item-create`, lives only in the project board. + +### Configuration + +Each repo specifies its GitHub Project in CLAUDE.md: + +```markdown +## GitHub Project + +github_project: owner/project-number +``` + +Examples: +```markdown +# User project +github_project: nclarke/1 + +# Org project +github_project: my-org/5 +``` + +- If `github_project` is missing and agent needs to create an issue, prompt: "No project configured. Create as repo-only issue, or specify a project?" +- For cross-repo items, always ask which project to use + +### Confirmation Required + +Agent always proposes issue details (title, body, labels) and waits for approval before creating anything. Issues are visible to the whole team — no auto-creation. + +## Integration Points + +### 1. After Brainstorming (Design Completion) + +**Trigger:** Brainstorming skill completes and writes design doc to `docs/plans/` + +**Action:** Propose creating a feature issue linking to the design + +**Agent behavior:** +1. After committing design doc, ask: "Create a tracking issue for this feature?" +2. If yes, propose issue details +3. Wait for approval/edits +4. Create issue and add to project + +**Issue template:** +``` +Title: [Feature] +Body: +## Summary +<1-2 sentence summary> + +## Design Document +See: docs/plans/YYYY-MM-DD--design.md + +## Acceptance Criteria + +``` + +### 2. After Writing Plans (Task Breakdown) + +**Trigger:** Writing-plans skill produces implementation plan + +**Action:** Propose creating issues for major tasks + +**Agent behavior:** +1. After plan is written, ask: "Create tracking issues for this plan?" +2. Present options: + - A) Single parent issue linking to plan + - B) Individual issues per major task + - C) Skip issue creation +3. If A or B, propose issue details +4. Wait for approval, create issues + +### 3. During Implementation (Bug Discovery) + +**Trigger:** Agent discovers a bug, technical debt, or issue unrelated to current task + +**When to trigger:** +- Bug found while working on something else +- Technical debt noticed but out of scope +- Edge case identified that needs future attention +- Dependency issue requiring separate investigation + +**Agent behavior:** +1. Note the discovery: "I found an issue: . This is separate from our current work." +2. Ask: "Create an issue to track this?" +3. If yes, propose issue with context +4. Continue with current task after issue created + +**Issue template:** +``` +Title: [Bug/Tech Debt] +Body: +## Context +Discovered while working on: +Location: + +## Description + + +## Potential Impact + +``` + +### 4. After Finishing Branch (Work Completion) + +**Trigger:** Finishing-a-development-branch skill runs + +**Action:** Update or close related issues + +**Agent behavior:** +1. Check commit messages for issue references (`#123`, `fixes #456`) +2. Check if current branch name contains issue number +3. If related issues found, ask: "Update these issues? [list issues]" +4. Options: close, add comment, or skip +5. If PR created, issues auto-close via GitHub when PR merges (no action needed) + +## Authentication + +The `gh` CLI requires the `project` scope: + +```bash +# Check current scopes +gh auth status + +# Add project scope if missing +gh auth refresh -s project +``` + +## Deliverables + +1. `skills/github-project-management/SKILL.md` — The workflow skill with integration point instructions +2. `skills/github-project-management/gh-reference.md` — CLI quick reference for `gh project` and `gh issue` commands + +## CLI Reference Structure + +The `gh-reference.md` file provides copy-pasteable commands: + +- Prerequisites (auth, scopes) +- Project Operations (list, view, get IDs) +- Issue Operations (create, view, edit, close, add to project) +- Project Item Operations (list, create draft, edit fields, archive) +- Common Workflows (create + add to project, update status) + +## What This Skill Is NOT + +- Strategic planning (sprint planning, backlog grooming, roadmap organization) +- Automated issue creation without confirmation +- A replacement for human judgment on prioritization From 4933a9fbb0fa3d6f872bedacc7bc59554f554fe7 Mon Sep 17 00:00:00 2001 From: Nick Clarke Date: Tue, 25 Nov 2025 22:35:19 -0800 Subject: [PATCH 2/4] feat: add github-project-management skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tactical workflow integration skill that manages GitHub issues at natural development checkpoints: - After brainstorming (create feature issue) - After writing plans (create task issues) - During implementation (track discovered bugs/debt) - After finishing branches (update/close issues) Includes gh-reference.md with CLI command quick reference. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- skills/github-project-management/SKILL.md | 122 +++++++++++++++ .../github-project-management/gh-reference.md | 146 ++++++++++++++++++ 2 files changed, 268 insertions(+) create mode 100644 skills/github-project-management/SKILL.md create mode 100644 skills/github-project-management/gh-reference.md diff --git a/skills/github-project-management/SKILL.md b/skills/github-project-management/SKILL.md new file mode 100644 index 00000000..97d91432 --- /dev/null +++ b/skills/github-project-management/SKILL.md @@ -0,0 +1,122 @@ +--- +name: github-project-management +description: Use when completing design docs, creating implementation plans, discovering bugs during unrelated work, or finishing branches - integrates GitHub issue tracking into development workflow with confirmation before creating issues +--- + +# GitHub Project Management + +## Overview + +Integrate GitHub issue tracking into natural development workflow. Offer to create issues at key checkpoints, always with user confirmation. + +**Core principle:** Work should be tracked where it happens, not as a separate administrative task. + +## Configuration + +Each repo specifies its project in CLAUDE.md: + +```markdown +## GitHub Project + +github_project: owner/project-number +``` + +Examples: `github_project: obra/1` (user) or `github_project: my-org/5` (org) + +If missing, ask: "No project configured. Create as repo-only issue, or specify a project?" + +For cross-repo items, always ask which project to use. + +## Integration Points + +### 1. After Brainstorming + +**Trigger:** Design doc committed to `docs/plans/` + +**Action:** Ask "Create a tracking issue for this feature?" + +If yes, propose: +``` +Title: [Feature] +Body: Summary + link to design doc + acceptance criteria +``` + +Wait for approval, then create and add to project. + +### 2. After Writing Plans + +**Trigger:** Implementation plan completed + +**Action:** Ask "Create tracking issues for this plan?" + +Options: +- A) Single parent issue linking to plan +- B) Individual issues per major task +- C) Skip + +### 3. During Implementation (Bug/Debt Discovery) + +**Trigger:** Discovered bug or tech debt unrelated to current task + +**Decision tree:** +- Can fix in <5 minutes without derailing current work? → Fix it, no issue needed +- Complex, requires investigation, or would derail work? → Offer to create issue + +**Action:** "I found an issue: . Create an issue to track this?" + +If yes, propose: +``` +Title: [Bug] or [Tech Debt] +Body: Context (what you were doing), location, description, potential impact +``` + +**This is NOT "overstepping"** — offering to track work is part of the development workflow, not project management politics. + +### 4. After Finishing Branch + +**Trigger:** Branch work complete, running finishing-a-development-branch + +**Action:** Check for related issues: +- Issue references in commits (`#123`, `fixes #456`) +- Issue number in branch name + +If found, ask: "Update these issues?" with options: close, comment, or skip. + +If PR created, remind: issues with `fixes #N` auto-close on merge. + +## Issue Types + +| Situation | Create | +|-----------|--------| +| Single-repo work (bug, feature) | Repo issue via `gh issue create` | +| Cross-repo, spike, unclear scope | Project draft via `gh project item-create` | + +Repo issues can be referenced in commits and auto-close via PR. + +## Common Rationalizations (Don't Fall For These) + +| Excuse | Reality | +|--------|---------| +| "Creating issues is overstepping" | Offering to track work is collaboration, not politics | +| "It's in git, no need for issue" | Git tracks code, issues track work intent and status | +| "Administrative overhead" | 30 seconds now vs forgotten work later | +| "Not my domain" | You're part of the team, tracking is everyone's job | + +## Quick Reference + +See gh-reference.md for CLI commands. + +**Minimum auth:** `gh auth refresh -s project` + +**Most common operations:** +```bash +# Create issue and add to project +gh issue create -R owner/repo --title "Title" --body "Body" +gh project item-add PROJECT_NUM --owner OWNER --url ISSUE_URL + +# Create project draft (cross-repo) +gh project item-create PROJECT_NUM --owner OWNER --title "Title" --body "Body" + +# Check project config +gh project list --owner OWNER +``` diff --git a/skills/github-project-management/gh-reference.md b/skills/github-project-management/gh-reference.md new file mode 100644 index 00000000..383c8970 --- /dev/null +++ b/skills/github-project-management/gh-reference.md @@ -0,0 +1,146 @@ +# GitHub CLI Reference for Project Management + +## Prerequisites + +```bash +# Check auth status and scopes +gh auth status + +# Add project scope (required for project operations) +gh auth refresh -s project +``` + +## Project Operations + +```bash +# List projects for owner +gh project list --owner obra +gh project list --owner my-org + +# View project details +gh project view 1 --owner obra + +# View in browser +gh project view 1 --owner obra --web + +# List fields (get field IDs for item-edit) +gh project field-list 1 --owner obra + +# List items in project +gh project item-list 1 --owner obra --limit 50 +``` + +## Issue Operations (Repo-Level) + +```bash +# Create issue +gh issue create -R owner/repo --title "Title" --body "Body" +gh issue create -R owner/repo --title "Title" --body "Body" --label "bug" +gh issue create -R owner/repo --title "Title" --body "Body" --assignee "@me" + +# Create and add to project in one command +gh issue create -R owner/repo --title "Title" --body "Body" --project "Project Name" + +# View issue +gh issue view 123 -R owner/repo +gh issue view 123 -R owner/repo --json title,body,state,labels + +# Edit issue +gh issue edit 123 -R owner/repo --title "New Title" +gh issue edit 123 -R owner/repo --add-label "priority:high" +gh issue edit 123 -R owner/repo --add-assignee "@me" +gh issue edit 123 -R owner/repo --add-project "Project Name" + +# Close issue +gh issue close 123 -R owner/repo + +# List issues +gh issue list -R owner/repo +gh issue list -R owner/repo --label "bug" --state open +``` + +## Project Item Operations (Project-Level) + +```bash +# Create draft item (for cross-repo/spike work) +gh project item-create 1 --owner obra --title "Title" --body "Description" + +# Add existing issue/PR to project +gh project item-add 1 --owner obra --url https://github.com/owner/repo/issues/123 + +# List items +gh project item-list 1 --owner obra --format json + +# Edit item field (requires field-id and project-id from field-list) +gh project item-edit --id ITEM_ID --field-id FIELD_ID --project-id PROJECT_ID --text "value" +gh project item-edit --id ITEM_ID --field-id FIELD_ID --project-id PROJECT_ID --single-select-option-id OPTION_ID + +# Delete item +gh project item-delete 1 --owner obra --id ITEM_ID + +# Archive item +gh project item-archive 1 --owner obra --id ITEM_ID +``` + +## Common Workflows + +### Create Issue and Add to Project + +```bash +# Method 1: Use --project flag (by project name) +gh issue create -R owner/repo \ + --title "[Feature] New notification preferences" \ + --body "## Summary +Implement user notification preferences. + +## Design +See: docs/plans/2025-11-25-notification-preferences-design.md" \ + --project "My Project" + +# Method 2: Two-step (by project number) +ISSUE_URL=$(gh issue create -R owner/repo --title "Title" --body "Body" | tail -1) +gh project item-add 1 --owner obra --url "$ISSUE_URL" +``` + +### Create Cross-Repo Draft Item + +```bash +gh project item-create 1 --owner obra \ + --title "[Spike] Evaluate auth library options" \ + --body "## Context +Need to choose auth library for new microservices. + +## Scope +- Evaluate Auth0, Clerk, and roll-our-own +- Affects: api-gateway, user-service, admin-portal" +``` + +### Find and Update Item Status + +```bash +# Get field IDs +gh project field-list 1 --owner obra --format json + +# Get item ID from list +gh project item-list 1 --owner obra --format json | jq '.items[] | select(.content.title == "Issue Title")' + +# Update status field (need field-id, project-id, option-id from above) +gh project item-edit \ + --id PVTI_xxx \ + --field-id PVTF_xxx \ + --project-id PVT_xxx \ + --single-select-option-id OPTION_ID +``` + +## JSON Output Examples + +```bash +# Issue with project info +gh issue view 123 -R owner/repo --json title,projectItems + +# Project items as JSON +gh project item-list 1 --owner obra --format json + +# Filter with jq +gh project item-list 1 --owner obra --format json | jq '.items[] | {title: .content.title, status: .status}' +``` From f42e426f003e8e531700f3196509b5a13ac19053 Mon Sep 17 00:00:00 2001 From: Nick Clarke Date: Wed, 26 Nov 2025 15:22:23 -0800 Subject: [PATCH 3/4] add sub-issue mechanics --- .../github-project-management/gh-reference.md | 74 +++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/skills/github-project-management/gh-reference.md b/skills/github-project-management/gh-reference.md index 383c8970..4457e910 100644 --- a/skills/github-project-management/gh-reference.md +++ b/skills/github-project-management/gh-reference.md @@ -132,6 +132,80 @@ gh project item-edit \ --single-select-option-id OPTION_ID ``` +## Sub-Issues (Parent/Child Relationships) + +GitHub supports hierarchical issue relationships via sub-issues. No native `gh` CLI support yet, so use GraphQL API directly. + +**Key requirements:** +- Requires node IDs, not issue numbers +- Requires feature flag: `-H "GraphQL-Features: sub_issues"` +- Works cross-repo (node IDs are globally unique) + +```bash +# Get node ID for an issue +gh api repos/owner/repo/issues/123 --jq '.node_id' +# Output: I_kwDONkHkN87aiXQ0 + +# Add sub-issue (child under parent) +gh api graphql \ + -H "GraphQL-Features: sub_issues" \ + -f query=' + mutation { + addSubIssue(input: { + issueId: "PARENT_NODE_ID", + subIssueId: "CHILD_NODE_ID" + }) { + issue { number } + subIssue { number } + } + } + ' + +# Remove sub-issue +gh api graphql \ + -H "GraphQL-Features: sub_issues" \ + -f query=' + mutation { + removeSubIssue(input: { + issueId: "PARENT_NODE_ID", + subIssueId: "CHILD_NODE_ID" + }) { + issue { number } + subIssue { number } + } + } + ' + +# List sub-issues of a parent +gh api graphql \ + -H "GraphQL-Features: sub_issues" \ + -f query=' + query { + node(id: "PARENT_NODE_ID") { + ... on Issue { + subIssues(first: 50) { + nodes { number title state } + } + } + } + } + ' +``` + +### Helper: Add Sub-Issue by Issue Numbers + +```bash +# Usage: Substitute owner/repo and issue numbers +PARENT_ID=$(gh api repos/owner/repo/issues/123 --jq '.node_id') +CHILD_ID=$(gh api repos/other-owner/other-repo/issues/456 --jq '.node_id') + +gh api graphql \ + -H "GraphQL-Features: sub_issues" \ + -f query="mutation { addSubIssue(input: {issueId: \"$PARENT_ID\", subIssueId: \"$CHILD_ID\"}) { subIssue { number } } }" +``` + +**Note:** Shell variable expansion in GraphQL queries can be tricky. If you hit escaping issues, hardcode the IDs directly in the query string. + ## JSON Output Examples ```bash From 51e5e01a823bd57f48e50e4e9b087646481958c0 Mon Sep 17 00:00:00 2001 From: Nick Clarke Date: Mon, 8 Dec 2025 15:30:37 -0800 Subject: [PATCH 4/4] feat: add sub-issues option to plan tracking workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update "After Writing Plans" section to offer hierarchical issue tracking via GitHub's sub-issues feature as option B. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- skills/github-project-management/SKILL.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/skills/github-project-management/SKILL.md b/skills/github-project-management/SKILL.md index 97d91432..b639f186 100644 --- a/skills/github-project-management/SKILL.md +++ b/skills/github-project-management/SKILL.md @@ -51,8 +51,11 @@ Wait for approval, then create and add to project. Options: - A) Single parent issue linking to plan -- B) Individual issues per major task -- C) Skip +- B) Parent issue with sub-issues for major tasks (hierarchical tracking) +- C) Individual issues per major task (flat structure) +- D) Skip + +For option B, use GitHub's sub-issues feature to create parent/child relationships. See gh-reference.md for GraphQL commands (requires node IDs, not issue numbers). ### 3. During Implementation (Bug/Debt Discovery)