@sureshdsk/devflow-mcp 3.0.0 → 3.0.2

package/README.md

@@ -16,8 +16,8 @@ Agents use MCP tools to write artifacts, check in/out of tasks, and keep executi
 
 ## Requirements
 
-- Node.js 20+ (web UI + CLI)
-- Bun 1.0+ (required for `devflow mcp`)
+- Node.js 20+
+- Bun 1.0+ (required for MCP server: `devflow mcp`)
 
 ## Install
 
@@ -46,11 +46,13 @@ Open http://localhost:3000.
 ### 3. Configure your AI tool
 
 **Claude Code CLI**
+
 ```bash
 claude mcp add devflow -- devflow mcp
 ```
 
 **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`)
+
 ```json
 {
   "mcpServers": {
@@ -63,6 +65,7 @@ claude mcp add devflow -- devflow mcp
 ```
 
 **Codex (`.codex/config.toml`)**
+
 ```toml
 [mcp_servers.devflow]
 command = "devflow"
@@ -70,6 +73,7 @@ args = ["mcp"]
 ```
 
 **Cursor**
+
 - Settings -> Features -> MCP
 - Add server command: `devflow mcp`
 
@@ -99,6 +103,7 @@ 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.
@@ -110,6 +115,7 @@ backlog -> todo -> in_progress -> done
 ```
 
 Typical agent flow:
+
 1. `check_in`
 2. implement + `log_activity`
 3. `check_out`
@@ -183,14 +189,143 @@ Use case: All work is complete and you want to move the spec out of active flow.
 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).
+
+```text
+/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:
+
+```yaml
+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`:**
+
+```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:
+
+```markdown
+# 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:**
+
+```bash
+# 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` |
-| Tasks | `list_tasks`, `get_task`, `create_task`, `create_tasks_bulk`, `update_task` |
-| Agent | `check_in`, `check_out`, `log_activity`, `get_activity_log` |
+| 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
 
@@ -209,14 +344,15 @@ Spec: improve-spec-validation-reporting
                 │                              │
                 ▼                              ▼
 ┌───────────────────────────────┐    ┌──────────────────────────────────┐
-│ Spec Files (git-tracked)      │    │ SQLite/libSQL DB                │
-│ ./devflow/specs/<spec-name>/  │    │ ~/.devflow/devflow.db           │
-│ - proposal.md                 │    │ - projects                       │
-│ - specs.md                    │    │ - tasks (promoted + MCP updates) │
-│ - design.md                   │    │ - agent_activity                 │
-│ - tasks.md                    │    └──────────────────────────────────┘
-│ - .approvals.json             │
-│ - .meta.json                  │
+│ 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:
@@ -242,35 +378,40 @@ Spec: improve-spec-validation-reporting
 ```bash
 git clone https://github.com/sureshdsk/devflow-mcp.git
 cd devflow-mcp
-bun install
-bun dev        # UI dev server
-bun run mcp    # MCP server
-bun typecheck
-bun lint
+npm install
+npm run dev        # UI dev server
+npm run mcp        # MCP server
+npm run typecheck
+npm run lint
 ```
 
 ## Local Package Testing
 
 ```bash
-bun run build
-bun install -g .
+npm run build
+npm install -g .
 devflow --help
 ```
 
 Restore published version:
 
 ```bash
-bun install -g @sureshdsk/devflow-mcp
+npm install -g @sureshdsk/devflow-mcp
 ```
 
 ## Documentation
 
+- [Custom Schemas](docs/custom-schemas.md) - creating and using custom schemas
+- [Local Dev Guide](docs/local-dev-guide.md) - local development setup
 - [AGENTS.md](AGENTS.md) - agent-specific repository guidance
 - [Contributing](CONTRIBUTING.md) - contribution guide
 
 ## Credits
 
-Special thanks to [OpenSpec](https://github.com/Fission-AI/OpenSpec/) for this amazing tool that inspired this project.
+Inspired by:
+
+- [OpenSpec](https://github.com/Fission-AI/OpenSpec/) — spec-driven development workflow
+- [Spec Kit](https://github.github.com/spec-kit/) — structured specification tooling
 
 ## License
 

package/bin/devflow.js

@@ -26,7 +26,9 @@ switch (command) {
     initProcess.on('exit', (code) => {
       if (code !== 0) process.exit(code);
       // Install skills and commands after DB init
-      const { installSkills, printReport } = require(path.join(__dirname, '..', 'scripts', 'install-skills.js'));
+      const { installSkills, printReport } = require(
+        path.join(__dirname, '..', 'scripts', 'install-skills.js'),
+      );
       console.log('\nInstalling skills and slash commands...');
       const report = installSkills(process.cwd(), {});
       printReport(report);
@@ -36,7 +38,9 @@ switch (command) {
   }
 
   case 'tool': {
-    const { installSkills, printReport } = require(path.join(__dirname, '..', 'scripts', 'install-skills.js'));
+    const { installSkills, printReport } = require(
+      path.join(__dirname, '..', 'scripts', 'install-skills.js'),
+    );
     if (subcommand === 'install' || subcommand === 'update') {
       const args = process.argv.slice(4);
       const options = {};
@@ -53,7 +57,9 @@ switch (command) {
         if (options.autodetect === undefined) options.autodetect = false;
         if (options.only === undefined && options.tools === undefined) options.tools = 'all';
       }
-      console.log(`${subcommand === 'update' ? 'Updating' : 'Installing'} DevFlow skills and slash commands...`);
+      console.log(
+        `${subcommand === 'update' ? 'Updating' : 'Installing'} DevFlow skills and slash commands...`,
+      );
       const report = installSkills(process.cwd(), options);
       printReport(report);
     } else {
@@ -82,14 +88,14 @@ Examples:
       const devProcess = spawn('node', [standaloneServer], {
         stdio: 'inherit',
         cwd: pkgDir,
-        env: { ...process.env, PORT: process.env.PORT || '3000' }
+        env: { ...process.env, PORT: process.env.DEVFLOW_PORT || process.env.PORT || '3000' },
       });
       devProcess.on('exit', (code) => process.exit(code));
     } else {
       const nextBin = path.join(pkgDir, 'node_modules', '.bin', 'next');
       const devProcess = spawn(nextBin, ['start'], {
         stdio: 'inherit',
-        cwd: pkgDir
+        cwd: pkgDir,
       });
       devProcess.on('exit', (code) => process.exit(code));
     }
@@ -141,6 +147,7 @@ Requirements:
   - MCP Server: Bun 1.0+ (required for AI agent integration)
 
 Environment Variables:
+  DEVFLOW_PORT      Web UI port (default: 3000)
   DEVFLOW_WS_PORT   WebSocket server port (default: 3001)
   CODEX_HOME        Override Codex home directory (default: ~/.codex)
 

package/drizzle.config.ts

@@ -1,12 +1,12 @@
-import type { Config } from "drizzle-kit";
-import { join } from "path";
-import { homedir } from "os";
+import type { Config } from 'drizzle-kit';
+import { join } from 'path';
+import { homedir } from 'os';
 
 export default {
-  schema: "./src/db/schema.ts",
-  out: "./drizzle",
-  dialect: "turso",
+  schema: './src/db/schema.ts',
+  out: './drizzle',
+  dialect: 'turso',
   dbCredentials: {
-    url: `file:${join(homedir(), ".devflow", "devflow.db")}`,
+    url: `file:${join(homedir(), '.devflow', 'devflow.db')}`,
   },
 } satisfies Config;

package/next.config.ts

@@ -1,7 +1,16 @@
-import type { NextConfig } from "next";
+import type { NextConfig } from 'next';
 
 const nextConfig: NextConfig = {
-  output: "standalone",
+  output: 'standalone',
+  images: {
+    unoptimized: true,
+  },
+  env: {
+    NEXT_PUBLIC_DEVFLOW_WS_PORT: process.env.DEVFLOW_WS_PORT || '3001',
+  },
+  outputFileTracingExcludes: {
+    '*': ['./node_modules/typescript/**', './node_modules/sharp/**', './node_modules/@img/**'],
+  },
 };
 
 export default nextConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sureshdsk/devflow-mcp",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "Context-First Kanban for AI Agents - MCP server with web UI for managing AI agent workflows",
   "author": "DevFlow Team",
   "license": "MIT",
@@ -29,7 +29,6 @@
     "drizzle",
     "scripts",
     ".next/standalone",
-    ".next/static",
     "next.config.ts",
     "tsconfig.json",
     "drizzle.config.ts",
@@ -47,11 +46,21 @@
     "typecheck": "tsc --noEmit",
     "db:generate": "drizzle-kit generate",
     "db:push": "drizzle-kit push",
-    "db:studio": "drizzle-kit studio",
     "db:init": "node scripts/init-db.js",
     "mcp": "bun src/mcp/server.ts",
-    "prepublishOnly": "npm run typecheck && npm run lint && npm run build",
-    "postinstall": "node scripts/postinstall.js"
+    "postbuild": "cp -r .next/static .next/standalone/.next/static",
+    "prepublishOnly": "npm run typecheck && npm run lint && npm run build && npm run postbuild",
+    "postinstall": "node scripts/postinstall.js",
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "*.{ts,tsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{js,json,css,md}": [
+      "prettier --write"
+    ]
   },
   "dependencies": {
     "@dnd-kit/core": "^6.3.1",
@@ -59,13 +68,10 @@
     "@dnd-kit/utilities": "^3.2.2",
     "@libsql/client": "^0.17.0",
     "@modelcontextprotocol/sdk": "^1.25.3",
-    "@radix-ui/react-collapsible": "^1.1.12",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
-    "@radix-ui/react-select": "^2.2.6",
     "@radix-ui/react-slot": "^1.2.4",
-    "@radix-ui/react-tabs": "^1.1.13",
-    "@radix-ui/react-toast": "^1.2.15",
+    "@tanstack/react-query": "^5.90.21",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "drizzle-orm": "^0.45.1",
@@ -92,6 +98,9 @@
     "drizzle-kit": "^0.31.8",
     "eslint": "^9.39.1",
     "eslint-config-next": "^16.0.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.8.1",
     "tailwindcss": "^4.1.17",
     "typescript": "^5.9.3"
   }

package/scripts/init-db.js

@@ -54,9 +54,7 @@ async function chooseSchemaTemplate(projectRoot, options) {
     availableSchemaIds,
     interactive,
     confirmKeepExisting: async (current) => {
-      const answer = await askQuestion(
-        `Current default schema is "${current}". Keep it? [Y/n]: `
-      );
+      const answer = await askQuestion(`Current default schema is "${current}". Keep it? [Y/n]: `);
       return answer === '' || /^y(es)?$/i.test(answer);
     },
     promptSelectSchema: async (ids, current) => {
@@ -84,7 +82,7 @@ async function chooseSchemaTemplate(projectRoot, options) {
   return {
     schemaId: result.schemaId,
     reason: result.reason,
-    configPath: path.join(projectRoot, '.devflow', 'project-config.json'),
+    configPath: path.join(projectRoot, 'devflow', 'project-config.json'),
   };
 }
 
@@ -110,7 +108,7 @@ async function initDatabase(options = {}) {
 
   // If DB has old schema (features table), drop and recreate
   const tables = await client.execute(
-    `SELECT name FROM sqlite_master WHERE type='table' AND name='features'`
+    `SELECT name FROM sqlite_master WHERE type='table' AND name='features'`,
   );
   if (tables.rows.length > 0) {
     console.log('⚠ Detected old schema (features table). Recreating database...');

package/scripts/init-db.test.js

@@ -1,10 +1,10 @@
-const test = require("node:test");
-const assert = require("node:assert/strict");
+const test = require('node:test');
+const assert = require('node:assert/strict');
 
-const { parseInitArgs } = require("./init-db");
+const { parseInitArgs } = require('./init-db');
 
-test("parseInitArgs parses schema and non-interactive flags", () => {
-  const parsed = parseInitArgs(["--schema", "backend-api", "--non-interactive"]);
-  assert.equal(parsed.schema, "backend-api");
+test('parseInitArgs parses schema and non-interactive flags', () => {
+  const parsed = parseInitArgs(['--schema', 'backend-api', '--non-interactive']);
+  assert.equal(parsed.schema, 'backend-api');
   assert.equal(parsed.nonInteractive, true);
 });

package/scripts/init-schema.js

@@ -1,16 +1,16 @@
-const fs = require("fs");
-const path = require("path");
-const yaml = require("js-yaml");
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
 
 function getProjectConfigPath(projectRoot) {
-  return path.join(projectRoot, ".devflow", "project-config.json");
+  return path.join(projectRoot, 'devflow', 'project-config.json');
 }
 
 function readProjectConfig(projectRoot) {
   const configPath = getProjectConfigPath(projectRoot);
   if (!fs.existsSync(configPath)) return {};
   try {
-    return JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    return JSON.parse(fs.readFileSync(configPath, 'utf-8'));
   } catch {
     return {};
   }
@@ -19,7 +19,7 @@ function readProjectConfig(projectRoot) {
 function writeProjectConfig(projectRoot, config) {
   const configPath = getProjectConfigPath(projectRoot);
   fs.mkdirSync(path.dirname(configPath), { recursive: true });
-  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), "utf-8");
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
 }
 
 function readSchemasFromDir(baseDir, source) {
@@ -31,9 +31,9 @@ function readSchemasFromDir(baseDir, source) {
 
   const schemas = [];
   for (const entryName of entries) {
-    const schemaPath = path.join(baseDir, entryName, "schema.yaml");
+    const schemaPath = path.join(baseDir, entryName, 'schema.yaml');
     if (!fs.existsSync(schemaPath)) continue;
-    const parsed = yaml.load(fs.readFileSync(schemaPath, "utf-8")) || {};
+    const parsed = yaml.load(fs.readFileSync(schemaPath, 'utf-8')) || {};
     if (!parsed.name) {
       throw new Error(`Invalid schema at ${schemaPath}: missing name`);
     }
@@ -41,7 +41,7 @@ function readSchemasFromDir(baseDir, source) {
       id: String(parsed.name),
       source,
       schemaPath,
-      templatesDir: path.join(path.dirname(schemaPath), "templates"),
+      templatesDir: path.join(path.dirname(schemaPath), 'templates'),
     });
   }
   return schemas;
@@ -50,11 +50,11 @@ function readSchemasFromDir(baseDir, source) {
 function discoverSchemaTemplates(options) {
   const projectRoot = options.projectRoot;
   const packageRoot = options.packageRoot;
-  const bundledDir = options.bundledDir || path.join(packageRoot, "src", "schemas");
-  const projectSchemaDir = path.join(projectRoot, "schemas");
+  const bundledDir = options.bundledDir || path.join(packageRoot, 'src', 'schemas');
+  const projectSchemaDir = path.join(projectRoot, 'schemas');
 
-  const bundled = readSchemasFromDir(bundledDir, "bundled");
-  const project = readSchemasFromDir(projectSchemaDir, "project");
+  const bundled = readSchemasFromDir(bundledDir, 'bundled');
+  const project = readSchemasFromDir(projectSchemaDir, 'project');
   const merged = [...bundled, ...project];
 
   const idToSchema = new Map();
@@ -62,7 +62,7 @@ function discoverSchemaTemplates(options) {
     const existing = idToSchema.get(schema.id);
     if (existing) {
       throw new Error(
-        `Schema ID conflict for "${schema.id}" between ${existing.source}:${existing.schemaPath} and ${schema.source}:${schema.schemaPath}`
+        `Schema ID conflict for "${schema.id}" between ${existing.source}:${existing.schemaPath} and ${schema.source}:${schema.schemaPath}`,
       );
     }
     idToSchema.set(schema.id, schema);
@@ -74,7 +74,7 @@ function discoverSchemaTemplates(options) {
 function assertKnownSchema(schemaId, availableSchemaIds) {
   if (!availableSchemaIds.includes(schemaId)) {
     throw new Error(
-      `Unknown schema "${schemaId}". Available schemas: ${availableSchemaIds.join(", ")}`
+      `Unknown schema "${schemaId}". Available schemas: ${availableSchemaIds.join(', ')}`,
     );
   }
 }
@@ -91,31 +91,31 @@ async function resolveInitSchemaSelection(options) {
 
   if (requestedSchema) {
     assertKnownSchema(requestedSchema, availableSchemaIds);
-    return { schemaId: requestedSchema, reason: "explicit" };
+    return { schemaId: requestedSchema, reason: 'explicit' };
   }
 
   if (!interactive) {
     if (existingDefaultSchema && availableSchemaIds.includes(existingDefaultSchema)) {
-      return { schemaId: existingDefaultSchema, reason: "existing-default" };
+      return { schemaId: existingDefaultSchema, reason: 'existing-default' };
     }
-    if (availableSchemaIds.includes("spec-driven")) {
-      return { schemaId: "spec-driven", reason: "non-interactive-fallback" };
+    if (availableSchemaIds.includes('spec-driven')) {
+      return { schemaId: 'spec-driven', reason: 'non-interactive-fallback' };
     }
     throw new Error(
-      `Non-interactive init requires a schema. Available schemas: ${availableSchemaIds.join(", ")}`
+      `Non-interactive init requires a schema. Available schemas: ${availableSchemaIds.join(', ')}`,
     );
   }
 
   if (existingDefaultSchema && availableSchemaIds.includes(existingDefaultSchema)) {
     const keep = (await confirmKeepExisting(existingDefaultSchema)) !== false;
     if (keep) {
-      return { schemaId: existingDefaultSchema, reason: "existing-default-kept" };
+      return { schemaId: existingDefaultSchema, reason: 'existing-default-kept' };
     }
   }
 
   const selected = await promptSelectSchema(availableSchemaIds, existingDefaultSchema);
   assertKnownSchema(selected, availableSchemaIds);
-  return { schemaId: selected, reason: "interactive-selection" };
+  return { schemaId: selected, reason: 'interactive-selection' };
 }
 
 module.exports = {