Configuration file

Sigilix reads its config from the PR head SHA on every review. The file is optional — missing means defaults apply, a malformed file means defaults apply plus a single warning posted on the PR. The file does not need to be committed to your default branch to take effect; whatever exists at the head SHA wins.

JSON or YAML — your choice

Sigilix accepts the same configuration as either JSON or YAML. The runner looks for these filenames at the repo root, in order, and uses the first one it finds:

Filename	Format
`sigilix.json`	JSON
`sigilix.yaml`	YAML
`sigilix.yml`	YAML

The schema is identical across formats — every field documented below works the same whether you write it as JSON or YAML. Pick whichever your repo already uses. Examples on this page are shown in JSON; the YAML example below is the same config in YAML.

Older versions of these docs documented a sigilix.yaml schema with thresholds, specialists.<name>, and review.comment_style keys. Those keys were never real — the schema below is the only one Sigilix reads in production. YAML as a format is fully supported, though: sigilix.yaml / sigilix.yml carry the exact same schema as sigilix.json.

Where it lives

your-repo/
├── sigilix.json   ← here, at the repo root (or sigilix.yaml / sigilix.yml)
├── src/
└── ...

The file is read via GitHub’s Contents API at the PR’s head SHA, so:

Edits in the PR itself apply to the same review (useful when iterating on the config).
Edits on main don’t take effect on open PRs until they’re synced.
A missing file is the most common case and is fine — Sigilix runs with defaults.

Schema overview

The schema has grown in three additive versions. Older configs keep working; new fields are opt-in.

Version	Added	Tracking
v1	`guidance`, `rules.<role>`	ARC-174
v2	`pathFilters`, `profile`	ARC-176
v3	`deterministicChecks`	ARC-193
v3+	Per-subsystem opt-outs (commands, depVulnScan, astRules, sarifEvidence, reviewMemory, describe)	ARC-181, ARC-185, ARC-186, ARC-188, ARC-189, ARC-191

The <role> token in rules is always one of logic, security, performance, tests. These are the internal specialist role names; their public-facing brand counterparts are Metis (logic), Argus (security), Iris (performance), and Eunomia (tests) respectively. A fifth specialist, the synthesizer Harmonia, runs after the four domain specialists to unify their findings.

Minimal example

{
  "guidance": "This repo is a TypeScript Cloudflare Worker. Reject any new class declarations — we use plain functions and module-scoped state."
}

A single guidance string is the smallest useful config. It’s prepended to every specialist and synthesizer prompt for this repo.

Realistic example

{
  "guidance": "This repo is a TypeScript Cloudflare Worker. State lives in KV + DOs.",
  "profile": "chill",
  "pathFilters": [
    "dist/**",
    "**/*.generated.ts",
    "vendor/**",
    "!vendor/critical-shim.ts"
  ],
  "rules": {
    "security": "All routes that mutate state must call requireAuth() before any side effect.",
    "tests": "vitest is the only test runner. Jest patterns (e.g., jest.mock) are out of scope."
  },
  "deterministicChecks": [
    {
      "id": "no-console-log",
      "pattern": "^\\+.*console\\.log\\(",
      "severity": "warning",
      "message": "Stray console.log left in committed code."
    }
  ],
  "depVulnScan": { "enabled": true },
  "describe": { "enabled": true }
}

YAML example

The exact same config as the realistic example above, written as sigilix.yaml instead. Same schema, same behavior — just YAML syntax:

sigilix.yaml

