AIConductor

AIConductor

An open-source Model Context Protocol (MCP) server that orchestrates multi-stakeholder feature refinement and development execution workflows for AI-assisted software teams.

    

---

Overview

AIConductor gives your AI coding agent a structured, auditable pipeline — from raw feature idea to merged code. It exposes 39 MCP tools that any MCP-compatible agent (Claude, Copilot, Cursor, Cline, etc.) can call to drive tasks through two workflows:

1. Feature Refinement — Break a feature into discrete tasks, then route each task through a sequential stakeholder approval chain before any code is written.
2. Development Execution — Drive approved tasks through a Developer → Code Reviewer → QA lifecycle with full audit history.

Features

| | | |---|---| | Multi-Stakeholder Reviews | Product Director → Architect → UI/UX Expert → Security Officer approval chain | | Development Pipeline | Developer → Code Reviewer → QA → Done with NeedsChanges feedback loops | | Real-time Dashboard | Kanban board at localhost:5111 with live WebSocket updates | | Multi-Repository | Manage tasks across multiple codebases from a single server | | Refinement Reports | Generate markdown/HTML/JSON reports of the full refinement process | | Workflow Checkpoints | Save and restore workflow state; rollback the last stakeholder decision | | Task Execution Planning | Dependency analysis with parallelisation suggestions | | Zero External Dependencies | Everything persisted in a local SQLite database |

---

Prerequisites

• Docker and Docker Compose
• An MCP-compatible AI agent (Claude Desktop, VS Code Copilot, Cursor, Cline, etc.)

---

Quick Start

git clone https://github.com/your-org/aiconductor.git
cd aiconductor
docker compose up -d

The MCP server and dashboard are now running. Connect your AI agent by adding the following to your MCP config:

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "aiconductor": {
      "command": "docker",
      "args": ["exec", "-i", "-e", "DISABLE_DASHBOARD=true", "aiconductor-mcp", "node", "dist/bundle.js"]
    }
  }
}

VS Code — .vscode/mcp.json or user settings

{
  "mcp.servers": {
    "aiconductor": {
      "command": "docker",
      "args": ["exec", "-i", "-e", "DISABLE_DASHBOARD=true", "aiconductor-mcp", "node", "dist/bundle.js"]
    }
  }
}

Restart your agent. Open the dashboard at http://localhost:5111.

---

Workflows

Two slash-command workflows are included in .github/prompts/ and can be invoked directly from your agent.

/refine-feature — Feature Refinement

Turns a plain-text feature description into stakeholder-approved, implementation-ready tasks.

Feature Description
  │
  ├─ Scope determination & context gathering
  ├─ Attachment analysis (images, docs, spreadsheets)
  ├─ Clarification questions
  ├─ SMART acceptance criteria generation
  ├─ Test scenario generation
  ├─ Task breakdown (5–8 tasks)
  │
  └─ Batched stakeholder review cycle
       │
       ├─ Product Director  →  Architect  →  UI/UX Expert  →  Security Officer
       │        │                  │               │                  │
       │     reject             reject          reject             reject
       │        └──────────────────┴───────────────┴──────────────────┘
       │                                  ▼
       │                         NeedsRefinement → restart
       │
       └─ All tasks reach ReadyForDevelopment ✓

Tasks are processed in batches per role — a single role adoption covers all tasks in one pass, dramatically reducing context overhead.

/dev-workflow — Development Execution

Drives ReadyForDevelopment tasks through implementation to Done.

ReadyForDevelopment
  └─→ InProgress ─→ InReview ─→ InQA ─→ Done ✓
           │             │          │
           └─────────────┴──────────┘
                    NeedsChanges → back to InProgress

Each stage is handled by a distinct role: Developer (implements & tests), Code Reviewer (approves or requests changes), QA (verifies acceptance criteria).

---

Dashboard

Open http://localhost:5111 in your browser.

| Kanban Board | Feature Details | |:---:|:---:| | !AIConductor Kanban Board | !AIConductor Feature Details |

• Kanban board — Task cards arranged by workflow status; empty columns collapse to a slim strip so all columns fit on screen without horizontal scrolling
• Real-time updates — WebSocket connection pushes task state changes instantly to all open browser tabs
• Detail panel — Per-feature acceptance criteria, test scenarios, clarifications, and refinement step progress
• Multi-repo switcher — Switch between registered repositories from the sidebar
• Reviewer presence — See which reviewers are currently active on a feature

---

MCP Tools Reference

Orchestration

| Tool | Description | |---|---| | get_next_step | Returns the next role, system prompt, and required output fields for a task — the primary orchestration driver | | get_workflow_snapshot | Compressed overview of all task statuses and roles for a feature (~5 KB vs ~50 KB for full fetch) | | get_task_execution_plan | Dependency analysis with optimal execution order and parallelisable phases | | get_similar_tasks | Find comparable tasks from past features to aid estimation | | get_workflow_metrics | Cycle time, throughput, and bottleneck statistics |

