agentleFS
Venkateshvenki404224Venkateshvenki404224/shipcraft-skills/skills/issue-to-phases/SKILL.md

issue-to-phases

Skill2 starsChanged 3 days agoMITView on GitHub

Decompose a planning document (plan.md, a spec, or a GitHub issue) into incremental, independently-shippable "tracer bullet" phases, write them as phase specs under specs/, and optionally generate a Ralph loop (ralph.sh + prompt.md) that implements them unattended. Use this whenever the user hands you a plan and wants it broken into phases, mentions "tracer bullets", "phase 0/1/2", "build this in phases", "thin end-to-end slice first", "ralph loop", or wants phased specs in the specs/ folder — even if they never say the word "phase". Also use it when the user asks to "implement / work on phase N" of an existing spec folder, so the branch, the PR and the spec's status all move the way every earlier phase did.

  • Installs packages
  • Commits and pushes

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If it cannot launch, fix that before the loop runs, not during it — an agent discovering a missing browser mid-phase burns an iteration on …

    line 140
  2. Distinctive:

    Not every spec needs one. A loop pays for itself when the work is long, has verifiable per-phase end states, and touches something you …

    line 158
  3. Very specific:

    Keep the bucket, the banner and STATUS.md in agreement.

    line 224

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

issue-to-phases

Three jobs. Work out which one the request is, then do that one.

JobTriggerOutput
1. Decomposethe user hands you a plana spec folder under specs/
2. Implement a phase"work on phase N"a commit on the one branch, the one PR retitled, the spec's status moved
3. Build a Ralph loop"make a ralph script", or the work is long and unattendedralph.sh + prompt.md in the spec folder

Job 1 usually leads into Job 3. Do not start Job 2 straight after Job 1 unless asked — decomposition is its own step, and the user may want to read it first.

The idea: tracer bullets

Tracer bullets come from The Pragmatic Programmer. When building systems you want feedback as quickly as possible. A tracer bullet is a small slice of functionality that goes through all layers of the system, letting you test and validate the approach early — before investing significant time.

Everything below is mechanics. The point is real feedback: each phase is a slice you can run and verify, not a horizontal layer (all the backend, then all the frontend) that proves nothing until the end.

Job 1 — Decompose a plan into phases

Read references/spec-templates.md before writing anything. It carries the README and phase templates, and the code-snippet style contract that keeps generated implementations from drowning in comments.

  1. Read the plan in full, then list every layer the finished feature touches — infra, a backend manager module, the deploy pipeline, a DocType, the whitelisted API, the SPA. You are looking for the seam that runs top to bottom through all of them.
  2. Find phase 1 — the thinnest end-to-end slice. Everything optional stripped: no auth, no toggles, no polish. Its only job is to prove the architecture and produce feedback. If phase 1 touches one layer it is not a tracer bullet; widen it until a single user-visible action travels the whole pipe.

    Two halves that are individually unverifiable are one phase, not two. If shipping half of it breaks production or changes nothing observable, it was never a phase boundary.

  3. Slice the rest. Each later phase adds one coherent capability, is independently shippable, and is independently verifiable. A phase is the wrong size when you cannot write a concrete "Done when". Order so nothing depends on a later phase. Most plans land at 3–5 phases; let the plan decide.
  4. Write the folder, using the templates:

    specs/not-completed/<feature-slug>/
    ├── README.md
    ├── phase-1-<slug>.md … phase-N-<slug>.md
    └── ralph.sh + prompt.md   (Job 3, optional)
  5. Create the tree and register it — with the script, never by hand:

    python3 .claude/skills/issue-to-phases/scripts/promote_spec.py --init
    python3 .claude/skills/issue-to-phases/scripts/promote_spec.py <slug> \
      --to not-completed --note "freshly authored — no branch yet"

    --init creates specs/, all four buckets and STATUS.md if any are missing, so a repo that has never used specs/ needs no setup. Run it first whenever you are not certain the tree exists.

  6. Tell the user the folder path, the phase list, and the branch name, then stop unless they ask you to build or implement.

Job 2 — Implement a phase

One branch for the whole feature; every phase commits to it; one PR that walks forward phase by phase. The reviewer watches the feature grow as a single story, and GitHub allows only one open PR per head→base pair anyway.

Branch name comes from the spec README. Base is the integration branch it names, else the repo default.

Phase 1

  1. promote_spec.py <slug> --to in-progress --detail "P1 started"
  2. git switch -c <branch> <base>
  3. Implement from the phase spec. Follow the repo conventions, run the lint hook.
  4. Commit, git push -u origin <branch>
  5. gh pr create --base <base> --head <branch> --title "Implemented phase one" --body "<what it does + how to verify>"
  6. gh pr checks <branch> --watch — fix whatever is red before calling the phase done.

Phase N ≥ 2

  1. git switch <branch> — do not branch off it.
  2. Implement, lint, commit, push.
  3. gh pr checks <branch> --watch, and fix what it reports.
  4. gh pr edit <branch> --title "Implemented phase <ordinal>" and gh pr comment <branch> --body "Phase <ordinal>: <what it added + how to verify>"
  5. promote_spec.py <slug> --to in-progress --detail "P<n> done"
  6. If it was the final phase, CI is green and it merged: promote_spec.py <slug> --to completed --detail "all phases in <base> (PR #<n>)"

