DevFlow AI

Official registry Developer tools

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-evidence asks 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).

NPM package @devflowai/cli
Claude Code
claude mcp add devflow-ai -- npx -y @devflowai/cli@0.2.1 mcp
JSON configuration (Claude Desktop, Cursor, VS Code)
{
    "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
  1. DevFlow AI
  2. Why DevFlow?
  3. How it works
  4. Core capabilities
  5. Quickstart
  6. What does the evidence look like?
  7. Supported stacks
  8. Developer workflows
  9. Using DevFlow with Claude Code, Codex, or another agent
  10. Security model
  11. Architecture
  12. Development and testing
  13. Documentation
  14. Contributing
  15. License and maintainer

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 problemWhat DevFlow adds
Requirements are scattered across tickets and conversationsTask contracts with explicit, validated requirements and acceptance criteria
An agent overlooks edge cases or existing conventionsRepository-aware analysis and reviewable implementation plans
Tests exist but do not cover the requested behaviorAcceptance-criteria-to-test traceability and baseline/after-change evidence
Reviewers receive a large diff without contextEvidence-based reports with changes, test results, findings, and unresolved checks
Different projects use different test toolsStack-specific verification adapters behind one CLI and workflow
AI-generated changes are applied without guardrailsHuman 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
  1. Describe the task. Supply YAML, JSON, Markdown, or a GitHub issue. DevFlow validates the task contract and highlights incomplete criteria.
  2. Analyze the project. Discover relevant modules, source files, contracts, engineering rules, dependencies, and potential contradictions.
  3. Approve the plan. Review proposed files, risks, constraints, and test strategy before code changes begin.
  4. 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.
  5. Implement with guardrails. Apply reviewable, scope-checked changes on a dedicated Git branch. Changes and bounded repair attempts require approval.
  6. Verify with real tools. Run authorized build, test, lint, type-check, and compatible contract checks using the repository's actual toolchain.
  7. 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-evidence asks 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 oasdiff and buf tools 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):

CriterionVerification evidenceStatus
AC-01: Valid order cancellationJUnit test executed successfullyVerified
AC-02: Paid orders cannot be cancelledNegative test executed successfullyVerified
AC-03: Existing API clients remain compatibleNo integration evidence availableUnverified
AC-04: Audit trail meets business policyManual review requiredManual

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

EcosystemDetection and conventionsVerification
JavaMaven, Gradle, Spring Boot, multi-module projectsJUnit, TestNG, compiler output, Checkstyle, SpotBugs and other configured tools
JavaScript / TypeScriptnpm, pnpm, Yarn, Bun; Express, NestJS, React, Next.js, Angular, VueJest, Vitest, ESLint, TypeScript, Playwright and other configured tools
Pythonpip, uv, Poetry; Django, Flask, FastAPIpytest, unittest, Ruff, flake8, mypy and other configured tools
Mixed repositoriesPer-module stack discovery and shared contractsConsistent 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

ModeExamplePurpose
Assistdevflow plan --task task.yamlAnalyze and plan without writing code
Testdevflow test --task task.yamlCreate and approve tests; record baseline evidence
Implementdevflow run --task task.yamlGenerate tests and implementation through human approvals
Verifydevflow verifyExecute the configured quality gates
Reviewdevflow review --task task.yaml --base mainAssess changes, evidence, risks, and rule violations
Contract diffdevflow contracts diffExamine OpenAPI/Protobuf compatibility; see CLI help for required inputs
Change impactdevflow contracts impact api/openapi.yamlList the consumers of each breaking contract change
Tracedevflow 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.

  1. The agent validated the task and started an implement run; DevFlow paused at each model request (AGENT_INPUT_REQUIRED) and the agent answered with devflow_agent_respond. One answer that did not match the schema was refused (AGENT_ANSWER_INVALID) and sent again.
  2. 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.
  3. 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).
  4. 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]
PackagePurpose
@devflowai/coreTask schemas, adapter ports, security policy, execution and evidence model
@devflowai/workflowState machine, approvals, implementation steps, history and reports
@devflowai/contextRepository discovery, code context and rules
@devflowai/aiAnthropic, OpenAI, Fake/Replay providers, usage and budget controls
@devflowai/adapter-javaJava-specific build, test and quality-gate intelligence
@devflowai/adapter-javascriptJavaScript/TypeScript-specific tooling and result parsing
@devflowai/adapter-pythonPython-specific discovery and verification
@devflowai/contractsOpenAPI and Protobuf compatibility analysis
@devflowai/githubGitHub issue, review and PR integration
@devflowai/cliDeveloper 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

Contributing

Contributions are welcome: bug reports, reproducible test cases, adapter improvements, documentation, security hardening, and real-world examples.

  1. Read CONTRIBUTING.md and the security policy.
  2. Open an issue to discuss a significant change.
  3. 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.