# Project Planner

> Triage ideas, problems, and feature requests into the right format: proposal doc, feature issue, or bug report. Repo-aware — discovers templates and docs structure from the current repository. Use when: (1) the user describes an idea, feature, or problem they want to track, (2) the user says "file a bug", "I have an idea", "let's plan this feature", or similar, (3) the user wants to break down a large feature into phases with GitHub issues. NOT for: actually implementing code (use coding-agent), reviewing PRs, or general questions about the codebase.

- Skill: `chriscox/project-planner` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add chriscox/project-planner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chriscox/project-planner/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: chriscox (https://skillmd.com/u/chriscox)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/chriscox/project-planner

---


# 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.

```yaml
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