From de40eb0d86ab8f796ecd4f36491c9d7bbedd374a Mon Sep 17 00:00:00 2001 From: Oriol Torrent Florensa Date: Fri, 22 May 2026 19:44:23 +0200 Subject: [PATCH 1/6] chore: remove ralph-orchestrator and retire docs/plans/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Windows incompatibility in ralph-cli was a hard blocker. All 18 monorepo specs (00–17) are complete; docs/plans/ has no future intake role now that unic-archon-dlc (unic-dlc-build) is the target runner. - Delete all ralph.yml, PROMPT.md, and .ralph/ artifacts (root + 3 plugins) - Remove @ralph-orchestrator/ralph-cli from package.json and pnpm-workspace.yaml - Retire Spec/Spec Runner terms from CONTEXT.md; Feature Runner now backed by unic-dlc-build - Add ADR-0030; mark ADR-0020 and ADR-0024 superseded - Update AGENTS.md, process docs, and per-plugin CLAUDE.md accordingly See docs/adr/0030-retire-ralph-adopt-archon-runner.md. Co-Authored-By: Claude Sonnet 4.6 --- AGENTS.md | 31 +---- CONTEXT-MAP.md | 2 +- CONTEXT.md | 15 +-- PROMPT.md | 106 ---------------- apps/claude-code/auto-format/CLAUDE.md | 4 - apps/claude-code/auto-format/PROMPT.md | 117 ------------------ apps/claude-code/auto-format/ralph.yml | 35 ------ apps/claude-code/pr-review/PROMPT.md | 113 ----------------- apps/claude-code/pr-review/ralph.yml | 35 ------ apps/claude-code/unic-confluence/PROMPT.md | 115 ----------------- apps/claude-code/unic-confluence/ralph.yml | 35 ------ docs/adr/0020-per-plugin-ralph-loops.md | 2 +- docs/adr/0024-ralph-atomic-iteration.md | 2 +- .../0030-retire-ralph-adopt-archon-runner.md | 28 +++++ docs/plans/README.md | 4 +- docs/process/ai-development.md | 46 +++---- docs/process/development-workflow.md | 18 +-- docs/process/ralph-loop-guide.md | 47 ------- package.json | 6 +- pnpm-workspace.yaml | 4 - ralph.yml | 35 ------ 21 files changed, 59 insertions(+), 741 deletions(-) delete mode 100644 PROMPT.md delete mode 100644 apps/claude-code/auto-format/PROMPT.md delete mode 100644 apps/claude-code/auto-format/ralph.yml delete mode 100644 apps/claude-code/pr-review/PROMPT.md delete mode 100644 apps/claude-code/pr-review/ralph.yml delete mode 100644 apps/claude-code/unic-confluence/PROMPT.md delete mode 100644 apps/claude-code/unic-confluence/ralph.yml create mode 100644 docs/adr/0030-retire-ralph-adopt-archon-runner.md delete mode 100644 docs/process/ralph-loop-guide.md delete mode 100644 ralph.yml diff --git a/AGENTS.md b/AGENTS.md index 4600e642..4fd206e6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,16 +21,14 @@ packages/ ├── tsconfig/ # @unic/tsconfig └── release-tools/ # @unic/release-tools (bump / sync-version / tag / verify-changelog) docs/ -└── plans/ # Monorepo-level Spec Runner roadmap (specs 00–14) +└── adr/ # Architectural Decision Records ``` -Each plugin under `apps//` also has its own `docs/plans/` for plugin-specific future work. - ## Navigation - Plugin manifests: `apps///.claude-plugin/plugin.json` and `marketplace.json` - Shared release scripts: `packages/release-tools/scripts/` -- Monorepo roadmap: `docs/plans/` +- Architectural decisions: `docs/adr/` - Process templates: `docs/process/` ## Commands @@ -42,12 +40,10 @@ pnpm format # Biome + Prettier fix (whole tree) pnpm ci:check # same as check, non-interactive (for CI) pnpm test # run tests across all packages pnpm typecheck # type-check across all packages -pnpm ralph # run the monorepo Spec Runner loop (specs 00–14) -# Per-plugin operations (after spec 03 sets up release-tools) +# Per-plugin operations pnpm --filter bump patch # bump plugin version pnpm --filter verify:changelog # check changelog -pnpm --filter ralph # run that plugin's own Spec Runner loop ``` ## Tech stack @@ -110,30 +106,15 @@ To ship a new plugin version: | Push to `develop` | ✓ | ✓ (changed packages) | — | | Push to `main` | ✓ | ✓ (changed packages) | — | -## Spec-driven development - -All work starts with a spec file under `docs/plans/`. Specs follow this format: - -``` -# NN. Title -**Priority:** / **Effort:** / **Version impact:** / **Depends on:** / **Touches:** -## Context -## Current behaviour -## Target behaviour -## Affected files -## Implementation steps -## Verification -## Acceptance criteria -## Out of scope -``` +## Feature-driven development -`pnpm ralph` runs the Spec Runner (currently `ralph-orchestrator`), which implements specs one at a time in a loop. +New work enters through the issue tracker as Features. Use `/tdd` to implement individual issues, or `unic-dlc-build` (via `unic-archon-dlc`) once the harness is set up in this repo. ## Do not add - External runtime deps to plugins unless truly essential (`auto-format` has zero; that's the bar) - Turborepo or other build orchestrators — plain pnpm workspaces is the current choice -- Features not described in an open spec file — open a spec first +- Features not tracked in the issue tracker — open a Feature first ## LICENSE files diff --git a/CONTEXT-MAP.md b/CONTEXT-MAP.md index c6ebe22d..2d6f1cee 100644 --- a/CONTEXT-MAP.md +++ b/CONTEXT-MAP.md @@ -2,7 +2,7 @@ ## Shared vocabulary -- [Monorepo](./CONTEXT.md) — Plugin, Workspace Package, Release, Spec, Spec Runner, Consumer +- [Monorepo](./CONTEXT.md) — Plugin, Workspace Package, Release, Feature, Feature Runner, Consumer ## Plugin contexts diff --git a/CONTEXT.md b/CONTEXT.md index d66161eb..bcdd0f57 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -20,20 +20,12 @@ _Avoid_: package (too generic), library, module A versioned, tagged snapshot of a single Plugin published to `main`. A per-Plugin event — there is no monorepo-wide release. _Avoid_: deploy, publish, version bump -**Spec**: -A structured markdown file under `docs/plans/` that defines a unit of work with context, target behaviour, and acceptance criteria. The atomic input to the Spec Runner. -_Avoid_: ticket, task, issue, story - -**Spec Runner**: -The agent automation that reads Specs and implements them one at a time. Currently backed by `ralph-orchestrator` but the concept is tool-agnostic. -_Avoid_: Ralph, Ralph Orchestrator (tool-specific, not domain terms) - **Feature**: A self-contained unit of work tracked as a directory under `docs/issues//`, containing a PRD and numbered implementation issues. The atomic input to the Feature Runner. _Avoid_: ticket, epic, story **Feature Runner**: -The skill that implements a Feature's issues end-to-end in one worktree, branch, and pull request. Parallel concept to Spec Runner, but driven by the issue tracker rather than `docs/plans/`. +The skill that implements a Feature's issues end-to-end in one worktree, branch, and pull request. Backed by `unic-dlc-build`. _Avoid_: issue runner, queue runner **Consumer**: @@ -45,8 +37,7 @@ _Avoid_: client, user repo, target repo, host repo - A **Plugin** belongs to one agent ecosystem (e.g., Claude Code) and has zero or more **Releases** - A **Claude Code Plugin** is a **Plugin** — the inverse is not always true - A **Workspace Package** supports **Plugin** development but is not itself a **Plugin** -- A **Spec** drives exactly one **Spec Runner** iteration -- A **Feature** drives one **Feature Runner** execution — a Feature is to the Feature Runner what a Spec is to the Spec Runner +- A **Feature** drives one **Feature Runner** execution - A **Consumer** installs one or more **Plugins** ## Example dialogue @@ -57,5 +48,3 @@ _Avoid_: client, user repo, target repo, host repo > **Dev:** "A Consumer reported the auto-format Plugin failing on Windows." > **Domain expert:** "That's a cross-platform gap. Plugins must use Node.js APIs — no shell commands or POSIX paths." -> **Dev:** "Can I use Ralph to implement this Spec?" -> **Domain expert:** "You mean the Spec Runner — Ralph is just the current tool backing it." diff --git a/PROMPT.md b/PROMPT.md deleted file mode 100644 index 735fa6dc..00000000 --- a/PROMPT.md +++ /dev/null @@ -1,106 +0,0 @@ -# Ralph Orchestrator — unic-agents-plugins Roadmap - -You are implementing the roadmap for the `unic-agents-plugins` monorepo, one spec at a time. - -## Step 1 — Determine what's next - -Check the execution order in `docs/plans/README.md`. Then scan spec files in order (00 → 13) and find the first file that does NOT contain the string `**Status: done`. - -If **all** specs contain `**Status: done`, output exactly: - -``` -LOOP_COMPLETE -``` - -…and stop. Do nothing else. - -## Step 2 — Read the spec completely - -Read the entire spec file before writing any code. Pay special attention to: - -- **Current behaviour** — verify the code actually works this way before starting; if it doesn't, add a `## Deviations` section at the bottom of the spec file documenting the discrepancy -- **Out of scope** — list of things you must NOT change in this iteration -- **Depends on** — if a dependency spec is not yet marked done, skip this spec and move to the next one that can be done - -## Step 3 — Implement - -Check the spec's `**Version impact:**` line to choose the implementation approach: - -**`none` (workspace/infrastructure spec)** — implement directly. Follow the "Implementation steps" exactly. If a step's "before" snapshot doesn't match the current file, consult the "Deviations" section (if you wrote one) or document the discrepancy and adapt minimally. - -**`patch` / `minor` / `major` (plugin spec)** — use `/tdd` to drive implementation. Treat the spec's "Implementation steps" as guidance (key files to touch, rough order), not a recipe. The spec's **Acceptance criteria** are the target; the red-green-refactor cycle drives the path there. - -Ground rules (from `docs/plans/README.md`): - -- Use `pnpm` for all package operations (not `npm`) -- Tabs for indentation in `.mjs`/`.js`/`.ts` files, spaces for `.json`/`.yml`/`.yaml` (per `.editorconfig`) -- Conventional commits: `feat(scope): description`, `fix(scope): description`, `chore(scope): description` -- Cross-platform: use Node.js APIs (`node:path`, `node:fs`, `node:os`) instead of shell commands; no bash/sh assumptions -- If something can't be followed as written: document it in `## Deviations`, don't silently deviate - -**Supporting skill:** `/diagnose` — if a failure persists and the root cause appears to be outside the spec's scope (an existing module, tooling, or dependency the spec doesn't touch), use `/diagnose` to isolate it before continuing. - -## Step 4 — Verify - -Run the exact commands in the spec's **Verification** section. Fix any failures before proceeding. - -Check every item in **Acceptance criteria**. If any item fails, fix it. - -Then run the always-on repo hygiene checks regardless of spec type: - -```sh -pnpm check # Biome + Prettier — fix any failures before proceeding -``` - -## Step 4.5 — Version bump (conditional) - -Check the spec's `**Version impact:**` line: - -**`none` (workspace/infrastructure spec)** — skip this step entirely. No CHANGELOG update. Proceed to Step 5. - -**`patch` / `minor` / `major` (plugin: ``)** — bump the specified plugin: - -1. Append one bullet under the matching subsection of `## [Unreleased]` in `apps/claude-code//CHANGELOG.md`: - - - `### Breaking` — CLI flag change, exit-code change, on-disk schema change - - `### Added` — new flag, subcommand, or user-visible feature - - `### Fixed` — bug fix, refactor, docs, internal tooling - -2. Run: `pnpm --filter bump ` - -3. Run: `pnpm --filter verify:changelog` - -## Step 5 — Mark done and commit - -1. Add this line immediately after the spec's `# NN. Title` heading (as the second line): - -``` -**Status: done — YYYY-MM-DD** -``` - -Replace `YYYY-MM-DD` with today's date. - -2. Stage and commit all changes using the appropriate prefix: - -- **Workspace specs** (version impact: none): `git commit -m "chore(spec-NN): "` -- **Plugin specs** (version impact: patch/minor/major): `git commit -m "feat(spec-NN): (vX.Y.Z)"` -- **Migration specs** (05–07): the `git merge --allow-unrelated-histories` creates a first commit; any post-merge fixups go in a second commit: `git commit -m "feat(spec-NN): finalize migration"` - -3. **Do not push.** Commits only. - -## Step 6 — Stop for this iteration - -Output a brief summary of what was implemented and committed. Then stop — Ralph will feed this prompt again for the next spec. - ---- - -## Important constraints - -- Implement **one spec per iteration**. Do not implement multiple specs in a single run. -- If a spec requires human judgment (e.g. choosing between two design approaches not covered by the spec), stop, document the question in a `## Questions` section at the bottom of the spec file, and output: - ``` - LOOP_COMPLETE - ``` - This pauses the loop for human review. -- Do not create any files outside of what the spec describes. -- Do not modify any spec files except to add `**Status: done**`, `## Deviations`, or `## Questions` sections. diff --git a/apps/claude-code/auto-format/CLAUDE.md b/apps/claude-code/auto-format/CLAUDE.md index 20e5c2a6..3143802a 100644 --- a/apps/claude-code/auto-format/CLAUDE.md +++ b/apps/claude-code/auto-format/CLAUDE.md @@ -41,7 +41,3 @@ pnpm verify:changelog # Check CHANGELOG structure - External npm runtime dependencies to the hook script. - Prettier or ESLint bundled inside the plugin — consumers bring their own. - Support for tools outside the Claude Code hook contract (e.g. bash hooks, pre-commit hooks — those belong in consumer repos). - -## Ralph Orchestrator - -This repo uses ralph-orchestrator for iterative development. See `docs/plans/README.md` for the spec roadmap and `PROMPT.md` for the orchestrator loop prompt. diff --git a/apps/claude-code/auto-format/PROMPT.md b/apps/claude-code/auto-format/PROMPT.md deleted file mode 100644 index 6f2119a1..00000000 --- a/apps/claude-code/auto-format/PROMPT.md +++ /dev/null @@ -1,117 +0,0 @@ -# Ralph Orchestrator — unic-claude-code-format Roadmap - -You are implementing the roadmap for the `unic-claude-code-format` Claude Code plugin, one spec at a time. - -## Step 1 — Determine what's next - -Check the execution order in `docs/plans/README.md`. Then scan spec files in order and find the first file that does NOT contain the string `**Status: done`. - -If **all** specs contain `**Status: done**, output exactly: - -``` -LOOP_COMPLETE -``` - -…and stop. Do nothing else. - -## Step 2 — Read the spec completely - -Read the entire spec file before writing any code. Pay special attention to: - -- **Current behaviour** — verify the code actually works this way before starting; if it doesn't, add a `## Deviations` section at the bottom of the spec file documenting the discrepancy -- **Out of scope** — list of things you must NOT change in this iteration -- **Depends on** — if a dependency spec is not yet marked done, skip this spec and move to the next one that can be done - -## Step 3 — Implement - -Check the spec's `**Version impact:**` line to choose the implementation approach: - -**`none` (workspace/infrastructure spec)** — implement directly. Follow the "Implementation steps" exactly. If a step's "before" snapshot doesn't match the current file, consult the "Deviations" section (if you wrote one) or document the discrepancy and adapt minimally. - -**`patch` / `minor` / `major` (plugin spec)** — use `/tdd` to drive implementation. Treat the spec's "Implementation steps" as guidance (key files to touch, rough order), not a recipe. The spec's **Acceptance criteria** are the target; the red-green-refactor cycle drives the path there. - -Ground rules (from `docs/plans/README.md`): - -- Use `pnpm` for all package operations -- Tabs for indentation, LF line endings (per `.editorconfig`) -- Conventional commits: `feat(scope): description`, `fix(scope): description`, `chore(scope): description` -- Cross-platform: use Node.js APIs (`node:path`, `node:fs`, `node:os`) instead of shell commands; no bash/sh assumptions -- **Never hand-edit** `.claude-plugin/marketplace.json` version — use `pnpm bump` -- If something can't be followed as written: document it in `## Deviations`, don't silently deviate - -**Supporting skill:** `/diagnose` — if a failure persists and the root cause appears to be outside the spec's scope (an existing module, tooling, or dependency the spec doesn't touch), use `/diagnose` to isolate it before continuing. - -## Step 4 — Verify - -Run the exact commands in the spec's **Verification** section. Fix any failures before proceeding. - -Check every item in **Acceptance criteria**. If any item fails, fix it. - -Then run the always-on repo hygiene checks regardless of spec type: - -```sh -pnpm -w check # Biome + Prettier (workspace root) — fix any failures before proceeding -``` - -## Step 4.5 — Bump version + CHANGELOG - -1. Read the spec's `**Version impact:** patch|minor|major` line at the top of the spec file. - If the line is absent, infer: breaking CLI/contract change → `major`; new flag/feature → `minor`; bug fix, refactor, docs → `patch`. - -2. Append **one bullet** to the matching subsection under `## [Unreleased]` in `CHANGELOG.md`, replacing the `- (none)` placeholder on first use: - - - `### Breaking` — on-disk file schema change, plugin-to-hook contract change - - `### Added` — new feature, new configuration option, new extension support - - `### Fixed` — bug fix, refactor, docs, internal tooling - -3. Run: - - ```sh - pnpm bump - ``` - - This atomically increments `plugin.json` version, mirrors into `marketplace.json`, and promotes `[Unreleased]` → a new dated section. - -4. Run `pnpm verify:changelog` to confirm the check passes. - -## Step 5 — Mark done and commit - -1. Add this line immediately after the spec's `# NN. Title` heading (as the second line): - -``` -**Status: done — YYYY-MM-DD** -``` - -Replace `YYYY-MM-DD` with today's date. - -1. Stage and commit all changes: - -```sh -git add -A -git commit -m "feat(spec-NN): (vX.Y.Z)" -``` - -Replace `NN` with the spec number (e.g. `00`, `03`) and write a clear description. -Replace `X.Y.Z` with the version output by `pnpm bump`. - -1. **Do not push.** Commits only. - -## Step 6 — Stop for this iteration - -Output a brief summary of what was implemented and committed. Then stop — Ralph will feed this prompt again for the next spec. - ---- - -## Important constraints - -- Implement **one spec per iteration**. Do not implement multiple specs in a single run. -- If a spec requires human judgment (e.g. choosing between two design approaches not covered by the spec), stop, document the question in a `## Questions` section at the bottom of the spec file, and output: - - ``` - LOOP_COMPLETE - ``` - - This pauses the loop for human review. - -- Do not create any files outside of what the spec describes. -- Do not modify any spec files except to add `**Status: done**`, `## Deviations`, or `## Questions` sections. diff --git a/apps/claude-code/auto-format/ralph.yml b/apps/claude-code/auto-format/ralph.yml deleted file mode 100644 index a221284f..00000000 --- a/apps/claude-code/auto-format/ralph.yml +++ /dev/null @@ -1,35 +0,0 @@ -# Ralph Orchestrator Configuration -# Generated by: ralph init --backend claude -# Project: unic-auto-format -# Docs: https://github.com/mikeyobrien/ralph-orchestrator - -cli: - backend: 'claude' - -event_loop: - prompt_file: 'PROMPT.md' - completion_promise: 'LOOP_COMPLETE' - max_iterations: 100 # 15 specs * generous retry budget - max_runtime_seconds: 28800 # 8 hours; abort if a spec stalls - -# ───────────────────────────────────────────────────────────────────────────── -# Additional Configuration (uncomment to customize) -# ───────────────────────────────────────────────────────────────────────────── - -# core: -# scratchpad: ".ralph/agent/scratchpad.md" -# specs_dir: ".ralph/specs/" - -# Custom hats for multi-agent workflows: -# hats: -# builder: -# name: "Builder" -# triggers: ["build.task"] -# publishes: ["build.done", "build.blocked"] -# -# reviewer: -# name: "Reviewer" -# triggers: ["review.request"] -# publishes: ["review.approved", "review.changes_requested"] - -# Create PROMPT.md with your task, then run: ralph run diff --git a/apps/claude-code/pr-review/PROMPT.md b/apps/claude-code/pr-review/PROMPT.md deleted file mode 100644 index 18ad81d4..00000000 --- a/apps/claude-code/pr-review/PROMPT.md +++ /dev/null @@ -1,113 +0,0 @@ -# Ralph driver — `unic-pr-review` re-review feature - -You are implementing the **re-review** capability for the `unic-pr-review` plugin, one spec at a time. - -## Step 1 — Determine what's next - -Open `docs/plans/README.md`. Scan spec files in order and find the first file whose status is **not** `done` nor `ignore`. - -If **all** specs contain `**Status: done**`, output exactly: - -``` -LOOP_COMPLETE -``` - -…and stop. Do nothing else. - -## Step 2 — Read the spec completely - -Read the entire spec file before writing any code. Pay special attention to: - -- **Current behaviour** — verify the code actually works this way before starting; if it doesn't, add a `## Deviations` section at the bottom of the spec file documenting the discrepancy -- **Out of scope** — list of things you must NOT change in this iteration -- **Depends on** — if a dependency spec is not yet marked done, skip this spec and move to the next one that can be done - -## Step 3 — Implement - -Check the spec's `**Version impact:**` line to choose the implementation approach: - -**`none` (workspace/infrastructure spec)** — implement directly. Make the smallest set of edits that fully satisfies the spec's _Acceptance criteria_. - -**`patch` / `minor` / `major` (plugin spec)** — use `/tdd` to drive implementation. Treat the spec's "Implementation steps" as guidance (key files to touch, rough order), not a recipe. The spec's **Acceptance criteria** are the target; the red-green-refactor cycle drives the path there. - -Ground rules: - -- Use `pnpm` for all package operations -- Tabs for indentation, LF line endings (per `.editorconfig`) -- Conventional commits: `feat(scope): description`, `fix(scope): description`, `chore(scope): description` -- Cross-platform: use Node.js APIs (`node:path`, `node:fs`, `node:os`) instead of shell commands; no bash/sh assumptions -- Don't refactor outside the spec's _Touches_ list -- Don't invent new specs; if you find missing work, add a `## Follow-ups` line to the current spec and surface it in `docs/plans/README.md` under "Discovered work" -- If something can't be followed as written: document it in `## Deviations`, don't silently deviate - -**Supporting skill:** `/diagnose` — if a failure persists and the root cause appears to be outside the spec's scope (an existing module, tooling, or dependency the spec doesn't touch), use `/diagnose` to isolate it before continuing. - -## Step 4 — Verify - -Run the exact commands in the spec's **Verification** section. Fix any failures before proceeding. - -Check every item in **Acceptance criteria**. If any item fails, fix it. - -Then run the always-on repo hygiene checks regardless of spec type: - -```sh -pnpm -w check # Biome + Prettier (workspace root) — fix any failures before proceeding -``` - -## Step 4.5 — Version bump (conditional) - -Check the spec's `**Version impact:**` line: - -**`none`** — skip this step entirely. No CHANGELOG update. Proceed to Step 5. - -**`patch` / `minor` / `major`** — bump the plugin: - -1. Append one bullet under the matching subsection of `## [Unreleased]` in `CHANGELOG.md`: - - - `### Breaking` — CLI flag change, exit-code change, on-disk schema change - - `### Added` — new flag, subcommand, or user-visible feature - - `### Fixed` — bug fix, refactor, docs, internal tooling - -2. Run: `pnpm bump ` - - This atomically increments `plugin.json` version, mirrors into `marketplace.json`, and promotes `[Unreleased]` → a new dated section. - -3. Run `pnpm verify:changelog` to confirm the check passes. - -## Step 5 — Mark done and commit - -1. Add this line immediately after the spec's `# NN. Title` heading (as the second line): - -``` -**Status: done — YYYY-MM-DD** -``` - -Replace `YYYY-MM-DD` with today's date. - -2. Stage and commit all changes: - -- **`none` specs**: `git commit -m "chore(spec-NN): "` -- **`patch`/`minor`/`major` specs**: `git commit -m "feat(spec-NN): (vX.Y.Z)"` - -Replace `NN` with the spec number (e.g. `00`, `03`). -Replace `X.Y.Z` with the version output by `pnpm bump`. - -3. **Do not push.** Commits only. - -## Step 6 — Stop for this iteration - -Output a brief summary of what was implemented and committed. Then stop — Ralph will feed this prompt again for the next spec. - ---- - -## Important constraints - -- Implement **one spec per iteration**. Do not implement multiple specs in a single run. -- If a spec requires human judgment (e.g. choosing between two design approaches not covered by the spec), stop, document the question in a `## Questions` section at the bottom of the spec file, and output: - ``` - LOOP_COMPLETE - ``` - This pauses the loop for human review. -- Do not create any files outside of what the spec describes. -- Do not modify any spec files except to add `**Status: done**`, `## Deviations`, `## Questions`, or `## Follow-ups` sections. -- Never edit `CLAUDE.md`'s rule list silently — propose the change in the spec instead. diff --git a/apps/claude-code/pr-review/ralph.yml b/apps/claude-code/pr-review/ralph.yml deleted file mode 100644 index 6b7525bb..00000000 --- a/apps/claude-code/pr-review/ralph.yml +++ /dev/null @@ -1,35 +0,0 @@ -# Ralph Orchestrator Configuration -# Generated by: ralph init --backend claude -# Project: unic-pr-review -# Docs: https://github.com/mikeyobrien/ralph-orchestrator - -cli: - backend: 'claude' - -event_loop: - prompt_file: 'PROMPT.md' - completion_promise: 'LOOP_COMPLETE' - max_iterations: 100 # 15 specs * generous retry budget - max_runtime_seconds: 28800 # 8 hours; abort if a spec stalls - -# ───────────────────────────────────────────────────────────────────────────── -# Additional Configuration (uncomment to customize) -# ───────────────────────────────────────────────────────────────────────────── - -# core: -# scratchpad: ".ralph/agent/scratchpad.md" -# specs_dir: ".ralph/specs/" - -# Custom hats for multi-agent workflows: -# hats: -# builder: -# name: "Builder" -# triggers: ["build.task"] -# publishes: ["build.done", "build.blocked"] -# -# reviewer: -# name: "Reviewer" -# triggers: ["review.request"] -# publishes: ["review.approved", "review.changes_requested"] - -# Create PROMPT.md with your task, then run: ralph run diff --git a/apps/claude-code/unic-confluence/PROMPT.md b/apps/claude-code/unic-confluence/PROMPT.md deleted file mode 100644 index 565737fd..00000000 --- a/apps/claude-code/unic-confluence/PROMPT.md +++ /dev/null @@ -1,115 +0,0 @@ -# Ralph Orchestrator — unic-confluence Roadmap - -You are implementing the roadmap for the `unic-confluence` Claude Code plugin, one spec at a time. - -## Step 1 — Determine what's next - -Check the execution order in `docs/plans/README.md`. Then scan spec files in order (00 → 18) and find the first file that does NOT contain the string `**Status: done`. - -If **all** specs contain `**Status: done`, output exactly: - -``` -LOOP_COMPLETE -``` - -…and stop. Do nothing else. - -## Step 2 — Read the spec completely - -Read the entire spec file before writing any code. Pay special attention to: - -- **Current behaviour** — verify the code actually works this way before starting; if it doesn't, add a `## Deviations` section at the bottom of the spec file documenting the discrepancy -- **Out of scope** — list of things you must NOT change in this iteration -- **Depends on** — if a dependency spec is not yet marked done, skip this spec and move to the next one that can be done - -## Step 3 — Implement - -Check the spec's `**Version impact:**` line to choose the implementation approach: - -**`none` (workspace/infrastructure spec)** — implement directly. Follow the "Implementation steps" exactly. If a step's "before" snapshot doesn't match the current file, consult the "Deviations" section (if you wrote one) or document the discrepancy and adapt minimally. - -**`patch` / `minor` / `major` (plugin spec)** — use `/tdd` to drive implementation. Treat the spec's "Implementation steps" as guidance (key files to touch, rough order), not a recipe. The spec's **Acceptance criteria** are the target; the red-green-refactor cycle drives the path there. - -Ground rules (from `docs/plans/README.md`): - -- Use `pnpm` for all package operations -- Tabs for indentation, LF line endings (per `.editorconfig`) -- Conventional commits: `feat(scope): description`, `fix(scope): description`, `chore(scope): description` -- Cross-platform: use Node.js APIs (`node:path`, `node:fs`, `node:os`) instead of shell commands; no bash/sh assumptions -- **Never hand-edit** `.claude-plugin/marketplace.json` version — use `pnpm bump` -- If something can't be followed as written: document it in `## Deviations`, don't silently deviate - -**Supporting skill:** `/diagnose` — if a failure persists and the root cause appears to be outside the spec's scope (an existing module, tooling, or dependency the spec doesn't touch), use `/diagnose` to isolate it before continuing. - -## Step 4 — Verify - -Run the exact commands in the spec's **Verification** section. Fix any failures before proceeding. - -Check every item in **Acceptance criteria**. If any item fails, fix it. - -Then run the always-on repo hygiene checks regardless of spec type: - -```sh -pnpm -w check # Biome + Prettier (workspace root) — fix any failures before proceeding -``` - -## Step 4.5 — Bump version + CHANGELOG - -1. Read the spec's `**Version impact:** patch|minor|major` line at the top of the spec file. - If the line is absent, infer: breaking CLI/contract change → `major`; new flag/feature → `minor`; bug fix, refactor, docs → `patch`. - -2. Append **one bullet** to the matching subsection under `## [Unreleased]` in `CHANGELOG.md`, replacing the `- (none)` placeholder on first use: - - - `### Breaking` — CLI flag renamed/removed, exit-code change, on-disk file schema change - - `### Added` — new flag, subcommand, or user-visible feature - - `### Fixed` — bug fix, refactor, docs, internal tooling - Wording: one line, user-facing, present-tense description (e.g. `- \`pnpm bump\` command for atomic version bumping`). - -3. Run: - - ```sh - pnpm bump - ``` - - This atomically: increments `plugin.json` version, mirrors into `marketplace.json`, and promotes `[Unreleased]` → a new dated section. - -4. Run `pnpm verify:changelog` to confirm the check passes. - -## Step 5 — Mark done and commit - -1. Add this line immediately after the spec's `# NN. Title` heading (as the second line): - -``` -**Status: done — YYYY-MM-DD** -``` - -Replace `YYYY-MM-DD` with today's date. - -2. Stage and commit all changes: - -```sh -git add -A -git commit -m "feat(spec-NN): (vX.Y.Z)" -``` - -Replace `NN` with the spec number (e.g. `00`, `03`) and write a clear description. -Replace `X.Y.Z` with the version output by `pnpm bump`. - -3. **Do not push.** Commits only. - -## Step 6 — Stop for this iteration - -Output a brief summary of what was implemented and committed. Then stop — Ralph will feed this prompt again for the next spec. - ---- - -## Important constraints - -- Implement **one spec per iteration**. Do not implement multiple specs in a single run. -- If a spec requires human judgment (e.g. choosing between two design approaches not covered by the spec), stop, document the question in a `## Questions` section at the bottom of the spec file, and output: - ``` - LOOP_COMPLETE - ``` - This pauses the loop for human review. -- Do not create any files outside of what the spec describes. -- Do not modify any spec files except to add `**Status: done**`, `## Deviations`, or `## Questions` sections. diff --git a/apps/claude-code/unic-confluence/ralph.yml b/apps/claude-code/unic-confluence/ralph.yml deleted file mode 100644 index 8b24f7c0..00000000 --- a/apps/claude-code/unic-confluence/ralph.yml +++ /dev/null @@ -1,35 +0,0 @@ -# Ralph Orchestrator Configuration -# Generated by: ralph init --backend claude -# Project: unic-confluence -# Docs: https://github.com/mikeyobrien/ralph-orchestrator - -cli: - backend: 'claude' - -event_loop: - prompt_file: 'PROMPT.md' - completion_promise: 'LOOP_COMPLETE' - max_iterations: 100 # 15 specs * generous retry budget - max_runtime_seconds: 28800 # 8 hours; abort if a spec stalls - -# ───────────────────────────────────────────────────────────────────────────── -# Additional Configuration (uncomment to customize) -# ───────────────────────────────────────────────────────────────────────────── - -# core: -# scratchpad: ".ralph/agent/scratchpad.md" -# specs_dir: ".ralph/specs/" - -# Custom hats for multi-agent workflows: -# hats: -# builder: -# name: "Builder" -# triggers: ["build.task"] -# publishes: ["build.done", "build.blocked"] -# -# reviewer: -# name: "Reviewer" -# triggers: ["review.request"] -# publishes: ["review.approved", "review.changes_requested"] - -# Create PROMPT.md with your task, then run: ralph run diff --git a/docs/adr/0020-per-plugin-ralph-loops.md b/docs/adr/0020-per-plugin-ralph-loops.md index 20a13d83..a6dba595 100644 --- a/docs/adr/0020-per-plugin-ralph-loops.md +++ b/docs/adr/0020-per-plugin-ralph-loops.md @@ -1,6 +1,6 @@ # 0020. Each plugin has its own Ralph loop with its own ralph.yml and PROMPT.md -**Status:** Accepted (2025-04) +**Status:** Superseded by [ADR-0030](0030-retire-ralph-adopt-archon-runner.md) ## Context diff --git a/docs/adr/0024-ralph-atomic-iteration.md b/docs/adr/0024-ralph-atomic-iteration.md index bc74b6d1..013fd505 100644 --- a/docs/adr/0024-ralph-atomic-iteration.md +++ b/docs/adr/0024-ralph-atomic-iteration.md @@ -1,6 +1,6 @@ # 0024. Ralph implements one spec per iteration, then commits and stops -**Status:** Accepted (2025-04) +**Status:** Superseded by [ADR-0030](0030-retire-ralph-adopt-archon-runner.md) ## Context diff --git a/docs/adr/0030-retire-ralph-adopt-archon-runner.md b/docs/adr/0030-retire-ralph-adopt-archon-runner.md new file mode 100644 index 00000000..1058bf25 --- /dev/null +++ b/docs/adr/0030-retire-ralph-adopt-archon-runner.md @@ -0,0 +1,28 @@ +# 0030. Retire ralph-orchestrator; adopt unic-archon-dlc as the Spec Runner + +**Status:** Accepted (2026-05) + +## Context + +`ralph-orchestrator` (`@ralph-orchestrator/ralph-cli`) was used as the Spec Runner for all `docs/plans/` specs at both the monorepo root and per-plugin level (see [ADR-0020](0020-per-plugin-ralph-loops.md), [ADR-0024](0024-ralph-atomic-iteration.md)). By 2026-05 all 18 monorepo-level specs (00–17) and all prior plugin specs were marked done. The `docs/plans/` format was a bootstrap mechanism, not a permanent intake path. + +Two factors drove the retirement: + +1. **Windows incompatibility** — `ralph-cli` has no Windows support. CI runs on Windows (see [ADR-0014](0014-ci-matrix-three-os-two-node.md)); contributors on Windows could not run the spec loop locally. +2. **Strategic direction** — `unic-archon-dlc` is being developed as an Archon-powered AI development lifecycle harness that this monorepo both ships and consumes. Its `unic-dlc-build` workflow is the intended long-term runner; converging on one tool reduces the harness surface. + +## Decision + +- Remove `@ralph-orchestrator/ralph-cli` from `package.json` and `pnpm-workspace.yaml`. +- Delete all `ralph.yml`, `PROMPT.md`, and `.ralph/` artifacts from the repo root and all plugin directories. +- Remove the `pnpm ralph` and per-plugin `ralph` scripts. +- Retire the `docs/plans/` spec format; specs 12–16 for `pr-review` are the last batch. +- Remove **Spec** and **Spec Runner** from `CONTEXT.md`; the **Feature Runner** (backed by `unic-dlc-build`) is the sole runner going forward. +- In the interim, individual specs are implemented manually via `/tdd`. + +## Consequences + +- No CLI wrapper exists for running specs during the transition; developers invoke `/tdd` directly. +- Future work items enter through the issue tracker as Features, not as `docs/plans/` spec files. +- `unic-dlc-build` must be production-ready before fully automated AFK runs resume. +- ADR-0020 and ADR-0024 are superseded by this decision. diff --git a/docs/plans/README.md b/docs/plans/README.md index dd7b5208..62cb2db3 100644 --- a/docs/plans/README.md +++ b/docs/plans/README.md @@ -1,8 +1,8 @@ # Monorepo Spec Roadmap -This directory contains the Ralph-iterable spec set for the `unic-agents-plugins` monorepo migration and bootstrapping. Each spec is implemented by Ralph in one iteration. +> **Retired.** All specs (00–17) are complete. `docs/plans/` is no longer the intake path for new work — use the issue tracker instead. See [ADR-0030](../adr/0030-retire-ralph-adopt-archon-runner.md). -Individual plugins have their own `docs/plans/` for plugin-specific development. +This directory contains the historical spec set for the `unic-agents-plugins` monorepo migration and bootstrapping. ## Execution order diff --git a/docs/process/ai-development.md b/docs/process/ai-development.md index a9fb516b..9093c640 100644 --- a/docs/process/ai-development.md +++ b/docs/process/ai-development.md @@ -4,22 +4,20 @@ This guide explains the mental model behind the AI-development workflow, the arc --- -## 1. Two runners, not one +## 1. The Feature Runner -The most important thing to understand is that this repo has two distinct execution loops, and they are not interchangeable. +All AFK execution flows through the Feature Runner. New work enters as Features in the issue tracker (`docs/issues//`). -| | Spec Runner | Feature Runner | -| --------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------- | -| **Input** | `docs/plans/NN-*.md` Spec | `docs/issues//NN-*.md` Issue | -| **Invocation** | `pnpm ralph` | `/implement-feature` | -| **Format** | Prescriptive: before/after snapshots, shell verification commands, explicit steps | Descriptive: `## What to build` + `## Acceptance criteria` | -| **Worker** | Agent follows spec as recipe (or `/tdd` for behavioral specs) | `/tdd` in non-interactive AFK mode | -| **Completion marker** | `**Status: done**` in spec file | `Status: resolved` in issue file | -| **Branch** | Current branch | `feature/afk/` worktree | +| | Feature Runner | +| --------------------- | ---------------------------------------------------------- | +| **Input** | `docs/issues//NN-*.md` Issue | +| **Invocation** | `/implement-feature` | +| **Format** | Descriptive: `## What to build` + `## Acceptance criteria` | +| **Worker** | `/tdd` in non-interactive AFK mode | +| **Completion marker** | `Status: resolved` in issue file | +| **Branch** | `feature/afk/` worktree | -**When to use which:** The Spec Runner is for building and evolving the repo itself — release tooling, CI configuration, monorepo infrastructure. The Feature Runner is for product work on top of a stable system — new plugin capabilities, improvements to existing features. A rough heuristic: if the work would change something under `packages/` or `.github/`, it belongs in a Spec. If it changes something under `apps/claude-code//`, it belongs in a Feature. - -Both runners are backed by the same agent; the difference is in what inputs they receive and how much the agent is expected to figure out on its own. +The Feature Runner is the sole execution path. Infrastructure work (CI, tooling, packages) and product work (plugin features) both enter through the issue tracker — the split is in the issue content, not in which runner handles it. --- @@ -129,7 +127,7 @@ The Feature Runner is designed to be composable with `/loop` for unattended over /loop /implement-feature ``` -When the queue empties (no qualifying feature exists — see `.claude/skills/implement-feature/SKILL.md` step 0 for the full qualification rule), the runner outputs `LOOP_COMPLETE` and the loop terminates cleanly. This mirrors the Spec Runner's `completion_promise: LOOP_COMPLETE` in `ralph.yml`. +When the queue empties (no qualifying feature exists — see `.claude/skills/implement-feature/SKILL.md` step 0 for the full qualification rule), the runner outputs `LOOP_COMPLETE` and the loop terminates cleanly. For overnight runs to succeed, the queue must be in good shape before you start: each target feature must qualify (see SKILL.md step 0) — every issue in `{ready-for-agent, resolved, closed, rejected, ready-for-human}`, no `needs-*` states, no conflicts between `## Blocked by` and numerical order, acceptance criteria specific enough to verify without judgment. A single malformed issue will halt the runner and leave the remainder of the queue unexecuted. @@ -151,31 +149,19 @@ The commits from your grilling sessions carry this context forward. The Feature --- -## 9. Keeping docs/plans/ and docs/issues/ in sync - -The Spec Runner and Feature Runner evolved independently. Work that was implemented via the Spec Runner (i.e. a Spec in `docs/plans/` was marked `done`) may have a corresponding directory in `docs/issues//` that was never updated. The Feature Runner will attempt to implement those stale issues if they have `ready-for-agent` status. - -The convention: when a Spec is marked `**Status: done**`, check for a corresponding `docs/issues//` directory. If it exists, mark all issue files in it `closed` and append a note: - -```markdown -## Comments - -> _Closed 2026-05-09 — implemented via Spec Runner (docs/plans/NN-.md marked done)._ -``` +## 9. Historical: docs/plans/ -This is a manual step. There is no automation for it. The `docs/agents/feature-runner.md` reference document records this convention for agents that need to be briefed on it. +`docs/plans/` was the intake path for monorepo infrastructure specs (00–17), implemented by `ralph-orchestrator`. All specs are complete and the format is retired as of 2026-05. If you encounter `docs/issues//` directories whose issues were never closed because they were implemented via a spec, mark them `closed` with a note referencing the spec that covered them. See [ADR-0030](../adr/0030-retire-ralph-adopt-archon-runner.md) for the full retirement decision. --- ## Related - `docs/process/development-workflow.md` — the 8-phase quick reference -- `docs/process/ralph-loop-guide.md` — Spec Runner invocation and resumption detail -- `docs/process/spec-template.md` — spec file format - `docs/agents/issue-tracker.md` — issue file conventions - `docs/agents/triage-labels.md` — 8-state triage vocabulary -- `docs/adr/0023-spec-template-format.md` — why specs are prescriptive -- `docs/adr/0026-tdd-dispatch-by-version-impact.md` — when the Spec Runner uses /tdd +- `docs/adr/0026-tdd-dispatch-by-version-impact.md` — when the Feature Runner uses /tdd - `docs/adr/0027-feature-runner-context-bundle.md` — what /tdd receives per invocation - `docs/adr/0028-blocked-by-canonical-sequencing.md` — why ## Blocked by beats filename order - `docs/adr/0029-feature-runner-afk-invocation.md` — how AFK invocation works +- `docs/adr/0030-retire-ralph-adopt-archon-runner.md` — retirement of ralph and docs/plans/ diff --git a/docs/process/development-workflow.md b/docs/process/development-workflow.md index bddc319a..426111dd 100644 --- a/docs/process/development-workflow.md +++ b/docs/process/development-workflow.md @@ -72,19 +72,6 @@ Use the triage labels to track state — see `docs/agents/triage-labels.md` for ## Phase 7 — Execute -There are two execution paths depending on the type of work. Choose based on where the work item lives, not on personal preference — the two runners are not interchangeable. - -### Spec Runner — for `docs/plans/` specs - -Use the Spec Runner when implementing infrastructure, tooling, or repo-level changes captured as Specs in `docs/plans/`: - -``` -pnpm ralph # root specs -pnpm --filter ralph # plugin-specific specs -``` - -Specs follow a prescriptive format (before/after snapshots, shell verification commands, acceptance criteria). The Spec Runner implements one Spec per iteration, commits, and stops. See `docs/process/ralph-loop-guide.md`. - ### Feature Runner — for `docs/issues/` features Use the Feature Runner when implementing product features tracked as Issues in `docs/issues//`. Once a feature has at least one `ready-for-agent` issue and no unprepped issues (`needs-triage`, `needs-info`, `needs-specs`): @@ -126,8 +113,7 @@ Human QA often surfaces new issues or improvement ideas — add them back to the | 4. Prototype | Uncertain design or UX | Ad hoc throwaway route | | 5. PRD | After grilling | `/to-prd` → `docs/issues//PRD.md` | | 6. Issues | After PRD | `/to-issues` → `docs/issues//-*.md` | -| 7a. Execute (Spec) | Specs in `docs/plans/` are ready | `pnpm ralph` (Spec Runner) | -| 7b. Execute (Feature) | Issues in `docs/issues/` are `ready-for-agent` | `/implement-feature` (Feature Runner) | +| 7. Execute (Feature) | Issues in `docs/issues/` are `ready-for-agent` | `/implement-feature` (Feature Runner) | | 8. QA | After execution | QA plan (agent-generated, human-verified) | ## Related @@ -135,6 +121,4 @@ Human QA often surfaces new issues or improvement ideas — add them back to the - `docs/inbox/README.md` — inbox conventions - `docs/agents/issue-tracker.md` — issue file conventions - `docs/agents/triage-labels.md` — 8-state triage vocabulary -- `docs/process/ralph-loop-guide.md` — Spec Runner detail -- `docs/process/spec-template.md` — spec file format - `docs/process/ai-development.md` — deep guide: mental model, context quality, AFK trust chain, key decisions diff --git a/docs/process/ralph-loop-guide.md b/docs/process/ralph-loop-guide.md deleted file mode 100644 index 61966d74..00000000 --- a/docs/process/ralph-loop-guide.md +++ /dev/null @@ -1,47 +0,0 @@ -# Ralph Loop Guide - -## What is the Ralph loop? - -Ralph Orchestrator is a Claude Code plugin that runs specs from `docs/plans/` one at a time. Each iteration implements one spec, commits, and stops. Re-running the loop picks up the next unfinished spec. - -## Key files - -- **`ralph.yml`** — Loop configuration: which model to use, which `PROMPT.md` to load, concurrency settings. -- **`PROMPT.md`** — The objective injected into each Ralph iteration. For the monorepo root, it instructs Ralph to scan specs in order and implement the first one not marked `**Status: done**`. - -## Starting a loop - -From the monorepo root (implements the next pending spec): - -```sh -pnpm ralph -``` - -From inside a plugin directory (runs that plugin's own development loop): - -```sh -cd apps/claude-code/pr-review -pnpm ralph -``` - -## Stopping and resuming - -- **Stop early**: `Ctrl+C` — safe at any point; the current spec is left in progress. -- **Resume**: `pnpm ralph` again — Ralph finds the first spec without `**Status: done**` and continues. - -## Paused for human review - -When Ralph encounters a decision that requires human judgment, it: - -1. Adds a `## Questions` section to the bottom of the spec file. -2. Emits `LOOP_COMPLETE`, which pauses the loop. - -To resume: answer the question in the spec file, remove the `## Questions` section, then run `pnpm ralph` again. - -## Single-spec-per-iteration discipline - -Ralph implements **one spec per run**. This keeps commits atomic and makes it easy to review, revert, or re-run a single change. Do not modify `PROMPT.md` to skip this discipline. - -## Writing new specs - -Use `docs/process/spec-template.md` as the canonical starting point. Register the new spec in `docs/plans/README.md`. diff --git a/package.json b/package.json index fbda189f..c0747d13 100644 --- a/package.json +++ b/package.json @@ -13,8 +13,7 @@ "check": "biome check . && prettier --check \"**/*.md\"", "ci:check": "biome ci . && prettier --check \"**/*.md\"", "test": "pnpm -r --if-present test", - "typecheck": "pnpm -r --if-present typecheck", - "ralph": "ralph run -c ralph.yml -H builtin:code-assist" + "typecheck": "pnpm -r --if-present typecheck" }, "devDependencies": { "@biomejs/biome": "catalog:", @@ -25,7 +24,4 @@ "prettier": "catalog:", "typescript": "catalog:" }, - "optionalDependencies": { - "@ralph-orchestrator/ralph-cli": "catalog:" - } } diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index b4f0e0fd..e906dba1 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -2,12 +2,8 @@ packages: - "apps/*/*" - "packages/*" -allowBuilds: - "@ralph-orchestrator/ralph-cli": true - catalog: "@biomejs/biome": 2.4.0 - "@ralph-orchestrator/ralph-cli": 2.9.2 "@types/node": 24.12.2 prettier: 3.4.2 typescript: 5.8.3 diff --git a/ralph.yml b/ralph.yml deleted file mode 100644 index 4ea993ed..00000000 --- a/ralph.yml +++ /dev/null @@ -1,35 +0,0 @@ -# Ralph Orchestrator Configuration -# Generated by: ralph init --backend claude -# Project: unic-agents-plugins -# Docs: https://github.com/mikeyobrien/ralph-orchestrator - -cli: - backend: 'claude' - -event_loop: - prompt_file: 'PROMPT.md' - completion_promise: 'LOOP_COMPLETE' - max_iterations: 100 # 15 specs * generous retry budget - max_runtime_seconds: 28800 # 8 hours; abort if a spec stalls - -# ───────────────────────────────────────────────────────────────────────────── -# Additional Configuration (uncomment to customize) -# ───────────────────────────────────────────────────────────────────────────── - -# core: -# scratchpad: ".ralph/agent/scratchpad.md" -# specs_dir: ".ralph/specs/" - -# Custom hats for multi-agent workflows: -# hats: -# builder: -# name: "Builder" -# triggers: ["build.task"] -# publishes: ["build.done", "build.blocked"] -# -# reviewer: -# name: "Reviewer" -# triggers: ["review.request"] -# publishes: ["review.approved", "review.changes_requested"] - -# Create PROMPT.md with your task, then run: ralph run From c311e82ab4c9743ca3d90c3554bdcaa2ed67b02b Mon Sep 17 00:00:00 2001 From: Oriol Torrent Florensa Date: Fri, 22 May 2026 19:49:04 +0200 Subject: [PATCH 2/6] fix: syntax and formatting issues --- CONTEXT.md | 1 - docs/process/development-workflow.md | 20 ++++++++++---------- package.json | 2 +- 3 files changed, 11 insertions(+), 12 deletions(-) diff --git a/CONTEXT.md b/CONTEXT.md index bcdd0f57..ca762a57 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -47,4 +47,3 @@ _Avoid_: client, user repo, target repo, host repo > **Dev:** "A Consumer reported the auto-format Plugin failing on Windows." > **Domain expert:** "That's a cross-platform gap. Plugins must use Node.js APIs — no shell commands or POSIX paths." - diff --git a/docs/process/development-workflow.md b/docs/process/development-workflow.md index 426111dd..c4e548e7 100644 --- a/docs/process/development-workflow.md +++ b/docs/process/development-workflow.md @@ -105,16 +105,16 @@ Human QA often surfaces new issues or improvement ideas — add them back to the ## Quick reference -| Phase | When | Tool | -| --------------------- | ---------------------------------------------- | --------------------------------------------- | -| 1. Capture | Idea surfaces mid-task | `/inbox ` | -| 2. Grill | Before any PRD or spec | `/grill-with-docs` or `/grill-me` | -| 3. Research | Unfamiliar external dependencies | `research.md` (ad hoc) | -| 4. Prototype | Uncertain design or UX | Ad hoc throwaway route | -| 5. PRD | After grilling | `/to-prd` → `docs/issues//PRD.md` | -| 6. Issues | After PRD | `/to-issues` → `docs/issues//-*.md` | -| 7. Execute (Feature) | Issues in `docs/issues/` are `ready-for-agent` | `/implement-feature` (Feature Runner) | -| 8. QA | After execution | QA plan (agent-generated, human-verified) | +| Phase | When | Tool | +| -------------------- | ---------------------------------------------- | --------------------------------------------- | +| 1. Capture | Idea surfaces mid-task | `/inbox ` | +| 2. Grill | Before any PRD or spec | `/grill-with-docs` or `/grill-me` | +| 3. Research | Unfamiliar external dependencies | `research.md` (ad hoc) | +| 4. Prototype | Uncertain design or UX | Ad hoc throwaway route | +| 5. PRD | After grilling | `/to-prd` → `docs/issues//PRD.md` | +| 6. Issues | After PRD | `/to-issues` → `docs/issues//-*.md` | +| 7. Execute (Feature) | Issues in `docs/issues/` are `ready-for-agent` | `/implement-feature` (Feature Runner) | +| 8. QA | After execution | QA plan (agent-generated, human-verified) | ## Related diff --git a/package.json b/package.json index c0747d13..c29f569d 100644 --- a/package.json +++ b/package.json @@ -23,5 +23,5 @@ "@unic/tsconfig": "workspace:*", "prettier": "catalog:", "typescript": "catalog:" - }, + } } From 94abe56ae16caf0731d65ad807b6f00cad00a13d Mon Sep 17 00:00:00 2001 From: Oriol Torrent Florensa Date: Fri, 22 May 2026 19:55:57 +0200 Subject: [PATCH 3/6] chore: remove ralph-orchestrator dependencies from package.json files --- .../references/package-json-template.md | 2 -- apps/claude-code/auto-format/package.json | 33 +++++++++---------- apps/claude-code/pr-review/package.json | 25 +++++++------- apps/claude-code/unic-confluence/package.json | 1 - 4 files changed, 28 insertions(+), 33 deletions(-) diff --git a/.claude/skills/new-plugin/references/package-json-template.md b/.claude/skills/new-plugin/references/package-json-template.md index 64b77ba4..0090aa1c 100644 --- a/.claude/skills/new-plugin/references/package-json-template.md +++ b/.claude/skills/new-plugin/references/package-json-template.md @@ -23,7 +23,6 @@ Use this as the starting shape for a new plugin's `package.json`. Copy `packageM "ralph": "ralph run -c ralph.yml -H builtin:code-assist" }, "devDependencies": { - "@ralph-orchestrator/ralph-cli": "catalog:", "@types/node": "catalog:", "@unic/release-tools": "workspace:*", "@unic/tsconfig": "workspace:*", @@ -55,7 +54,6 @@ Omit `test`, `typecheck`, and the `@types/node`/`@unic/tsconfig`/`typescript` de "ralph": "ralph run -c ralph.yml -H builtin:code-assist" }, "devDependencies": { - "@ralph-orchestrator/ralph-cli": "catalog:", "@unic/release-tools": "workspace:*" } } diff --git a/apps/claude-code/auto-format/package.json b/apps/claude-code/auto-format/package.json index c7254121..ad4fcf26 100644 --- a/apps/claude-code/auto-format/package.json +++ b/apps/claude-code/auto-format/package.json @@ -1,28 +1,27 @@ { - "name": "auto-format", - "version": "0.5.15", - "private": true, - "license": "LGPL-3.0-or-later", - "type": "module", - "packageManager": "pnpm@10.33.0", + "devDependencies": { + "@types/node": "catalog:", + "@unic/release-tools": "workspace:*", + "@unic/tsconfig": "workspace:*", + "typescript": "catalog:" + }, "engines": { "node": ">=22", "pnpm": ">=10" }, + "license": "LGPL-3.0-or-later", + "name": "auto-format", + "packageManager": "pnpm@10.33.0", + "private": true, "scripts": { - "test": "node --test tests/format-hook.test.mjs scripts/lib/runners.test.mjs scripts/lib/config.test.mjs", - "typecheck": "tsc --noEmit --project tsconfig.json", "bump": "unic-bump", + "ralph": "ralph run -c ralph.yml -H builtin:code-assist", "sync-version": "unic-sync-version", "tag": "unic-tag", - "verify:changelog": "unic-verify-changelog", - "ralph": "ralph run -c ralph.yml -H builtin:code-assist" + "test": "node --test tests/format-hook.test.mjs scripts/lib/runners.test.mjs scripts/lib/config.test.mjs", + "typecheck": "tsc --noEmit --project tsconfig.json", + "verify:changelog": "unic-verify-changelog" }, - "devDependencies": { - "@ralph-orchestrator/ralph-cli": "catalog:", - "@types/node": "catalog:", - "@unic/release-tools": "workspace:*", - "@unic/tsconfig": "workspace:*", - "typescript": "catalog:" - } + "type": "module", + "version": "0.5.15" } diff --git a/apps/claude-code/pr-review/package.json b/apps/claude-code/pr-review/package.json index 45841e78..ba8fce1d 100644 --- a/apps/claude-code/pr-review/package.json +++ b/apps/claude-code/pr-review/package.json @@ -1,24 +1,23 @@ { - "name": "pr-review", - "version": "1.2.10", - "private": true, - "license": "LGPL-3.0-or-later", - "type": "module", - "packageManager": "pnpm@10.33.0", + "devDependencies": { + "@unic/release-tools": "workspace:*" + }, "engines": { "node": ">=22", "pnpm": ">=10" }, + "license": "LGPL-3.0-or-later", + "name": "pr-review", + "packageManager": "pnpm@10.33.0", + "private": true, "scripts": { - "test": "node --test tests/parse-signature.test.mjs tests/classify-thread.test.mjs tests/match-finding.test.mjs tests/detect-prior-review.test.mjs tests/confluence-client.test.mjs tests/ado-fetcher.test.mjs tests/ado-writer.test.mjs tests/pre-pr.test.mjs tests/parse-diff-hunks.test.mjs tests/mode-detection.test.mjs tests/notices.test.mjs tests/classify-http-error.test.mjs tests/fetch-work-items.test.mjs tests/fetch-iterations.test.mjs tests/parse-write-response.test.mjs tests/detect-default-branch.test.mjs tests/plugin-structure.test.mjs", "bump": "unic-bump", + "ralph": "ralph run -c ralph.yml -H builtin:code-assist", "sync-version": "unic-sync-version", "tag": "unic-tag", - "verify:changelog": "unic-verify-changelog", - "ralph": "ralph run -c ralph.yml -H builtin:code-assist" + "test": "node --test tests/parse-signature.test.mjs tests/classify-thread.test.mjs tests/match-finding.test.mjs tests/detect-prior-review.test.mjs tests/confluence-client.test.mjs tests/ado-fetcher.test.mjs tests/ado-writer.test.mjs tests/pre-pr.test.mjs tests/parse-diff-hunks.test.mjs tests/mode-detection.test.mjs tests/notices.test.mjs tests/classify-http-error.test.mjs tests/fetch-work-items.test.mjs tests/fetch-iterations.test.mjs tests/parse-write-response.test.mjs tests/detect-default-branch.test.mjs tests/plugin-structure.test.mjs", + "verify:changelog": "unic-verify-changelog" }, - "devDependencies": { - "@ralph-orchestrator/ralph-cli": "catalog:", - "@unic/release-tools": "workspace:*" - } + "type": "module", + "version": "1.2.10" } diff --git a/apps/claude-code/unic-confluence/package.json b/apps/claude-code/unic-confluence/package.json index 21a4ad3f..fbe3f297 100644 --- a/apps/claude-code/unic-confluence/package.json +++ b/apps/claude-code/unic-confluence/package.json @@ -3,7 +3,6 @@ "marked": "17.0.5" }, "devDependencies": { - "@ralph-orchestrator/ralph-cli": "catalog:", "@types/node": "catalog:", "@unic/release-tools": "workspace:*", "@unic/tsconfig": "workspace:*", From 37e98387261f4b8b8869a6dfae77761231daaf31 Mon Sep 17 00:00:00 2001 From: Oriol Torrent Florensa Date: Fri, 22 May 2026 19:58:37 +0200 Subject: [PATCH 4/6] fix: recreate pnpm-lock.yaml without ralph-cli --- pnpm-lock.yaml | 344 ------------------------------------------------- 1 file changed, 344 deletions(-) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index a3d4eda8..77a045a9 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -9,9 +9,6 @@ catalogs: '@biomejs/biome': specifier: 2.4.0 version: 2.4.0 - '@ralph-orchestrator/ralph-cli': - specifier: 2.9.2 - version: 2.9.2 '@types/node': specifier: 24.12.2 version: 24.12.2 @@ -47,16 +44,9 @@ importers: typescript: specifier: 'catalog:' version: 5.8.3 - optionalDependencies: - '@ralph-orchestrator/ralph-cli': - specifier: 'catalog:' - version: 2.9.2 apps/claude-code/auto-format: devDependencies: - '@ralph-orchestrator/ralph-cli': - specifier: 'catalog:' - version: 2.9.2 '@types/node': specifier: 'catalog:' version: 24.12.2 @@ -72,9 +62,6 @@ importers: apps/claude-code/pr-review: devDependencies: - '@ralph-orchestrator/ralph-cli': - specifier: 'catalog:' - version: 2.9.2 '@unic/release-tools': specifier: workspace:* version: link:../../../packages/release-tools @@ -100,9 +87,6 @@ importers: specifier: 17.0.5 version: 17.0.5 devDependencies: - '@ralph-orchestrator/ralph-cli': - specifier: 'catalog:' - version: 2.9.2 '@types/node': specifier: 'catalog:' version: 24.12.2 @@ -188,179 +172,19 @@ packages: cpu: [x64] os: [win32] - '@ralph-orchestrator/ralph-cli@2.9.2': - resolution: {integrity: sha512-eRr1dc3SN0d5lnO9jFlc01Y/9EUDkQKXGIaSPNkBwVFZ0DLBf5SUk6fZswch8D4I+sEXsBLYQ423QlZkvNKhCw==} - engines: {node: '>=14', npm: '>=6'} - hasBin: true - '@types/node@24.12.2': resolution: {integrity: sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g==} - asynckit@0.4.0: - resolution: {integrity: sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==} - - axios-proxy-builder@0.1.2: - resolution: {integrity: sha512-6uBVsBZzkB3tCC8iyx59mCjQckhB8+GQrI9Cop8eC7ybIsvs/KtnNgEBfRMSEa7GqK2VBGUzgjNYMdPIfotyPA==} - - axios@1.15.2: - resolution: {integrity: sha512-wLrXxPtcrPTsNlJmKjkPnNPK2Ihe0hn0wGSaTEiHRPxwjvJwT3hKmXF4dpqxmPO9SoNb2FsYXj/xEo0gHN+D5A==} - - balanced-match@4.0.4: - resolution: {integrity: sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==} - engines: {node: 18 || 20 || >=22} - - brace-expansion@5.0.6: - resolution: {integrity: sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g==} - engines: {node: 18 || 20 || >=22} - - call-bind-apply-helpers@1.0.2: - resolution: {integrity: sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==} - engines: {node: '>= 0.4'} - - clone@1.0.4: - resolution: {integrity: sha512-JQHZ2QMW6l3aH/j6xCqQThY/9OH4D/9ls34cgkUBiEeocRTU04tHfKPBsUK1PqZCUQM7GiA0IIXJSuXHI64Kbg==} - engines: {node: '>=0.8'} - - combined-stream@1.0.8: - resolution: {integrity: sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg==} - engines: {node: '>= 0.8'} - - console.table@0.10.0: - resolution: {integrity: sha512-dPyZofqggxuvSf7WXvNjuRfnsOk1YazkVP8FdxH4tcH2c37wc79/Yl6Bhr7Lsu00KMgy2ql/qCMuNu8xctZM8g==} - engines: {node: '> 0.10'} - - defaults@1.0.4: - resolution: {integrity: sha512-eFuaLoy/Rxalv2kr+lqMlUnrDWV+3j4pljOIJgLIhI058IQfWJ7vXhyEIHu+HtC738klGALYxOKDO0bQP3tg8A==} - - delayed-stream@1.0.0: - resolution: {integrity: sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==} - engines: {node: '>=0.4.0'} - - detect-libc@2.1.2: - resolution: {integrity: sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==} - engines: {node: '>=8'} - - dunder-proto@1.0.1: - resolution: {integrity: sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==} - engines: {node: '>= 0.4'} - - easy-table@1.1.0: - resolution: {integrity: sha512-oq33hWOSSnl2Hoh00tZWaIPi1ievrD9aFG82/IgjlycAnW9hHx5PkJiXpxPsgEE+H7BsbVQXFVFST8TEXS6/pA==} - - es-define-property@1.0.1: - resolution: {integrity: sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==} - engines: {node: '>= 0.4'} - - es-errors@1.3.0: - resolution: {integrity: sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==} - engines: {node: '>= 0.4'} - - es-object-atoms@1.1.1: - resolution: {integrity: sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA==} - engines: {node: '>= 0.4'} - - es-set-tostringtag@2.1.0: - resolution: {integrity: sha512-j6vWzfrGVfyXxge+O0x5sh6cvxAog0a/4Rdd2K36zCMV5eJ+/+tOAngRO8cODMNWbVRdVlmGZQL2YS3yR8bIUA==} - engines: {node: '>= 0.4'} - - follow-redirects@1.16.0: - resolution: {integrity: sha512-y5rN/uOsadFT/JfYwhxRS5R7Qce+g3zG97+JrtFZlC9klX/W5hD7iiLzScI4nZqUS7DNUdhPgw4xI8W2LuXlUw==} - engines: {node: '>=4.0'} - peerDependencies: - debug: '*' - peerDependenciesMeta: - debug: - optional: true - - form-data@4.0.5: - resolution: {integrity: sha512-8RipRLol37bNs2bhoV67fiTEvdTrbMUYcFTiy3+wuuOnUog2QBHCZWXDRijWQfAkhBj2Uf5UnVaiWwA5vdd82w==} - engines: {node: '>= 6'} - - function-bind@1.1.2: - resolution: {integrity: sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==} - - get-intrinsic@1.3.0: - resolution: {integrity: sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==} - engines: {node: '>= 0.4'} - - get-proto@1.0.1: - resolution: {integrity: sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==} - engines: {node: '>= 0.4'} - - glob@13.0.6: - resolution: {integrity: sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw==} - engines: {node: 18 || 20 || >=22} - - gopd@1.2.0: - resolution: {integrity: sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==} - engines: {node: '>= 0.4'} - - has-symbols@1.1.0: - resolution: {integrity: sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==} - engines: {node: '>= 0.4'} - - has-tostringtag@1.0.2: - resolution: {integrity: sha512-NqADB8VjPFLM2V0VvHUewwwsw0ZWBaIdgo+ieHtK3hasLz4qeCRjYcqfB6AQrBggRKppKF8L52/VqdVsO47Dlw==} - engines: {node: '>= 0.4'} - - hasown@2.0.3: - resolution: {integrity: sha512-ej4AhfhfL2Q2zpMmLo7U1Uv9+PyhIZpgQLGT1F9miIGmiCJIoCgSmczFdrc97mWT4kVY72KA+WnnhJ5pghSvSg==} - engines: {node: '>= 0.4'} - - lru-cache@11.3.5: - resolution: {integrity: sha512-NxVFwLAnrd9i7KUBxC4DrUhmgjzOs+1Qm50D3oF1/oL+r1NpZ4gA7xvG0/zJ8evR7zIKn4vLf7qTNduWFtCrRw==} - engines: {node: 20 || >=22} - marked@17.0.5: resolution: {integrity: sha512-6hLvc0/JEbRjRgzI6wnT2P1XuM1/RrrDEX0kPt0N7jGm1133g6X7DlxFasUIx+72aKAr904GTxhSLDrd5DIlZg==} engines: {node: '>= 20'} hasBin: true - math-intrinsics@1.1.0: - resolution: {integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==} - engines: {node: '>= 0.4'} - - mime-db@1.52.0: - resolution: {integrity: sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==} - engines: {node: '>= 0.6'} - - mime-types@2.1.35: - resolution: {integrity: sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==} - engines: {node: '>= 0.6'} - - minimatch@10.2.5: - resolution: {integrity: sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg==} - engines: {node: 18 || 20 || >=22} - - minipass@7.1.3: - resolution: {integrity: sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==} - engines: {node: '>=16 || 14 >=14.17'} - - package-json-from-dist@1.0.1: - resolution: {integrity: sha512-UEZIS3/by4OC8vL3P2dTXRETpebLI2NiI5vIrjaD/5UtrkFX/tNbwjTSRAGC/+7CAo2pIcBaRgWmcBBHcsaCIw==} - - path-scurry@2.0.2: - resolution: {integrity: sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg==} - engines: {node: 18 || 20 || >=22} - prettier@3.4.2: resolution: {integrity: sha512-e9MewbtFo+Fevyuxn/4rrcDAaq0IYxPGLvObpQjiZBMAzB9IGmzlnG9RZy3FFas+eBMu2vA0CszMeduow5dIuQ==} engines: {node: '>=14'} hasBin: true - proxy-from-env@2.1.0: - resolution: {integrity: sha512-cJ+oHTW1VAEa8cJslgmUZrc+sjRKgAKl3Zyse6+PV38hZe/V6Z14TbCuXcan9F9ghlz4QrFr2c92TNF82UkYHA==} - engines: {node: '>=10'} - - rimraf@6.1.3: - resolution: {integrity: sha512-LKg+Cr2ZF61fkcaK1UdkH2yEBBKnYjTyWzTJT6KNPcSPaiT7HSdhtMXQuN5wkTX0Xu72KQ1l8S42rlmexS2hSA==} - engines: {node: 20 || >=22} - hasBin: true - - tunnel@0.0.6: - resolution: {integrity: sha512-1h/Lnq9yajKY2PEbBadPXj3VxsDDu844OnaAo52UVmIzIvwwtBPIuNvkjuzBlTWpfJyUbG3ez0KSBibQkj4ojg==} - engines: {node: '>=0.6.11 <=0.7.0 || >=0.7.3'} - typescript@5.8.3: resolution: {integrity: sha512-p1diW6TqL9L07nNxvRMM7hMMw4c5XOo/1ibL4aAIGmSAt9slTE1Xgw5KWuof2uTOvCg9BY7ZRi+GaF+7sfgPeQ==} engines: {node: '>=14.17'} @@ -369,9 +193,6 @@ packages: undici-types@7.16.0: resolution: {integrity: sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==} - wcwidth@1.0.1: - resolution: {integrity: sha512-XHPEwS0q6TaxcvG85+8EYkbiCux2XtWG2mkc47Ng2A77BQu9+DqIOJldST4HgPkuea7dvKSj5VgX3P1d4rW8Tg==} - snapshots: '@biomejs/biome@2.4.0': @@ -409,179 +230,14 @@ snapshots: '@biomejs/cli-win32-x64@2.4.0': optional: true - '@ralph-orchestrator/ralph-cli@2.9.2': - dependencies: - axios: 1.15.2 - axios-proxy-builder: 0.1.2 - console.table: 0.10.0 - detect-libc: 2.1.2 - rimraf: 6.1.3 - transitivePeerDependencies: - - debug - '@types/node@24.12.2': dependencies: undici-types: 7.16.0 - asynckit@0.4.0: {} - - axios-proxy-builder@0.1.2: - dependencies: - tunnel: 0.0.6 - - axios@1.15.2: - dependencies: - follow-redirects: 1.16.0 - form-data: 4.0.5 - proxy-from-env: 2.1.0 - transitivePeerDependencies: - - debug - - balanced-match@4.0.4: {} - - brace-expansion@5.0.6: - dependencies: - balanced-match: 4.0.4 - - call-bind-apply-helpers@1.0.2: - dependencies: - es-errors: 1.3.0 - function-bind: 1.1.2 - - clone@1.0.4: - optional: true - - combined-stream@1.0.8: - dependencies: - delayed-stream: 1.0.0 - - console.table@0.10.0: - dependencies: - easy-table: 1.1.0 - - defaults@1.0.4: - dependencies: - clone: 1.0.4 - optional: true - - delayed-stream@1.0.0: {} - - detect-libc@2.1.2: {} - - dunder-proto@1.0.1: - dependencies: - call-bind-apply-helpers: 1.0.2 - es-errors: 1.3.0 - gopd: 1.2.0 - - easy-table@1.1.0: - optionalDependencies: - wcwidth: 1.0.1 - - es-define-property@1.0.1: {} - - es-errors@1.3.0: {} - - es-object-atoms@1.1.1: - dependencies: - es-errors: 1.3.0 - - es-set-tostringtag@2.1.0: - dependencies: - es-errors: 1.3.0 - get-intrinsic: 1.3.0 - has-tostringtag: 1.0.2 - hasown: 2.0.3 - - follow-redirects@1.16.0: {} - - form-data@4.0.5: - dependencies: - asynckit: 0.4.0 - combined-stream: 1.0.8 - es-set-tostringtag: 2.1.0 - hasown: 2.0.3 - mime-types: 2.1.35 - - function-bind@1.1.2: {} - - get-intrinsic@1.3.0: - dependencies: - call-bind-apply-helpers: 1.0.2 - es-define-property: 1.0.1 - es-errors: 1.3.0 - es-object-atoms: 1.1.1 - function-bind: 1.1.2 - get-proto: 1.0.1 - gopd: 1.2.0 - has-symbols: 1.1.0 - hasown: 2.0.3 - math-intrinsics: 1.1.0 - - get-proto@1.0.1: - dependencies: - dunder-proto: 1.0.1 - es-object-atoms: 1.1.1 - - glob@13.0.6: - dependencies: - minimatch: 10.2.5 - minipass: 7.1.3 - path-scurry: 2.0.2 - - gopd@1.2.0: {} - - has-symbols@1.1.0: {} - - has-tostringtag@1.0.2: - dependencies: - has-symbols: 1.1.0 - - hasown@2.0.3: - dependencies: - function-bind: 1.1.2 - - lru-cache@11.3.5: {} - marked@17.0.5: {} - math-intrinsics@1.1.0: {} - - mime-db@1.52.0: {} - - mime-types@2.1.35: - dependencies: - mime-db: 1.52.0 - - minimatch@10.2.5: - dependencies: - brace-expansion: 5.0.6 - - minipass@7.1.3: {} - - package-json-from-dist@1.0.1: {} - - path-scurry@2.0.2: - dependencies: - lru-cache: 11.3.5 - minipass: 7.1.3 - prettier@3.4.2: {} - proxy-from-env@2.1.0: {} - - rimraf@6.1.3: - dependencies: - glob: 13.0.6 - package-json-from-dist: 1.0.1 - - tunnel@0.0.6: {} - typescript@5.8.3: {} undici-types@7.16.0: {} - - wcwidth@1.0.1: - dependencies: - defaults: 1.0.4 - optional: true From 5c74d232ad7ebc86bb4c8d3371342f372eb50f17 Mon Sep 17 00:00:00 2001 From: Oriol Torrent Florensa Date: Fri, 22 May 2026 20:06:12 +0200 Subject: [PATCH 5/6] fix: address Copilot review comments on ralph removal PR MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove leftover `ralph` scripts from 3 plugin package.json files (the ADR decision stated they should be removed but they were missed) - Fix ADR-0030 title: "Spec Runner" → "Feature Runner" to match the terminology retirement in the ADR body and CONTEXT.md - Expand AGENTS.md docs/ tree to show all actual subdirectories - Fix ADR-0026 link description in ai-development.md to accurately reflect dispatch-by-version-impact content Co-Authored-By: Claude Sonnet 4.6 --- AGENTS.md | 7 ++++++- apps/claude-code/auto-format/package.json | 1 - apps/claude-code/pr-review/package.json | 1 - apps/claude-code/unic-confluence/package.json | 1 - docs/adr/0030-retire-ralph-adopt-archon-runner.md | 2 +- docs/process/ai-development.md | 2 +- 6 files changed, 8 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4fd206e6..216be749 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,7 +21,12 @@ packages/ ├── tsconfig/ # @unic/tsconfig └── release-tools/ # @unic/release-tools (bump / sync-version / tag / verify-changelog) docs/ -└── adr/ # Architectural Decision Records +├── adr/ # Architectural Decision Records +├── agents/ # Agent skill documentation +├── inbox/ # Raw ideas pending triage +├── issues/ # Grilled and scoped feature issues +├── plans/ # Retired spec files (historical) +└── process/ # Process and workflow guides ``` ## Navigation diff --git a/apps/claude-code/auto-format/package.json b/apps/claude-code/auto-format/package.json index ad4fcf26..17931d45 100644 --- a/apps/claude-code/auto-format/package.json +++ b/apps/claude-code/auto-format/package.json @@ -15,7 +15,6 @@ "private": true, "scripts": { "bump": "unic-bump", - "ralph": "ralph run -c ralph.yml -H builtin:code-assist", "sync-version": "unic-sync-version", "tag": "unic-tag", "test": "node --test tests/format-hook.test.mjs scripts/lib/runners.test.mjs scripts/lib/config.test.mjs", diff --git a/apps/claude-code/pr-review/package.json b/apps/claude-code/pr-review/package.json index ba8fce1d..60e4f950 100644 --- a/apps/claude-code/pr-review/package.json +++ b/apps/claude-code/pr-review/package.json @@ -12,7 +12,6 @@ "private": true, "scripts": { "bump": "unic-bump", - "ralph": "ralph run -c ralph.yml -H builtin:code-assist", "sync-version": "unic-sync-version", "tag": "unic-tag", "test": "node --test tests/parse-signature.test.mjs tests/classify-thread.test.mjs tests/match-finding.test.mjs tests/detect-prior-review.test.mjs tests/confluence-client.test.mjs tests/ado-fetcher.test.mjs tests/ado-writer.test.mjs tests/pre-pr.test.mjs tests/parse-diff-hunks.test.mjs tests/mode-detection.test.mjs tests/notices.test.mjs tests/classify-http-error.test.mjs tests/fetch-work-items.test.mjs tests/fetch-iterations.test.mjs tests/parse-write-response.test.mjs tests/detect-default-branch.test.mjs tests/plugin-structure.test.mjs", diff --git a/apps/claude-code/unic-confluence/package.json b/apps/claude-code/unic-confluence/package.json index fbe3f297..032d166d 100644 --- a/apps/claude-code/unic-confluence/package.json +++ b/apps/claude-code/unic-confluence/package.json @@ -19,7 +19,6 @@ "scripts": { "bump": "unic-bump", "confluence": "node scripts/push-to-confluence.mjs", - "ralph": "ralph run -c ralph.yml -H builtin:code-assist", "sync-version": "unic-sync-version", "tag": "unic-tag", "test": "node --test scripts/lib/frontmatter.test.mjs scripts/lib/inject.test.mjs scripts/lib/resolve.test.mjs scripts/lib/slug.test.mjs scripts/lib/pages-file.test.mjs", diff --git a/docs/adr/0030-retire-ralph-adopt-archon-runner.md b/docs/adr/0030-retire-ralph-adopt-archon-runner.md index 1058bf25..17b8b375 100644 --- a/docs/adr/0030-retire-ralph-adopt-archon-runner.md +++ b/docs/adr/0030-retire-ralph-adopt-archon-runner.md @@ -1,4 +1,4 @@ -# 0030. Retire ralph-orchestrator; adopt unic-archon-dlc as the Spec Runner +# 0030. Retire ralph-orchestrator; adopt unic-archon-dlc as the Feature Runner **Status:** Accepted (2026-05) diff --git a/docs/process/ai-development.md b/docs/process/ai-development.md index 9093c640..7896e401 100644 --- a/docs/process/ai-development.md +++ b/docs/process/ai-development.md @@ -160,7 +160,7 @@ The commits from your grilling sessions carry this context forward. The Feature - `docs/process/development-workflow.md` — the 8-phase quick reference - `docs/agents/issue-tracker.md` — issue file conventions - `docs/agents/triage-labels.md` — 8-state triage vocabulary -- `docs/adr/0026-tdd-dispatch-by-version-impact.md` — when the Feature Runner uses /tdd +- `docs/adr/0026-tdd-dispatch-by-version-impact.md` — when to use /tdd vs direct implementation (dispatch by version impact) - `docs/adr/0027-feature-runner-context-bundle.md` — what /tdd receives per invocation - `docs/adr/0028-blocked-by-canonical-sequencing.md` — why ## Blocked by beats filename order - `docs/adr/0029-feature-runner-afk-invocation.md` — how AFK invocation works From eb93e9039759cb583e4270a695a34fd09bc60eb4 Mon Sep 17 00:00:00 2001 From: Oriol Torrent Florensa Date: Fri, 22 May 2026 20:15:07 +0200 Subject: [PATCH 6/6] fix: remove residual ralph/spec-runner references from docs and templates - Remove `ralph` script from both package-json-template.md variants - Remove ralph.yml, PROMPT.md, docs/plans/ stub from new-plugin SKILL.md - Fix docs/plans/README.md Backlog section to use historical-tense framing - feature-runner.md: drop "counterpart to the Spec Runner" framing; mark historical cleanup section as a historical note - AGENTS.md: replace chore(spec-NN) commit example; fix "spec step" in LICENSE section; add conversations/ and research/ to docs tree - CONTRIBUTING.md: replace spec-driven workflow with Feature-driven, remove ralph-loop install step and spec-writing sections Co-Authored-By: Claude Sonnet 4.6 --- .claude/skills/new-plugin/SKILL.md | 6 -- .../references/package-json-template.md | 6 +- AGENTS.md | 7 +- CONTRIBUTING.md | 92 ++++--------------- docs/agents/feature-runner.md | 6 +- docs/plans/README.md | 4 +- 6 files changed, 29 insertions(+), 92 deletions(-) diff --git a/.claude/skills/new-plugin/SKILL.md b/.claude/skills/new-plugin/SKILL.md index 6ac564c8..932e45d8 100644 --- a/.claude/skills/new-plugin/SKILL.md +++ b/.claude/skills/new-plugin/SKILL.md @@ -82,18 +82,12 @@ Only include if the plugin registers hooks. } ``` -**`ralph.yml`** — copy from `apps/claude-code/auto-format/ralph.yml`, replace the comment header plugin name. - -**`PROMPT.md`** — minimal stub: `# — Ralph Prompt\n\nDescribe the task here.` - **`CHANGELOG.md`** — use the exact format from `apps/claude-code/auto-format/CHANGELOG.md` as template. Include only `## [Unreleased]` with empty Breaking/Added/Fixed subsections — no historical version entry yet. **`README.md`** — one-paragraph description of what the plugin does. **`CLAUDE.md`** — plugin-specific guidance (not a symlink at the plugin level; see `auto-format/CLAUDE.md` for structure). -**`docs/plans/README.md`** — stub with: `# Spec Roadmap\n\nSpec files for this plugin go here.` - **`scripts/`** and **`tests/`** — empty directories, only if the plugin has scripts or tests. ## Bundled resources diff --git a/.claude/skills/new-plugin/references/package-json-template.md b/.claude/skills/new-plugin/references/package-json-template.md index 0090aa1c..188fc03f 100644 --- a/.claude/skills/new-plugin/references/package-json-template.md +++ b/.claude/skills/new-plugin/references/package-json-template.md @@ -19,8 +19,7 @@ Use this as the starting shape for a new plugin's `package.json`. Copy `packageM "bump": "unic-bump", "sync-version": "unic-sync-version", "tag": "unic-tag", - "verify:changelog": "unic-verify-changelog", - "ralph": "ralph run -c ralph.yml -H builtin:code-assist" + "verify:changelog": "unic-verify-changelog" }, "devDependencies": { "@types/node": "catalog:", @@ -50,8 +49,7 @@ Omit `test`, `typecheck`, and the `@types/node`/`@unic/tsconfig`/`typescript` de "bump": "unic-bump", "sync-version": "unic-sync-version", "tag": "unic-tag", - "verify:changelog": "unic-verify-changelog", - "ralph": "ralph run -c ralph.yml -H builtin:code-assist" + "verify:changelog": "unic-verify-changelog" }, "devDependencies": { "@unic/release-tools": "workspace:*" diff --git a/AGENTS.md b/AGENTS.md index 216be749..5fdb77eb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,7 +26,8 @@ docs/ ├── inbox/ # Raw ideas pending triage ├── issues/ # Grilled and scoped feature issues ├── plans/ # Retired spec files (historical) -└── process/ # Process and workflow guides +├── process/ # Process and workflow guides +└── research/ # Research notes and explorations ``` ## Navigation @@ -80,7 +81,7 @@ Tag scheme: `@` (e.g. `auto-format@0.5.5`). ## Conventional commits -Use package scope: `feat(auto-format): …`, `fix(pr-review): …`, `chore(release-tools): …`, `chore(spec-NN): …`. +Use package scope: `feat(auto-format): …`, `fix(pr-review): …`, `chore(release-tools): …`, `chore(unic-archon-dlc): …`. ## Git branching (Gitflow) @@ -123,7 +124,7 @@ New work enters through the issue tracker as Features. Use `/tdd` to implement i ## LICENSE files -**Never create, copy, or delete `LICENSE` files.** The maintainer manages these manually in every package and plugin directory. If a spec step or acceptance criterion requires a `LICENSE` file to exist, warn the maintainer to add it themselves before continuing. +**Never create, copy, or delete `LICENSE` files.** The maintainer manages these manually in every package and plugin directory. If an acceptance criterion requires a `LICENSE` file to exist, warn the maintainer to add it themselves before continuing. ## Skill summary diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ed3f1d09..3cf33180 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,8 @@ # Contributing -This monorepo uses a spec-driven development workflow. For the full lifecycle — from idea capture through grilling, PRD, issues, execution, and QA — see **[`docs/process/development-workflow.md`](docs/process/development-workflow.md)**. +This monorepo uses a Feature-driven development workflow. For the full lifecycle — from idea capture through grilling, PRD, issues, execution, and QA — see **[`docs/process/development-workflow.md`](docs/process/development-workflow.md)**. -New features and fixes are described in self-contained spec files under `docs/plans/`. Implementation is automated with the **Spec Runner** (`pnpm ralph`, currently backed by `ralph-orchestrator`) or done by hand following the same steps. +New features and fixes are tracked as Features in the issue tracker under `docs/issues//`. Implementation is driven by the **Feature Runner** (`/implement-feature`) or done manually using `/tdd` for individual issues. ## Cross-cutting standards @@ -48,7 +48,7 @@ Enforced by Biome (`pnpm ci:check`) for `.mjs`/`.js`/`.ts`/`.json`/`.css` and Pr - Zero external runtime deps unless essential (`auto-format` ships zero; `unic-confluence` has `marked` — that's the bar). - Zero-config from the user's perspective: no configuration files users must create beyond credentials. -- Every plugin uses the spec-driven workflow: `docs/plans/` + `ralph.yml` + `PROMPT.md` per the template in `docs/process/`. +- New plugin work enters through the issue tracker as Features — open a Feature before starting implementation. ### License @@ -56,87 +56,29 @@ LGPL-3.0-or-later for all packages in this monorepo. ## Prerequisites -| Tool | Version | How to get it | -| --------------- | ----------------------------------------------- | -------------------------------------------------------------------------------- | -| Node.js | ≥ 22 (see `.nvmrc` for the recommended version) | [nodejs.org](https://nodejs.org) | -| pnpm | ≥ 10 | `npm install -g pnpm` | -| Claude Code CLI | latest | [claude.ai/code](https://claude.ai/code) — required as the Spec Runner's backend | +| Tool | Version | How to get it | +| --------------- | ----------------------------------------------- | ---------------------------------------- | +| Node.js | ≥ 22 (see `.nvmrc` for the recommended version) | [nodejs.org](https://nodejs.org) | +| pnpm | ≥ 10 | `npm install -g pnpm` | +| Claude Code CLI | latest | [claude.ai/code](https://claude.ai/code) | -Everything else (ralph-orchestrator, Biome, Prettier, TypeScript) is a workspace devDependency and installs with: +Everything else (Biome, Prettier, TypeScript) is a workspace devDependency and installs with: ```sh pnpm install ``` -**ralph-loop** is a Claude Code plugin and must be installed once globally: +## Starting new work -```sh -claude plugins install anthropics/claude-plugins-official/plugins/ralph-loop -``` - -## Writing a spec - -All work starts with a spec file. See the existing specs under `docs/plans/` for examples. - -### 1. Pick a number - -Check `docs/plans/README.md` for the current highest spec number. Create `docs/plans/NN-short-slug.md`. - -### 2. Required metadata - -```markdown -# NN. Title - -**Priority:** P0 | P1 | P2 -**Effort:** XS | S | M | L -**Version impact:** none | patch (plugin: ) | minor (plugin: ) | major (plugin: ) -**Depends on:** (spec numbers, or "none") -**Touches:** (comma-separated files/dirs) -``` - -### 3. Required sections - -| Section | What to write | -| ------------------------- | ---------------------------------------- | -| `## Context` | Why this change is needed | -| `## Current behaviour` | Exact code/behaviour _before_ the change | -| `## Target behaviour` | What it should look like _after_ | -| `## Affected files` | Table: path → Create / Modify / Delete | -| `## Implementation steps` | Numbered steps with before → after diffs | -| `## Verification` | Shell commands + expected output | -| `## Acceptance criteria` | Checkbox list | -| `## Out of scope` | Explicit list of things NOT to change | - -Good specs are **self-contained** — the Spec Runner has no memory of prior runs. Include actual code snapshots. +All work enters through the issue tracker as a Feature. The recommended flow: -### 4. Register the spec +1. Capture the idea with `/inbox ` or open a GitHub Issue directly. +2. Grill the design with `/grill-me` or `/grill-with-docs` until the problem and solution are clear. +3. Create a PRD and issues with `/to-prd` → `/to-issues`. +4. Implement: `/implement-feature ` for automated AFK execution, or `/tdd` manually for individual issues. +5. Open a PR targeting `develop`. -Add a row to the execution order table in `docs/plans/README.md`. - -## Running the Spec Runner - -```sh -pnpm ralph -``` - -The Spec Runner reads `ralph.yml`, which points to `PROMPT.md`. Each iteration implements one spec, commits, and stops. Run `pnpm ralph` again for the next spec. - -- **Stop early**: `Ctrl+C` -- **Resume**: `pnpm ralph` again — it finds the first unfinished spec -- **Paused for review**: a `## Questions` section in a spec means the Spec Runner emitted `LOOP_COMPLETE` — answer the question, remove the section, re-run - -## Running manually (without the Spec Runner) - -Follow the steps in `PROMPT.md` yourself, replacing the Spec Runner's role. - -## Running per-plugin Spec Runner loops - -Each plugin also has its own `ralph.yml` + `PROMPT.md` for plugin-specific development. Run from inside the plugin directory: - -```sh -cd apps/claude-code/pr-review -pnpm ralph -``` +See [`docs/process/development-workflow.md`](docs/process/development-workflow.md) for the full 8-phase lifecycle. ## Verification commands diff --git a/docs/agents/feature-runner.md b/docs/agents/feature-runner.md index e013e5a7..da361787 100644 --- a/docs/agents/feature-runner.md +++ b/docs/agents/feature-runner.md @@ -1,6 +1,6 @@ # Feature Runner -The Feature Runner is the `/implement-feature` skill. It automates the implementation side of the AI-development cycle: given a Feature slug, it creates an isolated branch, works through all `ready-for-agent` issues in dependency order using `/tdd`, opens a pull request, and marks each issue `resolved`. It is the issue-tracker-driven counterpart to the Spec Runner. +The Feature Runner is the `/implement-feature` skill. It automates the implementation side of the AI-development cycle: given a Feature slug, it creates an isolated branch, works through all `ready-for-agent` issues in dependency order using `/tdd`, opens a pull request, and marks each issue `resolved`. Invoke it with `/implement-feature ` (named Feature) or `/implement-feature` (auto-select). Compose it with `/loop` for overnight queue draining. @@ -109,7 +109,9 @@ Re-running `/implement-feature ` after a manual fix resumes from the first ## Historical cleanup convention -When a Spec in `docs/plans/` is marked `done` and a corresponding `docs/issues//` directory exists, the issues in that directory were implemented via the Spec Runner, not the Feature Runner. They will never be processed by `/implement-feature` and should not remain at `ready-for-agent`. +> **Historical note:** This section describes a one-time cleanup task from the `ralph-orchestrator` retirement (see [ADR-0030](../adr/0030-retire-ralph-adopt-archon-runner.md)). It does not apply to Features created after 2026-05. + +When a spec in `docs/plans/` was marked `done` and a corresponding `docs/issues//` directory exists, those issues were implemented via the retired Spec Runner, not the Feature Runner. They will never be processed by `/implement-feature` and should not remain at `ready-for-agent`. **Convention**: manually mark all `NN-*.md` files in `docs/issues//` as `closed` and append a note: diff --git a/docs/plans/README.md b/docs/plans/README.md index 62cb2db3..5cab60e7 100644 --- a/docs/plans/README.md +++ b/docs/plans/README.md @@ -27,7 +27,7 @@ This directory contains the historical spec set for the `unic-agents-plugins` mo ## Backlog -Ideas that need a spec before Ralph can run them. When you're ready to act on one, ask Claude to write the spec (`NN-name.md`), review it, then hand it to Ralph. +> **Historical.** These ideas were never spec'd before `docs/plans/` was retired. If still relevant, triage them into the issue tracker (`docs/issues/`) via `/triage`. | Idea | Priority | Notes | |---|---|---| @@ -35,7 +35,7 @@ Ideas that need a spec before Ralph can run them. When you're ready to act on on | Bake `pnpm format` into `bump-version.mjs` | P2 | Every bump leaves CHANGELOG.md in a state Prettier disagrees with, requiring a manual `pnpm format` step; discovered during spec 14 | | GitHub Release notes automation | P3 | Auto-generate release notes from CHANGELOG.md when the release workflow fires a tag | -**Manual actions pending (not Ralph specs):** +**Pending manual actions:** - Execute smoke test checklist (`docs/process/smoke-test-checklist.md`) — requires a scratch Claude Code environment, an Azure DevOps PR URL, and Confluence credentials