How do I install the Spec To Repo skill?

Run npx skillmds add majiayu000/spec-to-repo in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Spec To Repo skill do?

Translate product specs (PRDs, user stories) into a ship-ready repo plan: ticket decomposition, branch strategy, and PR sequencing. Use when breaking a PRD into tickets or designing the branch/PR sequence. It is listed under Product & Planning on SkillMD.

Is Spec To Repo safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Spec To Repo?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Spec To Repo free to use?

Yes. Installing skills from SkillMD is free. This skill is licensed under MIT + Commons Clause.

Who published Spec To Repo?

majiayu000 (@majiayu000) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Spec To Repo by majiayu000 — Agent Skill

Name: Spec To Repo
Rating: 4.2 (5 reviews)
Author: majiayu000

Spec to Repo

A delivery-focused skill that bridges product spec to repository work. Where PRD-writing skills focus on what to build, this skill focuses on how to break it down for execution — the ticket decomposition, branch strategy, PR sequencing, and acceptance criteria that make a spec actually ship.

When to use this skill

Translating a PRD or feature brief into a sequence of tickets
Designing the branch + PR sequence for a multi-week feature
Auditing an existing ticket decomposition for risk (big tickets, hidden dependencies)
Defining definition-of-done that covers code, tests, docs, telemetry
Planning incremental shipping (feature flags, canaries, dark-launch)
Reviewing a decomposition before sprint planning to avoid mid-sprint surprises

Inputs the advisor expects

The PRD or spec document
Target ship window (1 sprint? 1 month? 1 quarter?)
Engineering team size + composition (FE, BE, ML, mobile)
Risk profile (greenfield vs production-impacting)
Feature-flag and rollout posture

Clarify First

Before generating the repo plan, confirm these inputs. If any is unknown or vague, ASK — do not assume:

The PRD or spec — the user-facing capabilities to decompose (drives the epic→ticket tree)
Target ship window — one sprint, month, or quarter (drives ticket sizing and PR sequencing)
Team composition — FE, BE, ML, mobile (decides parallel paths and vertical-slice tickets)
Feature-flag and rollout posture — flagged/dark-launch vs direct ship (drives PR sequencing and definition-of-done)

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.

Workflows

Workflow 1 — Decompose a PRD into tickets

Pull the PRD; identify the user-facing capabilities.
Run prd_to_tickets_decomposer.py with the user stories + technical notes to surface a candidate ticket tree (epic → tickets → subtasks) with size estimates and dependencies.
Manually review; tune for team-specific patterns.

python3 spec-to-repo/scripts/prd_to_tickets_decomposer.py \
  --input prd.json --format markdown

Workflow 2 — Validate the branch and PR plan

Capture proposed branch + PR sequence.
Run pr_scope_analyzer.py to flag oversized PRs, missing tests, missing telemetry, and risky merges.
Adjust before opening PRs.

python3 spec-to-repo/scripts/pr_scope_analyzer.py \
  --input pr_plan.json --format markdown

Workflow 3 — Lint branch names against convention

Capture branch list (e.g., git branch --list).
Run branch_naming_validator.py to flag non-conformant names.

python3 spec-to-repo/scripts/branch_naming_validator.py \
  --input branches.txt --format markdown

Decision frameworks

Ticket sizing

Size	Effort	Description
XS	< 0.5 day	Trivial; usually skip ticketing
S	0.5–1 day	One simple change
M	1–3 days	Single feature, well-scoped
L	3–5 days	Multi-day work; should split if possible
XL	> 5 days	Always split — too big for confident estimate

A ticket that's L or XL almost always hides a missing decomposition. Push back on yourself.

The ticket tree

Epic — large product feature ("Notifications v2")
├── Story — user-facing capability ("As a user I can mute by channel")
│   ├── Ticket — one engineering work item (backend, frontend, infra)
│   │   └── Subtask — atomic step (optional)

Most orgs:

Epic ≈ PRD-sized scope
Story ≈ one user-facing slice
Ticket ≈ one PR (or pair of PRs: BE + FE)

The "vertical slice"

Best ticket: ships a small user-visible improvement end-to-end.

Backend change + frontend change + tests + telemetry + docs in one ship
Better than: BE-only ticket waiting for FE-only ticket waiting for QA

When you can't slice vertically (e.g., backend is weeks before frontend):

Use feature flags to ship behind a switch
Dark-launch backend to validate before frontend
Communicate the lag explicitly

PR sequencing

For a multi-PR feature:

PR 1 — Infrastructure / scaffolding (no behavior change)
PR 2 — Backend changes (behind flag; no frontend uses it)
PR 3 — Frontend changes (behind flag; tests pass with flag on/off)
PR 4 — Telemetry + analytics events
PR 5 — Documentation + runbook
PR 6 — Flag enablement (small change; reviewable cleanly)

Each PR < 400 lines if possible. Reviewability collapses above 400.

Definition of done

Per ticket:

Code: written, reviewed, merged
Tests: unit + integration as appropriate
Telemetry: events fired (and verified)
Docs: README / runbook / API doc updated as needed
Accessibility: meets the project bar
Feature flag: configured (if applicable)
Rollout plan: defined for non-flagged ships

Per epic:

All tickets complete
Feature behind flag in production for 1+ week (if risky)
Flag enabled for X% (canary), then ramped
Telemetry shows expected behavior
Customer-facing comms drafted (if applicable)

Common engagements

"Help me decompose this PRD"

List user-facing capabilities (1-line each).
For each, list the backend, frontend, infra, telemetry, docs work.
Estimate; flag anything > 3 days for further breakdown.
Sequence: scaffolding first, behavior next, flag enablement last.
Identify cross-team dependencies; engage before sprint start.

"Our team is shipping huge PRs"

Audit the last 10 PRs: median size, P95 size.
Identify the patterns: monolithic services + flag-less work + slow review.
Pilot: feature flags + ticket-first decomposition + PR size SLA.
Track: median PR size + lead time week-over-week.

"Help me plan the rollout"

Define a successful launch criterion (e.g., < 0.5% error rate at 50%).
Identify the kill switch (feature flag or quick-revert).
Plan ramps: 1% → 5% → 25% → 50% → 100% with bake time.
Define rollback criteria + comms plan.
Coordinate with on-call + support.

Anti-patterns to avoid

Decomposition as wishful thinking. "3-day estimate" with no break-down is a 2-week-actual.
Sequential ticket tree (everyone waits). Plan parallel paths.
Hidden dependencies on other teams. Surface them in decomposition.
No feature flag. Shippable in chunks but every change goes to all users immediately.
PRs > 1000 lines. Reviewability dies; bugs hide.
DoD that's just "code merged." Forgets tests, docs, telemetry.
Ticket = a day of work. Sometimes tickets are 30 minutes; sometimes 3 days.

References

references/spec-to-ticket-decomposition.md — patterns for breaking specs into tickets
references/branch-strategy-for-features.md — branching, feature flags, dark-launch
references/pr-discipline-and-conventions.md — PR size, review, definition-of-done

Related skills

product-team/agile-product-owner — sprint planning, prioritization
engineering/feature-flags-architect — flag strategy
engineering/observability-designer — SLO / telemetry
c-level-advisor/vpe-advisor — broader delivery context
project-management/ skills — ticket / sprint management tooling

Spec To Repo

File contents