Creating Rules

Write rules agents can actually find

Rule Creation Guide

Rules encode what an agent must or must not do. They are indexed and discoverable the same way skills are — but unlike a skill, a rule is rarely invoked by name. An agent reaches a rule by asking a question ("am I allowed to delete this?"), so a rule that declares no trigger phrases is effectively unreachable by the discovery protocol that is supposed to surface it.

Declare activation explicitly

Every shipped rule requires `activation:` frontmatter. Choose `core` for a compact universal body, `kernel` for an always-on contract, `summary` for an always-on fetch obligation, `bound` for named artifact invocations, `paths` for file scopes, or `on-demand` for guidance fetched when needed. Summary, bound, and path rules also require an authored `summary`.

Deployment warns about legacy rules without activation and treats them as on demand regardless of enforcement. Lint rejects missing activation in shipped `agentic/code/` rules. Enforcement severity does not select delivery.

`aiwg use all` delivers kernel skills, selected kernel/core rules, and the rule index. Rule membership comes from installed bundles and required dependencies; provider adapters change how that set is presented. Agent and skill definitions link to their section in `<provider>/RULES-BOUND.md`. This index contains only the selected deployment’s bindings and fetch commands for the full contracts. Follow that section before governed work.

Rules support `triggers`

`rule` is in `OPERATIONAL_DISCOVERY_TYPES`, so the indexer runs the same trigger extraction over rule bodies that it runs over skills (`src/artifacts/index-builder.ts`). Declare triggers in frontmatter:

---
enforcement: high
activation: summary
summary: Verify authorization before governed actions.
triggers:
  - "am I allowed to do this"
  - "do I need permission for this"
  - "can I delete this"
---

# Human Authorization Rules

A `## Triggers` section works too (also `## Natural Language Triggers`, `## Activation Phrases`, `## When to invoke`), but frontmatter is preferred for rules: it keeps the rendered body focused on the rule itself.

Why this matters more for rules than for skills

Discovery ranking weights trigger matches heavily. A skill usually also has a distinctive name an agent might guess (`flow-deploy-to-production`); a rule's name describes the policy, not the question — nobody queries "delivery-policy", they query "should I open a pull request". Without triggers a rule only ranks on lexical overlap with its title and summary, and loses to any skill whose triggers happen to cover a token.

Measured before and after adding triggers to `respect-repo-access-manifest`:

before: aiwg discover "register a repo in the workspace manifest"
  1. Status (aiwg-status)  skill  1.00      <- wrong answer
  (the rule does not appear)

after:
  1. Respect Repo Access Manifest  rule  1.00
     ranking: trigger covers 100% of query tokens

No indexer change was needed. The capability existed; the rule had not declared any.

Writing triggers an agent will actually type

Write the question the agent is asking, not the rule's subject.

Instead ofWrite
`"human authorization"``"am I allowed to do this"`, `"do I need permission for this"`
`"token security"``"where do I put an api key"`, `"load a secret in a script"`
`"anti-laziness"``"can I skip this test"`, `"should I delete this test"`
`"delivery policy"``"should I open a pull request"`, `"can I commit to main"`

Guidance:

  • 3–6 phrases is usually enough. More dilutes rather than helps.
  • Phrase them as an agent mid-task would, first person, in the moment of doubt.
  • Avoid single generic words. A one-word trigger like `persona` matches far too

much; the scorer already downweights some of these specifically.

  • Do not restate the title. Title and summary are already indexed.

Checking coverage

npm run lint:rule-triggers          # report rules with no trigger phrases
npm run lint:rule-triggers -- --json

The lint reports rather than fails, so coverage can close incrementally. Run it after adding a rule, and verify the rule is actually reachable:

aiwg index build --graph framework --force    # at the install root
aiwg index sync --backend fortemi-core --graph framework
aiwg discover "<the question your rule answers>"

The build step only works at the install root — the framework graph indexes the AIWG corpus, which does not exist in a consumer project.

Core rules (`activation: core`)

A core rule is injected into every harness's always-loaded surface in every deploy mode. Reserve it for non-negotiable behavior; the budget is deliberately small.

  • Put the rule in the always-installed `aiwg-utils` addon, set `activation: core`,

and omit `bound_to` (a core rule already reaches every agent).

  • Write the compact normative text in `<name>.core.md` beside the rule: plain

markdown, no frontmatter, at most 1024 bytes, all core bodies together at most 6144 bytes. Deploy and `aiwg lint --ruleset rule-activation` fail above either cap.

  • End the body with a plain pointer, `aiwg show rule <name>`. Never use an `@`

import of the full rule; deploy rejects `@` file references in core bodies.