Cadence

Appearance is cheap. Verification is the work.

Cadence is a Claude Code plugin for a single developer who expects to maintain the software after the session ends. It keeps the project’s decisions, plans and results in the repository, where the next session can find them.

This guide follows the work: start a project, settle a phase, build it and check what it delivered. Testing has its own section because deciding when to stop is part of the job. The configuration reference is there when you need to change how Cadence behaves.

If you’re new to Cadence, start with installation. If it’s already installed, start or adopt a project.

Find what you need

This guide describes Cadence 3.11.0. The full contents are also readable on GitHub.

Install

Cadence runs inside Claude Code. You’ll need Claude Code with plugin support, Node.js and Git on your path, plus the CLI for the forge that hosts your repository:

Sign in through your chosen CLI before setting up a project. Cadence uses that identity for forge operations. The testing policy’s CI enforcement currently supports GitHub Actions only.

Add the plugin

Run these commands in Claude Code:

/plugin marketplace add https://github.com/crenshawdev/cadence.git
/plugin install cadence@cadence

Cadence’s scripts have no runtime package dependencies. Installing Cadence doesn’t require an npm install. The project you build with it will still need its own tools and dependencies.

To see the commands:

/cadence:cad-help

This guide writes the full /cadence:cad- names so you can use the examples directly.

Permissions

Cadence’s shell commands go through Claude Code’s permission checks. Your permission mode and allowed-command rules determine when it asks. An unattended workflow still needs permission to run its commands.

Publishing has additional controls. Accepting a testing policy doesn’t authorize verification pushes; you make that choice separately through /cadence:cad-config --testing.

The permissions and data reference describes provider calls, credentials and files outside your project.

Update or remove

/plugin update cadence@cadence

/plugin uninstall cadence@cadence

Once installed, start or adopt a project.

Start or adopt a project

Open Claude Code in the project’s directory. The starting command depends on what’s already there.

Existing code

/cadence:cad-adopt

Cadence reads the repository, manifests and Git history to establish what the project already does. It records shipped work and proposes a roadmap for what remains. You answer the questions the repository can’t settle.

Review that distinction carefully. Working code belongs in the project’s current state; it shouldn’t become a new implementation task just because Cadence has only now encountered it.

A new project

/cadence:cad-new-project

Cadence asks what you’re building, who it’s for, the constraints and what counts as done. It turns those answers into requirements and a phased roadmap.

If you’ve already had that conversation, bring a design brief. There’s no value in answering the same questions again.

The setup decisions

Setup establishes the forge and asks about role models and reasoning effort when those choices haven’t already been made. It also offers a testing policy before the roadmap, because the tests and any missing CI work affect the plan.

The testing recommendation covers:

• How deeply to test, based on the project and its consequential failure modes.
• Coverage thresholds, the production files measured and any exclusions.
• The required GitHub Actions jobs and whether the packaged product needs a check.
• Anything the chosen tools cannot measure.

The recommendation starts at 85% line and branch coverage, preserving higher existing thresholds. Go uses a separate statement threshold. Unsupported metrics are explained explicitly.

Accept the recommendation or adjust it. If an adopted project is below its accepted thresholds, the first phase addresses the shortfall and installs the CI gate together. Cadence doesn’t lower the threshold to make the first run green.

Verification publishing starts off. If you want /cadence:cad-verify to publish a branch so its CI checks can run, authorize that separately with /cadence:cad-config --testing. The authorization belongs to this clone and doesn’t travel in committed project configuration.

What setup leaves behind

The project record lives under .planning/:

Read the proposed roadmap before moving on. Correcting a mistaken goal here is cheaper than correcting several plans built from it.

When the roadmap is settled, move into your first phase.

Bring a design brief

You may have already spent an evening working through the idea. Save what you settled and let Cadence start there.

/cadence:cad-new-project --brief docs/design-brief.md

Replace the path with your own file. Cadence reads the brief, tells you what it understands to be decided, and asks about what remains open. You can correct that reading before it becomes the project plan.

What to put in it

A useful brief explains the problem, who has it, what you’re trying to achieve and the constraints you’ve accepted. Include what you deliberately won’t build. Those boundaries matter when the next plausible idea turns up.

Keep decisions separate from hypotheses. If you haven’t measured the performance, settled the data format or chosen a provider, say so. A confident paragraph can make an unresolved question look like a requirement.

There’s no required template. The brief can come from a conversation, your own notes or an existing design document. It needs enough context for someone who wasn’t in the conversation to understand your choices.

For example:

I want a CLI that checks a directory of Markdown files for broken local links. It’s for my own documentation repositories. It should report the source file and line, and return a failing exit status when a link is broken. It won’t check external URLs or modify files. I haven’t decided how to handle links into generated pages.

That gives Cadence a concrete goal, useful limits and a question still worth asking.

The brief changes where questioning starts. Setup still produces requirements and a roadmap, offers the testing policy, and asks you to review the result. From there, continue with your first phase.

If the repository already contains an implemented project, use /cadence:cad-adopt so the code informs the starting point.

Your first phase

Take one phase from the roadmap and work it through the loop. These examples use phase 1; substitute the phase you’re working on.

Settle the decisions

/cadence:cad-context 1

This is where you settle choices that affect the implementation and define the acceptance criteria. Be specific about observable behavior. “Supports configuration” leaves plenty of room for a working implementation you didn’t want. “Reads the project file and lets a command-line argument override it” gives the plan something to establish.

Make the plan

/cadence:cad-plan 1

Cadence turns the phase into tasks with actions and verification. Review the plan for what it will deliver and whether the work is proportionate.

Under an accepted testing policy, the plan checks existing coverage before adding tests. Its testing scope states the remaining outcomes to establish, the checks needed and where testing stops. Fixtures and mocks are part of the effort. If proving a small change requires a large testing apparatus, this is the time to question the approach.

Build it

/cadence:cad-execute 1

The executor works through the plan, runs checks and commits completed tasks. This command makes commits. Use it when you’re ready for that workflow.

Some checks may need services available only in CI. Under the testing policy, those checks are written for CI and remain outstanding until they run there.

Verify the result

/cadence:cad-verify 1

Verification asks whether the phase delivered its acceptance criteria. A completed task list alone doesn’t answer that.

With an accepted testing policy, required checks are automated. A check waiting on CI stays pending_ci, and the phase remains partial. Verification can publish the current non-protected branch when you’ve explicitly authorized it for this clone. Without that authorization, it leaves the work pending and explains how to proceed.

A phase is called CI-verified only when every required job passed for a recorded commit. A phase completed through local checks alone is reported as complete locally, not CI-verified. Projects without an accepted policy retain the conversational verification path.

Once the agreed behavior is covered and the required checks pass, finish. Another imaginable failure isn’t enough to reopen testing. That needs a demonstrated defect, an uncovered acceptance requirement or a measured coverage shortfall.

Come back to it

/cadence:cad-progress

Use this after a break or in a fresh session. Cadence reads the project state, finds incomplete or paused work, and offers the next step.

For a deliberate pause mid-phase, use /cadence:cad-pause. It records where to resume and can make a work-in-progress commit. You can also capture an unrelated idea with /cadence:cad-capture without turning it into work for the current phase.

Continue through the remaining phases. When the milestone is ready, /cadence:cad-milestone audits and closes the cycle; /cadence:cad-land handles publishing. Under the testing policy, unattended landing requires the configured jobs to pass on the branch head.

Plan and execute

A phase starts with a goal from the roadmap. The work before implementation is to make that goal specific enough to build and verify without reopening every decision along the way.

Settle the context

/cadence:cad-context 1

Cadence reads the project’s requirements and relevant earlier decisions before asking about this phase. It offers an assumptions-analyzer pass when you want a deeper reading of the code, or you can go straight to the unresolved choices.

The result is CONTEXT.md: the decisions and acceptance criteria the plan needs. Context is an optional artifact; planning can proceed without it. Use it when the phase has choices worth settling before someone starts implementing them.

You don’t have to explain an earlier decision again just because the session changed. If the current requirements contradict an older decision, resolve that contradiction explicitly.

Read the plan for outcomes

/cadence:cad-plan 1

The planner divides the phase into executable tasks. Each task names its files, actions and verification. A phase can have several plans; reaching a plan-size limit should split the work, not remove requirements.

When you read the result, check that it delivers the intended behavior and respects the decisions already made. Under an accepted testing policy, its Verify: fields also define a bounded testing scope: what existing checks cover, what must be added and what will be enough to finish.

Plan review provides a second opinion. The optional plan checker is separate and is off by default. Its presence isn’t a reason to turn a small change into a longer process.

Execute when you’re ready for commits

/cadence:cad-execute 1

Execution implements the plans and makes task commits. Start from a branch and working-tree state you’re comfortable building on. If you already have staged work, Cadence asks how to handle it before dispatching an executor.

Independent plans may run in parallel worktrees. Shared files, dependencies or an unsuitable worktree setup keep them sequential. The execution settings explain those conditions.

The executor runs the required checks and records its work. A successful execution produces the phase summary, but implementation being complete doesn’t establish that the phase passed verification.

When execution stops

A checkpoint names the decision, missing prerequisite or structural problem preventing the plan from continuing. Resolve that item before continuing. A resumed executor starts fresh and reads the record of what already happened.

