Skip to content
tjsasakiflnPublic

About

PR governance for AI-generated code. Reduce risk, enforce evidence, and produce auditable trails before AI-assisted changes reach review.

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

67 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Devflow — Local AI Coding Governance

Engineer AI-generated code with auditable evidence, pre-PR risk reports, and engineering guardrails. Runs locally. No LLM API keys required. No third-party review SaaS.

Maintainer and collaboration: Tiago Sasaki | Civil engineering, software systems and construction technology | LinkedIn. Interested in international remote collaboration across engineering software, developer tooling and technical product development.

npm version npm install node >= 18 License: MIT local-first


Use Devflow if…

  • You're receiving AI-generated PRs with no evidence of testing or review — Devflow makes the invisible visible before code lands.
  • You use Claude Code, Cursor, or Copilot and want guardrails before code reaches PR — audit locally, fail fast, fix before push.
  • You need a risk report to paste into a PR before asking for human review — devflow review-pr generates markdown you can attach.
  • You work in a legacy codebase and AI agents keep breaking architecture boundaries — Devflow enforces spec-driven coding and catches architectural drift.
  • You're a solo founder who ships fast but worries about accumulating technical debt — relaxed mode keeps you moving without losing the audit trail.
  • You want CI/CD integration for AI code governance without sending code to LLM providers or third-party review SaaS; when run on GitHub Actions, code is processed inside the configured CI runner — Devflow runs locally and also works in GitHub Actions.
  • Your team confuses "the tests pass" with "the code is well-engineered" — Devflow checks evidence, not just green CI.
  • You need an audit trail to show compliance, not just a green CI checkmark — every decision is logged with hashes, actor identity, and git context.

Quick Commands Per Use Case

You Need This Run That
Audit AI-generated changes before commit npx devflow audit
Generate a PR risk report npx devflow review-pr --format markdown
Full AI governance workflow npx devflow feature new → feature complete → gatekeep
Run AI code audit in CI See GitHub Actions section
Adversarial review of a feature npx devflow adversarial-review <id>

What Devflow Does

  • Audits AI-generated changes before they reach a PR — devflow audit scans local changes, checks against evidence requirements, and produces a pre-commit risk snapshot.
  • Enforces a spec-driven workflow before AI agents write code — no code before requirements, no merge before review.
  • Runs 25 Definition of Done checks including integrity consolidation across TypeScript, JavaScript, Python, Go, Rust, PHP, and Java.
  • Generates structured implementation prompts for AI agents so they produce traceable, governed output.
  • Adversarial review across 12 attack vectors — including bypass attempts, hallucination detection, and architecture boundary violation checks.
  • Independent gatekeeper review — implementer cannot be approver (Constitution C12).
  • Generates PR risk reports in HTML or markdown format that you can paste into any pull request.
  • Integrates with CI via GitHub Actions — gates run automatically on every PR.
  • Produces auditable evidence — every decision logged with actor identity, content hashes, git context, and timestamps.
  • Configurable risk tolerance: relaxed (solo builder), moderate (team), strict (release).

What Devflow Does NOT Do

  • Does not guarantee bug-free code
  • Does not replace human code review
  • Does not prevent deliberate process bypass
  • Does not write code for you — it prepares the ground so AI-generated code has evidence
  • Does not require LLM API keys or third-party review SaaS accounts — runs fully local by default; when used in GitHub Actions, code is processed inside the CI runner. Devflow has no SaaS backend, no telemetry, and never sends code to LLM providers or third-party review services.

Privacy: Devflow has no SaaS backend, collects no telemetry, and never sends your code to external services. CI artifact upload is optional and controlled by your workflow configuration. See docs/local-first.md for details.


How Devflow Compares

Tool Cloud Required? Evidence Enforcement? Pre-PR Risk Report? Adversarial Review?
Devflow No — fully local Yes Yes Yes (12 vectors)
ESLint / Biome No No — style only No No
CodeRabbit Yes No — post-hoc Partial No
Cursor Rules No No — advisory No No
Claude Code alone No No — trusts output No No
CI-only checks No No — green check only No No

