File Format

A POLICY.md file is Markdown with YAML frontmatter. The frontmatter contains machine-enforceable rules; the Markdown body contains human-readable policy sections.

Frontmatter top-level fields

Field	Required	Type	Description
name	yes	string	Unique policy identifier, kebab-case or snake_case.
description	no	string	Human-readable summary.
version	no	string	Semantic version or opaque policy version.
scope	no	string	One of project, skill, agent, department. Default: project.
appliesTo	no	string[]	Agent or skill ids this policy applies to. ["all"] means every agent. Default: ["all"].
severity	no	string	One of block, warn, require_approval. Default: block.
rules	no	Rule[]	Machine-enforceable rules.

Rule fields

Field	Required	Type	Description
id	no	string	Stable rule identifier.
capability	yes	string	Capability pattern, e.g. file.write, payment.*, *.
action	yes	string	allow, deny, or require_approval.
condition	no	Condition	When the rule applies. Omit to match every intent.
reason	no	string	Explanation returned to the agent/runtime.
priority	no	number	Higher number wins ties. Default: 0.
description	no	string	Human-readable rule note.

Capability patterns

• Exact: file.write matches file.write.
• Single-segment wildcard: payment.* matches payment.send, payment.refund, etc.
• Global wildcard: * matches every capability.

Conditions

A condition is exactly one of a field test, an and group, or an or group:

condition:
  field: { path: payload.path, op: includes, value: .env }

condition:
  and:
    - field: { path: payload.amount, op: gt, value: 1000 }
    - field: { path: constraints.environment, op: eq, value: production }

condition:
  or:
    - field: { path: workerId, op: eq, value: payment-bot }
    - field: { path: specialist, op: in, values: [frontend, backend] }

Operators

eq, neq, gt, gte, lt, lte, includes, in, notIn, exists, notExists, wildcard.

Special condition paths

Conditions can reference any field the runtime provides:

• payload.<key> - the action payload
• constraints.<key> - execution constraints
• requester.<key> - who is asking
• built-ins: risk, actionType, actionClass, reversibility, capability, specialist, workerId, toolName, connectorId

Markdown body

The body is free-form Markdown for humans and LLMs. The conventional sections are:

## Forbidden
- Never commit `.env` files or any file containing secrets

## Ask first
- Adding npm dependencies
- Modifying CI/CD pipelines

## Allowed
- Running `npm run typecheck` and `npm run test`

File discovery

POLICY.md files are discovered in conventional locations:

repo-root/
  POLICY.md              # project-wide policy
  .policies/
    payment/
      POLICY.md          # named policy directory
    infra/
      POLICY.md
  .devin/skills/
    ui-polish/
      SKILL.md
      POLICY.md          # negative boundaries for one skill

Scopes stack: a skill policy can be stricter than its project policy; the runtime combines them with the most severe decision winning (deny > require_approval > allow).