Architecture on 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:

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.

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: