ralphy: Skill for Claude Code

dev-loop — autonomous issue-driven dev cycle

A maintainer skill. It executes the open work in notes/issues/ (the inbox /dev-issues fills), one issue at a time, committing after each. It does not touch .ralphy/workspaces/<ws>/projects/ or call media models except where an issue explicitly requires it (and then only behind the paid-generation gate below).

Scope + limit

• Default scope: every open issue at the flat top level of notes/issues/. The notes/issues/done/ and notes/issues/deprecated/ subfolders are the closed archive — never in scope (status is encoded by folder; see Issues folder layout).
• Default limit: 25 issues per loop run. If the user's prompt names more (or "no limit", or a specific subset / range), honor that.
• The user can narrow scope in their prompt ("just the landing ones", "only #052-#055", "everything tagged cli").

Workflow (per run)

1. Read the rules first. docs/developing-ralphy.md (English-only, the lint suite, append-only contract, auto-generated files), AGENTS.md (the hard invariants — especially "wait for user 'go' before any paid generation"), and notes/README.md (including the Issues folder layout — active work is the flat top level only). Skim every candidate issue.

2. Build the execution order. Sort issues by dependency, not by number:

   • Foundational / schema / data-model changes FIRST (everything keys off them).
   • Cross-cutting renames or moves NEXT, as a single coordinated step (never parallelize these).
   • Independent, low-collision, and plan-only/docs issues can go any time.
   • Read each issue's ## Notes for explicit "sequence after #NNN" hints. State the planned order up front and track it with TaskCreate / TaskUpdate (one task per issue; mark in_progress on start, completed on land).

3. For each issue, in order: a. Dispatch ONE sub-agent (the Agent tool, usually general-purpose) with a tight, self-contained mandate: the mandatory reads, the exact scope, the gates it must pass, "do NOT git commit or push — leave changes in the working tree", and a required structured report-back. Give it the rename maps / file lists / schema decisions up front so it does not improvise on settled questions. Run agents sequentially — wait for one to finish and land before starting the next — to avoid collisions on shared files (AGENTS.md, skills, the landing app, the template schema). b. Review the diff yourself. Read the changed files / diffstat. Trust but verify the agent's report — re-run the real gates manually: the relevant lint:* scripts, the affected bun test files, cli:surface:build for CLI-surface changes, and rg '\p{Cyrillic}' --pcre2 over changed files (text only; .webp/.png are binary false positives). Web and public-doc checks run in their sibling repositories. c. Close gaps. Fix small issues inline; for a substantive miss, dispatch a focused follow-up agent (you cannot resume a finished agent — SendMessage is not available — so either edit directly or spawn a fresh scoped agent). d. Commit + push to main, then move on. One commit per issue with a Conventional-Commits message referencing the issue number. As part of that same commit, git mv the issue into notes/issues/done/ and update its > **Status:** line to done — <YYYY-MM-DD> (the folder is the live signal, the line carries the date/why — keep them in sync). If the issue turns out to be obsolete or superseded rather than implemented, git mv it into notes/issues/deprecated/ and set the line to SUPERSEDED by #NNN / dropped (<reason>) instead. Never delete the note — moving preserves the record. Push to origin (this repo commits to main; never gitlab).