@neriros/ralphy 0.1.0

package/dist/phases/done.md

@@ -0,0 +1,10 @@
+---
+name: done
+order: 99
+requires: []
+next: null
+autoAdvance: null
+loopBack: null
+terminal: true
+context: []
+---

package/dist/phases/exec.md

@@ -0,0 +1,140 @@
+---
+name: exec
+order: 3
+requires: [PLAN.md, PROGRESS.md]
+next: review
+autoAdvance: allChecked
+loopBack: null
+terminal: false
+context:
+  - type: currentSection
+    label: "Current Section"
+---
+
+# Task — Execution Phase
+
+You implement one section of a task plan. The current section and verification checklists are injected at the bottom of this prompt.
+
+---
+
+## Orient
+
+0a. Study `CLAUDE.md` for build commands, conventions, patterns, and gotchas. This is the operational source of truth.
+0b. Read `TASK_DIR/state.json` for task context: current phase, iteration count, history of previous runs, and any metadata.
+0c. Study existing source code using parallel subagents. **Read at least 2 existing files in the same area** you will be working in to understand the exact patterns before writing new code.
+0d. Never assume something is missing without searching first — use grep/glob to confirm before listing gaps.
+
+{{MCP_TOOLS}}
+
+---
+
+## Steps
+
+### 1. Implement
+
+Work through the items in the Current Section in order.
+
+- **Read before writing** — study at least 2 existing files in the same area before modifying code
+- **Check for existing code first** — before creating anything new, search the codebase for similar implementations, utilities, or patterns. Reuse and extend existing code rather than duplicating. If a helper, type, or component already exists that does 80% of what you need, build on it.
+- **Follow existing patterns** — match the style, naming, and structure of surrounding code
+- **Keep it minimal** — implement exactly what the item specifies, no more
+- **Type safety first** — follow the project's TypeScript strictness conventions. Favor Zod schemas for runtime validation at system boundaries (API inputs, external data, config). Define the Zod schema first, then derive the TypeScript type from it with `z.infer<>` rather than maintaining both separately.
+- **Size limits** — respect file and function size limits from `CLAUDE.md`
+
+### 2. Verify
+
+Follow every injected checklist below in order. Fix all issues before proceeding.
+
+**CRITICAL: ALWAYS use Nx affected, NEVER run-many**
+
+```bash
+# CORRECT - Run all relevant tasks together with affected
+nx affected -t test,lint,typecheck
+```
+
+**NEVER DO THIS:**
+
+```bash
+# WRONG - Runs ALL tests (100x slower, crushes CPU)
+nx run-many -t test
+
+# WRONG - Multiple independent commands (spawns uncontrolled processes)
+nx run lib1:test & nx run lib2:test
+```
+
+**Rules:**
+
+- **ALWAYS** use `affected` - it only validates your uncommitted changes
+- **NEVER** use `run-many` - it runs on the entire monorepo
+- **NEVER** run multiple independent Nx commands in parallel
+- Keep Nx daemon running (never use `NX_DAEMON=false`)
+- If tests fail, fix them and re-run `nx affected` (still fast)
+
+### 3. Update PROGRESS.md
+
+- Check off (`[x]`) every completed item in the section
+- If you discovered new issues or subtasks, add them as `- [ ]` entries in the appropriate section (or create a new section)
+
+### 4. Review
+
+Before committing, review all changes made in this section:
+
+- **Code review**: Check for typos, logic errors, missing edge cases, and adherence to patterns
+- **Test coverage**: Verify all new code paths are covered by tests
+- **Type safety**: Run typecheck to catch any type errors
+- **Lint & format**: Ensure all files pass linting
+- **Integration**: Check that changes work correctly with existing code
+
+**If issues are found:**
+
+- Document them in PROGRESS.md with a note (e.g., `- [x] Item name — Issue: [description]`)
+- Fix each issue directly in the code
+- Re-run verification commands (`nx affected -t test,lint,typecheck`)
+- Loop back to step 2 (Verify) until all issues are resolved
+
+**If no issues are found:**
+
+- Proceed to step 5 (Commit & push)
+
+### 5. Commit, push, and advance if done
+
+- `git add` the specific files you changed (not `git add -A`)
+- `git commit` with a descriptive message summarizing the section's work
+- `git push`
+- Check PROGRESS.md for remaining unchecked items. If **all items across all sections** are now checked, advance to done. Use `ralph_advance_phase` MCP tool if available, otherwise fall back to:
+  ```
+  ./loop.sh advance --name "{{TASK_NAME}}"
+  ```
+
+---
+
+## Remediation
+
+When items are bugs or fixes discovered during review/testing:
+
+- Group related failures by root cause
+- Fix the underlying issue, not just the symptom
+- Add regression tests for each fix
+- Verify the fix doesn't introduce new issues
+- If a fix reveals additional problems, add them to PROGRESS.md
+
+---
+
+## Termination Signal
+
+If you hit an unresolvable blocker (e.g., missing credentials, broken dependency, architectural question that needs human input), write a file `TASK_DIR/STOP` containing a one-line reason. The loop will halt after this iteration.
+
+Example: `echo "Blocked: need API key for X service" > TASK_DIR/STOP`
+
+Only use this for genuine blockers. For item-level blocks, add a note in PROGRESS.md and continue with remaining items.
+
+---
+
+## Rules
+
+- **One section per iteration.** Complete all items in the section, then commit and push.
+- **Never skip tests.** Tests are your backpressure mechanism.
+- **Follow `CLAUDE.md` conventions exactly** — lint/typecheck must pass on the first try.
+- If blocked on a specific item, add a note under it in PROGRESS.md and continue with remaining items.
+- Ultrathink when making architectural decisions.
+- Keep `CLAUDE.md` current with learnings.

package/dist/phases/plan.md

@@ -0,0 +1,119 @@
+---
+name: plan
+order: 2
+requires: [RESEARCH.md]
+next: exec
+autoAdvance: null
+loopBack: null
+terminal: false
+context:
+  - type: file
+    file: RESEARCH.md
+    label: "Research Findings"
+---
+
+# Task — Planning Phase
+
+You have a RESEARCH.md with detailed codebase findings. Your job is to create an implementation plan and execution checklist.
+
+**Input: `TASK_DIR/RESEARCH.md` (already exists)**
+**Output: `TASK_DIR/PLAN.md` and `TASK_DIR/PROGRESS.md` (you create both)**
+
+---
+
+## Orient
+
+0a. Study `CLAUDE.md` for build commands, conventions, patterns, and gotchas. This is the operational source of truth.
+0b. Read `TASK_DIR/state.json` for task context: current phase, iteration count, history of previous runs, and any metadata.
+0c. Read `TASK_DIR/RESEARCH.md` thoroughly — it contains the codebase analysis, file details, callsites, and dependency graph.
+0d. You may do additional targeted searches if the research missed something, but most exploration should already be done.
+0e. If PLAN.md and PROGRESS.md already exist, you are refining them — review, identify issues, improve.
+0f. Phase iteration: {{PHASE_ITERATION}}. After committing, advance to execution (use `ralph_advance_phase` MCP tool if available, otherwise `./loop.sh advance`).
+
+{{MCP_TOOLS}}
+
+---
+
+## Steps
+
+### 1. Read the research
+
+Read `TASK_DIR/RESEARCH.md` end to end. Absorb:
+
+- Current state of every file that will be modified
+- All callsites and consumers that need updating
+- Existing code to reuse
+- Discovered issues and edge cases
+- Dependency graph and ordering constraints
+
+### 2. Gap analysis
+
+Compare the research findings against what the task requires. For each gap, note:
+
+- What exists (if partial)
+- What's missing
+- Dependencies on other items
+- Priority (critical path items first)
+
+### 3. Create PLAN.md
+
+Write `TASK_DIR/PLAN.md` with:
+
+- A brief summary of the task and approach
+- Key architectural decisions and trade-offs
+- Files that will be created or modified
+- Risks or open questions
+
+### 4. Create PROGRESS.md
+
+Write `TASK_DIR/PROGRESS.md` as a detailed execution checklist. Structure:
+
+- Each `## Section N — Title` = one iteration (one agent invocation)
+- Items within a section should be completable together in one iteration
+- Later sections can depend on earlier sections
+- Items within a section should be as independent as possible
+
+Rules:
+
+- **Each item must be specific and implementable** — include file paths, function names, what changes
+- **No vague items** like "improve performance" or "clean up code"
+- **Include test items** alongside implementation items (not in a separate section)
+- **Include a final section** for integration testing, verification, and cleanup
+- **Order by dependency** — critical-path items first within each section
+- **Keep sections reasonably sized** — 3-8 items per section is ideal
+
+### 5. Append verification checklists
+
+Use `ralph_list_checklists` to see available verification checklists, then `ralph_apply_checklist` to append the relevant ones as final sections of PROGRESS.md before advancing to exec. Checklists are auto-appended during phase transition as a fallback, but explicitly choosing which ones to include is preferred.
+
+### 6. Commit and advance
+
+```
+git add TASK_DIR/PLAN.md TASK_DIR/PROGRESS.md
+git commit -m "plan: <task-name>"
+```
+
+Then advance to the execution phase so the next iteration starts correctly. Use `ralph_advance_phase` MCP tool if available, otherwise fall back to:
+
+```
+./loop.sh advance --name "{{TASK_NAME}}"
+```
+
+**Stop after advancing. Do not implement anything.**
+
+---
+
+## Termination Signal
+
+If you cannot proceed (e.g., research is insufficient, critical information is missing, or a dependency is unresolvable), write a file `TASK_DIR/STOP` containing a one-line reason. The loop will halt after this iteration.
+
+Only use this for genuine blockers — not for normal completion (the loop handles that automatically).
+
+---
+
+## Rules
+
+- **PLAN ONLY. Do NOT implement anything. Do NOT write application code.**
+- Base your plan on the research findings — don't re-explore what's already documented.
+- Ultrathink when analyzing architecture and priorities.
+- Keep each checklist item a single implementable unit of work.

