Configuration

This page lists the non-secret repository settings read by woostack. Artifact storage has its own reference section because local storage and remote mirroring have different fields and guarantees.

Configuration never contains credentials, grants permission to perform repository work, or approves artifact content.

Configuration files

If both files are absent, each consumer keeps its built-in defaults. An orphan local override without the tracked base file fails closed.

Merge and validation rules

The effective value for this base configuration:

{
  "artifacts": {
    "provider": "linear",
    "linear": {
      "repository": "https://github.com/acme/widgets",
      "workspace": "acme",
      "team": "ENG"
    }
  }
}

and this local override:

{
  "artifacts": {
    "linear": {
      "team": "LOCAL-ENG"
    }
  }
}

keeps repository and workspace, and sets team to LOCAL-ENG.

Top-level settings

There are eight supported top-level settings. The init template writes artifacts, models, review, and status; omitted supported settings use built-in defaults.

Artifact providers

A complete example

All keys in this example are optional. JSON has no comments, so the tables below own their exact types, defaults, and meaning.

{
  "artifacts": {
    "provider": "local"
  },
  "review": {
    "severity_floor": "high",
    "nits": true,
    "angles": {
      "force": ["tests"],
      "skip": ["seo"]
    },
    "ignore": ["**/*.generated.ts", "pnpm-lock.yaml"],
    "project_rules": ["docs/engineering/rules.md"],
    "authors_skip": ["dependabot[bot]", "renovate[bot]"],
    "force_tier": "",
    "chunking": { "max_loc": 4000 },
    "defer_markers": true,
    "metrics": false
  },
  "models": {
    "fast": { "model": "google/gemini-3-5-flash", "effort": "low" },
    "standard": { "model": "openai/gpt-5.5", "effort": "medium" },
    "deep": { "model": "anthropic/claude-opus-4-8", "effort": "xhigh" }
  },
  "audit": {
    "severity_floor": "high",
    "angles": {
      "force": [],
      "skip": ["deps"]
    },
    "ignore": ["**/*.generated.ts"],
    "chunking": { "max_loc": 4000 },
    "report_dir": ".woostack/audits"
  },
  "review_sweep": { "max_rounds": 3 },
  "commit": { "pre_commit": "pnpm format && pnpm test" },
  "status": { "staleDays": 14 },
  "base_branch": "main"
}

Review engine

All review keys nest under review. woostack-review validates the types when it runs; an unknown key inside review is a hard error.

Finding severity and nits

A finding at or above the severity floor is a normal (blocking-eligible) finding. A finding below the floor is surfaced as a non-blocking nit, or dropped entirely when nits are off. A below-floor finding explicitly marked blocking always surfaces regardless of the floor.

Angle selection

Angles are selected from the diff and verified context. Bounded low-risk local queues may use one holistic reviewer. Explicit force/skip settings retain specialist selection; force wins a tie and the base bugs pass cannot be skipped. CI and audit retain their existing specialist coverage.

See the review angle reference for each lens. The detector owns the exact selection heuristics; worker prompt frontmatter owns model tiers.

Filtering the diff

Skipping PRs automatically

Some PRs should short-circuit the whole review with a skip comment. By default, three bot authors are skipped (dependabot[bot], renovate[bot], and github-actions[bot]), and PR titles matching the release-rollup pattern ^(staging\|release\|chore\(release\)) are skipped. Set either to opt out: an empty array for authors_skip, or an empty string for the pattern.

Model selection

Each review subagent runs at a tier (fast, standard, or deep). On hosts that consume repository model configuration, the top-level models namespace maps that tier to a concrete model and optional effort. The namespace sits at the root, not under review, so review, audit, and local subagent drivers can share it.

omp is the host-owned exception. It ignores the entire models namespace and maps the effective tier to its fixed init-managed role worker instead. Changing a flat or provider-specific model leaf never changes an omp dispatch.

For hosts that consume this namespace, a provider-specific leaf takes precedence over the matching flat leaf. The same config file can therefore supply provider-neutral defaults and provider-specific overrides:

