feat(plugin): add compatibility and deprecation path for legacy bare commands (#1289)

packages/claude-code-plugin/README.md

@@ -2,7 +2,7 @@
 
 # CodingBuddy Claude Code Plugin
 
-> Version 5.1.3
+> Version 5.2.0
 
 Multi-AI Rules for consistent coding practices - PLAN/ACT/EVAL workflow, specialist agents, and reusable skills for systematic development.
 
@@ -25,11 +25,21 @@ claude plugin add codingbuddy
 - **AUTO**: Autonomous PLAN → ACT → EVAL cycle
 
 ### Commands
-- `/plan` - Enter PLAN mode
-- `/act` - Enter ACT mode
-- `/eval` - Enter EVAL mode
-- `/auto` - Enter AUTO mode
-- `/checklist` - Generate contextual checklists
+- `/codingbuddy:plan` - Enter PLAN mode
+- `/codingbuddy:act` - Enter ACT mode
+- `/codingbuddy:eval` - Enter EVAL mode
+- `/codingbuddy:auto` - Enter AUTO mode
+- `/codingbuddy:checklist` - Generate contextual checklists
+- `/codingbuddy:buddy` - Show project status and next actions
+
+> **Tip:** Type `PLAN`, `ACT`, `EVAL`, or `AUTO` as keywords for the fastest workflow entry.
+
+### Command Migration
+
+Legacy bare commands (`/plan`, `/act`, `/eval`, `/auto`, `/buddy`, `/checklist`) are deprecated.
+They continue to work during the transition period, but all new commands use the `codingbuddy:*` namespace.
+
+See [Migration Guide](./docs/migration-guide.md) for details.
 
 ### Specialist Agents
 35 AI agents for different domains:
@@ -46,24 +56,9 @@ Reusable workflows for consistent development:
 - Refactoring
 - And more...
 
-## Feature Availability
-
-| Feature | Standalone | With MCP |
-|---------|-----------|----------|
-| Mode detection (PLAN/ACT/EVAL/AUTO) | ✅ | ✅ |
-| Basic agent recommendation | ✅ | ✅ |
-| TDD workflow guidance | ✅ | ✅ |
-| HUD / StatusLine | ✅ | ✅ |
-| Session stats & history | ✅ | ✅ |
-| Specialist agent dispatch | ❌ | ✅ |
-| Context tracking (cross-session) | ❌ | ✅ |
-| Parallel agent execution | ❌ | ✅ |
-| Contextual checklists | ❌ | ✅ |
-| Rule search & impact tracking | ❌ | ✅ |
-
-## MCP Integration (Recommended)
+## MCP Integration (Required)
 
-This plugin works standalone but benefits from the CodingBuddy MCP server for full functionality:
+This plugin requires the CodingBuddy MCP server for full functionality:
 
 ```bash
 npm install -g codingbuddy

packages/claude-code-plugin/docs/migration-guide.md

@@ -0,0 +1,65 @@
+# Command Migration Guide
+
+## Overview
+
+CodingBuddy is migrating from bare slash commands (`/plan`, `/act`, etc.) to namespaced commands (`/codingbuddy:plan`, `/codingbuddy:act`, etc.) to prevent collisions with Claude Code built-in commands.
+
+**Bare commands continue to work during the transition period.** No immediate action is required.
+
+## Recommended: Use Keywords Instead
+
+The lowest-friction workflow uses **keywords** — plain text typed at the start of your message. Keywords are not slash commands and require no namespace:
+
+| Keyword  | Effect                              |
+| -------- | ----------------------------------- |
+| `PLAN`   | Enter planning mode                 |
+| `ACT`    | Enter implementation mode           |
+| `EVAL`   | Enter evaluation mode               |
+| `AUTO`   | Enter autonomous PLAN/ACT/EVAL cycle |
+
+**Examples:**
+
+```
+PLAN design auth feature
+ACT implement the login form
+EVAL review the auth module
+AUTO build user dashboard
+```
+
+Keywords also support localized variants: Korean (`계획`/`실행`/`평가`/`자동`), Japanese (`計画`/`実行`/`評価`/`自動`), Chinese (`计划`/`执行`/`评估`/`自动`), Spanish (`PLANIFICAR`/`ACTUAR`/`EVALUAR`/`AUTOMÁTICO`).
+
+## Command Mapping
+
+If you prefer slash commands, use the namespaced form:
+
+| Legacy (bare)  | Namespaced (new)           | Status           |
+| -------------- | -------------------------- | ---------------- |
+| `/plan`        | `/codingbuddy:plan`        | migration target |
+| `/act`         | `/codingbuddy:act`         | migration target |
+| `/eval`        | `/codingbuddy:eval`        | migration target |
+| `/auto`        | `/codingbuddy:auto`        | migration target |
+| `/buddy`       | `/codingbuddy:buddy`       | migration target |
+| `/checklist`   | `/codingbuddy:checklist`   | migration target |
+
+## Timeline
+
+1. **Now**: Both bare and namespaced commands work. Keywords are the recommended entry point.
+2. **Transition**: Bare commands are deprecated but functional. New commands use `codingbuddy:*` only.
+3. **Future**: Once Claude Code fully supports `plugin:command` namespace resolution, bare aliases will be removed.
+
+## What Changed and Why
+
+Claude Code reserves certain command names as built-ins (e.g., `/help`, `/clear`, `/review`). To avoid collisions and clearly identify CodingBuddy functionality, all plugin commands now use the `codingbuddy:` namespace prefix.
+
+See [namespace-policy.md](./namespace-policy.md) for the full policy.
+
+## FAQ
+
+**Q: Do I need to change anything right now?**
+A: No. Bare commands still work. Switch to keywords or namespaced commands at your convenience.
+
+**Q: What is the recommended approach?**
+A: Use keywords (`PLAN`, `ACT`, `EVAL`, `AUTO`). They are the fastest and most portable workflow entry point.
+
+**Q: Will new commands have bare aliases?**
+A: No. All new commands use the `codingbuddy:*` namespace exclusively.

packages/claude-code-plugin/scripts/build.ts

@@ -72,11 +72,21 @@ claude plugin add codingbuddy
 - **AUTO**: Autonomous PLAN → ACT → EVAL cycle
 
 ### Commands
-- \`/plan\` - Enter PLAN mode
-- \`/act\` - Enter ACT mode
-- \`/eval\` - Enter EVAL mode
-- \`/auto\` - Enter AUTO mode
-- \`/checklist\` - Generate contextual checklists
+- \`/codingbuddy:plan\` - Enter PLAN mode
+- \`/codingbuddy:act\` - Enter ACT mode
+- \`/codingbuddy:eval\` - Enter EVAL mode
+- \`/codingbuddy:auto\` - Enter AUTO mode
+- \`/codingbuddy:checklist\` - Generate contextual checklists
+- \`/codingbuddy:buddy\` - Show project status and next actions
+
+> **Tip:** Type \`PLAN\`, \`ACT\`, \`EVAL\`, or \`AUTO\` as keywords for the fastest workflow entry.
+
+### Command Migration
+
+Legacy bare commands (\`/plan\`, \`/act\`, \`/eval\`, \`/auto\`, \`/buddy\`, \`/checklist\`) are deprecated.
+They continue to work during the transition period, but all new commands use the \`codingbuddy:*\` namespace.
+
+See [Migration Guide](./docs/migration-guide.md) for details.
 
 ### Specialist Agents
 35 AI agents for different domains: