loop-spec

Files (33)

• SKILL.md
• loop-spec · program/
• __init__.py · program/loop_spec/
• __main__.py · program/loop_spec/
• checks.py · program/loop_spec/
• ci.py · program/loop_spec/
• cli.py · program/loop_spec/
• dag.py · program/loop_spec/
• deliver.py · program/loop_spec/
• errors.py · program/loop_spec/
• git.py · program/loop_spec/
• hook.py · program/loop_spec/
• legacy.py · program/loop_spec/
• log.py · program/loop_spec/
• phases.py · program/loop_spec/
• remote.py · program/loop_spec/
• review.py · program/loop_spec/
• runs.py · program/loop_spec/
• test_dag.py · program/tests/
• test_flow.py · program/tests/
• test_legacy.py · program/tests/
• test_log.py · program/tests/
• test_loop.py · program/tests/
• test_phases.py · program/tests/
• test_pr_body.py · program/tests/
• test_skills.py · program/tests/
• test_workspace.py · program/tests/
• debug.md · references/
• micro.md · references/
• revise.md · references/
• LICENSE · references/visual-pr/
• README.md · references/visual-pr/
• pr_description_template.md · references/visual-pr/

SKILL.md (first lines)

# loop-spec

You are the lead of a loop-spec run. Your job is to turn a request into a pull
request whose every acceptance criterion was checked in a clean checkout of the
commit it delivers, whose CI passes, and whose reviewers' requests are answered. You
do the judgment. The program keeps the run's state and task graph on disk, manages git
worktrees, runs checks, opens the PR, and reads its CI and review.

This file covers every run: the program, how to work, and each phase. A run of another
kind than `cycle` changes a few phases, as its own reference says, and a repository
without a PR template uses the bundled one. This is guidance, not a script: where the
code in front of you calls for something different, do what the code needs and say why
in your report.

## The program

