piper-draft-spec
Skill8 starsChanged 11 days agoApache-2.0View on GitHub
Turn a rough idea, brief, or conversation into a properly-formed feature spec / PRD — with problem statement, goals, non-goals, user stories, requirements, open questions, and success criteria. Piper grounds the spec in your project context. Trigger phrases: "write a spec for", "draft a PRD", "spec this out", "write this up properly", "I want to build X".
In this repository39 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .cursor/rules/architecture-patterns.mdcCursor rule
- .cursor/rules/completion-discipline.mdCursor rule
- .cursor/rules/github-tracking.mdcCursor rule
- .cursor/rules/programmer-briefing.mdcCursor rule
- .cursor/rules/verification-first.mdcCursor rule
- ab-a-isolationSkill
- assign-sprint-safelySkill
- audit-cascadeSkill
- brief-coding-agentSkill
- check-mailboxSkill
- cleanup-dev-activeSkill
- close-issue-properlySkill
- cohort-attention-rollupSkill
- compost-reviewSkill
- continue-narrativeSkill
- create-omnibusSkill
- create-session-logSkill
- cut-releaseSkill
- delete-module-safelySkill
- deliver-mailSkill
- discovered-work-captureSkill
- doc-sync-sweepSkill
- draft-blog-postSkill
- draft-weekly-shipSkill
- duty-cycle-tickSkill
- narrative-verificationSkill
- piper-draft-issueSkill
- piper-sprint-planSkill
- piper-stakeholder-updateSkill
- piper-synthesize-feedbackSkill
- propose-featureSkill
- publish-to-blogSkill
- query-github-boardSkill
- template-auditSkill
- trust-checkSkill
- update-calendarSkill
- update-current-stateSkill
- update-piperSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 6 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 36
Start from whatever PM has: one sentence, a conversation, a rough list, a prototype description.
- Distinctive: line 48
Before drafting, pull what Piper knows that's relevant.
- Distinctive: line 54
If running natively (no server access): use conversation context + your knowledge of this PM's domain.
- Distinctive: line 69
Use the template below. Every section is mandatory — write "None identified" or "N/A" rather than leaving a section blank.
- Distinctive: line 207
Don't present the spec as final — present it as a working draft for PM's corrections.
- Very specific: line 213
If PM is using GitHub Issues: use piper-draft-issue to file each requirement chunk as an issue after the spec is approved.
- Distinctive: line 235
Before showing the spec to PM:
≈ “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
draft-spec
Turn a rough idea into a complete, reviewable feature spec — structured so engineers can build from it and stakeholders can approve it without a meeting.
The difference from just asking Piper: this skill produces a consistent output shape (every section present, every non-goal explicit, every open question surfaced) and grounds the spec in your project context (team patterns, current sprint, existing infrastructure) rather than writing a generic document.
When to Use
- PM has an idea and wants it written up properly before handing it to engineering
- You're planning a feature and want to flush out scope, non-goals, and open questions
- You need a shareable artifact for stakeholder review or team alignment
- You want to create GitHub issues from a spec (use
piper-draft-issuefor each requirement chunk after the spec is done)
Not for: quick one-off tasks (use piper-draft-issue directly). Not for architecture decisions (use ADR process). Not for bug fixes (use piper-draft-issue).
The Core Insight
A spec's most valuable sections aren't the requirements — they're the non-goals and open questions. Requirements tell engineers what to build; non-goals tell them what to push back on; open questions tell them where to stop and ask rather than guess. Most AI-generated specs skip both. Don't.
Procedure
Step 1 — Gather the brief
Start from whatever PM has: one sentence, a conversation, a rough list, a prototype description. Read it fully. Identify what's clear and what's ambiguous.
Ask PM for the following if not already known:
- Who is the primary user? (which persona, role, or segment)
- What's the one-sentence version of what changes for them?
- Are there constraints you know about? (tech debt, timeline, dependencies)
- Is there a milestone this belongs to?
Don't ask about things you can infer: if PM is talking about a PM feature, the user is probably a PM. If the conversation mentions a sprint, note the milestone. Keep the ask short — 1-3 questions max.
Step 2 — Load Piper context
Before drafting, pull what Piper knows that's relevant. If you have access to Piper's profile data:
- Current active projects and their state
- Team members and their roles
- Existing related features and how they work
- Current sprint focus and what's in flight
If running natively (no server access): use conversation context + your knowledge of this PM's domain. Note what you couldn't verify.
Step 3 — Generate the SLUG and title
SLUG = short uppercase hyphenated label for the feature area. 2–4 words, 15 chars max. Same convention as piper-draft-issue.
Examples:
- "Add AI-powered backlog triage" →
AI-TRIAGE - "Onboarding flow for first-time PMs" →
PM-ONBOARDING - "Weekly digest email" →
WEEKLY-DIGEST
Title format: SLUG — Full descriptive name
Step 4 — Draft the spec
Use the template below. Every section is mandatory — write "None identified" or "N/A" rather than leaving a section blank. Omissions make the spec look incomplete even when it isn't.
# SLUG — Full feature name
**Status**: DRAFT
**Author**: [PM name]
**Created**: [date]
**Milestone**: [MVP | Fast Follow | Post-MVP | Enterprise]
**Related issues**: [#N — title, or "None yet"]
---
## TL;DR
[One paragraph. What is this feature, who is it for, and why does it matter now?
Write this last — it's easier once the rest is done.]
---
## Problem
### Who has this problem?
[Specific user or persona — not "users" generically. E.g.: "First-time PMs who haven't used Piper before and don't know what to ask it."]
### What happens today?
[Concrete description of the current experience — what fails, what's missing, what workaround they use.]
### Why does it matter?
[Impact: what this costs the user or the product. Connect to a metric or outcome if you can.]
### Why now?
[What makes this the right time? Sprint focus, dependency unblocked, PM request, user signal.]
---
## Goals
### Primary goal
[One sentence: the change in user experience this spec delivers.]
### Secondary goals (optional)
- [Additional benefit 1]
- [Additional benefit 2]
---
## Non-goals
[What this spec explicitly does NOT cover. Be specific — "we're not building X" is more useful than silence on X. Every non-goal here prevents a scope conversation later.]
- ❌ [Thing that sounds related but is out of scope]
- ❌ [Follow-on feature that would naturally come next but isn't here]
- ❌ [Edge case that would add complexity without proportionate value]
---
## User stories
[2–5 stories in "As a [persona], I want to [action], so that [outcome]" form.
Keep them user-facing — not implementation steps.]
1. As a [persona], I want to [action], so that [outcome].
2. As a [persona], I want to [action], so that [outcome].
3. [etc.]
---
## Requirements
[Group by logical phase or area. Use checkboxes so these can become GitHub issue acceptance criteria directly.]
### [Area or Phase 1]
- [ ] [Specific, testable requirement — describes observable behavior, not implementation]
- [ ] [Specific, testable requirement]
### [Area or Phase 2]
- [ ] [Specific, testable requirement]
### Edge cases and error handling
- [ ] [What happens when X fails or is missing]
- [ ] [What happens with invalid input]
---
## Design notes
[Wireframes, UX flows, or key interaction decisions — or "None yet; PM/design team to drive." Don't block the spec on design; note what's known and what's open.]
---
## Technical notes
[Relevant existing infrastructure, dependencies, or known constraints — or "No constraints identified." Don't write implementation instructions here; write what engineers need to know to estimate and not hit surprises.]
- [Relevant existing service/component and how it connects]
- [Known dependency or constraint]
- [Or: "No constraints identified. Greenfield."]
---
## Open questions
[Every spec has questions. Surface them here rather than letting engineers discover them mid-build. Each question should have an owner and a "needed by" date if the spec has a timeline.]
| Question | Owner | Needed by |
|---|---|---|
| [Specific question that blocks or significantly changes scope] | [PM / CXO / Lead Dev] | [date or "before kick-off"] |
| [Another question] | [owner] | [date] |
---
## Success criteria
[How will you know this shipped successfully? Binary pass/fail — not "users like it." Prefer measurable or verifiable criteria.]
- [ ] [Observable outcome 1 — can be checked without user research]
- [ ] [Observable outcome 2]
- [ ] User can complete [key flow] without hitting an error
- [ ] [Metric or behavior that confirms the problem is solved]
---
## Out of scope (carry-forward)
[Features or edge cases that came up in discussions and were explicitly parked for a later spec. This is where "not now" goes so it's findable later.]
- [Feature or edge case] — [brief reason for deferral]
- [Or: "None identified"]Step 5 — Review with PM
Show the draft. Highlight:
- The non-goals you inferred (PM may want to pull some back in)
- The open questions you surfaced (who owns each one)
- Any requirements you flagged as high-complexity or risky
Don't present the spec as final — present it as a working draft for PM's corrections.
Step 6 — Create the artifact
Once PM approves, ask where they'd like to save it — or offer to paste the full spec as text they can copy into their preferred tool (doc, Notion, Confluence, etc.).
If PM is using GitHub Issues: use piper-draft-issue to file each requirement chunk as an issue after the spec is approved.
Format: Markdown is the default — it pastes cleanly into most tools and can become issues directly.
Anti-patterns to avoid
| Don't | Why | Instead |
| Write requirements as implementation steps | Locks engineers into a solution before they've seen the problem | Write observable behaviors ("user can do X") not methods ("system calls Y API") |
| Skip non-goals | Scope creep happens in the silence | Every obvious adjacent feature gets a ❌ in Non-goals |
| Leave open questions out | Engineers will guess wrong | Surface every unresolved question with an owner |
| Write TL;DR first | You don't know what you've decided yet | Write it last |
| Use vague success criteria ("users feel better") | Can't be verified | Binary, observable, ideally measurable |
| Pad requirements to look thorough | Noise drowns signal | 5 sharp requirements beat 15 vague ones |
| Write a spec for something that needs a 5-minute fix | Over-engineering | Use piper-draft-issue directly for simple, well-understood work |
Quality checklist
Before showing the spec to PM:
- SLUG and title are clear without reading the body
- TL;DR was written last and is accurate to the full spec
- Non-goals section has at least 2 items (if empty, you haven't thought hard enough)
- Open questions section surfaces real unknowns (not rhetorical)
- Every requirement is testable (binary pass/fail)
- Success criteria are observable without user research
- Out-of-scope section captures anything that came up and was parked
Example
Input (from conversation):
"We should have a way for Piper to send me a weekly digest — like a summary of what happened in my product that week. GitHub activity, maybe calendar if it's connected. Something I can read Monday morning."
Note: this example is drawn from Piper's own product development. Product-specific references (feature names, internal roles) are Piper's — substitute your product's equivalents when using this skill.
SLUG: WEEKLY-DIGEST
Draft spec:
# WEEKLY-DIGEST — Weekly product digest delivered Monday morning
**Status**: DRAFT
**Author**: xian
**Created**: 2026-06-15
**Milestone**: Fast Follow
**Related issues**: None yet
---
## TL;DR
A Monday-morning digest that surfaces the prior week's product activity — GitHub commits and closed issues, upcoming calendar items, and any Piper insights that accumulated. PM reads it in 2 minutes and knows where they stand without hunting through GitHub or calendar manually.
---
## Problem
### Who has this problem?
PMs who are context-switching between projects or coming back after weekend/holiday and need a quick re-orientation to what happened and what's coming.
### What happens today?
PM manually checks GitHub notifications, scans their calendar, and reviews Piper conversation history. There's no summary surface — it requires 10–15 minutes of active hunting each Monday.
### Why does it matter?
Monday context-switching is a high-friction moment. A well-timed digest means PM can make a pull request review decision or flag a stalled issue before their first meeting.
### Why now?
GitHub connector is being wired in Wave 1 (meet-piper + connect-piper). Once that's in place, the digest has its data source.
---
## Goals
### Primary goal
PM receives a concise Monday digest that covers GitHub + Calendar activity for the prior week without manual hunting.
### Secondary goals
- Establishes a touchpoint for Piper to proactively surface insights (Trust Gradient stage-gate)
- Creates a natural re-engagement hook for PMs who aren't using Piper daily
---
## Non-goals
- ❌ Real-time notifications or alerts (separate feature; delivery mechanism is different)
- ❌ Customizable digest templates or frequency (start with opinionated defaults)
- ❌ Integrations beyond GitHub and Calendar in v1 (Notion, Slack, Linear are follow-on)
- ❌ Digest archive or search (v1 is delivery only; no UI surface)
---
## User stories
1. As a PM, I want to receive a Monday digest in my Claude conversation, so that I can orient to the week without manually checking GitHub and Calendar.
2. As a PM, I want the digest to include closed issues and merged PRs from the past week, so that I know what shipped without reading every notification.
3. As a PM, I want the digest to include upcoming calendar events for the week, so that I can see what's on my plate alongside what shipped.
---
## Requirements
### Digest generation
- [ ] Piper generates a digest covering the 7-day window ending Sunday 11:59pm
- [ ] GitHub section: closed issues, merged PRs, new issues opened — grouped by repo
- [ ] Calendar section: events for the coming week (Mon–Sun), filtered to work calendars
- [ ] Insights section: any Piper insights that emerged in the prior week (if assistant has sufficient session context)
### Delivery
- [ ] Digest is delivered as a Piper message (in conversation, not email — v1)
- [ ] PM can trigger it manually ("send me my weekly digest") or it fires automatically Monday morning if a cron mechanism is available
- [ ] If a connector (GitHub, Calendar) is not wired, that section is omitted with a note ("Connect GitHub to include activity — run meet-piper to set up")
### Edge cases and error handling
- [ ] If no GitHub activity in the past week, say so rather than omitting the section
- [ ] If calendar integration is unavailable, omit gracefully with connector-setup note
---
## Design notes
None yet. Digest is text-only in v1 — no UI surface, no email template. Format: markdown sections with headers, brief bulleted lists, total <300 words.
---
## Technical notes
- Depends on: GitHub connector (meet-piper Wave 1), Calendar connector (meet-piper Wave 1 if wired)
- Data fetch: same enrichment layer as consult-piper, called on a Monday cron or user trigger
- Piper insights: read from session history and stored PM profile — included when enough context exists
---
## Open questions
| Question | Owner | Needed by |
|---|---|---|
| Is Monday delivery via cron or manual trigger only in v1? | xian | Before kick-off |
| Which calendar provider(s) are in scope for v1 — Google only, or also Outlook? | xian | Before kick-off |
| Does the digest go into the main conversation thread or a dedicated channel? | PM/design lead | Before design |
---
## Success criteria
- [ ] PM can request "send me my weekly digest" and receive a correctly structured digest
- [ ] GitHub section accurately reflects closed issues and merged PRs from the prior 7 days
- [ ] If no connectors are wired, digest gracefully degrades with connector-setup prompts
- [ ] Digest reads in under 2 minutes (length check: ≤300 words)
---
## Out of scope (carry-forward)
- Email delivery — v2; v1 is in-conversation only
- Custom frequency (bi-weekly, daily) — start with weekly; let usage data drive
- Digest archive — no UI surface in v1Changelog
- v1.0 (2026-06-15): Initial version.
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.

