cmoriarty/braid
1
0
Fork 0
Code Issues 15 Pull requests Projects Releases Packages 1 Wiki Activity Actions

Step and band names that say what they do #142

New issue
Closed
opened 2026-10-04 23:07:18 -04:00 by cmoriarty · 2 comments
cmoriarty commented 2026-10-04 23:07:18 -04:00
Owner
Copy link

Several names on the spine don't say what the step does, and two read as OpenSpec functions that OpenSpec doesn't have.

Agent steps named as OpenSpec work. openspec.revise (and openspec.revise.r2) acts on the proposal review's blocking findings, and openspec.repair fixes a change that fails openspec validate --strict. Both run prompts of Braid's own. OpenSpec 1.10.0 has no revise or repair command, and no such /opsx workflow; the nearest, /opsx:update, shows each edit to a person and writes only once they confirm it. #52 moved Braid's own agent work to agent.*, and kept openspec.revise because it rewrites the change's artifacts.

Names that don't say what the step does:

Now Becomes What it does
openspec.revise, .r2 agent.revise, .r2 revises the proposal from the review's blocking findings
openspec.repair agent.repair fixes a change that fails strict validation
script.review-outcome script.record-review-decision saves the answer given at the proposal review, and what the review cost
script.deps, script.deps.tests script.dependencies, script.dependencies.tests installs the dependencies, and again after implementing
agent.test.scenarios agent.write-spec-tests writes a test for each example (scenario) in the change's spec that has none
script.verify, .r2, .r3 script.run-tests, .r2, .r3 runs the project's test commands, with no model
fix.repair, .r2 agent.fix, .r2 fixes what the tests or the judge found, in the implementer's session
script.fix-outcome script.confirm-checks-passed passes only if the last round passed on the code about to be committed
script.plan-tick script.update-plan ticks the plan's item the run carries out
fix.implement, fix.summarize agent.implement, agent.summarize the quick fix's implementer and its summary

Bands: SHIP becomes PULL REQUEST, and LAND becomes MERGE & ARCHIVE, or MERGE in a run with nothing to archive.

The naming rule narrows to match: openspec.* is a step that does an OpenSpec command or /opsx workflow, an agent doing Braid's own work is agent.*, and the fix.* prefix goes. Runs recorded with the old ids must still be drawn as they are now, and a run in flight keeps the pipeline it was admitted with (#102).

Several names on the spine don't say what the step does, and two read as OpenSpec functions that OpenSpec doesn't have. **Agent steps named as OpenSpec work.** `openspec.revise` (and `openspec.revise.r2`) acts on the proposal review's blocking findings, and `openspec.repair` fixes a change that fails `openspec validate --strict`. Both run prompts of Braid's own. OpenSpec 1.10.0 has no revise or repair command, and no such `/opsx` workflow; the nearest, `/opsx:update`, shows each edit to a person and writes only once they confirm it. #52 moved Braid's own agent work to `agent.*`, and kept `openspec.revise` because it rewrites the change's artifacts. **Names that don't say what the step does:** | Now | Becomes | What it does | |---|---|---| | `openspec.revise`, `.r2` | `agent.revise`, `.r2` | revises the proposal from the review's blocking findings | | `openspec.repair` | `agent.repair` | fixes a change that fails strict validation | | `script.review-outcome` | `script.record-review-decision` | saves the answer given at the proposal review, and what the review cost | | `script.deps`, `script.deps.tests` | `script.dependencies`, `script.dependencies.tests` | installs the dependencies, and again after implementing | | `agent.test.scenarios` | `agent.write-spec-tests` | writes a test for each example (scenario) in the change's spec that has none | | `script.verify`, `.r2`, `.r3` | `script.run-tests`, `.r2`, `.r3` | runs the project's test commands, with no model | | `fix.repair`, `.r2` | `agent.fix`, `.r2` | fixes what the tests or the judge found, in the implementer's session | | `script.fix-outcome` | `script.confirm-checks-passed` | passes only if the last round passed on the code about to be committed | | `script.plan-tick` | `script.update-plan` | ticks the plan's item the run carries out | | `fix.implement`, `fix.summarize` | `agent.implement`, `agent.summarize` | the quick fix's implementer and its summary | **Bands:** SHIP becomes PULL REQUEST, and LAND becomes MERGE & ARCHIVE, or MERGE in a run with nothing to archive. The naming rule narrows to match: `openspec.*` is a step that does an OpenSpec command or `/opsx` workflow, an agent doing Braid's own work is `agent.*`, and the `fix.*` prefix goes. Runs recorded with the old ids must still be drawn as they are now, and a run in flight keeps the pipeline it was admitted with (#102).
cmoriarty commented 2026-10-04 23:48:35 -04:00
Author
Owner
Copy link

Shipped: clearer-step-names, deployed as eb1161c and archived in openspec/changes/archive/2026-10-04-clearer-step-names.

Renamed, in every built-in pipeline that has them:

