rulespec

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

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.

Quick start

npx rulespec init --domain "customer support"
# → skills/customer-support/rulespec.yaml

npx rulespec add --id refund-policy \
  --rule "Refunds allowed within 30 days for unused items" \
  --context "Customer asks about returns" \
  --intent enforce

npx rulespec add --id escalation \
  --rule "Escalate to human after 2 failed attempts" \
  --context "Automated support cannot resolve" \
  --intent enforce

npx rulespec emit
# → skills/customer-support/SKILL.md

Each domain lives in its own skill folder — the authored rulespec.yaml source and the emitted SKILL.md sit side by side, so the folder is a self-contained, agent-loadable skill.

No global install needed — npx downloads and runs it automatically.

Target a specific agent

Pass -a <agent> once at init and the skill folder lands where that agent looks. Every later command (add, edit, emit, …) auto-discovers it — no need to repeat the flag:

# Project-scoped — committed with your repo
npx rulespec init --domain "customer support" -a claude-code
# → .claude/skills/customer-support/

# User-global — shared across all your projects
npx rulespec init --domain "customer support" -a claude-code -g
# → ~/.claude/skills/customer-support/

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

You can also override the destination per-emit:

npx rulespec emit -a cursor    # write SKILL.md to .agents/skills/<domain>/ instead

Install as an agent skill

# All agents globally
npx skills add pallaoro/rulespec -g -y

# Claude Code only
npx skills add pallaoro/rulespec -g -a claude-code -y

# OpenClaw (via ClawHub)
openclaw skills install rulespec

This installs the rulespec skill into your agent so it knows how to use the CLI when you ask it to create or manage business rules.

How it works

A rulespec file is deliberately simple. Business rules are data, not prose buried in a system prompt:

# skills/invoice-processing/rulespec.yaml
schema: rulespec/v1
domain: "invoice processing"

sources:
  - id: invoice
    type: document
    format: pdf
    description: "Incoming vendor invoice"
    schema:
      number: string
      vendor: string
      amount: number
      currency: string

  - id: erp-api
    type: api
    format: json
    description: "ERP vendor lookup"

rules:
  - id: duplicate-check
    rule: "Reject invoices with duplicate invoice numbers"
    context: "Before processing any invoice"
    intent: enforce

  - id: approval-threshold
    rule: "Invoices over $5000 require manager approval"
    context: "After extraction, before posting"
    intent: enforce

  - id: greeting
    rule: "Address the submitter by first name in confirmation messages"
    context: "After processing decision"
    intent: inform

examples:
  - note: "Foreign currency invoice requiring approval"
    input:
      invoice: { number: "INV-1001", vendor: "Acme GmbH", amount: 7200, currency: "EUR" }
    output:
      action: "require-approval"
      approver: "finance-mgr"

  - note: "Duplicate invoice rejection"
    input:
      invoice: { number: "INV-0999", vendor: "Local Supply" }
      existing_invoices: ["INV-0999"]
    output:
      action: "reject"
      reason: "duplicate"

  - note: "PDF invoice extraction"
    input:
      file: "./samples/invoice-1003.pdf"
    output:
      action: "auto-approve"
      vendor: "Office Depot"
      amount: 135

Fields

Rules have four fields:

| Field | Owner | Purpose | |-------|-------|---------| | id | Engineer | Unique identifier (kebab-case) | | rule | Business person | The business rule in plain language | | context | Shared | When this rule applies | | intent | Business person | enforce, inform, or suggest |

Intent shapes the compiled output:

• enforce — mandatory. Compiles to **You must follow this rule.**
• inform — guidance. Neutral language.
• suggest — recommendation. Compiles to Consider the following:

Sources (optional) describe what data the rules operate on — type, format, schema.

Examples (optional) are input/output golden standards for evaluation. They exist at two levels:

• Global examples — end-to-end test cases across all rules
• Per-rule examples — scoped to a single rule

CLI commands

Setup

rulespec init --domain "invoice processing"
rulespec set-domain "customer support"

Rules

rulespec add --id <id> --rule <text> --context <text> --intent <enforce|inform|suggest>
rulespec edit <id> [--rule <text>] [--context <text>] [--intent <type>]
rulespec remove <id>
rulespec list

