|
| 1 | +--- |
| 2 | +name: add-rule-or-skill |
| 3 | +description: Standardize adding/updating rules & commands/skills in this repo (scoping, dedupe, naming, DRY symlink structure) |
| 4 | +usage: /add-rule-or-skill |
| 5 | +--- |
| 6 | + |
| 7 | +# Rule & Command Authoring (LI.FI Contracts) |
| 8 | + |
| 9 | +> **Usage**: `/add-rule-or-skill` |
| 10 | +
|
| 11 | +This command is the single workflow for adding/updating **rules** and **commands/skills** in this repo. |
| 12 | + |
| 13 | +## Repo Structure (DRY Symlink Setup) |
| 14 | + |
| 15 | +Rules and commands have a single source of truth. Never edit the symlink targets directly. |
| 16 | + |
| 17 | +``` |
| 18 | +.agents/rules/*.md ← SOURCE OF TRUTH for rules (edit here) |
| 19 | + ↑ symlinked from: |
| 20 | + .cursor/rules/*.mdc ← Cursor reads these (link name keeps .mdc; target is .md) |
| 21 | + .claude/rules/*.md ← Claude Code reads these |
| 22 | +
|
| 23 | +.agents/commands/*.md ← SOURCE OF TRUTH for commands (edit here) |
| 24 | + ↑ symlinked from: |
| 25 | + .cursor/commands/*.md ← Cursor reads these |
| 26 | + .claude/skills/<name>/SKILL.md ← Claude Code skill bridge |
| 27 | +``` |
| 28 | + |
| 29 | +When you add or edit a rule, **always work in `.agents/rules/`**. |
| 30 | +When you add or edit a command, **always work in `.agents/commands/`**. |
| 31 | + |
| 32 | +## Hybrid Frontmatter (both tools, one file) |
| 33 | + |
| 34 | +Every rule must use the hybrid header so both Cursor and Claude Code activate it correctly. |
| 35 | + |
| 36 | +**Scoped rule** (activates only for matching files): |
| 37 | +```yaml |
| 38 | +--- |
| 39 | +name: Rule name |
| 40 | +description: One-sentence description |
| 41 | +globs: # Cursor: file matching |
| 42 | + - 'src/**/*.sol' |
| 43 | +paths: # Claude Code: file matching (no negation patterns) |
| 44 | + - 'src/**/*.sol' |
| 45 | +--- |
| 46 | +``` |
| 47 | + |
| 48 | +**Global rule** (always active, no file scoping): |
| 49 | +```yaml |
| 50 | +--- |
| 51 | +name: Rule name |
| 52 | +description: One-sentence description |
| 53 | +globs: # Cursor: match all files |
| 54 | + - '**/*' |
| 55 | +alwaysApply: true # Cursor: force-load |
| 56 | + # Claude Code: omit paths: entirely = always loaded |
| 57 | +--- |
| 58 | +``` |
| 59 | + |
| 60 | +Rules: Cursor ignores `paths:`. Claude Code ignores `alwaysApply:` and `globs:`. Both ignore unknown keys. |
| 61 | + |
| 62 | +Negation patterns (`!src/**/*.s.sol`) are supported in `globs:` (Cursor) but **not** in `paths:` (Claude Code) — omit them from `paths:`. |
| 63 | + |
| 64 | +## Scoping & Activation (globs-first) |
| 65 | + |
| 66 | +- Prefer **precise `globs`** over cross-references. |
| 67 | +- Use `alwaysApply: true` (+ omit `paths:`) only for truly universal rules (role/guardrails, architecture, project structure, context monitoring, final checks). |
| 68 | +- Avoid `globs: ['**/*']` unless the rule is an explicit **activation gate** (like tx analysis) or truly universal. |
| 69 | +- Prefer directory scoping by concern: |
| 70 | + - Solidity: `**/*.sol`, narrower `src/**`, `src/Facets/**`, `src/Interfaces/**`, `src/Periphery/Receiver*.sol`, `script/**/*.s.sol`, `test/**/*.t.sol` |
| 71 | + - TypeScript: `script/**/*.ts`, `tasks/**/*.ts` |
| 72 | + - Bash: `**/*.sh` |
| 73 | + - GitHub Actions: `.github/workflows/**/*.yml` / `**/*.yaml` |
| 74 | + - Audits: `audit/**/*.json`, `audit/**/*.pdf` |
| 75 | + |
| 76 | +## No-Duplication, Naming, Size, Cross-References |
| 77 | + |
| 78 | +These constraints are enforced automatically via `010-agents-authoring` (auto-loaded when editing `.agents/` files). See that rule for the full list. Key reminders: |
| 79 | +- Search before adding — pick a single owning file, remove duplicates. |
| 80 | +- Rules define "what/why", not "how"; report CI/tooling suggestions separately. |
| 81 | +- Follow `.agents/README.md` for numbering ranges. |
| 82 | + |
| 83 | +## Adding a New Rule (step by step) |
| 84 | + |
| 85 | +1. Determine scope → pick numbering range from `.agents/README.md`. |
| 86 | +2. Create `.agents/rules/<NNN>-<name>.md` with hybrid frontmatter. |
| 87 | +3. Create the Cursor and Claude Code symlinks: |
| 88 | + ```bash |
| 89 | + ln -sf "../../.agents/rules/<NNN>-<name>.md" ".cursor/rules/<NNN>-<name>.mdc" |
| 90 | + ln -sf "../../.agents/rules/<NNN>-<name>.md" ".claude/rules/<NNN>-<name>.md" |
| 91 | + ``` |
| 92 | +4. Update `.agents/README.md` table (name, range, description). |
| 93 | +5. Run validation steps below. |
| 94 | + |
| 95 | +## Adding a New Command/Skill (step by step) |
| 96 | + |
| 97 | +1. Run `/skill-creator` (Anthropic built-in) to draft the skill content — it enforces ≤500 lines, progressive disclosure, and other best practices automatically. |
| 98 | +2. Save the output to `.agents/commands/<name>.md`. |
| 99 | +3. Create the Cursor and Claude Code symlinks: |
| 100 | + ```bash |
| 101 | + ln -sf "../../.agents/commands/<name>.md" ".cursor/commands/<name>.md" |
| 102 | + mkdir -p ".claude/skills/<name>" |
| 103 | + ln -sf "../../../.agents/commands/<name>.md" ".claude/skills/<name>/SKILL.md" |
| 104 | + ``` |
| 105 | +4. Verify: `ls -l .cursor/commands/<name>.md` and `ls -l .claude/skills/<name>/SKILL.md` should both show symlink arrows into `.agents/commands/`. |
| 106 | + |
| 107 | +## Modifying an Existing Rule or Command |
| 108 | + |
| 109 | +All constraints (no-duplication, size, naming, validation) apply equally on edits. `010-agents-authoring` enforces them automatically — no need to repeat them here. No symlink work is needed unless you renamed the file. |
| 110 | + |
| 111 | +## Helper script exit codes |
| 112 | + |
| 113 | +When a skill shells out to a project script (e.g. via `bunx tsx script/utils/foo.ts`), use this exit-code convention so the orchestrating skill can branch independently per target: |
| 114 | + |
| 115 | +- **`0`** — success. |
| 116 | +- **`1`** — real error (network, API, malformed input). Report stderr to the user and stop. Do **not** retry. Do **not** write a fallback artifact. |
| 117 | +- **`2`** — recoverable misconfig (env var missing, optional credential absent). Fall through to an alternative path (manual fallback file, degraded mode) and tell the user which env var to set. |
| 118 | + |
| 119 | +This split lets the skill process N targets independently — if one channel/network/recipient succeeds and another exits `2`, the skill continues for the survivors and only writes a fallback for the failed one. |
| 120 | + |
| 121 | +## Validation Steps (PR-ready) |
| 122 | + |
| 123 | +- **Symlink integrity**: `ls -l .cursor/rules/*.mdc` and `ls -l .claude/rules/*.md` — all entries should be symlinks (`->`) pointing into `.agents/rules/`. |
| 124 | +- **Skill symlinks**: `ls -l .claude/skills/*/SKILL.md` — all should point into `.agents/commands/`. |
| 125 | +- **README accuracy**: `.agents/README.md` table reflects all files in `.agents/rules/` and all commands in `.agents/commands/`. |
| 126 | +- **Stale references**: grep `.agents/rules/` and `.agents/commands/` for references to removed files. |
| 127 | +- **Activation sanity check**: |
| 128 | + - Editing a facet (`src/Facets/*.sol`) → pulls facet + Solidity baseline + architecture/security. |
| 129 | + - Editing a TS script → pulls TS rule (+ security if applicable). |
| 130 | + - Editing audit files → pulls audit rules. |
| 131 | + |
| 132 | +## Smart-Contract Department Checklist (must not weaken) |
| 133 | + |
| 134 | +- **Rule interaction (required)**: |
| 135 | + - Identify which rules will apply via `globs` for the files you're about to touch. |
| 136 | + - Ensure the new rule does **not** conflict with or overwrite higher-priority/global rules. |
| 137 | + - Ensure there is **no duplicate guidance**: pick a single owning rule/command and delete/trim duplicates elsewhere. |
| 138 | + - Ensure numeric prefixes and `name:` fields stay **unique**. |
| 139 | +- **Diamond architecture**: single diamond entrypoint; keep facets thin; selector/storage invariants respected. |
| 140 | +- **Governance**: Safe + timelock flows never bypassed; no admin shortcuts. |
| 141 | +- **Events**: respect reserved event emission locations; non-EVM receiver rules respected. |
| 142 | +- **Security**: validate inputs/config; avoid new external-call patterns without prior art; reentrancy and approval hygiene; no new privileged paths. |
| 143 | +- **Scripts/tests separation**: deployment/update scripts remain in `script/`; tests mirror `src/` under `test/solidity/`. |
| 144 | +- **Audits**: audit log schema + report naming preserved; CI expectations respected. |
0 commit comments