Devflow is not a linter. It is not a CI pipeline. It is an engineering governance framework that makes AI-generated code auditable, evidence-backed, and ready for human review.


Quick Start

Recommended: Install as project dependency

Devflow is a recurring governance tool — install it locally so it's always available:

npm install --save-dev @tjsasakinpm/devflow
npx devflow install

# Then use via npx:
npx devflow audit
npx devflow feature new "my-feature"
npx devflow next
npx devflow doctor

Set up npm scripts (optional but recommended)

After installing, add to your package.json scripts for even shorter commands:

"scripts": {
  "devflow": "devflow",
  "devflow:status": "devflow status",
  "devflow:doctor": "devflow doctor",
  "devflow:audit": "devflow audit",
  "devflow:next": "devflow next"
}

Then: npm run devflow:status, npm run devflow:audit, etc.

Try without installing (one-off evaluation)

For a single evaluation run without modifying package.json:

npx -y @tjsasakinpm/devflow@latest install
npx -y @tjsasakinpm/devflow@latest audit
npx -y @tjsasakinpm/devflow@latest feature new "my-feature"

Every command must use the full npx -y @tjsasakinpm/devflow@latest prefix — the bare devflow command is only available after local or global install.

Full demo ->


Claude Code Integration (/devflow)

Installing the npm package and enabling the /devflow slash command in Claude Code are two separate things:

  • npm install --save-dev @tjsasakinpm/devflow installs the CLI.
  • devflow install creates .claude/commands/devflow.md, which registers the /devflow slash command.

The /devflow command does not come from npm — it comes from the file .claude/commands/devflow.md that Devflow creates in your project. Claude Code discovers project commands at startup by scanning .claude/commands/.

If /devflow doesn't appear: restart or reload Claude Code so it discovers the new .claude/commands/ directory. Claude Code only scans for project commands on launch.

When you run /devflow in Claude Code, it proxies your arguments to the Devflow CLI using the correct invocation prefix for your setup (local, global, or remote npx).


Three Setup Paths

Solo Builder

Working alone? Devflow becomes your second pair of eyes.

npx devflow config set riskTolerance relaxed
npx devflow config set reviewMode solo-hardened

Self-approval OK. Adversarial review compensates for missing reviewer. Lint and coverage become advisory — still visible, not blocking.

Team

Standard team setup with role segregation.

npx devflow install --review-mode independent

Implementer != approver enforced (Constitution C12). Independent gatekeep required before merge.

Strict / Release

CI required. All gates blocking. Full audit trail.

npx devflow config set executionMode strict
npx devflow config set riskTolerance strict

Unknown actors blocked. Every check must pass. Implementation log must be complete.


Commands

All commands are STABLE unless marked otherwise.

Command Description
devflow audit Audit AI-generated changes and produce pre-commit risk snapshot
devflow ai init Configure AI provider (Claude Code, Cursor, Copilot)
devflow install Guided first-run setup
devflow init Initialize Devflow (script-friendly, no onboarding)
devflow status [--json] [--verbose] Show project state, confidence, blockers
devflow next [--json] [--diagnose] Recommend next best action
devflow config set <key> <value> Configure reviewMode, executionMode, riskTolerance
devflow feature new <name> Create feature workspace with templates
devflow feature prompt <id> [--copy] [--save] Generate AI implementation prompt
devflow feature complete <id> Run 25 Definition of Done checks
devflow gatekeep <id> --approve|--reject Independent gatekeeper review
devflow adversarial-review <id> Adversarial review — 12 attack vectors
devflow adversarial-review-ai <id> AI-assisted adversarial review (LLM-powered)
devflow review-pr [--base] [--output] [--format] Generate PR risk report (markdown/HTML/JSON)
devflow doctor [--fix] Diagnose and fix common issues
devflow update-cockpit Regenerate DEVFLOW.md cockpit
devflow index Map project structure
devflow discover Discover and document brownfield project structure
devflow actions-generate Generate actions from requirements and roadmap
devflow tests-review Review test plan against requirements
devflow drift-check Detect drift between requirements and implementation
devflow design-review Review roadmap/design artifacts
devflow requirements-audit Audit requirements quality, consistency, and completeness
devflow analyze <type> Analyze project for specified concern
devflow trace <id> Trace requirement through design, implementation, and verification
devflow promote <id> Promote feature to next pipeline stage
devflow eval run Run evaluation suite

