Spektacular reads everything it needs from .spektacular/config.yaml. Here's what each key does.
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.
Seven top-level sections control the tool: command, agent,
spec_trigger_threshold, debug, spec, plan, changelog, and
knowledge.
command string spektacularThe 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 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 moderateHow 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 debug.enabled: falseDebug 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 .spektacular/specsHow 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 .spektacular/plansHow plans are stored.
plan.provider: storage backend; only file ships today.plan.config.directory: where the file provider writes plans. Defaults
to .spektacular/plans.changelog section .spektacular/changelogHow 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.
knowledge section .spektacular/knowledgeOrdered 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.A complete .spektacular/config.yaml with two knowledge sources — a
project-local one and a team-wide one stored elsewhere on disk.
command: spektacularagent: claudespec_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-knowledgeSpecs, plans, knowledge, and agents are all behind plugin interfaces. See what ships today and what's planned.