Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -180,7 +180,9 @@ Every finding is a proposal. Every count the revision reports is per rule, never

**Automatic once you start it.** The plan review loop and the build gates run on their own until they pass or hit a stop. How the build ended is always reported as it happened; a run that hit a cap is never called passed.

**Depth.** A build runs light, standard or deep. Light is the implementation reviewer, running lint and the tests that touch the change, beside one focused reviewer, for a change whose every changed line is on the profile's allowlist, such as a changelog entry; standard is the round of reviewers the diff calls for; deep always plans first, with the planner and the plan reviewer, for what `implement-change`'s depth floor names deep. A script sets the floor from the diff; you may raise it, and you may lower a standard floor to light with a reason, which the pull request's `Procedure:` line carries. Deep is never lowered. After the first round, only the implementation reviewer runs again, beside any focused reviewer that had a blocking finding and the tests reviewer when a fix changed a test.
**Depth.** A build runs light, standard or deep. Light is the implementation reviewer, running lint and the tests that touch the change, beside one focused reviewer, for a change whose every changed line is on the profile's allowlist, such as a changelog entry; standard is the round of reviewers the diff calls for; deep plans first, with the planner and the plan reviewer, for what `implement-change`'s depth floor names deep, except in a verify, which has no plan to draft and names a planned build as the alternative. A script sets the floor from the diff; you may raise it, and you may lower a standard floor to light with a reason, which the pull request's `Procedure:` line carries. Deep is never lowered. After the first round, only the implementation reviewer runs again, beside any focused reviewer that had a blocking finding and the tests reviewer when a fix changed a test.

**Code you wrote yourself.** `/lasp-dev:implement-change verify [goal]`, or "review what I just wrote", runs the same review on work written with no plan: the diff is your commits since the default branch plus the working tree, a one-line goal stands in for the plan, the wave fixes blocking findings in your working tree, and it ends at the diff gate, before any commit.

**One session per branch.** Starting a build (`implement-change`) or a fix (`pr-fix`) takes a lock under `.review/`; a second session starting either in the same tree is told who holds it and asks whether to take it over. The skill releases the lock when it finishes or when its session ends, and a lock untouched for four hours, from a session that crashed or was left open, is stale and taken without asking. Reviewing a pull request or drafting a ticket takes none. A session in a repository with a `.review/` directory opens with one line: where the ticket stands and the next command. It never touches GitHub.

Expand Down Expand Up @@ -215,7 +217,7 @@ Every finding is a proposal. Every count the revision reports is per rule, never
- **Provisional, established, graduated:** a rule's status on its ledger entry. A rule is admitted provisional, becomes established when the Established Dial is met, and is graduated when the revision judges that a check enforces it; one that leaves is retired.
- **Profile:** one repository's values the skills read, such as its ticket pattern, test and lint commands and depth allowlist, kept in its standard: its own `standards/profile.yaml`, or `profiles/<repo>.yaml` in a standard for several repositories. A key left out is read from the repository's own files, then the plugin's default profile.
- **Sitting:** a stretch of work on a ticket; `work` names three, the author's (plan, build, open and review), the reviewers' on GitHub, and the author's again (fix and reply), as Figure 1 shows.
- **Wave:** one round of reviewers on a build or a fix, the implementation reviewer beside a focused reviewer per focus the diff calls for; `skills/implement-change/reviews/wave.md` defines it.
- **Wave:** one round of reviewers on a build, a verify or a fix, the implementation reviewer beside a focused reviewer per focus the diff calls for; `skills/implement-change/reviews/wave.md` defines it.
- **Write plan:** every Jira write a `ticket-draft` or `ticket-audit` pass proposes, shown as one numbered list, approved once with any items dropped, then run in order and read back (`using-jira`, "Writing to Jira").
- **AI assistance level:** the `n/5` on prose a skill composes for a pull request, from 1, written by a person, to 5, not read by one; `5/5` until you lower it (`skills/pr-review/comment-style.md`).
- **Build outcome, Build line:** `.review/build/outcome.md`, which `implement-change` writes when the build loop stops; its first line, `Build: <phrase>`, says how the build ended, and `pr-create` copies it into the Already checked block.
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -445,7 +445,7 @@ The skills a person types, in the order they meet them:
- `work`: works out where a ticket or its pull request stands and runs the next phase; each phase
keeps its own approvals.
- `implement-change`: takes one change to an agreed plan, code verified by a wave of reviewers, and
an offered pull request.
an offered pull request; `verify` runs the same wave on work you wrote with no plan.

