.bot/workspace/ 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:| State | Meaning |
|---|---|
proposed | The decision has been recorded but not yet formally accepted. |
accepted | The decision is active and constrains future work. |
deprecated | The decision is no longer relevant or applicable but is preserved for audit. |
superseded | The decision has been replaced by a newer decision record. |
decision_create
Creates a new Decision Record in the workspace with proposed status by default. Required: title, context, decision.
Short title summarising the decision (e.g.
"Use PostgreSQL for primary data store").Background explaining why this decision needed to be made — the forces at play, constraints, and situation that led to the decision.
What was decided, stated clearly and unambiguously.
Type of decision. One of
architecture, business, technical, process.Trade-offs, risks, and follow-on constraints introduced by this decision.
Options evaluated and why they were rejected. Each item has
option (string) and reason_rejected (string).People involved in or affected by this decision.
IDs of tasks related to this decision.
IDs of related decision records (e.g.
["dec-a1b2c3d4"]).Categorisation tags (e.g.
["database", "infrastructure"]).Impact level. One of
high, medium, low.Initial status. One of
proposed (default) or accepted.decision_get
Retrieves a single Decision Record by its ID. Required: decision_id.
The decision ID (e.g.
"dec-a1b2c3d4").decision_list
Lists all Decision Records, optionally filtered by status. Returns summary information for all matching records.
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.
The ID of the decision to update (e.g.
"dec-a1b2c3d4").Updated title.
Updated type. One of
architecture, business, technical, process.Updated context.
Updated decision text.
Updated consequences.
Updated alternatives. Each item has
option and reason_rejected.Updated stakeholders.
Updated related task IDs.
Updated related decision IDs.
Updated tags.
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.
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.
The decision ID to deprecate (e.g.
"dec-a1b2c3d4").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.
The ID of the decision being superseded (e.g.
"dec-a1b2c3d4").The ID of the decision that supersedes it (e.g.
"dec-e5f6g7h8").