Sources

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

Examples

# Global examples
rulespec add-example --input '{"amount": 100}' --output '{"action": "approve"}' --note "Small amount"
rulespec add-example --input /path/to/input.json --output /path/to/expected.json
rulespec add-example --input /path/to/invoice.pdf --output '{"vendor": "Acme", "total": 500}'
rulespec remove-example <index>

# Rule-specific examples
rulespec add-rule-example <rule-id> --input '{"days": 5}' --output '{"refund": true}'
rulespec add-rule-example <rule-id> --input /path/to/document.pdf --output '{"extracted": "data"}'
rulespec remove-rule-example <rule-id> <index>

Input/output accepts three formats:

• Inline JSON — '{"key": "val"}'
• JSON file — /path/to/data.json (read and parsed)
• Any file — /path/to/doc.pdf (stored as { file: "/path/to/doc.pdf" })

Find & replace

rulespec replace --old "30 days" --new "60 days"

Safe find-and-replace: validates the result and recompiles all prompts automatically.

Build & emit

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 directory (default: skills)

All commands accept --file <path>. When omitted, rulespec auto-detects skills/*/rulespec.yaml.

Output

Each domain is a self-contained skill folder — authored source and emitted output live together. The folder lives wherever the target agent looks (or under skills/ by default):

skills/                       ← default, no agent specified
  invoice-processing/
    rulespec.yaml   ← authored source
    SKILL.md        ← emitted (agent-loadable)

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

The emitted SKILL.md uses YAML frontmatter for agent discovery and intent tags ([enforce], [inform], [suggest]) that tell the agent how strictly to follow each rule:

---
name: invoice-processing
description: Business rules for invoice processing. 3 rules: Duplicate Check, Approval Threshold, Greeting.
type: rules
schema: rulespec/v1
# Auto-generated by rulespec. Do not edit — changes will be overwritten on next emit.
---

## Rules

### Duplicate Check [enforce]
**You must follow this rule.** Before processing any invoice: Reject invoices with duplicate invoice numbers.

### Approval Threshold [enforce]
**You must follow this rule.** After extraction, before posting: Invoices over $5000 require manager approval.

### Greeting [inform]
After processing decision: Address the submitter by first name in confirmation messages.

Programmatic usage

Use rulespec as a library to inject rules into LLM prompts at runtime:

import { loadRules } from "rulespec";

// Load and compile rules into a markdown string
const rules = await loadRules("skills/customer-support/rulespec.yaml");

// Inject into your LLM call
const response = await llm.chat({
  system: `You are a support agent.\n\n${rules}`,
  message: userMessage,
});

loadRules() reads the rulespec file and returns the compiled markdown — ready to inject into any system prompt, API call, or workflow step.

npm install rulespec

Design choices

• Format first, tooling second. The YAML file is the product. The CLI is convenience.
• One rule, one change. Editing a rule only affects that rule's compiled prompt. No cascading rewrites.
• Intent shapes output. Same rule, different prompt weight — controlled by one field.
• Business people own rules, engineers own strategy. Rules are plain language. Compilation is where prompt engineering lives.
• Sources describe, examples prove. Together they form a complete, evaluable specification.
• Schema up, data stays down. The spec (rules + source schemas) is safe to share. Examples contain real data and are excluded from output by default.

Why not just edit prompts directly?

You can. It works until:

• A policy changes and you update 3 of 7 places it appears
• Two teams edit the same system prompt and one overwrites the other
• You can't tell which rule a paragraph of prompt corresponds to
• You want to A/B test one rule change without risking the rest
• An auditor asks "where is the refund policy enforced in our AI?"

rulespec makes rules traceable, diffable, and independently versionable. git blame shows who changed a rule and when. Examples prove the rules work.

Tech Stack

| Layer | Technology | |-------|-----------| | Runtime | Node.js, TypeScript | | Format | YAML (rulespec/v1 schema) | | Output | Markdown (SKILL.md with YAML frontmatter) | | Dependencies | yaml (single runtime dep) | | AI generation | Optional — AI SDK peer dep for LLM-assisted prompt compilation |

License

MIT

Built by the team behind Clawnify.