262 lines
13 KiB
Markdown
262 lines
13 KiB
Markdown
---
|
||
title: "feat: Add ce:* command aliases with backwards-compatible deprecation of workflows:*"
|
||
type: feat
|
||
status: active
|
||
date: 2026-03-01
|
||
---
|
||
|
||
# feat: Add `ce:*` Command Aliases with Backwards-Compatible Deprecation of `workflows:*`
|
||
|
||
## Overview
|
||
|
||
Rename the five `workflows:*` commands to `ce:*` to make it clearer they belong to compound-engineering. Keep `workflows:*` working as thin deprecation wrappers that warn users and forward to the new commands.
|
||
|
||
## Problem Statement / Motivation
|
||
|
||
The current `workflows:plan`, `workflows:work`, `workflows:review`, `workflows:brainstorm`, and `workflows:compound` commands are prefixed with `workflows:` — a generic namespace that doesn't signal their origin. Users don't immediately associate them with the compound-engineering plugin.
|
||
|
||
The `ce:` prefix is shorter, more memorable, and unambiguously identifies these as compound-engineering commands — consistent with how other plugin commands already use `compound-engineering:` as a namespace.
|
||
|
||
## Proposed Solution
|
||
|
||
### 1. Create New `ce:*` Commands (Primary)
|
||
|
||
Create a `commands/ce/` directory with five new command files. Each file gets the full implementation content from the current `workflows:*` counterpart, with the `name:` frontmatter updated to the new name.
|
||
|
||
| New Command | Source Content |
|
||
|-------------|---------------|
|
||
| `ce:plan` | `commands/workflows/plan.md` |
|
||
| `ce:work` | `commands/workflows/work.md` |
|
||
| `ce:review` | `commands/workflows/review.md` |
|
||
| `ce:brainstorm` | `commands/workflows/brainstorm.md` |
|
||
| `ce:compound` | `commands/workflows/compound.md` |
|
||
|
||
### 2. Convert `workflows:*` to Deprecation Wrappers (Backwards Compatibility)
|
||
|
||
Replace the full content of each `workflows:*` command with a thin wrapper that:
|
||
1. Displays a visible deprecation warning to the user
|
||
2. Invokes the new `ce:*` command with the same `$ARGUMENTS`
|
||
|
||
Example wrapper body:
|
||
|
||
```markdown
|
||
---
|
||
name: workflows:plan
|
||
description: "[DEPRECATED] Use /ce:plan instead. Renamed for clarity."
|
||
argument-hint: "[feature description]"
|
||
---
|
||
|
||
> ⚠️ **Deprecated:** `/workflows:plan` has been renamed to `/ce:plan`.
|
||
> Please update your workflow to use `/ce:plan` instead.
|
||
> This alias will be removed in a future version.
|
||
|
||
/ce:plan $ARGUMENTS
|
||
```
|
||
|
||
### 3. Update All Internal References
|
||
|
||
The grep reveals `workflows:*` is referenced in **many more places** than just `lfg`/`slfg`. All of these must be updated to point to the new `ce:*` names:
|
||
|
||
**Orchestration commands (update to new names):**
|
||
- `commands/lfg.md` — `/workflows:plan`, `/workflows:work`, `/workflows:review`
|
||
- `commands/slfg.md` — `/workflows:plan`, `/workflows:work`, `/workflows:review`
|
||
|
||
**Command bodies that cross-reference (update to new names):**
|
||
- `commands/workflows/brainstorm.md` — references `/workflows:plan` multiple times (will be in the deprecated wrapper, so should forward to `/ce:plan`)
|
||
- `commands/workflows/compound.md` — self-references and references `/workflows:plan`
|
||
- `commands/workflows/plan.md` — references `/workflows:work` multiple times
|
||
- `commands/deepen-plan.md` — references `/workflows:work`, `/workflows:compound`
|
||
|
||
**Agents (update to new names):**
|
||
- `agents/review/code-simplicity-reviewer.md` — references `/workflows:plan` and `/workflows:work`
|
||
- `agents/research/git-history-analyzer.md` — references `/workflows:plan`
|
||
- `agents/research/learnings-researcher.md` — references `/workflows:plan`
|
||
|
||
**Skills (update to new names):**
|
||
- `skills/document-review/SKILL.md` — references `/workflows:brainstorm`, `/workflows:plan`
|
||
- `skills/git-worktree/SKILL.md` — references `/workflows:review`, `/workflows:work` extensively
|
||
- `skills/setup/SKILL.md` — references `/workflows:review`, `/workflows:work`
|
||
- `skills/brainstorming/SKILL.md` — references `/workflows:plan` multiple times
|
||
- `skills/file-todos/SKILL.md` — references `/workflows:review`
|
||
|
||
**Other commands (update to new names):**
|
||
- `commands/test-xcode.md` — references `/workflows:review`
|
||
|
||
**Historical docs (leave as-is — they document the old names intentionally):**
|
||
- `docs/plans/*.md` — old plan files, historical record
|
||
- `docs/brainstorms/*.md` — historical
|
||
- `docs/solutions/*.md` — historical
|
||
- `tests/fixtures/` — test fixtures for the converter (intentionally use `workflows:*` to test namespace handling)
|
||
- `CHANGELOG.md` historical entries — don't rewrite history
|
||
|
||
### 4. Update Documentation
|
||
|
||
- `CHANGELOG.md` — add new entry documenting the rename and deprecation
|
||
- `plugins/compound-engineering/README.md` — update command table to list `ce:*` as primary, note `workflows:*` as deprecated aliases
|
||
- `plugins/compound-engineering/CLAUDE.md` — update command listing and the "Why `workflows:`?" section
|
||
- Root `README.md` — update the command table (lines 133–136)
|
||
|
||
### 5. Converter / bunx Install Script Considerations
|
||
|
||
The `bunx` install script (`src/commands/install.ts`) **only writes files, never deletes them**. This has two implications:
|
||
|
||
**Now (while deprecated wrappers exist):** No stale file problem. Running `bunx install compound-engineering --to gemini` after this change will:
|
||
- Write `commands/ce/plan.toml` (new primary)
|
||
- Write `commands/workflows/plan.toml` (deprecated wrapper, with deprecation content)
|
||
|
||
Both coexist correctly. Users who re-run install get both.
|
||
|
||
**Future (when deprecated wrappers are eventually removed):** The old `commands/workflows/` files will remain stale in users' converted targets. At that point, a cleanup step will be needed — either:
|
||
- Manual instructions: "Delete `.gemini/commands/workflows/` after upgrading"
|
||
- OR add a cleanup pass to the install script that removes known-renamed command directories
|
||
|
||
For now, document in the plan that stale cleanup is a known future concern when `workflows:*` wrappers are eventually dropped.
|
||
|
||
## Technical Considerations
|
||
|
||
### Command Naming
|
||
|
||
The `ce:` prefix maps to a `commands/ce/` directory. This follows the existing convention where `workflows:plan` maps to `commands/workflows/plan.md`.
|
||
|
||
### Deprecation Warning Display
|
||
|
||
Since commands are executed by Claude, the deprecation message in the wrapper body will be displayed to the user as Claude's response before the new command runs. The `>` blockquote markdown renders as a styled callout.
|
||
|
||
The deprecated wrappers should **not** use `disable-model-invocation: true` — Claude needs to process the body to display the warning and invoke the new command.
|
||
|
||
### Deprecation Wrapper Mechanism
|
||
|
||
The deprecated wrappers **must** use `disable-model-invocation: true`. This is the same mechanism `lfg.md` uses — the CLI runtime parses the body and executes slash command invocations directly. Without it, Claude reads the body as text and cannot actually invoke `/ce:plan`.
|
||
|
||
The deprecation notice in the wrapper body becomes a printed note (same as `lfg` step descriptions), not a styled Claude response. That's acceptable — it still communicates the message.
|
||
|
||
### Context Token Budget
|
||
|
||
The 5 new `ce:*` commands add descriptions to the context budget. Keep descriptions short (under 120 chars). The 5 deprecated `workflows:*` wrappers have minimal descriptions (tagged as deprecated) to minimize budget impact.
|
||
|
||
### Count Impact
|
||
|
||
Command count remains 22 (5 new `ce:*` + 5 updated `workflows:*` wrappers = net zero change). No version bump required for counts.
|
||
|
||
## Acceptance Criteria
|
||
|
||
- [ ] `commands/ce/` directory created with 5 new command files
|
||
- [ ] Each `ce:*` command has the full implementation from its `workflows:*` counterpart
|
||
- [ ] Each `ce:*` command frontmatter `name:` field set to `ce:plan`, `ce:work`, etc.
|
||
- [ ] Each `workflows:*` command replaced with a thin deprecation wrapper
|
||
- [ ] Deprecation wrapper shows a clear ⚠️ warning with the new command name
|
||
- [ ] Deprecation wrapper invokes the new `ce:*` command with `$ARGUMENTS`
|
||
- [ ] `lfg.md` updated to use `ce:plan`, `ce:work`, `ce:review`
|
||
- [ ] `slfg.md` updated to use `ce:plan`, `ce:work`, `ce:review`
|
||
- [ ] All agent `.md` files updated (code-simplicity-reviewer, git-history-analyzer, learnings-researcher)
|
||
- [ ] All skill `SKILL.md` files updated (document-review, git-worktree, setup, brainstorming, file-todos)
|
||
- [ ] `commands/deepen-plan.md` and `commands/test-xcode.md` updated
|
||
- [ ] `CHANGELOG.md` updated with deprecation notice
|
||
- [ ] `plugins/compound-engineering/README.md` command table updated
|
||
- [ ] `plugins/compound-engineering/CLAUDE.md` command listing updated
|
||
- [ ] Root `README.md` command table updated
|
||
- [ ] Validate: `/ce:plan "test feature"` works end-to-end
|
||
- [ ] Validate: `/workflows:plan "test feature"` shows deprecation warning and continues
|
||
- [ ] Re-run `bunx install compound-engineering --to [target]` and confirm both `ce/` and `workflows/` output dirs are written correctly
|
||
|
||
## Implementation Steps
|
||
|
||
### Step 1: Create `commands/ce/` directory with 5 new files
|
||
|
||
For each command, copy the source file and update only the `name:` frontmatter field:
|
||
|
||
- `commands/ce/plan.md` — copy `commands/workflows/plan.md`, set `name: ce:plan`
|
||
- `commands/ce/work.md` — copy `commands/workflows/work.md`, set `name: ce:work`
|
||
- `commands/ce/review.md` — copy `commands/workflows/review.md`, set `name: ce:review`
|
||
- `commands/ce/brainstorm.md` — copy `commands/workflows/brainstorm.md`, set `name: ce:brainstorm`
|
||
- `commands/ce/compound.md` — copy `commands/workflows/compound.md`, set `name: ce:compound`
|
||
|
||
### Step 2: Replace `commands/workflows/*.md` with deprecation wrappers
|
||
|
||
Use `disable-model-invocation: true` so the CLI runtime directly invokes `/ce:<command>`. The deprecation note is printed as a step description.
|
||
|
||
Template for each wrapper:
|
||
|
||
```markdown
|
||
---
|
||
name: workflows:<command>
|
||
description: "[DEPRECATED] Use /ce:<command> instead — renamed for clarity."
|
||
argument-hint: "[...]"
|
||
disable-model-invocation: true
|
||
---
|
||
|
||
NOTE: /workflows:<command> is deprecated. Please use /ce:<command> instead. This alias will be removed in a future version.
|
||
|
||
/ce:<command> $ARGUMENTS
|
||
```
|
||
|
||
### Step 3: Update all internal references
|
||
|
||
**Orchestration commands:**
|
||
- `commands/lfg.md` — replace `/workflows:plan`, `/workflows:work`, `/workflows:review`
|
||
- `commands/slfg.md` — same
|
||
|
||
**Command bodies:**
|
||
- `commands/deepen-plan.md` — replace `/workflows:work`, `/workflows:compound`
|
||
- `commands/test-xcode.md` — replace `/workflows:review`
|
||
- The deprecated `workflows/brainstorm.md`, `workflows/compound.md`, `workflows/plan.md` wrappers — references in their body text pointing to other `workflows:*` commands should also be updated to `ce:*` (since users reading them should see the new names)
|
||
|
||
**Agents:**
|
||
- `agents/review/code-simplicity-reviewer.md`
|
||
- `agents/research/git-history-analyzer.md`
|
||
- `agents/research/learnings-researcher.md`
|
||
|
||
**Skills:**
|
||
- `skills/document-review/SKILL.md`
|
||
- `skills/git-worktree/SKILL.md`
|
||
- `skills/setup/SKILL.md`
|
||
- `skills/brainstorming/SKILL.md`
|
||
- `skills/file-todos/SKILL.md`
|
||
|
||
### Step 4: Update documentation
|
||
|
||
**`plugins/compound-engineering/CHANGELOG.md`** — Add under new version section:
|
||
```
|
||
### Changed
|
||
- `workflows:plan`, `workflows:work`, `workflows:review`, `workflows:brainstorm`, `workflows:compound` renamed to `ce:plan`, `ce:work`, `ce:review`, `ce:brainstorm`, `ce:compound` for clarity
|
||
|
||
### Deprecated
|
||
- `workflows:*` commands — use `ce:*` equivalents instead. Aliases remain functional and will be removed in a future version.
|
||
```
|
||
|
||
**`plugins/compound-engineering/README.md`** — Update the commands table to list `ce:*` as primary, show `workflows:*` as deprecated aliases.
|
||
|
||
**`plugins/compound-engineering/CLAUDE.md`** — Update command listing and the "Why `workflows:`?" section to reflect new `ce:` namespace.
|
||
|
||
**Root `README.md`** — Update the commands table (lines 133–136).
|
||
|
||
### Step 5: Verify converter output
|
||
|
||
After updating, re-run the bunx install script to confirm both targets are written:
|
||
|
||
```bash
|
||
bunx @every-env/compound-plugin install compound-engineering --to gemini --output /tmp/test-output
|
||
ls /tmp/test-output/.gemini/commands/
|
||
# Should show both: ce/ and workflows/
|
||
```
|
||
|
||
The `workflows/` output will contain the deprecation wrapper content. The `ce/` output will have the full implementation.
|
||
|
||
**Future cleanup note:** When `workflows:*` wrappers are eventually removed, users must manually delete the stale `workflows/` directories from their converted targets (`.gemini/commands/workflows/`, `.codex/commands/workflows/`, etc.). Consider adding a migration note to the CHANGELOG at that time.
|
||
|
||
### Step 6: Run `/release-docs` to update the docs site
|
||
|
||
## Dependencies & Risks
|
||
|
||
- **Risk:** Users with saved references to `workflows:*` commands in their CLAUDE.md files or scripts. **Mitigation:** The deprecation wrappers remain functional indefinitely.
|
||
- **Risk:** Context token budget slightly increases (5 new command descriptions). **Mitigation:** Keep all descriptions short. Deprecated wrappers get minimal descriptions.
|
||
- **Risk:** `lfg`/`slfg` orchestration breaks if update is partial. **Mitigation:** Update both in the same commit.
|
||
|
||
## Sources & References
|
||
|
||
- Existing commands: `plugins/compound-engineering/commands/workflows/*.md`
|
||
- Orchestration commands: `plugins/compound-engineering/commands/lfg.md`, `plugins/compound-engineering/commands/slfg.md`
|
||
- Plugin metadata: `plugins/compound-engineering/.claude-plugin/plugin.json`
|
||
- Changelog: `plugins/compound-engineering/CHANGELOG.md`
|
||
- README: `plugins/compound-engineering/README.md`
|