Compound Engineering · Implementation Plan

# Remove ce-work-beta Skill - Plan

Retire the experimental Codex external-delegation skill and complete the repo's required removal cleanup, keeping the reusable delegation learnings.

Type
  chore
Date
  2026-06-26
Topic
  `remove-ce-work-beta`
Artifact
  `ce-unified-plan/v1`
Readiness
  `implementation-ready`
Source
  `ce-brainstorm`
Execution
  `code`

## Goal Capsule

Objective
  Remove the unmaintained `ce-work-beta` skill (the Codex shell-out delegation experiment) and complete every cleanup the repo's conventions require, while preserving the reusable external-delegation learnings.
Authority
  Trevin Chow (plugin maintainer). The Product Contract is the source of truth; planning corrections to it are noted below.
Execution profile
  Single small PR off a feature branch. Mechanical removal plus one documentation edit; no architectural risk.
Stop conditions
  Stop and surface if removing the skill breaks a test whose intent is to verify live delegation behavior in a way the plan didn't anticipate, or if `release:validate` fails for a reason other than the skill count. Do not expand scope into the historical plan docs or CHANGELOG.
Tail ownership
  Implementer runs `bun test` and `bun run release:validate` to green, then opens a PR with a `chore(ce-work-beta):`-scoped title. All changes to `main` go through the PR; no direct push.
Open blockers
  None.

## Product Contract

Product Contract preservation Requirements unchanged in intent. R5 clarified: there is no skill count stored in a release manifest — the count lives in README prose (R4) and one test assertion (`tests/release-metadata.test.ts`), and `release:validate` auto-derives counts from disk. R5 is reframed from "sync the release manifest count" to "fix the README + test count and run `release:validate` to confirm sync." No product-scope change.

### Summary

Delete the `ce-work-beta` skill from the plugin and perform the full set of cleanups its removal triggers: stale-install registries, the README inventory and skill count, the delegation-parity contract tests, and the release-metadata test count. The skill is beta and `disable-model-invocation: true` with no downstream handoffs, so removal is a hard delete rather than a deprecation. The Codex token-economics learnings are kept as a standalone reference; the now-moot promotion checklist is deleted.

### Problem Frame

`ce-work-beta` was a beta surface for routing implementation work to the Codex CLI via `codex exec`. The delegation machinery — config parsing, per-batch effort selection, sandbox routing, and the ~23 KB delegation-workflow reference — has ongoing carrying cost. Keeping the shell-out path correct as `ce-work` evolves means maintaining a parallel orchestration surface that stayed beta, manual-only, and isolated from planning/workflow handoffs by design. The maintenance burden now outweighs the value the experiment returns, so the experiment ends.

### Requirements

Skill removal

ID | Requirement
--- | ---
R1 | Delete the entire `skills/ce-work-beta/` directory tree, including `SKILL.md` and all files under `references/`.

Stale-install cleanup

ID | Requirement
--- | ---
R2 | Add `ce-work-beta` (dash variant) to `STALE_SKILL_DIRS` in `src/utils/legacy-cleanup.ts` so upgrades sweep the flat-install skill directory. The colon variant `ce:work-beta` is already present and stays.
R3 | Add `ce-work-beta` to `EXTRA_LEGACY_ARTIFACTS_BY_PLUGIN["compound-engineering"].skills` in `src/data/plugin-legacy-artifacts.ts` for the same reason.

Inventory and release sync

ID | Requirement
--- | ---
R4 | Update `README.md`: remove the `/ce-work-beta` inventory row and change the stated skill count from 27 to 26.
R5 | Fix the hardcoded skill-count assertion in `tests/release-metadata.test.ts` (27 to 26) and run `bun run release:validate` to confirm metadata is in sync. The count auto-derives from skill directories; do not hand-bump release-owned versions.

Knowledge preservation

ID | Requirement
--- | ---
R6 | Edit `docs/solutions/best-practices/codex-delegation-best-practices.md` to read as a standalone external-delegation reference: keep the token-economics and batching learnings, remove the parts that depend on `ce-work-beta` existing as a live skill.
R7 | Delete `docs/solutions/skill-design/ce-work-beta-promotion-checklist.md` — no longer applicable once the skill is removed rather than promoted.

Tests

ID | Requirement
--- | ---
R8 | Remove the `ce-work-beta` delegation-parity assertions in `tests/pipeline-review-contract.test.ts` (the tests that read the deleted skill to verify it mirrors `ce-work`).
R9 | Repair the remaining test references so `bun test` passes: fix the stale-install cleanup tests to stop reading the deleted `SKILL.md` while keeping their sweep assertions, drop `ce-work-beta` from the user-invoked-skills set, and repoint the converter example off the dead name.

### Scope Boundaries

Not in scope