{
  "models": {
    "fast": { "model": "google/gemini-3-5-flash", "effort": "low" },
    "standard": { "model": "openai-codex/gpt-5.6-sol", "effort": "medium" },
    "deep": { "model": "anthropic/claude-opus-4-8", "effort": "xhigh" },
    "anthropic": {
      "fast": { "model": "claude-opus-4-8", "effort": "low" },
      "standard": { "model": "claude-opus-4-8", "effort": "medium" },
      "deep": { "model": "claude-opus-4-8", "effort": "xhigh" }
    },
    "openai": {
      "fast": { "model": "gpt-5.5", "effort": "low" },
      "standard": { "model": "gpt-5.5", "effort": "medium" },
      "deep": { "model": "gpt-5.5", "effort": "high" }
    }
  }
}

In this example, Claude Code selects the Anthropic branch and Codex selects the OpenAI branch. Another repository-model host can use the flat leaves. omp ignores every entry in the block. How each non-omp host consumes the schema, including spawn primitives, per-call routing knobs, and fallback, lives in its canonical host reference under skills/using-woostack/references/hosts/.

Each tier leaf supports all three shared forms:

• a model-slug string;
• an object { "model": "<slug>", "effort": "<level>" }; or
• a non-empty ordered array of either form, used as a fallback preference list.

Supported effort levels are minimal, low, medium, high, and xhigh. review.force_tier pins every review subagent to one tier, like running the review with --fast or --deep.

In an array leaf, entry 0 is the primary and has the exact semantics of the bare value. Entries 1..n declare a static preference order; runtime enactment remains host-specific. A review host with an explicit per-call model override can redispatch a rate-limited worker along later entries; other consumers follow their host reference. omp does not read or enact the array. An empty array is a hard config error.

{
  "models": {
    "deep": [
      { "model": "openai-codex/gpt-5.6-sol", "effort": "xhigh" },
      { "model": "openai-codex/gpt-5.6-sol", "effort": "high" },
      "google/gemini-3-5-flash"
    ]
  }
}

The complete example uses flat leaves to assign non-omp hosts a model for each tier.

Clean break: models moved out of review. A review.models block is a hard config error. Move it to the top level. woostack-doctor warns on a lingering review.models.

The default model per provider and tier:

Anthropic routes every tier to claude-opus-4-8, so the tier is carried by reasoning effort (low/medium/xhigh) rather than by the model. Effort applies on per-call hosts (Claude Code); the CI single-session claude-code-action step passes only the model.

On repository-model hosts, the tier resolves by precedence, highest to lowest: an inline --fast / --deep comment on the PR → the action's force_tier input → review.force_tier → the action's model input → the matching provider-specific leaf → the matching flat leaf → the provider table default. On omp, only the effective-tier decisions apply; the fixed worker map replaces every model-resolution step.

Chunking, adjudication, and metrics

Audit engine

Audit settings nest under audit. woostack-audit validates this object when it runs and hard-fails on unknown audit-local keys. The audit always runs simplify and production-readiness, skips architecture, and keeps the bugs and security safety floor from the review engine. Configured force and skip lists add to those defaults.

Root model tiers also drive woostack-audit on hosts that consume repository model configuration. Put overrides in the root models namespace using flat leaves (models.fast, models.standard, models.deep) or provider-specific leaves. A nested audit.models block is a hard error.

Sweep rounds

woostack-sweep drives a stack of PRs to a clean review, looping review → address-comments per PR.

Commit hook

woostack-commit can run a command before it stages anything: a formatter, linter, or test runner.

Status board

woostack-status flags an active repository row that has remained unchanged past the configured threshold.

Base branch

base_branch is a top-level string (not nested) naming the trunk branch that PRs target and that worktrees are cut from.

Defaults and doctor

Migration notes

• AUDIT_CONFIG_FILE is removed: woostack-audit reads effective configuration through the canonical resolver.
• Review empty-config fallback is removed: an empty .woostack/config.json fails closed as malformed instead of falling back to default values.