workflow-ai 1.0.68 → 1.2.1

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+## [1.2.0] — 2026-04-28
+
+### New Features
+- **New built-in stage type: `manual-gate`** — Adds support for manual approval steps in pipelines. When a stage with `type: manual-gate` is encountered, the runner creates a pending approval file in `.workflow/approvals/{step_id}.json` and enters a polling loop, waiting for an external decision (`approved`/`rejected`).
+
+  **Key capabilities:**
+  - Deterministic `step_id` generation: `{ticket_id}_{stageId}_{attempt}` (e.g., `QA-12_manual-approve_0`)
+  - Idempotent file creation — pending file is not overwritten on retry/restart
+  - Configurable polling interval (`poll_interval_ms`, default 2000ms) and optional timeout (`timeout_seconds`)
+  - Graceful handling of SIGTERM/runner stop (returns `aborted`)
+  - Immediate return if file already has `approved`/`rejected` status (crash recovery)
+  - JSON approval file format with full audit trail (`created_at`, `updated_at`, `decided_by`, `comment`, `context_snapshot`)
+
+  **Pipeline configuration example:**
+  ```yaml
+  stages:
+    manual-approve-deploy:
+      type: manual-gate
+      poll_interval_ms: 2000
+      timeout_seconds: 86400
+      goto:
+        approved: continue-deploy
+        rejected: rollback
+        timeout: notify-stuck
+        aborted: end
+  ```
+
+  **Two approval methods (both opt-in):**
+  1. **External MCP/client**: tools like `workflow-mcp` can write to approval files programmatically
+  2. **Direct file edit**: users can simply edit `.workflow/approvals/{step_id}.json` and change `status` to `approved` or `rejected`
+
+  **Important:** `manual-gate` is **opt-in** — pipelines without such stages work identically to previous versions. No breaking changes.
+
+### Changed
+- No breaking changes. All existing pipelines without `manual-gate` stages are fully backward compatible.
+
+### Fixes
+- None
+
+### Technical Notes
+- Approval files are stored in `<project_root>/.workflow/approvals/`
+- Runner validates `manual-gate` stages on startup — requires `goto.approved` and `goto.rejected`, validates numeric parameters
+- New methods added to `PipelineRunner`: `computeStepId()`, `writeApprovalPending()`, `readApprovalFile()`, `executeManualGate()`
+
+### References
+- PLAN-009: workflow-ai 1.2 — manual-gate stage and approval files for workflow-mcp Sprint 2 integration
+- IMPL-55, IMPL-56, IMPL-57, IMPL-58: Implementation tickets
+- QA-35, QA-36, QA-37: Test coverage
+- IMPL-51, QA-55 in workflow-mcp: Dependent consumer work

package/README.md

@@ -102,14 +102,63 @@ workflow run
 20. **analyze-report / decompose-gaps** — проанализировать результаты и итерировать
 21. **complete-plan / increment-plan-iterations** — закрыть план или запустить следующую итерацию
 
-### Поддерживаемые агенты
+### Типы стадий
+
+#### `update-counter`
+Встроенная стадия, инкрементирует счётчик и возвращает статус для перехода. Требует `counter` и опционально `max`. Возвращает `default` или `max_reached`.
+
+#### `manual-gate`
+Встроенная стадия для ручного одобрения. Создаёт файл `.workflow/approvals/{step_id}.json` со статусом `pending` и ждёт решения через polling (интервал по умолчанию 2000мс).
+
+**Параметры:**
+- `poll_interval_ms` — интервал опроса (опц., default 2000)
+- `timeout_seconds` — таймаут в секундах (опц., default без таймаута)
+
+**Требуемые goto:**
+- `approved` — обязательный, переход при одобрении
+- `rejected` — обязательный, переход при отклонении
+
+**Опциональные goto:**
+- `timeout` — при истечении таймаута
+- `aborted` — при остановке runner'а (SIGTERM)
+
+**Формат step_id:** `{ticket_id}_{stageId}_{attempt}` (например, `QA-12_manual-approve_0`)
+
+**Approval-файл содержит:**
+```json
+{
+  "step_id": "QA-12_manual-approve_0",
+  "ticket_id": "QA-12",
+  "stage_id": "manual-approve",
+  "attempt": 0,
+  "status": "pending",
+  "created_at": "2026-04-28T12:34:56.789Z",
+  "updated_at": "2026-04-28T12:34:56.789Z",
+  "decided_by": null,
+  "comment": null,
+  "context_snapshot": { ... }
+}
+```
 
