.bot/workspace/decisions/ and committed to git, giving your entire team visibility through standard version history. The AI agent uses these records to constrain implementation: tasks declare applicable_decisions to ensure the agent respects previous choices before writing any code. There are 7 MCP tools for working with decision records.
Decision states
A decision record moves through the following states:decision_create
Creates a new Decision Record in the workspace with proposed status by default. Required: title, context, decision.
string
required
Short title summarising the decision (e.g.
"Use PostgreSQL for primary data store").string
required
Background explaining why this decision needed to be made - the forces at play, constraints, and situation that led to the decision.
string
required
What was decided, stated clearly and unambiguously.
string
Type of decision. One of
architecture, business, technical, process.string
Trade-offs, risks, and follow-on constraints introduced by this decision.
array of objects
Options evaluated and why they were rejected. Each item has
option (string) and reason_rejected (string).array of strings
People involved in or affected by this decision.
IDs of tasks related to this decision.
IDs of related decision records (e.g.
["dec-a1b2c3d4"]).array of strings
Categorisation tags (e.g.
["database", "infrastructure"]).string
Impact level. One of
high, medium, low.string
default:"proposed"
Initial status. One of
proposed (default) or accepted.decision_get
Retrieves a single Decision Record by its ID. Required: decision_id.
string
required
The decision ID (e.g.
"dec-a1b2c3d4").decision_list
Lists all Decision Records, optionally filtered by status. Returns summary information for all matching records.
string
Filter by status. One of
proposed, accepted, deprecated, superseded. If omitted, all records are returned.decision_update
Updates the fields of an existing Decision Record. Only the fields you provide are changed; all other fields retain their current values. Required: decision_id.
string
required
The ID of the decision to update (e.g.
"dec-a1b2c3d4").string
Updated title.
string
Updated type. One of
architecture, business, technical, process.string
Updated context.
string
Updated decision text.
string
Updated consequences.
array of objects
Updated alternatives. Each item has
option and reason_rejected.array of strings
Updated stakeholders.
Updated related task IDs.
Updated related decision IDs.
array of strings
Updated tags.
string
Updated impact level. One of
high, medium, low.decision_mark_accepted
Transitions a proposed Decision Record to accepted status, making it active and binding for future tasks. Once accepted, the agent will read this decision whenever it is referenced in a task’s applicable_decisions list. Required: decision_id.
string
required
The decision ID to accept (e.g.
"dec-a1b2c3d4").decision_mark_deprecated
Marks a Decision Record as deprecated. The record is preserved for audit purposes but is no longer considered active or binding. Use this when a decision no longer applies without a direct replacement. Required: decision_id.
string
required
The decision ID to deprecate (e.g.
"dec-a1b2c3d4").string
Reason for deprecation. Helps future readers understand why the decision was retired.
decision_mark_superseded
Marks a Decision Record as superseded by a newer decision. Both the old and new IDs are recorded so you can trace the complete decision lineage. Required: decision_id, superseded_by.
string
required
The ID of the decision being superseded (e.g.
"dec-a1b2c3d4").string
required
The ID of the decision that supersedes it (e.g.
"dec-e5f6g7h8").