Reference on DevFlow

df-tools CLI

Mon, 01 Jan 0001 00:00:00 +0000

df-tools is a CommonJS CLI, not a library. Roughly fifty skill and agent files call it. Skills resolve it through the home mirror:

node ~/.claude/devflow/bin/df-tools.cjs <command> [args] [--raw]

--raw emits compact JSON instead of pretty-printed — use it when piping.

Throughout this site the command is written df-tools <command> for brevity.

Complete command surface

Command	Subcommands
`awareness`	—
`benchmark`	—
`changelog`	`update` `check`
`check-todos`	—
`commit`	—
`config-ensure-section`	—
`config-get`	—
`config-set`	—
`context`	—
`current-timestamp`	—
`decision-queue`	—
`defaults-table`	`init`
`deprecation`	—
`detect`	`novel-domain` `brownfield-map` `flutter-ui-scope`
`dup-detect`	—
`find-objective`	—
`flutter-ui`	`setup` `eval` `bootstrap`
`frontmatter`	`get` `set` `merge` `validate`
`generate`	`uat`
`generate-slug`	—
`gh`	`status` `sync-objectives` `comment` `close-issue` `sync-release` `resolve` `sync` `pull`
`global-config`	—
`handoff`	`create` `complete` `list` `get`
`history-digest`	—
`init`	`execute-objective` `plan-objective` `new-project` `new-milestone` `quick` `resume` `verify-work` `objective-op` `todos` `milestone-op` `map-codebase` `security-audit` `progress`
`initiatives`	—
`intent`	`resolve`
`list-todos`	—
`micro`	—
`migrate`	`plan` `apply`
`milestone`	`complete`
`objective`	`next-decimal` `add` `insert` `remove` `complete`
`objective-job-index`	—
`objectives`	`list`
`org-awareness`	—
`override`	—
`planning`	`sibling-trd-scan`
`progress`	—
`project-accept`	—
`project-decline`	—
`project-hygiene`	`check` `move` `archive`
`project-state`	—
`requirements`	`mark-complete`
`resolve-model`	—
`roadmap`	`get-objective` `analyze` `update-job-progress`
`scaffold`	—
`session-audit`	—
`skill-active`	—
`skill-route`	—
`state`	`update` `get` `patch` `advance-job` `record-metric` `update-progress` `add-decision` `add-blocker` `resolve-blocker` `record-session`
`state-snapshot`	—
`summary-extract`	—
`survey`	`decimal-objectives`
`sync-roadmap`	—
`telemetry`	—
`template`	`select` `fill`
`todo`	`complete`
`transcript-export`	—
`trd-tdd`	`inspect`
`tui`	—
`validate`	`consistency` `health`
`verify`	`job-structure` `objective-completeness` `references` `commits` `artifacts` `key-links` `trd-pre` `api-contract` `flutter-ui-bootstrap` `flutter-state-coverage` `flutter-ui-eval`
`verify-path-exists`	—
`verify-summary`	—
`websearch`	—
`workstreams`	`analyze` `provision` `reconcile`

The commands you will use directly

State

df-tools state # load and print
df-tools state get <key>
df-tools state patch --key value
df-tools state advance-job
df-tools state update-progress
df-tools state add-decision --objective 4 --summary "..." --rationale "..."
df-tools state add-blocker --text "..."
df-tools state resolve-blocker --text "..."
df-tools state record-metric --objective 4 --job 02 --duration 620 --tasks 3 --files 7
df-tools state record-session --stopped-at "..." --resume-file <path>
df-tools state-snapshot

Commits

df-tools commit "feat(api): add rate limiting"
df-tools commit "..." --files src/a.go src/b.go
df-tools commit "..." --amend

This is what gate-commits redirects raw git commit to. It preserves objective scope and task IDs and updates STATE.md.

File structure

Mon, 01 Jan 0001 00:00:00 +0000

Project root

.planning/
 PROJECT.md vision, constraints, `kind` on frontmatter
 REQUIREMENTS.md scoped v1/v2 requirements with stable IDs
 ROADMAP.md objectives in dependency order, with checkboxes
 STATE.md decisions, blockers, position, session history
 MILESTONES.md archive of completed milestones
 SESSION_PICKUP.md resume note written by `status pause`
 STATE_ARCHIVE.md rolled-off state history
 config.json workflow configuration
 state.json machine-readable position mirror

Subdirectories

 research/ domain research (new-project)
 codebase/ brownfield mapping (map-codebase)
 todos/pending/ captured ideas
 todos/done/
 debug/ active debug sessions
 debug/resolved/
 decisions/pending/ parked DECISION-NNN.md
 milestones/ archived milestone directories
 quick/ quick-job records

Per objective

 objectives/NN-objective-name/
 OBJECTIVE.md goal, success criteria, `work` on frontmatter
 CONTEXT.md your preferences (discuss-objective)
 RESEARCH.md ecosystem research (research-objective)
 NN-YY-JOB.md atomic execution plan, one per job
 NN-YY-SUMMARY.md execution outcome and evidence
 VERIFICATION.md verification results
 UAT.md acceptance walkthrough
 verification/ Maestro YAML flows, capture manifests

Markers and caches

Rarely touched, but they explain otherwise-confusing behaviour.

Glossary

Mon, 01 Jan 0001 00:00:00 +0000

Ambient mode — a session in a DevFlow project with no skill currently running. gate-edits denies direct edits in this mode by default.

Atomic commit — one commit per task, carrying objective scope and task ID. Produced by df-tools commit, enforced by gate-commits.

Checkpoint — a formalised stop in an execution plan. Three types: human-verify, decision, human-action. Behaviour depends on mode.

Confidence tag — VERIFIED or SUSPECTED on every finding from codebase-mapper and security-auditor. Only VERIFIED findings are acted on downstream.