Performance baseline (v1.0.0): devflow status ~1.5s, devflow next ~1.5s (tested on 196-file project).


Configuration

# Review mode
npx devflow config set reviewMode independent      # Different actor required (default)
npx devflow config set reviewMode solo-hardened    # Self-approval with compensating evidence

# Execution mode
npx devflow config set executionMode local         # Default
npx devflow config set executionMode strict        # CI required, all gates blocking

# Risk tolerance
npx devflow config set riskTolerance relaxed       # Solo: advisory gates, self-approval OK
npx devflow config set riskTolerance moderate      # Team: standard gates (default)
npx devflow config set riskTolerance strict        # Release: all gates blocking, CI mandatory

The audit command supports a --risk-tolerance flag to override the project default for a single run:

npx devflow audit --risk-tolerance strict

Risk Tolerance Behavior

Gate relaxed moderate strict
Typecheck blocking blocking blocking
Tests blocking blocking blocking
Coverage advisory blocking blocking
Lint advisory blocking blocking
Implementer != approver advisory blocking blocking
Adversarial review blocking blocking blocking
CI ignored advisory blocking
Missing artifacts advisory advisory blocking

GitHub Actions

Devflow runs fully in CI without sending code to LLM providers or third-party review SaaS — processing is inside the CI runner. Example workflow:

name: Devflow PR Governance
on: [pull_request]
jobs:
  governance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npx @tjsasakinpm/devflow init
      - run: npx @tjsasakinpm/devflow feature complete feature-id
      - run: npx @tjsasakinpm/devflow adversarial-review feature-id
      - run: npx @tjsasakinpm/devflow gatekeep feature-id --approve --actor github-actions

Output Files

File Purpose
.devflow/config.json Configuration
.devflow/state.json Current state, confidence, blockers
.devflow/constitution.md Engineering constitution (C1-C12)
.devflow/audits/gatekeep-log.jsonl Gatekeep decisions with audit trail
.devflow/audits/<id>/adversarial-review.md Per-vector adversarial review report
_devflow/features/<id>/ Feature workspace (artifacts, logs)
_devflow/discovery/ Brownfield discovery reports
DEVFLOW.md Project cockpit — auto-generated for AI agents

Project States

Devflow tracks 22 states across project detection (5), feature pipeline (15), and anomaly states (2). States progress: feature-empty -> feature-requirements -> feature-design -> feature-test-plan -> feature-pre-code-audit -> feature-coding-ready -> feature-coding-in-progress -> feature-verification -> feature-review -> feature-done.

Key rule: AI agents must not write code before feature-coding-ready state. Devflow blocks premature implementation.


Installation

npm install --save-dev @tjsasakinpm/devflow  # Local install (recommended)
npx devflow install                           # Guided onboarding
npx devflow init                              # Script-friendly (no onboarding)

# Or install globally:
npm install -g @tjsasakinpm/devflow

Requires Node.js >= 18.


Development

git clone https://github.com/tjsasakifln/devflow
cd devflow
npm install
npm run build
npm test

Roadmap

All commands listed in the Commands section are implemented and stable. No pending command backlog for v1.0.0.

Future directions include:

  • Plugin system for custom guards and checks
  • Visual dashboard for multi-project governance
  • IDE extension for VS Code and JetBrains
  • Team sync for distributed audit log aggregation

License

MIT — see LICENSE.


[!NOTE] Built for teams who treat AI-generated code with the same rigor as human-written code. Devflow Governed — docs site (coming soon).

About

PR governance for AI-generated code. Reduce risk, enforce evidence, and produce auditable trails before AI-assisted changes reach review.

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages