Skip to content
decree

Start here

decree is a Python CLI. It reads markdown decisions and a decree.toml, and answers from what’s declared. There is no service to run and no model to call.

Install

Section titled “Install”

Install with Homebrew, or from the GitHub repo — the name decree on PyPI is an unrelated third-party project, so it is not installed from there:

Terminal window
brew install doruksahin/decree/decree
decree --version

Set up a project

Section titled “Set up a project”

  1. Define your decision types in decree.toml at the project root. Types are yours — prefix, statuses, transitions, and required sections are all config.

    decree.toml
    [types.spec]
    dir = "decree/spec"
    prefix = "SPEC"
    initial_status = "draft"
    statuses = ["draft", "approved", "implemented"]
    required_sections = ["Overview"]
    

    [types.spec.transitions]
    draft = ["approved"]
    approved = ["implemented"]
    implemented = []
    

    [types.spec.actions]
    approve = "approved"
    implement = "implemented"

    Not limited to one type — define prd, adr, spec, or anything your team uses. The full schema is in the repository docs.

  2. Create a decision. New files are named {id}-{slug}.md, so parallel branches never fight over the next number.

    Terminal window
    decree new spec "Token Storage API"

  3. Declare what it governs in the frontmatter, so why and the intent checks can find it:

    decree/spec/spec-….md
    governs:
      - src/auth/tokens.py

  4. Build the query index that why, health, and the intent checks read from:

    Terminal window
    decree index rebuild

The loop agents and CI run

Section titled “The loop agents and CI run”

decree is built to be called around every change — by a person, and by an LLM agent editing the code:

  1. Before coding, map the file and check the plan:

    Terminal window
    decree why src/auth/tokens.py
    decree intent-check --plan "rotate refresh tokens" --files src/auth/tokens.py

  2. After coding, gate the diff before review:

    Terminal window
    decree intent-review --diff change.diff

  3. Gate on the exit code. 1 is a finding to stop on; 0 is clean or advisory; 2 is a config error. Add --json anywhere for structured output an agent can parse.

Keep going

Section titled “Keep going”