If a run ends partway through, Cadence compares the executor’s report with Git history and offers to continue the remaining tasks or stop. It should not replay completed tasks over their existing commits.

When the implementation is ready, verify the result.

Review findings

A review is a second opinion about a particular plan, change or decision. Its value depends on the finding surviving contact with the code.

Cadence can use a fresh-context Claude reviewer and explicitly enabled external providers. Under the default adjudicated mode, the main session checks each finding against its cited code before combining the survivors. Agreement between reviewers helps prioritize a finding; it doesn’t replace that check.

When reviews run

Risk can also raise the default plan-review gate. Explicit settings and waivers affect that behavior; see review configuration.

An advisory review reports and continues. A blocking review stops on surviving blocker or high findings. A deferred review lets the work continue but leaves a queue that must be settled before landing. An adjudicated gate presents the surviving findings for your triage.

Decide what earns work

Look for the supported behavior affected, the evidence for the defect and the consequence of leaving it. A finding that sounds plausible still needs that connection.

In an adjudicated triage, nothing is selected by default. You choose what to act on. Findings that won’t be fixed in the current work need an explicit disposition through the applicable review flow; they shouldn’t quietly become extra implementation tasks.

Testing findings follow the same completion rule as implementation. Once the agreed checks pass, another imaginable failure isn’t enough to restart test development.

Ask for a review directly

A consult is different. It asks another model for help with a dead end and is offered only when configured. You still accept the named provider and model before the call.

If a reviewer fails to run, Cadence must report that. An unavailable review is not a clean review.

Verify results

/cadence:cad-verify 1

Verification asks whether the phase delivered its acceptance criteria. The implementation summary helps locate the work; its claim that something is finished isn’t the evidence that it works.

Results are recorded in the phase’s UAT.md, so a later session can see what passed, what failed and what remains unsettled.

With an accepted testing policy

Required checks are automated. Verification runs the project’s suite itself and checks that the accepted policy agrees with the committed policy file and workflow configuration.

A check that needs CI is recorded as pending_ci, naming its job and commit. It keeps the phase partial. A required criterion with no automated check is a test gap, not something handed to a person to certify.

Optional visual observations can remain useful, but they aren’t required test results and don’t determine completion. Required behavior becomes optional only through your explicit decision.

The CI chapter explains publishing authorization, bounded waits and the distinction between local completion and CI verification.

Without an accepted policy

Projects without a policy keep the conversational verification path. Cadence first runs the checks it can perform, then walks the remaining human checks with you and records the results.

That is compatibility behavior. To move required verification to the unattended policy path, use /cadence:cad-config --testing.

The deeper pass

/cadence:cad-verify 1 --deep

The deeper pass starts from the goal and examines whether the necessary implementation exists, has substance, is connected to the rest of the product and behaves as required. It can also be requested by the plan-time risk floor.

workflow.verifier=false disables that deep pass, including an explicit --deep request. It does not disable the ordinary verification walk. Under the testing policy, uncertainty about required behavior becomes a test gap.

Resolve failures deliberately

Verification diagnoses a failure and presents the next action. You can apply the proposed fix, re-plan the work or leave the failure open. Applying a fix can create a commit and returns the item to pending for a retest.

Leaving a failure open records the state; it doesn’t make the phase pass. If the remedy needs planned work, /cadence:cad-plan 1 --gaps can plan the outstanding gaps before execution resumes.

After the required items are settled, /cadence:cad-progress derives the next step from the project record.

Pause and resume

You should be able to end a session without writing a second account of everything it did. Cadence keeps the roadmap, decisions, plans and results in the repository so the next session can read them.

Find your place

/cadence:cad-progress

Progress derives the state from phase artifacts and Git, using the state cursor as a hint. It identifies incomplete or paused work and offers the next step.

A summary isn’t proof that every later gap plan has run. Progress also checks for outstanding plans and deferred reviews.

The normal progress command can reconcile a stale state cursor. For a read-only summary, use /cadence:cad-progress --stats; --trace gives a read-only view of what the current phase’s run did.

Leave a deliberate pause

/cadence:cad-pause Finish the parser error handling, then rerun its tests

Pause preserves in-flight work with a WIP commit when there are changes, then records a one-line resume pointer. It also commits the cursor update. It is a committing command, not just a bookmark.

Your note should name the next concrete action. “Finish the parser error handling” helps the next session more than “continue working.”

When you return, run /cadence:cad-progress. It reads the pause note and offers to resume from there.

Capture a thought without changing the phase

/cadence:cad-capture todo Add a JSON output mode in a later phase

Capture parks a todo, seed or note without making it part of the current implementation. It gives the idea somewhere to go without reopening the task you’re trying to finish.

After an interrupted run

Start with progress. If an executor stopped partway through, execution checks its report against the commits before offering to continue the remaining tasks. Completed work shouldn’t be repeated merely because the session ended.

If the planning files disagree or can’t be read, /cadence:cad-health reports structural problems. Use that evidence to resolve the state rather than marking work complete from memory.

Finish and publish

Closing a milestone updates the project record. Landing publishes the work. They are separate steps, with an explicitly authorized unattended path when you want them connected.

Close the milestone

/cadence:cad-milestone

The close begins with a traceability audit: requirements must connect to planned and verified work. An audit failure stops the close unless you explicitly override it.

For a release milestone, Cadence confirms the version before doing the applicable version and changelog work. A milestone can also close without a release version. Completed phases leave the live roadmap, while Git history retains the earlier record.

The release tag is not cut at this step. In the landing flow, it is cut on the pulled base after the merge is confirmed, when git.create_tag is enabled.

Choose how to publish

/cadence:cad-land

Landing first reports the branch, commits ahead, unpushed work and working-tree changes. When enabled, the issue report shows which referenced issues remain open; that report doesn’t modify them.

If there are uncommitted changes, Cadence asks whether to commit them first, leave them out or stop. It doesn’t silently bundle them into the land.

The default publishing choices have no preselected answer:

Available choices depend on the remote and forge setup. Under an accepted testing policy, direct push onto the base branch isn’t offered: that would land the work before its required jobs could pass. Use a separate branch and PR.

What can stop landing

Deferred reviews must be settled before publishing. A queue that can’t be read doesn’t count as an empty queue.

With a testing policy, landing compares the policy with the base and reports weakening. The unattended path stops on policy disagreement or reported weakening. On GitHub, its merge requires the configured jobs to succeed for the branch head; an earlier commit’s green checks aren’t enough. A timeout leaves the work unmerged.

Opening a PR and merging it are different outcomes. Cadence shouldn’t report a completed merge when it has only opened the request or enabled an auto-merge that is still waiting.

Unattended closing

git.auto_close must be explicitly true in both your user-global configuration and this repository’s configuration. When both authorize it, milestone closing can continue into landing without the per-step publishing questions. Required gates and host permissions still apply, and surviving blocker or high risk-surface findings stop the path.

Verification publishing has its own per-clone authorization. It doesn’t authorize a merge, and git.auto_close doesn’t authorize verification pushes. See Git and publishing settings for both.

After a confirmed merge, the configured cleanup can return to the base branch, pull and remove the merged integration branch. The next cycle starts with /cadence:cad-phase add when you’re ready to plan more work.

Agree on a policy

The testing policy answers two questions before implementation: what needs proving, and what evidence is enough to finish?

You accept it for the project. Planning, implementation, review, debugging, coverage and verification then work from that same agreement. Required tests run unattended in GitHub Actions, including their setup, services and cleanup.

Set it up

New-project setup and adoption offer a recommendation before the roadmap. For a project already using Cadence, run:

/cadence:cad-config --testing

Cadence reads the existing tests, coverage settings and workflows. The recommendation names the testing scope, thresholds, production files, exclusions, coverage commands and required CI jobs. It also identifies areas that warrant deeper testing and whether the packaged product needs verification.

Accept it or adjust it. A project with testing.scope unset has no accepted policy and keeps its existing behavior.

Choose the depth

The scope is a starting point. A focused project may still need careful tests around billing or destructive operations. Those areas belong in testing.strong_areas or the project’s identified risk surfaces, with a reason for the additional work. The stopping rule applies at every depth.

Coverage recommendations start at 85% for lines and branches, preserving higher existing thresholds. Unsupported metrics are explained before acceptance. A percentage marked estimated or unknown is never used as a measured result.

Keep policy changes deliberate

The planner and executor don’t change thresholds, exclusions, accepted commands or required jobs to get their work through. Reopen the policy with /cadence:cad-config --testing when the project’s requirements change.

A lower threshold, disabled metric or wider exclusion is an explicit adjustment. It should be visible as one.

Required acceptance criteria stay required. Cadence can’t make one optional because it is difficult to test. Optional visual observations can be recorded separately, but they don’t substitute for required automated checks.

Publishing is a separate choice

Accepting the policy doesn’t authorize a push. The --testing command asks separately whether verification may publish the current non-protected branch so GitHub Actions can run. Setup leaves that authorization off.

See required CI jobs for what happens when a check needs CI and the branch hasn’t been published.

Bound the testing effort

A test can be reasonable on its own and still add little to a suite. The decision is about what it establishes beyond the checks you already have, including what it will cost to maintain.

Cadence plans that work before writing tests. The task’s Verify: field records a short testing scope:

• The important observable outcomes and representative failures.
• What existing tests already establish.
• The smallest set of additional checks needed.
• What counts as sufficient evidence and where testing stops.

