Configuration

Spektacular reads everything it needs from .spektacular/config.yaml. Here's what each key does.

Where configuration lives

All Spektacular configuration lives in .spektacular/config.yaml at the root of your project. The file is created by spektacular init, missing keys fall back to defaults, and ${VAR} patterns are expanded from the environment when the file is read.

Top-level keys

Six top-level sections control the tool: command, agent, debug, spec, plan, and knowledge.

command string
default: spektacular

The CLI command name used in agent-generated documentation. Almost never needs to change — kept configurable so downstream tooling can refer to a different binary name if your team wraps the tool.

agent string
default: set by spektacular init

Which coding agent to drive during the implement workflow. Supported values: claude (Claude Code), bob, and codex. New agents register via the Agent plugin interface.

debug section
default: debug.enabled: false

Debug logging. Set debug.enabled: true to surface verbose internal logs to the console — useful when reporting issues or developing a new plugin.

spec section
default: file provider, timestamp IDs, .spektacular/specs

How specs are stored and identified.

  • spec.provider: storage backend; only file ships today.
  • spec.id_method: spec naming scheme. One of timestamp (default), counter (sequential numbers), or external (the caller supplies an id with each spec).
  • spec.config.directory: where the file provider writes specs. Defaults to .spektacular/specs.
plan section
default: file provider, .spektacular/plans

How plans are stored.

  • plan.provider: storage backend; only file ships today.
  • plan.config.directory: where the file provider writes plans. Defaults to .spektacular/plans.
knowledge section
default: one project source at .spektacular/knowledge

Ordered list of knowledge sources, queried in order at plan time and tagged by scope in results.

  • knowledge.sources[].scope: a label — project, team, global, or any custom string. Each scope must be unique within the list.
  • knowledge.sources[].provider: storage backend; only file ships today.
  • knowledge.sources[].config.location: where the file provider reads knowledge from. Relative paths resolve against the project root.

Example

A complete .spektacular/config.yaml with two knowledge sources — a project-local one and a team-wide one stored elsewhere on disk.

command: spektacular
agent: claude

debug:
  enabled: false

spec:
  provider: file
  id_method: timestamp
  config:
    directory: .spektacular/specs

plan:
  provider: file
  config:
    directory: .spektacular/plans

knowledge:
  sources:
    - scope: project
      provider: file
      config:
        location: .spektacular/knowledge
    - scope: team
      provider: file
      config:
        location: ${HOME}/work/team-knowledge

Pluggable by design

Specs, plans, knowledge, and agents are all behind plugin interfaces. See what ships today and what's planned.

Browse plugins →