/implement
Run the lightsout deterministic implementation pipeline on a plan file.
When to reach for it
Run it when a plan is graded and you want the work done unattended. Every step is gated by the repo’s own tests, lint, types and coverage, and the run parks rather than pushing past a gate it cannot satisfy.
How to run it
lightsout implementlightsout implementfolder: overview.md runs all phases, else plan.md| flag | meaning | left out |
|---|---|---|
| --plan <path> | The plan file to implement. | required |
| --overview <path> | The overview this plan is one phase of, so the run reads the wider intent. | The plan is implemented on its own. |
| --packages <a,b> | Comma-separated package names the gates are scoped to. | The packages the run actually changed files in. |
| --plan <folder> | A plan workspace folder — overview.md runs every phase as a child run, plan.md runs the one. | required |
| --start-phase <n> | The phase number a phased run begins at. | The first phase that has not already passed. |
| --cwd <path> | Repository to implement in. | The process working directory. |
| --skip-refactor | Skip the refactor step at the end of the run. | off |
| --worktree | Build in a fresh git worktree of this repository, on a branch named after the plan’s ticket folder. | The `implement.worktree` config key, which defaults to on. |
| --no-worktree | Build in the checkout this was launched from rather than a worktree of its own. | off |
| --ship | Ship the branch after the run passes: open or adopt the PR, wait for checks, merge, clean up. | off |
| --no-ship | End on the run result even when the config’s `ship.after-implement` asks to chain into ship. | off |
What happens
1. START THE RUN
- Hand the finished plan to `/implement`
- Resolve settings from the config
- Snapshot existing worktree changes and create a run ID
- Create a repository lock so other lightsout runs cannot clash
Isolates the agent’s changes and makes the run safely resumable
writes.lightsout/runs/<id>/manifest.json.lightsout/lock.json
2. VERIFY THE REPO STARTS GREEN
- Run lint, type checks, tests, build, and coverage before implementation begins
- Stop immediately if any gate is already failing
- Record files touched by setup or gates in the manifest
Proves any later failure was introduced by this run, not inherited from the repository
writesmanifest.json.lightsout/runs/<id>/commands.jsonl
3. IMPLEMENT THE PLAN
- The implementation agent follows the finished spec
- It writes the code and returns a structured report
- It can run only commands explicitly allowed in the config
Executes the finished spec without reopening settled decisions
writes.lightsout/runs/<id>/agents/stream-NN-implement.jsonlrejected-*.txt
4. VERIFY THE IMPLEMENTATION
- Re-run lint, type checks, tests, build, and coverage
- Try up to two lightweight repairs if a gate fails
- If the gates remain red, park the run with all evidence
Prevents a broken implementation from moving forward
writesmanifest.json.lightsout/friction.jsonl
5. WRITE THE TESTS
- Spawn a test-writing agent for each source file that changed
- Add tests until coverage meets the configured threshold
- Skip this step when no eligible source files changed
Makes sure the new behavior is covered by tests
writes.lightsout/runs/<id>/agents/stream-NN-write-tests.jsonl
6. VERIFY THE TESTS
- Re-run lint, type checks, tests, build, and coverage
- Try up to two lightweight repairs if a gate fails
Confirms the new tests pass and coverage meets the configured threshold
writesmanifest.json.lightsout/friction.jsonl
7. REFACTOR
- Review changed code for duplication and structural issues
- Reuse existing helpers or extract shared abstractions
- Refactor to your code standards without changing behavior
- Skip this step when requested or when nothing changed
Removes duplication and keeps agent-written code aligned with your code standards
writes.lightsout/runs/<id>/agents/stream-NN-refactor.jsonl
8. VERIFY THE REFACTOR
- Re-run lint, type checks, tests, build, and coverage
- Try up to two lightweight repairs if a gate fails
Confirms the refactor preserved behavior and passes every gate
writesmanifest.json.lightsout/friction.jsonl
9. FORMAT THE CODE
- Run the configured formatter on all changed files
- Re-run lint, type checks, tests, build, and coverage
Confirms formatting does not break a green run
writes.lightsout/runs/<id>/commands.jsonl
10. REPORT THE RESULT
- Generate the final report from artifacts saved during the run
- Record the final status, steps, retries, rejected reports, token cost, and friction
- Keep the complete run history in one folder
Leaves an inspectable record of what happened and why the run passed or failed
writes.lightsout/runs/<id>/