package/dist/phases/research.md

@@ -0,0 +1,99 @@
+---
+name: research
+order: 1
+requires: []
+next: plan
+autoAdvance: null
+loopBack: null
+terminal: false
+context: []
+---
+
+# Task — Research Phase
+
+You are starting a new task. Your job is to deeply research the codebase to understand the current state, then produce a RESEARCH.md documenting your findings.
+
+**Input: Task description (injected below)**
+**Output: `TASK_DIR/RESEARCH.md` (you create this)**
+
+---
+
+## Orient
+
+0a. Study `CLAUDE.md` for build commands, conventions, patterns, and gotchas. This is the operational source of truth.
+0b. Read `TASK_DIR/state.json` for task context: current phase, iteration count, history of previous runs, and any metadata.
+0c. Never assume something is missing without searching first — use grep/glob to confirm.
+
+{{MCP_TOOLS}}
+
+---
+
+## Steps
+
+### 1. Understand the task
+
+Read the task description below. Identify:
+
+- What needs to change or be created
+- What existing code is likely affected
+- What areas of the codebase to investigate
+
+### 2. Deep research
+
+**Write RESEARCH.md incrementally as you go.** Do not wait until the end — create the file early and append findings after each area of investigation. This ensures nothing is lost if the session is interrupted.
+
+Use parallel subagents to investigate the codebase. For each area the task touches:
+
+- **Read the actual files** that will be modified — understand their current structure, imports, exports, and patterns
+- **Search for all callsites** of code that will change — find every consumer that needs updating
+- **Check for edge cases** — related tests, config files, CI/CD, build scripts
+- **Find existing implementations** — code that already does something similar that can be reused or extended
+- **Find existing types, Zod schemas, and utilities** that overlap with the task requirements
+- **Identify ordering constraints** — what must happen before what? What can be parallelized?
+
+After each batch of investigation, immediately write or append your findings to `TASK_DIR/RESEARCH.md`.
+
+### 3. Finalize RESEARCH.md
+
+Review `TASK_DIR/RESEARCH.md` for completeness. Ensure it covers:
+
+- **For each file to be modified**: current state, relevant imports/exports, callsites, what needs to change
+- **For each new file**: patterns to follow (based on similar existing files), dependencies it needs
+- **Existing code to reuse**: types, utilities, patterns that already exist and should be leveraged
+- **Discovered issues**: extra files, hidden callsites, ordering constraints, edge cases
+- **Dependency graph**: what must happen before what, what can be parallelized
+
+Keep it factual and reference-heavy — file paths, line numbers, function names. This document is the foundation for the plan and execution checklist.
+
+### 4. Commit and advance
+
+```
+git add TASK_DIR/RESEARCH.md
+git commit -m "research: <task-name>"
+```
+
+Then advance to the planning phase so the next iteration starts correctly. Use `ralph_advance_phase` MCP tool if available, otherwise fall back to:
+
+```
+./loop.sh advance --name "{{TASK_NAME}}"
+```
+
+**Stop after advancing. Do not create PLAN.md or PROGRESS.md — that happens in the next phase. Do not implement anything.**
+
+---
+
+## Termination Signal
+
+If you hit a blocker (task description is ambiguous, critical information is missing), write `TASK_DIR/STOP` with a one-line reason.
+
+---
+
+## Rules
+
+- **RESEARCH ONLY. Do NOT implement anything. Do NOT write application code. Do NOT create PLAN.md or PROGRESS.md.**
+- If RESEARCH.md already exists, you are refining it — read it first, identify gaps, then enhance.
+- Phase iteration: {{PHASE_ITERATION}}. After committing, advance to planning (use `ralph_advance_phase` MCP tool if available, otherwise `./loop.sh advance`).
+- Read actual files — don't guess at what's in them.
+- Use parallel subagents aggressively to explore the codebase.
+- The quality of the plan depends entirely on the quality of this research. Be thorough.
+- Ultrathink when analyzing the codebase.

