DOCS · CONFIGURATION

Configuration

Synthex reads project settings from .synthex/config.yaml. Anything you don't specify falls back to the plugin's documented default, so the file only needs to contain the values you actually want to override.

File location and resolution

init/synthex:init scaffolds an empty .synthex/config.yaml at your project root with inline comments documenting every section. Each command resolves settings in this order, with later values winning:

Plugin defaults (shipped with Synthex)
Project overrides in .synthex/config.yaml
Per-command overrides (the review_loops: block under a specific command's section)
Per-invocation parameters passed to the command itself

You can delete any section you don't want to override; missing keys do not error.

Global review loops

review_loops:
  max_cycles: 2
  min_severity_to_address: high

Key	Default	What it does
`max_cycles`	`2`	Maximum review iterations before the loop exits with unresolved findings recorded
`min_severity_to_address`	`high`	Minimum severity that blocks loop exit. Options: `critical`, `high`, `medium`, `low`

Most commands inherit this block. Individual commands can override it under their own section (implementation_plan.review_loops, code_review.review_loops, and so on).

Implementation plan

Used by write-implementation-plan/synthex:write-implementation-plan.

implementation_plan:
  reviewers:
    - agent: architect
      enabled: true
      focus: "Technical architecture, feasibility, NFR coverage, missing technical tasks"
    - agent: designer
      enabled: true
      focus: "Design tasks, UX impact, visual/interaction design clarity"
    - agent: tech-lead
      enabled: true
      focus: "Task clarity, acceptance criteria, parallelizability, dependency accuracy"
  concurrent_tasks: 3
  review_loops:
    max_cycles: 3

Key	Default	What it does
`reviewers`	architect, designer, tech-lead	Sub-agents that review the draft plan. Add specialists or disable defaults
`concurrent_tasks`	`3`	Maximum tasks the PM recommends per parallel batch in the plan output
`review_loops`	`max_cycles: 3`	Plans get one extra cycle by default since they ripple downstream

To add a project-specific reviewer, append to the list:

implementation_plan:
  reviewers:
    - agent: compliance-reviewer
      enabled: true
      focus: "Regulatory compliance, audit trail requirements"

To disable a default reviewer, set enabled: false on its entry.

Refine requirements

Used by refine-requirements/synthex:refine-requirements.

refine_requirements:
  reviewers:
    - agent: product-manager
      enabled: true
      focus: "Requirement clarity, acceptance criteria, scope boundaries, success metrics"
    - agent: tech-lead
      enabled: true
      focus: "Technical clarity, implicit assumptions, NFR targets, missing requirements"
    - agent: designer
      enabled: true
      focus: "UX clarity, interaction patterns, accessibility, user flow completeness"

The roster mirrors the plan reviewers but with PRD-focused prompts. The Product Manager always leads the interview; reviewers join the clarity loop afterward.

Code review

Used by review-code/synthex:review-code.

code_review:
  reviewers:
    - code-reviewer
    - security-reviewer
  max_diff_lines: 300
  convention_sources:
    - CLAUDE.md
    - .eslintrc
    - .prettierrc
  spec_paths:
    - docs/specs

Key	Default	What it does
`reviewers`	`code-reviewer`, `security-reviewer`	Mandatory parallel reviewers; both run on every diff
`max_diff_lines`	`300`	Threshold above which the reviewer warns that diff size hurts review quality
`convention_sources`	`CLAUDE.md`, `.eslintrc`, `.prettierrc`	Files the code reviewer reads to learn project conventions
`spec_paths`	`docs/specs`	Directories the reviewer scans for specifications to check compliance against

For performance-critical code, add the optional performance-engineer reviewer:

code_review:
  reviewers:
    - code-reviewer
    - security-reviewer
    - performance-engineer

Specialist reviewers (compliance, accessibility, domain experts) attach via the specialists: block in the same section.

Quality / testing

Used by test-coverage-analysis/synthex:test-coverage-analysis.

quality:
  coverage_thresholds:
    line: 80
    branch: 70
    function: 80
  test_runner: vitest
  priority_modules: []

Key	Default	What it does
`coverage_thresholds.line`	`80`	Minimum line coverage for new code
`coverage_thresholds.branch`	`70`	Minimum branch coverage for new code
`coverage_thresholds.function`	`80`	Minimum function coverage for new code
`test_runner`	`vitest`	Test runner used to produce coverage reports
`priority_modules`	`[]`	Modules that always require thorough coverage. Empty = auto-detect by risk

Architecture

Used by write-adr/synthex:write-adr and write-rfc/synthex:write-rfc.

architecture:
  decisions_path: docs/specs/decisions
  rfcs_path: docs/specs/rfcs

Key	Default	What it does
`decisions_path`	`docs/specs/decisions`	Where Architecture Decision Records land
`rfcs_path`	`docs/specs/rfcs`	Where RFCs land

Design system

Used by design-system-audit/synthex:design-system-audit.

design_system:
  spec_path: docs/specs/design-system.md
  scan_paths:
    - src/

Key	Default	What it does
`spec_path`	`docs/specs/design-system.md`	Canonical reference for tokens, components, and patterns
`scan_paths`	`src/`	Directories to scan during compliance audits

Add framework-specific specialists (Storybook expert, Figma expert) via the specialists: block.

Reliability

Used by reliability-review/synthex:reliability-review.

reliability:
  slo_document: docs/specs/slos.md
  runbooks_path: docs/runbooks

Key	Default	What it does
`slo_document`	`docs/specs/slos.md`	Path to the SLO/SLI definitions document
`runbooks_path`	`docs/runbooks`	Where operational runbooks are stored

Performance audit

Used by performance-audit/synthex:performance-audit.

performance_audit:
  review_loops:
    max_cycles: 2

The performance audit only carries a per-command review_loops override; everything else inherits global defaults.

Retrospective

Used by retrospective/synthex:retrospective.

retrospective:
  output_path: docs/retros
  format: start-stop-continue
  max_improvement_items: 3

Key	Default	What it does
`output_path`	`docs/retros`	Where retrospective documents land
`format`	`start-stop-continue`	Retro format. Options: `start-stop-continue`, `4ls`, `sailboat`
`max_improvement_items`	`3`	Cap on improvement items per cycle. More than 3 means none get done

Next priority

Used by next-priority/synthex:next-priority.

next_priority:
  concurrent_tasks: 3

Key	Default	What it does
`concurrent_tasks`	`3`	Maximum number of tasks executed in parallel per next-priority/synthex:next-priority run

Override per-invocation by passing concurrent_tasks=N to the command.

Worktrees

Used by next-priority/synthex:next-priority for parallel task execution.

worktrees:
  base_path: .claude/worktrees
  branch_prefix: "feature/"

Key	Default	What it does
`base_path`	`.claude/worktrees`	Directory where per-task worktrees are created. Add this path to `.gitignore`
`branch_prefix`	`feature/`	Prefix prepended to each task branch name

Use an absolute path (e.g., /tmp/synthex-worktrees) if you want worktrees outside the repo.

Document paths

Default locations for project documents. Commands consult these unless overridden by their own parameters.

documents:
  requirements: docs/reqs/main.md
  implementation_plan: docs/plans/main.md
  specs: docs/specs
  decisions: docs/specs/decisions
  rfcs: docs/specs/rfcs
  runbooks: docs/runbooks
  retros: docs/retros

Most commands accept an explicit path parameter, so changing these is rarely necessary.

A minimal override file

If your project follows the defaults closely, your .synthex/config.yaml can be very short:

next_priority:
  concurrent_tasks: 6

code_review:
  reviewers:
    - code-reviewer
    - security-reviewer
    - performance-engineer

Everything else inherits from the plugin defaults. init/synthex:init will scaffold a fully-commented file when you want every setting visible at once.

The lifecycle — how each command fits into the five-phase loop
Parallel execution — how concurrent_tasks and worktree settings interact
Getting started — install Synthex and run your first command

Configuration

#File location and resolution

#Global review loops

#Implementation plan

#Refine requirements

#Code review

#Quality / testing

#Architecture

#Design system

#Reliability

#Performance audit

#Retrospective

#Next priority

#Worktrees

#Document paths

#A minimal override file

#Next