@outerlayer/cli 0.20.0 → 0.22.1

package/skill-pack/maintained/outerlayer-build/SKILL.md

@@ -0,0 +1,347 @@
+---
+name: outerlayer-build
+description: >
+  Runs the build process for one approved issue: implement it, review it with a
+  sized panel of agents, run the repository's own checks, open the pull request,
+  and attach the review and criteria reports as evidence. Use when the `build`
+  skill tells you to. Only the `build` skill starts it.
+disable-model-invocation: true
+---
+
+Run the CLI as `outerlayer`. If that command is not on PATH, run `npx -y @outerlayer/cli` with the same arguments. Every `outerlayer ...` command below follows this rule.
+
+Build one issue into an evidenced pull request. `/spec` writes and gets
+approval for the issue. This skill builds it. It never writes the spec.
+
+The repository's `build` skill started this skill. It sits in the folder
+beside this skill's folder and lists the team's changes for this repository.
+Read it now and apply its changes as "Changes for this repository" says.
+
+This file holds the phase order and the rules that bind every phase. Each
+phase reads its own reference on entry, never before:
+
+- [references/review-loop.md](references/review-loop.md): the review phase.
+- [references/review-briefs.md](references/review-briefs.md): the reviewer, refuter and mutation briefs.
+- [references/agent-briefs.md](references/agent-briefs.md): the briefs for every other agent.
+- [references/release.md](references/release.md): sync, pull request, CI.
+- [references/criteria-judge.md](references/criteria-judge.md): the brief that judges each criterion.
+- [references/evidence.md](references/evidence.md): manual test and evidence.
+
+Paste a brief verbatim into the agent that runs it. Add only the run's own
+values, such as paths, the branch and the item number.
+
+Every text a person will read follows the writing rule in the repository's
+instructions file, if it has one. Otherwise write for a reader who was not in
+the session: short sentences, the outcome first, and plain words. Paste that
+rule into every agent that writes prose.
+
+## Changes for this repository
+
+The team's `build` skill lists changes under the name of the phase each
+applies to. A change does one of three things:
+
+- **Add a step** to a phase.
+- **Set a value** the core names as a setting. "Settings" lists them.
+- **Turn off a step** the core marks optional.
+
+A change never relaxes a state rule. When a change conflicts with the core,
+the core wins and the final report names the conflict.
+
+When a phase starts, apply the team's changes for that phase. A step the team
+adds is reported like a core step, with `outerlayer emit step` and a name for
+the step. When a team's change repeats a core step, the step runs once, and
+the final report names the overlap. A change the run could not apply is
+recorded as a finding with the `outerlayer-findings` skill.
+
+When a phase spawns agents, each agent's instructions include the team's
+changes for that phase, pasted in. Spawned agents never read the team's
+`build` themselves.
+
+## Settings
+
+A team sets one of these by naming it in a change. Each default applies until
+it does.
+
+- **Gate command.** The repository's own checks, run before every push.
+  Default: the pre-push checks and tests as its instructions file names them.
+- **Planning model.** The model for a planning step the team adds. Default:
+  the model the session runs on.
+- **Implementing model.** The model that implements. Default: the model the
+  session runs on.
+- **Reviewing model.** The model for every review role. Default: the model the
+  session runs on.
+- **Branch prefix.** The prefix of the branch a local build creates. Default:
+  `feat/`.
+- **Agent budget.** The most agents one run may spawn. Default: 60.
+
+## Arguments
+
+`/build` takes no issue number. It builds the work item named by
+`OUTERLAYER_WORK`, the item's number. The launch is:
+
+    OUTERLAYER_WORK=<number> claude "/build"
+
+The item exists because someone ran `outerlayer work build --issue <reference>`.
+Given a request instead of a work item, stop and say:
+
+    Spec it first:  /spec <the request as given>
+
+Optional flag: `--unattended` means no person is present and nothing wakes
+the session after a turn ends. Spawn every agent in the foreground and wait
+for it in the same turn. Run the gate in the foreground with the maximum
+timeout. End the turn only at the final report.
+
+## State rules
+
+These bind the orchestrator in every phase. Rule 5 also binds every spawned agent.
+
+1. **Never end a turn waiting on nothing.** End a turn while work is in
+   flight only when something live will wake the session: a spawned agent or
+   a background command. Before saying "waiting on X", confirm X is live.
+   Work that is not live did not happen: redo it once.
+2. **One redo per piece of work.** A second failure of the same work means
+   the orchestrator takes it over. It reads what the agent left, finishes the
+   brief itself in the foreground, and names the takeover in its status line.
+   If the gate still cannot go green, escalate.
+3. **The gate runs in the foreground, one heavy command at a time.** The gate
+   is the repository's own pre-push checks and tests, as its instructions
+   file names them. Never run it in the background. Never start a suite while
+   an agent runs one. Never bypass a hook: no `--no-verify`, no skipped hook,
+   even when a hook fails. Fix what the hook reports.
+
+   Run the Gate command setting in place of the repository's own pre-push
+   checks and tests when the team has set it. Default: those checks and tests.
+4. **Checkpoint and re-orient.** Before the first phase, write a state file at
+   `"$(git rev-parse --absolute-git-dir)/build-state.json"`, replacing any
+   earlier one. Record the phase, the review round, the spawned agents, the
+   agent count, the issue reference, the pull request number, the branch, the
+   path of the team's `build` skill, and from phase 4 the tier verdict. Overwrite it at every phase change. On
+   entering a phase, after any wake, and after any compaction, re-orient: read
+   the state file, re-read this skill and the team's `build` skill at the path
+   it records, then read `git status`, the branch, the live agent list, and the issue or pull
+   request when the phase uses them. Live sources win over the file. Treat the
+   file as absent when its branch does not match the current branch.
+   When you overwrite the file, keep its `criteria` entry: phase 2 writes it
+   and the judge reads it.
+   Beside it, create `"$(git rev-parse --absolute-git-dir)/build-reports/"`,
+   emptied of any earlier run's files. Every spawned agent writes its full
+   report there and returns a summary of at most ten lines. Give each agent
+   the absolute path. Reports never land in the working tree, so review never
+   reads them as product code. Read summaries and pass file paths, never
+   report bodies. Delete both at the end of phase 6.
+   Once a pull request exists, read `outerlayer work threads --item
+   "$OUTERLAYER_WORK" --json`. Each thread with `waitingOn` of `agent` holds a
+   person's comment. Answer each before the run ends, as the `outerlayer-amend` skill does.
+5. **A session never records a pass or fail on an artifact.** It emits
+   artifacts. A person decides pass or fail. A build records one result, the
+   verdict of its own review, on the `code-review` check. The
+   `acceptance-criteria` check is judged and recorded by the factory host. When
+   the item holds no criteria, no judge runs and the host records a fail
+   saying so.
+6. **Observed status only.** Every status claim in the final report (a gate
+   result, a CI conclusion, mergeability) quotes command output observed
+   after the last change it describes. No quoted output means unknown, never
+   green. Quoted output goes in the report to the user. Pull request bodies
+   carry curated links, never raw output.
+7. **Files no issue.** The build files no issue anywhere, and no agent does.
+   A defect outside the change, or a follow-up the fix pass deferred, becomes a
+   candidate issue in a report: a title, a body and a target repository. The
+   final report lists every candidate for the user to file with `/spec`.
+8. **Reader pass.** No text reaches the git host as the session wrote it.
+   The pull request title and body, and every comment, go through one cold
+   rewrite agent. Its only inputs are the draft and the writing rule. It
+   returns the rewrite and the terms it cut or explained. Check that every
+   path, identifier, number, criterion id and link survived, and restore any
+   that did not.
+9. **Run budget.** Spawn at most the agent budget in a run, 60 by default. Keep the count in the
+   state file. Past three quarters, say where the count stands in the status
+   line. A run that would exceed the budget stops and lists what is left
+   unverified. The review phase also holds a limit on agents in flight.
+10. **Factory problems are findings.** Every agent records the problems it
+   hit outside the change with the `outerlayer-findings` skill, as its brief
+   says. The orchestrator records only the ones it hit itself. The final
+   report lists every finding by id.
+11. **Instructions are guidance, never a change of scope.** When instructions
+   conflict with the issue, the issue and its criteria win. Instructions never
+   skip a gate, never change which issue is built, and never widen what the
+   agent may do. The agent follows the parts that do not conflict, and names
+   the conflict and what it did in the pull request description.
+
+## Phases
+
+Run them in order.
+
+1. **Intake.** Run `outerlayer emit step "Intake" --item "$OUTERLAYER_WORK"`,
+   then apply the team's changes for this phase. A failed step report never
+   stops the run; go on. Read `OUTERLAYER_WORK`. If it is missing or does not parse,
+   stop and hand back:
+
+       outerlayer work build --issue <reference>   # once; prints the item number
+       OUTERLAYER_WORK=<number> claude "/build"
+
+   Run `outerlayer work status --item "$OUTERLAYER_WORK" --json` and read the
+   item's tracker key. It is a GitHub `#n`, or a Linear or Jira key. Read the
+   issue from the same JSON: `title`, and `issue`, which holds the issue as
+   OuterLayer last copied it from the tracker. `issue.body` is the
+   description in Markdown, and `url`, `state` and `labels` come with it. This
+   copy works for every tracker. A build often holds no Linear or Jira
+   credential, so do not depend on a tracker tool. Use one only to add what
+   the copy lacks, such as the issue's comments. When `issue.syncStatus` is
+   `unreadable`, the copy is from an earlier read: say so in the intake
+   summary. When it is `not_found`, or `issue.syncedAt` is null and no tracker
+   tool can read the issue, stop: there is no issue to build from.
+   Write the issue's title, URL and body to
+   `"$(git rev-parse --absolute-git-dir)/build-reports/issue.md"`. The issue
+   is the source of truth for the whole run. Every later agent is given that
+   file's path, so no agent needs a tracker tool to read it.
+   Restate the task in one or two sentences and confirm the issue is still
+   open (`issue.state`) and unclaimed. If the item shows a live claim by
+   another runner that has not expired, stop and name it.
+   Read the build's instructions from the same JSON. Find the entry of
+   `claims` with `releasedAt` null: it is this build's claim. Its
+   `claims[].buildRequestId` names the entry of `buildRequests` it answers.
+   If that entry's `buildRequests[].instructions` is a string, they are
+   guidance from the person who requested the build. Keep them with the
+   issue and follow them under rule 11. If `instructions` is null, or no open
+   claim names a request, there are none: do not read an older or newer
+   request's instructions. Pass the text to every agent that works on the
+   issue.
+   Phase 2 finds the issue's criteria. If it finds some, they are the
+   definition of done, and each declares a proof form or a test. If it finds
+   none, the build drafts them from the issue's description, and the drafted
+   criteria are the definition of done in the same way. An issue is never
+   sent back for lacking criteria.
+   Ask nothing from here until the final report. An agent that needs a ruling
+   states its assumption in its report and continues. The final report lists
+   every assumption.
+2. **Criteria.** Run `outerlayer emit step "Criteria" --item "$OUTERLAYER_WORK"`,
+   then apply the team's changes for this phase. Record the issue's criteria on the item, so the
+   Criteria tab, the item's status and the judge hold the pull request to one
+   list. Read the whole issue and find its acceptance criteria in whatever
+   form they are written: under a heading of any wording, as a checklist or
+   numbered items, as "done when" prose, with ids or without. There is no
+   fixed shape. Keep each criterion's text exactly as the author wrote it.
+   Never reword one. A criterion you think is wrong becomes a note in the
+   final report, never an edit.
+
+   Write them, in the order the issue lists them, to a file:
+
+       { "criteria": [ { "id": "<the id, if the issue gives one>", "text": "<verbatim>", "proof": null } ] }
+
+   Give `proof` an artifact kind (`video`, `screenshot`, `report`, `log`,
+   `test` or `file`) only when the issue states that proof explicitly, as in
+   `(proof: screenshot)`. Never infer a proof kind from the words. Then run:
+
+       node .outerlayer/skills/outerlayer-build/scripts/record-criteria.mjs --item "$OUTERLAYER_WORK" --criteria-file <file>
+
+   The script keeps the issue's ids only when every criterion carries one
+   that fits the id grammar. Otherwise, a partly numbered list included, it
+   numbers every criterion `AC-<item number>-NN` in order, and the state file
+   says why. The final report says the criteria were numbered and from what.
+   A file the script cannot use exits 2 with the reason. Fix the file and
+   run it again.
+
+   When the issue has no criteria anywhere, draft them from the issue's
+   description. Each is one observable behavior the description asks for, in
+   its words, adding no scope it does not state. Write them to the same kind
+   of file without ids, set `proof` only when the description asks for that
+   proof, and run the script with `--drafted` added. It numbers the draft
+   `AC-<item number>-NN` and records it with `drafted: true`, so the Criteria
+   tab says the build drafted the list.
+
+   The script writes the list to
+   `"$(git rev-parse --absolute-git-dir)/build-reports/criteria.json"` and runs
+   `outerlayer emit criteria` on it. The gateway decides whether a list may be
+   recorded. A 409 means the item already has a recorded list. That list
+   stands, and nothing is recorded. No command returns the item's list, so the
+   build cannot read it: it holds the work to its own reading of the criteria
+   and says so in the final report. Any other refusal is written to the state
+   file with its message, and the build continues. The script writes the
+   outcome under `criteria` in the state file: `source` (`issue`, `drafted`,
+   `item`, or `none` when even a draft holds no criterion), `recorded`,
+   `count`, `list` and `numbered`. On a 409, `list` is empty, and the build's
+   reading of the criteria goes under `issueReading`.
+
+   Drafted criteria are tiered, proven and judged like any others. A drafted
+   list stands like any recorded list. A later build's record
+   answers 409 until a person replaces the list with
+   `outerlayer emit criteria`, even after criteria are added to the issue. The
+   final report says the criteria were drafted and how to replace them.
+
+   Change nothing in the issue. The intake summary names how many criteria
+   were recorded, whether they kept the issue's ids or were numbered, and
+   whether they were drafted.
+3. **Implement.** Run `outerlayer emit step "Implement" --item "$OUTERLAYER_WORK"`,
+   then apply the team's changes for this phase. When `OUTERLAYER_BRANCH` is set, as it is in a host's
+   build, work on that branch, checking it out if it is not current, and
+   push only to it: the host refuses a push to any other branch. Otherwise
+   branch `feat/<slug>` from the default branch, with the branch prefix setting in place of `feat/`. Spawn the implementer with the Implementer brief from
+   [references/agent-briefs.md](references/agent-briefs.md), the issue, the
+   drafted criteria with their ids when the build drafted them, the branch
+   and the instructions-file pointer. The phase ends when the
+   repository's own pre-push checks and tests pass on the branch. Review
+   never opens on a red branch. A branch that cannot go green escalates.
+
+   The implementer runs on the Implementing model setting. Default: the model
+   the session runs on.
+
+   A planning step the team adds runs on the Planning model setting. Default:
+   the model the session runs on.
+
+   The phase's gate is the Gate command setting. Default: the repository's own
+   pre-push checks and tests.
+4. **Review.** Run `outerlayer emit step "Review" --item "$OUTERLAYER_WORK"`,
+   then apply the team's changes for this phase. Read [references/review-loop.md](references/review-loop.md) on
+   entry and run it. It sizes the panel to the finished diff: one generalist
+   for a small diff, the generalist and one focused reviewer for a medium
+   one, the generalist and up to three for a large or risky one. Findings are
+   merged into classes, checked by a refuter, fixed, and rechecked once. Then
+   write the review report as an HTML file and emit it:
+
+       outerlayer emit artifact <report>.html --caption "Review of the change and what it found"
+
+   Its verdict is recorded on the `code-review` check once the pull request
+   is open, as release.md says.
+
+5. **Pull request.** Run `outerlayer emit step "Pull request" --item "$OUTERLAYER_WORK"`,
+   then apply the team's changes for this phase. Read [references/release.md](references/release.md)
+   on entry and run it. A release agent rebases, gates and pushes. Open the
+   pull request as release.md says: a runner build with `outerlayer work open-pr`,
+   which links it, and a local session with `gh pr create` and then
+   `outerlayer work pr <number>`. When the build recorded criteria, from the issue or drafted, a fresh agent judges them with
+   [references/criteria-judge.md](references/criteria-judge.md), and the
+   judge's HTML report is linked to its tests and emitted:
+
+       node .outerlayer/skills/outerlayer-build/scripts/criterion-citations.mjs --report <judge-report>.html
+       outerlayer emit artifact <judge-report>.html --for acceptance-criteria --caption "Each criterion judged against its test"
+
+   The build does not record that verdict: the factory host judges the
+   criteria itself and records the `acceptance-criteria` check, as release.md
+   says. When the state file holds no criteria, no judge runs.
+   Watch CI until every check has concluded.
+6. **Evidence.** Run `outerlayer emit step "Evidence" --item "$OUTERLAYER_WORK"`,
+   then apply the team's changes for this phase. Read [references/evidence.md](references/evidence.md)
+   when the pull request opens, and run it. Capture the proof each criterion
+   declares, emit it.
+
+Optional steps a team may turn off: the manual test and screenshots in the
+Evidence phase, for a repository with no user interface.
+
+## Ending the run
+
+Run this last, after the pull request is open and the evidence is emitted, and
+run no other tool call after it:
+
+    outerlayer work release --item "$OUTERLAYER_WORK"
+
+A session that names a work item holds a lease on it, and review stays closed
+until the lease is released. In a session this command releases the session's
+own lease and no one else's. A later tool call takes the lease again, so write
+the final report as plain text once this has run. Skip this step in a runner
+build, whose host releases its own lease. Then end the run with the final
+report. The report lists:
+
+- every candidate issue and every assumption;
+- the team's changes applied, by phase, and each overlap between a change and
+  a core step;
+- each change the run could not apply, and the conflicts where the core won.

package/skill-pack/{template/build → maintained/outerlayer-build}/references/evidence.md

@@ -1,9 +1,9 @@
-# Phase 6: manual test and evidence
+# Evidence phase: manual test and evidence
 
 Read this when the pull request opens. The evidence agent starts then, in the
 same wave as the CI watch. Everything after it in this file runs once CI is
 conclusive and the evidence agent has returned. It deletes the state file and
-the report directory, then phase 7 releases the lease and ends the run. The evidence
+the report directory, then the run ends as "Ending the run" in SKILL.md says. The evidence
 brief is in [agent-briefs.md](agent-briefs.md). Read every value from an
 earlier phase from the state file.
 

package/skill-pack/{template/build → maintained/outerlayer-build}/references/release.md

@@ -1,4 +1,4 @@
-# Phase 5: sync and pull request
+# Pull request phase: sync and pull request
 
 Run this once the review loop reaches zero confirmed blocking findings. The
 release briefs are in [agent-briefs.md](agent-briefs.md). Read every value
@@ -76,7 +76,7 @@ The judge writes an HTML report with one verdict per criterion. Link each
 criterion to the tests that cite it, which the Criteria tab lists. With several
 judges, run it on the merged report. Then emit it:
 
-    node .outerlayer/skills/build/scripts/criterion-citations.mjs --report <judge-report>.html
+    node .outerlayer/skills/outerlayer-build/scripts/criterion-citations.mjs --report <judge-report>.html
     outerlayer emit artifact <judge-report>.html --for acceptance-criteria --caption "Each criterion judged against the test that cites it"
 
 Then run `outerlayer sync`. List every unsatisfied criterion in the final
@@ -115,8 +115,8 @@ captures, so the two waits overlap.
 
 Act on the release agent's return. A failed check has the standing of a red
 gate: fix it within the review phase's remaining budget or escalate. Never
-carry it into phase 6. A persistent unknown mergeability escalates. A
+carry it into the Evidence phase. A persistent unknown mergeability escalates. A
 conflict means one more sync through the release agent, told it is a resync so
 it gates the merge's diff and not the branch's. A second conflict escalates.
 Any fix or sync that lands after the evidence agent captured goes through
-phase 6's late-commit rule.
+the Evidence phase's late-commit rule.

package/skill-pack/{template/build → maintained/outerlayer-build}/references/review-loop.md

@@ -1,4 +1,4 @@
-# Phase 4: the review loop
+# Review phase: the review loop
 
 Run this after the implementer's branch is green and before anything is
 pushed. The reviewer, refuter and mutation briefs are in
@@ -64,6 +64,8 @@ Models: use one model for every review role unless the team says otherwise.
 A reviewer on a risky surface, or the refuter of a blocking class, never
 moves to a weaker model than the rest.
 
+The Reviewing model setting names that model. Default: the model the session runs on.
+
 ## Panel
 
 Write `build-reports/round-1-bundle.md` first: the branch diff against its

package/skill-pack/shipped.json