guidance: This repo is a TypeScript Cloudflare Worker. State lives in KV + DOs.
profile: chill
pathFilters:
  - dist/**
  - "**/*.generated.ts"
  - vendor/**
  - "!vendor/critical-shim.ts"
rules:
  security: All routes that mutate state must call requireAuth() before any side effect.
  tests: vitest is the only test runner. Jest patterns (e.g., jest.mock) are out of scope.
deterministicChecks:
  - id: no-console-log
    pattern: '^\+.*console\.log\('
    severity: warning
    message: Stray console.log left in committed code.
depVulnScan:
  enabled: true
describe:
  enabled: true

Full schema

{
  "guidance": "string — prepended to every specialist + synthesizer prompt",
  "rules": {
    "logic":       "appended only to the logic specialist's prompt",
    "security":    "appended only to the security specialist's prompt",
    "performance": "appended only to the performance specialist's prompt",
    "tests":       "appended only to the tests specialist's prompt"
  },
  "pathFilters": [
    "dist/**",
    "**/*.generated.*",
    "!critical/keep-this.generated.ts"
  ],
  "profile": "chill",
  "deterministicChecks": [
    {
      "id": "kebab-case-id",
      "pattern": "regex matched against added diff lines",
      "severity": "info | warning | critical",
      "message": "what the finding says",
      "flags": "i"
    }
  ],
  "commands": {
    "review":   { "prompt": { "addendum": "appended to the review system prompt" }, "model": { "primary": "model-id-from-allowlist" } },
    "improve":  { "prompt": { "addendum": "appended to the improve system prompt" } },
    "describe": { "prompt": { "addendum": "appended to the describe system prompt" }, "model": { "primary": "model-id-from-allowlist" } }
  },
  "depVulnScan":   { "enabled": true },
  "astRules":      { "enabled": true, "severityThreshold": "warning", "disabledRules": ["no-eval-call"], "autoInline": false },
  "sarifEvidence": { "enabled": true, "path": ".sigilix/trivy.sarif.json", "severityThreshold": "warning" },
  "reviewMemory":  { "enabled": true },
  "describe":      { "enabled": true }
}

Field reference

`guidance` (v1, string)

Repo-wide context prepended to every specialist’s prompt and the synthesizer’s prompt. Keep it specific and load-bearing — vague guidance dilutes findings, sharp guidance focuses them. Good guidance describes:

The stack (“TypeScript Cloudflare Worker”, “Rust embedded firmware”, “Next.js app router”)
Hard rules (“Domain code in src/domain/ may not import from src/infra/”)
Conventions a reviewer would otherwise miss (“Test files mirror source — foo.ts ↔ foo.test.ts”)

Bad guidance is generic (“Be careful about security”) — the models already know that.

`rules.<role>` (v1, string)

Per-specialist prompt addendum. Each <role> is one of logic, security, performance, tests. Use this when a rule only matters to one specialist:

{
  "rules": {
    "security": "All POST/PUT/DELETE routes must call requireCsrf() middleware.",
    "performance": "Avoid synchronous filesystem calls inside request handlers."
  }
}

Rules are additive to Sigilix’s built-in checks — they don’t replace them.

`pathFilters` (v2, string[])

Globs that drop files from review before specialist fan-out. Saves token spend on generated content and triggers the “no specialists” short-circuit when only filtered paths changed. Semantics:

Plain pattern excludes ("dist/**").
!pattern re-includes — later patterns win, so order matters.
Globstar (**) crosses directories. Single * matches one segment.

{
  "pathFilters": [
    "dist/**",
    "build/**",
    "**/*.lock",
    "**/*.snap",
    "!critical/important.snap"
  ]
}

`profile` (v2, “chill” | “assertive”)

Review tone. Default is chill.

Profile	Behavior
`chill`	Only flag must-fix issues. Skip nits, style, taste.
`assertive`	Include nits and style. Useful for high-bar codebases.

This maps to a one-line prefix on each specialist’s initial message; the model still weighs context but the flag-worthiness floor shifts.

`deterministicChecks` (v3, array)

JavaScript-flavored regex rules run against added diff lines before the LLM specialists fire. Matches surface as structured findings injected into the specialist prompts as authoritative facts. Each rule:

