fix: beta skill naming, plan file suffixes, and promotion checklist
- Beta plans use -beta-plan.md suffix to avoid clobbering stable plans - Fix internal references in beta skills to use beta names consistently - Add beta skills section to AGENTS.md with promotion checklist
This commit is contained in:
Trevin Chow
@@ -116,6 +116,32 @@ grep -E '`(references|assets|scripts)/[^`]+`' skills/*/SKILL.md
|
||||
grep -E '^description:' skills/*/SKILL.md
|
||||
```
|
||||
|
||||
## Beta Skills
|
||||
|
||||
Beta skills are experimental versions of core workflow skills, published as separate skills with a `-beta` suffix (e.g., `ce-plan-beta`, `deepen-plan-beta`). They live alongside the stable versions and are invoked directly.
|
||||
|
||||
See `docs/solutions/skill-design/beta-skills-framework.md` for the full pattern.
|
||||
|
||||
### Beta Skill Rules
|
||||
|
||||
- Beta skills use `-beta` suffix in directory name, skill name, and description prefix (`[BETA]`)
|
||||
- Beta skills must reference other beta skills by their beta names (e.g., `/deepen-plan-beta`, not `/deepen-plan`)
|
||||
- Beta plan output files use `-beta-plan.md` suffix to avoid clobbering stable plan files
|
||||
- Beta skills are not wired into `lfg`/`slfg` orchestration — invoke them directly
|
||||
|
||||
### Promoting Beta to Stable
|
||||
|
||||
When replacing a stable skill with its beta version:
|
||||
|
||||
- [ ] Replace stable `SKILL.md` content with beta skill content
|
||||
- [ ] Restore stable frontmatter: remove `[BETA]` prefix from description, restore stable `name:` (e.g., `ce:plan` not `ce:plan-beta`)
|
||||
- [ ] Update all internal references back to stable names (`/deepen-plan` not `/deepen-plan-beta`)
|
||||
- [ ] Restore stable plan file naming (remove `-beta` from `-beta-plan.md` convention)
|
||||
- [ ] Delete the beta skill directory
|
||||
- [ ] Update README.md: remove from Beta Skills section, verify counts
|
||||
- [ ] Verify `lfg`/`slfg` still work with the updated stable skill
|
||||
- [ ] Verify `ce:work` consumes plans from the promoted skill correctly
|
||||
|
||||
## Documentation
|
||||
|
||||
See `docs/solutions/plugin-versioning-requirements.md` for detailed versioning workflow.
|
||||
|
||||
@@ -224,11 +224,12 @@ Ask the user only when the answer materially affects architecture, scope, sequen
|
||||
|
||||
- Draft a clear, searchable title using conventional format such as `feat: Add user authentication` or `fix: Prevent checkout double-submit`
|
||||
- Determine the plan type: `feat`, `fix`, or `refactor`
|
||||
- Build the filename following the repository convention: `docs/plans/YYYY-MM-DD-NNN-<type>-<descriptive-name>-plan.md`
|
||||
- Build the filename following the repository convention: `docs/plans/YYYY-MM-DD-NNN-<type>-<descriptive-name>-beta-plan.md`
|
||||
- Create `docs/plans/` if it does not exist
|
||||
- Check existing files for today's date to determine the next sequence number (zero-padded to 3 digits, starting at 001)
|
||||
- Keep the descriptive name concise (3-5 words) and kebab-cased
|
||||
- Examples: `2026-01-15-001-feat-user-authentication-flow-plan.md`, `2026-02-03-002-fix-checkout-race-condition-plan.md`
|
||||
- Append `-beta` before `-plan` to distinguish from stable-generated plans
|
||||
- Examples: `2026-01-15-001-feat-user-authentication-flow-beta-plan.md`, `2026-02-03-002-fix-checkout-race-condition-beta-plan.md`
|
||||
- Avoid: missing sequence numbers, vague names like "new-feature", invalid characters (colons, spaces)
|
||||
|
||||
#### 3.2 Stakeholder and Impact Awareness
|
||||
@@ -322,7 +323,7 @@ type: [feat|fix|refactor]
|
||||
status: active
|
||||
date: YYYY-MM-DD
|
||||
origin: docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md # include when planning from a requirements doc
|
||||
deepened: YYYY-MM-DD # optional, set later by deepen-plan when the plan is substantively strengthened
|
||||
deepened: YYYY-MM-DD # optional, set later by deepen-plan-beta when the plan is substantively strengthened
|
||||
---
|
||||
|
||||
# [Plan Title]
|
||||
@@ -494,7 +495,7 @@ If the plan originated from a requirements document, re-read that document and v
|
||||
Use the Write tool to save the complete plan to:
|
||||
|
||||
```text
|
||||
docs/plans/YYYY-MM-DD-NNN-<type>-<descriptive-name>-plan.md
|
||||
docs/plans/YYYY-MM-DD-NNN-<type>-<descriptive-name>-beta-plan.md
|
||||
```
|
||||
|
||||
Confirm:
|
||||
|
||||
@@ -16,9 +16,9 @@ Use this skill when the plan already exists and the question is not "Is this doc
|
||||
|
||||
This skill does **not** turn plans into implementation scripts. It identifies weak sections, runs targeted research only for those sections, and strengthens the plan in place.
|
||||
|
||||
`document-review` and `deepen-plan` are different:
|
||||
`document-review` and `deepen-plan-beta` are different:
|
||||
- Use the `document-review` skill when the document needs clarity, simplification, completeness, or scope control
|
||||
- Use `deepen-plan` when the document is structurally sound but still needs stronger rationale, sequencing, risk treatment, or system-wide thinking
|
||||
- Use `deepen-plan-beta` when the document is structurally sound but still needs stronger rationale, sequencing, risk treatment, or system-wide thinking
|
||||
|
||||
## Interaction Method
|
||||
|
||||
|
||||
Reference in New Issue
Block a user