package/dist/phases/review.md

@@ -0,0 +1,115 @@
+---
+name: review
+order: 4
+requires: []
+next: exec
+autoAdvance: allChecked
+loopBack: exec
+terminal: false
+context:
+  - type: currentSection
+    label: "Current Section (to review)"
+---
+
+# Task — Review Phase
+
+You review the work completed in the current execution section and identify any issues that need to be fixed.
+
+**Input: `TASK_DIR/PROGRESS.md` (current section with completed items)**
+**Output: Issues documented in PROGRESS.md or approval to advance**
+
+---
+
+## Orient
+
+0a. Study `CLAUDE.md` for build commands, conventions, patterns, and gotchas.
+0b. Read `TASK_DIR/state.json` for task context and previous execution results.
+0c. Read the current section from `TASK_DIR/PROGRESS.md` — these are the items just implemented.
+0d. Review the git diff/recent commits to see exactly what was changed.
+
+{{MCP_TOOLS}}
+
+---
+
+## Steps
+
+### 1. Code Review
+
+For each implemented item in the current section:
+
+- **Correctness** — Does the implementation match the item requirements exactly?
+- **Patterns** — Does it follow existing code patterns and conventions?
+- **Edge cases** — Are there missing edge cases or error scenarios?
+- **Type safety** — No type errors or unsafe casts?
+- **Dependencies** — Are all imports and dependencies correct?
+- **Naming** — Are variable/function names clear and consistent?
+
+### 2. Test Coverage Review
+
+- **Test files created** — Are there tests for the new code?
+- **Coverage** — Do tests cover normal paths and edge cases?
+- **Integration** — Do tests verify the code works with existing code?
+- **No regressions** — Did existing tests pass? (`nx affected -t test`)
+
+### 3. Lint & Type Safety
+
+Run checks:
+
+```bash
+nx affected -t lint,typecheck
+```
+
+If there are errors:
+
+- Document them as issues in PROGRESS.md (step 4)
+- Do NOT fix them here — the execution phase will fix them
+
+### 4. Document Issues
+
+If you found **any problems**, add them to `PROGRESS.md` under the current section:
+
+```markdown
+- [x] Item name — Issue: [clear description of what's wrong]
+```
+
+Example:
+
+```markdown
+- [x] Add login button — Issue: Button missing error handling for failed login attempts
+- [x] Create auth service — Issue: Type error on line 42: cannot assign string to AuthToken
+```
+
+Include enough detail that an implementation agent can fix the issue directly without re-reading the code.
+
+### 5. Decision
+
+**If issues found:**
+
+- Do NOT advance
+- Return to console with issues documented
+- The loop will loop back to exec to fix them
+
+**If NO issues found:**
+
+- All items in section are correct
+- Ready to advance to next section
+
+---
+
+## Rules
+
+- **REVIEW ONLY. Do not implement or fix anything.**
+- Be thorough — catching issues now prevents rework later
+- If uncertain about an issue, document it anyway (better safe)
+- Focus on correctness, not "nice to have" improvements
+- Only block if the code doesn't work or is incorrect
+
+---
+
+## Termination Signal
+
+If you discover a fundamental architectural issue that requires revisiting the plan, write `TASK_DIR/STOP` with a one-line reason.
+
+Example: `echo "Discovered issue: Auth token storage conflicts with existing pattern" > TASK_DIR/STOP`
+
+Only use this for genuine blockers, not normal issues that can be fixed in the next execution pass.

package/dist/scaffolds/MANUAL_TESTING.md

@@ -0,0 +1,9 @@
+# Manual Testing — User Instructions
+
+This file is for providing manual testing steps that the agent should follow during execution and review phases.
+
+**USER: Edit this file anytime** to define manual testing procedures. Changes take effect on the next iteration.
+
+---
+
+**Leave this file empty if no manual testing is needed.**