Fixtures, mocks and test infrastructure count toward the effort. If setup becomes disproportionate to the change, simplify the approach before building it.

Plan around behavior

Suppose a CLI gains a command-line option that overrides a value in its configuration file. Existing tests already cover loading the file and rejecting invalid values. The change needs coverage of the override behavior. It doesn’t automatically justify another configuration-loading suite or every permutation of unrelated options.

The planning question is:

What plausible defect in supported behavior would this catch that existing tests would miss?

Use it to choose the checks. There’s no table to complete for each test, and no fixed one-test-per-criterion rule. One check may establish several outcomes; a consequential behavior may need several checks.

Assertions have to establish something

Expected results should come from the requirements or design, independently of the implementation being tested. Repeating the implementation’s calculation in the assertion can reproduce the same mistake and still pass.

Test doubles can replace dependencies. They shouldn’t replace the behavior the test claims to verify. A test that runs code without checking its result may improve the reported percentage while leaving the requirement unprotected.

For a bug fix, reuse an existing reproducer if it provides lasting regression coverage. Confirm that it fails for the defect and passes after the fix. There is no blanket requirement to manufacture a negative control for every test.

Know when to finish

Once the agreed behavior is covered and the required suite and coverage gate pass, finish.

Expanding the work needs one of three things:

Another imaginable failure or an alternative way the code could have been written isn’t enough. Reviewers follow the same rule; a review doesn’t restart completed testing without that evidence.

If closing a real gap would materially exceed the planned effort, Cadence should report the tradeoff once. It shouldn’t quietly grow the task or lower the threshold.

These scope rules guide the agents. CI enforces executable checks and coverage thresholds; it cannot prove that every additional test earned its place. The short testing scope makes the intended boundary visible in the plan.

Coverage and supported tools

Coverage tells you which measured code the tests exercised. The assertions determine what those tests established. A project needs both useful checks and its accepted coverage thresholds.

Cadence starts its recommendation at 85% line and branch coverage and preserves higher existing thresholds. These are aggregate thresholds over the accepted production scope, not a requirement for every file to reach 85%.

Decide what is measured

testing.coverage.include names the production files. testing.coverage.exclude records the accepted exclusions, such as generated code, bundled output and test code.

Production files that tests never import still belong in the measurement. An empty scope or a missing measurement must not become a passing result. The CI task configures the coverage tool and the applicable report checks or guards for that purpose.

A wider exclusion changes the policy. It isn’t a routine fix for a coverage failure.

How Cadence 3.11.0 sets up enforcement

The project’s coverage tool does the measurement. Cadence uses the tool’s own thresholds where available and adds a small report check where needed.

The implementation reference contains the command shapes and tool-version requirements used by this release. They need adapting to the project’s source layout and report paths.

For Go, the recommendation uses statements: 85, lines: 0 and branches: 0. The statement percentage is a separate metric, not an equivalent line-coverage figure. For Rust on stable, the policy asks you to choose the nightly branch-measurement path or explicitly disable branch enforcement.

Read the result accurately

The report helper rejects missing, empty or invalid reports. Its Python path also checks for tracked Python files in the accepted scope that are absent from the report. Zero branch records alone don’t establish that branch instrumentation was enabled.

The JavaScript command shapes include an empty-scope guard. The Node and c8 shapes also reject a report containing a file with zero covered lines, addressing the branch-reporting problem recorded in the implementation reference. This is an additional restriction beyond the aggregate percentage.

What the policy check can establish

Cadence compares the project settings with the committed .github/cadence/coverage-policy.json and looks for the accepted commands and required job names in workflow files. It treats those commands as text; this comparison doesn’t execute them on your machine.

It doesn’t parse every coverage tool’s configuration, and finding a command in a workflow doesn’t establish which job runs it. A tool-specific ignore setting can narrow coverage without that comparison noticing. The CI setup task must inspect those settings and connect the accepted commands to the required jobs.

When coverage falls short, measure the gap first. Apply the testing scope rule to the work needed to close it.

Required CI jobs

Under an accepted testing policy, every required test runs in GitHub Actions without someone preparing data, starting a service or certifying the result. Automatically provisioned services are fine; their setup and cleanup belong in the job.

testing.required_jobs names the jobs Cadence checks. Installing or extending the workflow is a plan task because the dependencies, fixtures and services are specific to the project. Existing workflows are extended rather than overwritten.

Check the product as it will be used

Where packaging is relevant, a required job builds the artifact, installs it in its supported installation state, launches it and exercises its entry point without undeclared development dependencies.

A fresh runner by itself doesn’t establish that the package works. A service’s clean-start check is also a separate concern: it starts the service from clean state with its provisioned dependencies.

When a test can’t run locally

/cadence:cad-verify runs what it can locally. A required check that needs CI is recorded as pending_ci, with its job and commit. The phase stays partial until that item is settled.

Only phases with pending CI checks enter the CI wait. Locally completed phases aren’t described as CI-verified merely because their local checks passed.

To authorize verification publishing for this clone:

/cadence:cad-config --testing

The command asks separately about publishing and stores your answer in the repository’s own .git/config as cadence.publishForVerification. A global setting, committed project configuration or git.auto_close doesn’t supply that authorization. Protected branches are refused.

With authorization, verification can publish the current branch and wait for its jobs. Without it, nothing is pushed. Cadence can read results if the commit is already on GitHub; otherwise the checks stay pending until you authorize verification publishing or publish through /cadence:cad-land.

What counts as a pass