-| Агент | Описание |
-|-------|----------|
-| `claude-code` | Claude Opus — мощная модель для сложных задач |
-| `qwen-code` | Qwen Code — альтернативный агент |
-| `kilo-code` | Kilo Code — мультирежимный агент |
-...
+**Два способа одобрения:**
+1. **Через MCP-клиент** (например `workflow-mcp`): tool `approve_step({step_id, decision, comment})` пишет в файл approval
+2. **Прямая правка файла:** открыть `.workflow/approvals/{step_id}.json`, изменить `"status": "pending"` на `"approved"` или `"rejected"`, сохранить
+
+**Важное:** `manual-gate` — **opt-in**. Если ваш pipeline не использует стадии `manual-gate`, поведение полностью идентично предыдущим версиям! Никаких breaking changes.
+
+**Пример:**
+```yaml
+stages:
+  manual-approve-deploy:
+    type: manual-gate
+    poll_interval_ms: 2000
+    timeout_seconds: 86400
+    goto:
+      approved: continue-deploy
+      rejected: rollback
+      timeout: notify-stuck
+      aborted: end
+```
 
 Агенты настраиваются в `configs/pipeline.yaml`.
 
@@ -343,6 +392,55 @@ agents:
 
 Определение конвейера: агенты, стадии, управление потоком, goto-логика, стратегии повторов.
 
+#### `manual-gate` stage
+
+`type: manual-gate` — встроенный тип стадии для ручного одобрения. Создаёт файл `.workflow/approvals/{step_id}.json` со статусом `pending` и ждёт решения через polling.
+
+**Поля:**
+- `type: manual-gate` — обязательное, идентификатор типа стадии
+- `poll_interval_ms` — опциональное, интервал опроса в мс (default: 2000, минимум: 100)
+- `timeout_seconds` — опциональное, таймаут в секундах (default: null — без таймаута)
+- `goto.approved` — обязательное, следующая стадия при одобрении
+- `goto.rejected` — обязательное, следующая стадия при отклонении
+- `goto.timeout` — опциональное, следующая стадия при истечении таймаута
+- `goto.aborted` — опциональное, следующая стадия при остановке runner'а (SIGTERM)
+
+**Пример:**
+```yaml
+stages:
+  manual-approve-deploy:
+    type: manual-gate
+    poll_interval_ms: 2000
+    timeout_seconds: 86400
+    goto:
+      approved: continue-deploy
+      rejected: rollback
+      timeout: notify-stuck
+      aborted: end
+```
+
+**Два способа одобрения:**
+1. **Через MCP-клиент** (например `workflow-mcp`): tool `approve_step({step_id, decision, comment})` пишет в файл approval. Опционально — пользователю не обязал подключать MCP.
+2. **Прямая правка файла:** открыть `.workflow/approvals/{step_id}.json`, изменить `"status": "pending"` на `"approved"` или `"rejected"`, сохранить. **Базовый способ, работающий без какой-либо внешней инфраструктуры** — достаточно текстового редактора.
+
+**Важное:** `manual-gate` — **opt-in**. Если ваш pipeline не использует стадии `manual-gate`, поведение полностью идентично предыдущим версиям! Никаких breaking changes.
+
+**Формат approval-файла:**
+```json
+{
+  "step_id": "QA-12_manual-approve_0",
+  "ticket_id": "QA-12",
+  "stage_id": "manual-approve",
+  "attempt": 0,
+  "status": "pending",
+  "created_at": "2026-04-28T12:34:56.789Z",
+  "updated_at": "2026-04-28T12:34:56.789Z",
+  "decided_by": null,
+  "comment": null,
+  "context_snapshot": { ... }
+}
+```
+
 ### `configs/ticket-movement-rules.yaml`
 
 Правила автоматического перемещения тикетов на основе статуса ревью.

