Configuration

FlowForge v3 reads its configuration from a single file at the root of your project: .flowforge/config.yml. This file declares the project name, the issue tracker FlowForge talks to, the rule presets and overrides FlowForge enforces, and the quantitative coding standards FlowForge measures against. Every value has a sensible default, so the smallest valid config is just two lines.

This section is the authoritative reference for that file. If a behavior is not described here or on one of the linked sub-pages, it is not part of the v3 contract.

Where the config lives

your-project/
├── .flowforge/
│   └── config.yml      ← FlowForge v3 configuration
├── src/
└── package.json

The path is relative to the project root and is fixed. FlowForge does not search parent directories and does not read configuration from package.json, pyproject.toml, or other ecosystem manifests. If .flowforge/config.yml does not exist, FlowForge applies the default configuration and continues — running FlowForge against an unconfigured project is supported.

Note

The legacy .flowforge/config.json format from FlowForge v1 and v2 is no longer read by v3. If you are migrating, copy the values you care about into the new YAML file; everything else picks up modern defaults automatically.

Validation behavior

FlowForge validates config.yml against a strict schema each time the configuration is loaded. The schema is the single source of truth — every loader, command, and rule reads through it.

Two validation guarantees are worth calling out explicitly:

• Strict object shape. The top-level object is .strict(). Any key other than version, project, tracking, rules, or standards causes a load-time error that lists the unknown key and the valid alternatives. This is intentional: it catches typos like tracker: (instead of tracking:) before they silently disable a feature.
• Typed leaves with bounded ranges. Every leaf has an explicit type and, where applicable, a bounded range (for example standards.testCoverage is constrained to 0–100). A value that is the wrong type or out of range fails validation with the offending path included in the error message.

Caution

Strict mode means forward compatibility is opt-in, not automatic. If a future version of FlowForge introduces a new top-level section, configs that do not bump their version field accordingly will not silently inherit the new key. Keep version aligned with the FlowForge release series you target.

When validation fails, FlowForge raises an error of the form:

Invalid configuration in /path/to/.flowforge/config.yml:
  - <field path>: <message>
  - ...

For unknown keys, the error message also enumerates the valid top-level keys, so a typo points immediately at its fix.

Defaults philosophy

FlowForge ships defaults that match the recommended professional baseline. Concretely:

• A config with only version and project.name is fully valid.
• All other sections (tracking, rules, standards) and every nested field have defaults applied by the schema.
• Defaults reflect the FlowForge recommended baseline: GitHub for tracking, conventional commits, 80% test coverage, 700-line file ceiling, 50-line function ceiling, no preset rule sets, no overrides.

This means most projects only declare what they want to change. The full default-applied object is what the rules engine ultimately sees, regardless of how sparse the original file is.

Smallest valid config

.flowforge/config.yml

version: '3.0'
project:
  name: my-app

This file passes validation and runs against every default. It is the recommended starting point for a brand-new FlowForge project; tune from there.

Configuration sections

The configuration file has five top-level sections. Each section has its own reference page:

Section	Purpose	Reference
version	FlowForge config schema version (must match 3.x).	config.yml schema
project	Project name and ecosystem type.	config.yml schema
tracking	Issue tracker provider, repository identifier, sync toggle.	Tracking providers
rules	Preset extends and per-rule severity/option overrides.	Built-in rules
standards	Quantitative coding standards (coverage, file/function caps, commit format).	Standards

For ecosystem-tuned starter configs (Node, Python, Go, Rust), see Project type examples. For environment variable overrides that change FlowForge runtime behavior without editing config.yml, see Environment variables.

Configuration precedence

The final FlowForge runtime state is computed from three sources, in order:

1. Schema defaults. Whatever the schema declares as the default for an omitted field.
2. .flowforge/config.yml. The project’s on-disk configuration. Values from this file override schema defaults.
3. Environment variables. A small set of variables overrides specific runtime behaviors at the per-process level. Today the surface is minimal — see Environment variables for the implemented and planned set. Environment variables do not mutate config.yml and are not persisted between sessions.

This layering keeps config.yml portable across machines while still allowing per-shell or CI-specific tweaks at the environment level.

Version compatibility

The version field must match the regex ^3\.\d+(?:\.\d+)?(?:-[\w.]+)?$. In practice this accepts:

• '3.0', '3.1', '3.0.0', '3.0.0-alpha.1'

It rejects:

• '3.', '3.xyz', '2.0', '3'

Quote the version in YAML so it is parsed as a string. Unquoted 3.0 is technically a float in YAML and will fail schema validation.

Where to go next

• Need the full schema? config.yml schema walks every field, including types, defaults, and examples.
• Tuning rules? Built-in rules catalogs the eight rules that ship in v3 and shows the override syntax.
• Connecting your tracker? Tracking providers covers GitHub, Linear, Jira, Notion, and local.
• Setting standards? Standards explains the rationale for each default threshold.
• Working in a specific ecosystem? Project type examples ships ready-to-use configs for Node, Python, Go, and Rust.
• Tweaking runtime behavior? Environment variables lists the user-facing overrides.