Pr Plan
Turn open-source repo research into a dated PR contribution plan with scope, targets, risks, and acceptance criteria before you write code.
Overview
PR Plan is an agent skill most often used in Build (also Ship review prep and Idea-style repo research follow-up) that turns pr-research into an actionable open-source contribution plan file.
Install
npx skills add https://github.com/boshu2/agentops --skill pr-planWhat is this skill?
- Seven-step workflow from input discovery through scope, targets, criteria, risk, strategy, and plan file output
- Consumes pr-research output and writes `.agents/plans/YYYY-MM-DD-pr-plan-{repo-slug}.md`
- Explicit when-NOT-to-use guardrails (no research yet, trivial typos, internal planning)
- Practices agile-manifesto, ADR, and lean-startup framing for contribution strategy
- Requires git and GitHub CLI (`gh`) for fork-window open-source context
- 7-step workflow from input discovery through strategy and plan output
- Output path pattern `.agents/plans/YYYY-MM-DD-pr-plan-{repo-slug}.md`
Adoption & trust: 599 installs on skills.sh; 384 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You finished researching an OSS repo but lack a scoped contribution plan with targets, acceptance criteria, and risks before you start coding the PR.
Who is it for?
Solo builders preparing a non-trivial open-source PR after structured repo research and before touching the fork.
Skip if: Contributors who have not run pr-research, one-line typo fixes, or internal product roadmaps that should use the generic plan skill instead.
When should I use this skill?
After completing pr-research, when planning contribution strategy, and before starting implementation on an open-source fork.
What do I get? / Deliverables
You get a dated `.agents/plans/YYYY-MM-DD-pr-plan-{repo-slug}.md` artifact you can execute against and hand to your agent for implementation.
- Dated PR plan markdown under `.agents/plans/`
- Structured scope, targets, criteria, risk, and strategy sections
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Build because the artifact is an implementation-ready contribution plan that bridges research and coding on an external repo. PM subphase fits strategic planning deliverables (scope, targets, criteria, risks) rather than a single integration or test task.
Where it fits
After pr-research on a library you depend on, lock which issues and areas are worth addressing before you allocate build time.
Produce the dated pr-plan markdown with scope and strategy so your agent implements against explicit acceptance criteria.
Use the plan’s criteria section to self-review the branch before opening the PR with gh.
How it compares
Use instead of jumping from research notes straight into implementation without acceptance criteria or risk review.
Common Questions / FAQ
Who is pr-plan for?
Solo and indie builders—and small teams—who use Claude Code, Cursor, or Codex to contribute to open source and want a formal plan artifact before implementation.
When should I use pr-plan?
Use it in Build / PM right after pr-research when scoping an OSS contribution; also when aligning Ship / review expectations from research-derived criteria; not for trivial edits or internal-only planning.
Is pr-plan safe to install?
It allows Read, Write, Bash, Grep, and Glob against your workspace and expects git and gh—review the Security Audits panel on this page and restrict repo access before running Bash.
Workflow Chain
Requires first: pr research
SKILL.md
READMESKILL.md - Pr Plan
# PR Plan Skill Strategic planning for open source contributions. ## Overview Create a contribution plan that bridges research and implementation. Takes `$pr-research` output and produces an actionable plan. **Output:** `.agents/plans/YYYY-MM-DD-pr-plan-{repo-slug}.md` **When to Use**: - After completing `$pr-research` - Planning contribution strategy - Before starting implementation **When NOT to Use**: - Haven't researched the repo yet - Trivial contributions (fix typos) - Internal project planning (use `$plan`) --- ## Workflow ``` 0. Input Discovery -> Find/load pr-research artifact 1. Scope Definition -> What exactly to contribute 2. Target Selection -> Which issues/areas to address 3. Criteria Definition -> Acceptance criteria from research 4. Risk Assessment -> What could go wrong 5. Strategy Formation -> Implementation approach 6. Output -> Write plan artifact ``` --- ## Phase 1: Scope Definition ### Scope Questions | Question | Why It Matters | |----------|----------------| | What specific functionality? | Clear deliverable | | Which files/packages? | Limits impact surface | | What's explicitly out of scope? | Prevents scope creep | | Single PR or series? | Sets expectations | ### Scope Template ```markdown ## Scope **Contribution**: [1-2 sentences describing the change] **Affected Areas**: - `path/to/file.go` - [what changes] **Out of Scope**: - [Related but excluded work] ``` --- ## Phase 3: Acceptance Criteria Define success from maintainer perspective: ```markdown ## Acceptance Criteria ### Code Quality - [ ] Follows project coding style - [ ] Passes existing tests - [ ] Adds tests for new functionality - [ ] No linting warnings ### PR Requirements - [ ] Title follows convention - [ ] Body uses project template - [ ] Size within acceptable range - [ ] Single logical change ### Project-Specific - [ ] [Any project-specific requirements from research] ``` --- ## Phase 4: Risk Assessment | Risk | Likelihood | Impact | Mitigation | |------|------------|--------|------------| | PR review takes > 2 weeks | Medium | Medium | Start small, be responsive | | Scope expands during review | Medium | High | Define scope clearly upfront | | Breaking change discovered | Low | High | Test against multiple versions | --- ## Phase 5: Implementation Strategy ```markdown ## Implementation Strategy ### Approach 1. **Setup**: Fork repo, configure dev environment 2. **Understand**: Read existing code in affected area 3. **Implement**: Make changes following project patterns 4. **Test**: Run existing tests + add new tests 5. **Document**: Update any affected documentation 6. **Submit**: Create PR following project conventions ### Pre-Implementation Checklist - [ ] Fork created and up-to-date with upstream - [ ] Dev environment working - [ ] Issue claimed or comment posted - [ ] Recent repo activity reviewed ``` --- ## Output Template Write to `.agents/plans/YYYY-MM-DD-pr-plan-{repo-slug}.md` ```markdown # PR Plan: {repo-name} ## Executive Summary {2-3 sentences: what you're contributing, why, expected outcome} ## Scope **Contribution**: {description} **Affected Areas**: [list] **Out of Scope**: [list] ## Target **Primary Issue**: #{N} - {title} ## Acceptance Criteria [checklist] ## Risk Assessment [table] ## Implementation Strategy [numbered steps] ## Next Steps 1. Claim/comment on target issue 2. Fork and set up deve