devflow-db

DevFlow DB

A SQLite-first developer workflow database, delivered as a VS Code agent plugin. It gives GitHub Copilot a persistent projects → requirements → tasks → reviews data layer, six task-scoped agents, three slash commands, and a Python MCP server — all installed as a single plugin.

---

Prerequisites

• VS Code with the GitHub Copilot extension
• chat.plugins.enabled: true in VS Code settings (agent plugins are a preview feature)
• Python 3.10+ available as python3

---

Installation

1. Clone or copy this repository to a local directory, e.g. ~/plugins/devflow-db.

2. Register the plugin by adding its path to your VS Code settings (User or Workspace):

   // .vscode/settings.json  (or User settings)
   "chat.pluginLocations": {
     "/absolute/path/to/devflow-db": true
   }
   

   Use chat.pluginLocations — not "Install Plugin From Source", which expects a Git URL.

3. Reload VS Code. The MCP server starts automatically; no manual setup is required.

---

Verify the installation

Check	Where to look
Plugin registered	Extensions sidebar → Agent Plugins — Installed → devflow-db
MCP server running	Command Palette → MCP: List Servers → devflow-db
Tools available	Command Palette → Configure Tools → 12 devflow-db tools listed
Agents available	Copilot Chat → @ → six DevFlow agents listed
Slash commands	Copilot Chat → / → /ingest-brief, /create-tasks, /run-review

The database file (db/devflow.db) is created automatically on first server start — no manual SQL execution is needed.

---

Slash commands

/ingest-brief

Reads a project brief markdown file from the workspace, inserts it as a project, and derives requirements.

/ingest-brief

The agent will locate the brief (or ask you to confirm its path), then:

1. Insert a projects row
2. Derive and insert requirements rows with priorities
3. Set the project status to active
4. Report the project ID and requirement list

/create-tasks

Decomposes a requirement into tasks and records them in the database.

/create-tasks

The agent will ask for a requirement_id (or list open requirements), then:

1. Decompose the requirement into tasks with appropriate task_type values
2. Insert each task — reviews are auto-spawned for plan, build, test, configure types
3. Report task IDs and any auto-spawned review IDs

/run-review

Surfaces all pending reviews and guides you through approving or rejecting each one.

/run-review

The agent will:

1. List all reviews with status = 'pending'
2. Show each review with its linked task context
3. Ask for your decision (approve / reject) and record it
4. reviewed_at is set automatically by the server on approval or rejection

---

Agents

Agent	Handles	Key capability
DevFlow Planner	plan tasks	Reads requirements, inserts plan tasks
DevFlow Builder	build, configure tasks	Implements and configures; updates task status
DevFlow Tester	test tasks	Inserts test tasks, tracks outcomes
DevFlow Reviewer	review tasks	Reads pending reviews, records approvals/rejections
DevFlow Documenter	document tasks	Inserts and completes documentation tasks
DevFlow Researcher	research tasks	Investigates questions, records findings

---

Schema overview

projects      id · name · brief_text · status · created_at
requirements  id · project_id · description · priority · status
tasks         id · requirement_id · title · task_type · status · created_at
reviews       id · task_id · status · notes · reviewed_at

• No records are ever deleted — use status fields to retire them
• Reviews for plan, build, test, and configure tasks are auto-created by the server

---

Running the tests

python3 -m venv .venv
.venv/bin/pip install mcp pytest
.venv/bin/python -m pytest tests/ -v

Expected: 46 tests, all passing.

---

Project layout

devflow-db/
  .claude-plugin/plugin.json   # Plugin manifest
  .mcp.json                    # MCP server definition
  hooks.json                   # Lifecycle hooks
  copilot-instructions.md      # Agent behaviour rules
  db/
    init.sql                   # Locked v1 schema (idempotent)
    devflow.db                 # Runtime database (gitignored)
  servers/
    mcp_server.py              # Python MCP server
    requirements.txt           # Python dependencies
  agents/                      # Six .agent.md files
  skills/                      # Three skill directories (/ingest-brief, /create-tasks, /run-review)
  templates/
    project-brief-template.md  # Copy this to start a new project
  tests/
    test_schema.py
    test_mcp_server.py