Configuration

<TrackedFiles paths="crates/supersigil-core/src/config.rs" />

Supersigil is configured through a supersigil.toml file at your project root. Run supersigil init to generate one.

Single-Project Mode

The minimal configuration requires only a paths array:

supersigil.toml

paths = ["specs/**/*.md"]
tests = ["tests/**/*.rs", "src/**/*.rs"]

Key	Type	Required	Description
paths	string[]	yes	Glob patterns for spec documents
tests	string[]	no	Glob patterns for test files (used by <VerifiedBy> tag and file-glob strategies)

Multi-Project Mode

For monorepos with multiple projects, use the [projects] table instead of top-level paths/tests:

supersigil.toml

[projects.frontend]
paths = ["frontend/specs/**/*.md"]
tests = ["frontend/tests/**/*.rs"]

[projects.backend]
paths = ["backend/specs/**/*.md"]
tests = ["backend/src/**/*.rs"]
isolated = true

Key	Type	Required	Description
paths	string[]	yes	Glob patterns for this project’s spec documents
tests	string[]	no	Glob patterns for this project’s test files
isolated	bool	no	When true, cross-project references produce errors (default: false)

Caution

paths/tests and [projects] are mutually exclusive. Using both is a config error.

Use --project <name> with commands like supersigil verify, supersigil ls, and supersigil new to target a specific project. For new, --project is required in multi-project mode to determine where to place the generated file.

ID Pattern

Optional regex to validate document IDs:

supersigil.toml

id_pattern = "^[a-z][a-z0-9-]*/[a-z]+/[a-z][a-z0-9-]*$"

IDs that don’t match produce an invalid_id_pattern diagnostic (configurable severity).

Verification Rules

Override the severity of configurable rules in the [verify.rules] table. Values: "error", "warning", "info", "off".

supersigil.toml

[verify.rules]
missing_verification_evidence = "error"    # default
missing_test_files = "error"               # default
zero_tag_matches = "warning"               # default
status_inconsistency = "warning"           # default
stale_tracked_files = "warning"            # default
empty_tracked_glob = "warning"             # default
orphan_test_tag = "warning"                # default
invalid_id_pattern = "warning"             # default
isolated_document = "off"                  # default
invalid_verified_by_placement = "error"    # default
plugin_discovery_failure = "warning"       # default
plugin_discovery_warning = "warning"       # default
sequential_id_order = "warning"           # default
sequential_id_gap = "warning"             # default
incomplete_decision = "warning"           # default
orphan_decision = "warning"               # default
missing_decision_coverage = "off"         # default
invalid_rationale_placement = "warning"   # default
invalid_alternative_placement = "warning" # default
duplicate_rationale = "warning"           # default
invalid_alternative_status = "warning"    # default
empty_project = "warning"                # default

Note

Hard errors (broken_ref, duplicate_id, dependency_cycle, missing_required_attribute) cannot be suppressed or reconfigured.

Document Types

Define or customize document types with valid statuses and required components:

supersigil.toml

[documents.types.requirements]
status = ["draft", "review", "approved", "implemented"]

[documents.types.design]
status = ["draft", "review", "approved"]

[documents.types.tasks]
status = ["draft", "ready", "in-progress", "done"]

Key	Type	Description
status	string[]	Allowed status values for this type
description	string	Human-readable description (shown in supersigil schema output)

The four built-in types (requirements, design, tasks, adr) are always available even without explicit configuration. User-defined entries extend or override them.

Custom Components

Define custom components beyond the 11 built-ins:

supersigil.toml

[components.SecurityReview]
referenceable = false
verifiable = false

[components.SecurityReview.attributes]
reviewer = { required = true, list = false }
findings = { required = false, list = true }

Key	Type	Description
referenceable	bool	Whether the component has an id that can be referenced
verifiable	bool	Whether it is a coverage target (must also be referenceable with a required id)
attributes.<name>.required	bool	Whether the attribute must be present
attributes.<name>.list	bool	Whether the attribute accepts comma-separated values

Custom components participate in structural checking (known component names, required attributes) but do not create graph edges.

Documentation

Configure how supersigil links evidence to source code in documentation surfaces like the graph explorer.

supersigil.toml

[documentation.repository]
provider = "github"
repo = "myorg/myproject"
# host = "github.example.com"    # optional, defaults per provider
# main_branch = "master"          # optional, defaults to "main"

Key	Type	Required	Default	Description
provider	"github" | "gitlab" | "bitbucket" | "gitea"	yes	—	Git hosting provider
repo	string	yes	—	Repository path (owner/repo for most providers, group/subgroup/project for GitLab)
host	string	no	Provider default	Hostname (defaults to github.com, gitlab.com, bitbucket.org). Required for Gitea.
main_branch	string	no	"main"	Branch used in source links

When configured, evidence source locations in the graph explorer become clickable links to the repository. When omitted, the Rust ecosystem plugin attempts to infer this from Cargo.toml’s repository field. If neither is available, evidence locations render as plain text.

Tip

For Rust projects with a repository field in Cargo.toml, this section is often unnecessary — the Rust plugin infers it automatically.

Ecosystem Plugins

Declare ecosystem plugins. The built-in plugins are rust and js:

supersigil.toml

[ecosystem]
plugins = ["rust", "js"]

[ecosystem.rust]
validation = "dev"

Key	Type	Default	Description
plugins	string[]	["rust"]	Active plugins
rust.validation	"off" | "dev" | "all"	"dev"	Which Cargo manifests to validate
rust.project_scope	array of {manifest_dir_prefix, project}	[]	Map manifest directories to projects in multi-project mode

Skills

Configure the path for installed agent skills:

supersigil.toml

[skills]
path = "custom/skills/path"

Key	Type	Default	Description
path	string	.agents/skills/	Directory where supersigil init and supersigil skills install write agent skills

This section is only needed when using a non-default skills path. When omitted, skills are installed to .agents/skills/.