docs: add beta skills framework pattern for parallel -beta suffix skills

docs/solutions/skill-design/beta-skills-framework.md

@@ -0,0 +1,85 @@
+---
+title: "Beta skills framework: parallel skills with -beta suffix for safe rollouts"
+category: skill-design
+date: 2026-03-17
+module: plugins/compound-engineering/skills
+component: SKILL.md
+tags:
+  - skill-design
+  - beta-testing
+  - skill-versioning
+  - rollout-safety
+severity: medium
+description: "Pattern for trialing new skill versions alongside stable ones using a -beta suffix. Covers naming, plan file naming, internal references, and promotion path."
+related:
+  - docs/brainstorms/2026-03-17-beta-skills-framework-brainstorm.md
+  - docs/solutions/skill-design/compound-refresh-skill-improvements.md
+---
+
+## Problem
+
+Core workflow skills like `ce:plan` and `deepen-plan` are deeply chained (`ce:brainstorm` → `ce:plan` → `deepen-plan` → `ce:work`) and orchestrated by `lfg` and `slfg`. Rewriting these skills risks breaking the entire workflow for all users simultaneously. There was no mechanism to let users trial new skill versions alongside stable ones.
+
+Alternatives considered and rejected:
+- **Beta gate in SKILL.md** with config-driven routing (`beta: true` in `compound-engineering.local.md`): relies on prompt-level conditional routing which risks instruction blending, requires setup integration, and adds complexity to the skill files themselves.
+- **Pure router SKILL.md** with both versions in `references/`: adds file-read penalty and refactors stable skills unnecessarily.
+- **Separate beta plugin**: heavy infrastructure for a temporary need.
+
+## Solution
+
+### Parallel skills with `-beta` suffix
+
+Create separate skill directories alongside the stable ones. Each beta skill is a fully independent copy with its own frontmatter, instructions, and internal references.
+
+```
+skills/
+├── ce-plan/SKILL.md           # Stable (unchanged)
+├── ce-plan-beta/SKILL.md      # New version
+├── deepen-plan/SKILL.md       # Stable (unchanged)
+└── deepen-plan-beta/SKILL.md  # New version
+```
+
+### Naming conventions
+
+- **Directory**: `<skill-name>-beta/`
+- **Frontmatter name**: `<skill:name>-beta` (e.g., `ce:plan-beta`)
+- **Description prefix**: `[BETA]` to make it visually obvious
+- **Plan files**: Use `-beta-plan.md` suffix (e.g., `2026-03-17-001-feat-auth-flow-beta-plan.md`) to avoid clobbering stable plan files
+
+### Internal references
+
+Beta skills must reference each other by their beta names:
+- `ce:plan-beta` references `/deepen-plan-beta` (not `/deepen-plan`)
+- `deepen-plan-beta` references `ce:plan-beta` (not `ce:plan`)
+
+### What doesn't change
+
+- Stable `ce:plan` and `deepen-plan` are completely untouched
+- `lfg`/`slfg` orchestration continues to use stable skills — no modification needed
+- `ce:brainstorm` still hands off to stable `ce:plan` — no modification needed
+- `ce:work` consumes plan files from either version (reads the file, doesn't care which skill wrote it)
+
+### Tradeoffs
+
+**Simplicity over seamless integration.** Beta skills exist as standalone, manually-invoked skills. They won't be auto-triggered by `ce:brainstorm` handoffs or `lfg`/`slfg` orchestration without further surgery to those skills, which isn't worth the complexity for a trial period.
+
+**Intended usage pattern:** A user can run `/ce:plan` for the stable output, then run `/ce:plan-beta` on the same input to compare the two plan documents side by side. The `-beta-plan.md` suffix ensures both outputs coexist in `docs/plans/` without collision.
+
+## Promotion path
+
+When the beta version is validated:
+
+1. Replace stable `SKILL.md` content with beta skill content
+2. Restore stable frontmatter: remove `[BETA]` prefix, restore stable `name:`
+3. Update all internal references back to stable names
+4. Restore stable plan file naming (remove `-beta` from the convention)
+5. Delete the beta skill directory
+6. Update README.md: remove from Beta Skills section, verify counts
+7. Verify `lfg`/`slfg` work with the promoted skill
+8. Verify `ce:work` consumes plans from the promoted skill
+
+## Prevention
+
+- When adding a beta skill, always use the `-beta` suffix consistently in directory name, frontmatter name, description, plan file naming, and all internal skill-to-skill references
+- Always test that stable skills are completely unaffected by the beta skill's existence
+- Keep beta and stable plan file suffixes distinct so outputs can coexist for comparison