- The historical plan docs in `docs/plans/` that mention `ce-work-beta` as an active work surface stay untouched — they record past state, and version control holds history.
- Existing `CHANGELOG.md` entries referencing `ce-work-beta` are left as-is — release-owned history, not hand-edited here.

Explicitly rejected Promoting Codex delegation into stable `ce-work`. The decision is to end the experiment, not graduate it; the promotion path is being deleted, not taken.

## Planning Contract

### Key Technical Decisions

KTD1Hard delete, not a deprecation stub The skill is beta, `disable-model-invocation: true`, and no other skill (planning, brainstorm, lfg, compound) hands off to it, so there is no user path to soften. The directory is removed outright and the name is added to the cleanup registries so existing flat installs get swept on upgrade.
KTD2Add the dash variant only to the two registries that lack it `legacy-cleanup.ts` already carries `ce-work-beta` in `STALE_PROMPT_FILES`, `LEGACY_SKILL_DESCRIPTION_ALIASES`, `LEGACY_PROMPT_CURRENT_SKILL_FOR_FILE`, and `LEGACY_PROMPT_DESCRIPTION_ALIASES` from the earlier `ce:`→`ce-` rename. Only `STALE_SKILL_DIRS` (R2) and the artifacts skills array (R3) are missing the dash variant. Add only those two; do not duplicate the existing entries.
KTD3Keep the stale-install cleanup tests; delete only the delegation-parity tests The registries continue to target `ce-work-beta`, so "a leftover `ce-work-beta` install gets swept" stays a tested behavior. The legacy-cleanup tests keep that assertion but must stop reading the deleted `skills/ce-work-beta/SKILL.md` (replace the runtime `pluginDescription(...)` read with the literal historical description already encoded in `LEGACY_SKILL_DESCRIPTION_ALIASES`). The `pipeline-review-contract` tests verify a capability that no longer exists and are deleted whole.
KTD4The skill count is README prose plus one test assertion, not a release manifest value `getCompoundEngineeringCounts` in `src/release/metadata.ts` derives the count from on-disk skill directories. `release:validate` reports it but does not fail on a README mismatch and does not write the count back. The only enforced copy is `tests/release-metadata.test.ts:150` (caught by `bun test`). So the count fix is two hand-edits (README prose + that assertion), not a manifest bump.

### Assumptions

