DevFlow AI
Evidence-driven AI coding: plans, tests and red/green verification for every change.
What can you do with DevFlow AI?
- Task contracts: YAML, JSON, and Markdown input; normalized IDs; acceptance criteria;
- Repository intelligence: context discovery, rule precedence, BM25 relevance ranking,
- AI-assisted engineering: requirements analysis, clarification questions, implementation
- Evidence-first verification: normalized test results, baseline comparison, regression
- Evidence-seeking review:
devflow review --seek-evidenceasks the model for a probe test - Security and control: workspace trust, command fingerprints, scoped file changes, protected
- GitHub workflows: issues as tasks, pull request reviews, opt-in comments/check runs, draft PR
- Contract compatibility: built-in OpenAPI and Protocol Buffers compatibility checks, with
Install
Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).
@devflowai/cliclaude mcp add devflow-ai -- npx -y @devflowai/cli@0.2.1 mcp
{
"mcpServers": {
"devflow-ai": {
"command": "npx",
"args": [
"-y",
"@devflowai/cli@0.2.1",
"mcp"
]
}
}
}
Documentation
From the project's README on GitHub, refreshed weekly. Links open on GitHub.
Contents
DevFlow AI
Engineering quality and verifiable delivery for AI-assisted software development.
AI-generated code should come with evidence, not just confidence.
DevFlow AI is an open-source, language-agnostic engineering workflow framework that turns software development tasks into planned, tested, reviewable changes. It brings requirements, acceptance criteria, project conventions, controlled execution, and verification evidence into one workflow.
The goal isn't to replace developers or coding agents. It's to make AI-assisted software delivery more reliable, traceable, and reviewable.
AI proposes. Deterministic tools verify. Developers stay in control.
Get started · See how it works · Supported stacks · Example report · Demo · Contribute
Why DevFlow?
Claude Code, Codex, GitHub Copilot, and other coding assistants can implement features quickly. But a successful build—or an agent saying "done"—doesn't establish that every acceptance criterion was addressed.
DevFlow provides a repeatable engineering process around those changes:
| Common problem | What DevFlow adds |
|---|---|
| Requirements are scattered across tickets and conversations | Task contracts with explicit, validated requirements and acceptance criteria |
| An agent overlooks edge cases or existing conventions | Repository-aware analysis and reviewable implementation plans |
| Tests exist but do not cover the requested behavior | Acceptance-criteria-to-test traceability and baseline/after-change evidence |
| Reviewers receive a large diff without context | Evidence-based reports with changes, test results, findings, and unresolved checks |
| Different projects use different test tools | Stack-specific verification adapters behind one CLI and workflow |
| AI-generated changes are applied without guardrails | Human approvals, scoped edits, command policies, and optional container isolation |
For developers: less manual coordination and more useful review evidence. For teams: a consistent way to evaluate AI-assisted changes across projects. These are product goals, not measured performance guarantees.
How it works
flowchart LR
A[Task / GitHub issue] --> B[Requirements & acceptance criteria]
B --> C[Repository context & project rules]
C --> D[Implementation plan]
D --> E{Developer approval}
E -->|Approved| F[Tests & baseline evidence]
F --> G[Controlled implementation]
G --> H[Build, test & quality gates]
H --> I[Evidence report & review]
E -->|Changes requested| D
- Describe the task. Supply YAML, JSON, Markdown, or a GitHub issue. DevFlow validates the task contract and highlights incomplete criteria.
- Analyze the project. Discover relevant modules, source files, contracts, engineering rules, dependencies, and potential contradictions.
- Approve the plan. Review proposed files, risks, constraints, and test strategy before code changes begin.
- Design tests. Associate automated tests with acceptance criteria; collect baseline evidence. New feature tests may fail meaningfully before implementation, while existing regression tests may already pass.
- Implement with guardrails. Apply reviewable, scope-checked changes on a dedicated Git branch. Changes and bounded repair attempts require approval.
- Verify with real tools. Run authorized build, test, lint, type-check, and compatible contract checks using the repository's actual toolchain.
- Review the evidence. Distinguish what passed, failed, was skipped, was not executed, or remains unverified. Prepare a PR when explicitly authorized.
The LLM proposes analyses, plans, tests, and edits. DevFlow's control layer enforces approvals, scope, security, and budgets. Its evidence layer derives verification results from executed tools—not the model's confidence.
Core capabilities
- Task contracts: YAML, JSON, and Markdown input; normalized IDs; acceptance criteria; constraints; definition of done; schema validation.
- Repository intelligence: context discovery, rule precedence, BM25 relevance ranking, Tree-sitter outlines, and read-only OpenAPI/Protobuf discovery.
- AI-assisted engineering: requirements analysis, clarification questions, implementation planning, test design, approved edits, bounded repair, and review.
- Evidence-first verification: normalized test results, baseline comparison, regression detection, acceptance-criteria coverage, and machine-readable/human-readable reports.
- Evidence-seeking review:
devflow review --seek-evidenceasks the model for a probe test per AI finding and runs it in a temporary git worktree; only a failing assertion confirms a finding, anything else leaves it unverified. - Security and control: workspace trust, command fingerprints, scoped file changes, protected paths, audit logs, redaction, timeouts, and optional network-restricted Docker execution.
- GitHub workflows: issues as tasks, pull request reviews, opt-in comments/check runs, draft PR creation, and a GitHub Action with fork-safe workflow patterns.
- Contract compatibility: built-in OpenAPI and Protocol Buffers compatibility checks, with
optional
oasdiffandbuftools when installed and approved, and cross-language change impact: the Spring, TypeScript, Java and Python consumers of each breaking change. - Observability export (opt-in): an OpenTelemetry-compatible trace per run (steps, model calls, gates), metadata only, written as OTLP/JSON or sent to your OTLP/HTTP collector.
- Language independence: Java, JavaScript/TypeScript, Python, and mixed-language repositories use one common workflow.
- Extensible adapters: external language adapters as user-installed plugins (
devflow plugins), checked against a versioned adapter API and pinned by hash.
Quickstart
Requirements
- Node.js 22.12+ (22.13+ and pnpm 10 to build from source)
- A supported project toolchain for the checks you want to run (for example, Java/Maven, Node.js/npm, or Python/pytest)
- For model-assisted steps: an Anthropic or OpenAI API key, or none in agent mode, where your coding agent answers DevFlow's model requests (see below)
- Optional: Docker for the container execution backend
1. Install
From npm (@devflowai/cli, published from version 0.2.0 with
provenance):
npm install -g @devflowai/cli
devflow --help
Or without installing: npx @devflowai/cli --help. Releases and their notes are on
GitHub; see also the
changelog.
From source
git clone https://github.com/mohamedyangui/DevFlow.git
cd DevFlow
pnpm install --frozen-lockfile
pnpm build
node packages/cli/dist/bin.js --help
Clone with --branch vX.Y.Z for a release, or without it for the development version on
main. From a source checkout, devflow in the examples below means
node /absolute/path/to/DevFlow/packages/cli/dist/bin.js. You can create a local shell alias,
for example:
alias devflow='node /absolute/path/to/DevFlow/packages/cli/dist/bin.js'
Or, in PowerShell:
function devflow { node 'D:\DevFlow\packages\cli\dist\bin.js' @args }
Adjust the path to your checkout. Run the commands from the target application's repository root, not the DevFlow source directory.
2. Initialize a project and validate a task
devflow init
devflow task validate tasks/add-pagination.yaml
Example task (tasks/add-pagination.yaml):
id: TASK-142
title: Add pagination to the orders API
requirements:
functional:
- id: FR-1
text: GET /api/orders accepts page and size query parameters.
nonFunctional:
- id: NFR-1
text: Requests without pagination parameters keep their existing behavior.
category: compatibility
acceptanceCriteria:
- id: AC-1
given: 25 orders exist
when: A client requests page 2 with size 10
then: The response includes orders 11 to 20
covers: [FR-1]
testLevel: integration
- id: AC-2
statement: Requests without pagination parameters retain their existing response format.
covers: [NFR-1]
testIntent: regression
constraints:
- Preserve the existing OrderDto JSON shape.
testing:
levels: [unit, integration]
definitionOfDone:
- All required verification gates pass.
Additional sample task files: examples/tasks/.
3. Analyze and approve a plan
Configure a supported provider using its environment variable (for example, ANTHROPIC_API_KEY or
OPENAI_API_KEY). Select a valid model ID for your account. In the examples, replace
YOUR_MODEL_ID and RUN_ID with actual values.
devflow plan --task tasks/add-pagination.yaml --model YOUR_MODEL_ID
# DevFlow shows the run ID and pauses for plan approval.
# Review .devflow/runs/RUN_ID/artifacts/plan.md before continuing.
devflow approve RUN_ID
devflow report RUN_ID
analyze and plan do not run project build commands or modify source files.
4. Implement and verify
Review the workspace configuration and trust only repositories you own or otherwise trust. Every executable verification command has its own approval fingerprint.
devflow trust
devflow run --task tasks/add-pagination.yaml --model YOUR_MODEL_ID
# Follow the returned run ID and approval checkpoints:
# Review the pending stage, then approve when instructed.
devflow status RUN_ID
devflow approve RUN_ID
# Repeat status/approval only for the next requested checkpoint.
devflow report RUN_ID
Approval steps can stop for clarification or command authorization; do not blindly repeat them. Use
devflow status RUN_ID, devflow resume RUN_ID, and the displayed instructions to proceed safely.
devflow verify can also run the project's approved quality gates independently.
What does the evidence look like?
An illustrative acceptance-criteria matrix (not the output of a specific DevFlow run):
| Criterion | Verification evidence | Status |
|---|---|---|
| AC-01: Valid order cancellation | JUnit test executed successfully | Verified |
| AC-02: Paid orders cannot be cancelled | Negative test executed successfully | Verified |
| AC-03: Existing API clients remain compatible | No integration evidence available | Unverified |
| AC-04: Audit trail meets business policy | Manual review required | Manual |
A passing test is evidence about the behavior it exercises, not proof of complete business
correctness. A final verdict is verified only when the framework's required gates and automated
acceptance criteria meet the verification policy. Unexecuted checks never become passes, and AI-only
review findings are not presented as confirmed defects.
DevFlow stores structured run artifacts under .devflow/runs/ and produces JSON and Markdown
reports so developers can inspect the reasoning trail and reproduce the checks.
Supported stacks
| Ecosystem | Detection and conventions | Verification |
|---|---|---|
| Java | Maven, Gradle, Spring Boot, multi-module projects | JUnit, TestNG, compiler output, Checkstyle, SpotBugs and other configured tools |
| JavaScript / TypeScript | npm, pnpm, Yarn, Bun; Express, NestJS, React, Next.js, Angular, Vue | Jest, Vitest, ESLint, TypeScript, Playwright and other configured tools |
| Python | pip, uv, Poetry; Django, Flask, FastAPI | pytest, unittest, Ruff, flake8, mypy and other configured tools |
| Mixed repositories | Per-module stack discovery and shared contracts | Consistent result statuses across modules |
Why adapters? DevFlow does not need to teach Claude Code or Codex how to write Java or TypeScript. An adapter discovers the stack, selects constrained verification commands, parses machine-readable results, and maps evidence back to the shared task contract. Language-specific tools stay behind one language-independent workflow.
See language adapter specification and example repositories.
Developer workflows
| Mode | Example | Purpose |
|---|---|---|
| Assist | devflow plan --task task.yaml | Analyze and plan without writing code |
| Test | devflow test --task task.yaml | Create and approve tests; record baseline evidence |
| Implement | devflow run --task task.yaml | Generate tests and implementation through human approvals |
| Verify | devflow verify | Execute the configured quality gates |
| Review | devflow review --task task.yaml --base main | Assess changes, evidence, risks, and rule violations |
| Contract diff | devflow contracts diff | Examine OpenAPI/Protobuf compatibility; see CLI help for required inputs |
| Change impact | devflow contracts impact api/openapi.yaml | List the consumers of each breaking contract change |
| Trace | devflow trace <run> [--otlp] | Export a run's trace (OTLP/JSON, metadata only) to a file or a collector |
See the CLI reference for flags, permissions, run states, budgets, and exit codes.
Use GitHub issues as tasks
devflow plan --issue 142 --repo owner/repository --model YOUR_MODEL_ID
DevFlow reads the issue as untrusted task data. It does not treat issue text as permission to run commands or access secrets.
Review a pull request
Check out the PR's head commit first; DevFlow does not fetch and execute untrusted pull request code on its own.
devflow review --task tasks/task.yaml --pr 57 --model YOUR_MODEL_ID
# Publishing is opt-in:
# devflow review --task tasks/task.yaml --pr 57 --model YOUR_MODEL_ID --publish comment
PR code from forks is not executed by default. Publishing findings requires explicit authorization and appropriate GitHub permissions.
Prepare a draft PR
devflow pr create RUN_ID # preview only
devflow pr create RUN_ID --yes # explicitly push the DevFlow branch and open a draft PR
DevFlow never force-pushes or merges automatically. The opt-in draft PR operation can push the run branch; this is deliberately separate from local implementation.
GitHub Actions
The repository includes a composite action.yml plus examples for
fork-safe verification and
gated AI review. Pin the action to a reviewed
commit SHA, configure approved command fingerprints, and keep untrusted-code execution separate from
jobs holding model API keys.
For setup details and required permissions, see the GitHub Action specification.
Using DevFlow with Claude Code, Codex, or another agent
DevFlow can complement an existing coding agent: the agent implements, while DevFlow organizes requirements and provides standardized verification evidence. Agents with terminal access can invoke the DevFlow CLI when the developer authorizes the relevant commands.
For example, an instruction to a coding agent could be:
Use DevFlow to validate TASK-142, inspect the project's engineering rules, propose a plan for my review, implement the approved change, and show the DevFlow verification report. Do not bypass approval checkpoints or claim unexecuted checks passed.
Use DevFlow as MCP tools
devflow mcp serves DevFlow to MCP clients over stdio: task validation, analysis and planning,
test and implement runs, run status, reports, approved verification gates, review and contract
diffs. Approvals are not tools: plans, tests, code changes, workspace trust and commands are
approved by the developer in a terminal.
No API key is needed in a coding agent's session: by default the server runs in agent mode (ADR 0027), where the agent itself answers DevFlow's model requests and DevFlow checks the answers as it checks a model's. For Claude Code:
claude mcp add devflow -- npx -y @devflowai/cli mcp
From a source checkout, after pnpm build:
claude mcp add devflow -- node /absolute/path/to/DevFlow/packages/cli/dist/bin.js mcp.
Codex, other clients, a .mcp.json example, Windows paths and what is validated (a real
Claude Code session implemented a task this way; Codex has not been tried) are in the
MCP specification. devflow init --provider agent writes a configuration
for agent mode.
Demo: a coding agent through DevFlow
A real session, recorded on 2026-11-12: a coding agent connected to devflow mcp in agent mode
implemented a small task in a JavaScript project (Vitest) with three acceptance criteria, one
behaviour to keep and two to add.
- The agent validated the task and started an implement run; DevFlow paused at each model
request (
AGENT_INPUT_REQUIRED) and the agent answered withdevflow_agent_respond. One answer that did not match the schema was refused (AGENT_ANSWER_INVALID) and sent again. - The developer approved the plan in a terminal, then rejected the first test design with feedback (it tested more than the criteria); the agent rewrote the tests.
- The developer approved the revised tests by hash and allowed the test command once by fingerprint. Baseline: the regression test passed, the two feature tests failed on an assertion (red).
- The agent wrote the change; the developer approved it by hash. After the change all four tests passed (green), and the report gave verdict: verified, with 0 model tokens billed to DevFlow.
The agent could not approve anything: the MCP server has no approval tool. The changes stayed
on the local branch devflow/TASK-7; nothing was pushed. The demo project is a disposable
workspace and is not part of this repository.
Security model
DevFlow is designed around least privilege and explicit approval:
- No arbitrary model-generated shell execution. The model can select only validated commands from an adapter-produced catalog; command policy and approvals control execution.
- Scoped source edits. Changes are checked against the approved plan, protected paths, repository boundaries, and content hashes.
- Workspace trust. Repository configuration does not grant itself permission to execute commands. Trust and command fingerprints are stored outside the repository.
- Secret handling. Sensitive files are excluded from model context where possible; outputs are screened and redacted. Redaction lowers risk but is not a guarantee of perfect secret detection.
- Auditable results. Actual execution records determine statuses; suspicious AI review findings remain unverified without supporting deterministic evidence.
- Optional Docker backend. Restricted execution uses a configured container with network isolation and resource limits. Isolation reduces risk but does not eliminate it.
- Human-controlled delivery. Approvals precede significant changes; PR publication is opt-in; automatic merge and force-push are prohibited.
Never run a repository's build or tests unless you trust the code and its dependencies. Build scripts and plugins may execute code. See the full security model and security policy.
Architecture
flowchart TB
CLI[CLI / SDK / GitHub Action] --> WF[Workflow engine]
WF --> CORE[Task contracts / policies / evidence]
WF --> CONTEXT[Repository context]
WF --> AI[LLM gateway]
WF --> CONTRACTS[OpenAPI / Protobuf checks]
CORE --> VERIFY[Policy-gated executor]
VERIFY --> JAVA[Java tools]
VERIFY --> JS[JS / TS tools]
VERIFY --> PY[Python tools]
VERIFY --> REPORT[Verification report]
| Package | Purpose |
|---|---|
@devflowai/core | Task schemas, adapter ports, security policy, execution and evidence model |
@devflowai/workflow | State machine, approvals, implementation steps, history and reports |
@devflowai/context | Repository discovery, code context and rules |
@devflowai/ai | Anthropic, OpenAI, Fake/Replay providers, usage and budget controls |
@devflowai/adapter-java | Java-specific build, test and quality-gate intelligence |
@devflowai/adapter-javascript | JavaScript/TypeScript-specific tooling and result parsing |
@devflowai/adapter-python | Python-specific discovery and verification |
@devflowai/contracts | OpenAPI and Protobuf compatibility analysis |
@devflowai/github | GitHub issue, review and PR integration |
@devflowai/cli | Developer command-line interface |
Read the architecture overview, ADRs, and technical specifications.
Development and testing
pnpm install --frozen-lockfile
pnpm check # build, typecheck, lint, formatting, unit / repository tests
pnpm test:examples # real-toolchain integration tests; requires matching toolchains
The repository's GitHub Actions CI runs a Node.js matrix on Ubuntu and Windows. Some integration tests require local Java/Python toolchains or model API credentials and may be skipped in the default suite. Consult the CI logs for the current executed and skipped test counts.
Documentation
- Getting started and CLI specification
- Task contracts
- Project configuration
- Language adapters
- Context engine
- Verification and evidence
- Security model
- GitHub Action
- Examples
- Roadmap
Contributing
Contributions are welcome: bug reports, reproducible test cases, adapter improvements, documentation, security hardening, and real-world examples.
- Read CONTRIBUTING.md and the security policy.
- Open an issue to discuss a significant change.
- Include tests and verification evidence in your pull request.
For security concerns, follow SECURITY.md rather than publishing sensitive details in a public issue.
License and maintainer
Licensed under Apache License 2.0.
Created and maintained by Mohamed Yangui.
Build with AI. Verify with evidence. Keep developers in control.
Frequently asked questions
What is DevFlow AI?
Evidence-driven AI coding: plans, tests and red/green verification for every change.
How do I install DevFlow AI?
It runs on your machine. In Claude Code: claude mcp add devflow-ai -- npx -y @devflowai/cli@0.2.1 mcp. For other clients, paste the JSON configuration from this page into their MCP settings.
Does DevFlow AI need an API key?
Its registry entry lists no required key or secret. Some features may still need an account with the service it connects to.
Is DevFlow AI open source?
Yes. Its code is on GitHub under the Apache-2.0 license.
Who maintains DevFlow AI?
It is published by mohamedyangui. AI.tn lists it but does not maintain or endorse it.
From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.