---
name: pallaoro/rulespec
source: https://app.decimal.ai/s/pallaoro-rulespec@2/SKILL.md
source_sha256: 915f0997a5bc
---

# rulespec

**Manage business rules for AI agents without breaking what already works.**

> **Note for OpenClaw users:** if rulespec is installed as an OpenClaw plugin (`openclaw plugins install rulespec`), prefer the **native tools** (`rulespec_init`, `rulespec_add_rule`, `rulespec_emit`, …) over the CLI — they run in-process with structured params. The plugin variant of this skill at `~/.openclaw/plugin-skills/rulespec/SKILL.md` documents them. The CLI docs below apply to every other context (standalone npm, Claude Code, Cursor, Codex, etc.).

Adding a rule to a system prompt shouldn't risk invalidating the ones that are already there. Inline prompt editing doesn't scale — and other solutions aren't built for business rules.

rulespec treats each rule as an independent, validated unit. Add, edit, or remove one rule via CLI — the rest stay untouched. The output is a structured SKILL.md that any AI agent can load.

**IMPORTANT: Always use the `rulespec` CLI to modify rules, sources, and examples. Never edit emitted SKILL.md files directly — they are generated and will be overwritten.** For complex structures (source schemas, nested example data), you may edit the source `rulespec.yaml` directly, but always run `rulespec validate` afterward.

All commands use `npx rulespec` — no global install needed. npx downloads and runs it automatically.

## Layout

Each domain lives in its own skill folder. By default it lands under `skills/`; with `-a <agent>` it lands in that agent's skills directory instead:

```
skills/                       ← default
  invoice-processing/
    rulespec.yaml   ← authored source
    SKILL.md        ← emitted, agent-loadable (do not edit)

.claude/skills/               ← rulespec init -a claude-code
  customer-support/
    rulespec.yaml
    SKILL.md
```

## CLI commands

### Setup
```bash
rulespec init --domain "invoice processing"                  # → skills/invoice-processing/
rulespec init --domain "invoice processing" -a claude-code   # → .claude/skills/invoice-processing/
rulespec init --domain "invoice processing" -a claude-code -g # → ~/.claude/skills/invoice-processing/
rulespec set-domain "customer support"                       # Change the domain
```

Supported agents for `-a`: `claude-code`, `cursor`, `openclaw`, `codex`, `opencode`, `windsurf`, `amp`, `augment`, `gemini-cli`, `github-copilot`. Anywhere else: pass `--outdir <path>`.

Once set at init, every other command auto-discovers the source — no need to repeat `-a`.

### Rules
```bash
rulespec add --id <id> --rule <text> --context <text> --intent <enforce|inform|suggest>
rulespec edit <id> --rule <new text>           # Update rule text
rulespec edit <id> --intent enforce            # Change intent level
rulespec edit <id> --context "new context"     # Change when rule applies
rulespec remove <id>                           # Remove a rule
rulespec list                                  # List all rules
```

### Sources
```bash
rulespec add-source --id <id> --type <document|api|database|message|structured> --description <text> [--format <fmt>]
rulespec remove-source <id>
```

### Global examples (end-to-end input/output pairs)
```bash
rulespec add-example --input '{"key": "val"}' --output '{"key": "val"}' [--note <text>]
rulespec add-example --input /path/to/input.json --output /path/to/output.json --note "From files"
rulespec add-example --input /path/to/invoice.pdf --output '{"action": "approve"}' --note "PDF input"
rulespec remove-example <index>                # 0-based index
```

### Rule-specific examples
```bash
rulespec add-rule-example <rule-id> --input '{"amount": 100}' --output '{"approved": true}'
rulespec add-rule-example <rule-id> --input /path/to/file.pdf --output '{"extracted": "data"}'
rulespec remove-rule-example <rule-id> <index> # 0-based index
```

### Input/output resolution

Both `--input` and `--output` accept three formats:
- **Inline JSON**: `'{"key": "val"}'` — parsed directly
- **JSON file path**: `/path/to/data.json` — file is read and parsed
- **Any other file path**: `/path/to/doc.pdf` — stored as `{ file: "/path/to/doc.pdf" }`

### Find & replace
```bash
rulespec replace --old "30 days" --new "60 days"   # Validates + recompiles automatically
```

### Build & emit
```bash
rulespec compile [id]                          # Preview compiled prompts
rulespec validate                              # Check file against schema
rulespec emit                                  # Generate skills/{domain}/SKILL.md
rulespec emit --include-examples true          # Include examples in output
rulespec emit --outdir <path>                  # Custom output dir (default: skills)
```

All commands accept `--file <path>` to specify a different file (auto-detected from `skills/*/rulespec.yaml`).

## File format

```yaml
schema: rulespec/v1
domain: "your domain here"

sources:                              # optional — what data the rules operate on
  - id: source-name
    type: document | api | database | message | structured
    format: pdf | json | csv          # optional
    description: "What this source is"
    schema:                           # optional — shape of the data
      field: type

rules:
  - id: rule-id                       # kebab-case, unique
    rule: "The business rule in plain language"
    context: "When this rule applies"
    intent: enforce | inform | suggest

examples:                             # optional — end-to-end golden standards
  - note: "What this example tests"
    input: { ... }
    output: { ... }
```

### Intent levels

- `enforce` — mandatory. Agent must follow this rule. Compiles to directive language.
- `inform` — guidance. Agent should be aware. Compiles to neutral language.
- `suggest` — recommendation. Agent may consider. Compiles to soft language.

## Workflow

1. `rulespec init --domain "my domain"` scaffolds `skills/{domain}/rulespec.yaml`
2. Add sources with `rulespec add-source`
3. Add rules with `rulespec add`
4. Add examples with `rulespec add-example`
5. `rulespec validate` to check for errors
6. `rulespec compile` to preview compiled prompts
7. `rulespec emit` to generate `skills/{domain}/SKILL.md` next to the source

## Programmatic usage

To inject rules into LLM prompts at runtime:

```typescript
import { loadRules } from "rulespec";
const rules = await loadRules("skills/my-domain/rulespec.yaml");
// rules is a compiled markdown string — inject into any system prompt or API call
```

## Key principles

- Use the CLI for rules, sources, and examples — never edit emitted SKILL.md files
- For complex source schemas or nested example data, edit the source `rulespec.yaml` directly + run `rulespec validate`
- `rulespec replace` is a safe find-and-replace: validates and recompiles after every change
- One rule, one change — editing a rule only affects that rule's compiled output
- Examples are excluded from emitted SKILL.md by default (they may contain sensitive data)

Built by the team behind [Clawnify](https://www.clawnify.com).