package/dist/scaffolds/PLAN.md

@@ -0,0 +1,20 @@
+# Plan — {{TASK_NAME}}
+
+> Task: {{TASK_PROMPT}}
+> Created: {{DATE}}
+
+## Summary
+
+<!-- Brief summary of the task and approach -->
+
+## Approach
+
+<!-- Key architectural decisions and trade-offs -->
+
+## Files
+
+<!-- Files that will be created or modified -->
+
+## Risks & Open Questions
+
+<!-- Anything uncertain or risky -->

package/dist/scaffolds/PROGRESS.md

@@ -0,0 +1,13 @@
+# Progress — {{TASK_NAME}}
+
+> Task: {{TASK_PROMPT}}
+> Created: {{DATE}}
+
+## Section 1 — TODO
+
+- [ ] Item description (specific, implementable)
+
+## Section N — Verification & Cleanup
+
+- [ ] Final integration testing
+- [ ] Update documentation if needed

package/dist/scaffolds/STEERING.md

@@ -0,0 +1,9 @@
+# Steering — User Guidance
+
+This file is for providing real-time guidance and constraints to the agent as iterations progress.
+
+**USER: Edit this file anytime** to steer the task. Changes take effect on the next iteration.
+
+---
+
+**Leave this file empty if no special guidance is needed.**

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@neriros/ralphy",
+  "version": "0.1.0",
+  "description": "An iterative AI task execution framework. Orchestrates multi-phase autonomous work using Claude or Codex engines.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neriros/ralphy.git"
+  },
+  "keywords": [
+    "ai",
+    "cli",
+    "claude",
+    "task-runner",
+    "mcp",
+    "agent",
+    "ralph",
+    "loop"
+  ],
+  "workspaces": [
+    "packages/*",
+    "apps/*",
+    "tools/generators/*"
+  ],
+  "type": "module",
+  "bin": {
+    "ralphy": "./dist/cli/index.js",
+    "ralphy-mcp": "./dist/mcp/index.js"
+  },
+  "files": [
+    "dist/cli/index.js",
+    "dist/mcp/index.js",
+    "dist/phases/",
+    "dist/checklists/",
+    "dist/scaffolds/",
+    "README.md"
+  ],
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "scripts": {
+    "ralph": "bun .ralph/bin/cli.js",
+    "lint": "oxlint --config .oxlintrc.json .",
+    "lint:fix": "oxlint --config .oxlintrc.json --fix .",
+    "fmt": "oxfmt --write .",
+    "fmt:check": "oxfmt --check .",
+    "typecheck": "nx affected -t typecheck",
+    "check:circular": "madge --circular --extensions ts packages/*/src apps/*/src",
+    "check:deps": "depcruise packages/*/src apps/*/src --config .dependency-cruiser.cjs",
+    "check:unused": "knip",
+    "lint:ci": "nx affected -t lint",
+    "fmt:ci": "nx affected -t fmt:check",
+    "typecheck:ci": "nx affected -t typecheck --parallel=1",
+    "test:ci": "nx affected -t test",
+    "test:coverage:ci": "nx affected -t test:coverage",
+    "check:circular:ci": "nx affected -t check:circular",
+    "prepare": "bunx husky",
+    "build:publish": "bunx nx run-many --target=build --projects=cli,mcp && bun run copy-assets",
+    "copy-assets": "bun scripts/copy-assets.ts",
+    "prepublishOnly": "bun run build:publish"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.4.3",
+    "@commitlint/config-conventional": "^20.4.3",
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@nx/devkit": "^22.5.3",
+    "@nx/js": "^22.5.3",
+    "@secretlint/secretlint-rule-preset-recommend": "^11.3.1",
+    "@swc-node/register": "^1.11.1",
+    "@swc/core": "^1.15.18",
+    "@total-typescript/ts-reset": "^0.6.1",
+    "@types/node": "^22.0.0",
+    "bun-types": "^1.3.0",
+    "chalk": "^5.4.0",
+    "dependency-cruiser": "^17.3.8",
+    "front-matter": "^4.0.2",
+    "husky": "^9.1.7",
+    "knip": "^5.85.0",
+    "lint-staged": "^16.3.2",
+    "madge": "^8.0.0",
+    "nx": "22.5.3",
+    "oxfmt": "^0.36.0",
+    "oxlint": "^1.51.0",
+    "secretlint": "^11.3.1",
+    "typescript": "^5.8.0",
+    "zod": "^3.24.0"
+  }
+}