caruso 0.6.2 → 0.7.0

data/reference/cursor_rules.md

@@ -0,0 +1,246 @@
+# Rules
+
+Rules provide system-level instructions to Agent. They bundle prompts, scripts, and more together, making it easy to manage and share workflows across your team.
+
+Cursor supports four types of rules:
+
+- [Project Rules](): Stored in .cursor/rules, version-controlled and scoped to your codebase.
+- [User Rules](): Global to your Cursor environment. Used by Agent (Chat).
+- [Team Rules](): Team-wide rules managed from the dashboard. Available on Team and Enterprise plans.
+- [AGENTS.md](): Agent instructions in markdown format. Simple alternative to
+.cursor/rules.
+
+## How rules work
+
+Large language models don't retain memory between completions. Rules provide persistent, reusable context at the prompt level.
+
+When applied, rule contents are included at the start of the model context. This gives the AI consistent guidance for generating code, interpreting edits, or helping with workflows.
+
+## Project rules
+
+Project rules live in `.cursor/rules`. Each rule is a folder containing a `RULE.md` file and is version-controlled. They are scoped using path patterns, invoked manually, or included based on relevance.
+
+Use project rules to:
+
+- Encode domain-specific knowledge about your codebase
+- Automate project-specific workflows or templates
+- Standardize style or architecture decisions
+
+### Rule folder structure
+
+Each rule folder can contain:
+
+- **`RULE.md`** — The main rule file with frontmatter metadata and instructions
+- **Scripts and prompts** — Additional files referenced by the rule
+
+```
+.cursor/rules/
+  my-rule/
+    RULE.md           # Main rule file
+    scripts/          # Helper scripts (optional)
+```
+
+### Rule anatomy
+
+Each rule is a folder containing a `RULE.md` file with frontmatter metadata and content. Control how rules are applied from the type dropdown which changes properties `description`, `globs`, `alwaysApply`.
+
+Rule TypeDescription`Always Apply`Apply to every chat session`Apply Intelligently`When Agent decides it's relevant based on description`Apply to Specific Files`When file matches a specified pattern`Apply Manually`When @-mentioned in chat (e.g., `@my-rule`)
+```
+---
+globs:
+alwaysApply: false
+---
+
+- Use our internal RPC pattern when defining services
+- Always use snake_case for service names.
+
+@service-template.ts
+```
+
+### Creating a rule
+
+Create rules using the `New Cursor Rule` command or going to `Cursor Settings > Rules, Commands`. This creates a new rule folder in `.cursor/rules`. From settings you can see all rules and their status.
+
+## Best practices
+
+Good rules are focused, actionable, and scoped.
+
+- Keep rules under 500 lines
+- Split large rules into multiple, composable rules
+- Provide concrete examples or referenced files
+- Avoid vague guidance. Write rules like clear internal docs
+- Reuse rules when repeating prompts in chat
+
+## RULE.md file format
+
+The `RULE.md` file is a markdown file with frontmatter metadata and content. The frontmatter metadata is used to control how the rule is applied. The content is the rule itself.
+
+```
+---
+description: "This rule provides standards for frontend components and API validation"
+alwaysApply: false
+---
+
+...rest of the rule content
+```
+
+If alwaysApply is true, the rule will be applied to every chat session. Otherwise, the description of the rule will be presented to the Cursor Agent to decide if it should be applied.
+
+## Examples
+
+### Standards for frontend components and API validation
+
+### Templates for Express services and React components
+
+### Automating development workflows and documentation generation
+
+### Adding a new setting in Cursor
+
+First create a property to toggle in `@reactiveStorageTypes.ts`.
+
+Add default value in `INIT_APPLICATION_USER_PERSISTENT_STORAGE` in `@reactiveStorageService.tsx`.
+
+For beta features, add toggle in `@settingsBetaTab.tsx`, otherwise add in `@settingsGeneralTab.tsx`. Toggles can be added as `<SettingsSubSection>` for general checkboxes. Look at the rest of the file for examples.
+
+```
+<SettingsSubSection  label="Your feature name"  description="Your feature description"  value={    vsContext.reactiveStorageService.applicationUserPersistentStorage      .myNewProperty ?? false  }  onChange={(newVal) => {    vsContext.reactiveStorageService.setApplicationUserPersistentStorage(      "myNewProperty",      newVal,    );  }}/>
+```
+
+To use in the app, import reactiveStorageService and use the property:
+
+```
+const flagIsEnabled =  vsContext.reactiveStorageService.applicationUserPersistentStorage    .myNewProperty;
+```
+
+Examples are available from providers and frameworks. Community-contributed rules are found across crowdsourced collections and repositories online.
+
+## Team Rules
+
+Team and [Enterprise](/docs/enterprise) plans can create and enforce rules across their entire organization from the [Cursor dashboard](https://cursor.com/dashboard?tab=team-content). Admins can configure whether or not each rule is required for team members.
+
+Team Rules work alongside other rule types and take precedence to ensure organizational standards are maintained across all projects. They provide a powerful way to ensure consistent coding standards, practices, and workflows across your entire team without requiring individual setup or configuration.
+
+### Managing Team Rules
+
+Team administrators can create and manage rules directly from the Cursor dashboard:
+
+Once team rules are created, they automatically apply to all team members and are visible in the dashboard:
+
+### Activation and enforcement
+
+- **Enable this rule immediately**: When checked, the rule is active as soon as you create it. When unchecked, the rule is saved as a draft and does not apply until you enable it later.
+- **Enforce this rule**: When enabled, the rule is required for all team members and cannot be disabled in their Cursor settings. When not enforced, team members can toggle the rule off in `Cursor Settings → Rules` under the Team Rules section.
+
+By default, non‑enforced Team Rules can be disabled by users. Use **Enforce this rule** to prevent that.
+
+### Format and how Team Rules are applied
+
+- **Plain text**: Team Rules are free‑form text. They do not use the folder structure of Project Rules and do not support metadata such as `globs`, `alwaysApply`, or rule types.
+- **Where they apply**: When a Team Rule is enabled (and not disabled by the user, unless enforced), it is included in the model context for Agent (Chat) across all repositories and projects for that team.
+- **Precedence**: Rules are applied in this order: **Team Rules → Project Rules → User Rules**. All applicable rules are merged; earlier sources take precedence when guidance conflicts.
+
+Some teams use enforced rules as part of internal compliance workflows. While this is supported, AI guidance should not be your only security control.
+
+## Importing Rules
+
+You can import rules from external sources to reuse existing configurations or bring in rules from other tools.
+
+### Remote rules (via GitHub)
+
+Import rules directly from any GitHub repository you have access to—public or private.
+
+1. Open **Cursor Settings → Rules, Commands**
+2. Click `+ Add Rule` next to `Project Rules`, then select Remote Rule (Github)
+3. Paste the GitHub repository URL containing the rule
+4. Cursor will pull and sync the rule into your project
+
+Imported rules stay synced with their source repository, so updates to the remote rule are automatically reflected in your project.
+
+### Agent Skills
+
+Cursor can load rules from [Agent Skills](/docs/context/skills), an open standard for extending AI agents with specialized capabilities. These imported skills are always applied as agent-decided rules, meaning Cursor determines when they are relevant based on context.
+
+To enable or disable Agent Skills:
+
+1. Open **Cursor Settings → Rules**
+2. Find the **Import Settings** section
+3. Toggle **Agent Skills** on or off
+
+Agent Skills are treated as agent-decided rules and cannot be configured as always-apply or manual rules.
+
+## AGENTS.md
+
+`AGENTS.md` is a simple markdown file for defining agent instructions. Place it in your project root as an alternative to `.cursor/rules` for straightforward use cases.
+
+Unlike Project Rules, `AGENTS.md` is a plain markdown file without metadata or complex configurations. It's perfect for projects that need simple, readable instructions without the overhead of structured rules.
+
+Cursor supports AGENTS.md in the project root and subdirectories.
+
+```
+# Project Instructions
+
+## Code Style
+
+- Use TypeScript for all new files
+- Prefer functional components in React
+- Use snake_case for database columns
+
+## Architecture
+
+- Follow the repository pattern
+- Keep business logic in service layers
+```
+
+### Improvements
+
+### Nested AGENTS.md support
+
+Nested `AGENTS.md` support in subdirectories is now available. You can place `AGENTS.md` files in any subdirectory of your project, and they will be automatically applied when working with files in that directory or its children.
+
+This allows for more granular control of agent instructions based on the area of your codebase you're working in:
+
+```
+project/
+  AGENTS.md              # Global instructions
+  frontend/
+    AGENTS.md            # Frontend-specific instructions
+    components/
+      AGENTS.md          # Component-specific instructions
+  backend/
+    AGENTS.md            # Backend-specific instructions
+```
+
+Instructions from nested `AGENTS.md` files are combined with parent directories, with more specific instructions taking precedence.
+
+## User Rules
+
+User Rules are global preferences defined in **Cursor Settings → Rules** that apply across all projects. They are used by Agent (Chat) and are perfect for setting preferred communication style or coding conventions:
+
+```
+Please reply in a concise style. Avoid unnecessary repetition or filler language.
+```
+
+## Legacy Cursor Rules
+
+### .cursorrules
+
+The `.cursorrules` (legacy) file in your project root is still supported but **will be deprecated**. We recommend migrating to Project Rules or to `AGENTS.md`.
+
+### .mdc cursor rules
+
+As of 2.2, `.mdc` cursor rules will remain functional however all new rules will now be created as folders in `.cursor/rules`. This is to improve the readability and maintainability of rules.
+
+## FAQ
+
+### Why isn't my rule being applied?
+
+### Can rules reference other rules or files?
+
+### Can I create a rule from chat?
+
+### Do rules impact Cursor Tab or other AI features?
+
+### Do User Rules apply to Inline Edit (Cmd/Ctrl+K)?
+
+No. User Rules are not applied to Inline Edit (Cmd/Ctrl+K). They are only
+used by Agent (Chat).

data/reference/steering_docs.md

@@ -0,0 +1,57 @@
+# Steering Docs
+
+**Steering docs** are files and configurations that direct an AI agent's behavior, capabilities, and workflows. They act as the "operating system" for the agent, defining what it can do, how it should act, and what rules it must follow.
+
+## Claude Code Supported Types
+
+Claude Code uses a plugin-based architecture where steering docs are organized into specific directories within a plugin or project structure.
+
+1.  **Commands** (`commands/*.md`)
+    *   **Definition:** Custom slash commands (e.g., `/deploy`) invoked by the user.
+    *   **Format:** Markdown files with frontmatter describing the command's intent and logic.
+
+2.  **Agents** (`agents/*.md`)
+    *   **Definition:** Specialized sub-personas (e.g., "Security Reviewer") that Claude can invoke automatically or users can call manually.
+    *   **Format:** Markdown files defining the agent's capabilities and prompt instructions.
+
+3.  **Skills** (`skills/*/SKILL.md`)
+    *   **Definition:** Discrete capabilities (e.g., "PDF Reader", "API Client") that Claude figures out how to use autonomously.
+    *   **Format:** Directories containing a `SKILL.md` file and optional supporting scripts.
+
+4.  **Hooks** (`hooks/hooks.json`)
+    *   **Definition:** Event handlers that trigger scripts based on system lifecycle events (e.g., `PostToolUse`, `SessionStart`).
+    *   **Format:** JSON configuration mapping events to scripts.
+
+5.  **MCP Servers** (`.mcp.json`)
+    *   **Definition:** Connections to external tools, databases, and APIs via the Model Context Protocol.
+    *   **Format:** JSON file configuring local servers (environment variables, command arguments).
+
+## Cursor Supported Types
+
+Cursor uses a file-based configuration system, typically stored in a `.cursor/` directory at the project root.
+
+1.  **Rules** (`.cursor/rules/*.md`)
+    *   **Definition:** Persistent, context-aware instructions injected into the agent's prompt.
+    *   **Application:** Can be applied always (`alwaysApply: true`), intelligently based on description, to specific files (globs), or manually via `@mention`.
+
+2.  **Commands** (`.cursor/commands/*.md`)
+    *   **Definition:** User-triggered workflows (e.g., `/onboard`) defined as standardized prompts.
+    *   **Role:** Replaces the deprecated "Custom Modes" feature.
+
+3.  **Hooks** (`.cursor/hooks.json`)
+    *   **Definition:** Scripts that run before or after agent/IDE actions (e.g., `beforeShellExecution`, `afterFileEdit`).
+    *   **Scope:** Supports distinct events for both the Agent (Cmd+K) and Tab (inline autocomplete).
+
+4.  **Modes** (Built-in)
+    *   **Definition:** High-level operational states: **Agent** (coding), **Ask** (read-only), **Plan** (architecture), and **Debug** (diagnosis).
+    *   **Note:** Custom modes are deprecated in favor of Commands.
+
+## Feature Mapping: Claude Code vs. Cursor
+
+| Claude Code Type | Cursor Equivalent | Justification | Caveats | Caruso Implementation |
+| :--- | :--- | :--- | :--- | :--- |
+| **Commands** | **Commands** | Both are user-triggered workflows invoked via `/` (e.g., `/test`). | Cursor Commands are simple markdown prompts; Claude Code Commands can be more complex plugins with executable code. | **Simplification:** Strip executable logic where possible, or convert complex commands into a Rule + Script combo if execution is required. |
+| **Agents** | **Rules** (partial) | Cursor Rules can define persona/behavior, which is similar to an Agent identity. | Cursor "Rules" are context injections, not autonomous loops. Claude Agents are distinct sub-personas that can have their own loops and tools. | **Sync Persona:** Extract agent prompt/identity into `.cursor/rules/agent_[name].mdc`. **Sub-agents:** Use [Cursor CLI](https://cursor.com/cli) to spawn independent agent sessions. |
+| **Skills** | **Rules** | Both are "model-invoked" capabilities. Cursor's "Apply Intelligently" mirrors Claude's autonomous skill selection. | **Pros:** Markdown-based, semantic alignment (teaching the agent). **Cons:** Cursor Rules are text context; they don't natively "bundle" executable scripts like a Plugin/Skill structure might. | **Script Bundling:** Fetch `scripts/` from the Skill directory, make them executable, and rewrite the Rule to reference these local scripts. |
+| **Hooks** | **Hooks** | Both intercept lifecycle events to run scripts (e.g., pre-command, post-edit). | Event names differ (e.g., `PostToolUse` vs `afterShellExecution`). Cursor distinguishes between "Main Agent" and "Tab" events. | **Event Translation:** Parse Claude's `hooks.json`, map events (e.g., `PostToolUse` -> `afterFileEdit`), and generate a valid `.cursor/hooks.json`. |
+| **MCP Servers** | **MCP Servers** | Direct 1:1 mapping. Both use the Model Context Protocol to connect to external tools. | Configuration syntax might differ slightly (e.g., `.mcp.json` vs Cursor settings), but the protocol is identical. | **Config Adapter:** specific MCP config from `.mcp.json` could be converted to a Cursor-compatible configuration or appended to a global MCP config file. |

data/tasks.md

@@ -0,0 +1,22 @@
+# Implementation Tasks: Skill Support Refactor
+
+## Phase 1: Foundation (Refactor)
+- [x] Create `lib/caruso/adapters/base.rb` (Base class for shared logic)
+- [x] Create `lib/caruso/adapters/dispatcher.rb` (Dispatcher to select adapter based on type)
+- [x] Refactor `lib/caruso/adapter.rb` to use the Dispatcher
+- [x] Update `lib/caruso/cli.rb` to use the new Adapter architecture (Implicit)
+
+## Phase 2: Skills Support
+- [x] Update `lib/caruso/fetcher.rb` to support `skills/` directory recursion
+- [x] Implement `check_resource_types` in Fetcher (Logic integrated in `find_steering_files`)
+- [x] Create `lib/caruso/adapters/skill_adapter.rb`
+- [x] Implement script copying to `.cursor/scripts/caruso/...`
+- [x] Implement rule generation (`SKILL.md` -> `.cursor/rules/...`)
+- [x] Add header/frontmatter to rule pointing to script location
+- [x] Create unit tests for `SkillAdapter` & `Fetcher`
+- [x] Verify implementation with tests
+- [x] Refactor `Dispatcher` logic for robust skill clustering <!-- id: 11 -->
+- [x] Refactor `SkillAdapter` to preserve script directory structure <!-- id: 12 -->
+
+
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: caruso
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.7.0
 platform: ruby
 authors:
 - Philipp Comans
@@ -143,8 +143,15 @@ files:
 - bin/caruso
 - caruso.gemspec
 - caruso.json
+- impl.md
 - lib/caruso.rb
 - lib/caruso/adapter.rb
+- lib/caruso/adapters/base.rb
+- lib/caruso/adapters/command_adapter.rb
+- lib/caruso/adapters/dispatcher.rb
+- lib/caruso/adapters/hook_adapter.rb
+- lib/caruso/adapters/markdown_adapter.rb
+- lib/caruso/adapters/skill_adapter.rb
 - lib/caruso/cli.rb
 - lib/caruso/config_manager.rb
 - lib/caruso/fetcher.rb
@@ -154,9 +161,19 @@ files:
 - lib/caruso/safe_dir.rb
 - lib/caruso/safe_file.rb
 - lib/caruso/version.rb
-- reference/marketplace.md
+- package-lock.json
+- reference/claude_code_create_marketplaces.md
+- reference/claude_code_hooks.md
+- reference/claude_code_marketplaces.md
+- reference/claude_code_plugins.md
+- reference/claude_code_slash_commands.md
+- reference/cursor_commands.md
+- reference/cursor_hooks.md
+- reference/cursor_modes.md
+- reference/cursor_rules.md
 - reference/plugins.md
-- reference/plugins_reference.md
+- reference/steering_docs.md
+- tasks.md
 homepage: https://github.com/pcomans/caruso
 licenses:
 - MIT