DevFlow

Agents

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

Skills are thin orchestrators. They load state, decide what to dispatch, and spawn agents — the work happens in the agents, each in its own fresh context window.

Agent	Role	Quality	Balanced	Budget
`codebase-mapper`	Analyzes a codebase from a specific angle (stack, architecture, quality, or concerns) and writes structured findings.	sonnet	haiku	haiku
`debugger` effort xhigh	Investigates bugs using a structured scientific method with persistent session state across context resets.	opus	sonnet	sonnet
`executor` effort xhigh	Executes planned tasks with atomic git commits, handles deviations, and manages checkpoints during builds.	opus	sonnet	sonnet
`integration-checker`	Verifies that separately-built features connect properly and end-to-end user workflows actually work.	sonnet	sonnet	haiku
`job-checker`	Reviews execution plans before they run to verify they will actually achieve the objective goal.	sonnet	sonnet	haiku
`objective-researcher`	Researches how to implement an objective — discovers best practices, patterns, and pitfalls before planning begins.	opus	sonnet	haiku
`planner` effort xhigh	Creates detailed execution plans for objectives with task breakdown, dependency ordering, and built-in quality checks.	opus	opus	sonnet
`project-researcher`	Researches the domain ecosystem for a new project — stack options, architecture patterns, features, and common pitfalls.	opus	sonnet	haiku
`research-synthesizer`	Combines findings from multiple parallel research agents into a unified summary for roadmap creation.	sonnet	sonnet	haiku
`roadmapper` effort high	Creates project roadmaps by breaking requirements into ordered objectives with success criteria and dependency mapping.	opus	sonnet	sonnet
`security-auditor` effort xhigh	Scans codebase for security vulnerabilities in a specific domain: secrets, auth flows, or dependency risks.	opus	sonnet	sonnet
`ui-evaluator` effort high	Machine-judges the visual correctness of Flutter UI states by capturing each declared surface, scoring it through the offline visual-eval engine, and writing evidence the verifier consumes.	opus	sonnet	sonnet
`verifier`	Verifies that built code actually achieves the objective goal, not just that tasks were completed.	sonnet	sonnet	haiku

How an agent is defined

Each agent is a single markdown file in plugins/devflow/agents/ with YAML frontmatter and an XML-structured body:

config.json

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

.planning/config.json is created by /devflow:new-project and edited by /devflow:settings. You can also edit it directly.

The shipped defaults

{
 "mode": "yolo",
 "depth": "standard",
 "job_checker_enabled": true,
 "workflow": {
 "research": true,
 "job_check": true,
 "verifier": true,
 "auto_advance": true,
 "verifier_checkpoints": false,
 "decision_queue": false
 },
 "planning": {
 "commit_docs": true,
 "search_gitignored": false
 },
 "parallelization": {
 "enabled": true,
 "job_level": true,
 "task_level": false,
 "skip_checkpoints": true,
 "max_concurrent_agents": 3,
 "min_jobs_for_parallel": 2
 },
 "gates": {
 "confirm_project": true,
 "confirm_objectives": true,
 "confirm_roadmap": true,
 "confirm_breakdown": true,
 "confirm_job": true,
 "execute_next_job": true,
 "issues_review": true,
 "confirm_transition": true,
 "editGate": "strict"
 },
 "safety": {
 "always_confirm_destructive": true,
 "always_confirm_external_services": true
 },
 "workstreams": {
 "worktree_prefix": "../{project}-ws-",
 "branch_prefix": "df/ws-",
 "merge_strategy": "squash"
 },
 "github": {
 "enabled": false,
 "repo": "",
 "milestone_prefix": "v",
 "labels": {
 "objective": "devflow:objective",
 "in_progress": "devflow:in-progress",
 "gaps": "devflow:gaps"
 }
 },
 "awareness": {
 "cache_ttl_minutes": 10,
 "peer_stale_days": 30,
 "branch_patterns": ["feature/*", "df/*", "fix/*", "proposal/*"],
 "org_project_id": "",
 "sibling_repos": [],
 "eden_libs_path": null
 },
 "daemon": {
 "notifications": false,
 "notify_on_start": true,
 "notify_on_complete": true,
 "auto_launch": false,
 "multi_project": false,
 "cross_shell": [],
 "status_line": false
 }
}

Top-level

Field	Values	Default	Meaning
`mode`	`interactive` / `yolo` / `autonomous`	`yolo`	How checkpoints behave — see below
`depth`	`quick` / `standard` / `comprehensive`	`standard`	Default planning depth when the intent model does not override it
`job_checker_enabled`	boolean	`true`	Whether plans are reviewed before execution

mode

The single most consequential setting.

Context rot

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

What it is

Context rot is the quality degradation that happens as an LLM fills its context window. It is not a single failure — it is a slow slide:

Early reconnaissance (files read, commands run, dead ends explored) stays in the window forever, crowding out the information that matters now.
Instructions given at turn 3 compete with 200 turns of tool output by turn 200.
The model starts repeating itself, re-reading files it already has, and re-deriving conclusions it already reached.
Errors compound, because a wrong assumption made early is now “established context” that later turns treat as settled.

A single Claude Code session that researches, plans, builds and verifies a feature will hit this. Not because the model is bad, but because by the time it writes the code that matters, the signal it needs is buried under everything it did to get there.

Core workflow

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

Command	Arguments	What it does
`/devflow:new-project`	`[--auto]`	Set up a new project from scratch — asks what you're building, researches the domain, defines requirements, and creates a development roadmap.
`/devflow:discuss-objective`	`<objective-number>`	Capture implementation decisions for an objective before planning — lock in preferences so research and planning don't drift into assumptions.
`/devflow:research-objective`	`[objective]`	Research how to build something before planning it — discovers best practices, architecture patterns, and pitfalls for the domain.
`/devflow:plan-objective`	`[objective] [--auto] [--research] [--skip-research] [--gaps] [--skip-verify] [--work TYPE] [--tdd POSTURE] [--depth LEVEL] [--model PROFILE]`	Create a detailed execution plan for an objective, breaking it into concrete tasks with success criteria.
`/devflow:execute-objective`	`<phase-number> [--gaps-only]`	Execute all planned tasks for an objective, running independent tasks in parallel for speed.
`/devflow:build`	`<objective-number-or-description> [--pause] [--skip-research] [--work TYPE] [--tdd POSTURE] [--depth LEVEL] [--model PROFILE]`	Build a feature from start to finish — plans the work, executes it, and verifies the result in one command.
`/devflow:verify-work`	`[objective number, e.g., '4']`	Test what was built by walking through expected behavior and checking it matches reality.
`/devflow:quick`	`[--full]`	Small features (single executor, no planner, no verifier) — between micro (1-line) and build (multi-subsystem). Cutoff: <5 files, <200 LOC, no new abstractions.
`/devflow:micro`	`<description>`	Sub-30-LOC, single-file changes. The cheapest DevFlow path (~2k tokens). Use for typo fixes, single-line bug fixes, prop renames, dependency bumps, missing semicolons.
`/devflow:debug`	`[issue description]`	Investigate bugs using a structured approach that survives context resets. Tracks hypotheses, evidence, and progress across sessions.

Choosing a tier

The single biggest cost lever in DevFlow is picking the right entry point.

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.

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:

Installation

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

Install

In Claude Code, add the marketplace and install the plugin:

/plugin marketplace add AO-Cyber-Systems/devflow-claude
/plugin install devflow@aocyber

You can do the same thing through the Claude Desktop plugin UI: open the plugins panel, add the AO-Cyber-Systems/devflow-claude marketplace, then install devflow.

Verify it took:

/devflow:help

What installation registers

Enabling the plugin wires up four things automatically. You do not edit settings.json by hand.

Thing	Count	Where it lives
Skills (slash commands)	31	`plugins/devflow/skills/<name>/SKILL.md`
Subagents	13	`plugins/devflow/agents/*.md`
Hooks	15 files, 12 registered	`plugins/devflow/hooks/hooks.json`
Status line	1	declared in `plugin.json`

The runtime mirror

Skills and agents reference shared files with @~/.claude/devflow/... paths. Those @path references are resolved by Claude Code and do not interpolate ${CLAUDE_PLUGIN_ROOT}, so the plugin cannot reference its own bundled runtime directly.

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.

Hooks

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

Hooks run in a separate process, receive the tool call as JSON on stdin, and can inject context, warn, or block execution outright. They are the difference between a convention and a rule.

All hooks are declared in plugins/devflow/hooks/hooks.json and registered automatically when the plugin is enabled. Every command uses ${CLAUDE_PLUGIN_ROOT} for path resolution.

Enforcement — these can block

Hook	Event	What it does	Escape hatch
`changelog-on-tag.js`	PreToolUse (Bash)	Blocks `git tag -a vX.Y.Z` unless CHANGELOG.md has a `## [X.Y.Z]` heading and the three release manifests carry matching versions.	`DEVFLOW_SKIP_CHANGELOG_GATE=1`
`gate-commits.js`	PreToolUse (Bash)	Blocks raw `git commit` and redirects to `df-tools commit`, which preserves objective scope and task IDs and updates STATE.md. Detection is invocation-aware: heredoc bodies and quoted arguments are stripped first, so prose that merely mentions the command is not gated.	`DEVFLOW_ALLOW_RAW_COMMIT=1`
`gate-edits.js`	PreToolUse (Edit\|Write\|MultiEdit)	Strict DENY by default in ambient mode. Allows edits when a live `.planning/.skill-active` marker exists (resolved from both the local and the main checkout, so worktree-isolated agents are not denied by a marker they cannot see), when the prompt carries an override phrase, or when the env escape is set. Targets outside the project root are never gated. Severity is per-project via `gates.editGate`.	`DEVFLOW_SKIP_EDIT_GATE=1`
`gate-interactive.js`	PreToolUse (Bash)	Intercepts TTY-requiring commands and routes them to the handoff watcher rather than letting them hang on a prompt no one can answer.	—
`guard-no-progress.js`	PreToolUse (*)	Detects the same tool being called with identical arguments repeatedly: warns at 3, escalates to `ask` at 5, and resets whenever the agent varies its approach. Step limits cannot catch a stuck loop — they only fire once the whole budget is spent.	`DEVFLOW_SKIP_PROGRESS_GUARD=1`
`route-intent.js`	UserPromptSubmit	Matches the prompt against build/plan/verify/debug intent and injects a directive to route through the matching skill instead of editing code directly. Regexes require imperative form, so plain questions do not trip it.	—

gate-edits is the one you will meet

In ambient mode — DevFlow project detected, no skill running — gate-edits denies Edit, Write and MultiEdit by default. That is intentional: it is what forces work through skills instead of ad-hoc edits that leave no plan, no summary and no atomic commits.

Model profiles

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

Switching profile

/devflow:set-profile quality
/devflow:set-profile balanced
/devflow:set-profile budget

Or for one run only, without changing any files:

/devflow:build 4 --model budget

The assignment table

Generated from references/model-profiles.json:

Agent	Role	Quality	Balanced	Budget
`codebase-mapper`	Analyzes a codebase from a specific angle (stack, architecture, quality, or concerns) and writes structured findings.	sonnet	haiku	haiku
`debugger` effort xhigh	Investigates bugs using a structured scientific method with persistent session state across context resets.	opus	sonnet	sonnet
`executor` effort xhigh	Executes planned tasks with atomic git commits, handles deviations, and manages checkpoints during builds.	opus	sonnet	sonnet
`integration-checker`	Verifies that separately-built features connect properly and end-to-end user workflows actually work.	sonnet	sonnet	haiku
`job-checker`	Reviews execution plans before they run to verify they will actually achieve the objective goal.	sonnet	sonnet	haiku
`objective-researcher`	Researches how to implement an objective — discovers best practices, patterns, and pitfalls before planning begins.	opus	sonnet	haiku
`planner` effort xhigh	Creates detailed execution plans for objectives with task breakdown, dependency ordering, and built-in quality checks.	opus	opus	sonnet
`project-researcher`	Researches the domain ecosystem for a new project — stack options, architecture patterns, features, and common pitfalls.	opus	sonnet	haiku
`research-synthesizer`	Combines findings from multiple parallel research agents into a unified summary for roadmap creation.	sonnet	sonnet	haiku
`roadmapper` effort high	Creates project roadmaps by breaking requirements into ordered objectives with success criteria and dependency mapping.	opus	sonnet	sonnet
`security-auditor` effort xhigh	Scans codebase for security vulnerabilities in a specific domain: secrets, auth flows, or dependency risks.	opus	sonnet	sonnet
`ui-evaluator` effort high	Machine-judges the visual correctness of Flutter UI states by capturing each declared surface, scoring it through the offline visual-eval engine, and writing evidence the verifier consumes.	opus	sonnet	sonnet
`verifier`	Verifies that built code actually achieves the objective goal, not just that tasks were completed.	sonnet	sonnet	haiku

The assignment is not uniform, and that is the point. Under budget, planner still drops only to Sonnet while codebase-mapper drops to Haiku — a bad plan costs a whole build, a slightly worse codebase map costs a re-read.

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.

Quickstart

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

This walks the shortest path that still exercises the whole loop. Use a scratch directory — you are going to let agents write code.

1. Initialise

mkdir hello-devflow && cd hello-devflow && git init
claude --dangerously-skip-permissions

In the session:

/devflow:new-project

DevFlow asks what you’re building, researches the domain, scopes requirements into v1 and v2, and writes a roadmap. You will be asked to confirm at three gates (project, requirements, roadmap) — that is gates.confirm_* doing its job.

Status and navigation

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

Command	Arguments	What it does
`/devflow:status`	`[check \| pause \| resume]`	Consolidated status/resume/pause/health — `/devflow:status [resume\|pause\|check]`.
`/devflow:help`	—	Show available DevFlow commands and usage guide.
`/devflow:todo`	`<add\|list> [args...]`	Manage todos: capture an idea/task or view the morning standup across local + GitHub + peer sources.
`/devflow:decide`	`[<decision-id> <choice>]`	Resolve a parked decision and resume autonomous execution.
`/devflow:awareness`	`[--peer-only\|--org-only] [--quarter Q] [--product P] [--refresh [peer\|org]] [--no-fetch] [--raw]`	Show cross-repo awareness: peer view (who's working on what in this repo) and org-wide progress (Product Roadmap). Renders both views by default.
`/devflow:tui`	`[--once] [--raw] [--no-color] [--reset-only]`	Open the program-aware TUI viewer — read-only terminal UI showing parallel sessions, org tree, and active initiatives in three stacked panels. tmux-safe; reflows narrow terminals.

/devflow:status

The consolidated status command. Four behaviours, one entry point.

The loop

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

DevFlow’s lifecycle is a loop you can enter and leave at any point. Each phase produces artifacts on disk; the next phase reads them. Nothing is passed through the conversation.

new-project → discuss-objective → plan-objective → execute-objective → verify-work → milestone complete
 │ │
 └───────────────────────────────── next milestone ──────────────────────────────────────┘

1. new-project

Command: /devflow:new-project · Agents: project-researcher, research-synthesizer, roadmapper

Interviews you, researches the domain in parallel, scopes requirements into v1/v2, and orders objectives into a roadmap.

Gates and enforcement

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

DevFlow has two kinds of gate and they are easy to confuse.

Confirmation gates are workflow pauses configured in config.json — points where DevFlow asks you before proceeding.

Enforcement gates are hooks that block tool calls outright. They are not configurable per-decision; they are on or off.

Confirmation gates

{
 "gates": {
 "confirm_project": true,
 "confirm_objectives": true,
 "confirm_roadmap": true,
 "confirm_breakdown": true,
 "confirm_job": true,
 "execute_next_job": true,
 "issues_review": true,
 "confirm_transition": true
 }
}

Gate	Fires when
`confirm_project`	after `PROJECT.md` is drafted
`confirm_objectives`	after objectives are proposed
`confirm_roadmap`	after the roadmap is assembled
`confirm_breakdown`	after an objective is broken into jobs
`confirm_job`	before each job executes
`execute_next_job`	between jobs
`issues_review`	when verification finds gaps
`confirm_transition`	at milestone transitions

Turn them off as you build trust on a project. confirm_roadmap is the one worth keeping longest — a wrong roadmap costs the most to discover late.

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.

Managing the plan

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

Command	Arguments	What it does
`/devflow:objective`	`<add\|remove> [args...]`	Add or remove an objective from the current milestone roadmap.
`/devflow:milestone` type it yourself	`<new\|audit\|complete\|gaps> [args...]`	Manage milestones: start a new one, audit a finished one, complete it, or plan gap-closure objectives.
`/devflow:list-objective-assumptions` type it yourself	`[objective]`	See what Claude plans to do for an objective before it starts, so you can course-correct early.
`/devflow:sync-roadmap`	`[--dry-run] [--interactive] [--raw]`	Reconcile ROADMAP.md checkbox state against on-disk SUMMARY.md presence. Default: silently corrects drift; --dry-run previews; --interactive prompts per change.
`/devflow:cleanup` type it yourself	—	Archive old objective directories from completed milestones to reduce clutter.

Most of these are user-typed only

Plugin layout

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

plugins/devflow/
├── .claude-plugin/plugin.json manifest — name, version, statusLine
├── skills/<name>/SKILL.md user-invocable slash commands
├── agents/<agent>.md subagent prompts
├── hooks/
│ ├── hooks.json event registrations, auto-loaded
│ ├── sync-runtime.js SessionStart: mirrors devflow/ → ~/.claude/devflow/
│ └── *.js the rest of the hooks
└── devflow/ runtime, mirrored to ~/.claude/devflow/
 ├── bin/df-tools.cjs the central CLI
 ├── bin/lib/*.cjs df-tools internals
 ├── workflows/<name>.md workflow bodies, referenced via @~/.claude/devflow/...
 ├── references/<name>.md static docs agents read at runtime
 └── templates/<name>.md files copied into user projects' .planning/

Skills

A skill is a directory containing exactly one SKILL.md:

The .planning directory

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

.planning/ is the project’s memory. It is the reason DevFlow survives context resets: nothing important lives in the conversation.

.planning/
 PROJECT.md vision, context, `kind` — loaded on nearly every operation
 REQUIREMENTS.md scoped v1/v2 requirements with stable IDs
 ROADMAP.md objectives in dependency order, with checkboxes
 STATE.md decisions, blockers, position, session memory
 MILESTONES.md archive of completed milestones
 config.json workflow configuration
 state.json machine-readable position mirror

 research/ domain research from new-project
 codebase/ brownfield mapping from map-codebase
 todos/
 pending/ captured ideas awaiting work
 done/
 debug/ active debug sessions
 resolved/
 decisions/
 pending/ parked DECISION-NNN.md awaiting your answer
 milestones/ archived milestone directories

 objectives/
 NN-objective-name/
 OBJECTIVE.md goal, success criteria, `work` type
 CONTEXT.md your implementation 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, decisions, evidence
 VERIFICATION.md post-execution verification results
 UAT.md user acceptance walkthrough
 verification/ Maestro YAML flows, capture manifests

The files you will actually read

PROJECT.md

Short by design — it is loaded on nearly every operation, so every line costs context on every command. Vision, constraints, key decisions, and the project kind on frontmatter.

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.

Your first project

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

/devflow:new-project is the only command that creates .planning/ from nothing. Everything downstream reads what it writes, so it is worth understanding what comes out.

The interview

DevFlow asks what you’re building. Answer in prose — a paragraph is plenty. It uses your answer to decide how much research it needs and what kind the project is.

You can skip the interview entirely with --auto, which makes reasonable assumptions and moves straight to research. Use it when you already know exactly what you want and would rather correct a draft than answer questions.

Advanced execution

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

Command	Arguments	What it does
`/devflow:workstreams` type it yourself	`<setup\|status\|merge\|run> [args...]`	Run independent objectives in parallel using git worktrees, then merge results back.
`/devflow:flow`	`<description of the multi-step flow>`	Orchestrate a multi-step DevFlow workflow by chaining skills. Use when the user wants to invoke a sequence of skills as one ask (e.g., "build and sync to github", "research, plan, then build", "ship and announce").
`/devflow:handoff`	`<command to run interactively or via user shell>`	Hand off a TTY-required or shell-env-dependent command to the user's shell.

/devflow:workstreams

Runs independent objectives in parallel using git worktrees, then merges them back. This is a level above wave parallelism — waves parallelise jobs inside one objective; workstreams parallelise whole objectives.

Environment variables

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

Escape hatches

Prefer one-off use over exporting. An exported escape hatch is a removed gate.

DEVFLOW_ALLOW_RAW_COMMIT=1 git commit -m "..."

Variable	Effect
`DEVFLOW_ALLOW_RAW_COMMIT=1`	Allow raw `git commit`, bypassing `gate-commits`
`DEVFLOW_SKIP_EDIT_GATE=1`	Disable `gate-edits` entirely
`DEVFLOW_SKIP_CHANGELOG_GATE=1`	Allow `git tag -a` without a changelog entry
`DEVFLOW_SKIP_PROGRESS_GUARD=1`	Disable the repeated-call guard
`DEVFLOW_SKIP_INTERACTIVE_GATE=1`	Disable interactive-command interception

Session behaviour

Variable	Effect
`DEVFLOW_SKIP_CLASSIFY=1`	Skip session classification and the routing preamble
`DEVFLOW_SKIP_AWARENESS_POPULATE=1`	Skip the background awareness cache warm
`DEVFLOW_SKIP_ORG_CONTEXT=1`	Skip org-context injection at planning time
`DEVFLOW_SKIP_HANDOFF_INJECT=1`	Skip handoff result injection
`DEVFLOW_SKIP_HANDOFF_RESULTS=1`	Skip handoff result routing

Paths and overrides

Variable	Effect
`DEVFLOW_HOME`	Override the runtime mirror location (default `~/.claude/devflow`)
`DEVFLOW_AUDIT_LOG_PATH`	Where the Stop-hook audit log is written
`DEVFLOW_MODEL_PROFILE`	Force a model profile for the session
`DEVFLOW_OWNED`	Marks a path as DevFlow-managed

Handoff daemon

Variable	Effect
`DEVFLOW_HANDOFF_PID_FILE`	Override the daemon PID file location
`DEVFLOW_WATCH_ALLOW_FILE`	Path to a custom allowlist
`DEVFLOW_HANDOFF_RESULT_TTL_MS`	How long an unconsumed result stays valid

Deprecated

Variable	Status
`DEVFLOW_STRICT_EDITS=1`	No longer needed — strict is the default. Use `gates.editGate` to relax it.

Claude Code variables

Two are worth an explicit position, because tuning them looks helpful and is not.

Existing codebases

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

DevFlow’s default assumption is a greenfield project. On an existing codebase, the roadmapper needs to know what is already there or it will plan work that duplicates or contradicts it.

Map first

/devflow:map-codebase

This dispatches codebase-mapper agents in parallel, each analysing a different angle:

Stack — languages, frameworks, build tooling, dependency posture.
Architecture — module boundaries, data flow, entry points.
Quality — test coverage shape, conventions actually followed (not the ones in the style guide).
Concerns — things that will bite: coupling, dead code, risky patterns.

Findings land in .planning/codebase/.

The intent model

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

Uniform rigor is wrong in both directions: it over-tests throwaway spikes and under-tests payment paths. DevFlow’s intent model derives the right posture from two declarations.

The two axes

Project kinds

api app library ui-lib cli plugin

Work types

feature port refactor foundation bugfix prototype spike

kind is declared once, on PROJECT.md frontmatter. It says what sort of software this is.

work is declared per objective, on OBJECTIVE.md frontmatter, or inherited from PROJECT.md’s default_work. It says what sort of change this objective is.

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.

Integrations and analysis

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

Command	Arguments	What it does
`/devflow:gh-sync`	`[objectives\|release <tag>\|status\|<objective_id>]`	Sync DevFlow planning state to GitHub — create/update objective issues, generate release notes, or push a single objective's state (body + sticky comment + Project v2 fields).
`/devflow:initiatives`	`[sync [--initiative <slug>] [--project-id <id>] [--force]] \| [list [--home <path>]] \| [show <slug>]`	Manage strategic initiative context — sync GitHub Epics to disk, list cached initiatives, or show a single initiative body. Planner reads these at plan time.
`/devflow:ui-eval`	`[objective number or manifest path]`	Run the UI visual-evaluation pipeline on a Flutter surface or objective: capture each declared UI state, score it through the offline visual-eval engine, and write machine-judged evidence the verifier consumes.
`/devflow:security-audit`	`[optional: path scope like 'src/api' or focus filter like 'secrets-only', 'auth-only', 'deps-only']`	Scan the codebase for security vulnerabilities — checks for secrets, auth flaws, dependency risks, and OWASP Top 10 issues.
`/devflow:map-codebase`	`[optional: specific area to map, e.g., 'api' or 'auth']`	Analyze an existing codebase to understand its stack, architecture, conventions, and concerns before starting new work.

/devflow:gh-sync

Pushes planning state to GitHub. One-way: planning files stay authoritative, GitHub is derivative.

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.

Waves and checkpoints

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

Wave-based parallelism

The planner records a dependency position on each job. At execution time, jobs are grouped into waves: everything in a wave is independent of everything else in that wave, so it can run concurrently.

Wave 1: job 4-01 job 4-02 job 4-03 ← no dependencies, run together
 │ │ │
 └──────────┴──────────┘
Wave 2: job 4-04 ← depends on wave 1 output

Each job goes to its own executor subagent with a fresh context window. This is not just a speed optimisation — it is the mechanism from context rot. Three jobs in a wave means three clean windows rather than one window carrying all three jobs’ reconnaissance.

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:

Settings

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

Command	Arguments	What it does
`/devflow:settings` type it yourself	—	Configure which agents run, which AI models they use, and how the workflow behaves.
`/devflow:set-profile` type it yourself	`<profile>`	Switch between quality, balanced, and budget model profiles to control cost and capability.

Both are user-typed only — Claude cannot fire them, because they rewrite config.json and change cost characteristics for everything downstream.

/devflow:set-profile

/devflow:set-profile quality
/devflow:set-profile balanced
/devflow:set-profile budget

Switches the model tier for every agent at once. The mapping is not uniform — each agent has its own per-profile assignment, so budget does not simply mean “Haiku everywhere”:

State and memory

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

DevFlow’s durability claim is simple: the things worth remembering were never in the context window, so losing the window loses nothing.

What is remembered

Thing	Where	Survives
Vision, constraints, `kind`	`PROJECT.md`	everything
Requirements with IDs	`REQUIREMENTS.md`	everything
Objectives and completion	`ROADMAP.md`	everything
Decisions and rationale	`STATE.md`	everything
Open blockers	`STATE.md`	everything
Position in the plan	`STATE.md` + `state.json`	everything
What each job did	`SUMMARY.md`	everything
Verification evidence	`VERIFICATION.md`	everything
Debug hypotheses and evidence	`debug/`	everything
The conversation	context window	nothing

Reading and writing state

State is manipulated through df-tools rather than by editing files, so the markdown and its JSON mirror stay consistent.

Context discipline

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

DevFlow’s context guidance comes from an audit of roughly 93 million tokens of real message blocks. The figures below are measured, not estimated.

Where the window actually goes

Component	Share	Who produces it
Tool results (text)	59.3%	the environment, read back in
Tool-call inputs	33.8%	the agent — file bodies, heredocs, patches
Assistant text	5.5%	prose to the user
Images	1.5%	screenshots

Two tools account for 94% of tool-result tokens:

Troubleshooting

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

A hook blocked my command

The model receives the denial reason and usually corrects itself. When you need to override deliberately:

DEVFLOW_ALLOW_RAW_COMMIT=1 git commit -m "..."

Every gate and its escape hatch is listed on gates and enforcement. Prefer a one-off prefix over an export — an exported escape hatch is a gate you removed.

If you are overriding the same gate repeatedly, log it so the friction is measurable rather than anecdotal:

Contributing

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

DevFlow is MIT licensed and developed in the open at AO-Cyber-Systems/devflow-claude.

Development install

git clone https://github.com/AO-Cyber-Systems/devflow-claude.git

/plugin marketplace add /absolute/path/to/devflow-claude
/plugin install devflow@aocyber

The plugin directory is the source of truth for distribution; there is no npm publish step.

Tests

npm test

Node’s native test runner against .test.cjs and .test.js files adjacent to their source. There is no lint command.

plugins/devflow/devflow/bin/df-tools.test.cjs
plugins/devflow/devflow/bin/lib/*.test.cjs
plugins/devflow/hooks/*.test.js

Hooks are tested like any other module — they are plain Node scripts reading JSON on stdin.