Configuration - Spektacular

Project configuration: config.yaml

A project’s own settings: the coding agent it drives, where it stores specs, plans, and changelog records, its knowledge sources, and the repositories it registers as members. Every project has exactly one .spektacular/config.yaml, at the root of the 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. A complete example, with two knowledge sources (a project-local one and a team-wide one stored elsewhere on disk):

command: spektacular
agent: claude
spec_trigger_threshold: moderate

debug:
  enabled: false

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

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

changelog:
  provider: file
  config:
    directory: .spektacular/changelog

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

repos:
  - name: docs
    local: ../docs

Project configuration keys

Eight top-level sections control the tool from .spektacular/config.yaml: command, agent, spec_trigger_threshold, debug, spec, plan, changelog, knowledge, and repos.

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.

spec_trigger_threshold string

default: moderate

How readily the agent offers to capture an open-ended discussion as a spec mid-conversation, rather than waiting for you to run /spek-new. One of strict (only substantial, multi-requirement features), moderate (default: a clear scoped decision or a feature with more than one requirement), or lenient (offers readily, including small fixes). Read live at the moment the agent decides whether to offer, so a change here takes effect immediately, mid-conversation.

debug section

default: debug.enabled: false

Debug logging. Set debug.enabled: true to write a JSONL log of every command to .spektacular/debug/session-log.jsonl, useful when reporting issues or developing a new plugin. See the Debugging page for the full walkthrough.

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.

Every spec record also carries lifecycle metadata: a created date, a status, and, once resolved, a closed date, tracked automatically without any extra configuration.

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.

Every plan record also carries lifecycle metadata: a created date, a status, and, once resolved, a closed date, tracked automatically without any extra configuration.

changelog section

default: file provider, .spektacular/changelog

How completed-feature changelog records are stored.

changelog.provider: storage backend; only file ships today.
changelog.config.directory: where the file provider writes changelog records. Defaults to .spektacular/changelog.

A record is written automatically at the end of every implement run, one flat markdown file per feature, covering what was built, why it matters, and how the outcome differed from the plan. Every changelog record also carries the same lifecycle metadata as specs and plans: a created date, a status, and, once resolved, a closed date.

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.

repos section

default: none

How a project registers its member repositories. Each entry identifies and locates one repository:

repos[].name: the repository’s project-local name, unique within this project.
repos[].address: the repository’s remote URL, when it is not colocated with the project.
repos[].local: a local path to the repository, when it is colocated or already checked out.
repos[].provider: the repository’s provider. Only git ships today.
repos[].dependencies: the project-local names of other registered repositories this one depends on.

A repository’s description, role, tags, and deployment are not declared here — they live in the repository’s own configuration file, described below.

Repository configuration: repo.yaml

What a member repository is: its description, role, tags, deployment, and its own knowledge sources and changelog provider. Every member repository carries its own .spektacular/repo.yaml, distinct from the project’s own .spektacular/config.yaml above. It is created as part of the repository’s footprint, either when it is registered with repo add or during a project’s initialization cascade over its already-registered repositories. It carries no reference back to any project that registers it, so the same repository can belong to any number of projects while describing itself in exactly one place. A complete example, for a documentation site:

description: Marketing and documentation site, built with Astro
role: documentation
tags:
  - docs
  - website
deployment: static-site

knowledge:
  sources:
    - scope: project
      provider: file
      config:
        location: .spektacular/knowledge

changelog:
  provider: file
  config:
    directory: .spektacular/changelog

Repository configuration keys

Descriptive metadata plus the repository’s own knowledge sources and changelog provider, shown wherever this repository’s details are surfaced, such as spektacular repo list or the repository roster an agent sees during planning.

description string

default: none

A short account of what this repository is or does.

role string

default: none

The role this repository plays, such as service, documentation, or library.

tags list of strings

default: none

Free-form labels for the repository, such as docs, website, or backend.

deployment string

default: none

How this repository is deployed, such as kubernetes or static-site.

knowledge section

default: one project source at .spektacular/knowledge

Same shape as the project-level knowledge key above. See the Knowledge Base page for the full reference.

changelog section

default: file provider, .spektacular/changelog

Same shape as the project-level changelog key above; this is where the repository’s own derived changelog entries land.

Pluggable by design

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

Browse plugins →