Skip to content

paulmona/pm

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

30 Commits
.claude-plugin
.claude-plugin
 
 
.github/workflows
.github/workflows
 
 
commands
commands
 
 
.gitignore
.gitignore
 
 
CLAUDE.md
CLAUDE.md
 
 
README.md
README.md
 
 

Repository files navigation

claude-skills

A complete project management pipeline for Claude Code — from product idea to structured GitHub project, powered by Notion and GitHub.

How the Pipeline Works

Idea → PRD → TRD → Bootstrap → GitHub → Build

Everything runs through a single command: /pm. It detects your environment (Claude Code vs Claude.ai/Desktop) and routes to the right action.

  1. Create a PRD (/pm create) — A guided interview captures product requirements: what you're building, why, for whom, and how you'll measure success. The PRD is saved to your Notion PRDs database with a Project Status dashboard and Project Board.

  2. Create a TRD (/pm trd) — A technical interview builds the implementation plan: architecture, tool decisions, milestones, stories, and dependencies. The TRD is saved as a child page of the PRD in Notion.

  3. Mark as Ready (/pm ready) — Validates the PRD and sets GitHub Ready = true in Notion. This is the gate between planning and execution.

  4. Bootstrap the Project (/pm bootstrap) — Populates the Notion Project Board, creates GitHub milestones and issues with TDD checklists, builds a dependency map, cross-links everything, and generates a CLAUDE.md file. One atomic operation.

  5. Build — Use /pm next to find what to work on, /pm bug and /pm enhancement to track issues as they arise, /pm bughunt to investigate problems, and /pm status for project health checks.

Environment Modes

Full Mode (Claude Code) Light Mode (Claude.ai / Desktop)
Available actions All 9 actions create, trd, ready, status, bug, enhancement
GitHub integration Yes (gh CLI) No — Notion board only
File system Yes No

Configuration

Skills read Notion database IDs from your project's CLAUDE.md (generated by /pm bootstrap). On first run, if no CLAUDE.md exists, the skill will ask for your Notion PRD database ID. No hardcoded IDs are stored in the skills themselves.

Installation

As a Claude Code Plugin (recommended)

Inside any Claude Code session:

/plugin marketplace add paulmona/claude

Then run /plugin, find pm under the paulmona-claude marketplace, and install it.

To update after new releases:

/plugin update pm

Manual Install