Was Now
openspec.revise, .r2 agent.revise, .r2
openspec.repair agent.repair
script.review-outcome script.record-review-decision
script.deps, script.deps.tests script.dependencies, script.dependencies.tests
agent.test.scenarios agent.write-spec-tests
script.verify, .r2, .r3 script.run-tests, .r2, .r3
fix.repair, .r2 agent.fix, .r2
script.fix-outcome script.confirm-checks-passed
script.plan-tick script.update-plan
fix.implement agent.implement
fix.summarize agent.summarize, the step the OpenSpec pipelines already had
  • Bands: SHIP is PULL REQUEST, and LAND is MERGE & ARCHIVE, or MERGE in a run with nothing to archive (a quick fix, a docs run, a plan). The run bar's stepper says the same.
  • The naming rule: openspec.* is a step that does an OpenSpec command or /opsx workflow (explore, new change, propose, validate, apply, archive). An agent doing Braid's own work is agent.*, whatever it edits, and the fix.* prefix is gone.
  • Purposes in plain words: agent.write-spec-tests reads "Write tests for the parts of the spec no test covers", and script.confirm-checks-passed reads "Confirm the tests and the judge passed".
  • Unchanged: what each step does, and its prompts, conditions, checks and files.

Runs recorded before. The console groups and describes the old ids as it did, so finished runs read the same. No built-in command changed, so a run admitted before the deploy still loads its recorded graph. One consequence: openspec.validate's failure message still says "openspec.repair fixes it". Rewording it would stop older runs loading their graphs, and it can change the next time that command does.

Verified

  • Every built-in pipeline is the same graph as before under the new ids, and no command changed.
  • Fast lane passed, with 167 browser specs. Full lane: 2,597 backend, 562 vitest, 181 browser.
  • On production:
    • the container's built-ins have no old id;
    • the recorded graphs of the last eight runs load;
    • the console draws run 46's old-id steps in the same bands, now PULL REQUEST and MERGE & ARCHIVE, and a quick fix ends with MERGE.
  • No run has used the new ids yet: trogdor is busy.
Shipped: `clearer-step-names`, deployed as eb1161c and archived in `openspec/changes/archive/2026-10-04-clearer-step-names`. **Renamed**, in every built-in pipeline that has them: | Was | Now | |---|---| | `openspec.revise`, `.r2` | `agent.revise`, `.r2` | | `openspec.repair` | `agent.repair` | | `script.review-outcome` | `script.record-review-decision` | | `script.deps`, `script.deps.tests` | `script.dependencies`, `script.dependencies.tests` | | `agent.test.scenarios` | `agent.write-spec-tests` | | `script.verify`, `.r2`, `.r3` | `script.run-tests`, `.r2`, `.r3` | | `fix.repair`, `.r2` | `agent.fix`, `.r2` | | `script.fix-outcome` | `script.confirm-checks-passed` | | `script.plan-tick` | `script.update-plan` | | `fix.implement` | `agent.implement` | | `fix.summarize` | `agent.summarize`, the step the OpenSpec pipelines already had | - **Bands:** SHIP is PULL REQUEST, and LAND is MERGE & ARCHIVE, or MERGE in a run with nothing to archive (a quick fix, a docs run, a plan). The run bar's stepper says the same. - **The naming rule:** `openspec.*` is a step that does an OpenSpec command or `/opsx` workflow (explore, new change, propose, validate, apply, archive). An agent doing Braid's own work is `agent.*`, whatever it edits, and the `fix.*` prefix is gone. - **Purposes in plain words:** `agent.write-spec-tests` reads "Write tests for the parts of the spec no test covers", and `script.confirm-checks-passed` reads "Confirm the tests and the judge passed". - **Unchanged:** what each step does, and its prompts, conditions, checks and files. **Runs recorded before.** The console groups and describes the old ids as it did, so finished runs read the same. No built-in command changed, so a run admitted before the deploy still loads its recorded graph. One consequence: `openspec.validate`'s failure message still says "openspec.repair fixes it". Rewording it would stop older runs loading their graphs, and it can change the next time that command does. **Verified** - Every built-in pipeline is the same graph as before under the new ids, and no command changed. - Fast lane passed, with 167 browser specs. Full lane: 2,597 backend, 562 vitest, 181 browser. - On production: - the container's built-ins have no old id; - the recorded graphs of the last eight runs load; - the console draws run 46's old-id steps in the same bands, now PULL REQUEST and MERGE & ARCHIVE, and a quick fix ends with MERGE. - No run has used the new ids yet: trogdor is busy.
cmoriarty commented 2026-10-05 10:41:41 -04:00
Author
Owner
Copy link

The first run under the new names is run 47 (run_01M46705KJ27XX2VXKFJVNCM16), #139's baseline, started 2026-10-05 at 14:20Z:

  • Its graph has every new id: agent.repair, agent.revise, script.record-review-decision, script.dependencies and script.dependencies.tests, agent.write-spec-tests, script.run-tests, agent.fix, script.confirm-checks-passed and script.update-plan.
  • agent.repair was skipped as not needed, because the change validated on the first try.
  • On production's console, each step is in its band, and the last two bands read PULL REQUEST and MERGE & ARCHIVE. The pages had no errors.

The remaining steps run as the run goes on. #139's results will report any that misbehaves.

**The first run under the new names is run 47** (`run_01M46705KJ27XX2VXKFJVNCM16`), #139's baseline, started 2026-10-05 at 14:20Z: - Its graph has every new id: `agent.repair`, `agent.revise`, `script.record-review-decision`, `script.dependencies` and `script.dependencies.tests`, `agent.write-spec-tests`, `script.run-tests`, `agent.fix`, `script.confirm-checks-passed` and `script.update-plan`. - `agent.repair` was skipped as not needed, because the change validated on the first try. - On production's console, each step is in its band, and the last two bands read PULL REQUEST and MERGE & ARCHIVE. The pages had no errors. The remaining steps run as the run goes on. #139's results will report any that misbehaves.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
archive/prefect-kestra-experiments
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cmoriarty/braid#142
No description provided.