CI is a gate, not a report. A phase whose tests pass locally and fail on the runner is unfinished, and a check that was already red before the branch is still the branch's problem — nothing merges past it. Fix it in its own commit.

Ordinals are spelled out: one, two, three, four, five.

Job 3 — Build a Ralph loop

Read references/ralph-loop.md before writing the script. Copy both templates into the spec folder and fill them in:

cp .claude/skills/issue-to-phases/assets/ralph.sh.template   specs/<bucket>/<slug>/ralph.sh
cp .claude/skills/issue-to-phases/assets/prompt.md.template  specs/<bucket>/<slug>/prompt.md
chmod +x specs/<bucket>/<slug>/ralph.sh

A phase that touches the UI needs a browser, so make sure there is one. Before writing the loop, check that agent-browser is installed and can launch:

agent-browser --version || npm i -g agent-browser && agent-browser install
agent-browser skills get core     # the workflow guide; the CLI serves its own docs

If it cannot launch, fix that before the loop runs, not during it — an agent discovering a missing browser mid-phase burns an iteration on setup. On a container host Chrome usually needs --args "--no-sandbox"; record the working invocation in the spec README so every iteration inherits it instead of rediscovering it.

A Ralph loop runs one fresh headless claude -p session per iteration, with the file system as its only memory, and runs phases strictly in order. The prompt lives in prompt.md so it can be tuned between runs without touching bash.

The thing that makes it trustworthy: the agent is not the only judge of its own work. After the agent writes a .done marker the loop runs its own smoke_check against the real system, and deletes the marker if reality disagrees. Write gates that would fail today, before the feature exists — a gate that passes on an unmodified tree is testing nothing. references/ralph-loop.md covers gate design, preflight/rollback, and the sandbox check to run before handing the loop over.

Not every spec needs one. A loop pays for itself when the work is long, has verifiable per-phase end states, and touches something you would rather not babysit.

Spec status: one script, three trackers

A spec's status lives in three places that must agree — the bucket folder, the README banner, and its row plus counts in STATUS.md. By hand that is three edits and two counters, and it is reliably the step that gets skipped while you are concentrating on code. A shipped feature filed under "not started" is how a tracker stops being worth reading.

So it is a script, not a ritual:

P=.claude/skills/issue-to-phases/scripts/promote_spec.py
python3 $P --init                                          # create the tree
python3 $P <slug> --to in-progress --detail "P1 started"
python3 $P <slug> --to completed --detail "all phases in main (PR #12)" --note "<index line>"
python3 $P <slug> --check                                  # verify; changes nothing

It is idempotent, recomputes every count, refuses a backwards move without --force, and --check exits non-zero on drift so a loop can gate on it — which the ralph template does.

Buckets walk forward only: not-completed/ → in-progress/ → completed/. superseded/ is a manual sideways move for an abandoned spec. Keep a spec in in-progress/ until the final phase actually merges; half-shipped is not completed.

Guardrails

  • Never hardcode configurable values. Anything a business admin could reasonably change — accounts, cost centers, rates, thresholds, default parties, recipients, toggles — belongs in an admin-editable config surface (a Settings DocType, a Custom Field, a config record read at runtime), never baked into source. When a phase needs such a value, adding the config surface is part of that phase. Flag every one of them while decomposing and give it a home in the spec.
  • A UI change is not done until it has been seen in a browser. Tests passing and a green smoke check say the code is right; they say nothing about whether a user can see it. Any phase touching a page, component or form ends with agent-browser driving the real deployment and a screenshot in the notes. Three things make a correct, merged UI change invisible, and none of them fails a test: the built assets are older than the source, a feature flag hides it, and no row exercises it (the feature reads a column every existing row has as NULL). Check those three before concluding the code is wrong.
  • A move that changes a dotted path ends with migrate, then the restart. Frappe resolves scheduled and enqueued jobs from strings at run time, so moving a function they name breaks them while every import still works. Rewrite every string in the same commit, run docker compose exec backend bench --site frontend migrate, and restart the workers after — the other order leaves a Scheduled Job Type row pointing at nothing, and that fails in complete silence. Job ids never change during a move, and a re-export shim is not a fallback: see Moving code that a string names.
  • One subfolder per feature, always inside a status bucket — never loose in specs/ or in a bucket root.
  • One branch and one PR per feature. Never a second PR for a later phase.
  • A spec reaches completed/ only with a green CI run behind it. The bucket is a claim about shippability; a red PR filed under "completed" is the same lie as a shipped feature filed under "not started".
  • Phase numbers and PR ordinals stay in lockstep: phase 1 is "Implemented phase one".
  • A phase with no concrete "Done when" is too big or too vague. Reslice it.
  • Keep the bucket, the banner and STATUS.md in agreement. When they disagree, the bucket the folder physically sits in wins.

Files in this skill

PathRead it when
references/spec-templates.mdwriting or revising a spec folder (Job 1)
references/ralph-loop.mdwriting a ralph.sh (Job 3)
assets/ralph.sh.templatethe loop skeleton to copy
assets/prompt.md.templatethe phase prompt to copy
scripts/promote_spec.pyany time spec status or the tree changes

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.