config.yml schema

This page documents every field in .flowforge/config.yml. The schema is enforced strictly: unknown top-level keys cause validation to fail. For an introduction to where the file lives and how it is loaded, see the Configuration overview.

Top-level structure

version: '3.0'              # required
project:                    # required (project.name is required)
  name: string
  type: string              # default: 'unknown'
tracking:                   # optional, defaults applied
  provider: string          # default: 'github'
  repository: string        # optional
  syncEnabled: boolean      # default: true
rules:                      # optional, defaults applied
  extends: [string]         # default: []
  overrides: {}             # default: {}
standards:                  # optional, defaults applied
  testCoverage: number      # default: 80
  maxFileLines: number      # default: 700
  maxFunctionLines: number  # default: 50
  commitFormat: string      # default: 'conventional'

Only version and project.name have no default — everything else is filled in by the schema if omitted.

version

Attribute	Value
Type	string
Required	Yes
Default	(none)
Valid values	Strings matching ^3\.\d+(?:\.\d+)?(?:-[\w.]+)?$

Declares the FlowForge config schema version this file targets. The value must be a string that matches the 3.x family. Accepted forms include '3.0', '3.1', '3.0.0', and '3.0.0-alpha.1'. Forms such as '3.', '3.xyz', and '2.0' are rejected.

version: '3.0'

Caution

Always quote the version value. Unquoted 3.0 is parsed by YAML as the floating-point number 3.0 and will fail schema validation, which expects a string.

project

The project section identifies the project FlowForge is managing.

project:
  name: my-app
  type: node

project.name

Attribute	Value
Type	string (min length 1)
Required	Yes
Default	(none)

A non-empty human-readable project name. This name surfaces in CLI output, generated reports, and any tracker integration that takes a free-text project label.

project.type

Attribute	Value
Type	enum
Required	No
Default	unknown
Valid values	node, python, go, rust, java, unknown

Identifies the dominant language ecosystem of the project. FlowForge uses this hint to apply ecosystem-appropriate defaults in some commands and reports. Choose the value that matches the language a contributor would write a feature in. Set it to unknown for polyglot or non-source projects (documentation sites, infra-only repos, and so on).

For ready-to-use ecosystem starters, see Project type examples.

tracking

The tracking section configures FlowForge’s link to your issue tracker. See Tracking providers for a per-provider walkthrough.

tracking:
  provider: github
  repository: my-org/my-repo
  syncEnabled: true

tracking.provider

Attribute	Value
Type	enum
Required	No
Default	github
Valid values	github, linear, jira, notion, local

Selects the upstream tracker FlowForge talks to when starting sessions, validating ticket references, and syncing time. The local value is the offline mode — sessions and time entries stay on disk and never call out to a remote service.

tracking.repository

Attribute	Value
Type	string
Required	No
Default	(none)

Optional repository or workspace identifier passed to the provider. The exact format depends on the provider; for GitHub it is the conventional owner/repo slug. Leave it blank to let FlowForge infer the repository from the local git remote where it can.

tracking.syncEnabled

Attribute	Value
Type	boolean
Required	No
Default	true

When true, FlowForge synchronizes session and time data with the configured provider. When false, FlowForge still validates ticket references and runs all rules, but does not push state to the tracker. Use false for short-lived experiments where you do not want noise on tickets, and during incidents where the upstream tracker is unavailable.

rules

The rules section controls which rules FlowForge enforces and how strictly. The full catalog is on the Built-in rules page; this section only describes the configuration shape.

rules:
  extends: []
  overrides:
    branch-protection:
      severity: error
      options:
        protectedBranches: ['main', 'develop', 'release/*']
    no-console-log:
      severity: off

rules.extends

Attribute	Value
Type	string[]
Required	No
Default	[]

A list of rule preset names to extend. Presets layer in a curated set of rules and severities; project-level overrides then take precedence over anything inherited from a preset. The default empty array means “no presets” — only the per-rule overrides you declare apply.

rules.overrides

Attribute	Value
Type	Record<string, RuleOverride>
Required	No
Default	{}