@@ -14,6 +14,7 @@
       "815c0b5816511e8f7c927aa3fd3bf386537dcdd039b9c6ec4d18d30c8c3c9b1a",
       "93953397c31d47a6f1c06edb8ae2190e1d8a3fca20c616deb33991311cee39a8",
       "a6743050c5c387e962ad4264526d9a3c10edf36823e4b6829f200bf79a4e45e7",
+      "a68ead00e1d1789896380a45c1b3d00a62d5c2bc0e041fe9225345fb07537e49",
       "a7671ebf0d8f4119b77ed9322d4070e1a7f0c94108b8ad17925b985f677cd37a",
       "b0aa9b6962675f772b67a4390c15b6b0100390983d958c656a826a066399f3d0",
       "b95986e95ea3b1ef4202f7f0c00bfcd35865d4fda033b3d6947a5bb9d33cd24c",
@@ -93,6 +94,7 @@
       "b00f5970b568159ca0bfbc75c3834938749ad5e2e73a80769d88bbe3c8c26737"
     ],
     ".outerlayer/validators/acceptance-criteria.yaml": [
+      "1e0e10fb2296ca1b2458036993abe2a13cb7fafffb0d95502fc878ec3aae4142",
       "3b2054aa1d4bd9f7441e88eec1a3bdf61b61ad00efa79736e26a5dd601d43910",
       "79679ed304b64f2b100dab2a24e91aa403a0a831e5a91ef4e6d7e7f06478ada0",
       "ca0da7d98a7922577d9725b615510f964de4d49987697b956d5ac1a45a3d2c6a",