The 5-beat loop
Every beat is one command. Every command computes instead of opines. The loop is deliberately boring — boring loops survive contact with real projects. Run the beats in order; each beat's output is the next beat's input.
Install once, then the loop is three keystrokes away
git clone https://github.com/CyberTycoon/vibe-to-ship.git cd vibe-to-ship && ./scripts/install.sh && ./scripts/doctor.sh
Boot
./scripts/loop.sh bootEnvironment readiness before anything runs: git present, repo clean enough, node available, MCP config parses, pairing valid, standing rules installed.
Fails when: Exits 1 only on a blocking High finding — e.g. broken mcp.json, pairing file without a projectId.
Good: doctor: 0 high, 2 watch, 0 noise → Result: READY
Bad: Ignoring the boot output because the agent 'feels ready'. Feelings are not readiness.
Triage
./scripts/loop.sh triageReality check against the declared plan: branch, quiet days, dirty files, TODO density — classified High / Watch / Noise with evidence on every line.
Fails when: Never fails by default (findings are data, not verdicts). Pass --fail-on-high in CI to gate.
Good: High (2): [auth-form-validation] email regex missing — contradicts decision dec-2208a1
Bad: "Repo looks mostly fine, some cleanup needed" — no counts, no ids, no evidence.
Act
./scripts/loop.sh actPrints the bounded-task contract before any edit: TASK (one deliverable), SCOPE (allowed files), DONE (observable check), STOP (halt-and-retriage condition).
Fails when: Never — it is the handoff. The discipline is filling every field. A blank STOP is a promise to drift.
Good: SCOPE: src/payments/retry.ts, tests/retry.test.ts
Bad: TASK: fix the checkout (scope: wherever the fix takes me)
Verify
./scripts/loop.sh verify --scope "src/payments/retry.ts,tests/retry.test.ts"Post-act reality gate: scope violations in the diff, auto-detected build, auto-detected tests, new TODO/FIXME markers introduced this session. Computes a verdict.
Fails when: Build fails, tests fail, or a changed file escapes the declared scope.
Good: VERDICT: PASSED — reality matches the plan. Safe to commit and record.
Bad: Accepting "done" from the agent that wrote the code, in the same context window.
Learn
./scripts/loop.sh learnAppends a structured session summary to MEMORY.md: branch, dirty files at close, last commit, decisions made, the single next bounded task.
Fails when: Never. Mid-flight sessions record partial state honestly — a half-written truth beats a clean lie.
Good: - Decisions: backoff capped at 3 attempts (product ask)
Bad: Skipping learn because 'I'll remember next session'. You won't. Neither will your agent.
The one rule that makes the loop work
A worker and its verifier never share a context window. An agent that wrote the code cannot objectively judge it — shared context is an agent nodding along to itself in a different font. Verify with the script (it computes), then with a fresh agent (it challenges), then ship.
Read the full skill contract