taskflow

TaskFlow

A VS Code agent plugin that implements a database-driven agentic pipeline for software development. Every agent action is authorised and scoped by a task record. The database is the single source of truth for pipeline state, permissions, and context.

---

Prerequisites

• uv — brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh
• VS Code with GitHub Copilot (agent mode)

---

Installation

Add to your VS Code settings.json:

"chat.pluginLocations": [
  "/path/to/taskflow"
]

Or install from GitHub by adding the repo URL to chat.pluginLocations.

On first use, uv will automatically install the mcp dependency. No manual pip install required.

---

Quick start

There are two ways to kick off a project. Use Path A when a client has filled in the brief form; use Path B for quick or informal starts.

Path A — Project brief form (recommended)

1. Open docs/project-brief-form.html in any browser (no server needed — it runs offline).

2. Complete all sections: identity, goals, features, workflows, NFRs, integrations, risks, timeline.

3. Click Generate brief — a project-brief-<name>.json file downloads to your machine.

4. In VS Code Copilot chat, invoke the TaskFlow Product Manager agent and run:

   @TaskFlow Product Manager use ingest_brief to start this project
   

   Paste the contents of the JSON file (or provide the file path). The agent calls ingest_brief, which parses all structured data into the database and seeds the first pipeline task.

5. Proceed to Working the pipeline.

Path B — Free-text brief

1. Open a project workspace in VS Code.
2. Type /start-project in Copilot chat and follow the prompts — paste a brief as plain text or provide a file path.
3. Proceed to Working the pipeline.

Working the pipeline

1. Use /my-tasks to see what each agent needs to do next.
2. Invoke the appropriate agent (e.g. TaskFlow Product Manager) to work the next task.
3. Use /pipeline-status at any time to see the full pipeline state.

---

Slash commands

Command	Description
/start-project	Start a project from free-text or a brief file (Path B)
/my-tasks	Show pending tasks for a chosen agent role
/pipeline-status	Show the full pipeline state for a project

For the form-based path, use ingest_brief directly via the TaskFlow Product Manager agent rather than /start-project.

---

Agents

Agent	Role in pipeline
TaskFlow Product Manager	Defines features, decisions, and decision artefacts (steps 3, 10, 12)
TaskFlow PM Reviewer	Reviews and approves PM outputs (steps 2, 4, 11, 13)
TaskFlow Tester	Writes test specs and runs tests (steps 5, 8)
TaskFlow Test Reviewer	Reviews test specs (step 6)
TaskFlow Builder	Implements features (step 7)
TaskFlow Documenter	Writes retrospective and recommendations (step 9)

---

Project brief form

The brief form (docs/project-brief-form.html) is a single offline HTML file — no install, no server, no dependencies.

Sections captured:

Section	What agents use it for
Project identity & problem	All agents — project scope and context
Goals & success metrics	PM (step 3 feature alignment); PM Reviewer (step 13 final verification)
User roles & workflows	PM (step 3 user-centric features); Tester (step 5 test scenario design)
Features (Must / Should / Could)	PM (step 3 starting point — promote Must features first)
Non-functional requirements	Builder (step 7 implementation constraints); Tester (step 8 verification)
Integrations	Builder (step 7 — system, direction, auth method, phase 1 flag)
Risks	PM (steps 10/12 — seeded as initial decision artefacts)
Release phases	PM (step 3 — assigns features to cycles)
Timeline & deadline	All reviewers — context for prioritisation

Form features:

• Dynamic add/remove rows for features, roles, workflows, integrations, risks
• Toggle rows for NFRs — only enabled constraints are stored; disabled ones produce no noise in the DB
• Client-side validation before download (required fields, at least one Must feature, at least one platform)
• Auto-saves to localStorage every 2 seconds — reload the page and it offers to restore the draft
• Downloads as project-brief-<slug>.json — the file is the pipeline entry artefact

---

Pipeline overview