ralph-prd-afk

Fully automated, AFK-capable orchestrator built on top of ralph-prd. Point it at a product idea, walk away, and come back to implemented features.

What it does

ralph-prd-afk runs a complete product development pipeline without manual intervention:

1. Grill-me — you describe what you want to build, then Claude interviews you relentlessly until you confirm the requirements are complete
2. Plan-PRDs — analyzes the grill summary and decides how many PRDs are needed, with a structured plan including dependencies, folder layout, and architectural decisions
3. PRD generation — writes each PRD using the grill summary and plan context, with folder naming like 1-feature, 2a-feature, 2b-feature
4. Reality-check loop — iteratively critiques and revises each PRD until it passes
5. Plan generation — converts each approved PRD into an implementation plan (parallel when multi-agent is enabled)
6. Execution — runs ralph-prd against each plan; optionally in parallel git worktrees with AI-coordinated commit ordering

Requirements

• Node.js 18+
• ralph-prd >= 3.0.0 (installed automatically)
• Skills: grill-me, write-a-prd, prd-to-plan, reality-check (installed automatically)

Install

npx ralph-prd-afk init

# Offline mode (use cached skills, skip network)
npx ralph-prd-afk init --offline

This will:

• Install ralph-prd and required skills (with retry + cached fallback on network failure)
• Scaffold a config file at .claude/ralph-afk.config.yaml

The orchestrator runs directly from the npm package — no runtime is copied to your project.

Usage

# Full pipeline (interactive grill session, then fully automated)
npx ralph-prd-afk

# Check pipeline state
npx ralph-prd-afk status

# Preview what would happen without running anything
npx ralph-prd-afk --dry-run

# Import existing PRDs from docs/
npx ralph-prd-afk bootstrap

# Edit the roadmap in $EDITOR
npx ralph-prd-afk edit-roadmap

# Reset state and clean up (worktrees, branches)
npx ralph-prd-afk reset
npx ralph-prd-afk reset --keep-prds   # keep roadmap/PRDs/plans, reset execution

Stage control

npx ralph-prd-afk --start-from=prd        # skip grill-me and plan-prds
npx ralph-prd-afk --start-from=plan       # skip to plan generation
npx ralph-prd-afk --start-from=execution  # skip to execution

npx ralph-prd-afk --stop-after=plan-prds  # stop after PRD planning (alias: --stop-after=roadmap)
npx ralph-prd-afk --stop-after=prd        # stop after PRDs approved
npx ralph-prd-afk --stop-after=plan       # stop after plans generated

Execution modes

Preset configurations that override individual flags — like gear modes:

npx ralph-prd-afk --mode=fast       # max speed, minimal checks (default)
npx ralph-prd-afk --mode=thorough   # ship-check + reality-check, 3 repairs, parallel
npx ralph-prd-afk --mode=cautious   # sequential, 2 reality-check rounds, strict ship-check

| Setting | fast | thorough | cautious | |---------|------|----------|----------| | allowMultiAgent | true | true | false | | skipShipCheck | true | false | false | | realityCheckIterations | 0 | 1 | 2 | | maxRepairs | 1 | 3 | 3 | | skipOnVerifyFail | true | false | false | | skipOnShipCheckFail | — | true | false | | shipCheckRetries | — | 1 | 2 | | continueOnError | false | false | false |

Execution flags

npx ralph-prd-afk --allow-multi-agent          # parallel git worktrees
npx ralph-prd-afk --continue-on-error          # skip failing PRDs
npx ralph-prd-afk --skip-ship-check            # skip ship-check
npx ralph-prd-afk --ship-check-retries=3       # retry ship-check
npx ralph-prd-afk --skip-on-ship-check-fail    # continue on ship-check failure
npx ralph-prd-afk --no-skip-on-ship-check-fail # halt on ship-check failure
npx ralph-prd-afk --user-in-reality-check-loop # manual approval per finding
npx ralph-prd-afk --skip-reality-check-threshold
npx ralph-prd-afk --log-level=dump             # verbose logging
npx ralph-prd-afk --version

Pipeline stages

Grill-me

The grill-me skill interviews you relentlessly about every aspect of your plan. It does not stop early based on turn count — the interrogation continues until you explicitly confirm the requirements are complete. The skill then emits a structured summary with a GRILL_COMPLETE marker that the orchestrator requires before advancing.

When you type /done to end the session, the runner handles two cases automatically:

• Summary already present: if Claude emitted the GRILL-SUMMARY markers during the conversation, the runner captures it and moves to the next stage immediately.
• No summary yet: the runner sends one final --continue turn asking Claude to produce the structured summary with the required markers, then advances.

Plan-PRDs

After the grill session, a planning sub-phase analyzes the summary and produces a structured PRD plan:

• Scope heuristic: small features get 1 PRD; large/risky work gets multiple PRDs decomposed for surgical delivery
• Folder naming: sequential (1-feature, 2-feature) with siblings at the same level (2a-feature, 2b-feature)
• Roadmap.md: generated at docs/Roadmap.md for multi-PRD plans, containing a build order graph, PRD index, and key architectural decisions table. Skipped for single-PRD plans.

The plan is emitted as machine-parseable JSON inside <!-- PRD-PLAN-START/END --> delimiters and saved to session state.

Multi-agent mode

When allowMultiAgent: false:

