Agent Onboarding & Environment Seeding Subsystem Guide
Comprehensive architectural, operational, and integration reference for the pkg/agentonboard subsystem in ZQK Core.
1. Architectural Overview
When autonomous software agents, human pair programmers, or IDE tools connect to a repository governed by the ZQK Knowledge Kernel, they require an unambiguous operational contract. In heterogeneous environments, different agent harnesses (e.g. Claude Code, Cursor, Windsurf, Antigravity, Copilot, Ollama, and CLI-based headless runtimes) expect workspace configuration files and directives in differing formats and filesystem locations.
The Agent Onboarding & Environment Seeding Subsystem (pkg/agentonboard) serves as the first-contact entry membrane for the workspace. It reconciles local editor environments with persistent Knowledge Kernel graph objects, primes operational directives, synchronizes kernel-managed skill definitions, and registers stable workspace identity fingerprints without mutating non-managed user files.
flowchart TD
subgraph Host["Host Environment & IDE Workspace"]
Editor["Agent Host / IDE / Headless CLI"]
WorkspaceDir["Project Root Workspace"]
end
subgraph AgentOnboardSubsystem["Agent Onboarding Subsystem (pkg/agentonboard)"]
Runner["Onboarding Runner (run.go)"]
Detector["Vendor Detector (vendors.go)"]
Headless["Headless Vector Engine (headless.go)"]
PrimeSeeder["Prime Seeder (prime.go)"]
PackWriter["Pack Writer (packs.go)"]
SkillHydrator["Skill Hydrator (skills.go)"]
end
subgraph KnowledgeKernel["ZQK Knowledge Kernel (.zqk/)"]
GraphCAS["CAS Graph Storage & Seating"]
KernelSkills[".zqk/skills/ (Source of Truth)"]
AgentPacks[".zqk/agent_packs/ (Boot Payloads)"]
RuntimeStore[".zqk/agent-runtime/sync-report.json"]
end
Editor -->|"Invoke: zqk system agent-onboard"| Runner
Runner -->|"1. Probe Markers & Signals"| Detector
Runner -->|"2. Evaluate Specialization"| Headless
Runner -->|"3. Seed Default Seating"| GraphCAS
Runner -->|"4. Project Universal Directives"| PrimeSeeder
PrimeSeeder -->|"Write AGENTS.md & Hooks"| WorkspaceDir
Runner -->|"5. Materialize Vendor Packs"| PackWriter
PackWriter -->|"Persist BOOT.md per Vendor"| AgentPacks
Runner -->|"6. Project Managed Skills"| SkillHydrator
KernelSkills -->|"Symlink Projection & Orphan Prune"| SkillHydrator
SkillHydrator -->|"Hydrate Skills"| WorkspaceDir
Runner -->|"7. Persist Sync Report"| RuntimeStore
Core Invariants
-
Universal Directive Anchor (
AGENTS.md): Regardless of detected IDE vendors or headless modes,pkg/agentonboardguarantees that.agents/AGENTS.mdis populated with canonical kernel boot payload directives. This universal directive acts as the primary headless-safe interface. -
Non-Destructive Default & Explicit Force Protection: Existing workspace configuration files and foreign symlinks or custom user files are never overwritten or deleted by default. Modifications or overwrites require explicit operator consent via
--force. -
Dual Execution Vectors (Vector A vs. Vector B): - Vector A (IDE & Interactive Hosts): Activated when IDE markers (such as
.cursor,.claude,.ide, or.windsurf) are present. Provisions vendor-specific rules, symlinks skills into editor directories, and exposes interactive workflows. - Vector B (Headless, Appliance & Edge Hosts): Activated in headless CLI environments, server appliances, or remote SSH/container workers. Skips desktop IDE rule files, generates edge signal probes, and relies exclusively on universal directives and kernel graph objects. -
Kernel as Single Source of Truth for Skills: The authoritative origin for all reusable agent skills is
.zqk/skills/. Workspace skill directories (such as.agent/skillsand.cursor/skills) are projected views created via relative symlinks. Orphaned symlinks whose origin was removed from.zqk/skills/are cleaned automatically. -
Idempotent Execution & Fingerprinted Synchronization: Repeated invocations of
zqk system agent-onboardare completely idempotent. Each run calculates a SHA-256 workspace fingerprint combining project path, vector mode, and detected vendor set, recorded within.zqk/agent-runtime/sync-report.json.
2. Component Topology
The subsystem is organized into modular Go packages providing clear separation of concerns:
| Component | Implementation File | Primary Responsibilities |
|---|---|---|
| Onboarding Runner | run.go |
Orchestrates the multi-stage pipeline: detection, session validation, agent seating, workspace priming, skill synchronization, and post-onboarding smoke validation. |
| Vendor Registry & Detector | vendors.go |
Defines the canonical vendor table (KnownVendors), marker path heuristics, filter normalization, and local Ollama inference detection. |
| Headless Vector Engine | headless.go |
Collects edge hints (GPU visible devices, DGX appliance release markers, SSH session detection, specialization tiers) and manages the market probe questionnaire. |
| Prime Seeder | prime.go |
Formats and writes vendor configuration files, provisions anti-idle hook configurations (hooks.json), and handles JSON sync report persistence and loading. |
| Pack Writer | packs.go |
Materializes isolated vendor boot definitions (.zqk/agent_packs/<vendor>/BOOT.md) containing base kernel guidance plus vendor-specific addenda. |
| Skill Hydrator | skills.go |
Projects kernel skills into active IDE skill folders using relative symlinks, prunes unmanaged or orphaned projections, and guards against collisions. |
| Payload Formatter | payload.go |
Generates the core markdown boot payload containing the 5-layer ontological cascade, anti-idleness protocols, and execution discipline. |
3. Multi-Agent Onboarding Lifecycle
The onboarding pipeline progresses through six deterministic execution stages:
sequenceDiagram
autonumber
participant Op as Human / Autonomous Agent
participant Run as Onboarding Runner (run.go)
participant Det as Vendor Detector (vendors.go)
participant Seat as Seating Engine (CAS)
participant Prime as Prime Seeder (prime.go)
participant Skill as Skill Hydrator (skills.go)
participant Repo as Disk / Knowledge Kernel
Op->>Run: Run(Options)
Run->>Det: DetectVendors(projectRoot)
Det-->>Run: []DetectedVendor
Run->>Run: InferVector(detected) -> Vector A or B
alt Seating Enabled
Run->>Seat: opts.Seat(projectRoot, logger)
Seat->>Repo: Create default agent seating objects
Seat-->>Run: createdCount, err
end
alt Workspace Priming Enabled
Run->>Prime: WriteVendorConfigs(projectRoot, vendors, dryRun, force)
Prime->>Repo: Write .agents/AGENTS.md & hooks.json
Prime-->>Run: WriteResult
Run->>Repo: WriteVendorPacks (agent_packs/<id>/BOOT.md)
end
alt Skill Synchronization Enabled
Run->>Skill: SyncSkills(projectRoot, detected, allVendors, headless, dryRun, force)
Skill->>Repo: Validate .zqk/skills, create relative symlinks
Skill-->>Run: SkillSyncResult
end
Run->>Repo: WriteSyncReport(.zqk/agent-runtime/sync-report.json)
Run->>Run: smoke(projectRoot, dryRun, skipPrime, primed, skipped)
Run-->>Op: *Result (Stages, Fingerprint, NextSteps)
Stage Details
-
Detection Stage (
detect): Scans the workspace root for marker directories and configuration files. In addition to filesystem markers, it probes local TCP loopbacks (e.g. port 11434) and environment variables (OLLAMA_HOST,LLM_PROVIDER) to detect local air-gapped models. -
Authentication & Session Stage (
auth): Verifies whether an authenticated session exists. In Community Edition, local offline sessions are accepted by default (StageOK). -
Seating Stage (
seat): Invokes the seat provisioning delegate to create default agent seating records in kernel CAS storage (e.g., Lead Architect, Software Engineer, Quality Verification Craftsman). -
Workspace Priming Stage (
prime_workspace): Emits.agents/AGENTS.mdand vendor-specific rules files. When agent-hook vendors are detected, it configures.agents/hooks.jsonto prevent idle halts and enforce subagent context injection. -
Kernel Sync & Skill Stage (
prime_kernel): Synchronizes skills from.zqk/skills/into editor directories (.agent/skills,.cursor/skills,.claude/skills). Persists the completesync-report.jsonunder.zqk/agent-runtime/. -
Smoke Verification Stage (
smoke): Verifies that generated directives are accessible and intact on disk. Generates targetedNextStepsguidance based on detected execution vector (Vector A vs. Vector B).
4. Vendor Support & Directory Layout
The subsystem provides built-in adapter definitions for major agent platforms:
| Vendor ID | Display Name | Detection Markers | Target Configuration Files |
|---|---|---|---|
agents_md |
AGENTS.md / Universal | AGENTS.md, .agents/AGENTS.md |
.agents/AGENTS.md |
ide |
Generic IDE / Cursor | .ide, .iderules, .ide/mcp.json |
.iderules |
claude_code |
Claude Code | .claude, CLAUDE.md |
CLAUDE.md |
cline |
Cline | .clinerules, .cline |
.clinerules |
windsurf |
Windsurf | .windsurfrules, .windsurf |
.windsurfrules |
gemini |
Gemini CLI | .gemini, GEMINI.md |
GEMINI.md |
agent |
Antigravity / Agent | .agent, ANTIGRAVITY.md |
ANTIGRAVITY.md |
openclaw |
OpenClaw | .openclaw, OPENCLAW.md |
OPENCLAW.md |
ollama |
Ollama (Local Air-Gapped) | .ollama, OLLAMA.md, local:11434 |
OLLAMA.md |
Filesystem Layout Example
A fully onboarded hybrid workspace exhibits the following directory structure:
my-project/
├── .agents/
│ ├── AGENTS.md # Universal headless & agent directive surface
│ └── hooks.json # Subagent pre-invocation and anti-idle hooks
├── .agent/
│ └── skills/ # Projected agent skills
│ ├── arch-design -> ../../.zqk/skills/arch-design
│ └── code-craft -> ../../.zqk/skills/code-craft
├── .cursor/
│ └── skills/ # Projected IDE skills
│ ├── arch-design -> ../../.zqk/skills/arch-design
│ └── code-craft -> ../../.zqk/skills/code-craft
├── .zqk/
│ ├── agent_packs/ # Regenerable vendor boot packs
│ │ ├── agents_md/
│ │ │ └── BOOT.md
│ │ └── ide/
│ │ └── BOOT.md
│ ├── agent-runtime/
│ │ └── sync-report.json # JSON record of sync status and fingerprint
│ └── skills/ # Authoritative kernel skills storage
│ ├── arch-design/
│ │ └── SKILL.md
│ └── code-craft/
│ └── SKILL.md
└── CLAUDE.md # Claude Code entry point (if vendor detected)
5. Failure Modes & Self-Healing
The onboarding subsystem is engineered with defensive fallbacks and fail-safe protections:
stateDiagram-v2
[*] --> HealthyRun: Execute Onboarding
HealthyRun --> SkillCollision: Non-symlink directory in skill path
SkillCollision --> CollisionHalt: force == false (Fail Closed)
SkillCollision --> OverwriteSymlink: force == true (Self-Heal)
HealthyRun --> OrphanedSkillSymlink: Kernel skill removed from .zqk/skills
OrphanedSkillSymlink --> PruneOrphan: Auto-Prune (Self-Heal)
HealthyRun --> MissingVendorConfig: Vendor rules file deleted
MissingVendorConfig --> RegenerateConfig: Re-run agent-onboard (Idempotent)
HealthyRun --> HeadlessEnvironment: Headless flag or no IDE markers
HeadlessEnvironment --> VectorBMode: Fall back to AGENTS.md & skip IDE rules
Specific Resilience Mechanisms
-
Skill Collision Protection: If a non-symlink file or directory occupies a target skill destination (e.g.
.agent/skills/custom-tool), the hydrator refuses to delete or overwrite it without--force. This protects human-authored local tools from accidental truncation. -
Orphaned Skill Auto-Pruning: When a skill pack is removed from
.zqk/skills/, any corresponding symlink whose target path references.zqk/skills/is pruned automatically during synchronization, preventing broken references in editor panels. -
Foreign Symlink Preservation: Symlinks in
.agent/skillsor.cursor/skillspointing to arbitrary outside directories (e.g. personal global dotfiles) are preserved unless--forceis specified. -
Vector B Headless Degradation: In automated pipelines where no GUI editor is running, running with
--headlesssilences the creation of IDE-specific rule files (.iderules,.windsurfrules) and produces lean universal directives.
6. Verification & Test Coverage Invariant
To maintain the architectural integrity of the onboarding membrane, all changes to pkg/agentonboard are governed by continuous verification gates.
Invariant Contract
- Statement Coverage Threshold:
pkg/agentonboardrequires strictly >= 85.0% statement test coverage. - Hermetic Testing: All unit and boundary tests execute against isolated temporary directories (
t.TempDir()). - Zero Swallowed Errors: Error returns across filesystem operations, symlink creation, and JSON serialization are explicitly checked and wrapped using
errfmt. - Targeted Verification Command:
ZQK_ALLOW_FOREGROUND_GO_TEST=1 go test -v -timeout 30s -cover ./pkg/agentonboard
Static Analysis and Code Formatting
gofmt -w pkg/agentonboard/
./bin/zqk-vet -suite hygiene,tree
sh scripts/open-core/check-public-release-payload.sh .