Cadence reads GitHub check runs for a specific commit. Every configured required job must succeed. Matrix runs match the configured job name followed by (; all matching runs must succeed.

A completed check with a skipped, cancelled or other non-success conclusion doesn’t pass. A missing run, unavailable GitHub CLI or failed API request leaves the result pending.

The wait is bounded to at most nine minutes per call. A timeout leaves the checks pending and lands nothing. Run verification again to resume. If the branch head changed, pending checks move to that commit.

On GitHub, the policy’s landing path checks the required jobs at the branch head before merging. A green result for an earlier commit doesn’t satisfy that requirement. Policy mismatches or reported weakening stop the unattended landing path too.

Other forges

Cadence 3.11.0 enforces this policy through GitHub Actions. On Forgejo or GitLab, it reports enforcement as unavailable. A required pending check doesn’t become optional because that integration is unavailable; it remains required until settled by an automated check or explicitly made optional by you.

Existing projects and migration

Updating Cadence doesn’t silently accept a testing policy for every repository. With testing.scope unset, the project keeps its previous behavior.

To adopt the policy in a project already using Cadence:

/cadence:cad-config --testing

Cadence reads the current settings, coverage configuration and workflows, then presents the recommendation alongside what it would change. For an existing codebase that hasn’t used Cadence, /cadence:cad-adopt offers the same policy during setup.

Keep useful tests and existing gates

Migration doesn’t require rewriting the suite. Existing tests count wherever they adequately establish the required behavior. The work is to identify real gaps, agree on the measurement scope and connect the required checks to CI.

Higher existing thresholds are preserved. For an adopted project below its accepted thresholds, the first roadmap phase addresses the shortfall and installs the gate together. Unknown coverage needs measurement; it isn’t evidence that the project meets or misses the threshold.

For an already managed project accepting a policy through --testing, /cadence:cad-plan puts the CI task first when the policy check finds no gate. Accepting the settings alone doesn’t install a working CI job.

The four retired switches

Cadence 3.11.1 retires test_attack, test_evidence, check_inspection and independent_rerun from the workflow settings, along with the evidence, inspection and re-run steps they turned on. Nothing reads them any more, with or without a policy.

A config that still holds one gets a warning on every read, and setting one is refused. The warning names the two commands that remove it, and Cadence doesn’t edit your config files for you. Other settings in the same file keep working.

The policy keeps independent verification’s purpose: verification runs the project’s suite itself. Older plans carrying test tables stay readable as plain text, and nothing acts on those sections.

Existing human-verification criteria

An old human-verify label doesn’t make required behavior optional. Under the policy, that criterion needs an automated check. If CI can run it, it can wait there; if it has no automated check, verification records the gap as a failure.

Only your explicit decision makes a required criterion optional. Visual observations can remain useful, but they don’t certify required behavior or hold up completion as optional observations.

Reauthorize publishing in a new clone

The policy can travel with the project. Verification-publishing authorization doesn’t. In a fresh clone, use /cadence:cad-config --testing if you want verification to push branches unattended.

These settings govern projects Cadence manages. They don’t lower Cadence’s own development coverage gates, which remain 95% lines and 88% branches in this release.

How settings resolve

You don’t need to tune every setting to start using Cadence. Setup asks about the choices the project needs, and /cadence:cad-config lets you revisit them. This reference covers every key in the 3.11.0 schema, including older fallback keys and settings outside the interactive menu.

Choose the right entry point

The menu doesn’t expose every key. Provider model settings use their guided setup; older role fallbacks and other advanced keys can be set through the validated configuration command.

Repository, user-global, then defaults

The normal read order is:

1. The repository’s .planning/config.json.
2. Your user-global ~/.claude/cadence/config.json.
3. The built-in default for that key.

CADENCE_GLOBAL_CONFIG can relocate the user-global file. Nested objects merge by key. Lists replace the lower layer’s list in full; they aren’t appended.

An absent setting can inherit a value. An explicit null replaces the lower layer’s value and has the meaning documented for that key. It isn’t a general synonym for removing the setting. For role settings, the older fallback keys can still participate after a null; see roles and models.

Scope and authorization exceptions

The pages below use repository or user-global for ordinary settings, repository only for project-bound settings and user-global only for machine-owned settings. The publishing and provider checks above still apply after values have been merged.

Inspect and change values

Cadence’s config.mjs command is the validated interface. In the examples below, CLAUDE_PLUGIN_ROOT must point to your installed Cadence plugin; run from the project directory.

# Read effective values, including inherited settings.
node "${CLAUDE_PLUGIN_ROOT}/cadence-core/bin/config.mjs" get parallelization.enabled

# Check a proposed change without writing it.
node "${CLAUDE_PLUGIN_ROOT}/cadence-core/bin/config.mjs" check parallelization.enabled=false

# Set a machine-wide default.
node "${CLAUDE_PLUGIN_ROOT}/cadence-core/bin/config.mjs" set --global parallelization.enabled=false

# Remove a repository override so inheritance applies again.
node "${CLAUDE_PLUGIN_ROOT}/cadence-core/bin/config.mjs" unset parallelization.enabled

set validates all supplied pairs before writing them together. unset removes keys from one layer; it doesn’t erase an inherited value. Add --global when removing a user-global setting. keys lists the schema, and validate checks the selected configuration file.

For a simple inheritance example, suppose your global setting disables parallelization and this repository enables it. The repository runs with true. Removing its override exposes the global false; removing both returns to the built-in true. Execution still checks whether the plans can safely run in parallel.

Find a setting

• Roles and models
• Reviews
• Testing
• Execution and parallelism
• Git and publishing
• Project records

Roles and models

Choose the model and starting reasoning effort for each role. You don’t need to make every role equally expensive: planning, implementation and review do different jobs.

/cadence:cad-config --roles

Use --roles --global to set your machine-wide answers. The interview explains each role before asking what it should use. Repository settings override those answers per key.

How the choices resolve

For a model, an explicit roles.<role>.model takes precedence over the older model.overrides.<role>. If neither supplies one, Cadence sends no model parameter and the role uses the session’s model. An unsupported model name warns and also uses the session’s model; it doesn’t quietly select a replacement.

The 3.11.0 resolver recognizes opus, sonnet, haiku and fable. The configuration accepts a string, but a string outside that set isn’t dispatched as a model. Availability still depends on your Claude Code environment.

For effort, the order is roles.<role>.effort, then the older model.effort.<role>, then the role’s schema default. Setting the newer key to null removes its answer, so a configured older fallback can still apply. Remove that fallback too if you want the schema default.

The five effort levels are low, medium, high, xhigh and max. A role’s effort selects an agent file carrying that effort. Review-provider effort is a separate setting on the reviews page.

All settings on this page can be set in either configuration layer. The older model and effort families remain supported for compatibility; use the roles.* settings for new configuration.

Settings

roles.cad-planner.model

Default: null · Type: string or null · Scope: repository or user-global.

Model for cad-planner. A non-null value takes precedence over model.overrides.cad-planner. With neither set, use the session model.

roles.cad-assumptions-analyzer.model

Default: null · Type: string or null · Scope: repository or user-global.

Model for cad-assumptions-analyzer. A non-null value takes precedence over model.overrides.cad-assumptions-analyzer. With neither set, use the session model.

roles.cad-verifier.model

Default: null · Type: string or null · Scope: repository or user-global.

Model for cad-verifier. A non-null value takes precedence over model.overrides.cad-verifier. With neither set, use the session model.

roles.cad-reviewer.model

Default: null · Type: string or null · Scope: repository or user-global.

Model for cad-reviewer. A non-null value takes precedence over model.overrides.cad-reviewer. With neither set, use the session model.

roles.cad-executor.model

Default: null · Type: string or null · Scope: repository or user-global.

Model for cad-executor. A non-null value takes precedence over model.overrides.cad-executor. With neither set, use the session model.

roles.cad-plan-checker.model

Default: null · Type: string or null · Scope: repository or user-global.

Model for cad-plan-checker. A non-null value takes precedence over model.overrides.cad-plan-checker. With neither set, use the session model.

roles.cad-planner.effort

Default: "high" · Type: enum · Scope: repository or user-global.

Allowed values: "low", "medium", "high", "xhigh", "max", null.

Starting effort for cad-planner. A non-null value takes precedence over model.effort.cad-planner. See the resolution order above for null.

roles.cad-assumptions-analyzer.effort

Default: "high" · Type: enum · Scope: repository or user-global.

Allowed values: "low", "medium", "high", "xhigh", "max", null.

Starting effort for cad-assumptions-analyzer. A non-null value takes precedence over model.effort.cad-assumptions-analyzer. See the resolution order above for null.

roles.cad-verifier.effort

Default: "high" · Type: enum · Scope: repository or user-global.

Allowed values: "low", "medium", "high", "xhigh", "max", null.

Starting effort for cad-verifier. A non-null value takes precedence over model.effort.cad-verifier. See the resolution order above for null.

roles.cad-reviewer.effort

Default: "medium" · Type: enum · Scope: repository or user-global.

Allowed values: "low", "medium", "high", "xhigh", "max", null.

Starting effort for cad-reviewer. A non-null value takes precedence over model.effort.cad-reviewer. See the resolution order above for null.

roles.cad-executor.effort

Default: "high" · Type: enum · Scope: repository or user-global.

Allowed values: "low", "medium", "high", "xhigh", "max", null.

Starting effort for cad-executor. A non-null value takes precedence over model.effort.cad-executor. See the resolution order above for null.

roles.cad-plan-checker.effort

Default: "low" · Type: enum · Scope: repository or user-global.

Allowed values: "low", "medium", "high", "xhigh", "max", null.

Starting effort for cad-plan-checker. A non-null value takes precedence over model.effort.cad-plan-checker. See the resolution order above for null.

model.escalate_on_failure

Default: false · Type: boolean · Scope: repository or user-global.

On a failed-attempt retry, dispatch one effort level above the configured starting level, holding at the top level. With this off, the retry keeps its starting effort.

model.overrides.cad-planner

Default: null · Type: string or null · Scope: repository or user-global.

Older model fallback for cad-planner, used only when roles.cad-planner.model supplies no value. Prefer the newer role key.

model.overrides.cad-assumptions-analyzer

Default: null · Type: string or null · Scope: repository or user-global.

Older model fallback for cad-assumptions-analyzer, used only when roles.cad-assumptions-analyzer.model supplies no value. Prefer the newer role key.

model.overrides.cad-verifier

Default: null · Type: string or null · Scope: repository or user-global.

Older model fallback for cad-verifier, used only when roles.cad-verifier.model supplies no value. Prefer the newer role key.

model.overrides.cad-reviewer

Default: null · Type: string or null · Scope: repository or user-global.

Older model fallback for cad-reviewer, used only when roles.cad-reviewer.model supplies no value. Prefer the newer role key.

model.overrides.cad-executor

Default: null · Type: string or null · Scope: repository or user-global.

Older model fallback for cad-executor, used only when roles.cad-executor.model supplies no value. Prefer the newer role key.

model.overrides.cad-plan-checker

Default: null · Type: string or null · Scope: repository or user-global.

Older model fallback for cad-plan-checker, used only when roles.cad-plan-checker.model supplies no value. Prefer the newer role key.

model.effort.cad-planner

Default: null · Type: enum · Scope: repository or user-global.

Allowed values: "low", "medium", "high", "xhigh", "max", null.

Older effort fallback for cad-planner, below roles.cad-planner.effort and above that role’s schema default. null supplies no fallback.

model.effort.cad-assumptions-analyzer

Default: null · Type: enum · Scope: repository or user-global.

Allowed values: "low", "medium", "high", "xhigh", "max", null.

Older effort fallback for cad-assumptions-analyzer, below roles.cad-assumptions-analyzer.effort and above that role’s schema default. null supplies no fallback.

model.effort.cad-verifier

Default: null · Type: enum · Scope: repository or user-global.

Allowed values: "low", "medium", "high", "xhigh", "max", null.

Older effort fallback for cad-verifier, below roles.cad-verifier.effort and above that role’s schema default. null supplies no fallback.

model.effort.cad-reviewer

Default: null · Type: enum · Scope: repository or user-global.

Allowed values: "low", "medium", "high", "xhigh", "max", null.

Older effort fallback for cad-reviewer, below roles.cad-reviewer.effort and above that role’s schema default. null supplies no fallback.

model.effort.cad-executor

Default: null · Type: enum · Scope: repository or user-global.

Allowed values: "low", "medium", "high", "xhigh", "max", null.

Older effort fallback for cad-executor, below roles.cad-executor.effort and above that role’s schema default. null supplies no fallback.

model.effort.cad-plan-checker

Default: null · Type: enum · Scope: repository or user-global.

Allowed values: "low", "medium", "high", "xhigh", "max", null.

Older effort fallback for cad-plan-checker, below roles.cad-plan-checker.effort and above that role’s schema default. null supplies no fallback.

Reviews

Three choices shape a review: who reviews, how their findings are combined, and what happens to those findings. Keep those choices separate when tuning the cost or interruption level.

/cadence:cad-config --review

This configures providers and detects their available models. The default reviewer is a fresh-context Claude subagent and needs no separate API key.

Providers and authorization

External providers run only when they are in the effective reviewer list and your user-global review.reviewers also names them. A repository list can narrow your authorized set, but cannot add a provider you haven’t authorized globally. A provider also needs a configured model and an available credential.

Provider model tiers and trigger effort affect external API reviewers. They don’t choose the Claude subagent’s model or effort; those come from its role settings. Decision review has its own provider settings and a separate Claude-subagent path.

Store model IDs and credential-file paths in configuration, never API keys. Credentials come from the environment first, then the provider env file. review.key_file changes that file’s path only from your user-global configuration.

What a gate does

review.mode controls how reviewers combine; a gate set to adjudicated requires adjudication regardless of the mode.

Risk surfaces

Use /cadence:cad-config --surfaces to revisit which risk surfaces the project contains. The plan-time risk floor can raise the default plan review to blocking and turn on deep verification. The resolver preserves a valid explicitly configured plan gate, including an explicitly configured advisory value. It doesn’t change role models or effort.

Waiving a surface’s routing floor withholds those plan-time effects for that surface. It doesn’t disable review of a matching actual diff. Keep the waiver distinct from changing which surfaces the detector watches.

Settings

review.mode

Default: "adjudicated" · Type: enum · Scope: repository or user-global.

Allowed values: "single", "panel", "adjudicated".

single uses the first available reviewer. panel combines and deduplicates findings. adjudicated runs reviewers independently, then evaluates their findings against the cited code before merging survivors.

review.reviewers

Default: ["claude-subagent"] · Type: list of allowed values · Scope: repository or user-global.

Allowed items: "claude-subagent", "openai", "gemini", "deepseek".

Reviewer backends to request. Lists replace across layers. External providers also need explicit user-global authorization, a model and a credential; the repository alone cannot enable them.

review.key_file

Default: null · Type: string or null · Scope: user-global only.

Override the provider credential env-file path, never the key itself. null uses providers.env under the Cadence XDG config directory, normally ~/.config/cadence/providers.env. Environment credentials take precedence.

review.request_timeout_ms

Default: 540000 · Type: integer · Scope: repository or user-global.

Range: 1–600000.

Timeout in milliseconds for an external review-provider HTTPS request. It does not set a Claude-subagent execution timeout.

review.max_prompt_tokens

Default: 120000 · Type: integer · Scope: repository or user-global.

Range: 1 or greater.

Estimated token ceiling for external review and consult payloads, using characters divided by four. An over-cap request is refused before transmission. It does not limit the Claude subagent.

review.providers.openai.tiers.flagship

Default: null · Type: string or null · Scope: repository or user-global.

Format: 1–128 letters, digits, ., _, : or -, beginning with a letter or digit; or null.

The openai model ID used when a review or consult requests the flagship tier. Configure it through --review. null leaves this provider/tier without a model.

review.providers.openai.tiers.balanced

Default: null · Type: string or null · Scope: repository or user-global.

Format: 1–128 letters, digits, ., _, : or -, beginning with a letter or digit; or null.

The openai model ID used when a review or consult requests the balanced tier. Configure it through --review. null leaves this provider/tier without a model.

review.providers.openai.tiers.cheap

Default: null · Type: string or null · Scope: repository or user-global.

Format: 1–128 letters, digits, ., _, : or -, beginning with a letter or digit; or null.

The openai model ID used when a review or consult requests the cheap tier. Configure it through --review. null leaves this provider/tier without a model.

review.providers.gemini.tiers.flagship

Default: null · Type: string or null · Scope: repository or user-global.

Format: 1–128 letters, digits, ., _, : or -, beginning with a letter or digit; or null.

The gemini model ID used when a review or consult requests the flagship tier. Configure it through --review. null leaves this provider/tier without a model.

review.providers.gemini.tiers.balanced

Default: null · Type: string or null · Scope: repository or user-global.

Format: 1–128 letters, digits, ., _, : or -, beginning with a letter or digit; or null.

The gemini model ID used when a review or consult requests the balanced tier. Configure it through --review. null leaves this provider/tier without a model.

review.providers.gemini.tiers.cheap

Default: null · Type: string or null · Scope: repository or user-global.

Format: 1–128 letters, digits, ., _, : or -, beginning with a letter or digit; or null.

The gemini model ID used when a review or consult requests the cheap tier. Configure it through --review. null leaves this provider/tier without a model.

review.providers.deepseek.tiers.flagship

Default: null · Type: string or null · Scope: repository or user-global.

Format: 1–128 letters, digits, ., _, : or -, beginning with a letter or digit; or null.

The deepseek model ID used when a review or consult requests the flagship tier. Configure it through --review. null leaves this provider/tier without a model.

review.providers.deepseek.tiers.balanced

Default: null · Type: string or null · Scope: repository or user-global.

Format: 1–128 letters, digits, ., _, : or -, beginning with a letter or digit; or null.

The deepseek model ID used when a review or consult requests the balanced tier. Configure it through --review. null leaves this provider/tier without a model.

review.providers.deepseek.tiers.cheap

Default: null · Type: string or null · Scope: repository or user-global.

Format: 1–128 letters, digits, ., _, : or -, beginning with a letter or digit; or null.

The deepseek model ID used when a review or consult requests the cheap tier. Configure it through --review. null leaves this provider/tier without a model.

review.triggers.plan.gate

Default: "advisory" · Type: enum · Scope: repository or user-global.

Allowed values: "off", "advisory", "deferred", "blocking", "adjudicated".

Consequence of reviewing a written plan. Gate values are explained above.

review.triggers.plan.tier

Default: "cheap" · Type: enum · Scope: repository or user-global.

Allowed values: "flagship", "balanced", "cheap".

External-provider model tier for reviewing a written plan. The Claude subagent uses its own role model.

review.triggers.plan.effort

Default: "low" · Type: enum · Scope: repository or user-global.

Allowed values: "minimal", "low", "medium", "high", "xhigh".

Requested external-provider reasoning effort for reviewing a written plan. The Claude subagent uses its agent file’s effort.

review.triggers.diff.gate

Default: "off" · Type: enum · Scope: repository or user-global.

Allowed values: "off", "advisory", "deferred", "blocking", "adjudicated".

Consequence of reviewing a per-task diff. Gate values are explained above.

review.triggers.diff.tier

Default: "cheap" · Type: enum · Scope: repository or user-global.

Allowed values: "flagship", "balanced", "cheap".

External-provider model tier for reviewing a per-task diff. The Claude subagent uses its own role model.

review.triggers.diff.effort

Default: "minimal" · Type: enum · Scope: repository or user-global.

Allowed values: "minimal", "low", "medium", "high", "xhigh".

Requested external-provider reasoning effort for reviewing a per-task diff. The Claude subagent uses its agent file’s effort.

review.triggers.risk_surface.gate

Default: "blocking" · Type: enum · Scope: repository or user-global.

Allowed values: "off", "advisory", "deferred", "blocking", "adjudicated".

Consequence of reviewing a detected risk-surface match. Gate values are explained above.

review.triggers.risk_surface.tier

Default: "cheap" · Type: enum · Scope: repository or user-global.

Allowed values: "flagship", "balanced", "cheap".

External-provider model tier for reviewing a detected risk-surface match. The Claude subagent uses its own role model.

review.triggers.risk_surface.effort

Default: "low" · Type: enum · Scope: repository or user-global.

Allowed values: "minimal", "low", "medium", "high", "xhigh".

Requested external-provider reasoning effort for reviewing a detected risk-surface match. The Claude subagent uses its agent file’s effort.

review.triggers.risk_surface.surfaces

Default: null · Type: list of allowed values · Scope: repository or user-global.

Allowed items: "auth", "migrations", "billing", "concurrency", "destructive", "secrets", "api_contract", "untrusted_input". null is also accepted as the unanswered state.

Risk categories the detector watches. null means unanswered and keeps all eight; an explicit list selects the categories. Use --surfaces to revisit the answer.

review.triggers.risk_surface.waive_routing_floor

Default: null · Type: list of allowed values · Scope: repository or user-global.

Allowed items: "auth", "migrations", "billing", "concurrency", "destructive", "secrets", "api_contract", "untrusted_input". null is also accepted as the unanswered state.

Surfaces that may not raise the plan-time review/deep-verification floor. null waives none. A waiver does not disable review on an actual diff or change any role’s model or effort.

review.triggers.phase_diff.gate

Default: "off" · Type: enum · Scope: repository or user-global.

Allowed values: "off", "advisory", "deferred", "blocking", "adjudicated".

Consequence of reviewing the merged phase diff after parallel execution. Gate values are explained above.

review.triggers.phase_diff.tier

Default: "cheap" · Type: enum · Scope: repository or user-global.

Allowed values: "flagship", "balanced", "cheap".

External-provider model tier for reviewing the merged phase diff after parallel execution. The Claude subagent uses its own role model.

review.triggers.phase_diff.effort

Default: "low" · Type: enum · Scope: repository or user-global.

Allowed values: "minimal", "low", "medium", "high", "xhigh".

Requested external-provider reasoning effort for reviewing the merged phase diff after parallel execution. The Claude subagent uses its agent file’s effort.

review.consult.enabled

Default: false · Type: boolean · Scope: repository or user-global.

Allow an offer of a second-model consult at a dead end. Each consult still needs your acceptance of the named provider and model.

review.consult.tier

Default: "flagship" · Type: enum · Scope: repository or user-global.

Allowed values: "flagship", "balanced", "cheap".

Provider model tier for a consult.

review.consult.effort

Default: "high" · Type: enum · Scope: repository or user-global.

Allowed values: "minimal", "low", "medium", "high", "xhigh".

Requested provider reasoning effort for a consult.

review.consult.attempt_threshold

Default: 3 · Type: integer · Scope: repository or user-global.

Range: 1 or greater.

Failed fix attempts or red-test iterations on one bug before /cad-debug offers a consult. It is not an automatic permission to call a provider.

review.decision_review.tier

Default: "flagship" · Type: enum · Scope: repository or user-global.

Allowed values: "flagship", "balanced", "cheap".

Provider model tier for /cad-decision-review. It affects external reviewers only; that command’s Claude-subagent path uses the session model.

review.decision_review.effort

Default: "high" · Type: enum · Scope: repository or user-global.

Allowed values: "minimal", "low", "medium", "high", "xhigh".

Requested provider reasoning effort for /cad-decision-review. It does not override the Claude reviewer agent file’s effort.

Testing settings

Accept or adjust the project’s policy through:

/cadence:cad-config --testing

The testing chapter explains the decisions behind these settings. All nine testing.* keys are repository-only. A user-global write is refused, and a hand-edited global testing section is ignored during the merge.

Defaults alone don’t activate the policy: testing.scope must name an accepted scope. Policy acceptance records the source scope, thresholds, commands and required jobs together. Change them through that policy discussion rather than treating a failing gate as permission to loosen them.

The accepted coverage commands describe what CI runs. Cadence compares them as text against workflow files; they are separate from workflow.test_command, the user-global command for local test execution.

Policy settings

testing.scope

Default: null · Type: enum · Scope: repository only.

Allowed values: "focused", "integrated", "thorough", null.

Accept a project policy: focused covers units/components and necessary interactions; integrated adds main-path integration; thorough adds justified deeper failure/limit checks. null leaves the policy inactive.

testing.coverage.lines

Default: 85 · Type: integer · Scope: repository only.

Range: 0–100.

Aggregate line-coverage threshold. 0 explicitly disables this metric; it is never reported as satisfied by that choice.

testing.coverage.branches

Default: 85 · Type: integer · Scope: repository only.

Range: 0–100.

Aggregate branch-coverage threshold, checked separately from lines. 0 disables enforcement. A valid zero-branch measurement is a different outcome.

testing.coverage.statements

Default: 0 · Type: integer · Scope: repository only.

Range: 0–100.

Separate statement-coverage threshold for tools such as Go. It is not used as a line threshold. 0 disables it.

testing.coverage.include

Default: [] · Type: list of strings · Scope: repository only.

Globs naming the production files to measure. An empty list leaves selection to the accepted command’s defaults; review that scope during acceptance.

testing.coverage.exclude

Default: [] · Type: list of strings · Scope: repository only.

Accepted exclusions from measurement, such as generated code, bundled output and test code. Expanding this list is a policy adjustment.

testing.coverage.commands

Default: [] · Type: list of strings · Scope: repository only.

Accepted CI coverage commands. Threshold placeholders are {lines}, {branches} and {statements}. The policy check matches filled-in commands against workflow text; it does not execute them.

testing.strong_areas

Default: [] · Type: list of strings · Scope: repository only.

Project paths that justify deeper testing because of a concrete requirement or plausible consequential defect. The stopping rule still applies.

testing.required_jobs

Default: [] · Type: list of strings · Scope: repository only.

GitHub Actions job names that must succeed for a commit to be recorded as CI-verified. The active policy needs at least one required job; [] cannot establish a CI pass.

Execution and parallelism

These settings control planning, execution and reporting. Some are limits the workflow works within; others report measurements after the work. A setting named a ceiling isn’t necessarily an execution cutoff.

For example, to keep plans sequential:

/cadence:cad-config parallelization.enabled=false

Parallel work needs independent plans

Enabling parallelization doesn’t force a parallel run. Plans must be independent, with non-overlapping declared files, and the host must support the required worktree behavior. If Cadence can’t establish that, it runs sequentially.

The host’s worktree.baseRef setting must resolve to head for this path. It belongs in Claude Code’s settings, outside Cadence’s schema. /cadence:cad-config offers to configure it when worktrees are enabled and asks which settings file to update. Disabling worktrees leaves parallel execution unavailable.

Reported limits

workflow.max_plan_bytes reports the size of a plan’s declared files; exceeding it doesn’t itself refuse planning or execution. The six workflow.max_dispatch_tokens.* settings report a dispatch’s final recorded context-window figure after it returns. They aren’t token budgets enforced by the host, and they aren’t cumulative token spend.

Local commands

workflow.test_command and workflow.lint_command are user-global only. Repository values are ignored. When no override is configured, the workflows use their documented project-manifest detection or fallback. The lint override covers lint, not a separately configurable typecheck command.

Settings

workflow.research

Default: false · Type: boolean · Scope: repository or user-global.

Enable the research pass during new-project setup. Other workflows do not read this switch.

workflow.plan_check

Default: false · Type: boolean · Scope: repository or user-global.

Add the optional plan-checker pass before implementation. This is separate from the standing plan-review trigger.

workflow.verifier

Default: true · Type: boolean · Scope: repository or user-global.

Enable the goal-backward deep-verification path. The risk floor can request it and --deep requests it explicitly; false is the workflow’s off switch. This does not disable the ordinary verification walk.

workflow.skip_discuss

Default: false · Type: boolean · Scope: repository or user-global.

Change the next-step suggestion for an unplanned phase in /cad-progress. It suggests planning instead of context gathering; it does not skip a workflow step.

workflow.inline_plan_threshold

Default: 3 · Type: integer · Scope: repository or user-global.

Range: 0 or greater.

Task count at or below which the plan can use the inline path rather than its own plan document.

workflow.max_plan_tasks

Default: 8 · Type: integer · Scope: repository or user-global.

Range: 1 or greater.

Maximum tasks per plan. A larger phase needs more plans, not fewer requirements. Plans that share files remain sequential.

workflow.max_plan_bytes

Default: 675000 · Type: integer · Scope: repository or user-global.

Range: 1 or greater.

Reporting threshold for the summed on-disk sizes of a single plan’s declared files. A crossing is reported by plan-size; it does not block dispatch or execution.

workflow.max_dispatch_tokens.cad-planner

Default: 200000 · Type: integer · Scope: repository or user-global.

Range: 1 or greater.

Reporting threshold for cad-planner’s final recorded context-window size. Read after dispatch; it neither stops the agent nor caps total token spend.

workflow.max_dispatch_tokens.cad-assumptions-analyzer

Default: 150000 · Type: integer · Scope: repository or user-global.

Range: 1 or greater.

Reporting threshold for cad-assumptions-analyzer’s final recorded context-window size. Read after dispatch; it neither stops the agent nor caps total token spend.

workflow.max_dispatch_tokens.cad-verifier

Default: 100000 · Type: integer · Scope: repository or user-global.

Range: 1 or greater.

Reporting threshold for cad-verifier’s final recorded context-window size. Read after dispatch; it neither stops the agent nor caps total token spend.

workflow.max_dispatch_tokens.cad-reviewer

Default: 150000 · Type: integer · Scope: repository or user-global.

Range: 1 or greater.

Reporting threshold for cad-reviewer’s final recorded context-window size. Read after dispatch; it neither stops the agent nor caps total token spend.

workflow.max_dispatch_tokens.cad-executor

Default: 200000 · Type: integer · Scope: repository or user-global.

Range: 1 or greater.

Reporting threshold for cad-executor’s final recorded context-window size. Read after dispatch; it neither stops the agent nor caps total token spend.

workflow.max_dispatch_tokens.cad-plan-checker

Default: 75000 · Type: integer · Scope: repository or user-global.

Range: 1 or greater.

Reporting threshold for cad-plan-checker’s final recorded context-window size. Read after dispatch; it neither stops the agent nor caps total token spend.

workflow.test_command

Default: null · Type: string or null · Scope: user-global only.

Override the local test command. null means no override; the executor and verifier use their project-manifest fallback. Set this in the user-global layer.

workflow.lint_command

Default: null · Type: string or null · Scope: user-global only.

Override the executor’s pre-commit lint command. With no override, command detection reads the project manifests. There is no companion typecheck setting.

parallelization.enabled

Default: true · Type: boolean · Scope: repository or user-global.

Allow independent plans to execute concurrently when the worktree and independence checks pass. Otherwise execution remains sequential.

parallelization.max_concurrent_agents

Default: 3 · Type: integer · Scope: repository or user-global.

Range: 1 or greater.

Maximum simultaneous agents for parallel execution.

parallelization.min_plans_for_parallel

Default: 2 · Type: integer · Scope: repository or user-global.

Range: 1 or greater.

Minimum number of plans needed before considering parallel execution.

parallelization.use_worktrees

Default: true · Type: boolean · Scope: repository or user-global.

Use separate Git worktrees for parallel writes. Turning this off prevents the parallel path from establishing the isolation it requires.

Git and publishing

Branch choices and authorization are related, but they answer different questions. Choosing a forge or an integration branch doesn’t authorize unattended publishing.

Two separate publishing permissions

git.auto_close authorizes the unattended milestone/landing path only when both the repository and user-global configuration set it to true. Either layer alone is insufficient. Required checks and the host’s command permissions still apply.

Verification publishing uses a different permission: cadence.publishForVerification in this clone’s own .git/config. It starts off and is enabled or disabled through /cadence:cad-config --testing. Global Git configuration, command-line overrides and git.auto_close don’t supply it. Verification publishing refuses protected branches.

That local Git setting isn’t a Cadence schema key and doesn’t travel with a clone. See required CI jobs for the pending-CI workflow.

Branch and forge choices

A milestone integration branch gives the cycle a shared destination for completed work. Trunk mode uses the base branch, subject to the protected-branch rule. Worktree starting points remain a separate host setting, explained under execution.

Forge setup records the provider and the repository it should address. For Forgejo, the host is the web/API host, optionally with its port; an SSH endpoint may be different. git.forge_repo is repository-only because a global repository identity would point unrelated projects at the same target.

Settings

git.protected_branches

Default: ["main", "master"] · Type: list of strings · Scope: repository or user-global.

Branch names governed by git.on_protected for direct commits. Verification publishing refuses protected branches regardless of that commit setting.

git.on_protected

Default: "ask" · Type: enum · Scope: repository or user-global.

Allowed values: "ask", "refuse", "allow".

ask requests a decision for a protected-branch commit, refuse blocks it and allow permits it. This does not authorize publishing.

git.integration_branch

Default: "milestone" · Type: enum · Scope: repository or user-global.

Allowed values: "milestone", "trunk".

milestone uses a per-milestone integration branch. trunk creates no integration branch and places work on the base, subject to the protected-branch rule.

git.auto_branch

Default: "ask" · Type: enum · Scope: repository or user-global.

Allowed values: "ask", "auto", "off".

ask prompts before creating or switching to the integration branch at cycle start. auto does so without that prompt. off stays on the current branch.

git.base_branch

Default: null · Type: string or null · Scope: repository or user-global.

Base branch for new work. null uses the current branch.

git.create_tag

Default: true · Type: boolean · Scope: repository or user-global.

Create the release tag at landing, on the pulled base after the merge is confirmed. It does not govern manifest version bumps.

git.on_land_cleanup

Default: true · Type: boolean · Scope: repository or user-global.

After a successful merge, return to the base branch, pull and remove the merged integration branch.

git.issue_check

Default: true · Type: boolean · Scope: repository or user-global.

Show the read-only issue report at the start of landing: issues referenced by this branch and which remain open. This setting does not close or modify issues.

git.forge_provider

Default: null · Type: enum · Scope: repository or user-global.

Allowed values: "forgejo", "github", "gitlab", null.

The forge selected at setup. null means it has not been answered. The configured provider is used instead of inferring it anew from the remote.

git.forge_repo

Default: null · Type: string or null · Scope: repository only.

Format: two or more slash-separated segments containing letters, digits, ., _ or -. No segment may begin with - or equal . or ... null leaves it unset.

The repository identity used for forge calls, such as owner/name; nested GitLab groups are supported. null means it has not been answered. Setup offers a remote-derived value for confirmation.

git.forge_host

Default: null · Type: string or null · Scope: repository or user-global.

Format: a hostname with an optional decimal port from 1–65535 (no leading zero). Host labels contain letters, digits and internal hyphens. null leaves it unset.

The confirmed Forgejo web/API hostname, optionally with a port. It is asked separately from the SSH remote. Leave it null for GitHub and GitLab.

git.auto_close

Default: false · Type: boolean · Scope: repository or user-global.

Authorize unattended closing and landing only when explicitly true in both configuration layers. Surviving blocker/high risk-surface findings and other required gates can still stop it. This does not authorize verification publishing.

Project records

Cadence keeps project state on disk so another session can continue from it. These settings control roadmap granularity, whether planning documents are committed, capture-queue reporting and recall.

Committing planning documents makes that record available wherever the repository goes. Turning it off changes what Cadence commits; it doesn’t erase existing history or make already tracked files private. Review what is tracked before publishing.

The testing policy’s committed .github/cadence/coverage-policy.json is separate from .planning/. CI needs that policy even when planning documents aren’t committed.

Settings

granularity

Default: "standard" · Type: enum · Scope: repository or user-global.

Allowed values: "fine", "standard", "coarse".

Controls the number of phases proposed during new-project roadmap creation: coarse aims for 3–5, standard for 5–8 and fine for 8–12. It does not split a phase into tasks.

planning.commit_docs

Default: true · Type: boolean · Scope: repository or user-global.

Commit planning documents alongside code. false tells Cadence not to commit them; it does not remove files from previous commits.

planning.max_capture_bullets

Default: 40 · Type: integer · Scope: repository or user-global.

Range: 1 or greater.

Reporting threshold for substantive Todos, Seeds and Notes in .planning/CAPTURE.md, excluding the empty placeholder. A crossing is reported; capture writers continue accepting items.

memory.backend

Default: "builtin" · Type: enum · Scope: repository or user-global.

Allowed values: "none", "builtin".

builtin uses the built-in BM25 recall over .planning/. none disables recall.

Commands

Use the full /cadence:cad- name in Claude Code. Square brackets below mean an optional argument; angle brackets name a value you supply. N is a phase number. Commands that accept an optional phase use the current phase when they can resolve one, or ask when they can’t.

The commands do different kinds of work. Execution, task work, fixes, pausing and rollback can make commits. Setup and planning can commit project records. Landing publishes only through its chosen or explicitly authorized path. A slash command isn’t inherently read-only.

Start and build

See plan and execute and verify results for the normal sequence. A request for --deep still respects workflow.verifier=false.

Review and investigate

Review findings explains the difference between a report, a blocking gate and work you choose to accept.

Manage the cycle

See finish and publish before using the closing commands. Pausing and undoing also change repository state; they aren’t status queries.

Find your place and configure

Provider consultation and automatic review triggers are capabilities used by these commands, not additional standalone commands.

Permissions and data

Cadence sends no telemetry and keeps its record in your repository. Optional cross-model reviews use provider APIs; forge operations and publishing use your own forge CLI and git. Everything else it touches outside the project is listed here, so you don’t have to find it by reading the scripts.

Cross-model reviewers

They’re off by default. The shipped reviewer is the Claude subagent, which needs no key and sends nothing your session isn’t already sending. A provider runs only when your user-global config’s review.reviewers names it as well as the project’s, so a repository’s committed review.reviewers can’t send your code to a provider on your key by itself, and cloning a repo that lists openai changes nothing until you’ve named openai yourself. Naming a provider there authorizes it for every repository whose own config names it too, and /cadence:cad-config --review asks before it writes that.

The key comes from the environment first. When the variable isn’t set, cadence-core/bin/review-provider.mjs reads it from ~/.config/cadence/providers.env (under $XDG_CONFIG_HOME when that’s set), or from the file review.key_file names in your user-global config. That’s a script reading a credential off your machine, which is what the plugin directory flags, and it stays that way on purpose: a plugin userConfig secret only reaches hooks and MCP servers, and the review calls run through Bash. The key is never written to a config file or printed, and each key goes only to its own provider’s host.

review-provider.mjs makes three calls, each to that host with that key:

• review sends the review instruction and the artifact under review, a plan or a diff, after credential redaction. It runs when a review gate fires with that provider in the reviewer set, and at /cadence:cad-decision-review.
• consult sends a short description of a dead end, the goal, what was tried and the exact failing signal, after the same redaction. It runs only with review.consult.enabled true, and only after you say yes to an offer that names the provider and model. /cadence:cad-debug, /cadence:cad-execute and /cadence:cad-plan make that offer.
• detect-models sends no project content, only the key as the request’s credential, to list the provider’s models when you run /cadence:cad-config --review.

Redaction catches a credential by its shape, a credential-shaped name beside its value, a URL’s userinfo, an Authorization header, and not by a list of known prefixes. A bare key sitting in a diff with nothing naming it goes out as written, so don’t point a reviewer at a secrets file.

Your forge

Every forge write goes through your own tea, gh or glab, signed in as you:

• repo create --private, once, at /cadence:cad-new-project, after you confirm the owner and name;
• issue create, with an issue list first to find a duplicate, when you send a review finding to the tracker instead of fixing it now;
• PR or MR create and merge at /cadence:cad-land, when you pick that arm, or unattended when git.auto_close is true in both the repository’s config and your user-global config.
• under an accepted testing policy, gh api reads the check runs of one commit, and /cadence:cad-verify pushes a non-protected branch so those jobs can run, only when cadence.publishForVerification is true in the repository’s .git/config.

Optional MCP tool

Context7 is used when it’s installed and skipped when it’s not, and Cadence doesn’t install it. Without Context7, /cadence:cad-decision-review checks library and API claims against the installed package source, the lockfile or vendored docs, and lists every claim it couldn’t check.

The two hooks that watch

• subagent-trace reads the stopped subagent’s own transcript, the file the host keeps for that agent, to price the dispatch in .planning/trace.jsonl.
• read-trace logs the path of each project file a tool call opens to .planning/reads.jsonl. Paths only, never contents. A file inside the plugin is recorded relative to the plugin, and any other path outside the project is recorded only as outside.

Outside the project

What Cadence writes outside your repository:

• ~/.claude/cadence/config.json, or the file CADENCE_GLOBAL_CONFIG names, when a setup interview or /cadence:cad-config saves a machine-wide answer;
• CAPTURE.md beside that config, from /cadence:cad-capture --cadence;
• the worktree.baseRef key, merged into .claude/settings.json or ~/.claude/settings.json, only after you pick the file at /cadence:cad-config;
• scratch directories from mktemp under TMPDIR, or /tmp when it’s unset.

What it reads outside it: your user-global config, providers.env or the review.key_file file during a provider call, and ~/.claude/settings.json and the platform’s managed-settings.json to learn worktree.baseRef before running plans in parallel worktrees.

Shell commands

No Cadence command lists Bash in allowed-tools, so every shell command a workflow runs goes through Claude Code’s own permission check, and your permission mode and your permissions.allow rules decide whether it asks first. What the workflows run:

• Cadence’s own scripts, as node "${CLAUDE_PLUGIN_ROOT}/cadence-core/bin/<script>.mjs";
• git, and in /cadence:cad-land the forge CLI, gh, glab or tea;
• scratch lines that make a directory with mktemp -d and read it back with node -e;
• workflow.test_command or a detected test runner during execution, task work, coverage and verification, experiment code in /cadence:cad-spike, and reproductions in /cadence:cad-debug.

To stop the prompts, add rules for the commands you trust with /permissions. The unattended /cadence:cad-milestone into /cadence:cad-land chain stops at the first command your settings don’t approve, so set those rules before you turn on git.auto_close.

Pushes are still guarded by git-guard, a hook that only asks or refuses and never approves, and the pushes it never sees are the unattended close above and the verification publish, which a repository authorizes for itself in .git/config.

Privacy

No telemetry, no analytics, no phoning home. Provider calls use the APIs described above. Forge and push traffic goes through your own tea, gh, glab and git. Commands that build, test or install project dependencies can also use the network under the host’s permissions. The planning record, the run trace and the reads log stay in .planning/ in your repository and go wherever you push it. Cadence runs inside Claude Code, so what your session sees goes wherever Claude Code sends it, which is the host’s policy and not this plugin’s.

Back to the guide

Roles and context

A long conversation is a poor place to keep the only copy of a project decision. Cadence puts that decision in a file and gives each role the context it needs for its part of the work.

The main session coordinates. Subagents do bounded jobs and return results that the main session can inspect and route.

These are separate contexts, not a guarantee that the judgments will be independent or correct. A fresh reviewer can miss a defect or repeat an assumption. Its findings still need grounding in the code, and behavioral claims still need evidence.

A continuation reads the record

A paused or interrupted executor doesn’t need its old conversation restored. A fresh continuation reads the plan and the report of completed work, with Git history establishing what was committed.

The report is important here. It lets the coordinator ask for the remaining work instead of paying for a new attempt at tasks that already landed.

Model and effort are separate choices

Each role has a model setting and a starting effort setting. In Cadence’s dispatch design, model selection is passed with the dispatch; effort comes from the selected agent file’s frontmatter. The files share a role contract so a different effort level doesn’t introduce a different set of instructions.

Those settings govern Cadence’s subagents. Your main session’s model and effort remain Claude Code choices. External API reviewers have their own provider model tiers and effort settings.

Use the role configuration to choose them. Raising every role’s effort isn’t a substitute for a clear plan or a useful assertion.

State and records

Cadence keeps enough on disk for a new session to work out what the project intended, what changed and what remains. Git history preserves earlier versions of that record.

The project and phase files

A summary says a run finished reporting. It doesn’t by itself prove that the phase passed, or that a gap plan written later has been executed.

Records have different jobs

The workflows assign ownership of updates. Executors report task work; the coordinator writes the phase summary and updates the cursor. Verification records acceptance results and updates completion state. Progress derives status and can reconcile a stale cursor.

That separation matters when files disagree. The answer is to examine the underlying plans, reports, checks and commits, not to pick whichever status looks most complete.

Run evidence

.planning/trace.jsonl records dispatch and workflow events, including the information used for cost and review-outcome reporting. .planning/reads.jsonl records file paths read by tools, not file contents. These are local records, not telemetry sent to Cadence’s author.

/cadence:cad-report reads the run record. /cadence:cad-suggest uses it to propose changes that the evidence supports. A missing or incomplete record limits what either can establish.

Deferred reviews have a durable queue because landing must still find them after a session ends. They don’t become resolved because a conversation or a local trace disappeared.

See project-record settings for committing planning documents, capture limits and recall, and permissions and data for where information is read or written.

Controls and their limits

Some Cadence rules are executable checks. Others are instructions the model must follow. You should be able to tell which one you’re relying on.

Git controls aren’t a sandbox

Cadence’s Git hook detects a limited set of command shapes and asks or refuses where its rules apply. It does not fully parse shell syntax. Wrapped commands, substitutions, aliases and other indirect invocations can be outside what it sees.

That limit matters. The hook is a workflow control, not an operating-system security boundary. Claude Code’s own permissions and your environment remain part of what controls execution.

Authorized unattended publishing uses a separate script that validates its inputs and invokes Git with an argument array. Closing requires both configuration layers to opt in; verification publishing requires this clone’s local Git authorization. Those are separate paths with separate permissions.

The publishing reference lists the guard’s known blind spots and the publishing rules.

Documentation checks also have a boundary

Cadence’s self-verification checks selected links between its runtime prose and code: keys, invocations, paths, role files and byte budgets. It can catch a reference to something that doesn’t exist. It can’t prove that a model obeyed an instruction or that a paragraph accurately explains every behavior.

The testing policy has the same distinction. The suite and coverage gate can execute. Deciding that a test earns its maintenance cost is still an engineering judgment, made visible in the plan and bounded by the completion rule.

A check that couldn’t run must remain unresolved. Describing that limitation is part of the result.

Cost

The useful question is what it costs to finish the work with enough confidence to keep it. A cheap dispatch that creates a day of rework wasn’t cheap.

Cadence gives you separate choices for role models, effort, review gates and external providers. Start with the work the role has to do, then use the run record to see where the spend went.

Read an actual run

/cadence:cad-report 1
/cadence:cad-report --all

The report brings together dispatch costs and recorded outcomes. Use /cadence:cad-suggest when you want configuration suggestions tied to that evidence. It proposes changes; it doesn’t apply them itself.

The trace can be incomplete, and a reported cost is only as good as the data available for that dispatch. Treat gaps as gaps.

Context is part of the cost

A command loads some instructions immediately and may read more as it works. A subagent receives a separate context. These aren’t interchangeable measurements.

From a Cadence checkout, the current tree can be measured with:

node cadence-core/bin/weight.mjs resident --root .

Don’t add command and dispatch weights together and call the result the main session’s context. They belong to different contexts. The measurement reference explains the definitions and available commands.

What the historical figures mean

The published cost notes contain dated measurements from my own account. They compare my Cadence sessions with my freeform work; they aren’t a controlled experiment or a prediction of your bill.

For your project, use your own run record. Change a setting for a reason you can name, then see whether it improved the work. More reviewers and higher effort both need to earn their place.

Contributing

Bug reports and documentation corrections are welcome. Tell me what you ran, what you expected, what happened, and enough of the relevant state to reproduce it. Include the Claude Code and Node versions when they matter. Remove credentials and private project material before sharing logs.

For a feature, open an issue before writing the implementation. Cadence is intentionally a single-developer tool, and a useful idea doesn’t automatically belong in its scope. Discussing that first saves both of us work.

The repository’s contribution guide has the code checks, separate test-repository workflow and contribution policy. GitHub issues are the place for reproducible bugs; #cadence on the jcrenshaw.dev Discord is for discussion.

Work on the book

The source is Markdown under docs/guide/. SUMMARY.md controls the navigation, and docs/book.toml configures the build. The files remain readable on GitHub.

With mdBook 0.5.4 installed, run from the repository root:

mdbook build docs
mdbook serve docs

The build writes docs/book/, which is ignored by Git. serve gives you a local preview. Review the rendered page as well as the Markdown, especially after changing tables or navigation.

Write from the reader’s task. Explain what a command does, what it changes and what the result establishes. Link to implementation details when they help; a user shouldn’t need the history of an internal parser to start a project.

Configuration descriptions must agree with the schema and the code that consumes the setting. A documented default isn’t a promise that a workflow always takes that path: scope, authorization and overrides can change the result.

Publishing the book

The documentation workflow builds pull requests. Its deployment job is restricted to main; it can run after a push there or a manual dispatch on that branch. It uploads only the generated book.

Before the first deployment, select GitHub Actions as the repository’s Pages publishing source and review the github-pages environment’s deployment rules. The workflow doesn’t enable Pages itself. Use the deployment’s reported URL once the site is live.

Contributions use the repository’s MIT license.

Design decisions and lineage

Cadence grew from GSD and its discuss, plan, execute and verify loop. I kept that core idea and narrowed the tool around the way I work as a single developer.

The history matters because some of the current boundaries came from trying a broader approach and paying for it. It belongs here for readers who want to understand those choices, without making everyone read it before using the tool.

Historical counts and experiments describe the version measured at the time. For current behavior, use this guide and the implementation it describes.

Cadence is maintained by John Crenshaw and is a derivative work of GSD by Open GSD. It is distributed under the MIT License. The original copyright and attribution are retained in the license and NOTICE.