Architecture v2: branch-based pipelines, five phases, multilane

.changeset/README.md

@@ -1,16 +1,7 @@
 # Changesets
 
-Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
-with multi-package repos, or single-package repos to help you version your code. You can
-find the full documentation for it [in our repository](https://github.com/changesets/changesets).
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works with multi-package repos, or single-package repos to help you version your code. You can find the full documentation for it [in our repository](https://github.com/changesets/changesets).
 
-We have a quick list of common questions to get you started engaging with this project in
-[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md).
+We have a quick list of common questions to get you started engaging with this project in [our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md).
 
-This package is `private`, so there is no registry publish — but releases are CI-driven. Changesets open
-a "Version Packages" PR that bumps the version and updates the changelog; merging that PR creates a
-`v<version>` git tag and a GitHub Release. This `README.md` is the changesets cheat-sheet generated once by
-`changeset init`; it is hand-customized and is not regenerated by `changeset version`, so edits here are
-safe. See the ["Changelog and versioning"](../README.md#changelog-and-versioning) section of the root
-[`README.md`](../README.md) and [`CONTRIBUTING.md`](../CONTRIBUTING.md) for how to add a changeset and how
-the release flow works.
+This package is `private`, so there is no registry publish — but releases are CI-driven. Changesets open a "Version Packages" PR that bumps the version and updates the changelog; merging that PR creates a `v<version>` git tag and a GitHub Release. This `README.md` is the changesets cheat-sheet generated once by `changeset init`; it is hand-customized and is not regenerated by `changeset version`, so edits here are safe. See the ["Changelog and versioning"](../README.md#changelog-and-versioning) section of the root [`README.md`](../README.md) and [`CONTRIBUTING.md`](../CONTRIBUTING.md) for how to add a changeset and how the release flow works.

.changeset/ambient-gate-failures.md

@@ -0,0 +1,5 @@
+---
+"@automattic/radical-pipelines": patch
+---
+
+Gate failures are never classified as pre-existing or environmental without proof. Reviewers require reproducing the identical failure on the run's diff base before treating a failure as ambient; writers fix the failure or report a blocker instead of committing around it; the untouched-test heuristic is forbidden for both.

.changeset/architecture-v2-consistency.md

@@ -0,0 +1,5 @@
+---
+"@automattic/radical-pipelines": patch
+---
+
+Fix architecture-v2 consistency leftovers: drop the revision flow's dangling `pipeline.md` step, align the glossary's lane entries and Conventions-block fields with the lane-scoped folder model, replace the nonexistent `/loop-list`/`/loop-kill` commands with Claude Code's `CronList`/`CronDelete` tools, remove duplicated and undefined workflow instructions, generalize the blocker payload to name the approved artifact that must change, make cross-folder references and the reviewer/researcher profiles symmetric across phases, update the website to the five-phase architecture and current agent set, and remove the leftover Pi settings file and stale working documents.

.changeset/architecture-v2.md

@@ -0,0 +1,5 @@
+---
+"@automattic/radical-pipelines": minor
+---
+
+Architecture v2. The pipeline is now five phases (Intent → Spec → Design doc → Build → Document): the standalone Plan phase is gone, folded into Build and Document as an inner plan-approval gate. Pipelines are chains of run branches with lane branches, and forks are new pipeline versions created by branching at cut commits — inherited history carries the inherited work itself, with no copying. The spec and design-doc phases run as N independent lanes consolidated into one artifact by new consolidator agents (N=1 is the default single flow), each lane writing its artifacts in a `lane-<K>` subfolder of the phase folder so the full lane record lands on the run branch. Design-doc lanes support isolated and divergent modes: isolated lanes run in parallel on lane branches merged back on approval; divergent lanes run sequentially on the run branch itself. Worktrees are raw `git worktree` checkouts, one per branch, with all branch and worktree topology owned by the orchestrator, which seats each agent in its worktree at spawn per the now-required per-tool Team spawning convention. Agents are renamed to the phase-prefixed set: `build-plan-writer`/`build-plan-reviewer`, `build-writer-tdd`/`build-writer-e2e`/`build-reviewer`, `document-plan-writer`/`document-plan-reviewer`, `document-writer`/`document-reviewer`, plus the new `design-doc-consolidator`.

.changeset/claude-code-teammates.md

@@ -0,0 +1,5 @@
+---
+"@automattic/radical-pipelines": patch
+---
+
+Spawn Claude Code agents as teammates, matching Claude Code's current agent-teams model where each session has one implicit team and named teammates message each other and the orchestrator directly.

.changeset/confirm-revision-intent.md

@@ -0,0 +1,5 @@
+---
+"@automattic/radical-pipelines": patch
+---
+
+The revision intent is always rendered to the owner and explicitly approved before it is written and the revision run starts.

.changeset/dependency-gate.md

@@ -0,0 +1,5 @@
+---
+"@automattic/radical-pipelines": patch
+---
+
+Before starting work on an issue, open dependencies are surfaced and the owner explicitly chooses to proceed or wait; issues without declared dependencies proceed unchanged.

.changeset/drop-pi-support.md

@@ -0,0 +1,5 @@
+---
+"@automattic/radical-pipelines": minor
+---
+
+BREAKING: Remove Pi as a supported agentic coding tool. The repository is now solely a Claude Code plugin and a standalone agent skill: the root `package.json` is no longer a Pi manifest (its `pi` block, the bundled `pi-teams` and `@pi-agents/loop` dependencies, the Pi peer dependencies, and the `pi-package` keyword are gone), the Pi convention file and the Pi-specific setup, README, and website sections are removed, and the setup convention table lists only Claude Code.

.changeset/inline-summary-format.md

@@ -0,0 +1,5 @@
+---
+"@automattic/radical-pipelines": patch
+---
+
+Inline the per-phase summary format into the `build-reviewer` and `document-reviewer` profiles instead of holding it in a standalone `reference/summary-format.md` that the orchestrator resolved and passed in each reviewer's launch prompt. The reviewer is the only agent with the whole-phase view and already authors the summary, so the format now lives at its point of use in each profile and the orchestrator no longer couriers it.

.changeset/no-unverified-hedges.md

@@ -0,0 +1,5 @@
+---
+"@automattic/radical-pipelines": patch
+---
+
+Reviewers reject artifacts whose correctness rests on an unverified hedge: each load-bearing hedged risk is verified, sent back, or recorded as an accepted residual with justification before approval.

.changeset/premise-verification.md

@@ -0,0 +1,5 @@
+---
+"@automattic/radical-pipelines": patch
+---
+
+Require analysts to send a new load-bearing claim — especially a known rule's premise — to the researcher before it sways a requirement or decision.

.changeset/rejection-iteration-budget.md

@@ -0,0 +1,5 @@
+---
+"@automattic/radical-pipelines": patch
+---
+
+Rejection loops are checkpointed: every three consecutive rejections the orchestrator inspects their cause and stops the run only when the same pattern repeats and could perpetuate indefinitely.

.changeset/search-related-issues.md

@@ -0,0 +1,5 @@
+---
+"@automattic/radical-pipelines": patch
+---
+
+Before creating an issue, the orchestrator searches the tracker for related or duplicate issues and presents them with the draft so the owner can proceed, modify the existing issue, or link it.

.changeset/setup-only-defined-conventions.md

@@ -0,0 +1,5 @@
+---
+"@automattic/radical-pipelines": patch
+---
+
+Setup writes only the defined conventions into `.rp.md` — anything beyond them, like orchestrator instructions or setup-time discoveries, is captured only on explicit owner request. The Claude Code conventions keep only their tool-specific values; the orchestrator instructions they held move into the workflow and health-monitoring references or drop where those already state them.

.changeset/unbundle-pi-worktrees.md

@@ -0,0 +1,5 @@
+---
+"@automattic/radical-pipelines": patch
+---
+
+Stop bundling `@zenobius/pi-worktrees`: worktree handling is raw `git worktree` owned by the orchestrator, so the extension is no longer used.

.changeset/verbatim-evidence-relay.md

@@ -0,0 +1,5 @@
+---
+"@automattic/radical-pipelines": patch
+---
+
+When a launch prompt carries prior-phase evidence — such as a rejection's issues — the orchestrator passes it verbatim, never interpreted or framed.

.github/PULL_REQUEST_TEMPLATE.md

@@ -12,6 +12,10 @@ Closes #
 
 <!-- How does it work? Key implementation details or approach. -->
 
+## Review guide
+
+<!-- The order to read the changes in and what to focus on at each step, so a reviewer can follow the reasoning instead of piecing it together from the diff. -->
+
 ## Changeset
 
 - [ ] I confirm I have added a changeset or a changeset is not relevant for this change (see [CONTRIBUTING.md](../CONTRIBUTING.md) for details).

.gitignore

@@ -2,5 +2,6 @@ node_modules/
 .env
 .env.local
 .rp.local.md
+.worktrees/
 .claude/worktrees/
 .claude/scheduled_tasks.lock

.rp.md

@@ -1,12 +1,12 @@
 # Radical Pipelines project conventions
 
-This file holds the conventions for this project. The shared section applies to every agentic coding tool used here; the per-tool sections add conventions specific to Claude Code and Pi. Read the shared section plus the section for the active tool at the start of any workflow.
+This file holds the conventions for this project: a shared section that applies regardless of the agentic coding tool, plus a Claude Code section.
 
 ## Shared conventions
 
-### Managing tasks
+### Issues
 
-All tasks are tracked in two mirrored trackers. **GitHub is the source of truth**; Linear mirrors it for status tracking only.
+All issues are tracked in two mirrored trackers. **GitHub is the source of truth**; Linear mirrors it for status tracking only.
 
 - **GitHub**: https://github.com/Automattic/radical-pipelines — accessed via the `gh` CLI.
 - **Linear**: the Linear project with id `15a89be6fe3c` — accessed via the Linear MCP and filtered by the `radical-pipelines` label. Both the project and the label live in the **Billow** team (id `49ae3cbc-a6f1-4c22-a064-1ef8f168aeff`); scope label lookups to that team.
@@ -25,26 +25,30 @@ Edit the GitHub issue description using `gh`. Do not modify the Linear descripti
 
 #### Orchestrator updates during a run
 
-In addition to the normal pipeline workflow, the orchestrator must keep the Linear issue in sync with pipeline activity and push the pipeline branch at the end of every run.
+In addition to the normal pipeline workflow, the orchestrator must keep the Linear issue in sync with pipeline activity and push the run branch at the end of every run.
 
 All Linear operations use the Linear MCP. To find the Linear issue that mirrors a given GitHub issue, search Linear via the MCP for the GitHub issue URL — it lives in the Linear issue's description.
 
 - **At run start** — add the `running…` label to the Linear issue before launching anything.
 - **At run end** — remove the `running…` label. This applies to every outcome: normal close-out, blockers, owner-cancelled runs, and failures.
-- **Push at run close-out** — push the pipeline branch to the remote. This happens after the final commit of the run has landed locally and applies to every outcome: normal close-out, blockers, owner-cancelled runs, and failures.
-- **When a phase finishes** — set the Linear issue status to match the phase that just satisfied its completion predicate: `0 - Intent` after the pipeline is created, then `1 - Spec`, `2 - Design Doc`, `3 - Plan`, `4 - Code`, `5 - Docs` as each phase completes. Update the status **immediately when the phase finishes**, before launching the next phase — never wait until the end of the run. For a revision run the status re-cycles from `1 - Spec` through `5 - Docs` as the revision's phases complete; `0 - Intent` is set only when the pipeline is first created, not on a revision's intent.
+- **Push at run close-out** — push the run branch and its lane branches to the remote. This happens after the final commit of the run has landed locally and applies to every outcome: normal close-out, blockers, owner-cancelled runs, and failures.
+- **When a phase finishes** — set the Linear issue status to match the phase that just satisfied its completion predicate: `0 - Intent` after the pipeline is created, then `1 - Spec`, `2 - Design Doc`, `3 - Build`, `4 - Document` as each phase completes. Update the status **immediately when the phase finishes**, before launching the next phase — never wait until the end of the run. For a revision run the status re-cycles from `1 - Spec` through `4 - Document` as the revision's phases complete; `0 - Intent` is set only when the pipeline is first created, not on a revision's intent.
 - **Pipeline version label** — when starting work on a pipeline (creating, resuming, forking, or revising), make sure the Linear issue carries exactly one version label matching the active pipeline (`v1`, `v2`, …). Remove any other version labels first, then add the current one if it isn't already present.
 - **Assignee** — when starting work on a pipeline (creating, resuming, forking, or revising), assign the Linear issue to the person running it: the current Linear user, found via the Linear MCP. Overwrite whoever was assigned before.
 
 These updates apply to both autonomous and assisted runs.
 
-### Pipeline slugs
+### Branch name base
 
-Use `<issue-number>-<short-description>` where `issue-number` is the **GitHub** issue number. Even though a parallel Linear issue exists, the slug always keys off the GitHub id — never the Linear id.
+`<branch-base>` is `<issue-number>-<short-description>`, where `<issue-number>` is the **GitHub** issue number (never the Linear id) and `<short-description>` is lowercase kebab-case. It must not contain `_`.
 
-### Artifact folders
+### Pipeline family folder
 
-Use `.pipelines/<slug>`.
+`.pipelines/<branch-base>`
+
+### Artifact storage
+
+`artifacts-in-repo` — `.rp.md`, the pipeline family folder, and the worktree-root `.gitignore` entry live in this repository.
 
 ### Commit format
 
@@ -54,54 +58,56 @@ Examples:
 
 - `Add intent (orchestrator)`
 - `Add spec (spec-reviewer)`
-- `Support for X (implementer)`
+- `Support for X (build-writer-tdd)`
 - `Fix bug Y (assisted)`
 
-### Worktrees
+### Worktree root
 
-Folder: `.claude/worktrees/<pipeline-slug>`
-Enter worktree: `EnterWorktree` with name: `<pipeline-slug>`
-Exit worktree: `ExitWorktree` with name: `<pipeline-slug>`
+Worktrees live under `.worktrees/` — one worktree per branch, at `.worktrees/<branch>`.
 
-### Branch names
+### Guardrails
 
-Created automatically by `EnterWorktree`: `worktree-<pipeline-slug>`
+#### tests
 
-### Team spawning
+- command: `npm test`
+- agents: build-writer-tdd, build-writer-e2e, build-reviewer
 
-Create the team with `TeamCreate({ name: "<pipeline-slug>-<random-suffix>" })` — a fresh random suffix per creation.
+## Claude Code conventions
 
-Be aware that teams include a shared task list and idle teammates are nudged to claim unassigned, unblocked tasks from it so track phase progress in the phase subfolders, never on the task list.
+### Team spawning
+
+Spawn each agent as a Claude Code teammate. A teammate starts in the orchestrator's shell working directory at spawn time, and a directory change inside a teammate does not persist to its next command — its start directory is fixed for its whole run. To seat an agent: `cd` into its worktree, spawn the agent, then `cd` back. Never use Claude Code's worktree tools (`EnterWorktree`/`ExitWorktree`) during a run — a worktree switch is session-wide and retargets the working directory of every running agent.
 
 ### Agent models
 
 Before starting a pipeline run in autonomous mode, always ask the owner which difficulty to apply:
 
-| Agent                   | low    | medium | high   |
-| ----------------------- | ------ | ------ | ------ |
-| `spec-analyst`          | opus   | opus   | fable  |
-| `spec-researcher`       | sonnet | opus   | opus   |
-| `spec-writer`           | sonnet | sonnet | opus   |
-| `spec-reviewer`         | opus   | opus   | fable  |
-| `design-doc-analyst`    | opus   | fable  | fable  |
-| `design-doc-researcher` | sonnet | opus   | opus   |
-| `design-doc-writer`     | sonnet | sonnet | opus   |
-| `design-doc-reviewer`   | opus   | opus   | fable  |
-| `code-plan-writer`      | sonnet | opus   | opus   |
-| `code-plan-reviewer`    | opus   | opus   | fable  |
-| `doc-plan-writer`       | sonnet | sonnet | opus   |
-| `doc-plan-reviewer`     | opus   | opus   | opus   |
-| `code-writer`           | sonnet | sonnet | sonnet |
-| `code-reviewer`         | opus   | opus   | fable  |
-| `doc-writer`            | sonnet | sonnet | opus   |
-| `doc-reviewer`          | opus   | opus   | opus   |
+| Agent                     | low    | medium | high   |
+| ------------------------- | ------ | ------ | ------ |
+| `spec-analyst`            | opus   | opus   | fable  |
+| `spec-researcher`         | sonnet | opus   | opus   |
+| `spec-writer`             | sonnet | sonnet | opus   |
+| `spec-reviewer`           | opus   | opus   | fable  |
+| `spec-consolidator`       | sonnet | sonnet | opus   |
+| `design-doc-analyst`      | opus   | fable  | fable  |
+| `design-doc-researcher`   | sonnet | opus   | opus   |
+| `design-doc-writer`       | sonnet | sonnet | opus   |
+| `design-doc-reviewer`     | opus   | opus   | fable  |
+| `design-doc-consolidator` | sonnet | sonnet | opus   |
+| `build-plan-writer`       | sonnet | opus   | opus   |
+| `build-plan-reviewer`     | opus   | opus   | fable  |
+| `build-writer-tdd`        | sonnet | sonnet | sonnet |
+| `build-writer-e2e`        | sonnet | sonnet | sonnet |
+| `build-reviewer`          | opus   | opus   | fable  |
+| `document-plan-writer`    | sonnet | sonnet | opus   |
+| `document-plan-reviewer`  | opus   | opus   | opus   |
+| `document-writer`         | sonnet | sonnet | opus   |
+| `document-reviewer`       | opus   | opus   | opus   |
 
 ### Health monitoring
 
-Use the bundled `/loop` skill.
+Use Claude Code's bundled `/loop` skill — no install is required.
 
 - **Start:** `/loop 15m <prompt>` where `<prompt>` is the template from `skills/radical-pipelines/reference/health-monitoring.md`.
-- **List active loops:** `/loop-list`.
-- **Cancel:** `/loop-kill <id>` using the id returned at start.
-
-The orchestrator starts the loop itself.
+- **List active loops:** the `CronList` tool.
+- **Cancel:** the `CronDelete` tool with the loop's task id.

AGENTS.md

@@ -15,3 +15,8 @@ An agent orchestrator that runs teams of agents autonomously through a pipeline
 - The skill must describe the system only as it is designed to work, not transient, historical, or speculative situations. A case earns a place in the skill only when it is a durable part of the design — not a one-off (like a migration leftover) or a future need that doesn't yet exist.
 - Reuse the terms and identifiers the skill already defines instead of introducing new notation for the same concept.
 - The skill is prose, not software. Do not write structural tests that assert the content of skill or agent files — their sections, wording, or ordering. Such tests merely restate the skill and break on every legitimate edit.
+
+## Repository rules
+
+- Every change to the repository records a changeset (authoring guidance in CONTRIBUTING.md).
+- README.md is updated when a change alters behavior it describes.