From ralph-cc
Generate the next sprint from the PRD, backlog, tech debt, or GitHub Issues — detects completed features, picks the next chunk of work, and builds user stories with minimal user input
How this skill is triggered — by the user, by Claude, or both
Slash command
/ralph-cc:new-sprintThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Creates a new `scripts/ralph/prd.json` by reading the PRD, backlog, tech debt, and (when `Github.enabled`) open GitHub Issues, detecting what's already been built. The user should only need to confirm or tweak — not describe features from scratch.
Creates a new scripts/ralph/prd.json by reading the PRD, backlog, tech debt, and (when Github.enabled) open GitHub Issues, detecting what's already been built. The user should only need to confirm or tweak — not describe features from scratch.
Before anything else, check that RALPH.md exists in the project root and has Documents.prd defined with a non-empty path.
"No RALPH.md found. Run
/ralph-initto set up ralph in this project."
"No PRD found. Run
/prd-planto create one."
"PRD file not found at
[path]. Run/prd-planto create one, or update the path in RALPH.md."
Once validated, read all paths from RALPH.md and capture settings:
Audit.mode — off | sprint-close | per-story (default sprint-close)Github.enabled — true | false (default false)Proceed.
Silently read all of these:
Github.enabled): run
gh issue list --state open --label "enhancement" --json number,title,body,labels,createdAt --limit 50
gh issue list --state open --label "bug" --json number,title,body,labels,createdAt --limit 50
gh issue list --state open --label "tech-debt" --json number,title,body,labels,createdAt --limit 50
If gh is not installed or auth fails, warn the user once and continue without GitHub data.scripts/ralph/archive/ to see completed featuresscripts/ralph/prd.json — current sprint (may be complete or in-progress)scripts/ralph/progress.txt — the "Codebase Patterns" section at the top for implementation contextCLAUDE.md — tech stack, project structure, key patterns (if exists)AGENTS.md — codebase conventions (if exists)Build a mental map of all sources:
PRD features:
Parse the PRD for feature sections dynamically. Look for ## N. or ### N.N headings under the Features section. Each numbered feature section is a potential sprint source.
| PRD Section | Feature | Sprint Status |
|---|---|---|
| [N.1] | [Feature name] | Check archive for matching sprint IDs |
| [N.2] | [Feature name] | Check archive/current |
| ... | ... | ... |
Backlog items:
If the backlog file exists, parse each section heading. Check the **Status:** field — items that say "Complete" or "Done" are finished. Everything else is available.
Tech debt:
If the tech debt file exists, parse the active items. Each typically has an ID (TD-NNN), severity (High/Medium/Low), and effort (Trivial/Small/Medium/Large). Items in "Resolved Items" are already fixed.
GitHub Issues (when Github.enabled):
| Type | # | Title | Priority | Source label |
|---|---|---|---|---|
| bug | #N | ... | P0/P1/P2 | user-feedback / agent-audit |
| enhancement | #N | ... | P0/P1/P2 | ... |
| tech-debt | #N | ... | P0/P1/P2 | ... |
Deduplicate GitHub tech-debt issues against the local tech debt file.
Present all sources to the user. Show what's available from each:
## Sprint Sources
### PRD Features
- Completed: [list completed features]
- In Progress: [current sprint feature, if any]
- Next up: **[Section N.N: Feature Name]** (or "All v1 features complete")
- Later: [features marked as "later" or post-v1, if any]
### Backlog
[If no backlog file or empty: "No backlog items" and skip.]
- Completed: [list completed items]
- Available: [list items where Status != Complete/Done]
### Tech Debt
[If no active items: "No active tech debt" and skip.]
- **Can fold into next sprint** (Trivial/Small): [list TD-IDs + titles]
- **Could be its own sprint** (Medium/Large): [list TD-IDs + titles, with severity noted]
### GitHub Issues (when Github.enabled)
- P0: [list any P0-critical items]
- P1: [list P1-important items]
- P2: [list P2-nice-to-have items]
Trivial/Small tech debt items don't get their own sprint option — they're noted as things that can be folded into whatever sprint is selected.
Present options to the user with the recommendation:
Multiple issues as one sprint: the user might want to combine related GitHub Issues into a single sprint (e.g., "fix all P1 bugs" or "do enhancement #12 and #15 together"). Support this — sourceIssues can list multiple numbers.
Ask: "Which one should we sprint on?"
If scripts/ralph/prd.json exists and has stories:
Count completed vs total stories
If incomplete stories remain, warn the user:
"This sprint has [N] incomplete stories out of [total]. Archive anyway?"
Wait for confirmation. If declined, stop — they may want to finish the current sprint first.
If confirmed or all stories are complete, archive:
DATE=$(date +%Y-%m-%d)
FEATURE=$(echo "[branchName from prd.json]" | sed 's|^[^/]*/||')
ARCHIVE_DIR="scripts/ralph/archive/$DATE-$FEATURE"
if [ -d "$ARCHIVE_DIR" ]; then
COUNTER=2
while [ -d "${ARCHIVE_DIR}-${COUNTER}" ]; do
COUNTER=$((COUNTER + 1))
done
ARCHIVE_DIR="${ARCHIVE_DIR}-${COUNTER}"
fi
mkdir -p "$ARCHIVE_DIR"
cp scripts/ralph/prd.json "$ARCHIVE_DIR/"
cp scripts/ralph/progress.txt "$ARCHIVE_DIR/"
After archiving, reset progress.txt with a fresh header (preserve the Codebase Patterns section from the old progress.txt at the top — those patterns carry forward).
Based on the selected source, extract the details needed to write stories.
Read the specific PRD feature section in detail. Extract:
Read the specific backlog item. Extract:
Read the full issue with gh issue view [NUMBER]. Extract:
Read the specific tech debt item (from docs/tech-debt.md or from a GitHub Issue labeled tech-debt). Extract description, severity/effort, affected files, fix approach.
Also read:
progress.txt Codebase Patterns sectionBefore writing stories, explore the codebase to understand current patterns relevant to the sprint. Use Grep/Glob/Read to find files that will be created or modified, existing patterns to follow, dependencies between components.
If there are Trivial or Small effort tech debt items that relate to the sprint feature area, fold them into the sprint as additional stories or extra acceptance criteria. Mention this to the user.
e2e_single, set testFlow for stories that create new screens or user-facing flows; null for backend-only stories or refactors. If e2e_single is not configured, always set testFlow to null.[branch_prefix from RALPH.md][kebab-case-feature-name]Acceptance criteria are objects: { "text": string, "humanGated"?: boolean }. Legacy string-form ACs are still accepted (treated as humanGated: false), but always emit the object form for new sprints.
When to set humanGated: true: ACs the auditor cannot verify alone — the operator must take action on a system the coding agent can't reach. Examples:
When the auditor encounters these ACs it will (a) audit every non-humanGated AC immediately, (b) mark the humanGated ones PENDING (human-gated), (c) verdict becomes PASS-PENDING-HUMAN. The lead surfaces the exact AC text and waits for confirmation before flipping passes: true.
Default to humanGated: false. Only set true when the AC genuinely cannot be verified without the human. Code-verifiable ACs (typecheck, lint, test, file presence, exact text in source) are NOT humanGated even if you mention "verify in browser" — E2E flows handle UI verification.
Do not emit a wrapPoints array. Wrap timing is no longer planned at PRD-authoring time — story-clustering was a guess at future context burn. /start decides live, in-process: before each next story it runs /ctx and wraps based on the actual context % (nudge at 40%, strongly recommended at 60%). This measures real burn instead of predicting it. See skills/start/SKILL.md step 10.
{
"id": "PREFIX-NNN",
"title": "Concise imperative title",
"description": "What needs to happen and why",
"acceptanceCriteria": [
{ "text": "Specific, testable criterion from source doc" },
{ "text": "Another criterion" },
{ "text": "Typecheck passes" },
{ "text": "Operator confirms behavior on a real device", "humanGated": true }
],
"priority": 1,
"passes": false,
"testFlow": "path/to/test.yaml or null",
"notes": "Implementation hints referencing existing patterns and specific file paths"
}
{
"project": "[Project Name from RALPH.md]",
"source": "prd",
"sourceItem": "3.1",
"sourceIssues": [42, 45],
"branchName": "ralph/feature-name",
"description": "Feature description — what this sprint delivers",
"userStories": [
{ "...story objects..." }
]
}
Source field values by sprint type:
| Sprint source | source value | sourceItem value | sourceIssues |
|---|---|---|---|
| PRD feature section | "prd" | Section number as string (e.g., "3.1") | omit or empty |
| Backlog item | "backlog" | Item number as integer | omit or empty |
| Tech debt item | "tech-debt" | Tech debt ID as string (e.g., "TD-003") | optionally [N] if also tracked as a GitHub Issue |
| GitHub Issue | "github-issue" | omit | array of issue numbers ([42] or [42, 45]) |
The completion flow (/start Case D / D2) uses sourceItem to mark backlog/tech-debt items complete, and sourceIssues to close GitHub Issues (verifying Fixes #N auto-close first, then closing the rest manually).
If Audit.mode = per-story: Before writing the prd.json, send the draft through the auditor for a structured PRD review. The auditor catches problems while they're cheap to fix.
If Audit.mode = sprint-close or off: Skip this step. Jump to Step 6 (Review and Write).
Write the draft PRD to a temp path so the auditor can read it without conflicting with any existing scripts/ralph/prd.json:
# write the draft to a temp path (the lead's tooling, not bash here)
# echo "<draft prd json>" > /tmp/draft-prd.json
Team name (
<team>): resolve once per session —team_namefrom RALPH.md's## Auditsection if set, otherwiseralph-<project-folder>(the kebab-cased basename of the repo root, e.g.ralph-closetize-website). Never use the bare nameralph: teams are machine-global (~/.claude/teams/), shared across every terminal and directory, so a fixed literal name cross-wires concurrent Ralph projects — a lead in one repo can wake an idle session in another repo and send it work.
Then check if the <team> team already exists at ~/.claude/teams/<team>/config.json. If yes (a sprint is in progress, auditor is alive), reuse it. If not, create one:
TeamCreate({ team_name: "<team>", agent_type: "team-lead", description: "Ralph sprint coordination" })
Spawn the auditor (skip if already a member):
Agent({
subagent_type: "auditor",
team_name: "<team>",
name: "auditor",
description: "Ralph sprint auditor — PRD review mode",
prompt: "You are joining the '<team>' team as the auditor. Your first task is PRD review. Run setup per agents/auditor.md. Then go idle and wait for an 'audit prd' message."
})
SendMessage({
to: "auditor",
summary: "audit draft PRD",
message: "audit prd /tmp/draft-prd.json — run your PRD review mode flow per agents/auditor.md. Write the report to <Audit.reports_dir>/PRD-AUDIT-<branchName>.md. SendMessage the verdict + finding counts + report path back when done."
})
Wait for the auditor's reply.
Once the auditor returns its verdict, show:
Use AskUserQuestion with options:
scripts/ralph/prd.json.If the user picks "apply critical fixes," apply them to the draft and re-message the auditor with "re-audit prd /tmp/draft-prd.json" to confirm fixes resolved the findings. Loop until verdict is READY TO COMMIT or user explicitly accepts a residual finding.
Show the complete generated prd.json to the user. Highlight:
If Step 5 ran, also note the auditor verdict for transparency.
Ask: "Does this look good? Any stories to add, remove, or adjust?"
Offer options:
scripts/ralph/prd.jsonscripts/ralph/progress.txt — keep the Codebase Patterns section at the top if it exists; clear all previous sprint entries below it. If no Codebase Patterns section exists, create a minimal header:
# Ralph Progress Log
## Codebase Patterns
[Will be populated as stories are completed]
---
## Sprint Created!
Feature: [name]
Source: [PRD section N.N / Backlog item #N / Tech debt TD-NNN / GitHub Issue #N]
Branch: [branchName]
Stories: [count]
E2E tests: [count with testFlow] / [total]
humanGated ACs: [count, with story IDs that have them]
Run /start to begin working on the first story.
Good story size (fits one context window):
Too big (split these):
Rule of thumb: If you cannot describe the change in 2-3 sentences, it is too big.
Before writing prd.json, verify:
text (and humanGated where applicable)source and sourceItem / sourceIssues fields are set correctlywrapPoints array (wrap timing is decided live by /start)npx claudepluginhub yarikchekin/ralph-cc --plugin ralph-ccGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.