package/configs/pipeline.yaml

@@ -90,6 +90,20 @@ pipeline:
       capabilities: [text]
       description: "Kilo deepseek"
 
+    deepseek-flash:
+      command: "kilo"
+      args: ["-m", "deepseek/deepseek-v4-flash", "--agent", "code", "--print-logs", "--log-level", "ERROR", "run", "--auto"]
+      workdir: "."
+      capabilities: [text]
+      description: "Kilo deepseek"
+
+    deepseek-pro:
+      command: "kilo"
+      args: ["-m", "deepseek/deepseek-v4-pro", "--agent", "code", "--print-logs", "--log-level", "ERROR", "run", "--auto"]
+      workdir: "."
+      capabilities: [text]
+      description: "Kilo deepseek"
+
     kilo-minimax:
       command: "kilo"
       args: ["-m", "kilo/minimax/minimax-m2.7", "--agent", "code", "--print-logs", "--log-level", "ERROR", "run", "--auto"]
@@ -104,6 +118,13 @@ pipeline:
       capabilities: [text]
       description: "Kilo free"
 
+    openrouter-free:
+      command: "kilo"
+      args: ["-m", "kilo/openrouter/free", "--agent", "code", "--print-logs", "--log-level", "ERROR", "run", "--auto"]
+      workdir: "."
+      capabilities: [text]
+      description: "Kilo free"
+
     script-move:
       command: "node"
       args: [".workflow/src/scripts/move-ticket.js"]
@@ -576,10 +597,10 @@ pipeline:
       description: "Выполнить выбранную задачу"
       skill: execute-task
       counter: task_attempts
-      agents: [kilo-free, kilo-glm-air, claude-haiku, claude-sonnet, claude-opus, kilo-minimax, kilo-deepseek]
+      agents: [kilo-free, openrouter-free, kilo-glm-air, claude-haiku, claude-sonnet, claude-opus, kilo-minimax, deepseek-flash]
       agents_by_type:
         coach:
-          agents: [kilo-glm, claude-sonnet, kilo-minimax, kilo-deepseek]
+          agents: [kilo-glm, claude-sonnet, deepseek-pro, kilo-minimax]
           instructions: "Твоя роль: coach"
         qa:
           agents: [claude-haiku, kilo-glm, claude-sonnet, claude-opus, kilo-minimax]

package/package.json

