codingbuddy-rules 4.2.0 → 4.4.0

package/.ai-rules/adapters/cursor.md

@@ -21,12 +21,20 @@ End users access rules **only through MCP tools**. No local rule files needed.
   "mcpServers": {
     "codingbuddy": {
       "command": "npx",
-      "args": ["-y", "codingbuddy"]
+      "args": ["-y", "codingbuddy"],
+      "env": {
+        "CODINGBUDDY_PROJECT_ROOT": "/absolute/path/to/your/project"
+      }
     }
   }
 }
 ```
 
+> **Important:** Cursor may not support the `roots/list` MCP capability.
+> Without `CODINGBUDDY_PROJECT_ROOT`, the server cannot locate your project's
+> `codingbuddy.config.json`, causing `language` and other settings to use defaults.
+> Always set this environment variable to your project's absolute path.
+
 Optional: Create `.cursor/rules/codingbuddy.mdc` for basic integration:
 
 ```yaml
@@ -122,26 +130,196 @@ Available codingbuddy MCP tools in Cursor:
 
 | Tool | Purpose |
 |------|---------|
-| `parse_mode` | Parse mode keywords + load Agent/rules |
-| `get_agent_details` | Get specific Agent details |
-| `get_project_config` | Get project configuration |
-| `recommend_skills` | Recommend skills based on prompt |
-| `prepare_parallel_agents` | Prepare parallel Agent execution |
+| `parse_mode` | Parse mode keywords (PLAN/ACT/EVAL/AUTO) + load Agent/rules |
+| `search_rules` | Search rules and guidelines by query |
+| `get_agent_details` | Get specific Agent profile and expertise |
+| `get_project_config` | Get project configuration (language, tech stack) |
+| `get_code_conventions` | Get project code conventions and style guide |
+| `suggest_config_updates` | Analyze project and suggest config updates |
+| `recommend_skills` | Recommend skills based on prompt → then call `get_skill` |
+| `get_skill` | Load full skill content by name (e.g., `get_skill("systematic-debugging")`) |
+| `list_skills` | List all available skills with optional filtering |
+| `get_agent_system_prompt` | Get complete system prompt for a specialist agent |
+| `prepare_parallel_agents` | Prepare specialist agents for sequential execution |
+| `dispatch_agents` | Get Task tool-ready dispatch params (Claude Code optimized) |
+| `generate_checklist` | Generate contextual checklists (security, a11y, performance) |
+| `analyze_task` | Analyze task for risk assessment and specialist recommendations |
+| `read_context` | Read context document (`docs/codingbuddy/context.md`) |
+| `update_context` | Update context document with decisions, notes, progress |
+| `cleanup_context` | Manually trigger context document cleanup |
+| `set_project_root` | ~~Set project root directory~~ **(deprecated)** — use `CODINGBUDDY_PROJECT_ROOT` env var instead |
+
+## Specialist Agents Execution
+
+Cursor does not have a `Task` tool for spawning background subagents. When `parse_mode` returns `parallelAgentsRecommendation`, execute specialists **sequentially**.
+
+### Auto-Detection
+
+The MCP server automatically detects Cursor as the client and returns a sequential execution hint in `parallelAgentsRecommendation.hint`. No manual configuration is needed.
+
+### Sequential Workflow
+
+```
+parse_mode returns parallelAgentsRecommendation
+  ↓
+Call prepare_parallel_agents with recommended specialists
+  ↓
+For each specialist (sequentially):
+  - Announce: "🔍 Analyzing from [icon] [specialist-name] perspective..."
+  - Apply the specialist's system prompt as analysis context
+  - Analyze the target code/design from that specialist's viewpoint
+  - Record findings
+  ↓
+Consolidate all specialist findings into unified summary
+```
+
+### Example (EVAL mode)
+
+```
+parse_mode({ prompt: "EVAL review auth implementation" })
+→ parallelAgentsRecommendation:
+    specialists: ["security-specialist", "accessibility-specialist", "performance-specialist"]
+
+prepare_parallel_agents({
+  mode: "EVAL",
+  specialists: ["security-specialist", "accessibility-specialist", "performance-specialist"]
+})
+→ agents[]: each has systemPrompt
+
+Sequential analysis:
+  1. 🔒 Security: Apply security-specialist prompt, analyze, record findings
+  2. ♿ Accessibility: Apply accessibility-specialist prompt, analyze, record findings
+  3. ⚡ Performance: Apply performance-specialist prompt, analyze, record findings
+
+Present: Consolidated findings from all 3 specialists
+```
+
+### Specialist Icons
+
+| Icon | Specialist |
+|------|------------|
+| 🔒 | security-specialist |
+| ♿ | accessibility-specialist |
+| ⚡ | performance-specialist |
+| 📏 | code-quality-specialist |
+| 🧪 | test-strategy-specialist |
+| 🏛️ | architecture-specialist |
+| 📚 | documentation-specialist |
+| 🔍 | seo-specialist |
+| 🎨 | design-system-specialist |
+| 📨 | event-architecture-specialist |
+| 🔗 | integration-specialist |
+| 📊 | observability-specialist |
+| 🔄 | migration-specialist |
+| 🌐 | i18n-specialist |
 
 ## Skills
 
+Cursor accesses codingbuddy skills through three patterns:
+
+1. **Auto-recommend** — AI calls `recommend_skills` based on intent detection
+2. **Browse and select** — User calls `list_skills` to discover, then `get_skill` to load
+3. **Slash-command** — User types `/<command>`, AI maps to `get_skill`
+
 ### Using Skills in Cursor
 
-Load skills via file reference (monorepo only):
+**Method 1: MCP Tool Chain (End Users — Recommended)**
+
+The AI should follow this chain when a skill might apply:
+
+1. `recommend_skills({ prompt: "user's message" })` — Get skill recommendations
+2. `get_skill("skill-name")` — Load the recommended skill's full content
+3. Follow the skill instructions in the response
+
+Example flow:
+```
+User: "There is a bug in the authentication logic"
+→ AI calls recommend_skills({ prompt: "There is a bug in the authentication logic" })
+→ Response: { recommendations: [{ skillName: "systematic-debugging", ... }], nextAction: "Call get_skill..." }
+→ AI calls get_skill("systematic-debugging")
+→ AI follows the systematic-debugging skill instructions
+```
+
+**Method 2: File Reference (Monorepo Contributors Only)**
 
 ```
 @packages/rules/.ai-rules/skills/test-driven-development/SKILL.md
 ```
 
-For end users, use `recommend_skills` MCP tool instead.
+> **Note:** `parse_mode` already embeds matched skill content in `included_skills` — no separate `get_skill` call needed when using mode keywords (PLAN/ACT/EVAL/AUTO).
+
+### Skill Discovery
+
+Use `list_skills` to browse available skills before deciding which one to load:
+
+```
+list_skills()                                    # Browse all skills
+list_skills({ minPriority: 1, maxPriority: 3 })  # Filter by priority
+```
+
+**Discovery flow:**
+
+1. `list_skills()` — Browse available skills and descriptions
+2. Identify the skill relevant to the current task
+3. `get_skill("skill-name")` — Load the full skill content
+4. Follow the skill instructions
+
+> **Tip:** Use `recommend_skills` when you want AI to automatically pick the best skill. Use `list_skills` when you want to manually browse and select.
+
+### Slash-Command Mapping
+
+Cursor has no native slash-command skill invocation. When a user types `/<command>`, the AI must call `get_skill` — this is Cursor's equivalent of Claude Code's built-in Skill tool.
+
+**Rule:** When user input matches `/<command>`, call `get_skill("<skill-name>")` and follow the returned instructions. This table is a curated subset — use `list_skills()` to discover all available skills.
+
+| User Types | MCP Call |
+|---|---|
+| `/debug` or `/debugging` | `get_skill("systematic-debugging")` |
+| `/tdd` | `get_skill("test-driven-development")` |
+| `/brainstorm` | `get_skill("brainstorming")` |
+| `/plan` or `/write-plan` | `get_skill("writing-plans")` |
+| `/execute` or `/exec` | `get_skill("executing-plans")` |
+| `/design` or `/frontend` | `get_skill("frontend-design")` |
+| `/refactor` | `get_skill("refactoring")` |
+| `/security` or `/audit` | `get_skill("security-audit")` |
+| `/pr` | `get_skill("pr-all-in-one")` |
+| `/review` or `/pr-review` | `get_skill("pr-review")` |
+| `/parallel` or `/agents` | `get_skill("dispatching-parallel-agents")` |
+| `/subagent` | `get_skill("subagent-driven-development")` |
+
+For unrecognized slash commands, call `recommend_skills({ prompt: "<user's full message>" })` to find the closest match.
+
+> **Disambiguation:** `/plan` (with slash prefix) triggers `get_skill("writing-plans")`. `PLAN` (without slash, at message start) triggers `parse_mode`. Similarly, `/execute` triggers `get_skill("executing-plans")` while `ACT` triggers `parse_mode`. The slash prefix is the distinguishing signal.
+
+### Proactive Skill Activation
+
+Cursor lacks session hooks that automatically enforce skill invocation (unlike Claude Code). The AI must detect intent patterns and call `recommend_skills` proactively — without waiting for the user to explicitly request a skill.
+
+**Rule:** When the user's message suggests a skill would help, call `recommend_skills` at the start of the response — before any other action. The `recommend_skills` engine matches trigger patterns across multiple languages and is the authoritative source of truth.
+
+Common trigger examples (not exhaustive):
+
+| User Intent Signal | Likely Skill |
+|---|---|
+| Bug report, error, "not working", exception | `systematic-debugging` |
+| "Brainstorm", "build", "create", "implement" | `brainstorming` |
+| "Test first", TDD, write tests before code | `test-driven-development` |
+| "Plan", "design", implementation approach | `writing-plans` |
+| PR, commit, code review workflow | `pr-all-in-one` |
+
+```
+User: "I need to plan the implementation for user authentication"
+→ AI calls recommend_skills({ prompt: "plan implementation for user authentication" })
+→ Loads writing-plans via get_skill
+→ Follows skill instructions to create structured plan
+```
+
+> **Note:** When the user message starts with a mode keyword (`PLAN`, `ACT`, `EVAL`, `AUTO`), `parse_mode` already handles skill matching automatically via `included_skills` — no separate `recommend_skills` call is needed.
 
 ### Available Skills
 
+Highlighted skills (use `list_skills()` for the complete list):
+
 - `brainstorming/SKILL.md` - Idea → Design
 - `test-driven-development/SKILL.md` - TDD workflow
 - `systematic-debugging/SKILL.md` - Systematic debugging
@@ -270,6 +448,72 @@ module.exports = {
 - Bug fixes needing comprehensive testing
 - Code quality improvements with measurable criteria
 
+> **Cursor limitation:** AUTO mode has no enforcement mechanism in Cursor. See [Known Limitations](#known-limitations) for details.
+
+## Context Document Management
+
+codingbuddy uses a fixed-path context document (`docs/codingbuddy/context.md`) to persist decisions across mode transitions.
+
+### How It Works
+
+| Mode | Behavior |
+|------|----------|
+| PLAN / AUTO | Resets (clears) existing content and starts fresh |
+| ACT / EVAL | Appends new section to existing content |
+
+### Required Workflow
+
+1. `parse_mode` automatically reads/creates the context document
+2. Review `contextDocument` in the response for previous decisions
+3. **Before completing each mode:** call `update_context` to persist current work
+
+### Available Tools
+
+| Tool | Purpose |
+|------|---------|
+| `read_context` | Read current context document |
+| `update_context` | Persist decisions, notes, progress, findings |
+| `cleanup_context` | Summarize older sections to reduce document size |
+
+### Cursor-Specific Note
+
+Unlike Claude Code, Cursor has no hooks to enforce `update_context` calls. You must **manually remember** to call `update_context` before concluding each mode to avoid losing context across sessions.
+
+## Known Limitations
+
+Cursor environment does not support several features available in Claude Code:
+
+| Feature | Status | Workaround |
+|---------|--------|------------|
+| **Task tool** (background subagents) | ❌ Not available | Use `prepare_parallel_agents` for sequential execution |
+| **Native Skill tool** (`/skill-name`) | ❌ Not available | Use MCP tool chain: `recommend_skills` → `get_skill` |
+| **Session hooks** (PreToolUse, etc.) | ❌ Not available | Rely on `.cursor/rules/*.mdc` for always-on instructions |
+| **Autonomous loop mechanism** | ❌ Not available | AUTO mode depends on Cursor AI voluntarily looping |
+| **Context compaction hooks** | ❌ Not available | Manually call `update_context` before ending each mode |
+| **`dispatch_agents` full usage** | ⚠️ Partial | Returns Claude Code-specific `dispatchParams`; use `prepare_parallel_agents` instead |
+| **`restart_tui`** | ❌ Not applicable | Claude Code TUI-only tool |
+
+### AUTO Mode Reliability
+
+AUTO mode documents autonomous PLAN → ACT → EVAL cycling. In Cursor, this depends entirely on the AI model voluntarily continuing the loop — there is no enforcement mechanism like Claude Code's hooks. Results may vary:
+
+- The AI may stop after one iteration instead of looping
+- Quality exit criteria (`Critical = 0 AND High = 0`) are advisory, not enforced
+- For reliable multi-iteration workflows, prefer manual `PLAN` → `ACT` → `EVAL` cycling
+
+## Verification Status
+
+> Audit per [#609](https://github.com/JeremyDev87/codingbuddy/issues/609). Code-level analysis complete, Cursor runtime verification pending.
+
+| Pattern | Status | Notes |
+|---------|--------|-------|
+| MCP Tools Table | ✅ Updated | All 18 tools documented (including 1 deprecated) |
+| Mode keyword detection (imports.mdc) | ⚠️ Code-verified | `parse_mode` handler exists; Cursor AI invocation depends on model behavior |
+| File pattern → Agent mapping (auto-agent.mdc) | ⚠️ Code-verified | Mappings reference valid agents; Cursor auto-apply depends on glob matching |
+| AUTO mode workflow | ⚠️ Documented with caveat | No enforcement mechanism in Cursor; see Known Limitations |
+| Context document management | ✅ Documented | New section added with Cursor-specific guidance |
+| Known Limitations | ✅ Added | Task tool, hooks, autonomous loop, TUI limitations documented |
+
 ## Reference
 
 - [AGENTS.md Official Spec](https://agents.md)