@goodandready/dsh-agent-orchestrator 0.1.6

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 GooDAnDReaDY
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,184 @@
+# 📦 @goodandready/dsh-agent-orchestrator
+
+<div align="center">
+
+<h3>Multi-Agent Task Decomposition, DAG Workflow Orchestration & Prompt Caching Engine for DeepSeek Harness</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-agent-orchestrator"><img src="https://img.shields.io/npm/v/@goodandready/dsh-agent-orchestrator.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-agent-orchestrator.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+</p>
+
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/All_Author_Projects-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="All Author Projects"></a>
+</p>
+
+<p align="center">
+  <a href="README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+
+<table align="center">
+  <tr>
+    <td align="center">
+      ⭐ <strong>If you like this plugin, please star it on GitHub</strong> — it shows me that the plugin is useful to you and motivates me to keep developing it.
+      <br><br>
+      🐛 <strong>If you find a bug or would like to request a feature</strong>, open a GitHub issue in any language — I will review your proposal and implement useful suggestions in a future plugin version.
+    </td>
+  </tr>
+</table>
+
+</div>
+
+---
+
+## ⚡ Overview & The Problem
+
+Single-agent software engineering architectures suffer from cognitive overload when tasked with complex multi-stage projects: monolithic prompts conflate architecture, styling, core business logic, testing, and documentation into a single generation pass, leading to hallucinated contracts, regression bugs, and excessive token expenditure.
+
+Furthermore, executing multiple subagents independently often resets the LLM KV-cache on each turn, forfeiting prefix cache reuse and incurring substantial latency and financial overhead.
+
+**`@goodandready/dsh-agent-orchestrator`** introduces an autonomous multi-agent orchestration framework to DeepSeek Harness:
+
+1. **Intelligent Triage & Decomposition**: Analyzes high-level objectives from chat or Kanban cards and breaks them down into fine-grained stages across **12 specialized agent roles**.
+2. **DAG Execution Engine**: Schedules tasks based on Directed Acyclic Graph dependencies, running independent stages concurrently while strictly enforcing blocker gates.
+3. **KV-Cache / Prompt Caching Optimizer**: Guarantees byte-level prefix invariance for subagents sharing identical models, unlocking 80–90% prompt token cache hits and near-instant TTFT.
+4. **Strict Separation of Duties**: Backend implementation, UI interface design, and frontend client assembly are strictly isolated into distinct personas and execution stages.
+5. **Dual Surface Integration**: Dispatched natively via `/orchestrate` in DSH chat (with a sticky header milestone card) or via `@goodandready/dsh-kanban` task boards.
+
+---
+
+## 🏗️ Architecture
+
+```mermaid
+graph TD
+    Trigger["Input Task<br/>(/orchestrate in Chat or Kanban Card)"] --> Main["Lead Orchestrator (Triage)"]
+    
+    subgraph Engine ["DAG Engine & Prompt Caching"]
+        L1["Layer 1: Canonical Base Anchor (>1024 tokens)"]
+        L2["Layer 2: Shared Task Anchor"]
+        L3["Layer 3: Cumulative Artifacts (Append-Only)"]
+        L4["Layer 4: Role Suffix Directive"]
+    end
+
+    Main --> Engine
+
+    subgraph AgentPool ["Configured Agent Personas (Self-Contained in Settings)"]
+        R1["Technical Spec Analyst"]
+        R2["System Architect"]
+        R3["UI/UX Interface Designer"]
+        R4["Backend Developer"]
+        R5["Frontend Developer"]
+        R6["QA Automation Specialist"]
+        R7["Documentation Specialist"]
+    end
+
+    Engine --> AgentPool
+    AgentPool --> Delivery["Orchestrated Delivery<br/>(Header Utility Card & Kanban Sync)"]
+```
+
+---
+
+## 👥 12 Built-In Specialized Agent Roles
+
+All agent profiles are **completely self-contained within plugin settings** (no external file dependencies):
+
+| Role ID | Title | Specialization | Strict Boundaries |
+|---|---|---|---|
+| `spec` | Technical Spec Analyst | Requirements, Acceptance Criteria (DoD), Schemas | Never writes implementation or styling |
+| `architecture` | System Architect | System Design, DESIGN.md, ADR, Modular Contracts | Never implements production code or deploys |
+| `ui_design` | UI/UX Interface Designer | Layouts, Theme Tokens (`--dsw-alias-*`), Slots | Never writes backend Cordis services |
+| `frontend` | Frontend Developer | React Components, Client Hooks, DOM Events | Never alters backend routes or DB schemas |
+| `backend` | Backend Developer | Cordis Services, WebServer Routes, Data Store | Never writes client React JSX or styles |
+| `fullstack` | Fullstack Integrator | Client-Server Contract Wiring, End-to-End Flow | Adheres strictly to modular limits |
+| `qa_tests` | QA Automation Specialist | Unit Tests (`node:test`), Boundary Verification | Verifies without external network calls |
+| `bugfix` | Hotfix & Triage Engineer | Root-Cause Diagnosis, Minimal Blast Radius Fixes | Never refactors unrelated code |
+| `docs` | Documentation Specialist | Trilingual Documentation (en/ru/zh), Releases | Never overwrites previous documentation |
+| `refactoring` | Refactoring Specialist | Complexity Reduction (YAGNI), Bundle Compression | Preserves backwards compatibility |
+| `research` | Research & Spike Engineer | Technology Evaluation, Library Trade-Offs | Delivers analysis; never merges spike code |
+| `devops` | DevOps & Tooling Engineer | Package Manifests, Build Verification, Systemd | Never exposes private network credentials |
+
+---
+
+## 🔄 Complexity Scenarios
+
+1. **Hotfix / Trivial (1 Stage)**: Instant defect elimination or single-parameter tweak.
+2. **Simple (2 Stages)**: Discussion & Spec $\rightarrow$ Targeted Execution.
+3. **Medium (3–4 Stages)**: Spec $\rightarrow$ UI Design $\rightarrow$ Frontend Code $\rightarrow$ QA Tests.
+4. **Complex (5–6 Stages)**: Spec $\rightarrow$ Architecture $\rightarrow$ UI Design $\rightarrow$ Implementation $\rightarrow$ QA $\rightarrow$ Trilingual Docs.
+5. **Enterprise / Deep R&D (7 Stages)**: Spike Research $\rightarrow$ Spec $\rightarrow$ Architecture $\rightarrow$ Parallel Backend & UI Design $\rightarrow$ Frontend Assembly $\rightarrow$ Comprehensive QA $\rightarrow$ Documentation Gate.
+6. **Custom DAG Scenarios**: Fully configurable in plugin settings with custom stages and blocker checkboxes.
+
+---
+
+## ⚡ Prompt Caching Mechanics
+
+Modern LLMs (DeepSeek-V3, Claude 3.5 Sonnet, vLLM) cache prompt KV states strictly from the first token forward. If non-deterministic timestamps or random IDs are placed in the prompt header, cache hit rate drops to 0%.
+
+`dsh-agent-orchestrator` enforces a **4-layer canonical layout**:
+1. **Layer 1: Static Base Anchor (>1024 tokens)**: Byte-identical guidelines and tools definition common across all agents.
+2. **Layer 2: Shared Task Anchor**: Stable description of user objective and target repository.
+3. **Layer 3: Cumulative Context (Append-Only)**: Outputs of predecessor stages appended in a deterministic sequence, preserving 100% of the preceding KV-cache.
+4. **Layer 4: Role Directive (Suffix)**: Role persona prompt, skills, and subtask-specific scope appended at the end.
+
+This architecture delivers **80–95% cache hits** across subagents utilizing the same model, reducing TTFT and cutting token costs by ~90%.
+
+---
+
+## 💻 Usage
+
+### 1. In DSH Chat via Slash Command
+```text
+/orchestrate Design and build a settings card for the finance plugin
+```
+
+Explicit scenario selection:
+```text
+/orchestrate complex Build a multi-tenant authentication provider
+/orchestrate hotfix Fix null reference in store.js
+```
+
+Short alias:
+```text
+/orc Refactor state management
+```
+
+### 2. In @goodandready/dsh-kanban
+- Open any card on the board.
+- Click **[Собрать пайплайн / Assemble Pipeline]**.
+- Select the complexity preset or allow auto-triage.
+- The card automatically reflects stage transitions and advances to `Review` upon completion.
+
+---
+
+## 🧪 Verification & Automated Testing
+
+Execute the native test suite (121 passing tests across 53 suites, zero network dependencies):
+
+```bash
+node --test test/*.test.mjs
+```
+
+Verify npm package bundle size compliance (<256 KiB threshold):
+
+```bash
+npm pack --dry-run --json
+```
+
+---
+
+## Visual verification
+
+Production acceptance of v0.1.6 — Settings card, Dark and Light themes side by side:
+
+![dsh-agent-orchestrator v0.1.6 visual verification](media/visual-verification.png)
+
+---
+
+## 📄 License
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
+

