DevFlow MCP

Spec-Driven Kanban for AI Agents

DevFlow lets humans and AI agents collaborate through a spec-first workflow:

proposal -> specs/design -> tasks -> promote to Kanban

Agents use MCP tools to write artifacts, check in/out of tasks, and keep execution visible across sessions.

Requirements

Node.js 20+

Install

npm install -g @sureshdsk/devflow-mcp

Quick Start

1. Initialize DevFlow

devflow init

This sets up ~/.devflow/devflow.db and installs DevFlow skills/commands for detected tools.

2. Start the web UI

devflow dev

Open http://localhost:3000.

3. Configure your AI tool

Claude Code CLI

claude mcp add devflow -- devflow mcp

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)

{
  "mcpServers": {
    "devflow": {
      "command": "devflow",
      "args": ["mcp"]
    }
  }
}

Codex (.codex/config.toml)

[mcp_servers.devflow]
command = "devflow"
args = ["mcp"]

Cursor

Settings -> Features -> MCP
Add server command: devflow mcp

4. Install/update skills and slash commands

devflow tool install

Useful variants:

devflow tool install --only codex
devflow tool install --only claudecode
devflow tool install --tools codex
devflow tool install --no-autodetect
devflow tool install --dry-run
devflow tool update

Workflow

Spec lifecycle

proposal -> specs + design -> tasks -> promote_spec -> Kanban tasks

Rules:

Downstream artifacts stay blocked until prerequisites are approved.
Editing approved artifacts revokes approval.
promote_spec only works after tasks is approved.

Task lifecycle

backlog -> todo -> in_progress -> done

Typical agent flow:

check_in
implement + log_activity
check_out

Sample Prompts (Codex Slash Commands)

Use these in Codex chat after DevFlow MCP is configured:

1. Start a new feature spec

Use case: You want to improve how spec validation feedback is reported in DevFlow.

/df:new
Project: devflow-mcp-v2
Spec name: improve-spec-validation-reporting
Title: Improve Spec Validation Reporting

2. Continue to the next unblocked artifact

Use case: Proposal is approved and you want Codex to move to specs or design.

/df:continue
Spec: improve-spec-validation-reporting

3. Check where the spec stands

Use case: You want to see what is done, what is blocked, and what needs approval.

/df:status
Spec: improve-spec-validation-reporting

4. Validate quality before promotion

Use case: You want a quality pass on completeness and structure before task promotion.

/df:validate
Spec: improve-spec-validation-reporting

5. Promote approved tasks to Kanban

Use case: tasks.md is approved and you want to create actionable board tasks.

/df:promote
Spec: improve-spec-validation-reporting

6. Execute promoted tasks one by one

Use case: You want Codex to implement tasks in order with check-in/check-out tracking.

/df:apply
Spec: improve-spec-validation-reporting

7. Archive completed spec

Use case: All work is complete and you want to move the spec out of active flow.

/df:archive
Spec: improve-spec-validation-reporting

8. Create a custom schema

Use case: You need a workflow different from the bundled schemas (e.g. ML pipeline, infrastructure, security review).

/df:schema

Custom Schemas

DevFlow ships with bundled schemas (spec-driven, backend-api, frontend-product, data-engineering, devops-platform), but you can create your own to match your team's workflow.

How schemas work

A schema defines the artifact DAG — which documents exist, what order they follow, and what templates agents use to generate them. The bundled spec-driven schema looks like this:

name: spec-driven
version: 1
artifacts:
  - id: proposal
    generates: proposal.md
    description: Change intent and scope
    template: proposal.md
    requires: []
  - id: specs
    generates: specs.md
    description: Requirements and scenarios
    template: specs.md
    requires: [proposal]
  - id: design
    generates: design.md
    description: Technical approach
    template: design.md
    requires: [proposal]
  - id: tasks
    generates: tasks.md
    description: Implementation tasks
    template: tasks.md
    requires: [specs, design]
qualityRules:
  requireRfc2119: true
  minScenariosPerRequirement: 1
apply:
  requires: [tasks]

The requires field creates the approval DAG — an artifact stays blocked until all its prerequisites are approved.

Creating a custom schema

Interactive (recommended): Use the /df:schema command to interactively create a schema. It will ask about your project type, workflow stages, and quality preferences, then generate everything for you.

Programmatic: Use the create_schema MCP tool to create a schema from code.

Manual: Place your schema in devflow/schemas/<schema-name>/:

devflow/
├── schemas/
│   └── my-workflow/
│       ├── schema.yaml
│       └── templates/
│           ├── rfc.md
│           ├── adr.md
│           └── tasks.md
└── specs/

1. Define schema.yaml:

name: my-workflow
version: 1
artifacts:
  - id: rfc
    generates: rfc.md
    description: Request for comments
    template: rfc.md
    requires: []
  - id: adr
    generates: adr.md
    description: Architecture decision record
    template: adr.md
    requires: [rfc]
  - id: tasks
    generates: tasks.md
    description: Implementation tasks
    template: tasks.md
    requires: [adr]
apply:
  requires: [tasks]

2. Add templates for each artifact in templates/. These are markdown files that agents use as starting points:

# RFC: [Title]

## Context

<!-- What is the background? -->

## Decision

<!-- What are we proposing? -->

## Consequences

<!-- What are the trade-offs? -->

3. Use it when creating a spec:

# Via MCP tool
create_spec(name: "my-feature", title: "My Feature", projectId: "...", schema: "my-workflow")

# Or set as project default during init
devflow init --schema my-workflow

Key rules

The schema name in schema.yaml must be unique — it cannot conflict with bundled schema names.
The last artifact should be tasks with ## Task: <title> headings (required for promote_spec).
Project-local templates in devflow/schemas/ take priority over bundled templates with the same name.

MCP Tools

Category	Tools
Projects	`list_projects`, `create_project`, `get_project`, `update_project`, `get_or_create_project`
Specs	`create_spec`, `list_specs`, `get_spec`, `get_spec_status`, `write_artifact`, `get_artifact`, `get_artifact_template`, `approve_artifact`, `draft_artifact`, `validate_spec`, `promote_spec`, `archive_spec`
Schemas	`list_schemas`, `create_schema`
Tasks	`list_tasks`, `get_task`, `create_task`, `create_tasks_bulk`, `update_task`
Agent	`check_in`, `check_out`, `log_activity`, `get_activity_log`

Architecture

┌───────────────────────────────────────────────────────────────────────┐
│                           AI Agents                                   │
│                    (Codex / Claude / Cursor)                          │
└───────────────────────────────┬───────────────────────────────────────┘
                                │ MCP protocol (stdio)
                                ▼
┌───────────────────────────────────────────────────────────────────────┐
│                  MCP Server (tsx, src/mcp/server.ts)                  │
│  project/spec/task/agent tools                                       │
│  DB + spec mutations -> broadcastUpdate()                            │
└───────────────┬──────────────────────────────┬────────────────────────┘
                │                              │
                ▼                              ▼
┌───────────────────────────────┐    ┌──────────────────────────────────┐
│ devflow/ (git-tracked)         │    │ SQLite/libSQL DB                │
│ ├─ project-config.json        │    │ ~/.devflow/devflow.db           │
│ └─ specs/<spec-name>/         │    │ - projects                       │
│    - proposal.md              │    │ - tasks (promoted + MCP updates) │
│    - specs.md                 │    │ - agent_activity                 │
│    - design.md                │    └──────────────────────────────────┘
│    - tasks.md                 │
│    - .approvals.json          │
│    - .meta.json               │
└───────────────────────────────┘
                │
                │ broadcastUpdate() for:
                │ - task_created / task_updated / tasks_created
                │ - project/spec/artifact/activity mutations
                ▼
┌───────────────────────────────────────────────────────────────────────┐
│                 WebSocket Server (src/websocket/server.ts)            │
│                              port 3001                               │
└───────────────────────────────┬───────────────────────────────────────┘
                                │ real-time updates
                                ▼
┌───────────────────────────────────────────────────────────────────────┐
│              Web UI (Hono + Vite SPA, localhost:3000)                 │
│  /            -> Kanban board                                        │
│  /specs/:name -> Artifact editor + approve/promote                   │
└───────────────────────────────────────────────────────────────────────┘

Development

git clone https://github.com/sureshdsk/devflow-mcp.git
cd devflow-mcp
pnpm install
pnpm dev           # Starts Hono API server + Vite dev server concurrently
pnpm typecheck
pnpm lint

Local Package Testing

pnpm build
npm install -g .
devflow --help

Restore published version:

npm install -g @sureshdsk/devflow-mcp

Documentation

Custom Schemas - creating and using custom schemas
Local Dev Guide - local development setup
AGENTS.md - agent-specific repository guidance
Contributing - contribution guide

Credits

Inspired by:

OpenSpec — spec-driven development workflow
Spec Kit — structured specification tooling

Contributors

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 27 Commits
.codex		.codex
.github/workflows		.github/workflows
.husky		.husky
bin		bin
docs		docs
drizzle		drizzle
public		public
scripts		scripts
src		src
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
drizzle.config.ts		drizzle.config.ts
eslint.config.mjs		eslint.config.mjs
index.html		index.html
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

DevFlow MCP

Requirements

Install

Quick Start

1. Initialize DevFlow

2. Start the web UI

3. Configure your AI tool

4. Install/update skills and slash commands

Workflow

Spec lifecycle

Task lifecycle

Sample Prompts (Codex Slash Commands)

1. Start a new feature spec

2. Continue to the next unblocked artifact

3. Check where the spec stands

4. Validate quality before promotion

5. Promote approved tasks to Kanban

6. Execute promoted tasks one by one

7. Archive completed spec

8. Create a custom schema

Custom Schemas

How schemas work

Creating a custom schema

Key rules

MCP Tools

Architecture

Development

Local Package Testing

Documentation

Credits

Contributors

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages