Configuration Reference

The Spec System is configured via a single config.yml file at .zoto/spec-system/config.yml in your repository root. This is the only path the plugin reads — earlier versions used .zoto-spec-system/config.json; that path is no longer supported.

All defaults are commented

The init template lists every supported key — commented out — alongside the value the plugin would otherwise apply internally. Uncomment any line(s) to override.

Creating the Config File

Run the dedicated init command once per repository: 

/z-spec-init

This writes .zoto/spec-system/config.yml from the plugin's templates/init-config.yml. The generated file is fully commented — uncomment a line to override that field. 

# unitOfWork: spec
# specsDir: specs
# workDir: specs/current

# spec:
#   maxSubtasks: 99
#   parallelLimit: 4
#   adversarialVerification: true
# ...

All path fields (specsDir, workDir) are relative to the repository root.

Default Behaviour

When the .zoto/spec-system/config.yml file exists but every line is commented out (the shipped init template), the Spec System operates with its built-in defaults:

  • Work items are called "specs"
  • Spec directories are created under specs/
  • The session hook watches specs/current/ for unprocessed items
  • Up to 4 subagents run concurrently during execution
  • Adversarial verification is enabled
  • The memory extension is disabled

This means you can start using the Spec System immediately without any configuration — just install the plugin and go.

Configuration Keys

The table below lists every configuration key, its type, default value, and what it controls.

Key Type Default Description
unitOfWork string "spec" The term used for work items in user-facing messages. Examples: "spec", "prp", "task", "story".
specsDir string "specs" Directory where spec directories are created. Relative to the repository root.
workDir string "specs/current" Directory monitored by the session hook for unprocessed items. Relative to the repository root.
hooks.sessionStartNudge.enabled boolean true Whether the session-start hook checks for unprocessed items in workDir.
hooks.sessionStartNudge.threshold number 20 Number of items in workDir before the nudge triggers.
hooks.sessionStartNudge.message string "You have ${count} unprocessed ${unitOfWork}s..." Nudge message template. Supports ${count} and ${unitOfWork} interpolation variables.
spec.maxSubtasks number 99 Maximum number of subtasks allowed per spec.
spec.parallelLimit number 4 Maximum number of concurrent subagents during spec execution.
spec.adversarialVerification boolean true Whether adversarial verification is mandatory after subtask completion.
extensions.memory.enabled boolean false Whether the memory extension is active.
extensions.memory.plugin string | null null Name of the memory plugin to use. Only relevant when extensions.memory.enabled is true.

Example Configurations

Minimal

An empty object is valid. All defaults apply — specs are stored in specs/, the session hook is active, and adversarial verification is enabled. 

{}

Or, if you only want to rename the unit of work: 

{
  "unitOfWork": "task"
}

Team Setup

A team that uses "story" as their work-item term and stores specs in a custom directory. The nudge threshold is raised since the team processes items in batches. 

{
  "unitOfWork": "story",
  "specsDir": "docs/stories",
  "workDir": "docs/stories/inbox",
  "hooks": {
    "sessionStartNudge": {
      "threshold": 50,
      "message": "You have ${count} unprocessed ${unitOfWork}s in the inbox."
    }
  }
}

Full Configuration

Every option set explicitly. Use this as a starting point if you want full control. 

{
  "unitOfWork": "spec",
  "specsDir": "specs",
  "workDir": "specs/current",
  "hooks": {
    "sessionStartNudge": {
      "enabled": true,
      "threshold": 20,
      "message": "You have ${count} unprocessed ${unitOfWork}s in the working directory."
    }
  },
  "spec": {
    "maxSubtasks": 99,
    "parallelLimit": 4,
    "adversarialVerification": true
  },
  "extensions": {
    "memory": {
      "enabled": false,
      "plugin": null
    }
  }
}

Key Groups

Top-level Keys

unitOfWork, specsDir, and workDir are the most commonly customized options. They control naming and file layout without changing system behaviour.

Hooks (hooks.*)

The hooks.sessionStartNudge group controls the automatic reminder that fires when you start a new Cursor session and there are pending items in workDir. Set enabled to false to disable it entirely, or raise the threshold if you prefer fewer reminders.

Spec Execution (spec.*)

These options govern how specs are executed:

  • maxSubtasks — guards against overly complex specs. Lower this if you want to enforce smaller, more focused specs.
  • parallelLimit — controls how many subagents run at once. Reduce this on resource-constrained machines.
  • adversarialVerification — when enabled, each completed subtask is independently verified before the spec is marked done. Disable only if you have external review processes.

Extensions (extensions.*)

The extensions.memory group enables an optional memory layer that persists context across sessions. Set enabled to true and provide the plugin name to activate it.