SPECWRIGHT.yaml Reference | Specwright
Description: AI-native enterprise documentation platform. Living specs, agent-maintained docs, repo-native knowledge.

Skip to content

# SPECWRIGHT.yaml Reference ​

The `SPECWRIGHT.yaml` file configures Specwright behavior for a repository. Place it in the repository root.

## Schema ​

yaml

    # Required
    version: "1"

    # Optional: team metadata
    team: string              # Team name
    ticket_system: string     # Default ticket system (jira, linear, github)
    project_key: string       # Default project key
    slack_channel: string     # Slack channel for notifications

    # Spec configuration
    specs:
      doc_paths: string[]     # Glob patterns for files to index
      auto_tickets: boolean   # Auto-create tickets from spec sections
      require_review: boolean # Require review before ticket creation

    # Agent behavior
    agents:
      pr_analysis: boolean    # Enable PR analysis comments
      doc_updates: boolean    # Enable doc update suggestions
      stale_detection: string | false  # Duration or false
      realization_check: boolean       # Enable AC realization tracking

    # Simple ticket sync
    sync:
      system: string          # jira, linear, or github
      project_key: string     # Project key for ticket creation
      create_tickets: boolean # Auto-create tickets
      reverse_sync: boolean   # Sync ticket status back to specs

    # Advanced: multi-system ticket routing
    ticket_systems:
      <name>:
        system: string        # jira, linear, or github
        project: string       # Project key
        status_map:           # Spec status → ticket status mapping
          draft: string
          todo: string
          in_progress: string
          done: string
          blocked: string
          deprecated: string
        hierarchy:            # Section depth → issue type mapping
          2: string           # e.g., "Epic"
          3: string           # e.g., "Story"
          4: string           # e.g., "Sub-task"
        auto_parent: boolean  # Auto-link child tickets to parent

    routing:
      - match:
          tags: string[]      # Match on spec tags
          team: string        # Match on team
          default: boolean    # Default route
        target: string        # ticket_systems key

## Fields ​

### `version` ​

Required. Schema version. Currently only `"1"` is supported.

### `team` ​

Team name used for ticket routing and dashboards.

### `ticket_system` ​

Default ticket system. One of: `jira`, `linear`, `github`.

### `project_key` ​

Default project key for ticket creation (Jira project key, Linear team key, or GitHub `owner/repo`).

### `slack_channel` ​

Slack channel for notifications (e.g., `"#payments-eng"`).

### `specs` ​

#### `specs.doc_paths` ​

Type: `string[]`Default: `["docs/specs/*.md"]`

Glob patterns for files to index. All matched files become part of the agent's knowledge base.

yaml

    specs:
      doc_paths:
        - "docs/specs/*.md"
        - "docs/**/*.md"
        - "README.md"
        - "CHANGELOG.md"

#### `specs.auto_tickets` ​

Type: `boolean`Default: `false`

When `true`, the agent automatically creates tickets from spec sections.

#### `specs.require_review` ​

Type: `boolean`Default: `true`

When `true`, auto-created tickets require review before creation.

### `agents` ​

#### `agents.pr_analysis` ​

Type: `boolean`Default: `true`

Enable PR analysis comments. Set to `false` to disable the bot commenting on PRs.

#### `agents.doc_updates` ​

Type: `boolean`Default: `true`

Enable doc update suggestions in PR comments.

#### `agents.stale_detection` ​

Type: `string | false`Default: `"30d"`

Duration string (e.g., `"30d"`, `"7d"`) before flagging stale sections, or `false` to disable.

#### `agents.realization_check` ​

Type: `boolean`Default: `true`

Enable acceptance criteria realization tracking in PR analysis.

### `sync` ​

Simple ticket sync configuration. For multi-system routing, use `ticket_systems` instead.

#### `sync.system` ​

Type: `string`

Ticket system: `jira`, `linear`, or `github`.

#### `sync.project_key` ​

Type: `string`

Project key for ticket creation.

#### `sync.create_tickets` ​

Type: `boolean`Default: `true`

Auto-create tickets from spec sections.

#### `sync.reverse_sync` ​

Type: `boolean`Default: `true`

Sync ticket status changes back to specs.

### `ticket_systems` / `routing` ​

Advanced multi-system ticket routing. See the Ticket Sync guide for detailed usage.

## Examples ​

### Minimal ​

yaml

    version: "1"

    specs:
      doc_paths:
        - "docs/specs/*.md"

### Full-Featured ​

yaml

    version: "1"

    team: payments
    ticket_system: jira
    project_key: PAY
    slack_channel: "#payments-eng"

    specs:
      doc_paths:
        - "docs/specs/*.md"
        - "docs/**/*.md"
        - "README.md"
        - "CHANGELOG.md"
      auto_tickets: true
      require_review: true

    agents:
      pr_analysis: true
      doc_updates: true
      stale_detection: "30d"
      realization_check: true

    sync:
      system: jira
      project_key: PAY
      create_tickets: true
      reverse_sync: true