Project Planner

Prerequisites

• git
• gh (GitHub CLI, authenticated via gh auth login)

Triage user input into the right project artifact: a proposal (big idea with phases), a feature issue (small enhancement), or a bug report (something's broken).

Repo Discovery

Before doing anything, discover the current repo's configuration:

1. Run git rev-parse --show-toplevel to find the repo root
2. Check for .project-planner.yml at the repo root — if it exists, read it and use its values for all paths, labels, and conventions
3. If no config file, fall back to auto-discovery:
   • Proposal template: look for docs/proposals/TEMPLATE.md
   • Issue templates: look in .github/ISSUE_TEMPLATE/
   • Docs directory: look for docs/, mkdocs.yml
   • If nothing found, use the fallback formats bundled with the skill
4. If the repo has CLAUDE.md or CONTRIBUTING.md, read for conventions
5. Run gh repo view --json name,owner to confirm the repo for issue creation

Config File: .project-planner.yml

Optional config file at repo root. All fields are optional — auto-discovery fills gaps. See project-planner.yml in the skill directory for a copy-paste starter.

project: MyProject                    # project name (for issue titles)
repo: owner/repo                      # GitHub repo (usually auto-detected)

proposals:
  dir: docs/proposals                 # where proposal docs live
  template: docs/proposals/TEMPLATE.md # proposal template to follow
  index: docs/proposals/index.md      # index file to update with new proposals
  mkdocs_nav: true                    # update mkdocs.yml nav when creating proposals

issues:
  labels:
    feature: enhancement              # label for feature issues
    bug: bug                          # label for bug issues
  # branch_prefix: feature/           # branch naming prefix

# conventions:
#   docs: docs                        # where project docs live

Triage Rules

Determine the type by asking: does this need design work or multiple phases?

• Needs design decisions, multiple phases, or architectural thought → Proposal
• Single, obvious change — no design needed → Feature issue
• Something is broken or behaving wrong → Bug report

If unclear, ask the user: "Is this a quick fix or does it need a design doc?"

Workflow: Proposal

For big ideas that need phases and design.

1. Discover proposal template (see Repo Discovery above)
2. Research the codebase and any docs/ directory for relevant context
3. Think through the design — motivation, approach, trade-offs
4. Break into shippable phases (each phase delivers user value)
5. Write acceptance criteria at both levels (overall + per-phase)
6. Create the proposal doc at docs/proposals/<name>.md
7. If mkdocs.yml exists, add the proposal to the nav under Proposals
8. If docs/proposals/index.md exists, add to the Active Proposals list
9. Create a tracking issue (parent) using gh issue create:
   • Title: <Proposal name> (no "Phase" prefix — this is the umbrella issue)
   • Body: link to the proposal doc, overall acceptance criteria, summary of phases
   • Label: enhancement
   • Save the issue node ID (gh issue view <number> --json id -q .id)
10. Create a GitHub issue for each phase using gh issue create:
    • Title: <Proposal name>: Phase N — <phase name>
    • Body: phase goal, acceptance criteria, tasks as checklist, link to proposal, and a ## Tracking section with Parent: #<tracking-issue-number>
    • Label: enhancement
11. Wire each phase issue as a native sub-issue of the tracking issue using GraphQL:

    gh api graphql -f query='
      mutation {
        addSubIssue(input: {
          issueId: "<tracking-issue-node-id>"
          subIssueId: "<phase-issue-node-id>"
        }) { issue { id } subIssue { id } }
      }'
    

    If the mutation fails (repo doesn't support sub-issues, permissions), fall back to listing phase issues as linked references in the tracking issue body.
12. Update the proposal doc with phase issue links and the tracking issue link in the header (e.g., Tracking: #<number>)
13. Commit to a new branch and push

Tracking Issue Convention

Every multi-phase proposal gets a tracking issue with native GitHub sub-issues (not markdown checkbox task lists). This gives you:

• Progress badges — the issue list shows "2 of 5" sub-issue completion at a glance
• Bidirectional navigation — parent links to children, children link back to parent
• Automatic updates — when PRs close a phase issue, the tracking issue progress updates

Always use the addSubIssue GraphQL mutation to wire parent↔child relationships. Markdown checkboxes (- [ ] #123) are just text — they don't update automatically and GitHub doesn't treat them as real relationships. Native sub-issues are a first-class GitHub feature with proper status tracking.

Proposal Quality Checklist

Before committing, verify:

• Summary is one clear paragraph
• Motivation explains why now
• Design covers user experience AND technical approach
• Every phase is independently shippable
• Acceptance criteria are testable (not vague)
• Open questions section exists (even if empty)
• Related section links to relevant docs, issues, or design docs
• Tracking issue exists with all phase issues wired as sub-issues (or, if unsupported, linked from the tracking issue body)
• Status is set to "Ready" (if issues created) or "Draft" (if not)

Workflow: Feature Issue

For small, self-contained enhancements.

1. Discover feature template (see Repo Discovery above)
2. Create a GitHub issue using gh issue create:
   • Title: clear, action-oriented
   • Body: summary, acceptance criteria as checklist, doc references if relevant
   • Follow the repo's template format if one exists
   • Label: enhancement
3. Report the issue number and URL to the user

Workflow: Bug Report

For problems and broken behavior.

1. Discover bug template (see Repo Discovery above)
2. Try to identify the relevant code by searching the codebase
3. Create a GitHub issue using gh issue create:
   • Title: Bug: <concise description>
   • Body: description, steps to reproduce (if known), expected vs actual, relevant code files/lines, related docs
   • Follow the repo's template format if one exists
   • Label: bug
4. Report the issue number and URL to the user

Important Rules

• Always use gh issue create — it's repo-aware, handles auth
• Always link back — issues reference proposals, proposals reference issues
• Proposals stay forever — status changes, docs never move or get deleted
• One proposal per feature — don't cram multiple ideas into one doc
• Phases must be shippable — each delivers user value, not just "backend work"
• Every multi-phase proposal gets a tracking issue — created before phase issues
• Phase issues reference the tracking issue — via ## Tracking section in body
• Commit to a branch — never push directly to main
• Respect repo conventions — if the repo has CLAUDE.md or CONTRIBUTING.md, read and follow its branch naming, commit message, and PR conventions