Guides on DevFlow

GitHub integration

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

Opt-in. Disabled by default. Every operation is a no-op when the integration is off, gh is missing, or auth has expired — GitHub failures never block your workflow.

Enable

{
 "github": {
 "enabled": true,
 "repo": "owner/name",
 "milestone_prefix": "v",
 "labels": {
 "objective": "devflow:objective",
 "in_progress": "devflow:in-progress",
 "gaps": "devflow:gaps"
 }
 }
}

Prerequisites: the gh CLI installed and authenticated. If the auth flow needs a TTY, hand it off with /devflow:handoff.

df-tools gh status # is the integration reachable?

What syncs, and when

Trigger	Action	Manual equivalent
End of `/devflow:new-project`	One milestone per roadmap version, one issue per objective; numbers persisted to `.planning/.gh-mapping.json`	`df-tools gh sync-objectives`
Verifier finds gaps	Posts the `gaps:` block from `VERIFICATION.md` as an issue comment	`df-tools gh comment <obj> @file:path`
Verification passes	Closes the issue with a link to the verification report	`df-tools gh close-issue <obj>`
Tag push `vX.Y.Z`	Release notes generated from `SUMMARY.md` files since the previous tag	`df-tools gh sync-release vX.Y.Z`
Manual	Any of the above	`/devflow:gh-sync [objectives\|release <tag>\|status]`

Additional CLI surface:

Parallel workstreams

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

Wave parallelism runs independent jobs inside one objective. Workstreams run independent objectives — each in its own git worktree and branch.

User-typed only

/devflow:workstreams carries disable-model-invocation: true. Claude cannot fire it. Creating and merging concurrent worktrees is not something to trigger by accident.

The cycle

/devflow:workstreams setup # analyse independence, provision worktrees
/devflow:workstreams status # what's running where
/devflow:workstreams run # execute across streams
/devflow:workstreams merge # merge completed streams back

Setup analyses independence first

Not every pair of objectives can run concurrently. setup runs a dependency analysis and excludes objectives that touch the same modules, because the merge would conflict and you would spend more time resolving than you saved.

The handoff watcher

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

Some commands cannot run in an agent’s non-interactive Bash. Without a mechanism, Claude has to stop and ask you to paste ! cmd, which breaks both its flow and your concentration.

devflow-watch is a small local daemon that closes that loop.

Quick start

devflow-watch start # start the daemon for the current project
devflow-watch status # verify
devflow-watch stop

That is the whole setup. From then on, when Claude tries to run something on the allowlist, the gate-interactive hook queues it instead of failing, the daemon executes it in your interactive shell, and the route-results hook injects the result into Claude’s next turn.

UI evaluation

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

Screenshots that a human glances at are not evidence. The UI eval pipeline captures each declared UI state, scores it through an offline visual-eval engine, and writes machine-readable evidence the verifier consumes and gates on.

Running it

/devflow:ui-eval 6
/devflow:ui-eval path/to/manifest.json

The pipeline

declare surfaces → capture each state → score offline → evidence → verifier gates
 (manifest) (Maestro / Playwright) (visual-eval) (JSON) (pass / fail)

The ui-evaluator agent drives it. Backend selection is automatic: Flutter surfaces go through Maestro, web through Playwright.

Telemetry and auditing

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

Everything here is local. It reads your own session transcripts on your own machine and writes to your own filesystem. Nothing is transmitted.

Context composition

df-tools context --limit 150
df-tools context --root /path/to/projects --raw

Recomputes where the context window actually goes, from your own transcripts: tool results versus tool-call inputs versus assistant text versus images, plus per-tool call counts and averages.

Images are priced per block

df-tools context prices images at roughly 1,500 tokens per block rather than by base64 length. Counting base64 characters overstates image cost by about 25× — that was the one real error in the original context audit.

See context discipline for what to do with the numbers.

Changelog and releases

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

Generating an entry

df-tools changelog update --version v2.6.0
df-tools changelog update --version v2.6.0 --dry-run
df-tools changelog update --version 1.27.4 --from 6aafba1 --to dcfba83
df-tools changelog check 2.5.0

Commits since the last tag are grouped by conventional-commit type:

Prefix	Section
`feat`	Added
`fix`	Fixed
`perf`	Performance
`refactor`	Changed
`docs`	Documentation
`test`, `chore`	grouped accordingly
unrecognised	Other

--from / --to let you backfill an older release with an explicit commit range.

The tag gate

changelog-on-tag is a PreToolUse(Bash) hook that fires when an annotated version tag is about to be created. It enforces two invariants: