Set up Phase 1: creates .ralph/phase1.sh and .ralph/phase1-prd-prompt.md, seeds a draft .github/plans/project-plan.md if missing. Run bash .ralph/phase1.sh to normalize the source plan into the canonical PRD at .ralph/prd.md via ralph.write_prd. Configure phase1.sourcePlan in .ralph/config.json (default .github/plans/project-plan.md). When the PRD is ready, run ralph.generate_phase2.

Write or update a planning document under .github/plans/. Use for draft plans before Phase 1 PRD normalization, or auxiliary planning docs.

Write or replace the canonical product requirements document at .ralph/prd.md. Used by the Phase 1 Copilot session only.

Read .ralph state: config, parsed tasks, spec index, PRD tail, and log tails. Call at the start of Phase 2/3 iterations.

List files and directories one level deep under a repo-relative path. Use this during Phase 2 exploration to discover source files, then read them with ralph.read_file.

Read any text file inside the repo by its repo-relative path. Use this during Phase 2 to explore source code and inform spec and fix-plan authoring.

Write/update the canonical .ralph/epic_plan.md file.

Write/update a spec file under .ralph/specs/**. Call this iteratively during Phase 2 as you explore source files and refine your understanding.

Replace .ralph/fix_plan.md, optionally preserving completed items from the previous file. Phase 2/3: use preserveCompleted:true when refining. You may add <!-- ralph-defer: blocked-by: task-id — note --> on the line after a checkbox to defer work.

Return the next unchecked active task from .ralph/fix_plan.md (ignores blocked tasks).

Check/uncheck a task in .ralph/fix_plan.md by text or taskId. In Phase 3, only the QA-close persona should call this with checked:true after Dev agrees sign-off.

Move an active task into the dedicated Blocked section with a short reason.

Move a blocked task back into the active task list (unchecked by default).

Append a timestamped entry to .ralph/logs/progress.txt.

Append a new section to .ralph/logs/learnings.md.

Set up Phase 2: .ralph/phase2.sh (planning persona + worker loop), config.json with defaults, phase2-planner-prompt.md, phase2-worker-prompt.md, specs/, logs/. Phase 2 reads paths.projectPlan (default .ralph/prd.md). Ensure .ralph/prd.md exists first. Run bash .ralph/phase2.sh after setup.

Set up Phase 3: .ralph/phase3.sh — Plan, Dev, QA personas, Dev/QA consensus sign-off, then QA close marks tasks done. Prompt files: phase3-plan-prompt.md, phase3-dev-prompt.md, phase3-qa-prompt.md, sign-off prompts. Requires .ralph/fix_plan.md. Run bash .ralph/phase3.sh.

Run strict verification gate: npm run ci, then npm run test:e2e (stop on first failure).