- No test asserts README inventory contents or the prose skill count — verified: only `tests/release-metadata.test.ts:150` hardcodes `27`.
- The kept best-practices doc has standalone value independent of the skill. If a closer read shows it is inseparable from `ce-work-beta`, fall back to deleting it (the brainstorm's "delete all" option) and note that in the PR.

### Sources & Research

- Cleanup-registry convention: repo agent instructions require adding a removed skill to both `STALE_SKILL_DIRS`/`STALE_AGENT_NAMES`/`STALE_PROMPT_FILES` in `src/utils/legacy-cleanup.ts` and `EXTRA_LEGACY_ARTIFACTS_BY_PLUGIN["compound-engineering"]` in `src/data/plugin-legacy-artifacts.ts`.
- Existing `ce-work-beta` references mapped across `src/utils/legacy-cleanup.ts`, `src/data/plugin-legacy-artifacts.ts`, `tests/legacy-cleanup.test.ts`, `tests/pipeline-review-contract.test.ts`, `tests/skill-conventions.test.ts`, `tests/copilot-converter.test.ts`, `tests/release-metadata.test.ts`, and `README.md`.

## Implementation Units

### U1. Delete the ce-work-beta skill tree

Goal
  Remove the skill itself.
Requirements
  R1
Dependencies
  None
Files
  `skills/ce-work-beta/` (entire tree: `SKILL.md` + `references/`)

Execution noteLand U1 together with U3 in the same PR — deleting the tree red-lines the tests that read it until U3 lands. The PR tip must be green.
Approach & verification

Pure deletion of the directory. After this, `countSkillDirectories` returns 26 automatically. No code references the skill at import time — all remaining references are string literals in tests and registries handled by other units.

Test expectation: none — pure file deletion; the absence is proven by U3's suite repair and the Verification Contract grep.

Verification: `skills/ce-work-beta/` no longer exists.

### U2. Add dash variant to the two cleanup registries

Goal
  Ensure existing installs sweep the now-stale `ce-work-beta` skill directory on upgrade.
Requirements
  R2, R3
Dependencies
  None
Files
  `src/utils/legacy-cleanup.ts`, `src/data/plugin-legacy-artifacts.ts`

Approach, patterns & test scenarios

Approach: Add the string `"ce-work-beta"` to `STALE_SKILL_DIRS` (next to the existing `"ce:work-beta"`) and to `EXTRA_LEGACY_ARTIFACTS_BY_PLUGIN["compound-engineering"].skills` (next to its `"ce:work-beta"`). Per KTD2, do not touch the prompt-file / description-alias registries — they already carry the dash variant.

Patterns to follow: mirror the adjacent `ce:work-beta` entries; keep alphabetical/grouped ordering consistent with neighbors.

Test scenarios:

- Cleanup sweep: a fixture containing a stale `ce-work-beta` skill directory is removed by the cleanup routine (extends the existing prompt-file sweep coverage to the skill-dir registry entry).
- Registry membership: `STALE_SKILL_DIRS` and the artifacts skills array each contain both `ce:work-beta` and `ce-work-beta`.

Verification: the cleanup tests in U3 pass with the new entries.

### U3. Repair the test suite

Goal
  Make `bun test` green after the skill and its parity surface are gone.
Requirements
  R5, R8, R9
Dependencies
  U1, U2
Files
  `tests/pipeline-review-contract.test.ts`, `tests/legacy-cleanup.test.ts`, `tests/skill-conventions.test.ts`, `tests/copilot-converter.test.ts`, `tests/release-metadata.test.ts`

Approach & test scenarios

Approach (per file):

- `pipeline-review-contract.test.ts` — delete the four named `ce-work-beta` tests and the `ce:work-beta codex delegation contract` describe block (all read the deleted skill to assert delegation parity). (R8)
- `legacy-cleanup.test.ts` — keep both tests that assert a stale `ce-work-beta.md` wrapper is removed, but replace the `pluginDescription("skills/ce-work-beta/SKILL.md")` runtime read with the literal historical description string (already encoded in `LEGACY_SKILL_DESCRIPTION_ALIASES`), so the test no longer depends on the deleted file. (R9, KTD3)
- `skill-conventions.test.ts` — remove `"ce-work-beta"` from `EXPECTED_USER_INVOKED_SKILLS`. (R9)
- `copilot-converter.test.ts` — repoint the multi-colon transform example off the dead skill name (use a live or neutral example) so no test references a removed skill. (R9)
- `release-metadata.test.ts` — change the `skills: 27` assertion to `26`. (R5)

Test scenarios:

- Full suite green: `bun test` passes with no `ce-work-beta` SKILL.md reads.
- Count assertion: `getCompoundEngineeringCounts` reports `skills: 26`.
- Stale-install sweep still asserted: the `ce-work-beta.md` removal tests pass without touching the filesystem skill dir.
- Converter transform still correct after the example swap (colon→dash output unchanged in behavior).

Verification: `bun test` green.

### U4. Update README inventory and count

Goal
  Keep the public inventory accurate.
Requirements
  R4
Dependencies
  None
Files
  `README.md`

Approach & verification

Approach: Remove the `| /ce-work-beta | ... |` inventory row and change "currently ships 27 skills" to "26 skills".

Test expectation: none — documentation prose; no test asserts README contents (verified).

Verification: no `ce-work-beta` row remains; count reads 26.

### U5. Decouple the best-practices doc

Goal
  Preserve the delegation learnings as a standalone reference.
Requirements
  R6
Dependencies
  None
Files
  `docs/solutions/best-practices/codex-delegation-best-practices.md`

Approach & verification

Approach: Keep the token-economics crossover (~5–7 unit threshold) and batching guidance. Remove or rewrite passages that frame the doc as `ce-work-beta` usage (references to the live skill, its config keys, the promotion path) so it reads as general external-delegation knowledge. Update frontmatter tags if they name the skill.

Test expectation: none — documentation.

Verification: the doc stands alone; no dangling references to `ce-work-beta` as a live skill.

### U6. Delete the promotion checklist

Goal
  Remove the now-moot promotion doc.
Requirements
  R7
Dependencies
  None
Files
  `docs/solutions/skill-design/ce-work-beta-promotion-checklist.md`

Approach & verification

Approach: Delete the file. Grep `docs/solutions/` for inbound links to it and fix any (likely none).

Test expectation: none — documentation.

Verification: file gone; no broken links to it.

## Verification Contract

- `bun test` — full suite green, including the repaired cleanup, conventions, converter, and release-metadata tests.
- `bun run release:validate` — reports `compound-engineering currently has 0 agents, 26 skills, ...` and exits in sync (no metadata errors).
- `rg -n "ce-work-beta" .` — the only surviving matches are historical files in `docs/plans/`, `CHANGELOG.md` history, and this plan document. No live skill, registry-absent reference, README row, or test reading the deleted SKILL.md remains.

## Definition of Done

- R1–R9 satisfied.
- `bun test` and `bun run release:validate` both green; `release:validate` reports 26 skills.
- No reference to `ce-work-beta` as a live skill anywhere except historical plan docs, CHANGELOG history, and this plan.
- The best-practices doc reads standalone; the promotion checklist is deleted.
- No abandoned or experimental code left in the diff; changes land in one PR with a `chore(ce-work-beta):` title via the standard PR flow (no direct push to `main`).