@@ -1,41 +1,44 @@
-{
-  "name": "workflow-ai",
-  "version": "1.0.68",
-  "description": "AI Agent Workflow Coordinator — kanban-based pipeline for AI coding agents",
-  "type": "module",
-  "bin": {
-    "workflow": "./bin/workflow.mjs"
-  },
-  "files": [
-    "bin/",
-    "src/cli.mjs",
-    "src/init.mjs",
-    "src/runner.mjs",
-    "src/wf-loader.mjs",
-    "src/global-dir.mjs",
-    "src/junction-manager.mjs",
-    "src/lib/",
-    "src/scripts/",
-    "src/skills/",
-    "templates/",
-    "configs/",
-    "agent-templates/"
-  ],
-  "exports": {
-    "./lib/find-root.mjs": "./src/lib/find-root.mjs",
-    "./lib/utils.mjs": "./src/lib/utils.mjs",
-    "./lib/logger.mjs": "./src/lib/logger.mjs",
-    "./lib/js-yaml.mjs": "./src/lib/js-yaml.mjs"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "scripts": {
-    "test": "node --test src/tests/*.test.mjs",
-    "test:skills": "node src/scripts/run-skill-tests.js --all",
-    "release": "npm version patch && npm publish"
-  },
-  "dependencies": {
-    "js-yaml": "^4.1.0"
-  }
-}
+{
+  "name": "workflow-ai",
+  "version": "1.2.1",
+  "description": "AI Agent Workflow Coordinator — kanban-based pipeline for AI coding agents",
+  "type": "module",
+  "bin": {
+    "workflow": "./bin/workflow.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/cli.mjs",
+    "src/init.mjs",
+    "src/runner.mjs",
+    "src/wf-loader.mjs",
+    "src/global-dir.mjs",
+    "src/junction-manager.mjs",
+    "src/lib/",
+    "src/scripts/*.js",
+    "src/skills/*/SKILL.md",
+    "src/skills/*/index.mjs",
+    "templates/",
+    "configs/",
+    "agent-templates/",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    "./lib/find-root.mjs": "./src/lib/find-root.mjs",
+    "./lib/utils.mjs": "./src/lib/utils.mjs",
+    "./lib/logger.mjs": "./src/lib/logger.mjs",
+    "./lib/js-yaml.mjs": "./src/lib/js-yaml.mjs",
+    "./lib/operations/tickets.mjs": "./src/lib/operations/tickets.mjs"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node --test src/tests/*.test.mjs",
+    "test:skills": "node src/scripts/run-skill-tests.js --all",
+    "release": "npm version patch && npm publish"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0"
+  }
+}

package/src/lib/operations/plans.mjs

@@ -0,0 +1,85 @@
+import { parseFrontmatter } from '../utils.mjs';
+import { fileURLToPath } from 'url';
+import path from 'path';
+import fs from 'fs/promises';
+
+/**
+ * List all plans in plans/current and plans/archive directories.
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {{ status?: string }} [options] - Filter options
+ * @returns {Promise<Array<{id: string, title: string, status: string, path: string}>>}
+ */
+export async function listPlans(projectRoot, { status } = {}) {
+  const plansDirs = [
+    path.join(projectRoot, 'plans', 'current'),
+    path.join(projectRoot, 'plans', 'archive')
+  ];
+
+  const allPlans = [];
+
+  for (const plansDir of plansDirs) {
+    try {
+      const files = await fs.readdir(plansDir);
+      for (const file of files) {
+        if (!file.endsWith('.md')) continue;
+        const filePath = path.join(plansDir, file);
+        const content = await fs.readFile(filePath, 'utf8');
+        const { frontmatter } = parseFrontmatter(content);
+        if (status && frontmatter.status !== status) continue;
+        allPlans.push({
+          id: frontmatter.id || file.replace('.md', ''),
+          title: frontmatter.title || '',
+          status: frontmatter.status || 'unknown',
+          path: filePath
+        });
+      }
+    } catch (err) {
+      // If directory doesn't exist, just skip it
+      if (err.code !== 'ENOENT') throw err;
+    }
+  }
+
+  return allPlans;
+}
+
+/**
+ * Get a specific plan by ID.
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {string} planId - Plan ID (e.g., 'PLAN-001')
+ * @returns {Promise<{frontmatter: object, body: string, path: string}>}
+ * @throws {Error} With code 'PLAN_NOT_FOUND' if plan not found
+ */
+export async function getPlan(projectRoot, planId) {
+  const plansDirs = [
+    path.join(projectRoot, 'plans', 'current'),
+    path.join(projectRoot, 'plans', 'archive')
+  ];
+
+  for (const plansDir of plansDirs) {
+    try {
+      const files = await fs.readdir(plansDir);
+      for (const file of files) {
+        if (!file.endsWith('.md')) continue;
+        // Normalize file name to plan ID format for comparison
+        const fileId = file.replace('.md', '');
+        if (fileId === planId || fileId.toUpperCase() === planId.toUpperCase()) {
+          const filePath = path.join(plansDir, file);
+          const content = await fs.readFile(filePath, 'utf8');
+          const { frontmatter, body } = parseFrontmatter(content);
+          return {
+            frontmatter,
+            body,
+            path: filePath
+          };
+        }
+      }
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+    }
+  }
+
+  const error = new Error(`Plan not found: ${planId}`);
+  error.code = 'PLAN_NOT_FOUND';
+  error.planId = planId;
+  throw error;
+}

package/src/lib/operations/skills.mjs

@@ -0,0 +1,124 @@
+import { findProjectRoot } from '../find-root.mjs';
+import { existsSync, lstatSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Lists all available skills, distinguishing between shared and ejected ones.
+ * 
+ * @param {string} [projectRoot] - Project root directory. If not provided, will be auto-detected.
+ * @returns {Promise<Array<{name: string, path: string, source: 'shared' | 'ejected'}>>}
+ */
+export async function listSkills(projectRoot) {
+  // Auto-detect project root if not provided
+  if (!projectRoot) {
+    projectRoot = findProjectRoot();
+  }
+
+  // Get global skills directory (from where this module is located)
+  // Assuming this file is in src/lib/operations/skills.mjs
+  // Global root is two levels up from src (since src is in project root)
+  const globalRoot = join(projectRoot, '..');
+  const globalSkillsDir = join(globalRoot, 'src', 'skills');
+  
+  // Project skills directory
+  const projectSkillsDir = join(projectRoot, '.workflow', 'src', 'skills');
+
+  const result = [];
+
+  // Check if global skills directory exists
+  if (!existsSync(globalSkillsDir)) {
+    return result;
+  }
+
+  // Read global skills
+  const globalSkills = readdirSync(globalSkillsDir, { withFileTypes: true })
+    .filter(entry => entry.isDirectory())
+    .map(entry => entry.name);
+
+  // Check if project skills directory exists
+  if (existsSync(projectSkillsDir)) {
+    // Check if it's a junction/symlink
+    let isJunctionLink = false;
+    try {
+      const stats = lstatSync(projectSkillsDir);
+      isJunctionLink = stats.isSymbolicLink();
+    } catch (error) {
+      // If lstat fails, treat as not a junction
+      isJunctionLink = false;
+    }
+
+    if (isJunctionLink) {
+      // If it's a junction, all skills in it are considered shared
+      const projectSkills = readdirSync(projectSkillsDir, { withFileTypes: true })
+        .filter(entry => entry.isDirectory())
+        .map(entry => entry.name);
+
+      // Add all skills as shared (from junction)
+      for (const skillName of [...new Set([...globalSkills, ...projectSkills])]) {
+        result.push({
+          name: skillName,
+          path: join(globalSkillsDir, skillName),
+          source: 'shared'
+        });
+      }
+    } else {
+      // Not a junction - handle ejected skills
+      const projectSkills = readdirSync(projectSkillsDir, { withFileTypes: true })
+        .filter(entry => entry.isDirectory())
+        .map(entry => entry.name);
+
+      // First, add all global skills as shared
+      for (const skillName of globalSkills) {
+        result.push({
+          name: skillName,
+          path: join(globalSkillsDir, skillName),
+          source: 'shared'
+        });
+      }
+
+      // Then, override with ejected skills where applicable
+      const ejectedSkillsMap = new Map();
+      for (const skillName of projectSkills) {
+        ejectedSkillsMap.set(skillName, join(projectSkillsDir, skillName));
+      }
+
+      // Build final result: ejected overrides shared
+      const finalResult = [];
+      const processedSkills = new Set();
+
+      // Add ejected skills first
+      for (const [skillName, skillPath] of ejectedSkillsMap) {
+        finalResult.push({
+          name: skillName,
+          path: skillPath,
+          source: 'ejected'
+        });
+        processedSkills.add(skillName);
+      }
+
+      // Add global skills that weren't overridden
+      for (const skillName of globalSkills) {
+        if (!processedSkills.has(skillName)) {
+          finalResult.push({
+            name: skillName,
+            path: join(globalSkillsDir, skillName),
+            source: 'shared'
+          });
+        }
+      }
+
+      return finalResult;
+    }
+  } else {
+    // No project skills directory - return all global skills as shared
+    for (const skillName of globalSkills) {
+      result.push({
+        name: skillName,
+        path: join(globalSkillsDir, skillName),
+        source: 'shared'
+      });
+    }
+  }
+
+  return result;
+}