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

Security Scan

The skill's declared purpose (triaging repo ideas into proposals/issues) matches its instructions and bundled templates; it operates on the repository and uses the Git/GitHub CLI as expected.

Purpose & Capability

Name/description, bundled proposal/issue templates, and the runtime instructions all align: the skill discovers repo templates/docs, produces proposal docs and GitHub issues, and commits/pushes branches. Nothing required by the skill appears unrelated to triaging and authoring project artifacts.

Instruction Scope

SKILL.md explicitly instructs the agent to read repo files (templates, CONTRIBUTING.md/CLAUDE.md, mkdocs.yml), create docs, create issues via `gh`, commit to a branch, and push. Those actions are consistent with the stated workflows; the instructions do not request unrelated system data or external endpoints beyond GitHub/Git access.

Install Mechanism

This is an instruction-only skill with no install spec and no code to write to disk, which is the lowest-risk model for this functionality.

Credentials

The metadata declares no required env vars, which matches there being no explicit API keys bundled. However, the runtime expects the GitHub CLI (`gh`) to be installed and authenticated (via `gh auth login` or an existing gh session) and Git credentials/SSH keys to push branches. The skill will therefore act using the user's existing Git/GitHub authentication and requires write access to the repo to create/push branches and create issues. This is proportionate to its purpose but the metadata does not call out the need for authenticated GitHub credentials.

Persistence & Privilege

always is false and model invocation is allowed (the default). The skill will modify repository files (docs, mkdocs.yml, index), create branches, and push commits using the user's credentials — appropriate for this use case. If you are concerned about autonomous changes, limit when the skill can run or require explicit invocation before it performs writes.

Assessment

This skill will read your repository, create proposal docs, open GitHub issues, and commit & push branches using your Git/GitHub credentials (via the GitHub CLI). Before installing or invoking it: (1) verify the gh CLI is installed and authenticated with an account/token that has only the permissions you want to grant, (2) review the bundled templates and .project-planner.yml if present so you know what will be written, (3) prefer testing in a fork or test repo if you do not want automated changes in a production repository, and (4) if you do not want the agent to make writes autonomously, require manual invocation or remove its ability to run commands that push commits and create issues.

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 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
   • Label: enhancement
10. Update the proposal doc with issue links for each phase
11. Commit to a new branch and push

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
• 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"
• 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