diff --git a/docs/plans/2026-03-01-feat-ce-command-aliases-backwards-compatible-deprecation-plan.md b/docs/plans/2026-03-01-feat-ce-command-aliases-backwards-compatible-deprecation-plan.md new file mode 100644 index 0000000..844cfb9 --- /dev/null +++ b/docs/plans/2026-03-01-feat-ce-command-aliases-backwards-compatible-deprecation-plan.md @@ -0,0 +1,261 @@ +--- +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:`. The deprecation note is printed as a step description. + +Template for each wrapper: + +```markdown +--- +name: workflows: +description: "[DEPRECATED] Use /ce: instead — renamed for clarity." +argument-hint: "[...]" +disable-model-invocation: true +--- + +NOTE: /workflows: is deprecated. Please use /ce: instead. This alias will be removed in a future version. + +/ce: $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` diff --git a/docs/plans/2026-03-01-fix-setup-skill-non-claude-llm-fallback-plan.md b/docs/plans/2026-03-01-fix-setup-skill-non-claude-llm-fallback-plan.md new file mode 100644 index 0000000..fd5cdf7 --- /dev/null +++ b/docs/plans/2026-03-01-fix-setup-skill-non-claude-llm-fallback-plan.md @@ -0,0 +1,140 @@ +--- +title: "fix: Setup skill fails silently on non-Claude LLMs due to AskUserQuestion dependency" +type: fix +status: active +date: 2026-03-01 +--- + +## Enhancement Summary + +**Deepened on:** 2026-03-01 +**Research agents used:** best-practices-researcher, architecture-strategist, code-simplicity-reviewer, scope-explorer + +### Key Improvements +1. Simplified preamble from 16 lines to 4 lines — drop platform name list and example blockquote (YAGNI) +2. Expanded scope: `create-new-skill.md` also has `AskUserQuestion` and needs the same fix +3. Clarified that `codex-agents.ts` change helps command/agent contexts only — does NOT reach skill execution (skills aren't converter-transformed) +4. Added CLAUDE.md skill compliance policy as a third deliverable to prevent recurrence +5. Separated two distinct failure modes: tool-not-found error vs silent auto-configuration + +### New Considerations Discovered +- Only Pi converter transforms `AskUserQuestion` (incompletely); all others pass skill content through verbatim — the codex-agents.ts fix is independent of skill execution +- `add-workflow.md` and `audit-skill.md` already explicitly prohibit `AskUserQuestion` — this undocumented policy should be formalized +- Prose fallback is probabilistic (LLM compliance); converter-level transformation is the correct long-term architectural fix +- The brainstorming skill avoids `AskUserQuestion` entirely and works cross-platform — that's the gold standard pattern + +--- + +# fix: Setup Skill Cross-Platform Fallback for AskUserQuestion + +## Overview + +The `setup` skill uses `AskUserQuestion` at 5 decision points. On non-Claude platforms (Codex, Gemini, OpenCode, Copilot, Kiro, etc.), this tool doesn't exist — the LLM reads the skill body but cannot call the tool, causing silent failure or unconsented auto-configuration. Fix by adding a minimal fallback instruction to the skill body, applying the same to `create-new-skill.md`, and adding a policy to the CLAUDE.md skill checklist to prevent recurrence. + +## Problem Statement + +**Two distinct failure modes:** + +1. **Tool-not-found error** — LLM tries to call `AskUserQuestion` as a function; platform returns an error. Setup halts. +2. **Silent skip** — LLM reads `AskUserQuestion` as prose, ignores the decision gate, auto-configures. User never consulted. This is worse — produces a `compound-engineering.local.md` the user never approved. + +`plugins/compound-engineering/skills/setup/SKILL.md` has 5 `AskUserQuestion` blocks: + +| Line | Decision Point | +|------|----------------| +| 13 | Check existing config: Reconfigure / View / Cancel | +| 44 | Stack detection: Auto-configure / Customize | +| 67 | Stack override (multi-option) | +| 85 | Focus areas (multiSelect) | +| 104 | Review depth: Thorough / Fast / Comprehensive | + +`plugins/compound-engineering/skills/create-agent-skills/workflows/create-new-skill.md` lines 22 and 45 also use `AskUserQuestion`. + +Only the Pi converter transforms the reference (incompletely). All other converters (Codex, Gemini, Copilot, Kiro, Droid, Windsurf) pass skill content through verbatim — **skills are not converter-transformed**. + +## Proposed Solution + +Three deliverables, each addressing a different layer: + +### 1. Add 4-line "Interaction Method" preamble to `setup/SKILL.md` + +Immediately after the `# Compound Engineering Setup` heading, insert: + +```markdown +## Interaction Method + +If `AskUserQuestion` is available, use it for all prompts below. + +If not, present each question as a numbered list and wait for a reply before proceeding to the next step. For multiSelect questions, accept comma-separated numbers (e.g. `1, 3`). Never skip or auto-configure. +``` + +**Why 4 lines, not 16:** LLMs know what a numbered list is — no example blockquote needed. The branching condition is tool availability, not platform identity — no platform name list needed (YAGNI: new platforms will be added and lists go stale). State the "never skip" rule once here; don't repeat it in `codex-agents.ts`. + +**Why this works:** The skill body IS read by the LLM on all platforms when `/setup` is invoked. The agent follows prose instructions regardless of tool availability. This is the same pattern `brainstorming/SKILL.md` uses — it avoids `AskUserQuestion` entirely and uses inline numbered lists — the gold standard cross-platform approach. + +### 2. Apply the same preamble to `create-new-skill.md` + +`plugins/compound-engineering/skills/create-agent-skills/workflows/create-new-skill.md` uses `AskUserQuestion` at lines 22 and 45. Apply an identical preamble at the top of that file. + +### 3. Strengthen `codex-agents.ts` AskUserQuestion mapping + +This change does NOT fix skill execution (skills bypass the converter pipeline). It improves the AGENTS.md guidance for Codex command/agent contexts. + +Replace (`src/utils/codex-agents.ts` line 21): +``` +- AskUserQuestion/Question: ask the user in chat +``` + +With: +``` +- AskUserQuestion/Question: present choices as a numbered list in chat and wait for a reply number. For multi-select (multiSelect: true), accept comma-separated numbers. Never skip or auto-configure — always wait for the user's response before proceeding. +``` + +### 4. Add lint rule to CLAUDE.md skill compliance checklist + +Add to the "Skill Compliance Checklist" in `plugins/compound-engineering/CLAUDE.md`: + +``` +### AskUserQuestion Usage + +- [ ] If the skill uses `AskUserQuestion`, it must include an "Interaction Method" preamble explaining the numbered-list fallback for non-Claude environments +- [ ] Prefer avoiding `AskUserQuestion` entirely (see brainstorming/SKILL.md pattern) for skills intended to run cross-platform +``` + +## Technical Considerations + +- `setup/SKILL.md` has `disable-model-invocation: true` — this controls session-startup context loading only, not skill-body execution at invocation time +- The prose fallback is probabilistic (LLM compliance), not a build-time guarantee. The correct long-term architectural fix is converter-level transformation of skill content (a `transformSkillContent()` pass in each converter), but that is out of scope here +- Commands with `AskUserQuestion` (`ce/brainstorm.md`, `ce/plan.md`, `test-browser.md`, etc.) have the same gap but are out of scope — explicitly noted as a future task + +## Acceptance Criteria + +- [ ] `setup/SKILL.md` has a 4-line "Interaction Method" preamble after the opening heading +- [ ] `create-new-skill.md` has the same preamble +- [ ] The skills still use `AskUserQuestion` as primary — no change to Claude Code behavior +- [ ] `codex-agents.ts` AskUserQuestion line updated with structured guidance +- [ ] `plugins/compound-engineering/CLAUDE.md` skill checklist includes AskUserQuestion policy +- [ ] No regression: on Claude Code, setup works exactly as before + +## Files + +- `plugins/compound-engineering/skills/setup/SKILL.md` — Add 4-line preamble after line 8 +- `plugins/compound-engineering/skills/create-agent-skills/workflows/create-new-skill.md` — Add same preamble at top +- `src/utils/codex-agents.ts` — Strengthen AskUserQuestion mapping (line 21) +- `plugins/compound-engineering/CLAUDE.md` — Add AskUserQuestion policy to skill compliance checklist + +## Future Work (Out of Scope) + +- Converter-level `transformSkillContent()` for all targets — build-time guarantee instead of prose fallback +- Commands with `AskUserQuestion` (`ce/brainstorm.md`, `ce/plan.md`, `test-browser.md`) — same failure mode, separate fix + +## Sources & References + +- Issue: [#204](https://github.com/EveryInc/compound-engineering-plugin/issues/204) +- `plugins/compound-engineering/skills/setup/SKILL.md:13,44,67,85,104` +- `plugins/compound-engineering/skills/create-agent-skills/workflows/create-new-skill.md:22,45` +- `src/utils/codex-agents.ts:21` +- `src/converters/claude-to-pi.ts:106` — Pi converter (reference pattern) +- `plugins/compound-engineering/skills/brainstorming/SKILL.md` — gold standard cross-platform skill (no AskUserQuestion) +- `plugins/compound-engineering/skills/create-agent-skills/workflows/add-workflow.md:12,37` — existing "DO NOT use AskUserQuestion" policy +- `docs/solutions/adding-converter-target-providers.md`