@every-env/compound-plugin 0.9.0 → 2.34.2

package/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:<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`

package/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`