> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dev-workflows.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rules

> How to write and organize rules in dev-workflows

Rules are the core of dev-workflows. Each rule is a piece of guidance for AI editors, written in natural language and stored in YAML.

## File Structure

Rules live in `.dwf/rules/`, organized by scope:

```
.dwf/rules/
  architecture.yml
  conventions.yml
  security.yml
  testing.yml
  workflow.yml
```

## Rule Format

```yaml theme={null}
scope: conventions

rules:
  - id: named-exports
    severity: error
    content: |
      Always use named exports. Never use default exports.
      This applies to all files: components, utilities, hooks, and types.

  - id: no-barrel-files
    severity: warning
    content: |
      Avoid barrel files (index.ts re-exports).
      Import directly from the source file.
```

## Fields

| Field      | Type      | Required | Description                                       |
| ---------- | --------- | -------- | ------------------------------------------------- |
| `id`       | string    | Yes      | Unique identifier (kebab-case)                    |
| `severity` | enum      | No       | `error` \| `warning` \| `info` (default: `error`) |
| `content`  | string    | Yes      | The rule in natural language (multiline YAML)     |
| `tags`     | string\[] | No       | Tags for filtering                                |
| `enabled`  | boolean   | No       | Default: `true`. Disable without deleting         |

## Severity Behavior

* **error** and **warning** rules are included in compiled output
* **info** rules are internal documentation only — they are omitted from output
* Rules with `enabled: false` are always omitted

## Scopes

The five built-in scopes organize rules by concern:

| Scope          | Purpose                                          |
| -------------- | ------------------------------------------------ |
| `architecture` | Project structure, patterns, module organization |
| `conventions`  | Naming, formatting, code style                   |
| `security`     | Auth, RLS, secrets, input validation             |
| `testing`      | Test strategy, naming, coverage                  |
| `workflow`     | Git, CI/CD, PR process, deployment               |

## Custom Scopes

Beyond the five built-in scopes, you can define your own using the `kind:name` pattern:

```yaml theme={null}
scope: team:payments
scope: agent:reviewer
scope: pipeline:ci
```

Custom scopes follow the same rules as built-in ones. Create a new YAML file in `.dwf/rules/` with your custom scope:

```yaml theme={null}
# .dwf/rules/team-payments.yml
scope: team:payments

rules:
  - id: payments-no-raw-sql
    severity: error
    content: |
      Never write raw SQL in payment flows.
      Always use the PaymentRepository abstraction.
```

Custom scopes appear after built-in scopes in compiled output, sorted alphabetically. The scope name is used as-is for the heading (e.g., `## team:payments`).

**Format:** lowercase alphanumeric, hyphens allowed in name. Examples: `team:frontend`, `agent:reviewer`, `pipeline:ci`.