📦 @goodandready/dsh-agent-orchestrator
Multi-Agent Task Decomposition, DAG Workflow Orchestration & Prompt Caching Engine for DeepSeek Harness
🇬🇧 English •
🇷🇺 Русский •
🇨🇳 中文说明
⭐ If you like this plugin, please star it on GitHub — it shows me that the plugin is useful to you and motivates me to keep developing it.
🐛 If you find a bug or would like to request a feature, open a GitHub issue in any language — I will review your proposal and implement useful suggestions in a future plugin version.
|
⚡ 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:
- 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.
- DAG Execution Engine: Schedules tasks based on Directed Acyclic Graph dependencies, running independent stages concurrently while strictly enforcing blocker gates.
- 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.
- Strict Separation of Duties: Backend implementation, UI interface design, and frontend client assembly are strictly isolated into distinct personas and execution stages.
- Dual Surface Integration: Dispatched natively via
/orchestrate in DSH chat (with a sticky header milestone card) or via @goodandready/dsh-kanban task boards.
🏗️ Architecture
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
- Hotfix / Trivial (1 Stage): Instant defect elimination or single-parameter tweak.
- Simple (2 Stages): Discussion & Spec $\rightarrow$ Targeted Execution.
- Medium (3–4 Stages): Spec $\rightarrow$ UI Design $\rightarrow$ Frontend Code $\rightarrow$ QA Tests.
- Complex (5–6 Stages): Spec $\rightarrow$ Architecture $\rightarrow$ UI Design $\rightarrow$ Implementation $\rightarrow$ QA $\rightarrow$ Trilingual Docs.
- 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.
- 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:
- Layer 1: Static Base Anchor (>1024 tokens): Byte-identical guidelines and tools definition common across all agents.
- Layer 2: Shared Task Anchor: Stable description of user objective and target repository.
- Layer 3: Cumulative Context (Append-Only): Outputs of predecessor stages appended in a deterministic sequence, preserving 100% of the preceding KV-cache.
- 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
/orchestrate Design and build a settings card for the finance plugin
Explicit scenario selection:
/orchestrate complex Build a multi-tenant authentication provider
/orchestrate hotfix Fix null reference in store.js
Short alias:
/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):
node --test test/*.test.mjs
Verify npm package bundle size compliance (<256 KiB threshold):
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
📄 License
MIT © GooDAnDReaDY
