pm-plan
Skill2 starsChanged 8 months agoMITView on GitHub
Plan new work by creating issues or feature requests from a natural language description. Researches the domain online, analyzes the codebase for context, and decomposes complex descriptions into multiple entities when sensible. Use when the user describes work needed, a bug to fix, a feature to add, or says things like "we need...", "there's a problem with...", "I want to add...", "plan out...", or "let's track...". Also triggers for vague requests that need clarification before becoming actionable work items.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- navjyotnishant/nj-agentstheir own version, first seen Oct 15, 2026
- pmatos/skillstheir own version, first seen Jul 2, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- pmatos/skills★ 2same name
- navjyotnishant/nj-agents★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository15 other files it gives its agents.
- pm-auditSkill
- pm-brainstormSkill
- pm-cleanupSkill
- pm-codesmellsSkill
- pm-doneSkill
- pm-exploreSkill
- pm-housekeepingSkill
- pm-implementSkill
- pm-nextSkill
- pm-refine-frSkill
- pm-scaffoldSkill
- pm-statusSkill
- pm-triageSkill
- pm-troubleshootSkill
- pm-verifySkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
21 rules. About 0 are common, 12 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈12
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 21
Call mcp__pinkrooster__get_project_status with projectPath set to the directory above
- Distinctive: line 23
If no project found, offer to register it first
- Distinctive: line 27
Before asking questions or creating anything, build context from two sources:
- Very specific: line 40
Use Grep/Glob to find files related to $ARGUMENTS
- Very specific: line 48
Call mcp__pinkrooster__get_issue_overview with projectId and stateFilter: "Active" + "Inactive"
- Distinctive: line 52
If a closely matching item already exists, surface it to the user before creating anything new.
- Very specific: line 69
Use WebSearch with targeted queries about the technology/pattern
- Very specific: line 70
Use WebFetch to pull relevant documentation pages
- Distinctive: line 97
If the user selects "Adjust", ask what they'd like to change and iterate.
- Very specific: line 149
After classification but before creation, check if anything important is missing or ambiguous.
- Distinctive: line 162
If the description is clear and specific, skip this step entirely.
- Distinctive: line 206
Before each create call, check against the deduplication list from Step 2.
- Very specific: line 212
Use the AskUserQuestion tool to confirm:
- Very specific: line 242
Use the AskUserQuestion tool:
- Distinctive: line 247
If single item: offer Scaffold, Refine (FR only), or Done
- Distinctive: line 248
If multiple items: offer "Scaffold first item", "Triage all", or Done
- Distinctive: line 257
Always confirm classification before creating entities — the user should see what's about to be created
- Distinctive: line 260
When decomposing, each item should be independently meaningful — don't create items that only make sense together
- Distinctive: line 262
Never create entities without first checking for duplicates
- Distinctive: line 263
Prefer updating existing items over creating new ones: when there is overlap — fragmented tracking is worse than a comprehensive single item
- Very specific: line 265
If the project has many open items, suggest /pm-triage after creation to help prioritize
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Plan Work from Description
Transform a natural language description into well-structured tracking entities (issues and/or feature requests). The goal is to produce entities that are detailed enough for /pm-scaffold to generate realistic work packages from — so invest in understanding the problem space before creating anything.
Step 1: Resolve Project
- Current directory: !
pwd - Call
mcp__pinkrooster__get_project_statuswithprojectPathset to the directory above - Extract the
projectId - If no project found, offer to register it first
Step 2: Understand What Already Exists
Before asking questions or creating anything, build context from two sources:
2a: Codebase Analysis (proportional to complexity)
Calibrate the depth of exploration to the request:
Simple bug reports (clear error message, known location, reproduction steps): Quick lookup — a single Grep/Glob to confirm the affected file exists. Spend under a minute here. The goal is just to populate affectedComponent accurately, not to diagnose the root cause.
Moderate requests (CRUD addition, extend existing feature): Targeted exploration — find the existing pattern to follow, note the relevant files and conventions. A few Grep/Glob calls.
Complex features (new system, integration, cross-cutting concern): Deep exploration — understand the relevant architectural layers, existing infrastructure that can be reused, and how the feature fits into the current design. Use Grep/Glob and Read to trace through related code.
In all cases:
- Use Grep/Glob to find files related to
$ARGUMENTS - Identify what already exists — existing implementations inform classification and description quality
- Note patterns, conventions, and layers involved
2b: Existing Tracked Items
Load current items to avoid duplicates and understand project context:
- Call
mcp__pinkrooster__get_issue_overviewwithprojectIdandstateFilter: "Active"+"Inactive" - Call
mcp__pinkrooster__get_feature_requestswithprojectIdandstateFilter: "Active"+"Inactive" - Compile a deduplication list of names, descriptions, and states
If a closely matching item already exists, surface it to the user before creating anything new.
Step 3: Research the Domain
For non-trivial work — especially new features, integrations, or unfamiliar domains — use online research to inform the planning. This produces better descriptions, more accurate scoping, and catches edge cases early.
When to research:
- The description mentions a technology, library, or integration you should verify (e.g., "add OAuth support", "export to Parquet", "integrate with Stripe")
- The work involves patterns or best practices worth confirming (e.g., "add rate limiting", "implement RBAC")
- The user's description is vague about implementation and external context could help clarify options
When to skip:
- Pure bug reports with clear reproduction steps
- Simple CRUD additions following existing patterns
- Work that's entirely internal to the existing codebase
How to research:
- Use
WebSearchwith targeted queries about the technology/pattern - Use
WebFetchto pull relevant documentation pages - Synthesize findings into actionable context that improves the entity descriptions
Fold research findings into the entity description — mention relevant libraries, standards, common pitfalls, or architectural considerations discovered.
Step 4: Decompose into Work Items
Analyze $ARGUMENTS and determine whether this is a single item or multiple distinct items.
Signals that work should be decomposed:
- Conjunctions connecting distinct capabilities: "add X and Y", "we need A, B, and C"
- Different affected areas: "fix the login page and add export to the dashboard"
- Mixed types: description contains both bugs and features
- Large scope with natural boundaries: "add a notification system" might decompose into "notification infrastructure", "email notifications", "in-app notifications"
Signals to keep as one item:
- Tightly coupled changes that don't make sense independently
- Single capability described from multiple angles
- Small scope even if touching multiple files
If decomposing, present the breakdown to the user for confirmation before creating anything. Use the AskUserQuestion tool:
- Question: "I see {N} distinct items in this description. Here's how I'd break them down:\n\n{numbered list with type and name for each}\n\nDoes this look right?"
- Header: "Work breakdown"
- Options:
[{label: "Create all", description: "Create all {N} items as described"}, {label: "Adjust", description: "Let me modify the breakdown first"}, {label: "Keep as one", description: "Create a single item instead"}]
If the user selects "Adjust", ask what they'd like to change and iterate.
Step 5: Classify Each Item
For each item (whether single or decomposed), determine the type:
Issue indicators (create an Issue):
- Bug, defect, broken, error, crash, regression, failing, wrong, incorrect
- Performance: slow, timeout, latency, memory leak, high CPU
- Security: vulnerability, CVE, injection, XSS, auth bypass
- Technical debt: refactor, cleanup, deprecated, legacy
Feature Request indicators (create a Feature Request):
- Feature, add, new, enhance, improve, support, enable, implement
- User stories: "as a...", "I want...", "we need..."
- Capabilities: dashboard, page, export, import, notification, integration
If ambiguous, use the AskUserQuestion tool:
- Question: "Is '{itemName}' a bug/issue to fix, or a new feature/enhancement?"
- Header: "Work type"
- Options:
[{label: "Bug/Issue", description: "Something broken, slow, or insecure"}, {label: "Feature/Enhancement", description: "A new capability or improvement"}]
Map to specific types
Issue types:
- Bug/broken/error/crash → IssueType:
Bug - Regression/was-working → IssueType:
Regression - Slow/timeout/performance → IssueType:
PerformanceIssue - Security/vulnerability → IssueType:
SecurityVulnerability - Refactor/cleanup/debt → IssueType:
TechnicalDebt
Feature categories:
- New capability → FeatureCategory:
Feature - Extends existing → FeatureCategory:
Enhancement - Makes existing better → FeatureCategory:
Improvement
Map severity (issues only)
- Crash, data loss, security breach →
Critical - Broken functionality, major regression →
Major - Cosmetic, minor inconvenience →
Minor - Typo, trivial cosmetic →
Trivial
Map priority (all entities)
- Urgent, ASAP, critical, blocker →
Critical - Important, should, high →
High - Would be nice, eventually →
Low - Default →
Medium
Step 6: Clarify Gaps
After classification but before creation, check if anything important is missing or ambiguous. Ask concisely — combine related questions into a single AskUserQuestion call rather than asking one at a time.
Worth clarifying:
- Scope ambiguity: "improve the dashboard" → which aspect? Performance? UI? New features?
- Boundary ambiguity: "add export" → which entities? What formats? Where in the UI?
- Audience ambiguity: "make it easier to use" → for whom?
- Priority conflicts: description mixes urgency levels
Not worth asking about:
- Implementation details that
/pm-scaffoldwill figure out from the codebase - Fields that can be reasonably inferred from context
- Things the user clearly specified already
If the description is clear and specific, skip this step entirely.
Step 7: Confirm Before Creating
Present the full plan using the AskUserQuestion tool:
For a single item:
- Question: "Create {type} '{name}' with {priority} priority?"
- Header: "Confirm"
- Options:
[{label: "Create", description: "Proceed"}, {label: "Adjust", description: "Change something first"}, {label: "Cancel", description: "Don't create"}]
For multiple items:
- Question: "Create the following {N} items?\n\n{numbered list with type, name, and priority for each}"
- Header: "Confirm ({N} items)"
- Options:
[{label: "Create all", description: "Create all {N} items"}, {label: "Select", description: "Let me pick which ones to create"}, {label: "Cancel", description: "Don't create anything"}]
Step 8: Create Entities
For Issues
Call mcp__pinkrooster__create_or_update_issue with:
projectIdname: concise, descriptive titledescription: comprehensive description incorporating codebase context and research findings. Include: what's wrong, where it manifests, impact, and any relevant technical context discovered during analysisissueType: mapped typeseverity: mapped severitypriority: mapped priorityaffectedComponent: if identifiable from codebase analysisstepsToReproduce: if the description includes or implies reproduction steps
For Feature Requests
Call mcp__pinkrooster__create_or_update_feature_request with:
projectIdname: descriptive title following pattern{Feature}: {qualifier}description: comprehensive specification incorporating research findings. Include: what the feature does, why it matters, how it fits with existing functionality, and any technical considerations discoveredcategory: mapped categorypriority: mapped prioritybusinessValue: derived from the "why" — who benefits and what becomes possibleuserStories: array of structured stories extracted from the description[{"role": "...", "goal": "...", "benefit": "..."}]. Derive 2-4 stories covering distinct user roles or capabilities. Make them concrete and specific.requester: "Claude Code" (or user name if known)
Duplicate and Overlap Handling
Before each create call, check against the deduplication list from Step 2.
Exact duplicate (same bug, same feature, same scope): Do not create a new entity. Surface the existing item to the user and suggest next steps (scaffold, refine, or update it).
Partial overlap (existing item covers part of the scope, or the new request expands on it): Prefer updating the existing entity over creating a new one. Call the update endpoint with projectId + the existing entity's ID + expanded fields. This avoids fragmentation — one well-maintained item is better than two overlapping ones.
Use the AskUserQuestion tool to confirm:
- Question: "Found {existingId} '{existingName}' ({state}) which overlaps with this request. How should I handle it?"
- Header: "Overlap found"
- Options:
[{label: "Update existing", description: "Expand {existingId} with the new details (recommended)"}, {label: "Create new", description: "Create a separate item — the scope is different enough"}, {label: "Skip", description: "The existing item already covers this"}]
No match: Proceed silently.
Step 9: Report Results
## Created {count} Item(s)
| # | Type | ID | Name | Priority |
|---|------|----|------|----------|
| 1 | {Issue/FR} | {entityId} | {name} | {priority} |
| ... |
### Research Applied
- {key finding 1 from online research, if any}
- {key finding 2, if any}
### Next Steps
- **Refine** (FRs): `/pm-refine-fr {frId}` — add user stories and detail
- **Scaffold**: `/pm-scaffold {entityId}` — create implementation work package
- **Triage**: `/pm-triage` — review priorities across all items
- **Status**: `/pm-status` — project overviewStep 10: Offer Next Steps
Use the AskUserQuestion tool:
- Question: "What would you like to do next?"
- Header: "Next step"
Build options based on what was created:
- If single item: offer Scaffold, Refine (FR only), or Done
- If multiple items: offer "Scaffold first item", "Triage all", or Done
If Scaffold: Delegate to /pm-scaffold {entityId}
If Refine: Delegate to /pm-refine-fr {frId}
If Triage: Delegate to /pm-triage
If Done: Close with a summary of entity IDs for future reference
Constraints
- Always confirm classification before creating entities — the user should see what's about to be created
- Derive as much structured data as possible from natural language — don't leave fields empty when they can be inferred
- Report all entity IDs prominently so the user can reference them
- When decomposing, each item should be independently meaningful — don't create items that only make sense together
- Fold research findings into entity descriptions rather than keeping them separate
- Never create entities without first checking for duplicates
- Prefer updating existing items over creating new ones when there is overlap — fragmented tracking is worse than a comprehensive single item
- Proportional effort is critical: a bug report with clear reproduction steps should take under 30 seconds of analysis (quick file lookup, create issue, done). Reserve deep codebase exploration and online research for complex features and integrations. The user should not wait 3 minutes for a simple bug to be logged.
- If the project has many open items, suggest
/pm-triageafter creation to help prioritize
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