A map keyed by rule name. Each entry is an override object with two optional fields:

• severity — one of error, warning, info, or off. Replaces the rule’s defaultSeverity. Use off to disable the rule entirely.
• options — a free-form Record<string, unknown> that is passed to the rule. Each rule documents the options it consumes (see Built-in rules).

rules:
  overrides:
    branch-protection:
      options:
        protectedBranches: ['main', 'release/*']
    jsdoc-required:
      severity: error

A rule that is not mentioned in overrides runs with its built-in default severity and no extra options.

standards

The standards section sets the quantitative coding-standard thresholds FlowForge measures against. The rationale for each default is on the Standards page.

standards:
  testCoverage: 80
  maxFileLines: 700
  maxFunctionLines: 50
  commitFormat: conventional

standards.testCoverage

Attribute	Value
Type	number (0–100)
Required	No
Default	80

Minimum acceptable test-coverage percentage. Reports flag any package or module below this threshold.

standards.maxFileLines

Attribute	Value
Type	positive integer
Required	No
Default	700

The maximum number of lines a non-test source file may have. Consumed by the max-file-lines rule.

standards.maxFunctionLines

Attribute	Value
Type	positive integer
Required	No
Default	50

The maximum number of lines a single function may span. Consumed by the max-function-lines rule.

standards.commitFormat

Attribute	Value
Type	enum
Required	No
Default	conventional
Valid values	conventional, simple

Selects the commit-message format FlowForge enforces:

• conventional — full Conventional Commits (type(scope): description), validated by the commit-message-format rule.
• simple — the commit-message-format rule is skipped entirely. No format is enforced. Use this when your team has a pre-existing house style that conflicts with Conventional Commits, or when commit history is not used to drive changelogs.

Strict mode and unknown keys

The schema is .strict(). Top-level keys other than version, project, tracking, rules, and standards cause validation to fail with an error like:

Invalid configuration in /path/to/.flowforge/config.yml:
  - <root>: Unrecognized key: "tracker". Valid top-level keys: version, project, tracking, rules, standards

This is deliberate. A typo such as tracker: (instead of tracking:) would silently drop your tracker configuration without strict mode. With strict mode the typo fails fast, with a precise error message and the list of valid keys.

Complete annotated example

The following is a fully populated .flowforge/config.yml that exercises every section. Every value is either explicitly set or pinned to its default, with comments explaining the choice. Use it as a copy-paste starting point for projects that want to be explicit rather than rely on defaults.

.flowforge/config.yml

# FlowForge v3 configuration. See https://flowforge.dev/docs/reference/configuration

# Schema version — must be quoted so YAML parses it as a string.
version: '3.0'

# Project identification.
project:
  name: my-app
  # One of: node | python | go | rust | java | unknown
  type: node

# Issue tracker integration.
tracking:
  # Tracker provider. One of: github | linear | jira | notion | local
  provider: github
  # Repository or workspace identifier. For GitHub, owner/repo.
  repository: my-org/my-app
  # Push session and time data to the provider.
  syncEnabled: true

# Rule enforcement.
rules:
  # Reusable rule presets, applied before overrides. Empty = no presets.
  # When presets ship, this will look like: extends: [recommended]
  extends: []
  # Per-rule overrides. Keys are rule names; see the Built-in rules page.
  overrides:
    # Lock down release branches in addition to the defaults.
    branch-protection:
      severity: error
      options:
        protectedBranches:
          - main
          - develop
          - release/*
    # Promote JSDoc requirements from a warning to a hard error.
    jsdoc-required:
      severity: error
    # Disable the console.log rule for a project that uses console.log
    # as a primary CLI output channel.
    no-console-log:
      severity: off

# Quantitative coding standards.
standards:
  # Minimum test coverage percentage (0–100).
  testCoverage: 80
  # Max non-test source file length.
  maxFileLines: 700
  # Max function length in JS/TS files.
  maxFunctionLines: 50
  # Commit message format. One of: conventional | simple
  commitFormat: conventional

For ecosystem-tuned starters, jump to Project type examples. To move on to the rules catalog, see Built-in rules.