Skip to main content
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

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

FieldTypeRequiredDescription
idstringYesUnique identifier (kebab-case)
severityenumNoerror | warning | info (default: error)
contentstringYesThe rule in natural language (multiline YAML)
tagsstring[]NoTags for filtering
enabledbooleanNoDefault: 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:
ScopePurpose
architectureProject structure, patterns, module organization
conventionsNaming, formatting, code style
securityAuth, RLS, secrets, input validation
testingTest strategy, naming, coverage
workflowGit, CI/CD, PR process, deployment

​
Custom Scopes

Beyond the five built-in scopes, you can define your own using the kind:name pattern: 
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: 
# .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.