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 000000000..5951bcaf2 --- /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 diff --git a/docs/plans/2026-02-11-github-project-management-skill-review.md b/docs/plans/2026-02-11-github-project-management-skill-review.md new file mode 100644 index 000000000..5cbe52fb4 --- /dev/null +++ b/docs/plans/2026-02-11-github-project-management-skill-review.md @@ -0,0 +1,369 @@ +# GitHub Project Management Skill — TDD Review + +## RED Phase: CLI Testing Results + +All `gh` CLI commands from `gh-reference.md` were tested against real project `nickolasclarke/1`. + +### Working Correctly +- `gh auth status`, `project list/view/field-list/item-list` +- `project item-create` (drafts), `item-edit`, `item-delete` +- `issue create`, `issue create --project` (one-step) +- All GraphQL sub-issues commands (`addSubIssue`, `removeSubIssue`, `listSubIssues`) + +### Issues Found + +1. **`item-create` returns NO OUTPUT on success** — agent won't know the item ID was created. The skill/reference should note this and suggest using `item-list --format json` after to verify. +2. **`gh issue create` fails if the repo has issues disabled** — skill doesn't handle this case. +3. **`--project` flag on `gh issue create` works by PROJECT NAME (not number)** — `gh-reference.md` shows both methods but could be clearer about when to use which. + +--- + +## Analysis Against writing-skills Guidelines + +### Frontmatter/CSO + +**Current description (227 chars):** +```yaml +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 +``` + +**Analysis:** + +| Criterion | Status | Notes | +|-----------|--------|-------| +| Starts with "Use when..." | Pass | Correct format | +| Under 500 chars | Pass | 227 chars | +| Under 1024 chars total | Pass | Well within limit | +| Third person | Pass | No first-person language | +| Avoids summarizing workflow | **Fail** | The second half — "integrates GitHub issue tracking into development workflow with confirmation before creating issues" — summarizes what the skill does rather than when to use it. This is exactly the trap writing-skills warns about in the CSO section. | + +The description's first half is good (triggering conditions), but the second half describes the skill's behavior. Per writing-skills: "Descriptions that summarize workflow create a shortcut Claude will take. The skill body becomes documentation Claude skips." + +**Proposed fix:** +```yaml +description: Use when completing design docs, creating implementation plans, discovering bugs during unrelated work, or finishing branches — any checkpoint where work should be tracked in GitHub issues or project boards +``` + +This keeps the triggering conditions but replaces the workflow summary with additional context about *when* (not *how*). + +### Structure + +**Recommended template from writing-skills:** +``` +Overview, When to Use, Core Pattern, Quick Reference, Implementation, Common Mistakes +``` + +**Current SKILL.md structure:** +``` +Overview, Configuration, Integration Points (4 sub-sections), Issue Types, Common Rationalizations, Quick Reference +``` + +**Comparison:** + +| Recommended Section | Present? | Notes | +|---------------------|----------|-------| +| Overview | Yes | Good — has core principle | +| When to Use | **No** | Missing entirely. Integration Points partially covers this but as workflow steps, not as a "When to Use / When NOT to Use" section | +| Core Pattern | N/A | This is a workflow skill, not a technique — reasonable to skip | +| Quick Reference | Yes | Present but minimal — just a pointer to gh-reference.md + 3 commands | +| Implementation | Partially | Integration Points serve this role | +| Common Mistakes | **No** | Missing. The "Common Rationalizations" table addresses a different concern (resistance to issue creation) | +| Red Flags | **No** | Missing | + +**Additional observations:** +- The "Configuration" section is well-placed early — good for practical setup. +- "Integration Points" is the skill's core content and is well-structured with triggers and actions. +- "Issue Types" table is clean and useful. + +### Token Efficiency + +**Word counts:** + +| File | Words | Target | Status | +|------|-------|--------|--------| +| SKILL.md | 582 | <500 | **Over by 82 words** | +| gh-reference.md | 829 | N/A (reference file) | Acceptable as heavy reference | +| **Combined** | **1,411** | — | Loaded together when skill is active | + +**Comparison with peer skills:** + +| Skill | Words | +|-------|-------| +| brainstorming | 364 | +| writing-plans | 458 | +| finishing-a-development-branch | 679 | +| **github-project-management** | **582** | + +The SKILL.md is in the same ballpark as finishing-a-development-branch (which is a more complex skill). Not egregiously over, but should be trimmed. + +**What can be cut:** + +1. **Quick Reference section (lines 109-125):** The 3 example commands duplicate content from gh-reference.md. Replace with just: "See gh-reference.md for CLI commands. Minimum auth: `gh auth refresh -s project`" — saves ~50 words. +2. **"Common Rationalizations" table (lines 99-106):** This is good content but takes ~50 words. Could be tighter — the table repeats similar points. Consider keeping 2 rows instead of 4. +3. **Integration Point templates:** The proposed issue body formats in sections 1 and 3 are detailed. These are useful for agent behavior but could be compressed slightly. + +**Net savings estimate:** ~80-100 words, bringing it under 500. + +### Keyword Coverage + +**Terms an agent would search for when needing this skill:** + +| Search Term | Present in SKILL.md? | Present in gh-reference.md? | +|-------------|---------------------|-----------------------------| +| "issue" | Yes | Yes | +| "project" | Yes | Yes | +| "tracking" / "track" | Yes | No | +| "bug" | Yes (in rationalizations) | No | +| "tech debt" | Yes | No | +| "sub-issue" / "sub-issues" | Yes | Yes | +| "GitHub" | Yes (title + config) | Yes | +| "milestone" | No | No | +| "backlog" | No | No | +| "project board" | No | No | +| "draft" | Yes (in Issue Types table) | Yes | +| "sprint" | No | No | +| "triage" | No | No | +| "gh project" / "gh issue" | Yes | Yes | + +**Gaps:** "project board", "backlog", and "triage" are terms an agent might search for. The first is a minor gap. The latter two are intentionally out of scope (the design doc explicitly says strategic planning is not covered), but a "When NOT to Use" section could mention them as exclusions, which would actually *improve* discoverability — an agent searching "backlog" would find the skill and see it's not the right one, avoiding confusion. + +### Cross-Referencing + +**Current references in SKILL.md:** + +| Referenced Skill | How Referenced | Proper Marker? | +|------------------|---------------|----------------| +| brainstorming | Implicit — "Design doc committed to `docs/plans/`" (section 1) | **No** — no explicit skill reference | +| writing-plans | Implicit — "Implementation plan completed" (section 2) | **No** — no explicit skill reference | +| finishing-a-development-branch | Explicit — "running finishing-a-development-branch" (section 4) | **No** — uses plain text, not `REQUIRED SUB-SKILL` or `REQUIRED BACKGROUND` marker | +| gh-reference.md | "See gh-reference.md for CLI commands" + "See gh-reference.md for GraphQL commands" | N/A — this is a file within the skill, not a cross-skill reference | + +**Issues:** + +1. None of the cross-references use the required markers (`REQUIRED BACKGROUND` or `REQUIRED SUB-SKILL`). +2. The relationship here is the reverse of typical cross-references — this skill is *called by* brainstorming, writing-plans, and finishing-a-development-branch, not the other way around. The question is whether *those* skills reference this one. That's outside the scope of this review but worth noting. +3. The skill should clarify its relationship to the other skills. Something like: "**Called after:** brainstorming, writing-plans, finishing-a-development-branch" (similar to how finishing-a-development-branch has a "Called by" section). + +**Comparison:** finishing-a-development-branch has an explicit "Integration" section at the bottom listing "Called by" and "Pairs with" relationships. github-project-management lacks this pattern. + +### Flowcharts + +**Decision points that could benefit from a flowchart:** + +1. **Issue Type Decision (Repo issue vs Project draft):** Currently a 2-row table. The decision is simple enough that a table works fine — a flowchart would be overkill. + +2. **Bug Discovery Decision Tree (section 3):** Currently inline text: "Can fix in <5 minutes? → Fix it. Complex? → Offer to create issue." This is a legitimate decision point. A small inline flowchart would make the decision clearer and harder to skip. However, it's only two branches — borderline whether it warrants a flowchart. + +3. **Overall Integration Point Selection:** "Which integration point am I at?" is implicitly answered by the trigger conditions (design doc committed, plan completed, bug discovered, branch finishing). This doesn't need a flowchart — the triggers are distinct enough. + +**Recommendation:** A flowchart is not strictly necessary. The existing structure is clear. If anything, the bug discovery decision tree in section 3 is the best candidate, but it's simple enough that the current inline format works. + +### Missing Sections + +| Section | Status | Priority | +|---------|--------|----------| +| **When to Use / When NOT to Use** | Missing | High — this is in the template and helps discoverability | +| **Common Mistakes** | Missing | Medium — what goes wrong when agents use this skill? | +| **Red Flags** | Missing | Medium — for discipline aspects (e.g., creating issues without confirmation) | +| **Integration / Called By** | Missing | Low — nice to have for cross-skill navigation | + +### Pattern Comparison + +**How peer skills handle key structural elements:** + +| Element | brainstorming | finishing-branch | writing-plans | github-project-mgmt | +|---------|--------------|-----------------|--------------|---------------------| +| "Announce at start" | No | Yes | Yes | No | +| When to Use / NOT | No | No | No | No | +| Common Mistakes | No | Yes (4 items) | No | No | +| Red Flags | No | Yes | No | No | +| Quick Reference table | No | Yes | No | Partial (pointer) | +| Integration/Cross-refs | Mentioned inline | Explicit section | Explicit markers | Implicit only | +| Core principle stated | No | Yes | No | Yes | + +**Observations:** +- finishing-a-development-branch is the most mature skill of the set — it has Common Mistakes, Red Flags, Quick Reference table, and an Integration section. It's the best structural model for github-project-management. +- brainstorming is surprisingly light on structure — no common mistakes, no red flags, no announce. It may also need a review. +- writing-plans uses `REQUIRED SUB-SKILL` markers correctly in its execution handoff section — a good pattern for github-project-management to follow. + +--- + +## Proposed Improvements + +### Priority 1: Must Fix + +These are things that are either broken or violate critical guidelines. + +**1.1 — Description summarizes workflow (CSO violation)** + +The description's second half tells the agent what the skill does instead of when to use it. This is the exact anti-pattern the writing-skills CSO section warns about. + +Before: +```yaml +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 +``` + +After: +```yaml +description: Use when completing design docs, creating implementation plans, discovering bugs during unrelated work, or finishing branches — any development checkpoint where work should be tracked as GitHub issues or project items +``` + +**1.2 — `item-create` silent success not documented** + +`gh project item-create` returns no output on success. An agent following the reference will create an item and have no feedback. This should be noted in gh-reference.md. + +Add after the `item-create` command in gh-reference.md: +```markdown +# Note: item-create returns NO OUTPUT on success. +# Verify creation with: +gh project item-list 1 --owner obra --format json | jq '.items[-1]' +``` + +**1.3 — `--project` flag uses PROJECT NAME, not number** + +gh-reference.md Method 1 shows `--project "My Project"` which is correct, but the distinction between project name (for `--project` flag) and project number (for `gh project` subcommands) is not called out. An agent could easily confuse them. + +Add a note in gh-reference.md: +```markdown +# IMPORTANT: --project flag takes the project NAME (display name), +# while gh project subcommands take the project NUMBER. +``` + +### Priority 2: Should Fix + +These are guideline violations that affect quality but aren't broken. + +**2.1 — Add "When to Use / When NOT to Use" section** + +This is in the recommended template. The Integration Points section covers "when" implicitly via triggers, but there's no explicit section and — more importantly — no "When NOT to Use" guidance. + +Add after Overview: +```markdown +## When to Use + +- After completing a design doc (brainstorming) +- After writing an implementation plan (writing-plans) +- When you discover a bug or tech debt unrelated to current work +- After finishing a development branch (finishing-a-development-branch) + +## When NOT to Use + +- Sprint planning, backlog grooming, or roadmap organization +- Automated issue creation without user confirmation +- Project-specific conventions (put those in CLAUDE.md) +``` + +**2.2 — Add "Common Mistakes" section** + +finishing-a-development-branch provides a good model. Based on the RED phase testing results and the skill's design: + +```markdown +## Common Mistakes + +**Creating issues without confirmation** +- Problem: Issues are visible to the whole team — auto-creation is overstepping +- Fix: Always propose details and wait for explicit approval + +**Using project number with --project flag** +- Problem: `--project 1` fails; the flag takes project name, not number +- Fix: Use `--project "Project Name"` or the two-step method with project number + +**Assuming item-create output confirms success** +- Problem: `gh project item-create` returns no output on success +- Fix: Verify with `item-list --format json` after creation + +**Not checking repo has issues enabled** +- Problem: `gh issue create` fails on repos with issues disabled +- Fix: Fall back to project draft item for repos without issues +``` + +**2.3 — Add cross-reference markers** + +Replace implicit references with explicit markers per writing-skills guidelines. + +In Integration Points section headers, add: + +- Section 1: "**Follows:** superpowers:brainstorming" +- Section 2: "**Follows:** superpowers:writing-plans" +- Section 4: "**Follows:** superpowers:finishing-a-development-branch" + +And add an Integration section at the bottom (following finishing-a-development-branch's pattern): +```markdown +## Integration + +**Called after:** +- **brainstorming** — When design doc is committed +- **writing-plans** — When implementation plan is written +- **finishing-a-development-branch** — When branch work is complete +``` + +**2.4 — Trim SKILL.md to under 500 words** + +Current: 582 words. Target: <500. + +Specific cuts: +- Remove Quick Reference code block (lines 115-125) — redundant with gh-reference.md. Keep only the one-liner pointer and auth command. Saves ~40 words. +- Trim Common Rationalizations table from 4 rows to 2 most impactful. Saves ~30 words. +- Tighten Integration Point descriptions slightly. Target ~20 words saved. + +### Priority 3: Nice to Have + +**3.1 — Add "Red Flags" section** + +This skill has discipline-enforcing aspects (always confirm before creating, don't auto-create). A Red Flags section would reinforce these: + +```markdown +## Red Flags + +**Never:** +- Create an issue without user confirmation +- Add items to a project without checking configuration first +- Close issues without verifying they're actually resolved + +**Always:** +- Propose issue details and wait for approval +- Check `github_project` config before project operations +- Verify auth scopes before first project operation +``` + +**3.2 — Add sub-issues to SKILL.md Integration Point 2** + +The SKILL.md mentions sub-issues in Integration Point 2 (option B), but the design doc only shows options A, B (individual issues), C (skip). The SKILL.md added "Parent issue with sub-issues" as a new option B without it being in the design doc. This is an enhancement worth keeping since sub-issues were tested and work, but it should be noted that gh-reference.md is the reference for how to execute this. + +**3.3 — Note that `gh issue create` fails on repos with issues disabled** + +Add to Issue Types table or to a Common Mistakes section: +```markdown +**Note:** Some repos have GitHub Issues disabled. If `gh issue create` fails, fall back to creating a project draft item instead. +``` + +--- + +## Summary + +The github-project-management skill is well-designed overall. The integration point structure is clear, the triggers are distinct, and the separation between SKILL.md (workflow) and gh-reference.md (CLI commands) follows the writing-skills heavy reference pattern correctly. + +**What's good:** +- Clear core principle and overview +- Well-defined triggers for each integration point +- Issue Types table is concise and useful +- Common Rationalizations table addresses agent resistance effectively +- gh-reference.md is comprehensive with working examples +- Sub-issues support via GraphQL is well-documented + +**What needs work:** +- Description summarizes workflow (CSO violation) — Priority 1 +- Missing "When to Use / When NOT to Use" section — Priority 2 +- Missing "Common Mistakes" section — Priority 2, and the RED phase testing found real mistakes to document +- Cross-references are implicit rather than using required markers — Priority 2 +- Slightly over word count target (582 vs 500) — Priority 2 +- CLI gotchas from testing (silent `item-create`, `--project` name vs number) need to be documented — Priority 1 + +**Recommended next steps:** +1. Fix the description (CSO violation) — smallest change, highest impact on discoverability +2. Add Common Mistakes section incorporating RED phase findings +3. Add verification notes to gh-reference.md for `item-create` and `--project` flag +4. Add When to Use / When NOT to Use section +5. Add cross-reference markers and Integration section +6. Trim to under 500 words +7. Run GREEN phase tests with the updated skill to verify agent compliance diff --git a/skills/github-project-management/SKILL.md b/skills/github-project-management/SKILL.md new file mode 100644 index 000000000..e214252cb --- /dev/null +++ b/skills/github-project-management/SKILL.md @@ -0,0 +1,94 @@ +--- +name: github-project-management +description: Use when completing design docs, creating implementation plans, discovering bugs during unrelated work, or finishing branches — any development checkpoint where work should be tracked as GitHub issues or project items +--- + +# 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. + +## When to Use + +- After completing a design doc (brainstorming) +- After writing an implementation plan (writing-plans) +- When you discover a bug or tech debt unrelated to current work +- After finishing a development branch (finishing-a-development-branch) + +## When NOT to Use + +- Sprint planning, backlog grooming, or roadmap organization +- Automated issue creation without user confirmation +- Project-specific conventions (put those in CLAUDE.md) + +## Configuration + +Each repo specifies its project in CLAUDE.md as `github_project: owner/project-number` (e.g., `obra/1` for user, `my-org/5` for org). + +If missing, ask: "No project configured. Create as repo-only issue, or specify a project?" + +## Integration Points + +### 1. After Brainstorming + +**Follows:** superpowers:brainstorming + +**Trigger:** Design doc committed to `docs/plans/` + +**Action:** Ask "Create a tracking issue for this feature?" If yes, propose title (`[Feature] `), summary, link to design doc, and acceptance criteria. Wait for approval before creating. + +### 2. After Writing Plans + +**Follows:** superpowers:writing-plans + +**Trigger:** Implementation plan completed + +**Action:** Ask "Create tracking issues for this plan?" + +Options: A) Single parent issue linking to plan, B) Parent with sub-issues (see gh-reference.md for GraphQL commands), C) Individual issues per task, D) Skip. + +### 3. During Implementation (Bug/Debt Discovery) + +**Trigger:** Discovered bug or tech debt unrelated to current task + +Can fix in <5 minutes without derailing? Fix it. Otherwise, offer to create issue. + +**Action:** "I found an issue: . Create an issue to track this?" If yes, propose title (`[Bug]` or `[Tech Debt]`), context, location, and impact. Wait for approval. + +### 4. After Finishing Branch + +**Follows:** superpowers:finishing-a-development-branch + +**Trigger:** Branch work complete + +**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` | + +**Note:** Some repos have issues disabled. If `gh issue create` fails, use a project draft item instead. + +## Common Mistakes + +| Mistake | Fix | +|---------|-----| +| Creating issues without user confirmation | Always propose details and wait for explicit approval | +| Using project number with `--project` flag | `--project` takes the display name, not the number. Use `--project "My Project"` or the two-step method | +| Assuming `item-create` succeeded with no output | `gh project item-create` is silent on success. Verify with `item-list --format json` | + +## Quick Reference + +See gh-reference.md for CLI commands. **Minimum auth:** `gh auth refresh -s project` diff --git a/skills/github-project-management/gh-reference.md b/skills/github-project-management/gh-reference.md new file mode 100644 index 000000000..7bee58b12 --- /dev/null +++ b/skills/github-project-management/gh-reference.md @@ -0,0 +1,222 @@ +# 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 +# NOTE: --project takes the project DISPLAY NAME, not the number +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) +# NOTE: Returns no output on success. Verify with item-list after. +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 (takes project DISPLAY NAME, not number) +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 +``` + +## 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 +# 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}' +```