Stakeholder Reviews

| Tool | Description | |---|---| | add_stakeholder_review | Submit an approve/reject review with role-specific structured fields | | validate_review_completeness | Pre-flight check that all required fields are present before submitting | | get_task_status | Current status, completed/pending reviews, and allowed transitions | | get_review_summary | Completion percentage and stakeholder progress across all tasks | | validate_workflow | Dry-run validation — check if a transition can proceed | | rollback_last_decision | Undo the most recent stakeholder decision on a task |

Development Pipeline

| Tool | Description | |---|---| | transition_task_status | Move a task through development stages (InProgress → InReview → InQA → Done) | | batch_transition_tasks | Transition multiple tasks atomically in a single call | | get_next_task | Get the next task to work on, optionally filtered by status | | get_tasks_by_status | List all tasks matching a specific status | | verify_all_tasks_complete | Assert every task in a feature has reached Done | | update_acceptance_criteria | Mark individual acceptance criteria as verified | | batch_update_acceptance_criteria | Verify multiple criteria in one call |

Feature & Task Management

| Tool | Description | |---|---| | create_feature | Create a new feature with slug, name, and description | | update_feature | Update feature metadata (name, description) | | get_feature | Load full feature data including all tasks, criteria, and scenarios | | list_features | List all features in a repository with task counts | | delete_feature | Remove a feature and all associated tasks, reviews, and transitions | | add_task | Add a task to a feature with acceptance criteria and test scenarios | | update_task | Modify task properties (title, description, criteria, scenarios, dependencies) | | delete_task | Remove a task and all its data |

Refinement Tracking

| Tool | Description | |---|---| | update_refinement_step | Record progress through the 8-step refinement workflow | | get_refinement_status | Full refinement progress including step completion and criteria | | add_feature_acceptance_criteria | Add feature-level acceptance criteria (before tasks are created) | | add_feature_test_scenarios | Add feature-level test scenarios | | add_clarification | Record a clarification question and answer | | add_attachment_analysis | Store analysis results for an attached file or design | | generate_refinement_report | Export the full refinement process as markdown, HTML, or JSON |

Checkpoint Management

| Tool | Description | |---|---| | save_workflow_checkpoint | Save current workflow state with a description | | list_workflow_checkpoints | List all saved checkpoints for a feature | | restore_workflow_checkpoint | Resume from a previously saved checkpoint |

Repository Management

| Tool | Description | |---|---| | register_repo | Register a new repository namespace | | list_repos | List all registered repositories with task counts | | get_current_repo | Auto-detect the repository from the current working directory |

---

Stakeholder Roles

| Role | Focus Areas | Key Output Fields | |---|---|---| | Product Director | Market fit, user value, acceptance criteria quality | marketAnalysis, competitorAnalysis, quickSummary | | Architect | Technical feasibility, design patterns, technology choices | technologyRecommendations, designPatterns | | UI/UX Expert | Usability, accessibility, user behaviour | usabilityFindings, accessibilityRequirements, userBehaviorInsights | | Security Officer | Security requirements, compliance, risk assessment | securityRequirements, complianceNotes |

---

Project Structure

src/
├── index.ts                 # MCP server — tool definitions and request handling
├── AIConductor.ts     # Business logic for all workflow operations
├── WorkflowValidator.ts     # State machine — validates transitions and returns role prompts
├── DatabaseHandler.ts       # SQLite CRUD operations
├── rolePrompts.ts           # System prompts for each stakeholder role
├── websocket.ts             # WebSocket server — real-time event broadcasting
├── dashboard.ts             # Express web server (port 5111)
├── types.ts                 # TypeScript interfaces
└── client/                  # React SPA (Vite)

.github/prompts/
├── refine-feature.prompt.md # Feature refinement workflow
└── dev-workflow.prompt.md   # Development execution workflow

Database:

• Docker: /data/tasks.db (persistent volume task-review-data)
• Local: ./tasks.db in project root

---

Local Development

npm install
npm run dev          # Watch mode — recompiles on change
npm run build        # Production build (server + client)
npm test             # Run all tests with coverage
npm run lint         # TypeScript and code quality lint
npm run dashboard    # Start dashboard standalone (port 5111)

To rebuild the Docker image after code changes:

docker compose up -d --build

CI/CD Pipeline

All pull requests automatically run through our GitHub Actions CI workflow, which includes:

• Build — TypeScript compilation with npm run build
• Lint — Code quality checks with npm run lint
• Test — Jest tests with coverage tracking via npm test
• Coverage — Coverage metrics uploaded to Codecov

See CONTRIBUTING.md for details on running these checks locally, understanding failures, and our branch protection rules.

---

Configuration

| Variable | Default | Description | |---|---|---| | DATABASE_PATH | ./tasks.db | SQLite file location (/data/tasks.db in Docker) |

To reset all data:

docker compose down -v && docker compose up -d

---

License

MIT