Architecture

DojOps is designed as a modular, layered DevOps agent system — not a simple chatbot that generates bash commands. It is a structured, safe, extensible orchestration framework with 12 built-in DevOps tools, a custom tool system for extending with additional tools, 16 specialist agents, sandboxed execution, approval workflows, and hash-chained audit trails.

High-Level Data Flow

User
 |
 v
CLI (@clack/prompts TUI) / REST API (Express)
 |
 v
Agent Router (16 specialist agents, keyword confidence scoring)
 |
 v
Planner Engine (LLM -> TaskGraph -> topological execution)
 |
 v
Tool Registry (12 built-in tools + custom tools, unified discovery)
 |
 v
Tool SDK Layer (BaseTool<T>, Zod validation)
 |
 v
Execution Engine (Sandboxed, policy-enforced, approval-gated, audit-logged)

Package Architecture

DojOps is a pnpm monorepo with Turbo build orchestration. TypeScript (ES2022, CommonJS). All packages use the @dojops/* scope.

10 Packages

@dojops/cli            CLI entry point + rich TUI (@clack/prompts)
@dojops/api            REST API (Express) + web dashboard + factory functions
@dojops/tool-registry  Tool registry + custom tool system (discovers built-in + custom tools)
@dojops/planner        TaskGraph decomposition + topological executor
@dojops/executor       SafeExecutor: sandbox + policy engine + approval + audit log
@dojops/runtime        12 built-in DevOps tools (GitHub Actions, Terraform, K8s, Helm, Ansible,
                       Docker Compose, Dockerfile, Nginx, Makefile, GitLab CI, Prometheus, Systemd)
@dojops/scanner        9 security scanners + remediation engine
@dojops/session        Chat session management + memory + context injection
@dojops/core           LLM abstraction + 6 providers + 16 specialist agents + CI debugger + infra diff + DevOps checker
@dojops/sdk            BaseTool<T> abstract class with Zod validation + optional verify() + file-reader utilities

Dependency Flow

@dojops/cli
  +-- @dojops/api
  |     +-- @dojops/tool-registry
  |     |     +-- @dojops/runtime
  |     |     |     +-- @dojops/core
  |     |     |     +-- @dojops/sdk
  |     |     +-- @dojops/core
  |     |     +-- @dojops/sdk (zod)
  |     +-- @dojops/planner
  |     |     +-- @dojops/core
  |     |           +-- @dojops/sdk (zod)
  |     +-- @dojops/executor
  |     |     +-- @dojops/sdk
  |     +-- @dojops/scanner
  |     +-- @dojops/session
  |           +-- @dojops/core

Simplified linear flow:

cli -> api -> tool-registry -> runtime -> core -> sdk
          -> planner -> executor
          -> scanner
          -> session -> core

Layer Descriptions

1. LLM Layer (@dojops/core)

Abstraction over six LLM providers with structured JSON output:

Key interface:

interface LLMProvider {
  name: string;
  generate(request: LLMRequest): Promise<LLMResponse>;
  listModels?(): Promise<string[]>;
}

All responses pass through parseAndValidate() — strips markdown fences, JSON.parse, Zod safeParse — ensuring every LLM output conforms to the expected schema. All 6 providers support temperature passthrough for deterministic reproducibility (conditionally included in API calls only when explicitly set). A DeterministicProvider wrapper forces temperature: 0 on every call for replay mode (apply --replay). The GitHubCopilotProvider creates a new OpenAI client per generate() call to use the freshest JWT (tokens expire every ~30 min).

2. Multi-Agent System (@dojops/core)

16 built-in specialist agents with keyword-based routing and confidence scoring, plus support for custom agents. The AgentRouter scores prompts against each agent’s keyword list and routes to the highest-confidence match. If no agent exceeds the threshold, it falls back to the general-purpose DevOpsAgent.

Custom agents are defined as structured README.md files in .dojops/agents/<name>/ (project) or ~/.dojops/agents/<name>/ (global). They can be created via LLM (dojops agents create "description") or manually (dojops agents create --manual). Custom agents participate in the same keyword-based routing as built-in agents and can override built-in agents by name. Discovery is handled by @dojops/tool-registry.

Additionally, three specialized analyzers (not routed via AgentRouter) provide structured analysis:

• CIDebugger — CI log diagnosis producing CIDiagnosis (error type, root cause, fixes)
• InfraDiffAnalyzer — Infrastructure diff analysis producing InfraDiffAnalysis (risk, cost, security)
• DevOpsChecker — DevOps config quality analysis producing CheckReport (score 0-100, findings, missing files)

See Specialist Agents for the full agent list.

3. Task Planner (@dojops/planner)

LLM-powered goal decomposition into structured, dependency-aware task graphs. Uses Kahn’s algorithm for topological execution ordering, $ref:<taskId> for inter-task data wiring, and completedTaskIds for resume after partial failures.

See Task Planner for details.

4. Tool SDK (@dojops/sdk)

Abstract BaseTool<T> class with Zod input schema validation, abstract generate() for LLM generation, optional execute() for file writes, and optional verify() for external tool validation. Also provides readExistingConfig(), backupFile(), atomicWriteFileSync() (temp + rename for crash-safe writes), and restoreBackup() utilities.

See DevOps Tools for the tool pattern.

4b. DOPS Runtime (@dojops/runtime)

The DOPS runtime processes .dops module files — a declarative format combining YAML frontmatter with markdown prompt sections. Each .dops file defines a complete tool: input/output schemas, file specs, prompt templates, and metadata.

Frontmatter sections (all optional except meta, output, files):

Markdown sections: ## Prompt (required), ## Update Prompt (optional), ## Examples, ## Constraints, ## Keywords (required).

Key runtime features:

• DopsRuntime.risk — Returns declared risk or defaults to { level: "LOW", rationale: "No risk classification declared" }
• DopsRuntime.executionMode — Returns declared execution semantics or defaults to { mode: "generate", deterministic: false, idempotent: false }
• DopsRuntime.metadata — Includes riskLevel, icon, systemPromptHash, toolHash for audit and marketplace integration
• Scope enforcement — writeFiles() validates resolved paths against scope.write patterns after {var} expansion; out-of-scope writes throw
• Update strategy — preserve_structure injects additional prompt instructions to maintain existing config organization

5. DevOps Tools (@dojops/runtime)

12 built-in tools covering CI/CD, IaC, containers, monitoring, and system services. Each follows the same file pattern: schemas.ts -> detector.ts -> generator.ts -> verifier.ts -> *-tool.ts. All tools support updating existing configs via auto-detection, existingContent input, and .bak backup before overwrite. All file writes use atomicWriteFileSync() for crash safety. YAML generators use sorted keys for idempotent output. Every execute() returns filesWritten/filesModified for rollback tracking.

See DevOps Tools for the full tool list.

5b. Tool Registry (@dojops/tool-registry)

Unified registry layer between consumers (Planner, Executor, CLI, API) and tool implementations. Combines all 12 built-in tools with custom tools discovered from disk:

• Custom tool discovery — Scans ~/.dojops/tools/ (global) and .dojops/tools/ (project) for tool.yaml manifests
• Manifest validation — Zod schema validates tool manifests; JSON Schema inputs are converted to Zod at runtime
• CustomTool adapter — Converts declarative tool.yaml into a DevOpsTool-compatible object with generate/execute/verify
• Tool policy — .dojops/policy.yaml supports allowedTools and blockedTools lists
• Audit enrichment — Custom tool executions include toolType, toolSource, toolVersion, toolHash, and systemPromptHash in audit entries
• Tool isolation — Verification commands restricted to a whitelist of 16 allowed binaries (terraform, kubectl, helm, etc.), child_process permission must be "required" for execution, path traversal (..) blocked in manifest file paths and detector paths
• Unified interface — ToolRegistry.getAll() returns DevOpsTool[], so Planner, Executor, and API remain unchanged

6. Execution Engine (@dojops/executor)

Orchestrates generate -> verify -> approve -> execute with policy enforcement, sandboxed file operations, and audit logging.

See Execution Engine for details.

7. Security Scanner (@dojops/scanner)

9 scanners (npm-audit, pip-audit, trivy, gitleaks, checkov, hadolint, shellcheck, trivy-sbom, semgrep) with LLM-powered remediation and scan comparison (--compare).

See Security Scanning for details.

8. Chat Sessions (@dojops/session)

Multi-turn conversation management with memory windowing, LLM-generated summaries, project context injection, and session persistence.

9. REST API & Dashboard (@dojops/api)

Express-based API with dependency injection via createApp(deps). Uses @dojops/tool-registry to load all built-in + custom tools. 19 endpoints exposing all capabilities over HTTP with API v1 versioning (/api/v1/ prefix with backward-compatible /api/ alias, X-API-Version: 1 header on v1 routes). Vanilla web dashboard with 5 tabs (Overview, Security, Audit, Agents, History). Health endpoint reports customToolCount.

See API Reference and Web Dashboard.

10. CLI (@dojops/cli)

Full-lifecycle CLI with rich TUI powered by @clack/prompts. Interactive prompts, spinners, styled panels, semantic log levels. Includes dojops init (comprehensive repo scanner with 11 CI platforms, IaC, scripts, security detection) and dojops check (LLM-powered DevOps config quality analysis).

See CLI Reference.

Design Principles

1. No blind execution — Every LLM output is validated before use.
2. Structured JSON outputs — Provider-native JSON modes + Zod schemas on all LLM responses.
3. Schema validation everywhere — Tool inputs, LLM responses, plan structures, API requests.
4. Idempotent operations — Generated configs produce the same result on re-execution. YAML keys are sorted for deterministic output.
5. Clear separation of concerns — Orchestration, generation, validation, execution, and auditing are independent layers.
6. Extensibility — New tools follow the BaseTool<T> pattern. New agents are registered in the specialist list.
7. Declarative safety — .dops modules declare their own scope boundaries, risk levels, and execution semantics, enabling automated policy enforcement without hardcoded tool-specific rules.

Data Storage

DojOps stores project state in the .dojops/ directory:

.dojops/
  context.json           Project context v2 (languages, 11 CI platforms, IaC, containers,
                         monitoring/web servers, scripts, security configs, devopsFiles[])
  session.json           Current session state
  plans/                 Saved TaskGraph plans (*.json)
  execution-logs/        Per-execution results (*.json)
  scan-history/          Security scan reports (*.json)
  sessions/              Chat session persistence (*.json)
  tools/                 Project-scoped custom tools (tool.yaml + input.schema.json)
  agents/                Project-scoped custom agents (<name>/README.md)
  policy.yaml            Tool policy (allowedTools / blockedTools)
  history/
    audit.jsonl          Hash-chained audit log (append-only)
  lock.json              Execution lock (PID-based)

~/.dojops/
  tools/                 Global custom tools (shared across projects)
  toolchain/             System binary sandbox (installed verification binaries)
  agents/                Global custom agents (shared across projects)