From plan-directory
Create a structured plan directory with Ralph Wiggum Loop integration for backend Django projects (PLAN.md, task files, and RALPH-PROMPT.md).
How this skill is triggered — by the user, by Claude, or both
Slash command
/plan-directory:backend-ralph-planThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill creates **two deliverables**:
examples/user-preferences/001-preferences-model.mdexamples/user-preferences/002-preferences-service.mdexamples/user-preferences/003-api-endpoints.mdexamples/user-preferences/004-caching-layer.mdexamples/user-preferences/PLAN.mdexamples/user-preferences/RALPH-PROMPT.mdreferences/plan-template.mdreferences/quality-gates.mdreferences/ralph-prompt-template.mdThis skill creates two deliverables:
/ralph-wiggum:ralph-loopThe key insight: Ralph works by feeding the same prompt repeatedly. Claude sees its previous work in files/git and iterates. RALPH-PROMPT.md becomes that prompt, instructing Claude to work through tasks with strict quality gates.
frontend-ralph-plan if needed)Step 1: This skill creates the plan
docs/plans/<slug>/
├── PLAN.md # Task index with tracking
├── RALPH-PROMPT.md # Prompt for ralph-loop
├── 001-<task>.md # Task files
└── ...
Step 2: Run the plan
/plan-directory:run <slug>
That's it. This command:
/ralph-wiggum:ralph-loop automaticallyOptional: /plan-directory:run <slug> --max-iterations 50
| Input | Required | Description |
|---|---|---|
| Plan title | Yes | Human-readable name |
| Plan slug | Yes | Directory name, kebab-case |
| Task list | Yes | Tasks with names and scopes |
| Django app path | Yes | e.g., optimo_surveys/ |
| Module path | Yes | e.g., digest/ |
| Test filter | Yes | Pytest -k filter |
| Input | Default | Description |
|---|---|---|
| Lint command | ruff check | Prefix with .bin/ if needed |
| Format command | ruff format | |
| Type gate | Auto-detect (ty → pyright → mypy) | ty is mandatory if configured |
| Test command | pytest | |
| Test config | `` | e.g., --dc=TestLocalApp |
| Django command | django | |
| Coverage target | 90 | Minimum percentage |
| Max iterations | 100 | Ralph loop limit |
Type policy for generated plans:
ty, then pyright, then mypy.ty is configured ([tool.ty], ty.toml, .bin/ty, CI/pre-commit), it
is mandatory and blocking.Right-sized tasks for Ralph:
| Task Size | Checklist Items | Good For |
|---|---|---|
| Too small | 1-2 | Overhead exceeds value |
| Ideal | 4-8 | Clear scope, achievable in one iteration |
| Too large | 10+ | Gets stuck, split it |
Signs a task is too large:
Split large tasks by:
The promise must be plan-specific, not generic:
ALL {{TASK_COUNT}} {{PLAN_SLUG_UPPER}} TASKS COMPLETE
Examples:
ALL 4 USER-PREFERENCES TASKS COMPLETEALL 11 MANAGER-DIGEST TASKS COMPLETEALL 6 NOTIFICATION-SERVICE TASKS COMPLETEThis prevents Claude from lying with a generic "done" when tasks remain.
The prompt is iteration-aware. It tells Claude to:
See references/ralph-prompt-template.md for the full template.
See examples/user-preferences/ for a complete working example.
Each task completion includes a commit:
git commit -m "Complete 001 - Preferences Model
- Added JSONField to User model
- Created Pydantic schemas for validation
- 5 tests added, 94% coverage
Plan: user-preferences"
This is critical for Ralph because:
git logFor large/unfamiliar codebases, add a warm-up task:
# 000 - Codebase Orientation
## Goal
Understand existing patterns before implementing.
## Checklist
- [ ] Read existing models in `{{APP_PATH}}`
- [ ] Identify service layer patterns
- [ ] Note testing conventions
- [ ] Document relevant existing code in Notes section
## Completion Criteria
- [ ] Notes section filled with findings
- [ ] No implementation (orientation only)
This prevents Claude from fighting existing patterns.
If Claude is genuinely stuck:
Blockers section in task file:
## Blockers
- **Blocked by:** External API not available
- **Attempted:** Mock implementation, local stub
- **Needs:** API credentials or decision to defer
Skip to independent task if dependencies allow
Max iterations as ultimate safety net
The loop continues until genuine completion or max iterations. Claude should never lie to exit.
Ask for all required inputs. Clarify:
.bin/ wrappers)Before creating files:
docs/plans/<slug>/ directoryPLAN.md with task index and tracking tablesRALPH-PROMPT.md with all placeholders replacedIn RALPH-PROMPT.md, replace:
{{PLAN_TITLE}} → e.g., "User Preferences API"{{TASK_COUNT}} → e.g., "4"{{PLAN_SLUG}} → e.g., "user-preferences"{{PLAN_SLUG_UPPER}} → e.g., "USER-PREFERENCES"{{LINT_CMD}} → e.g., ".bin/ruff check"{{APP_PATH}} → e.g., "accounts/"{{MODULE_PATH}} → e.g., "preferences/"Before delivering:
{{placeholders}}See examples/user-preferences/ for a complete working example:
PLAN.md - 4-task plan with trackingRALPH-PROMPT.md - Iteration-aware prompt001-preferences-model.md - Foundation task (model layer)002-preferences-service.md - Service layer003-api-endpoints.md - API layer004-caching-layer.md - Performance optimizationreferences/ralph-prompt-template.md - Full prompt templatereferences/plan-template.md - PLAN.md structurereferences/quality-gates.md - Verification commandsexamples/user-preferences/ - Working exampleThis Skill is designed to work with both Claude Code and OpenAI Codex.
plugins/plan-directory/commands/).name: backend-ralph-plan.For installation, see this repo's README.md.
npx claudepluginhub diversioteam/agent-skills-marketplace --plugin plan-directoryCreates a structured implementation plan in docs/plans/ with interactive context gathering via Explore agent. Supports feature, bugfix, refactor, and migration plans.
Initializes Ralph Loop infrastructure from approved Claude plans by creating .ralph/ with prd.json, loop.py, CLAUDE.md for autonomous multi-step execution.
Generates feature specs, implementation plans with task checklists, and project loop infrastructure via interactive user interviews on scope, risk tolerance, and validation.