KDCO Primitives

Relevant source files

The following files were used as context for generating this wiki page:

• workers/kdco-registry/files/plugin/kdco-primitives/index.ts
• workers/kdco-registry/files/plugin/kdco-primitives/shell.ts
• workers/kdco-registry/files/plugin/kdco-primitives/mutex.ts
• workers/kdco-registry/files/plugin/workspace-plugin.ts
• workers/kdco-registry/files/skill/code-philosophy/SKILL.md
• AGENTS.md

KDCO Primitives represent the foundational logic and utility layer for the KDCO registry components within the OCX ecosystem. These primitives enforce a rigorous architectural standard known as the 5 Laws of Elegant Defense, ensuring that core utilities for filesystem operations, process management, and synchronization remain flat, safe, and predictable.

The primary scope of these primitives is to support higher-level plugins, such as the workspace-plugin, by providing reliable mechanisms for project identification, atomic operations, and boundary-safe data processing. They serve as the technical implementation of the "Elegant Simplicity" philosophy, where code guides data naturally to prevent errors before they occur.

Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:257-262, workers/kdco-registry/files/skill/code-philosophy/SKILL.md:6-10

The 5 Laws of Elegant Defense

KDCO Primitives are built upon five core development principles designed to minimize complexity and maximize reliability.

Law	Principle	Implementation Strategy
Early Exit	Indentation is the enemy.	Use guard clauses at the top of functions to handle edge cases and nulls immediately.
Parse, Don't Validate	Make illegal states unrepresentable.	Parse inputs at boundaries (e.g., using Zod) so internal logic only handles trusted, typed states.
Atomic Predictability	Functions must never surprise.	Favor pure functions where the same input always yields the same output without hidden mutations.
Fail Fast, Fail Loud	Descriptive errors over silent failures.	Halt execution immediately with clear errors if an invalid state is detected.
Intentional Naming	Self-documenting code.	Name variables and functions so clearly that the logic reads like a sentence.

Sources: workers/kdco-registry/files/skill/code-philosophy/SKILL.md:12-32, workers/kdco-registry/files/plugin/workspace-plugin.ts:167-175

Core Utilities and Architecture

Project Identification and Persistence

A critical primitive involves resolving the projectId to ensure cross-worktree consistency. This is achieved by utilizing the Git root commit hash, which allows the system to map a project to a persistent directory in the user's local share folder (~/.local/share/opencode/workspace/).

The diagram shows the flow of deriving a unique, persistent filesystem path for a project based on its Git identity.
Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:468-472

Plan Management and Validation

The workspace-plugin leverages primitives to manage implementation plans. The parsing logic strictly follows the "Parse, Don't Validate" law by extracting raw markdown parts and subjecting them to a single Zod schema validation point.

• Boundary Parsing: Raw markdown is broken into frontmatter, goals, and hierarchical phases.
• Hierarchical IDs: Tasks must follow a \d+\.\d+ format (e.g., '1.1').
• State Enforcement: Only one task can be marked as ← CURRENT across the entire plan.

Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:10-33, workers/kdco-registry/files/plugin/workspace-plugin.ts:167-200

Session Scope Resolution

KDCO Primitives include logic to resolve the root session ID by traversing the session parent chain. This ensures that tools like plan_save operate within the correct hierarchical context, preventing state fragmentation in deeply nested agent delegations.

The sequence shows the recursive traversal logic used to find the top-level orchestrator session.
Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:477-498

System Rule Injection

KDCO Primitives facilitate the injection of "System Reminders" into the AI context. These are targeted rules injected via the experimental.chat.system.transform hook based on the active agent's role (e.g., plan or build).

Routing and Boundary Constraints

The primitives enforce strict boundaries between different agent types to prevent "tool sprawl" and ensure specific specialists handle appropriate tasks.

Agent	Scope	Critical Constraint
explore	Internal Only	Cannot access external resources (docs, web, APIs).
researcher	External Only	Cannot search internal codebase files.
coder	Implementation	Handles all code modifications and bash execution.
scribe	Prose/Docs	Restricted to human-facing content; no bash access.

Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:314-340, workers/kdco-registry/files/plugin/workspace-plugin.ts:397-414

Execution Primitives: Task Tracking

The system tracks the lifecycle of asynchronous tasks to trigger automated workflows, such as code reviews. A Map is used to store active callIDs with timestamps, paired with a periodic cleanup interval to handle orphaned or stale calls (timeout set to 15 minutes).

// Tracking in-flight coder tasks
const activeCoderCalls = new Map<string, { startTime: number }>()
const STALE_CALL_TIMEOUT_MS = 15 * 60 * 1000

// Periodic cleanup of orphaned callIDs (runs every 60s)
const cleanupInterval = setInterval(() => {
	const now = Date.now()
	for (const [callID, data] of activeCoderCalls) {
		if (now - data.startTime > STALE_CALL_TIMEOUT_MS) {
			activeCoderCalls.delete(callID)
		}
	}
}, 60_000)

Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:275-290

Summary

KDCO Primitives establish the operational backbone of the KDCO extension suite. By centralizing logic for session management, project identification, and strict validation protocols, they ensure that AI agents operate within safe, predictable, and highly structured environments. This technical foundation allows the system to scale from simple task execution to complex, multi-agent orchestrations while maintaining a "Fail Fast, Fail Loud" safety net.

Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:257-262, workers/kdco-registry/files/skill/code-philosophy/SKILL.md:34-40