• Plan generation runs in parallel for independent PRDs
• Execution uses isolated git worktrees on branches named afk/<prd-id>
• All agents in a batch run concurrently; commits land sequentially through a FIFO commit queue
• Before each subsequent merge, an AI reconciliation step runs:
  1. Rebases the agent's branch onto the updated main
  2. Resolves any merge conflicts
  3. Applies the DRY principle — deduplicates overlapping logic between agents touching the same repo
• Reconciliation is per-repo: agents touching different repos skip the check
• On reconciliation failure: retry with user hint / skip PRD (preserve worktree) / abort batch

Worktree lifecycle

Worktrees track their owner repo — the git repository that created them. This is critical for multi-repo setups where parent and nested repos have separate git databases.

• activeWorktrees in session state records every live worktree with its ownerRepo path
• Cleanup always prunes from the owner repo, never from an assumed cwd
• On startup, the orchestrator consults activeWorktrees first (exact paths), then sweeps all configured repos as a safety net
• reset iterates all configured repos; warns if no config is available

Execution progress bar

During the execution phase, a sticky progress bar appears at the bottom of the terminal:

──────────────────────────────────────────────────────────────────────────────────
 ████████░░░░░░░░░░░░  40%  2/5 PRDs  4/12 phases  ⏳ ~15m remaining  → endpoint
──────────────────────────────────────────────────────────────────────────────────

• Shows percentage, completed/total PRDs, phase-level progress (checkboxes in plan.md), and current PRD name
• ETA based on measured phase completion pace (falls back to PRD-level averages when no phase data available)
• Phase progress tracks - [ ] / - [x] checkboxes in plan.md — ralph-prd checks these off as it completes each phase
• Only appears during execution (not during grill-me, plan-prds, or PRD generation)
• Uses ANSI scroll regions — all subprocess output scrolls above the bar
• Automatically hidden in non-TTY environments (CI, piped output)
• Handles terminal resize, and always cleans up on exit/crash

Configuration

Edit .claude/ralph-afk.config.yaml — this is the single config file. ralph-prd's config is auto-generated from it.

# ── Pipeline control ─────────────────────────────────────────────
startFrom: grill
stopAfter: null
allowMultiAgent: false
continueOnError: false

# ── Reality-check ─────────────────────────────────────────────────
userInRealityCheckLoop: false
realityCheckIterations: 0
skipRealityCheckThreshold: true

# ── Ship check ────────────────────────────────────────────────────
skipShipCheck: true
shipCheckRetries: 1
skipOnShipCheckFail: true

# ── Logging ───────────────────────────────────────────────────────
logLevel: necessary

# ── Repositories ──────────────────────────────────────────────────
# repos:
#   - name: backend
#     path: ../backend

# ── Extra writable directories ────────────────────────────────────
# writableDirs:
#   - ../docs

# ── Ralph-PRD execution flags ────────────────────────────────────
# Forwarded to ralph-prd. You only configure them here.
ralphFlags:
  iDidThis: false
  waitForIt: false
  maxRepairs: 1
  skipOnVerifyFail: true

# ── Hooks ─────────────────────────────────────────────────────────
# hooks:
#   afterCommit: npm test

Config lookup: .claude/ralph-afk.config.yaml (canonical) -> .claude/ralph-afk/ralph-afk.config.yaml (legacy). CLI flags override the config.

Status command

npx ralph-prd-afk status

[ralph-afk] Pipeline Status

  Roadmap: 5 PRD(s)
  Approved: 5  |  Completed: 3  |  Failed: 0
  API cost: $2.4510

  ✓ template-entity-schema [prd] [plan]
  ✓ template-create-endpoint [prd] [plan]
  ✓ template-update-endpoint [prd] [plan]
  → template-soft-delete-purge-flow [prd] [plan]
  ○ template-crud-frontend [prd] [plan]

  Legend: ✓ complete  ✗ failed  → in progress  ○ approved  · pending

Error recovery

# Continue past failing PRDs
npx ralph-prd-afk --continue-on-error

# Check what failed
npx ralph-prd-afk status

# Reset just the execution state and retry
npx ralph-prd-afk reset --keep-prds
npx ralph-prd-afk --start-from=execution

Failed PRDs are tracked in session state with [execution] or [reconcile] prefixes and skipped on re-runs. The status command shows them with error details.

Crash recovery

Session state is saved to .ralph-afk-state.json after every stage. State writes are atomic (write-then-rename) to prevent corruption on crash.

• Grill session: transcript is saved after each turn. On restart, the session resumes from the saved transcript.
• PRDs/plans: completed items are skipped. In-progress items resume from the correct phase.
• Worktrees: tracked in activeWorktrees with their owner repo. On startup, the orchestrator cleans them up using exact owner paths, then sweeps all configured repos as a safety net.

Multi-repo support

repos:
  - name: backend
    path: ../backend
  - name: frontend
    path: ../frontend

writableDirs:
  - ../docs

ralph-prd-afk auto-generates ralph.config.yaml for ralph-prd with repos, flags, writable dirs, and hooks. Worktree cleanup is multi-repo aware — each worktree tracks its owner repo and cleanup always prunes from the correct git database.

Starting from existing PRDs

npx ralph-prd-afk bootstrap
npx ralph-prd-afk --start-from=plan

bootstrap scans docs/*/PRD.md and registers each as an approved PRD with a minimal prdPlan.

Output

| Artifact | Location | |----------|----------| | Roadmap | docs/Roadmap.md (multi-PRD only) | | PRDs | docs/<folder>/PRD.md | | Plans | docs/<folder>/plan.md | | Session state | .ralph-afk-state.json | | Logs | .claude/ralph-afk/logs/<timestamp>/ |

License

MIT