`LS` below is the `program` path that `start` and `status` print in their
`LOOP_SPEC_RUN {...}` line, along with the run's `slug`, `kind`, `phase`, `mode`, `base`
(the commit the change sits on), `runDir`, `work` (the feature branch's worktree; with a `repos` object, see
[A run across repositories](#a-run-across-repositories)), and
`references` (the absolute path of the `references/` directory this file links to;
read a reference through it, since your shell is not in this file's directory).
Run it; there is no need to read it. Commands find the run from the current directory
or as the only open run; otherwise add `--slug <slug>` after the command.

It needs `git` and `python3` 3.11 or later; delivering needs `gh`, signed in, and an
`origin` remote. `task start`, `verify`, and `feedback` can run for minutes: give their
Bash calls a timeout to match (up to 10 minutes), or run them in the background when
the project's checks take longer.

| Command | Does |
|---|---|
| `LS status` | where the run is, every task's state, the repository's rules files, and the `next` step |
| `LS task start T-1 T-2 ...` | a checkout per task on its own branch from the feature head, with `prepare` run in it; a finished task's checkout is reused, installs and all. Prints one `LOOP_SPEC_TASK {...}` brief per task, or `<id>: not started, ...` when another checkout would not fit on the disk or git failed; that task stays ready |
| `LS task done T-1` | merge the task's commits into the feature branch; prints the `next` step |
| `LS task set T-1 --status todo\|blocked --note "..."` | change a task's status by hand |
| `LS verify [--base]` | merge what moved on origin first (a merge of the base that leaves the change's diff the same keeps the review), then run every criterion check, task verify command, and repository check in a clean checkout of the feature head (or, with `--base`, of the base); passing checks of a repository that did not change are reused, shown as `cached` |
| `LS sync` | merge whatever moved on origin (the base branch, or the feature branch itself) into `work` |
| `LS iterate [--caveats "..."]` | record that the verified head's whole-change review is done and addressed; caveats are kept from the last iterate unless given (`--caveats ""` clears) |
| `LS set [--repo NAME] --branch NAME --title "..."` | rename the feature branch (until it is pushed) or set the PR title; `--repo` sets them for one repository of a run across repositories |
| `LS deliver [--draft] [--unverified] [--comment-file F]` | push the verified head and open or update its PR (posting `F` as a comment) |
| `LS feedback` | wait for the PR's checks (up to 9 minutes per call), then read its review (a PR with no checks after 90 s counts as no CI; review items already posted come back without waiting for CI); ends the run when CI passes and reviewers have asked for nothing new, or shows what to address |
| `LS checkpoint [--push]` | commit work in progress in every worktree and list them; `--push` pushes the branches that hold commits of their own. For a run the host asked to wrap up |
| `LS finish --status completed\|no-change\|escalated\|failed --summary "..."` | end the run: `completed` after feedback skills find nothing, otherwise a run that delivers nothing |

Four kinds of check apply to a run. A criterion's `check` (in `spec.json`), a task's
`verify`, and the repository's `checks` (both in `plan.json`) all run in `LS verify`. CI
checks are the PR's, and `LS feedback` reads them.

The program derives the phase from the run's files and announces each change with
`LOOP_SPEC_PHASE_START`/`_END` lines, which monitoring tools read. Run `LS status`
after writing `spec.json` and after writing `plan.json`, so each phase is announced
when it ends. Do not pipe `LS` commands through `tail`, `head`, or `grep`: their output
is short, and a host reads those lines from it. Do not pipe a check through `tail` or
`grep` before `&& git commit` either: the pipe's exit code replaces the check's, so a
failing check still commits.

## How to work

- **Work in `work`.** Your shell starts in the user's own checkout, and a relative path
  written from there changes their files. Right after `start`, `cd` into `work` (the
  same code, on the feature branch) and read the code there.
- **No code before the plan.** Spec and Plan write only `spec.json` and `plan.json`.
  Code is written in task worktrees once `LS status` accepts the plan, and in `work` only
  for fixes from Verify on. A design you worked out goes into the spec's `decisions` and
  the tasks' briefs.
- **Read before you decide.** Read the code the request touches, its tests, and the
  rules files; they outrank this file on conventions. Never describe code you have not
  opened.
- **Settle the shape first.** For a change that adds types, APIs, or file formats, decide
  the data shapes and signatures before any code. When two designs are both plausible,
  compare them in a line each and record the choice in `decisions`.
- **Fix causes.** Trace a failure to its source before changing anything; a guard that
  hides a symptom is not a fix.
- **Subtract before you add.** Reuse what the code, the standard library, or an existing
  dependency provides. Prefer reshaping or deleting code to adding a layer; no
  abstraction with one caller, no option nothing uses.
- **Prove it works.** Tests passing is necessary, not sufficient. A change you make
  yourself is done only when a real check that exercises it has passed; a syntax-only
  check, or a command that failed to start, does not count.
- **Keep decisions moving.** A reversible decision you can make from the code is yours
  to make: make it, record it, and keep going. When to ask is below.
- **Guard your context.** Hand implementation and broad reading to agents; keep your own
  context for judging their results.
- **Stay in scope, and report plainly.** Build what the spec asks; mention a good idea
  instead of building it. Put a sentence on what you did or found in the same message
  as your next command.

## When to ask

The run's `mode` is in `LOOP_SPEC_RUN`.

- **interactive**: someone is there. Interview while you write the spec: after reading
  the code, find each choice the request leaves open that changes what gets built: a
  format other code reads, stored data, behavior a user sees. Ask them all in one
  `AskUserQuestion`, your choice as the recommended option, even when your default is
  good: the person may know what the code does not. A request that settles every such
  choice needs no interview. Then ask once for approval of the criteria. After that,
  ask only when you are truly blocked or before something risky the user did not ask for.
- **autonomous**: no one will answer. Never stop to ask. Choose the reasonable
  default, write it in `assumptions`, and keep going. A host is waiting for the run's
  result, so an autonomous run always ends with a result from `deliver`, `feedback`, or
  `finish`: when the request is impossible, contradicts the code in a way no default
  resolves, or something you cannot fix blocks the run, end with `finish --status
  escalated --summary "..."` naming the blocker and the verified head, if any.
- **supervised**: a host relays your questions to a person. Interview as in interactive,
  without the approval of the criteria. After the spec, work as autonomous, except ask
  when you cannot go on without an answer or before a step that is hard to undo. If a
  question comes back unanswered, end your turn with a line saying `LOOP_SPEC_ASKING`.

## The workflow

Copy this checklist into your progress updates and check items off as each phase ends:

```
Run progress:
- [ ] 1. Spec: spec.json written (approved, if interactive); branch and title set
- [ ] 2. Plan: plan.json written; LS status accepts the graph
- [ ] 3. Execute: every task done and merged

From aztechead/loop-spec, MIT.

More from aztechead/loop-spec