cp commands/* ~/.claude/commands/
cp -r commands/pm-actions ~/.claude/commands/

Usage

/pm                     — Show menu (filtered by environment)
/pm create              — Create PRD via guided interview
/pm trd [PRD ref]       — Create TRD from PRD
/pm ready [PRD ref]     — Mark PRD as GitHub Ready
/pm bootstrap [PRD ref] — Populate Notion board + GitHub milestones/issues
/pm status              — Project health summary
/pm next                — Recommend what to work on next
/pm bug ["description"] — File a bug
/pm enhancement ["desc"]— File an enhancement
/pm bughunt [#N or desc]— Investigate and root-cause a bug

After each action, /pm suggests the logical next step in the pipeline.

Actions Reference

/pm create

Guides you through a structured interview to create a Product Requirements Document and saves it to Notion.

What it does:

  • Walks through 9 interview topics one at a time: name, problem, goals, non-goals, user stories, success metrics, stakeholders, open questions, and priority
  • Coaches you to keep product and technical concerns separate — technical details are redirected to the TRD
  • Probes thin answers with follow-up questions to get depth
  • Flags production-only metrics that will need instrumentation
  • Auto-numbers the PRD by scanning existing entries in Notion
  • Drafts the full PRD in Markdown for review before saving
  • Creates the page in your Notion PRDs database with Status: Draft
  • Creates a Project Status dashboard and inline Project Board database as child pages

Output: A Notion page titled PRD-{NNN}: {Feature Name} with dashboard and board.

/pm trd

Guides you through a technical interview to create a Technical Requirements Document, then saves it as a child page of the PRD in Notion.

Usage: /pm trd PRD-009 or /pm trd "Feature name"

What it does:

  • Locates the PRD in Notion and pulls its content for context
  • Walks through 9 technical topics: architecture, tool decisions, interface mapping, observability, milestones, stories per milestone, dependencies, risks, and open questions
  • Ensures observability is a dedicated milestone, not an afterthought
  • Keeps stories atomic — if a story has "and" in it, it's probably two stories
  • Can auto-generate interface mappings from OpenAPI specs or API docs
  • Story IDs are sequential (S1, S2, S3...) with explicit dependency declarations
  • Drafts the full TRD in Markdown for review before saving
  • Creates the TRD as a child page of the PRD in Notion
  • Updates the dashboard Quick Links with TRD reference

Output: A Notion page titled TRD: {Feature Name} nested under the PRD.

/pm ready

Validates a PRD and marks it as GitHub Ready in Notion — the gate between planning and execution.

Usage: /pm ready PRD-002 or /pm ready (lists available PRDs)

What it does:

  • If no argument, searches Notion for Approved PRDs not yet marked GitHub Ready and presents the list
  • Confirms with the user before making any changes
  • Sets GitHub Ready = true on the PRD page in Notion
  • Updates the dashboard status section

Output: The PRD's GitHub Ready property is set to true.

/pm bootstrap

The core action. Reads a PRD and TRD from Notion and generates a complete GitHub project structure in one operation. Full mode only.

Usage: /pm bootstrap PRD-002 paulmona/my-repo

What it does:

  1. Pre-flight — Resolves the Notion database ID (from CLAUDE.md or asks), fetches the PRD (must be Approved + GitHub Ready), fetches the TRD (warns if missing), and runs a frontend requirements interview if the project has UI.

  2. Notion Board — Populates the Project Board database with story cards from the TRD, including status, milestone, phase, dependencies, and type.

  3. Milestones — Creates GitHub milestones from the TRD. Ensures full-stack coverage if the project has a frontend.

  4. Issues — Decomposes each milestone into discrete, testable issues (1-4 hours each). Every build issue gets a paired test issue written first (TDD). Issues include user story, acceptance criteria, Definition of Done checklist, dependencies, and file ownership boundaries. Issues are presented one milestone at a time for review before creation. Each created issue is cross-linked to its Notion board card.

  5. Dashboard — Updates the milestone progress table with actual counts from GitHub.

  6. Dependency Map — Creates a pinned GitHub issue showing the full dependency graph organized into parallelizable phases.

  7. CLAUDE.md — Generates and commits a project-specific CLAUDE.md with build commands, architecture docs, Notion IDs, git workflow rules, file ownership rules, and the Definition of Done.

Supports resuming — State is saved to .claude/pm-state.json after each step. If interrupted, running /pm bootstrap again detects the state file and offers to resume or start fresh.

Output: A fully structured GitHub project with Notion board cross-linked to GitHub issues.

/pm next

Analyzes GitHub project state and recommends the highest-priority unblocked work. Full mode only.

Usage: /pm next paulmona/my-repo

What it does:

  • Fetches all open milestones, issues, labels, and the pinned dependency map
  • Reads Notion board for phase information
  • Identifies the active milestone (earliest incomplete)
  • Classifies issues as UNBLOCKED, BLOCKED, or IN PROGRESS
  • Applies priority ordering: test before build (TDD), setup before features, bugs before enhancements
  • Flags issues with missing milestones, labels, or DoD checklists

Output:

## Next — repo — date

### Active Milestone: M2: Core Build (60% — 6/10 issues)

### Recommended Next (unblocked, highest priority)
#14 Write failing tests for lead scoring — test issue, TDD requires this before #15

### Also Unblocked (can run in parallel)
#16 Implement API proxy endpoint
#18 Write failing tests for report generation

### Blocked
#15 Implement lead scoring — waiting on #14

### Flags
2 issues have no type label

/pm status

Generates a health summary of the entire GitHub project.

Usage: /pm status paulmona/my-repo

What it does:

  • Fetches all milestones (open and recently closed), all issues, and the dependency map
  • Calculates per-milestone: % complete, open issues by type, blocked count, missing labels
  • Tracks velocity: issues closed in last 7 and 30 days
  • Estimates milestone completion at current pace
  • Full mode: syncs live data back to the Notion dashboard
  • Light mode: reads last synced state from Notion dashboard

Output:

## Project Status — repo — date

### Milestones
| Milestone | Progress | Open | Bugs | Blocked | Status |
|---|---|---|---|---|---|
| M1: Scaffolding | 100% | 0 | 0 | 0 | Complete |
| M2: Core Build | 60% (6/10) | 4 | 1 | 1 | Active |
| M3: Integration | 0% | 8 | 0 | 0 | Not started |

### Open Bugs / Blocked Issues / Health Flags / Velocity

Overall: Yellow — M2 progressing but 1 critical bug blocking #22

/pm bug

Creates a structured bug report. In Full mode, creates both a GitHub issue and a Notion board card. In Light mode, creates a Notion board card only.

Usage: /pm bug "Lead scoring returns null when company size is missing"

What it does:

  • If no description provided, asks for one
  • Asks for: repo (Full mode), related milestone, severity (Critical / High / Low)
  • Creates a GitHub issue with: what's happening, what should happen, steps to reproduce, environment, and a TDD-based Definition of Done checklist
  • Applies labels: bug, severity, and feature label (F1/F2/F3)
  • Assigns to the relevant milestone
  • Cross-links to Notion board card

Output: A labeled, milestone-assigned bug issue in GitHub + Notion board card.

/pm enhancement

Creates a structured enhancement request. In Full mode, creates both a GitHub issue and a Notion board card. In Light mode, creates a Notion board card only.

Usage: /pm enhancement "Add email notification when assessment report is ready"

What it does:

  • If no description provided, asks for one
  • Asks for: repo (Full mode), change type (existing behaviour or net-new), related milestone, priority (High / Medium / Low)
  • Flags enhancements that don't fit an existing milestone — may need a new milestone or PRD update
  • Creates a GitHub issue with: current behaviour, proposed behaviour, motivation, acceptance criteria, and Definition of Done checklist
  • Applies labels: enhancement, priority, and feature label
  • Assigns to the relevant milestone
  • Cross-links to Notion board card

Output: A labeled, milestone-assigned enhancement issue in GitHub + Notion board card.

/pm bughunt

A structured investigation workflow for troubleshooting and root-causing bugs. Full mode only.

Usage: /pm bughunt #55 or /pm bughunt "app crashes on form submit" or /pm bughunt (browse open bugs)

What it does:

  1. Identify — Fetches the bug from GitHub, or browses open bugs, or takes a description. Optionally creates a GitHub issue to track the investigation.

  2. Gather Evidence — Asks for error output, logs, reproduction steps, observability data, environment, and recent changes. Asks only what's relevant, not all at once.

  3. Investigate — Reproduces locally, traces the code path, forms hypotheses ranked by likelihood, and tests each one. Adds comments to GitHub after each hypothesis. Offers to pause after each hypothesis test.

  4. Root Cause — Presents findings with root cause, affected code, and fix approach. Options: fix it now (TDD), document it, assign to a team, or save & exit.

  5. Fix (if chosen) — Creates branch, writes failing test, commits, implements fix, runs full suite. All TDD.

Supports resuming — State saved to .claude/pm-state.json with full hypothesis history. Offers save & exit at every natural breakpoint.

Output: Root cause analysis, optionally a fix via PR, GitHub issue updated with findings.

Standards

All actions that create or resolve issues embed a strict Definition of Done:

  • Failing test written first and committed before any implementation (TDD Red)
  • Implementation written to make test pass (Green)
  • Code refactored while keeping tests green
  • Full test suite passes — no regressions
  • Happy path: 100% test coverage
  • Non-happy path: 100% target (edge cases can be lower, document exceptions)
  • Error states: 100% — every error state handled AND tested, no exceptions
  • No commented-out code
  • No hardcoded values — config or constants only
  • Every TODO references a GitHub issue number
  • Functions are single-responsibility
  • No issue = no work started, no exceptions
  • Merged via PR — issue closed on merge only, not before

Prerequisites

1. Claude Code CLI

Install from claude.ai/claude-code.

2. GitHub CLI

Install and authenticate the GitHub CLI:

brew install gh
gh auth login

Required for: bootstrap, next, status, bug, enhancement, bughunt.

3. Notion MCP Integration

The /pm skill uses Notion as its planning hub. All PRDs, TRDs, dashboards, and project boards live in Notion. GitHub handles execution (milestones, issues, code); Notion handles planning and status tracking.

Step 1 — Connect Notion to Claude Code

Enable the Notion MCP integration in your Claude Code settings. This gives Claude read/write access to your Notion workspace via MCP tools (notion-search, notion-create-pages, notion-update-page, notion-fetch, notion-create-database).

Step 2 — Create a PRDs database (or let /pm create do it)

On first run, /pm create will check for a PRD Database ID in your config. If none exists, it will offer to create the database for you in your Notion workspace.

If you prefer to create it manually, make a full-page Notion database with these properties:

Property Type Values
Name title PRD-NNN: Feature Name
Status select Draft, In Review, Approved, Shelved
Priority select P0 - Now, P1 - Next, P2 - Later, Shelved
Category select Internal Ops, Client Demo, GTM
GitHub Ready checkbox true / false
Status Dashboard URL (auto-populated by /pm create)

Step 3 — Save the database ID

Add the database ID to your ~/.claude/CLAUDE.md (for global access) or your project's CLAUDE.md (for per-project access):

## Notion

- PRD Database ID: your-database-id-here

To find the database ID: open the database in Notion as a full page, copy the URL. The ID is the 32-character hex string before the ?v= parameter:

https://www.notion.so/workspace/YOUR_DATABASE_ID?v=...

What Notion stores

Artifact Where Created by
PRD pages PRDs database /pm create
Project Status dashboard Child page of PRD /pm create
Project Board (stories) Inline database in dashboard /pm create
TRD pages Child page of PRD /pm trd
Story cards Project Board database /pm bootstrap

GitHub issues are cross-linked to Notion board cards. /pm status syncs live GitHub data back to the Notion dashboard.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v1.2.0 Latest
Mar 12, 2026

Packages

 
 
 

Contributors