@every-env/compound-plugin 0.2.0 → 0.5.0

package/docs/plans/2026-02-08-refactor-reduce-plugin-context-token-usage-plan.md

@@ -0,0 +1,212 @@
+---
+title: Reduce compound-engineering plugin context token usage
+type: refactor
+date: 2026-02-08
+---
+
+# Reduce compound-engineering Plugin Context Token Usage
+
+## Overview
+
+The compound-engineering plugin is **overflowing the default context budget by ~3x**, causing Claude Code to silently drop components. The plugin consumes ~50,500 characters in always-loaded descriptions against a default budget of 16,000 characters (2% of context window). This means Claude literally doesn't know some agents/skills exist during sessions.
+
+## Problem Statement
+
+### How Context Loading Works
+
+Claude Code uses progressive disclosure for plugin content:
+
+| Level | What Loads | When |
+|-------|-----------|------|
+| **Always in context** | `description` frontmatter from skills, commands, and agents | Session startup (unless `disable-model-invocation: true`) |
+| **On invocation** | Full SKILL.md / command body / agent body | When triggered |
+| **On demand** | Reference files in skill directories | When Claude reads them |
+
+The total budget for ALL descriptions combined is **2% of context window** (~16,000 chars fallback). When exceeded, components are **silently excluded**.
+
+### Current State: 316% of Budget
+
+| Component | Count | Always-Loaded Chars | % of 16K Budget |
+|-----------|------:|--------------------:|----------------:|
+| Agent descriptions | 29 | ~41,400 | 259% |
+| Skill descriptions | 16 | ~5,450 | 34% |
+| Command descriptions | 24 | ~3,700 | 23% |
+| **Total** | **69** | **~50,500** | **316%** |
+
+### Root Cause: Bloated Agent Descriptions
+
+Agent `description` fields contain full `<example>` blocks with user/assistant dialog. These examples belong in the agent body (system prompt), not the description. The description's only job is **discovery** — helping Claude decide whether to delegate.
+
+Examples of the problem:
+
+- `design-iterator.md`: 2,488 chars in description (should be ~200)
+- `spec-flow-analyzer.md`: 2,289 chars in description
+- `security-sentinel.md`: 1,986 chars in description
+- `kieran-rails-reviewer.md`: 1,822 chars in description
+- Average agent description: ~1,400 chars (should be 100-250)
+
+Compare to Anthropic's official examples at 100-200 chars:
+
+```yaml
+# Official (140 chars)
+description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
+
+# Current plugin (1,822 chars)
+description: "Use this agent when you need to review Rails code changes with an extremely high quality bar...\n\nExamples:\n- <example>\n  Context: The user has just implemented..."
+```
+
+### Secondary Cause: No `disable-model-invocation` on Manual Commands
+
+Zero commands set `disable-model-invocation: true`. Commands like `/deploy-docs`, `/lfg`, `/slfg`, `/triage`, `/feature-video`, `/test-browser`, `/xcode-test` are manual workflows with side effects. Their descriptions consume budget unnecessarily.
+
+The official docs explicitly state:
+> Use `disable-model-invocation: true` for workflows with side effects: `/deploy`, `/commit`, `/triage-prs`. You don't want Claude deciding to deploy because your code looks ready.
+
+---
+
+## Proposed Solution
+
+Three changes, ordered by impact:
+
+### Phase 1: Trim Agent Descriptions (saves ~35,600 chars)
+
+For all 29 agents: move `<example>` blocks from the `description` field into the agent body markdown. Keep descriptions to 1-2 sentences (100-250 chars).
+
+**Before** (agent frontmatter):
+```yaml
+---
+name: kieran-rails-reviewer
+description: "Use this agent when you need to review Rails code changes with an extremely high quality bar. This agent should be invoked after implementing features, modifying existing code, or creating new Rails components. The agent applies Kieran's strict Rails conventions and taste preferences to ensure code meets exceptional standards.\n\nExamples:\n- <example>\n  Context: The user has just implemented a new controller action with turbo streams.\n  user: \"I've added a new update action to the posts controller\"\n  ..."
+---
+
+Detailed system prompt...
+```
+
+**After** (agent frontmatter):
+```yaml
+---
+name: kieran-rails-reviewer
+description: Review Rails code with Kieran's strict conventions. Use after implementing features, modifying code, or creating new Rails components.
+---
+
+<examples>
+<example>
+Context: The user has just implemented a new controller action with turbo streams.
+user: "I've added a new update action to the posts controller"
+...
+</example>
+</examples>
+
+Detailed system prompt...
+```
+
+The examples move into the body (which only loads when the agent is actually invoked).
+
+**Impact:** ~41,400 chars → ~5,800 chars (86% reduction)
+
+### Phase 2: Add `disable-model-invocation: true` to Manual Commands (saves ~3,100 chars)
+
+Commands that should only run when explicitly invoked by the user:
+
+| Command | Reason |
+|---------|--------|
+| `/deploy-docs` | Side effect: deploys |
+| `/release-docs` | Side effect: regenerates docs |
+| `/changelog` | Side effect: generates changelog |
+| `/lfg` | Side effect: autonomous workflow |
+| `/slfg` | Side effect: swarm workflow |
+| `/triage` | Side effect: categorizes findings |
+| `/resolve_parallel` | Side effect: resolves TODOs |
+| `/resolve_todo_parallel` | Side effect: resolves todos |
+| `/resolve_pr_parallel` | Side effect: resolves PR comments |
+| `/feature-video` | Side effect: records video |
+| `/test-browser` | Side effect: runs browser tests |
+| `/xcode-test` | Side effect: builds/tests iOS |
+| `/reproduce-bug` | Side effect: runs reproduction |
+| `/report-bug` | Side effect: creates bug report |
+| `/agent-native-audit` | Side effect: runs audit |
+| `/heal-skill` | Side effect: modifies skill files |
+| `/generate_command` | Side effect: creates files |
+| `/create-agent-skill` | Side effect: creates files |
+
+Keep these **without** the flag (Claude should know about them):
+- `/workflows:plan` — Claude might suggest planning
+- `/workflows:work` — Claude might suggest starting work
+- `/workflows:review` — Claude might suggest review
+- `/workflows:brainstorm` — Claude might suggest brainstorming
+- `/workflows:compound` — Claude might suggest documenting
+- `/deepen-plan` — Claude might suggest deepening a plan
+
+**Impact:** ~3,700 chars → ~600 chars for commands in context
+
+### Phase 3: Add `disable-model-invocation: true` to Manual Skills (saves ~1,000 chars)
+
+Skills that are manual workflows:
+
+| Skill | Reason |
+|-------|--------|
+| `skill-creator` | Only invoked manually |
+| `orchestrating-swarms` | Only invoked manually |
+| `git-worktree` | Only invoked manually |
+| `resolve-pr-parallel` | Side effect |
+| `compound-docs` | Only invoked manually |
+| `file-todos` | Only invoked manually |
+
+Keep without the flag (Claude should auto-invoke):
+- `dhh-rails-style` — Claude should use when writing Rails code
+- `frontend-design` — Claude should use when building UI
+- `brainstorming` — Claude should suggest before implementation
+- `agent-browser` — Claude should use for browser tasks
+- `gemini-imagegen` — Claude should use for image generation
+- `create-agent-skills` — Claude should use when creating skills
+- `every-style-editor` — Claude should use for editing
+- `dspy-ruby` — Claude should use for DSPy.rb
+- `agent-native-architecture` — Claude should use for agent-native design
+- `andrew-kane-gem-writer` — Claude should use for gem writing
+- `rclone` — Claude should use for cloud uploads
+- `document-review` — Claude should use for doc review
+
+**Impact:** ~5,450 chars → ~4,000 chars for skills in context
+
+---
+
+## Projected Result
+
+| Component | Before (chars) | After (chars) | Reduction |
+|-----------|---------------:|-------------:|-----------:|
+| Agent descriptions | ~41,400 | ~5,800 | -86% |
+| Command descriptions | ~3,700 | ~600 | -84% |
+| Skill descriptions | ~5,450 | ~4,000 | -27% |
+| **Total** | **~50,500** | **~10,400** | **-79%** |
+| **% of 16K budget** | **316%** | **65%** | -- |
+
+From 316% of budget (components silently dropped) to 65% of budget (room for growth).
+
+---
+
+## Acceptance Criteria
+
+- [x] All 29 agent description fields are under 250 characters
+- [x] All `<example>` blocks moved from description to agent body
+- [x] 18 manual commands have `disable-model-invocation: true`
+- [x] 6 manual skills have `disable-model-invocation: true`
+- [x] Total always-loaded description content is under 16,000 characters
+- [ ] Run `/context` to verify no "excluded skills" warnings
+- [x] All agents still function correctly (examples are in body, not lost)
+- [x] All commands still invocable via `/command-name`
+- [x] Update plugin version in plugin.json and marketplace.json
+- [x] Update CHANGELOG.md
+
+## Implementation Notes
+
+- Agent examples should use `<examples><example>...</example></examples>` tags in the body — Claude understands these natively
+- Description format: "[What it does]. Use [when/trigger condition]." — two sentences max
+- The `lint` agent at 115 words shows compact agents work great
+- Test with `claude --plugin-dir ./plugins/compound-engineering` after changes
+- The `SLASH_COMMAND_TOOL_CHAR_BUDGET` env var can override the default budget for testing
+
+## References
+
+- [Skills docs](https://code.claude.com/docs/en/skills) — "Skill descriptions are loaded into context... If you have many skills, they may exceed the character budget"
+- [Subagents docs](https://code.claude.com/docs/en/sub-agents) — description field used for automatic delegation
+- [Skills troubleshooting](https://code.claude.com/docs/en/skills#claude-doesnt-see-all-my-skills) — "The budget scales dynamically at 2% of the context window, with a fallback of 16,000 characters"

package/docs/plans/2026-02-09-refactor-dspy-ruby-skill-update-plan.md

@@ -0,0 +1,104 @@
+---
+title: "refactor: Update dspy-ruby skill to DSPy.rb v0.34.3 API"
+type: refactor
+date: 2026-02-09
+---
+
+# Update dspy-ruby Skill to DSPy.rb v0.34.3 API
+
+## Problem
+
+The `dspy-ruby` skill uses outdated API patterns (`.forward()`, `result[:field]`, inline `T.enum([...])`, `DSPy::Tool`) and is missing 10+ features (events, lifecycle callbacks, GEPA, evaluation framework, BAML/TOON, storage, etc.).
+
+## Solution
+
+Use the engineering skill as base (already has correct API), enhance with official docs content, rewrite all reference files and templates.
+
+### Source Priority (when conflicts arise)
+
+1. **Official docs** (`../dspy.rb/docs/src/`) — source of truth for API correctness
+2. **Engineering skill** (`../engineering/.../dspy-rb/SKILL.md`) — source of truth for structure/style
+3. **NavigationContext brainstorm** — for Typed Context pattern only
+
+## Files to Update
+
+### Core (SKILL.md)
+
+1. **`skills/dspy-ruby/SKILL.md`** — Copy from engineering base, then:
+   - Fix frontmatter: `name: dspy-rb` → `name: dspy-ruby`, keep long description format
+   - Add sections before "Guidelines for Claude": Events System, Lifecycle Callbacks, Fiber-Local LM Context, Evaluation Framework, GEPA Optimization, Typed Context Pattern, Schema Formats (BAML/TOON)
+   - Update Resources section with 5 references + 3 assets using markdown links
+   - Fix any backtick references to markdown link format
+
+### References (rewrite from themed doc batches)
+
+2. **`references/core-concepts.md`** — Rewrite
+   - Source: `core-concepts/signatures.md`, `modules.md`, `predictors.md`, `advanced/complex-types.md`
+   - Cover: signatures (Date/Time types, T::Enum, defaults, field descriptions, BAML/TOON, recursive types), modules (.call() API, lifecycle callbacks, instruction update contract), predictors (all 4 types, concurrent predictions), type system (discriminators, union types)
+
+3. **`references/toolsets.md`** — NEW
+   - Source: `core-concepts/toolsets.md`, `toolsets-guide.md`
+   - Cover: Tools::Base, Tools::Toolset DSL, type safety with Sorbet sigs, schema generation, built-in toolsets, testing
+
+4. **`references/providers.md`** — Rewrite
+   - Source: `llms.txt.erb`, engineering SKILL.md, `core-concepts/module-runtime-context.md`
+   - Cover: per-provider adapters, RubyLLM unified adapter, Rails initializer, fiber-local LM context (`DSPy.with_lm`), feature-flagged model selection, compatibility matrix
+
+5. **`references/optimization.md`** — Rewrite
+   - Source: `optimization/miprov2.md`, `gepa.md`, `evaluation.md`, `production/storage.md`
+   - Cover: MIPROv2 (dspy-miprov2 gem, AutoMode presets), GEPA (dspy-gepa gem, feedback maps), Evaluation (DSPy::Evals, built-in metrics, DSPy::Example), Storage (ProgramStorage)
+
+6. **`references/observability.md`** — NEW
+   - Source: `production/observability.md`, `core-concepts/events.md`, `advanced/observability-interception.md`
+   - Cover: event system (module-scoped + global), dspy-o11y gems, Langfuse (env vars), score reporting (DSPy.score()), observation types, DSPy::Context.with_span
+
+### Assets (rewrite to current API)
+
+7. **`assets/signature-template.rb`** — T::Enum classes, `description:` kwarg, Date/Time types, defaults, union types, `.call()` / `result.field` usage examples
+
+8. **`assets/module-template.rb`** — `.call()` API, `result.field`, Tools::Base, lifecycle callbacks, `DSPy.with_lm`, `configure_predictor`
+
+9. **`assets/config-template.rb`** — RubyLLM adapter, `structured_outputs: true`, `after_initialize` Rails pattern, dspy-o11y env vars, feature-flagged model selection
+
+### Metadata
+
+10. **`.claude-plugin/plugin.json`** — Version `2.31.0` → `2.31.1`
+
+11. **`CHANGELOG.md`** — Add `[2.31.1] - 2026-02-09` entry under `### Changed`
+
+## Verification
+
+```bash
+# No old API patterns
+grep -n '\.forward(\|result\[:\|T\.enum(\[\|DSPy::Tool[^s]' plugins/compound-engineering/skills/dspy-ruby/SKILL.md
+
+# No backtick references
+grep -E '`(references|assets|scripts)/' plugins/compound-engineering/skills/dspy-ruby/SKILL.md
+
+# Frontmatter correct
+head -4 plugins/compound-engineering/skills/dspy-ruby/SKILL.md
+
+# JSON valid
+cat plugins/compound-engineering/.claude-plugin/plugin.json | jq .
+
+# All files exist
+ls plugins/compound-engineering/skills/dspy-ruby/{references,assets}/
+```
+
+## Success Criteria
+
+- [x] All API patterns updated (`.call()`, `result.field`, `T::Enum`, `Tools::Base`)
+- [x] New features covered: events, callbacks, fiber-local LM, GEPA, evals, BAML/TOON, storage, score API, RubyLLM, typed context
+- [x] 5 reference files present (core-concepts, toolsets, providers, optimization, observability)
+- [x] 3 asset templates updated to current API
+- [x] YAML frontmatter: `name: dspy-ruby`, description has "what" and "when"
+- [x] All reference links use `[file.md](./references/file.md)` format
+- [x] Writing style: imperative form, no "you should"
+- [x] Version bumped to `2.31.1`, CHANGELOG updated
+- [x] Verification commands all pass
+
+## Source Materials
+
+- Engineering skill: `/Users/vicente/Workspaces/vicente.services/engineering/plugins/engineering-skills/skills/dspy-rb/SKILL.md`
+- Official docs: `/Users/vicente/Workspaces/vicente.services/dspy.rb/docs/src/`
+- NavigationContext brainstorm: `/Users/vicente/Workspaces/vicente.services/observo/observo-server/docs/brainstorms/2026-02-09-typed-navigation-context-brainstorm.md`

package/docs/plans/2026-02-12-feat-add-cursor-cli-target-provider-plan.md

@@ -0,0 +1,306 @@
+---
+title: Add Cursor CLI as a Target Provider
+type: feat
+date: 2026-02-12
+---
+
+# Add Cursor CLI as a Target Provider
+
+## Overview
+
+Add `cursor` as a fourth target provider in the converter CLI, alongside `opencode`, `codex`, and `droid`. This enables `--to cursor` for both `convert` and `install` commands, converting Claude Code plugins into Cursor-compatible format.
+
+Cursor CLI (`cursor-agent`) launched in August 2025 and supports rules (`.mdc`), commands (`.md`), skills (`SKILL.md` standard), and MCP servers (`.cursor/mcp.json`). The mapping from Claude Code is straightforward because Cursor adopted the open SKILL.md standard and has a similar command format.
+
+## Component Mapping
+
+| Claude Code | Cursor Equivalent | Notes |
+|---|---|---|
+| `agents/*.md` | `.cursor/rules/*.mdc` | Agents become "Agent Requested" rules (`alwaysApply: false`, `description` set) so the AI activates them on demand rather than flooding context |
+| `commands/*.md` | `.cursor/commands/*.md` | Plain markdown files; Cursor commands have no frontmatter support -- description becomes a markdown heading |
+| `skills/*/SKILL.md` | `.cursor/skills/*/SKILL.md` | **Identical standard** -- copy directly |
+| MCP servers | `.cursor/mcp.json` | Same JSON structure (`mcpServers` key), compatible format |
+| `hooks/` | No equivalent | Cursor has no hook system; emit `console.warn` and skip |
+| `.claude/` paths | `.cursor/` paths | Content rewriting needed |
+
+### Key Design Decisions
+
+**1. Agents use `alwaysApply: false` (Agent Requested mode)**
+
+With 29 agents, setting `alwaysApply: true` would flood every Cursor session's context. Instead, agents become "Agent Requested" rules: `alwaysApply: false` with a populated `description` field. Cursor's AI reads the description and activates the rule only when relevant -- matching how Claude Code agents are invoked on demand.
+
+**2. Commands are plain markdown (no frontmatter)**
+
+Cursor commands (`.cursor/commands/*.md`) are simple markdown files where the filename becomes the command name. Unlike Claude Code commands, they do not support YAML frontmatter. The converter emits the description as a leading markdown comment, then the command body.
+
+**3. Flattened command names with deduplication**
+
+Cursor uses flat command names (no namespaces). `workflows:plan` becomes `plan`. If two commands flatten to the same name, the `uniqueName()` pattern from the codex converter appends `-2`, `-3`, etc.
+
+### Rules (`.mdc`) Frontmatter Format
+
+```yaml
+---
+description: "What this rule does and when it applies"
+globs: ""
+alwaysApply: false
+---
+```
+
+- `description` (string): Used by the AI to decide relevance -- maps from agent `description`
+- `globs` (string): Comma-separated file patterns for auto-attachment -- leave empty for converted agents
+- `alwaysApply` (boolean): Set `false` for Agent Requested mode
+
+### MCP Servers (`.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "npx",
+      "args": ["-y", "package-name"],
+      "env": { "KEY": "value" }
+    }
+  }
+}
+```
+
+Supports both local (command-based) and remote (url-based) servers. Pass through `headers` for remote servers.
+
+## Acceptance Criteria
+
+- [x] `bun run src/index.ts convert --to cursor ./plugins/compound-engineering` produces valid Cursor config
+- [x] Agents convert to `.cursor/rules/*.mdc` with `alwaysApply: false` and populated `description`
+- [x] Commands convert to `.cursor/commands/*.md` as plain markdown (no frontmatter)
+- [x] Flattened command names that collide are deduplicated (`plan`, `plan-2`, etc.)
+- [x] Skills copied to `.cursor/skills/` (identical format)
+- [x] MCP servers written to `.cursor/mcp.json` with backup of existing file
+- [x] Content transformation rewrites `.claude/` and `~/.claude/` paths to `.cursor/` and `~/.cursor/`
+- [x] `/workflows:plan` transformed to `/plan` (flat command names)
+- [x] `Task agent-name(args)` transformed to natural-language skill reference
+- [x] Plugins with hooks emit `console.warn` about unsupported hooks
+- [x] Writer does not double-nest `.cursor/.cursor/` (follows droid writer pattern)
+- [x] `model` and `allowedTools` fields silently dropped (no Cursor equivalent)
+- [x] Converter and writer tests pass
+- [x] Existing tests still pass (`bun test`)
+
+## Implementation
+
+### Phase 1: Types
+
+**Create `src/types/cursor.ts`**
+
+```typescript
+export type CursorRule = {
+  name: string
+  content: string  // Full .mdc file with YAML frontmatter
+}
+
+export type CursorCommand = {
+  name: string
+  content: string  // Plain markdown (no frontmatter)
+}
+
+export type CursorSkillDir = {
+  name: string
+  sourceDir: string
+}
+
+export type CursorBundle = {
+  rules: CursorRule[]
+  commands: CursorCommand[]
+  skillDirs: CursorSkillDir[]
+  mcpServers?: Record<string, {
+    command?: string
+    args?: string[]
+    env?: Record<string, string>
+    url?: string
+    headers?: Record<string, string>
+  }>
+}
+```
+
+### Phase 2: Converter
+
+**Create `src/converters/claude-to-cursor.ts`**
+
+Core functions:
+
+1. **`convertClaudeToCursor(plugin, options)`** -- main entry point
+   - Convert each agent to a `.mdc` rule via `convertAgentToRule()`
+   - Convert each command (including `disable-model-invocation` ones) via `convertCommand()`
+   - Pass skills through as directory references
+   - Convert MCP servers to JSON-compatible object
+   - Emit `console.warn` if `plugin.hooks` has entries
+
+2. **`convertAgentToRule(agent, usedNames)`** -- agent -> `.mdc` rule
+   - Frontmatter fields: `description` (from agent description), `globs: ""`, `alwaysApply: false`
+   - Body: agent body with content transformations applied
+   - Prepend capabilities section if present
+   - Deduplicate names via `uniqueName()`
+   - Silently drop `model` field (no Cursor equivalent)
+
+3. **`convertCommand(command, usedNames)`** -- command -> plain `.md`
+   - Flatten namespace: `workflows:plan` -> `plan`
+   - Deduplicate flattened names via `uniqueName()`
+   - Emit as plain markdown: description as `<!-- description -->` comment, then body
+   - Include `argument-hint` as a `## Arguments` section if present
+   - Body: apply `transformContentForCursor()` transformations
+   - Silently drop `allowedTools` (no Cursor equivalent)
+
+4. **`transformContentForCursor(body)`** -- content rewriting
+   - `.claude/` -> `.cursor/` and `~/.claude/` -> `~/.cursor/`
+   - `Task agent-name(args)` -> `Use the agent-name skill to: args` (same as codex)
+   - `/workflows:command` -> `/command` (flatten slash commands)
+   - `@agent-name` references -> `the agent-name rule` (use codex's suffix-matching pattern)
+   - Skip file paths (containing `/`) and common non-command patterns
+
+5. **`convertMcpServers(servers)`** -- MCP config
+   - Map each `ClaudeMcpServer` entry to Cursor-compatible JSON
+   - Pass through: `command`, `args`, `env`, `url`, `headers`
+   - Drop `type` field (Cursor infers transport from `command` vs `url`)
+
+### Phase 3: Writer
+
+**Create `src/targets/cursor.ts`**
+
+Output structure:
+
+```
+.cursor/
+├── rules/
+│   ├── agent-name-1.mdc
+│   └── agent-name-2.mdc
+├── commands/
+│   ├── command-1.md
+│   └── command-2.md
+├── skills/
+│   └── skill-name/
+│       └── SKILL.md
+└── mcp.json
+```
+
+Core function: `writeCursorBundle(outputRoot, bundle)`
+
+- `resolveCursorPaths(outputRoot)` -- detect if path already ends in `.cursor` to avoid double-nesting (follow droid writer pattern at `src/targets/droid.ts:31-50`)
+- Write rules to `rules/` as `.mdc` files
+- Write commands to `commands/` as `.md` files
+- Copy skill directories to `skills/` via `copyDir()`
+- Write `mcp.json` via `writeJson()` with `backupFile()` for existing files
+
+### Phase 4: Wire into CLI
+
+**Modify `src/targets/index.ts`**
+
+```typescript
+import { convertClaudeToCursor } from "../converters/claude-to-cursor"
+import { writeCursorBundle } from "./cursor"
+import type { CursorBundle } from "../types/cursor"
+
+// Add to targets:
+cursor: {
+  name: "cursor",
+  implemented: true,
+  convert: convertClaudeToCursor as TargetHandler<CursorBundle>["convert"],
+  write: writeCursorBundle as TargetHandler<CursorBundle>["write"],
+},
+```
+
+**Modify `src/commands/convert.ts`**
+
+- Update `--to` description: `"Target format (opencode | codex | droid | cursor)"`
+- Add to `resolveTargetOutputRoot`: `if (targetName === "cursor") return path.join(outputRoot, ".cursor")`
+
+**Modify `src/commands/install.ts`**
+
+- Same two changes as convert.ts
+
+### Phase 5: Tests
+
+**Create `tests/cursor-converter.test.ts`**
+
+Test cases (use inline `ClaudePlugin` fixtures, following codex converter test pattern):
+
+- Agent converts to rule with `.mdc` frontmatter (`alwaysApply: false`, `description` populated)
+- Agent with empty description gets default description text
+- Agent with capabilities prepended to body
+- Agent `model` field silently dropped
+- Agent with empty body gets default body text
+- Command converts with flattened name (`workflows:plan` -> `plan`)
+- Command name collision after flattening is deduplicated (`plan`, `plan-2`)
+- Command with `disable-model-invocation` is still included
+- Command `allowedTools` silently dropped
+- Command with `argument-hint` gets Arguments section
+- Skills pass through as directory references
+- MCP servers convert to JSON config (local and remote)
+- MCP `headers` pass through for remote servers
+- Content transformation: `.claude/` paths -> `.cursor/`
+- Content transformation: `~/.claude/` paths -> `~/.cursor/`
+- Content transformation: `Task agent(args)` -> natural language
+- Content transformation: slash commands flattened
+- Hooks present -> `console.warn` emitted
+- Plugin with zero agents produces empty rules array
+- Plugin with only skills works correctly
+
+**Create `tests/cursor-writer.test.ts`**
+
+Test cases (use temp directories, following droid writer test pattern):
+
+- Full bundle writes rules, commands, skills, mcp.json
+- Rules written as `.mdc` files in `rules/` directory
+- Commands written as `.md` files in `commands/` directory
+- Skills copied to `skills/` directory
+- MCP config written as valid JSON `mcp.json`
+- Existing `mcp.json` is backed up before overwrite
+- Output root already ending in `.cursor` does NOT double-nest
+- Empty bundle (no rules, commands, skills, or MCP) produces no output
+
+### Phase 6: Documentation
+
+**Create `docs/specs/cursor.md`**
+
+Document the Cursor CLI spec as a reference, following `docs/specs/codex.md` pattern:
+
+- Rules format (`.mdc` with `description`, `globs`, `alwaysApply` frontmatter)
+- Commands format (plain markdown, no frontmatter)
+- Skills format (identical SKILL.md standard)
+- MCP server configuration (`.cursor/mcp.json`)
+- CLI permissions (`.cursor/cli.json` -- for reference, not converted)
+- Config file locations (project-level vs global)
+
+**Update `README.md`**
+
+Add `cursor` to the supported targets in the CLI usage section.
+
+## What We're NOT Doing
+
+- Not converting hooks (Cursor has no hook system -- warn and skip)
+- Not generating `.cursor/cli.json` permissions (user-specific, not plugin-scoped)
+- Not creating `AGENTS.md` (Cursor reads it natively, but not part of plugin conversion)
+- Not using `globs` field intelligently (would require analyzing agent content to guess file patterns)
+- Not adding sync support (follow-up task)
+- Not transforming content inside copied SKILL.md files (known limitation -- skills may reference `.claude/` paths internally)
+- Not clearing old output before writing (matches existing target behavior -- re-runs accumulate)
+
+## Complexity Assessment
+
+This is a **medium change**. The converter architecture is well-established with three existing targets, so this is mostly pattern-following. The key novelties are:
+
+1. The `.mdc` frontmatter format (different from all other targets)
+2. Agents map to "rules" rather than a direct equivalent
+3. Commands are plain markdown (no frontmatter) unlike other targets
+4. Name deduplication needed for flattened command namespaces
+
+Skills being identical across platforms simplifies things significantly. MCP config is nearly 1:1.
+
+## References
+
+- Cursor Rules: `.cursor/rules/*.mdc` with `description`, `globs`, `alwaysApply` frontmatter
+- Cursor Commands: `.cursor/commands/*.md` (plain markdown, no frontmatter)
+- Cursor Skills: `.cursor/skills/*/SKILL.md` (open standard, identical to Claude Code)
+- Cursor MCP: `.cursor/mcp.json` with `mcpServers` key
+- Cursor CLI: `cursor-agent` command (launched August 2025)
+- Existing codex converter: `src/converters/claude-to-codex.ts` (has `uniqueName()` deduplication pattern)
+- Existing droid writer: `src/targets/droid.ts` (has double-nesting guard pattern)
+- Existing codex plan: `docs/plans/2026-02-08-feat-convert-local-md-settings-for-opencode-codex-plan.md`
+- Target provider checklist: `AGENTS.md` section "Adding a New Target Provider"