Skip to content
decree

Start here

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

Install

Section titled “Install”

Use Homebrew. The name decree on PyPI belongs to an unrelated project.

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

If you cannot use Homebrew, install from source:

Terminal window
uv tool install git+https://github.com/doruksahin/decree

Set up a project

Section titled “Set up a project”

  1. Go to your repository.

    Terminal window
    cd my-app

  2. Initialize decree. This writes decree.toml, example PRD/ADR/SPEC docs, the local index cache, and project-local Codex/Claude skills.

    Terminal window
    decree init --with-agents

  3. Check the scaffold.

    Terminal window
    decree lint

  4. Create your first decision chain.

    Terminal window
    decree new prd "User Authentication" --bucket auth
    decree new adr "Use JWT sessions" --bucket auth
    decree new spec "Token Storage API" --bucket auth

  5. Rebuild the query index after document edits.

    Terminal window
    decree index rebuild

Optional: track active sprint work

Section titled “Optional: track active sprint work”

Sprint mode scopes decree progress and decree ddd to the active work in the current timebox. Sprint membership is stored as one file per document, so parallel worktrees can add and finish different items without fighting over one shared file.

Terminal window
decree sprint init "Sprint 1"
decree sprint add SPEC-01KT22NMS0D19VMD8VPK4D2MNX
decree sprint move SPEC-01KT22NMS0D19VMD8VPK4D2MNX --to active
decree generate-html --output decree-board.html
decree sprint complete SPEC-01KT22NMS0D19VMD8VPK4D2MNX --commit abc1234
decree sprint status

Use the generated HTML as a read-only human board: the orchestrator can open it to see open work, done items awaiting rollover, buckets, and acceptance-criteria progress. Agent workers do not need the board; hand each one a document ID and let it run the CLI/MCP loop against that scoped item. When backlog or draft-pool work becomes current-sprint work, promote it with decree sprint move DOC-ID --to active.

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 ddd --doc SPEC-01KT22NMS0D19VMD8VPK4D2MNX
    decree why src/auth/tokens.py
    decree intent-check --plan "rotate refresh tokens" \
      --files src/auth/tokens.py \
      --under SPEC-01KT22NMS0D19VMD8VPK4D2MNX

  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.

For parallel runs, give each agent a different sprint document ID. If a worker needs isolation, start it in its own git worktree and keep the same scoped loop.

Keep going

Section titled “Keep going”