package/README.ru.md

@@ -0,0 +1,86 @@
+# 📦 @goodandready/dsh-agent-orchestrator
+
+<div align="center">
+
+<h3>Мульти-агентная декомпозиция задач, DAG-оркестрация и оптимизатор Prompt Caching для DeepSeek Harness</h3>
+
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/Все_проекты_автора-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="Все проекты автора"></a>
+</p>
+
+<p align="center">
+  <a href="README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+
+</div>
+
+---
+
+## ⚡ Обзор и решаемая проблема
+
+При выполнении комплексных многоэтапных проектов один агент неизбежно сталкивается с перегрузкой контекста: в один монолитный запрос смешиваются архитектура, дизайн, верстка, бэкенд, тестирование и написание документации. Это приводит к галлюцинациям, нарушению контрактов и неоправданным затратам токенов.
+
+Кроме того, запуск независимых субагентов обычно сбрасывает KV-кэш языковой модели на каждом шаге, теряя преимущества префиксного кэширования (Prompt Caching) и приводя к долгим задержкам ответа.
+
+**`@goodandready/dsh-agent-orchestrator`** внедряет автономную мульти-агентную оркестрацию в DeepSeek Harness:
+
+1. **Триаж и декомпозиция**: Анализирует задачу из чата или карточки Канбана и разбивает её на этапы между **12 специализированными ролями агентов**.
+2. **Графовый DAG-движок**: Планирует задачи на основе направленного ациклического графа, исполняя независимые ветки параллельно и контролируя блокеры.
+3. **Оптимизатор Prompt Caching (KV-кэш)**: Гарантирует побайтовое совпадение префикса для агентов с одинаковыми моделями, обеспечивая 80–90% Cache Hit и моментальный старт генерации.
+4. **Строгое разделение труда**: Бэкенд, UI-дизайн и клиентский фронтенд строго изолированы по разным ролям и этапам.
+5. **Два режима работы**: Через команду `/orchestrate` в чате DSH (с плавающей карточкой прогресса в шапке) или через доску задач `@goodandready/dsh-kanban`.
+
+---
+
+## 👥 12 специализированных ролей агентов
+
+Все профили агентов **хранятся и управляются исключительно внутри настроек плагина** (без внешних зависимостей от диска):
+- **ТЗ-аналитик (`spec`)**: требования, критерии приёмки (DoD), границы задачи.
+- **Архитектор (`architecture`)**: системный дизайн, DESIGN.md, ADR, модульные контракты.
+- **UI/UX Дизайнер (`ui_design`)**: дизайн-система, CSS-переменные (`--dsw-alias-*`), слоты.
+- **Фронтендер (`frontend`)**: компоненты React, хуки, клиентские состояния.
+- **Бэкендер (`backend`)**: сервисы Cordis, роуты webServer, базы данных, хранилище.
+- **Фуллстек-интегратор (`fullstack`)**: сквозная сборка контрактов клиент-сервер.
+- **QA-инженер (`qa_tests`)**: модульные тесты (`node:test`), проверка граничных условий.
+- **Hotfix-инженер (`bugfix`)**: диагностика и минимальный целевой фикс без регрессий.
+- **Технический писатель (`docs`)**: трёхъязычная документация (en/ru/zh), релиз-ноутс.
+- **Рефакторинг-специалист (`refactoring`)**: чистка кода (YAGNI, ponytail), оптимизация бандла (<250 Кб).
+- **Research-инженер (`research`)**: оценка технологий, библиотек, сравнительные спайки.
+- **DevOps-инженер (`devops`)**: манифесты пакетов, проверка сборки, systemd сервисы.
+
+---
+
+## 💻 Использование
+
+### 1. В чате DSH через слэш-команду
+```text
+/orchestrate Сделай карточку настроек для плагина финансов
+```
+С указанием сценария сложности:
+```text
+/orchestrate complex Разработай систему очередей задач с бэком и веб-панелью
+/orchestrate hotfix Исправь падение при null в store.js
+```
+Быстрый алиас:
+```text
+/orc Рефакторинг управления состоянием
+```
+
+### 2. В @goodandready/dsh-kanban
+- Открой карточку задачи на доске.
+- Нажми **[Собрать пайплайн]**.
+- Выбери сценарий сложности или оставь авто-триаж.
+- Карточка сама отразит этапы и перейдёт в `Review` по завершении.
+
+---
+
+## 🧪 Запуск тестов
+
+```bash
+node --test test/*.test.mjs
+```
+
+Лицензия: MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
+

package/README.zh.md

@@ -0,0 +1,64 @@
+# 📦 @goodandready/dsh-agent-orchestrator
+
+<div align="center">
+
+<h3>面向 DeepSeek Harness 的多智能体任务分解、DAG 工作流编排与提示词缓存优化引擎</h3>
+
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/作者所有项目-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="作者所有项目"></a>
+</p>
+
+<p align="center">
+  <a href="README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+
+</div>
+
+---
+
+## ⚡ 概述与解决的问题
+
+在执行复杂的多阶段工程任务时，单一智能体架构往往面临上下文过载：单一请求中混合了系统架构、界面设计、前端编码、后端逻辑、单元测试与文档编写，容易导致幻觉与契约不一致。
+
+此外，独立调用多个子智能体会导致每次推理重新建立 KV 缓存，无法重用提示词前缀缓存（Prompt Caching），造成严重的延迟与计算开销。
+
+**`@goodandready/dsh-agent-orchestrator`** 为 DeepSeek Harness 带来了自主的多智能体编排框架：
+
+1. **智能分流与分解**：分析聊天或看板卡片的目标，将其分解并分发给 **12 个专用智能体角色**。
+2. **有向无环图 (DAG) 引擎**：基于依赖关系并行调度无阻塞任务，严格控制前置阶段。
+3. **提示词缓存优化 (KV Cache Optimizer)**：确保相同模型的智能体在字节级上共享规范前缀，实现 80–90% 的缓存命中率。
+4. **职责严格分离**：后端逻辑、界面设计与前端实现彼此独立，严禁单一智能体混同处理。
+5. **双重使用场景**：支持通过 DSH 聊天斜杠命令 `/orchestrate` 触发，或无缝嵌入 `@goodandready/dsh-kanban` 任务看板。
+
+---
+
+## 💻 使用方法
+
+### 1. 在 DSH 聊天中通过斜杠命令触发
+```text
+/orchestrate 为财务插件设计并开发设置卡片
+```
+
+指定复杂度模式：
+```text
+/orchestrate complex 开发带有后端和前端界面的任务排队系统
+/orchestrate hotfix 修复 store.js 中的空指针异常
+```
+
+简短别名：
+```text
+/orc 重构状态管理模块
+```
+
+---
+
+## 🧪 单元测试
+
+```bash
+node --test test/*.test.mjs
+```
+
+许可证：MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
+

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+- insert:
+    - id: dsh-agent-orchestrator
+      name: '@goodandready/dsh-agent-orchestrator'
+      config: {}
+