Developer & Agent Guides
Practical, battle-tested execution guides for human software engineers and autonomous AI agents working within the ZQK Knowledge Kernel.
Overview
While the Reference Manual details comprehensive subsystem APIs and Specifications formalize architectural grammar, these Guides provide step-by-step, actionable recipes for common engineering disciplines, graph operations, and multi-agent coordination patterns.
Every guide is structured to serve both human pair programmers using the interactive CLI/TUI and autonomous AI agents operating via headless interfaces or Model Context Protocol (MCP) tools.
Operational Guide Directory
1. Knowledge Graph & Data Plane Operations
| Guide | Focus Area | Target Audience | Primary CLI & MCP Commands |
|---|---|---|---|
| Knowledge Kernel Object Model & Usage Guide | Canonical taxonomy across all 14 ontological domains and packs (70+ object kinds), standard envelopes, VDS cascade, and copy-pasteable CLI recipes. | All Engineers & Agents | zqk object create, zqk object list, zqk object ref add, zqk object promote |
| CLI Kind Alias Parity Guide | Specification of canonical kind shorthand aliases (tst, tc, crit, req, pri, bli, mil, goal) across zqk new and object new CLI entrypoints. | All Engineers & Agents | zqk new, zqk object new, pkg/kindsynonyms |
| Object Scaffolding Hygiene and Reference Field Initialization Guide | Reference field initialization invariants across CLI scaffolding templates, omission of optional references, empty array typing, and strict validation. | All Engineers & Agents | zqk object template, zqk new, pkg/validation |
| Kernel Subsystem Operational & Architectural Guide | Cellular microkernel architecture, KnowledgeKernel lifecycle, relational graph membrane, adjacency engine, plane boundary enforcer, extension registry, and >=85.0% coverage invariant. | Kernel Architects & Agents | pkg/kernel |
| Knowledge Management, Vocabularies & Semantic Recall | Operational glossaries, lens taxonomies, composable libraries, docman CAS verification, and on-demand recall protocols. |
AI Agents, Architects, SREs | zqk docman register, zqk docman verify, zqk object list glossary_term |
| Declarative Graph Queries (ZPARQL) & Atomic Mutations (ZQL) | Multi-hop graph traversals, Cypher-like pattern queries, and atomic multi-object ACID transactions. | AI Agents, Backend Devs | zqk query, zqk mutate, query_zparql, mutate_zql |
| Object Lifecycle, State Machines & CAS Storage | Schema contracts, Content-Addressed Storage (CAS) membrane, two-phase draft/authoritative isolation, and DoD criteria binding. | All Engineers & Agents | zqk object create, zqk object inspect, zqk object promote |
| Objects & Specs Subsystem Operational & Architectural Guide | Ontological schema contracts, spec roots, meta-schema compilation, trait normalization, and shockwave propagation. | Kernel Architects & Agents | pkg/objects |
| Spec Origination, Pipeline Triggers & Validation Subsystem Operational Architecture Guide | Subsystem architecture, spec origination pipeline stages, idempotent trigger coordination, config membrane synchronization, validation scoping, and >=85.0% statement coverage invariant. | Kernel Architects, Ontologists & AI Agents | pkg/specorigination |
| Data Cell Registry & Read Model Cache Operational Architecture Guide | Subsystem architecture, spec-to-runtime decoupling bridge, CellKindDescriptor lifecycle, in-memory read model memoization, cache revision tracking, and 98.5% statement coverage invariant. | Kernel Architects, Storage Engineers & Autonomous AI Agents | pkg/datacellregistry |
| System Ontology & Object Classification Subsystem Operational & Architectural Guide | Semantic schema projection, 14 planning kinds, typed edge directional occupancy, thread-safe manager, data plane contextualizer, and >=85.0% coverage invariant. | Kernel Architects & AI Agents | pkg/ontology |
| Semantic Graph, AST Parsing & Inference Engine Subsystem Operational Architecture Guide | Subsystem architecture, ontological translation, semantic maturity assessment (Levels 0-4), dynamic rule inference, drift reconciliation, and >=85.0% statement coverage invariant. | Kernel Architects, AI Agents & Ontologists | pkg/semantic |
| Schema Translation, Multi-Format Serialization & Cross-Model Converter Subsystem Operational Architecture Guide | Subsystem architecture, TranslatorRegistry, multi-format deserialization and AST mapping (RDF/OWL, Turtle, RDF/XML, JSON-LD, Cypher, JSON Schema, OpenAPI), domain registry and object spec synthesis, thread-safe registry, and 98.9% statement coverage. | Kernel Architects, Ontologists & Autonomous AI Agents | pkg/translation |
| CLI Object Subsystem Operational Guide | Subsystem command taxonomy, CAS storage membrane, two-phase draft plane isolation, and relational query pipelines. | All Engineers & Agents | zqk object create, zqk object get, zqk object list, zqk object update, zqk object delete, zqk object promote, zqk object demote, zqk object ref |
| CLI Command Taxonomy & Internal Operations Guide | Subsystem architecture, internal command taxonomy, administrative role gates, bulk mutation engine, write-behind durability flushes, query-time grouping, and batch reference pipelines. | All Engineers & Autonomous AI Agents | zqk internal, pkg/zqkcli |
| Storage Subsystem Operational & Architectural Guide | Foundational persistence engine, Content Addressable Storage (CAS), write-behind audit event buffering, transaction safety, and TSDB engine. | Storage Engineers & Agents | pkg/storage |
| Real-Time State Accumulator Subsystem Architectural Guide | Subsystem architecture, Zero Hot-Path Scan Invariant (<5ms reads), dual-format deserialization, quiescent WAL detection, and asynchronous non-blocking recovery with >=85.0% statement coverage. | All Engineers & Autonomous AI Agents | pkg/accumulator |
| Write-Ahead Log Utilities Subsystem Architectural & Operational Guide | Subsystem architecture, append-only line-delimited JSON log streams, dual-coordinate ReplayCursor checkpoints, hot-path sequence skipping, corrupted tail quarantine, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/walutil |
| High-Performance Buffer Pool Subsystem Operational & Architectural Guide | Subsystem architecture, sync.Pool byte buffer recycling, 1MB retention ceiling, zero-allocation serialization, 64KB chunked streaming readers, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/bufferpool |
| Lifecycle Subsystem Operational & Architectural Guide | Subsystem architecture, state machine transitions, event WAL persistence, reactive listener rules, waker registry, updater synchronization, shockwave dependency cascades, remaining open counting, and >=85.0% coverage invariant. | Kernel Architects & Agents | pkg/lifecycle |
| Lifecycle Rollback, Transaction Boundaries & Snapshot Management Subsystem Architectural & Operational Guide | Subsystem architecture, transactional snapshot capture, WAL-backed rollback points, quick vs reconstruct restore pathways, multi-entity graph state reversion, lock operation boundaries, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/rollback |
| Contract Change, Outbox Dispatch & Mutation Lifecycle Subsystem Operational Architecture Guide | Subsystem architecture, SPEC_ORIGIN to kernel shockwave outbox, stay-in-status invariant verification, lifecycle demotions, replay safety, corrupted record recovery, and 98.2% statement coverage. | Kernel Architects, Distributed Systems Engineers & Autonomous AI Agents | pkg/contractchange |
| Migration Subsystem & Schema Evolution Operational Architecture Guide | Subsystem architecture, declarative migration specifications, composable step engine, snapshot-backed rollback points, lifecycle and UUID transformations, and >=85.0% statement coverage invariant. | Kernel Architects, Storage Engineers & Autonomous AI Agents | pkg/migration, pkg/migration/detector |
| Release Pack Composition, Object Kind Bindings & Spec Mapping Subsystem Architectural & Operational Guide | Subsystem architecture, release pack composition root integration, object kind bindings, instance and lifecycle builder registrations, spec and lifecycle path mapping, and 100.0% statement coverage invariant. | Kernel Architects, Release Engineers & Autonomous AI Agents | pkg/releasepack |
| Decision Ontology Pack & Impact Analysis Subsystem Architectural & Operational Guide | Subsystem architecture, decision pack composition root integration, owned kinds (decision, impact_analysis, question), spec and lifecycle state machines, blast-radius graph evaluation, and 100.0% statement coverage invariant. | Kernel Architects, Governance Stewards & Autonomous AI Agents | pkg/decisionpack |
| Vocabulary Pack, Ontology Dictionary & Domain Terminology Subsystem Architectural & Operational Guide | Subsystem architecture, domain terminology, ontology dictionary schema, glossary terms, relations, vocabulary schemes, import tracking, pack composition root integration, and 100.0% statement coverage invariant. | Kernel Architects, Ontologists & Autonomous AI Agents | pkg/vocabularypack |
| Workflow Pack & Process Composition Subsystem Architectural & Operational Guide | Subsystem architecture, workflow orchestration taxonomy, schema definitions, stages, role and account scoping, MCP tool configuration, pack composition root integration, and 100.0% statement coverage invariant. | Kernel Architects, Process Engineers & Autonomous AI Agents | pkg/workflowpack |
| Workpack Composition, Redundancy Analysis & Verification Engine Subsystem Operational Architecture Guide | Subsystem architecture, 22 planning and verification kinds, workpack composition root integration, fail-closed spec and lifecycle verification, schema normalization, redundancy analysis algorithms, and 99.3% statement coverage. | Kernel Architects, Quality Engineers & Autonomous AI Agents | pkg/workpack |
| Metric Pack Subsystem & Telemetry Pipeline Operational Architecture Guide | Subsystem architecture, metric pack composition root integration, 12 registered metric entity kinds, telemetry collection lifecycle, aggregation windows, ring buffers, memory limits, exporters (Prometheus/OpenTelemetry/stdout), backpressure handling, and 100.0% statement coverage invariant. | Kernel Architects, SREs & Autonomous AI Agents | pkg/metricpack, pkg/telemetry, pkg/metrics |
| Metrics Subsystem & Telemetry Pipeline Operational Architecture Guide | Subsystem architecture, component taxonomy (counters, gauges, histograms, samplers, registry), thread-safe atomic update invariants, timeseries chunk storage, telemetry export pipeline integration, failure mode mitigation, and >=85.0% statement coverage invariant. | Kernel Architects, SREs & Autonomous AI Agents | pkg/metrics, pkg/telemetry, pkg/metricpack |
| Event Streaming & Action Router Subsystem Guide | Subsystem architecture, bitmask event routing, localized policy inspectors, cascading overlay propagation, non-blocking delivery channels, and >=85.0% coverage invariant. | All Engineers & Autonomous AI Agents | pkg/events |
| Pipeline Subsystem Operational & Architectural Guide | Composable execution stages, DAG executor, monotonic process mutation pipeline, multi-agent orchestrator state machine, git worktree isolation, TPM rate limiting, and >=85.0% coverage invariant. | Kernel Architects & Agents | pkg/pipeline |
| Shockwave Propagation, Event Accumulation & Pipeline Dispatch Subsystem Guide | Subsystem architecture, shockwave ripples, decoupled pub/sub event pipeline, dynamic batch accumulation, gateway dispatching with reduce strategies, bounded worker neurons, and >=85.0% statement coverage invariant. | Kernel Architects, Distributed Systems Engineers & Autonomous AI Agents | pkg/shockwave |
| CLI Organizational Subsystem Architectural Guide | Subsystem command taxonomy, domain modeling, impact analysis cascade, propagation lifecycle, and declarative structure sync. | All Engineers & Agents | zqk organizational record-change, zqk organizational analyze-impact, zqk organizational propagate, zqk organizational sync |
| CLI Application Subsystem Architectural & Operational Guide | Root application bootstrap, command tree composition, execution context propagation, runtime diagnostics, and authentication middleware. | All Engineers & Agents | zqk, cmd/zqk/app |
| CLI Code Search Subsystem Operational & Architectural Guide | Subsystem command taxonomy, pure-Go in-process search, trigram indexing, Go AST structural queries, and token-budgeted AI agent output. | All Engineers & Agents | zqk grep, zgrep |
| CLI Documentation Management Subsystem Operational & Architectural Guide | Subsystem taxonomy, markdown metadata extraction, doc_entry registration pipeline, cryptographic drift verification, and auto-sealing. | All Engineers & Agents | zqk docman register, zqk docman verify |
| Docman Documentation Registry & Cryptographic Verifier Architecture Guide | Subsystem architecture, document discovery hierarchy, Markdown AST parser integration, frontmatter extraction, doc_entry graph registry, read model caching, cryptographic drift verification, and auto-sealing. | Kernel Architects, Documentation Engineers & Autonomous AI Agents | pkg/docman, zqk docman |
| Paths & Directory Topology Subsystem Operational & Architectural Guide | Subsystem filesystem topology, 4-tier project root discovery, runtime layout (.zqk/), ephemeral worktree isolation, trunk lock eviction, path resolver, and >=85.0% coverage invariant. | Kernel Architects, SREs & Agents | pkg/paths |
| CLI Query Subsystem Architectural & Operational Guide | Subsystem command taxonomy, declarative ZPARQL pattern queries, interactive REPL console, graph edge path visualization, and >=85.0% coverage invariant. | All Engineers & Agents | zqk query, zqk query -i, zqk query --visualize |
| Knowledge Graph Traversal & Query Execution Subsystem Guide | Subsystem architecture, ZPARQL pattern grammar, AST compilation, cost-based physical planner, cycle-safe DFS traversal, bounded streaming joins, and >=85.0% statement coverage invariant. | Graph Engineers & AI Agents | pkg/traversal, zqk query |
| Graph Mutation, Preflight Validation & Transaction Engine Subsystem Guide | Subsystem architecture, ZQL grammar compilation, Draft 2020-12 AST, preflight invariant validation, atomic ACID transactions, multi-engine write isolation, rollback unwinding, and >=85.0% statement coverage invariant. | Kernel Architects, Database Engineers & AI Agents | pkg/mutation, zqk mutate |
| Expression Filtering & Time Parser Subsystem Architectural & Operational Guide | Subsystem architecture, lexical filter parsing, comparison operators, pipe-separated sets, schema validation with fuzzy Levenshtein suggestions, relative time token resolution, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/filter |
| Time Standardization & Deterministic Simulation Subsystem Guide | Subsystem architecture, UTC timestamp invariants, RFC3339/RFC3339Nano formatting, deterministic simulation and WAL replay, nil pointer safety, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/zqktime |
| Acronym Vocabulary & Progressive Disclosure Subsystem Guide | Subsystem architecture, canonical acronym registry, VOC-KERNEL-ACRONYMS vocabulary scheme, live storage projection, approximate search, progressive disclosure, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/acronyms, zqk explain |
| Canonical Kind Synonyms & CLI Workflow Aliases Subsystem Operational Architecture Guide | Subsystem architecture, canonical kind lookup, synonym dictionary mapping, plural normalization, whitespace and case-folding, concurrency-safe registry, and 100.0% statement coverage. | All Engineers & Autonomous AI Agents | pkg/kindsynonyms |
| Library Pack Composition, Object Kind Bindings & Spec Mapping Operational Architecture Guide | Subsystem architecture, library pack composition root, spec and lifecycle directory bindings, kind registrations, omission build tags, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/librarypack |
| Display Pack and UI Specification Registry Operational Architecture Guide | Subsystem architecture, display pack composition root, spec and lifecycle directory bindings, UI component/display kind registrations, omission build tags, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/displaypack |
| Evolution Pack and Migration Management Operational Architecture Guide | Subsystem architecture, evolution pack composition root, spec and lifecycle directory bindings, evolution management kind registrations, omission build tags, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/evolutionpack |
| Interface Pack and API Command Contract Operational Architecture Guide | Subsystem architecture, interface pack composition root, spec and lifecycle directory bindings, API and CLI command spec kind registrations, omission build tags, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/interfacepack |
| Organization Pack and Team Topology Registry Operational Architecture Guide | Subsystem architecture, organization pack composition root, spec and lifecycle directory bindings, enterprise structure and team topology kind registrations, omission build tags, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/orgpack |
| Pipeline Pack and Stage Execution Engine Operational Architecture Guide | Subsystem architecture, pipeline pack composition root, spec and lifecycle directory bindings, pipeline definition and stage kind registrations, omission build tags, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/pipelinepack |
| QA Pack and Quality Assurance Rules Operational Architecture Guide | Subsystem architecture, QA pack composition root, spec and lifecycle directory bindings, quality metrics and validation rule kind registrations, omission build tags, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/qapack |
| Batch AF (Aggregation & Orphaned Processing) Subsystem Architectural & Operational Guide | Subsystem architecture, dual-trigger batch aggregation, bounded worker pool execution, exponential backoff retries, orphaned batch reclamation, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/batchaf |
| Stamp Memoization & Generation Tracking Subsystem Guide | Subsystem architecture, stamp-invalidated memoization, generation tracking, zero-copy view projections, non-blocking peek, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/stampmemo |
| Metric Rollup, State Convergence & Hierarchical Aggregation Subsystem Operational Architecture Guide | Subsystem architecture, hierarchical progress aggregation, effort statistics distributions, multi-tier parent-child resolution, cycle-safe graph traversal, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/rollup |
| Convergence Rollup, BFS Tree Traversal & Reference Cycle Detection Subsystem Operational Architecture Guide | Subsystem architecture, BFS tree traversal, cycle detection gates, parent-child nesting hierarchies, status aggregation invariants, and 98.8% statement coverage. | Kernel Architects, Swarm Engineers & Autonomous AI Agents | pkg/convergerollup, zqk scheduler convergence measure |
| Object Steward Base, Ingestion Enqueuer & Work Delivery Subsystem Architectural & Operational Guide | Subsystem architecture, decoupled maintenance enqueuing, storage profile validation, bounded detail truncation, atomic JSONL queue persistence, structured logging, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/stewardbase |
| Storage Testing, Isolation Contracts & Decoupling Seams Architectural & Operational Guide | Subsystem architecture, storage test isolation contracts, decoupling seams, test harness factory hooks, thread-safe mock isolation factory, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/storagetesting |
| Network Transport, Multiplexing & Connection Lifecycle Subsystem Operational Architecture Guide | Subsystem architecture, transport protocol handlers, FTP/RPC transport wrappers, protocol multiplexing, connection lifecycle management, telemetry integration, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/transport |
| Developer Tooling, Spec Code Generation & Engineering Pipelines Subsystem Operational Architecture Guide | Subsystem architecture, code generation pipelines (builders, field keys, spec index, lifecycle IDs), trait synthesis, AST-driven generation, concurrent worker dispatch, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/zqkdev, zqk system generate-* |
| Environment Variables, Secret Masking & Agent Execution Guards Subsystem Operational Architecture Guide | Subsystem architecture, strongly-typed EnvVar descriptors, dynamic brand key resolution, cryptographic secret masking, agent execution guards (agentguard), subprocess isolation, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/zqkenv |
| Session Lifecycle, Worker Context & Identity Engine Subsystem Operational Architecture Guide | Subsystem architecture, CLI session state persistence and reuse, worker context propagation, file lock synchronization, idle timeout invalidation, identity prefix validation, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/zqksession |
| LLM Provider Adapters, Streaming Protocol & Multi-Engine Dispatch Subsystem Operational Architecture Guide | Subsystem architecture, vendor-neutral provider adapters (Antigravity, Gemini, OpenAI, Qwen, Ollama, Golang, MacOS, Sync), streaming delivery protocols, message normalization, execution gates, error recovery, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/adapters |
| LLM Client Abstraction & Provider Adapters Operational Architecture Guide | Subsystem architecture, unified Client contracts, OpenAI and Gemini adapters, ResilientClient failover, StaticMockClient offline fallback, ToolBudget message token governance, prompt injection sanitization, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/llm |
| LLM Client Abstraction & Structured Tool Budget Operational Architecture Guide | Subsystem architecture, unified Client contracts, structured tool calling, ToolBudget token estimation and message trimming, negative adversarial boundary resilience, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/llm |
| Agent Pack Architecture, Kind Registry & Lifecycle Schemas Operational Architecture Guide | Subsystem architecture, pack metadata schemas, bundle registration, validation boundaries, kind taxonomy integration, lifecycle hooks, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/agentpack |
| Ambient EventMesh, Anticipatory Evaluation & In-Memory Dispatch Subsystem Operational Architecture Guide | Subsystem architecture, in-memory event bus, async audit dispatch, subscription filters, anticipatory rule engine, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/ambience |
| Metrics Recording Policy, In-Memory Sampler & Sampling Invariants Operational Architecture Guide | Subsystem architecture, metric recording policies, in-memory ring buffers, sampling invariants, rate limit governance, telemetry integration, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/metricsrecording |
| Metrics Recording Subsystem & Recorder Pipeline Operational Architecture Guide | Subsystem architecture, recording policy gates, hot-path suppression circuit breaker, kind filtering, storage sink integration, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/metricsrecording |
| Kernel Bootstrap, Template Extraction & Greenfield Project Initialization Operational Architecture Guide | Subsystem architecture, dual-path archive extraction (embedded vs source fallback), prefix routing, path jail containment, decompression bomb mitigations, community denylist filtering, and >=85.0% statement coverage invariant. | Kernel Architects, Release Engineers & Autonomous AI Agents | pkg/bootstrap, zqk system init |
| Component Loader Pattern, Atomic State Transitions & Timeout Envelope Subsystem Guide | Subsystem architecture, Runner single-flight execution, atomic state transitions, multi-stage timeout envelopes (wait, publish, load), stamp memoized configuration, profile overrides, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/loader |
| Git Plumbing & VCS Snapshot Engine Operational Architecture Guide | Subsystem architecture, isolated Git plumbing refs (refs/zqk/*), tree creation, snapshot capture, tar archive restoration, directory escape mitigation, remote synchronization (push/fetch), and >=85.0% statement coverage invariant. | Kernel Architects, VCS Engineers & Autonomous AI Agents | pkg/gitplumbing |
2. Governance, Security & Policy DSL
| Guide | Focus Area | Target Audience | Primary CLI & MCP Commands |
|---|---|---|---|
| Validation Subsystem Architectural & Operational Guide | Multi-layer validation architecture (Layers 0–4), AST invariant checks, async priority queue execution, automated remediation engine, and >=85.0% statement coverage invariant. | All Engineers & Agents | pkg/validation, zqk system check, zqk object inspect |
| Static AST Linting, Code Vetting Engine & Policy Rule Suite Subsystem Operational Architecture Guide | Subsystem architecture, VetRunner orchestration, declarative GatesConfig, AST check suites (command specs, CLI builders, concurrency, duplication, paths/perms, tree police, payload guard), fail-fast thresholds, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/vet, zqk-vet |
| Architectural Drift Hotspots, AST Metric Barrel & Field Key Literal Fixer Subsystem Operational Architecture Guide | Subsystem architecture, AST interval inspection, constant barrels and data catalog boundaries, 13 drift hotspot categories, automated field key literal AST rewriter, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/drifthotspots |
| System Check, Validator Registration & Violation Resolution Subsystem Operational Architecture Guide | Subsystem architecture, ValidatorRegistry, bounded worker pool execution, spec-informed violation resolution, auto-remedy strategies, TPM feedback telemetry, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/systemcheck, zqk system check, zqk system telemetry |
| CLI Test Subsystem Architectural & Operational Guide | Subsystem command taxonomy, 3-Fold Proof verification, test execution pipeline, AST contamination detector, parallel test runner, WAL event streaming, TUI test dashboard, and >=85.0% coverage invariant. | All Engineers & Agents | zqk test run, zqk test discover, zqk test dashboard, zqk test bind, zqk test check-contamination, zqk test identify-parallel, zqk test stream |
| Test Runner Execution, Parallel Safety, Race Gate & Event Streaming Subsystem Operational Architecture Guide | Subsystem architecture, TestRunnerEngine, ParallelSafetyGovernor, RaceConditionGate, ContaminationSentinel, EventStreamMultiplexer, process group sandboxing, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/testrunner, zqk test run, zqk test stream |
| Polyglot Test Discovery, Engine Registry & Cache Subsystem Operational Architecture Guide | Subsystem architecture, static AST/source parsing across Go, Python, TypeScript, and Rust, DiscoveryEngine, EngineRegistry, SHA-256 mtime incremental cache, zero-execution security boundaries, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/testdiscovery, zqk test discover |
| Hermetic Test Environment & Repo Mutation Guard Subsystem Operational Architecture Guide | Subsystem architecture, isolated test root materialization, repo write protection, state modtime snapshotting, asset replication without repository contamination, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/testenvroot |
| Test-Requirements Verification Harness & Predicate Evidence Engine Operational Architecture Guide | Subsystem architecture, POL-WORKFLOW-VDS evidence engine, scope:Name predicate grammar, verification lifecycle, prescriptive next actions remediation, sync.RWMutex registry, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/reqharness |
| Verifiable Delivery Standard (VDS), Chunk Evaluation & Predicate Evidence Engine Subsystem Operational Architecture Guide | Subsystem architecture, Verifiable Decomposition Spine (POL-WORKFLOW-VDS), five rigid delivery stages, chunk evaluation engine, predicate DSL assertion matrix, vendor instruction projections, and >=85.0% statement coverage invariant. | Kernel Architects, Quality Engineers & Autonomous AI Agents | pkg/vds, zqk workflow vds |
| Continuous Verification Engine, Matrix Scorecard & Evidence Classification Subsystem Operational Architecture Guide | Subsystem architecture, Universal Verification DSL strategies, content-addressed verification matrix, evidence classification, multi-language file profiling, diamond quality scoring, and >=85.0% statement coverage invariant. | Kernel Architects, Quality Engineers & Autonomous AI Agents | pkg/verification, pkg/verification/matrix |
| Object Closure Gate, Machine-Checkable Evidence Validation & Scheduler Health Fingerprinting Subsystem Operational Architecture Guide | Subsystem architecture, fail-closed closure gate (machine_checkable_closure_evidence), bundle log disk verification, scheduler health.jsonl fingerprint matching, grandfathering transitions, and 100.0% statement coverage invariant. |
Kernel Architects, Quality Engineers & Autonomous AI Agents | pkg/closureevidence |
| Scenario Testing, Behavioral Simulation & Convergence Playback Subsystem Operational Architecture Guide | Subsystem architecture, scenario bundle application, doc convergence, traceability matrix resolution, creation order topological sorting, draft bundle authoring, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/scenario |
| Kernel Test Scaffolding, Deterministic Waiting & Scenario Test Harness Subsystem Operational Architecture Guide | Subsystem architecture, TestEnvironment setup, deterministic condition waiting, scenario environment sandboxing, callback synchronization, snapshot verification, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/testing |
| Universal Testkit, Leak Detection & Hermetic Project Isolation Subsystem Operational Architecture Guide | Subsystem architecture, hermetic project isolation, goroutine and subprocess leak profiling, managed subprocess groups, LIFO teardown pipelines, condition polling, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/testkit |
| Test Services Lifecycle, Fixture Management & Ephemeral Environment Subsystem Operational Architecture Guide | Subsystem architecture, ServiceManager, ServiceConfig, HealthCheckEngine, PortPublisherSentinel, ContainerLifecycleGovernor, shared listener reuse, Docker orchestration, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/testservices |
| Custom Validation Policy Creation & Rule DSL | Composing declarative Validation Rule DSL expressions, live population dry-run audits, grandfathering, and check-valve registration. | Tech Leads, Governance Stewards | zqk object inspect --policy-studio, zqk system check-policy |
| Agent Execution Rules & Manifest Governance Subsystem Guide | Subsystem architecture, rule definition (*.mdc), manifest registry, candidate directory resolution hierarchy, diff engine, pre-commit enforcement, auto-healing, and >=85.0% coverage invariant. | All Engineers & Autonomous AI Agents | pkg/agentrules, zqk system validate-agent-rules |
| Predicate DSL & AST Evaluation Engine Subsystem Architectural & Operational Guide | Subsystem architecture, formal EBNF grammar, tokenization, AST parser construction, truth table evaluation, built-in predicates, legacy prose overlay compilation, keyword salience engine, goroutinelabels concurrency, and >=85.0% statement coverage invariant. | Kernel Architects, Governance Stewards & AI Agents | pkg/predicate |
| Conditional Evaluation & Fluent Predicate Chains Subsystem Architectural & Operational Guide | Subsystem architecture, fluent conditional chains, short-circuit evaluation, Try/Catch monadic containers, error preservation, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/when |
| Functional Programming Primitives & Result Monad Subsystem Architectural & Operational Guide | Subsystem architecture, Result[T] monadic container, fluent combinators, collection transformations, telemetry-integrated execution, pure functions, immutability guarantees, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/functional |
| Generic Payload Decoding, Type Assertion & Nil-Safety Subsystem Operational Architecture Guide | Subsystem architecture, generic type assertions, zero-value guards, Go typed-nil interface trap elimination, collection decoding, pure function concurrency invariants, and >=85.0% statement coverage. | All Engineers & Autonomous AI Agents | pkg/nildecode |
| Domain-Specific String Aliases & Canonical Normalization Subsystem Guide | Subsystem architecture, domain-isolated static alias resolution, case-folding, whitespace normalization, cross-domain collision prevention, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/aliases |
| String Utilities & Distance Metrics Subsystem Architectural & Operational Guide | Subsystem architecture, Levenshtein distance metrics, default fallback resolution, escape rune decoding, line-delimited token extraction, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/strutil |
| Safe Path Manipulation & Traversal Protection Subsystem Operational & Architectural Guide | Subsystem architecture, JoinUnderRoot containment validator, lexical cleaner, relative resolver, symlink evaluation gate (F-SEC-006), Gosec G703 mitigation, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/safepath |
| Security Primitives, Path Traversal Defense & Release Security Subsystem Architectural & Operational Guide | Subsystem architecture, path sanitization, root jail containment, release security verification, tool name validation, error taxonomy, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/security |
| AppleDouble Resource-Fork Sidecar & Filesystem Hygiene Subsystem Architectural & Operational Guide | Subsystem architecture, macOS Finder/SMB resource fork sidecar detection, segment-aware path filtering, tree walk pruning, cross-platform path normalization, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/appledouble |
| Error Formatting, Actionable Diagnostics & Poison Pill Protection Subsystem Guide | Subsystem architecture, Errorf wrapper, ErrorStringBuilder, poison pill electrocution defense, actionable diagnostics engine, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/errfmt |
| HandSlapper Drift Interceptor Subsystem Architectural & Operational Guide | Subsystem architecture, pre-OS command inspection, tokenization, forbidden tool bypass detection, namespace containment (.zqk), strict electrocution sentinel, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/handslapper |
| Cryptographic Primitives & Key Management Subsystem Operational & Architectural Guide | Subsystem architecture, Ed25519 digital signatures, JWT cryptographic stamps, public/private key management, tamper and replay defense, algorithm confusion mitigations, and >=85.0% statement coverage invariant. | Kernel Architects, Security Engineers & Autonomous AI Agents | pkg/crypto |
| Authentication Credential, RBAC Account Resolution & Seat Security Subsystem Operational Architecture Guide | Subsystem architecture, credentials resolution, keystore caching, CAS listing index memoization, Account RBAC binding, Persona vocabulary schema, Discovery Membrane lane filtering, Prototype Rejection invariant, Seating directory isolation, and >=85.0% statement coverage. | Kernel Architects, Security Engineers & Autonomous AI Agents | pkg/authcred, zqk agent seat-worker |
| Role Entitlements, Capability Matrix & Object Elevation Operational Architecture Guide | Subsystem architecture, dual-tier platform governance (Community vs Enterprise), offline Ed25519 cryptographic license verification, fail-closed fallback invariant, RBAC capability matrix, object elevation lifecycle, and 100.0% statement coverage. | Kernel Architects, Security Engineers & Autonomous AI Agents | pkg/entitlements, zqk object --internal |
| HTTP Headers Standardization & Canonicalization Subsystem Architectural & Operational Guide | Subsystem architecture, RFC 7230/9110 canonicalization, CRLF injection defense, W3C trace context propagation, robust auth parsers, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/httpheaders |
| Task Decision Envelope, Decision Log & WAL Subsystem Guide | Subsystem architecture, Time-Delayed Execution (TDE), cognitive governance, staging WAL, Crystalline Fortress hard-block, background commit daemon, and 100.0% statement coverage invariant. | Kernel Architects, Security Stewards & AI Agents | pkg/tde |
| Traceable Data Envelope Validator, Schema Integrity & Skill Seal Subsystem Guide | Subsystem architecture, Traceable Data Envelope (TDE) validation, schema integrity checking, Skill Seal cryptographic verification, tamper detection, error taxonomy, and >=85.0% statement coverage invariant. | Kernel Architects, Security Stewards & AI Agents | pkg/tdval |
| Audit Policy Engine, Stream Multiplexing & Subscription Lifecycle Subsystem Operational Architecture Guide | Subsystem architecture, PolicyEngine parallel evaluation, PolicyViolationError taxonomy, AuditStream multiplexing, slow subscriber backpressure drops, disk-backed JSONL WAL, and >=85.0% statement coverage invariant. | Kernel Architects, Security Stewards & Autonomous AI Agents | pkg/audit |
| Offline Cryptographic License Verification, Ed25519 Signatures & Feature Entitlements Architecture Guide | Subsystem architecture, offline Ed25519 JWT verification, algorithm downgrade defense (strict EdDSA), fail-closed entitlement checks, and >=85.0% statement coverage invariant. | Kernel Architects, Security Stewards & Autonomous AI Agents | pkg/license |
3. Autonomous Execution & Continuous Loops
| Guide | Focus Area | Target Audience | Primary CLI & MCP Commands |
|---|---|---|---|
Single-Command Execution Loop (zqk do) |
5-phase execution engine (Intent ➔ Preflight ➔ Locks ➔ Dispatch ➔ Verification), fail-closed invariant guards, and anti-thrashing discipline. | Autonomous AI Agents | zqk do <intent>, zqk workflow whats-next |
| CLI Do Subsystem Architectural & Operational Guide | Subsystem command taxonomy, single-command autonomous execution loop, five-stage cycle (discover, claim, context-prepare, verify, latch), token conservation, and >=85.0% coverage invariant. | All Engineers & Autonomous AI Agents | zqk do, zqk auto-exec, zqk auto-do |
| CLI Application Subsystem Architectural & Operational Guide | Subsystem lifecycle, execution topology, session persistence, runtime diagnostics, profiling, shell completions, and failure isolation. | All Engineers & Agents | zqk, cmd/zqk/app, zqk completion |
| CLI Workflow Subsystem Architectural & Operational Guide | Subsystem command taxonomy, composite ambient routing, deterministic next-action resolution, gate preconditions, and VDS verification. | All Engineers & Agents | zqk workflow whats-next, zqk workflow next, zqk workflow check, zqk workflow add |
| Workflow Engine & Continuous Autonomy Subsystem Guide | Ontological anti-superficiality linter, Three-Fold Proof validation, Whats-Next decision engine, CAP flywheel state machine, and >=85.0% coverage invariant. | All Engineers & Autonomous AI Agents | pkg/workflow, zqk workflow whats-next, zqk workflow lint |
| TPM Strategic Readiness, Three-Fold Phi Metrics & Gantt Matrix View Subsystem Operational Architecture Guide | Subsystem architecture, Three-Fold Phi metrics (specification, traceability, execution fuel), domain clustering, runway depth evaluation, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/tpm |
| Shovel-Ready Backlog Evaluation, Dependency Topology & Batching Subsystem Guide | Subsystem architecture, Definition of Ready (DoR) gates, CRI-SHOVEL-READY criteria, acyclic dependency topology validation, blocked ancestor resolution, readiness scoring, batch allocation, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/shovelready, zqk workflow whats-next, zqk do |
| CLI Ambient Compute Subsystem Architectural & Operational Guide | Subsystem command taxonomy, singleton daemon supervision, background wave scheduling, automerge synchronization, and HTTP event ingestion. | All Engineers & Agents | zqk ambient, zqk ambient status, zqk ambient wave, zqk ambient automerge, zqk ambient ingest |
| Ambient Compute, EventMesh & Anticipatory Intent Subsystem Operational Architecture Guide | Subsystem architecture, InMemoryEventMesh router, sliding-window and count-bounded SignalAggregator, FSEventsEngine anticipatory intent heuristics, audit event sourcing, deterministic teardown synchronization, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/ambience |
| CLI Scheduler Subsystem Architectural & Operational Guide | Subsystem command taxonomy, singleton daemon supervision, keep-alive heartbeat, WAL event streaming, dead-letter escalation, maintenance skip windows, and >=85.0% coverage invariant. | All Engineers & Agents | zqk scheduler start, zqk scheduler stop, zqk scheduler status, zqk scheduler health-check, zqk scheduler submit, zqk scheduler dump, zqk scheduler escalate, zqk scheduler test-failures |
| Scheduler Subsystem Operational & Architectural Guide | Embedded job queue, CAP loop orchestrator, transient retry membranes, atomic job state registry, retention cleanup, and watchdog monitoring. | Kernel Engineers & Agents | pkg/scheduler, zqk scheduler |
| Shell Command Parsing, Metacharacter Inspection & Cross-Platform Execution Subsystem Architectural & Operational Guide | Subsystem architecture, command tokenization, metacharacter inspection, cross-platform POSIX/Windows shell delegation, fail-closed empty argv handling, concurrency guarantees, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/shellcmd |
| Process Execution, Group Isolation & Subprocess Management Subsystem Architectural & Operational Guide | Subsystem architecture, hardened process lifecycle management, process group isolation, timeout enforcement, stream buffering, transient ETXTBSY exponential backoff retry, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/execwrap |
| OS Service Management & Adapter Subsystem Architectural & Operational Guide | Subsystem architecture, cross-platform service supervision, launchd/systemd adapters, process lifecycle state machines, dual-path fallbacks, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/service |
| Circuit Breaker & Concurrency Throttling Subsystem Architectural Guide | Three-state circuit breaker automaton, sliding-window failure decay, per-package semaphore concurrency limits, and token-bucket TPM rate limiting. | All Engineers & Autonomous AI Agents | pkg/circuitbreaker |
| Host Load Sampling & Adaptive Concurrency Subsystem Architectural Guide | Subsystem architecture, dynamic CPU saturation telemetry, EMA low-pass filtering, three-tier pressure classification, self-heat compensation, fail-open guarantees, cross-platform sensors, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/hostload |
| Concurrency Primitives Subsystem Architectural & Operational Guide | Synchronization primitives, deadlock prevention, TimeoutMutex invariants, adaptive GoroutineCeiling token pools, context-aware waits, named WaitGroupManager, and >=85.0% coverage invariant. | All Engineers & Agents | pkg/concurrency |
| Goroutine Identity & Concurrency Labels Subsystem Operational Architecture Guide | Subsystem architecture, named goroutines and runtime categorization, bounded worker pool lifecycle, CPU/concurrency budget tracking, panic recovery telemetry, test fixtures, and >=85.0% statement coverage invariant. | Kernel Architects, Concurrency Engineers & Agents | pkg/goroutinelabels |
| Test Package Concurrency Limits & Parallel Execution Throttling Subsystem Guide | Subsystem architecture, package path normalization, on-disk policy loading, conservative multi-source limit merging, parallel runner throttling, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/testpackageconcurrency |
| Runtime Subsystem Architectural & Operational Guide | Centralized supervision tree, goroutine lifecycle governance, leak detection heuristics, graceful drain coordination, and >=85.0% coverage invariant. | All Engineers & Agents | pkg/runtime |
| Branding & Identity Subsystem Architectural & Operational Guide | Subsystem architecture, dynamic brand discovery, channel suffix stripping, environment variable prefix resolution, role differentiators, multi-tenant isolation, and >=85.0% statement coverage invariant. | All Engineers & Agents | pkg/brand |
| Pipeline Execution Subsystem Operational & Architectural Guide | Multi-stage pipeline composition, DAG execution engine, pipeline router, context hydration, token budget enforcement, graph ownership, native swarm dispatchers, and >=85.0% coverage invariant. | All Engineers & Autonomous AI Agents | pkg/pipeline, zqk agent orchestrate, zqk do |
| Local CI Engine, Worktree Isolation & Git Fast-Forward Subsystem Operational Architecture Guide | Subsystem architecture, pure Go CI checkout, fail-closed dirty studio verification, detached worktree isolation, atomic symlink workdir swinging, cryptographic tarball archiving, and 98.3% statement coverage. | All Engineers & Autonomous AI Agents | pkg/localci, zqk local-ci |
| Event Coordination Subsystem Architectural & Operational Guide | Subsystem architecture, central event spinal cord, TRIGGER stage pipelines, multi-channel routing (logging, audit, metrics, operational), subscriber topologies, progress reporting, CLI notifier adapters, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/coordination |
| Feature Flags, Dynamic Toggles & Runtime Organism Subsystem Architectural & Operational Guide | Subsystem architecture, dynamic runtime feature toggles, progressive rollout switches, thread-safe synchronization, stamp memoization caching, defaults initialization, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/featureflags |
4. Multi-Agent Swarm Collaboration
| Guide | Focus Area | Target Audience | Primary CLI & MCP Commands |
|---|---|---|---|
| Atomic Work Claiming & Session Checkin Subsystem Guide | Subsystem architecture, CAS lock acquisition, heartbeat renewal, write lock gate evaluation, write queue serialization, provenance tracking, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/agentclaim, zqk agent claim, zqk agent release |
| Agent Feed & Peer Mesh Subsystem Architecture Guide | Core agent feed event ledger, peer seat liveness tracking, asynchronous await wakes, in-flight steering, deterministic COMMS-CHECK protocols, and >=85.0% coverage invariant. | All Engineers & Autonomous AI Agents | pkg/agentfeed, zqk feed, zqk agent seat-worker |
| Agent Idle Detection & Resource Conservation Subsystem Guide | Subsystem architecture, FileStore accumulator, StoreDocument schema (2.0.0), CVS snapshot telemetry, in-memory caching, atomic temp rename, and >=85.0% statement coverage invariant. | Swarm Engineers & Autonomous AI Agents | pkg/agentidle |
| Core Orchestration Subsystem Architectural & Operational Guide | Multi-agent convergence sessions, SubagentRunner with sentinel rollbacks, ephemeral worktree pool and sweeper, IdleWatchdog, PredictiveSpawner heuristics, PolicyNegotiator schema reconciliation, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/orchestration, zqk agent orchestrate, zqk do |
| CLI Agent Subsystem Architectural & Operational Guide | Subsystem command taxonomy, context-bound prompt generation, atomic work claim gates, AST verification, and multi-agent coordination mesh with >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | zqk agent orchestrate, zqk agent claim, zqk agent prepare-context, zqk agent deliver, zqk agent seat-worker, zqk agent recover, zqk agent status |
| Multi-Agent Swarm Orchestration & Mesh Collaboration | Agent seating, append-only agent feeds, conflict-free single-claimant work leases, and ambient signal interpretation rubrics. | Swarm Engineers, Multi-Agent Setups | zqk system agent-onboard, zqk agent feed, zqk agent claim-work |
| CLI Agent Feed Subsystem Architectural & Operational Guide | Subsystem command taxonomy, agent coordination mesh, heartbeat mechanisms, proof-of-life leases, interrupt handling, streaming JSON lines, and >=85.0% statement coverage invariant. | Swarm Engineers, Multi-Agent Setups | zqk feed ack, zqk feed steer, zqk feed emit-status, zqk feed watch, zqk feed wake, zqk feed serve, zqk feed pending, zqk feed proof-of-life, zqk feed doctor, zqk feed bridge-ingest |
| Multi-Transport Agent Delivery & Protocol Adapters Subsystem Guide | Subsystem architecture, DeliveryRouter, HTTP/MCP transports, in-process subagent invocation, trust-domain envelope enforcement, delivery audit logging, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/agentdelivery, zqk agent deliver |
| Task Decision Envelope & Ingestion Subsystem Operational Architecture Guide | Subsystem architecture, Task Decision Envelope (TDE) schema contracts, robust ingestion parsing, status state machine, zero shared-memory mutation invariants, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/envelope |
| Agent Onboarding & Environment Seeding Subsystem Guide | Subsystem architecture, first contact detection, universal AGENTS.md directives, vendor rule projection, skill hydration, headless execution vector B, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/agentonboard, zqk system agent-onboard |
| Agent Prompt Engineering & Dynamic Context Assembly Subsystem Guide | Subsystem architecture, dynamic prompt builder pipeline, envelope hydration, policy and skill injection, token budget compaction, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/agentprompt, zqk agent prepare-context, zqk do |
| Skill Drift Audit, Integrity Sealing & Evolution Tracking Subsystem Guide | Subsystem architecture, dual-directory drift detection, SHA-256 cryptographic sealing, frontmatter tamper detection, evolutionary lineage tracking, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/skill |
| CLI MCP-Simple Subsystem Architectural Guide | Minimal footprint Model Context Protocol (MCP) server, stdio & mTLS transports, diagnostic tools, and isolated client execution. | AI Agents, Swarm Integrators | zqk mcp-simple, zqk mcp-simple -mtls-addr |
| Model Context Protocol (MCP) Subsystem & Tool Execution Architecture Guide | Subsystem architecture, JSON-RPC 2.0 protocol lifecycle, in-process CLI bridge, role-based tool catalog, path traversal guards, session leases, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/mcp, zqk mcp |
| MCP Auto-Configuration & Host Integration Guide | Single-command auto-configuration (zqk mcp install, zqk mcp ensure), multi-host IDE discovery (Cursor, Claude Code, Cline, Windsurf), stdio and TCP proxy architectures, and manual configuration recipes. |
All Engineers & Autonomous AI Agents | zqk mcp install, zqk mcp ensure, zqk mcp proxy |
| Cellular Specialization & Organism Roles Subsystem Architectural & Operational Guide | Subsystem architecture, biological organ tiers (Neuron, Muscle, Heart, Lung, All), normal vs shielded (Rubber Room) modes, PCS vitality telemetry, and >=85.0% statement coverage invariant. | Kernel Architects, Swarm Engineers & Autonomous AI Agents | pkg/specialization, zqk scheduler daemon, zqk system status |
| Semantic Model, Tool & Gradient Routing Subsystem Operational Architecture Guide | Subsystem architecture, model gradient dispatch, tool scope isolation, adaptive timeout envelopes, model tier classification, telemetry counters, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/router |
| Swarm Initialization & Mesh Recipe Pipeline Runner Subsystem Operational Architecture Guide | Subsystem architecture, mesh recipe parsing, step executors, runner orchestration, registry lookup, recipe failure modes, conversation wiring errors, timeout handling, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/swarminit, zqk swarminit run |
| Swarm Execution Engine & Multi-Agent Orchestration Subsystem Operational Architecture Guide | Subsystem architecture, deterministic cognitive loop lifecycle, task scheduling, tool guarding, MCP client integration, token tracking, prompt synthesis, error recovery, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/swarm, zqk do, zqk agent orchestrate |
| Mesh Networking, State Sync & ToolPod Subsystem Operational Architecture Guide | Subsystem architecture, UDP gossip protocol, cryptographic trust verification, dynamic ToolPod coordination, async priority queue dispatch, backpressure flow control, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/mesh |
| Token Broker, Agent Resource Marketplace & Economic Exchange Subsystem Guide | Subsystem architecture, EconomicBroker credit enforcement, AgentMarketplace skill broadcasting and leasing, quota rate limits, balance updates, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/economy |
5. Diagnostics, Self-Healing & Telemetry
| Guide | Focus Area | Target Audience | Primary CLI & MCP Commands |
|---|---|---|---|
| Diagnostics, Auto-Remedies & Self-Healing | 4-layer health checks, automated resolution of stale locks and orphaned temp buffers, and CAS quarantine recovery. | SREs, Operators, CI/CD | zqk system check --auto-remedy, zqk system doctor |
| CLI System Subsystem & Health Operations Guide | Multi-layer validation, automated remediation engine, strategic alignment scoring, and service lifecycle management. | SREs, Operators, Swarm Engineers | zqk system check, zqk system align, zqk system status |
| CLI Visual Studio & Interactive TUI Subsystem Operational Architecture Guide | Interactive full-screen terminal mission control, headless model projection, embedded Web Visual Studio, port auto-scanning, and >=85.0% coverage invariant. | All Engineers & Agents | zqk ui, zqk dashboard, zqk console |
| Web Studio & Visual Graph Explorer Operational Architecture Guide | Embedded local web server (zqk ui -w), HTTP/WebSocket endpoints, real-time DAG streaming, Gantt matrix visualization, and headless CI export. |
All Engineers & Autonomous AI Agents | zqk ui -w, zqk ui --web, pkg/studio |
| TUI Engine & Terminal Interface Subsystem Architectural & Operational Guide | High-performance terminal UI engine, Elm architecture in Go (Model-Update-View), TDS styling invariants, headless fallback, and >=85.0% coverage invariant. | All Engineers & Agents | pkg/tui, zqk ui |
| Screen Capture & Window Automation Subsystem Architectural & Operational Guide | Subsystem architecture, TerminalAutomator session orchestration, native window & region capture, cross-platform adapters, timeline tracing, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/screencap |
| Desktop System Tray, Menu Schema Validation & Action Security Subsystem Guide | Subsystem architecture, native desktop tray integration, menu schema validation, cryptographic action security membrane, stamp memoization, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/tray, zqk tray |
| CLI Utility Subsystem Architectural Guide | Subsystem command taxonomy, scenario synthesis, hash fix, registration repair, YAML validation, migration engine, config file watcher, and >=85.0% coverage invariant. | All Engineers & Agents | zqk utility, zqk utility fix-hashes, zqk utility fix-registration, zqk utility validate-yaml, zqk utility scenario-builder, zqk utility migrate |
| Stale Lock Health & Cleanup Subsystem Architectural & Operational Guide | Subsystem architecture, fail-closed directory discovery, stale lock sweep heuristics, owner-verified removal, advisory flock probing, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/lockhealth |
| Disk Usage & Storage Capacity Telemetry Subsystem Architectural Guide | Subsystem architecture, pure-Go filesystem tree traversal, size rollups, binary byte formatting, capacity telemetry, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/diskusage, zqk system disk-usage |
| Config-Driven Cleanup & Maintenance Subsystem Architectural & Operational Guide | Subsystem architecture, single-track YAML cleanup configuration, polymorphic step unmarshaling, stamp memoization caching, scheduled task pruning, safe deletion safeguards, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/cleanup, zqk scheduler submit --job-type cleanup |
| I/O Resource Hygiene, File Descriptor Leak Detection & Storage Telemetry Subsystem Architectural & Operational Guide | Subsystem architecture, resource reaper, file descriptor tracking, orphaned temp file cleanup, stale lock purging, storage telemetry inspection, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/resourcehygiene |
| System Modularity Inspection & Codebase Peeling Subsystem Operational Architecture Guide | Subsystem architecture, codebase structural inspection, dynamic command peeling, LOC metrics engine, threshold sentinels, thread-safe component registry, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/systempeel |
| Sovereign Relay Tunnel & Inbound Webhook Bridge Subsystem Architectural & Operational Guide | Subsystem architecture, persistent outbound TLS/WSS tunnels, Ed25519 JWT verification, inbound webhook ingress routing, token bucket rate limiting, TTL buffer queues, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/relay |
| Release Gate, Multi-Platform Compilation & Public Payload Verification Subsystem Architectural & Operational Guide | Subsystem architecture, hermetic cross-compilation matrix, SHA-256 manifest verification, archive stream inspection, path traversal sentinels, secret quarantine, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/releasegate |
| Diagnostic Reports & System Vitality Telemetry Subsystem Architectural & Operational Guide | Subsystem architecture, lifecycle maturation metrics, system vitality health scores, QA test telemetry, cross-system summaries, MCP tool integration, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/reports, report_maturation, report_vitality, report_qa_success |
| Diagnostic Capture, Stagnation Detection & Runtime Profile Subsystem Architectural & Operational Guide | Subsystem architecture, failure envelope schema, deterministic cryptographic signatures, loop stagnation detection, progressive disambiguation, SIGUSR1/SIGUSR2 signal profiling, embedded pprof server, and >=85.0% statement coverage invariant. | SREs, Kernel Architects & Autonomous AI Agents | pkg/diagnostics |
| Process Supervision, Engine Registry & Metrics Extractor Subsystem Architectural & Operational Guide | Subsystem architecture, failure diagnostic extraction, contrastive retry prompt formatting, negative hypothesis pruning, canonical exemplar registry, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/supervision |
| Supply Chain Integrity, SBOM Generation & Secret Scanning Subsystem Architectural & Operational Guide | Subsystem architecture, OpenVEX attestation validation, SHA-256 manifest verification, secret pattern scanning, fail-closed release gates, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/supply, scripts/open-core, scripts/scan-secrets.sh |
| System Check Wake, Threshold Evaluation & Seat Notification Subsystem Operational Architecture Guide | Subsystem architecture, threshold evaluation engine, primary seat resolution, agent feed wake dispatch, Proof of Life toasts, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/systemcheckwake, zqk system check --notify |
| System Auto-Remedy, Anomaly Healing & Remediation Engine Subsystem Operational Architecture Guide | Subsystem architecture, DiagnosticsRemedyEngine, stale lock/temp remediation, precondition seeding, boundary guards, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/system, zqk system check --auto-fix |
| Telemetry Pipeline, Metric Export & Observability Subsystem Architectural & Operational Guide | Subsystem architecture, telemetry intake, anonymization pipeline, drift detection, memory cap RSS protection, hook propagation, throughput aggregation, daemon lifecycle, and >=85.0% statement coverage invariant. | SREs, Kernel Architects & Autonomous AI Agents | pkg/telemetry |
| Distributed Tracing, Requirement-to-Backlog Binding & Span Correlation Subsystem Operational Architecture Guide | Subsystem architecture, requirement-to-backlog binding, active lifecycle evaluation, orphan parking with no_covering_bli, stateless concurrency safety, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/tracing |
| Workstream Observability, Metric Sets & Heuristic Snapshot Subsystem Operational Architecture Guide | Subsystem architecture, point-in-time metric snapshots, tagged metric sets, multi-type heuristic bounds checking, snapshot isolation, workspace thresholds, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/wsobs |
| Context Events Pipeline, Wire Event Serialization & JSON Codec Multiplexing Subsystem Operational Architecture Guide | Subsystem architecture, append-only context_events.jsonl pipeline, wire protocol specification, JSON codec multiplexing, backwards-compatible schema fallbacks, 64KB payload bounds, and 100.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/contextevents, zqk system emit-context-event |
| Logging & Structured Event Dispatch Subsystem Operational Architecture Guide | Subsystem architecture, context-aware event routing, MCP protocol stream protection, zero-allocation fluent builder pooling, shared background flush loop, size-based rolling, and >=85.0% statement coverage invariant. | All Engineers & Autonomous AI Agents | pkg/logging |
Recommended Learning & Onboarding Paths
Human Engineer Onboarding Path:
[Community First-Run] ──► [Object Lifecycle Guide] ──► [Mission Control Visual Guide] ──► [Policy Studio Guide]
(docs/onboarding) (docs/guides) (docs/manual) (docs/guides)
Autonomous AI Agent Onboarding Path:
[Agent Boot Protocol] ──► [Agent Onboarding Guide] ──► [ZQL & ZPARQL Guide] ──► [Single-Command Execution Loop]
(AGENTS.md) (docs/onboarding) (docs/guides) (docs/guides)
Related Documentation
- Reference Manual: Deep subsystem manuals for Mission Control, Web Studio, and language references.
- Interactive Tutorials: Hands-on walkthroughs for object inspection, console navigation, and TUI features.
- Architecture Specifications: Formal EBNF grammars, AST schemas, and transaction execution specifications.
- Operational Incident Runbooks: Tactical runbooks for CAS corruption, lock contention, and WAL recovery.
- Documentation Index: Complete hierarchical site map of all ZQK Core documentation.