![Inside implement-change: a plan loop of up to three rounds, your approval of the plan, up to five review rounds with fresh agents, up to two simplify passes, then your review of the diff](docs/img/build-loop.svg)

Expand Down Expand Up @@ -495,7 +495,7 @@ Most days need one command, `work`. Started, in the skills table: `typed only` r
| | `quickstart` | typed or asked | Say where this machine and repository stand, what to fix first and what to type next, with `onboard` first in a repository with no standard, and the skills by group; with a question, answer it from the plugin's own files. Reads only |
| | `onboard` | typed or asked | Survey a repository for the facts the plugin works from, its committed templates, contributing guide, test commands (instruction files, docs, CI) and pre-commit, and its history, and the tracker's statuses and fields when the servers are connected; say where each fact would be read from, the repository's own file first; first asking where the repository's rules live, here or in another repository's standard; then ask where facts should live, which value holds where the repository's files disagree, and which proposals to keep. Writes only `.review/onboard/` unless the person says yes to a named write: the repository's standard, or its `standard:` pointer and the standard's `profiles/<repo>.yaml` |
| Phases, also run alone | `ticket-draft` | typed or asked | Turn a prompt, an existing ticket or a pull request with none into one in the team's format, a Jira ticket or, on a GitHub tracker, an issue: duplicates merged, dependencies, follow-up tickets for out-of-scope work, an in-session estimate, and an Open Questions section for what cannot be settled yet. `investigate` answers your questions about the code first; `settle` folds later answers in and records a departure the work keeps as a comment; `reformat` moves a drafted ticket to the current format, asking only what the format needs. Run directly for an epic or a group ticket session |
| | `implement-change` | typed or asked | Take a change request to an agreed plan, an implementation and a diff verified by a wave of reviewers |
| | `implement-change` | typed or asked | Take a change request to an agreed plan, an implementation and a diff verified by a wave of reviewers; `verify` runs the wave on work written with no plan |
| | `pr-create` | typed or asked | Write a reviewer-focused description and open the pull request |
| | `pr-review` | typed or asked | Review a pull request and present the findings at their lines, each citing a rule, decision, term, ticket criterion or test check when one applies, and no key otherwise; draft comments when asked, and post one review with the verdict you choose only on your yes. A posted review's threads are what the revision reads; a review kept local leaves it nothing |
| | `pr-fix` | typed or asked | Assess every thread, your own comments included, take your agree, disagree or discuss on each (posting them is optional, and each run links the ones not yet on GitHub), offer a rebase when the branch is behind, then plan, implement and reply to the agreed feedback on a pull request, people's comments before AI findings |
Expand Down
3 changes: 2 additions & 1 deletion ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ merged pull request is its record. Owners are roles. Status is `planned`, `defer
| Item | Why | Owner | Trigger | Status |
| --- | --- | --- | --- | --- |
| A neutral thread JSON (#60), with a `gh api` adapter for `record.py`'s four inputs (`pull_request_read` `get`, `get_reviews`, `get_review_comments`, `get_comments`) | `pr-fix` and the harvest stop without a GitHub MCP server, and `pr-review` on `gh` presents a re-review's findings without posting them, since it cannot deduplicate against the threads; one documented thread shape lets `gh` feed them | plugin maintainer | step 4 of #24's order | planned |
| A declined finding's reason carried between review waves | A finding the person declines at a stop or the diff gate would be marked with their reason in the wave file and passed to the next wave's reviewers, who raise it again only when the reason is factually wrong. On Haiku, 10 runs a side (2026-11-10 to 11), the declined code survived 10/10 on main and 9/10 with it; the decline was written into a wave file 7/10 (main 0/10), and a contradicted reason was marked disputed to the person 4/5, two of them only as what a later wave would do (main 0/5, though main's session said the reason did not hold in 3/5). The session sometimes did not write the decline down, and a consolidated `wave-<N>.md` is written in only 1 or 2 of 10 runs on main too | plugin maintainer | recording a decline in the wave file is reliable | deferred |
| `pr-review` on the shared wave, with one finding format | `pr-review`'s reviewer would run as the build's wave does, one focus each, and the build's digests and `pr-review`'s findings would share one shape | plugin maintainer | after a sandbox comparison of the two | planned |
| `next_phase.py` reading `pr-fix`'s local dispositions | A decision kept in `.review/pr-<n>-fix-plan.md` `## Dispositions` and not posted leaves its thread unanswered in the record, so `work` routes to `pr-fix` each time and `pr-fix` raises it with its link. A `--fix-plan` read in `next_phase.py` would route on instead, at the cost of a GitHub record the revision cannot read | plugin maintainer | the repeated prompt proves a burden, or the team decides a local decision is enough | deferred |
| Keep it simple and don't repeat yourself, with a tiebreak | The planner and its reviewer look for the smallest change and `standards/review-contract.md` "New surface" makes a duplicate of an existing function a finding, but nothing says which wins when the two pull apart: strict deduplication extracts abstractions early. A few lines in the contract would name both and settle it: a copy is a finding at its third occurrence, or at its second when the copies must stay in step (a constant, a unit conversion, a validation); similar blocks that may change independently are left. A sandbox check confirms the simplicity reviewer does not then flag every pair of similar lines | plugin maintainer | a review flags, or misses, a duplication the team disagrees with | idea |
Expand All @@ -53,7 +54,7 @@ merged pull request is its record. Owners are roles. Status is `planned`, `defer
| Reviewer counts from `SubagentStop` | The build hook counting reviewers from `SubagentStop` rather than from the Agent tool's prompt | plugin maintainer | a miscounted wave | idea |
| `make`, `tox` and `nox` as gates | The build hook counting them | plugin maintainer | a repository adopts one | idea |
| A simpler-design check against the requirements | Given a ticket's requirements and a drafted design or plan, look for a simpler implementation that meets every requirement; where one exists and is rejected, write into the design why it is not acceptable, as an "Alternatives considered" line naming the requirement it fails. `implementation-plan-reviewer` hunts complexity in a plan and the build's simplicity reviewer reads a finished diff, but neither starts from the requirements, and neither leaves the rejected option written down for the next reader. A mode of `implementation-plan-reviewer`, or a step in `implement-change` and `ticket-draft`, before a new skill | plugin maintainer | a design where a reviewer asks "why not just X?" after the build | idea |
| A route where the person writes the code | Some people want to write a change themselves and keep Claude for the ticket, the plan and the review. `ticket-draft`, the planner, `pr-review` and `pr-fix` already serve a pull request whoever wrote it; the gap is between them: `implement-change` goes from the approved plan straight to the build. An "I'll write it" option at the plan gate would keep the plan as a checklist and skip the build, `work` would route a branch with commits and no build to review, and while the person codes Claude would answer questions with pointers rather than edits, which a hook refusing edits to source files could enforce. Open: whether it serves keeping one's own skills sharp (hints and explanations) or distrust of generated code (the strict guard and a closer review) | plugin maintainer | a teammate asks to write a change themselves within the workflow | idea |
| A route where the person writes the code | Some people want to write a change themselves and keep Claude for the ticket, the plan and the review. `ticket-draft`, the planner, `pr-review` and `pr-fix` already serve a pull request whoever wrote it, and `implement-change verify` runs the build's review on work written with no plan; the gap is the route between them: `implement-change` goes from the approved plan straight to the build. An "I'll write it" option at the plan gate would keep the plan as a checklist and skip the build, `work` and the session-start line would route a branch with commits and no build, or a verify's build, to review, and while the person codes Claude would answer questions with pointers rather than edits, which a hook refusing edits to source files could enforce. Open: whether it serves keeping one's own skills sharp (hints and explanations) or distrust of generated code (the strict guard and a closer review) | plugin maintainer | a teammate asks to write a change themselves within the workflow | idea |
| Where a long run stands | After about ten minutes of work, or when the person asks, say where things stand and which skills ran, with the review loops inside them, such as `implement-change` with two review rounds. `/status` is Claude Code's own command, so this is a skill's report or a status line entry | plugin maintainer | | idea |
| `bug-fix` and `release` skills | A bug taken from its report to a failing test that reproduces it, then the fix; a release that follows the repository's version and changelog convention and hands off to `downstream release`, with the tag behind a yes | plugin maintainer | | idea |

Expand Down
12 changes: 6 additions & 6 deletions agents/focused-reviewer.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,15 +23,15 @@ in place of the digest, its first line naming the error.

## Inputs

The caller gives you: the path of your brief, the plan file path, the ticket's context page
when one exists, `.review/standard.md` when it exists, and the base to diff against: a commit;
given a branch name, use `git merge-base <branch> HEAD`, so commits that branch gained since the
change began are not read, reversed, as part of it. On a later wave, also the delta since the
previous wave and your focus's previous findings.
The caller gives you: the path of your brief, the plan file path, or `none` for work written
with no plan, the ticket's context page when one exists, `.review/standard.md` when it exists,
and the base to diff against: a commit; given a branch name, use `git merge-base <branch> HEAD`,
so commits that branch gained since the change began are not read, reversed, as part of it. On a
later wave, also the delta since the previous wave and your focus's previous findings.

Read the brief first and hold to it: its "Raise" is your whole job, its "Leave to others" is
owned by another reviewer in the same wave, and its "Read first" says where the rules live.
Then read the plan, then `git diff <base>` plus untracked files; the change is usually
Then read the plan, if there is one, then `git diff <base>` plus untracked files; the change is usually
uncommitted. Read the code around each hunk, not only the hunk.

## What you raise
Expand Down
8 changes: 4 additions & 4 deletions agents/implementation-reviewer.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@
name: implementation-reviewer
description: >
Verifies a finished change against its agreed plan, running the tests and linters; returns
SATISFIED or NOT SATISFIED. Run by the review wave, or asked to "verify this implementation" or
"check this is ready to commit".
SATISFIED or NOT SATISFIED. Run by the review wave, or asked to "verify this implementation".
Work written with no plan reaches it through implement-change's verify, not a direct request.
tools:
- Bash
- Read
Expand All @@ -21,7 +21,7 @@ Decide whether a finished change is ready to commit: it passes, it does what was

## Step 1: Take the Inputs

The caller gives you the plan file path, the brief (goal, scope and non-goals, acceptance criteria), and the base to diff against: a commit; given a branch name, use `git merge-base <branch> HEAD`, so commits that branch gained since the change began are not read, reversed, as part of it. Read the plan file itself, not a summary of it. Review `git diff <base>` plus untracked files — the change is usually uncommitted.
The caller gives you the plan file path, the brief (goal, scope and non-goals, acceptance criteria), and the base to diff against: a commit; given a branch name, use `git merge-base <branch> HEAD`, so commits that branch gained since the change began are not read, reversed, as part of it. Read the plan file itself, not a summary of it; with `Plan: none` there is no plan file, so read none and judge against the brief. Review `git diff <base>` plus untracked files — the change is usually uncommitted.

On a later round the caller also gives your previous findings. Check each was fixed, and review the whole change again: a fix can break something that passed before.

Expand All @@ -41,7 +41,7 @@ The caller does not run them, so every round runs them fresh; never carry a resu

## Step 4: Judge the Change Against the Plan and Scope

Implementation always teaches something the plan could not know, so expect small deviations. Judge the spirit: did the change reach the brief's goal by roughly the agreed route?
Implementation always teaches something the plan could not know, so expect small deviations. Judge the spirit: did the change reach the brief's goal by roughly the agreed route? With no plan, judge the goal, the scope and the acceptance criteria against the brief; the plan's steps and deviations do not apply.

- **Every acceptance criterion is met**, by whichever step ended up meeting it.
- **Every plan step is done** or visibly superseded — not stubbed, half-done, or quietly dropped.
Expand Down
Loading
Loading