Field	Type	Required	Notes
`id`	string	yes	Kebab-case unique identifier
`pattern`	string	yes	JavaScript regex source (no surrounding slashes)
`severity`	`"info" \| "warning" \| "critical"`	yes	Maps to score 2 / 4 / 5
`message`	string	yes	What the finding says
`flags`	string	no	Regex flags. `i` for case-insensitive. `g` is implied — don’t pass it.

{
  "deterministicChecks": [
    {
      "id": "no-todo-in-prod",
      "pattern": "^\\+.*(TODO|FIXME|XXX)\\b",
      "severity": "warning",
      "message": "TODO/FIXME left in committed code."
    },
    {
      "id": "no-aws-keys",
      "pattern": "AKIA[0-9A-Z]{16}",
      "severity": "critical",
      "message": "Possible AWS access key leak."
    }
  ]
}

See Deterministic Checks for the conceptual layer and Writing deterministic checks for the practical guide.

`commands` (ARC-185, object)

Per-command prompt addenda and model overrides. Each key is a Sigilix slash command (review, improve, describe). Each value can carry prompt.addendum (a string appended to the command’s system prompt) and model.primary / model.fallbacks (override the default model + retry chain).

{
  "commands": {
    "review":   { "model": { "primary": "model-id-from-allowlist", "fallbacks": ["fallback-model-id"] } },
    "describe": { "prompt": { "addendum": "Always start changelogs with the user-facing impact, never the implementation." } }
  }
}

model.primary and each model.fallbacks entry must be a model identifier on Sigilix’s current allowlist. The allowlist tracks the providers and model versions in production and changes over time, so run /sigilix help or check the live command-override docs for the current set rather than pinning a model ID here. An unknown model name is a parse error; addendum is capped at 4000 code points.

Subsystem opt-outs

Each subsystem ships enabled by default and can be turned off per-repo:

Key	Subsystem	Disable with
`depVulnScan`	Dependency vulnerability scan (ARC-186)	`{ "enabled": false }`
`astRules`	AST rule-pack scanner (How It Works)	`{ "enabled": false }`
`sarifEvidence`	SARIF evidence channel (ARC-188)	`{ "enabled": false }`
`reviewMemory`	Cross-PR review memory (How It Works)	`{ "enabled": false }`
`describe`	`/sigilix describe` command	`{ "enabled": false }`

See Opt-outs for the consolidated reference.

Validation

Sigilix validates the config on every review. Fail-open semantics:

Missing file → defaults, no warning.
Malformed JSON or YAML → defaults + warning posted as a single sticky comment (see config-error comment).
Unknown top-level key → ignored, no warning (preserves forward compatibility — older Sigilix versions won’t break on newer schemas).
Type mismatch on a known key → that key dropped, warning logged in telemetry, review proceeds with defaults for that key.

The fail-open policy is deliberate: never break a review because a config field changed shape.

Rules & Guidance

Best practices for writing guidance and per-role rules.

Path Filters & Profile

Scope reviews with globs and tune flag-worthiness with profile.

Deterministic Checks

Write regex rules that run before the LLMs.

Slash Commands

/sigilix review, improve, describe — prompt/model overrides per command.

​JSON or YAML — your choice

​Where it lives

​Schema overview

​Minimal example

​Realistic example

​YAML example

​Full schema

​Field reference

​guidance (v1, string)

​rules.<role> (v1, string)

​pathFilters (v2, string[])

​profile (v2, “chill” | “assertive”)

​deterministicChecks (v3, array)

​commands (ARC-185, object)

​Subsystem opt-outs

​Validation

​Read next

Rules & Guidance

Path Filters & Profile

Deterministic Checks

Slash Commands

JSON or YAML — your choice

Where it lives

Schema overview

Minimal example

Realistic example

YAML example

Full schema

Field reference

`guidance` (v1, string)

`rules.<role>` (v1, string)

`pathFilters` (v2, string[])

`profile` (v2, “chill” | “assertive”)

`deterministicChecks` (v3, array)

`commands` (ARC-185, object)

Subsystem opt-outs

Validation

Read next