Getting Started
Docs » Getting Started » AI Agent Onboarding & Operating Protocol
Raw .md

AI Agent Onboarding & Operating Protocol

Welcome. This document outlines the operational directives, seating configurations, and self-discovery protocols for operating AI agents within a ZQK Knowledge Kernel repository.

🔌 Agent Seating & Connection Matrix

ZQK is built to interface seamlessly with any AI agent via the Model Context Protocol (MCP) or direct CLI execution. Choose your host below:

1. Cursor

  • Directives: Cursor automatically reads .agents/AGENTS.md and .cursorrules in your project root.

  • MCP Connection: Pre-configured in .cursor/mcp.json. If configuring manually, add to .cursor/mcp.json (or Cursor Settings → Features → MCP): json { "mcpServers": { "zqk": { "command": "zqk", "args": ["mcp", "serve"] } } }

  • Seating Prompt: In Cursor Composer or Chat, prompt your agent:

    "You are paired with the ZQK Knowledge Kernel. Run zqk workflow whats-next to discover active goals and tasks, then run zqk do to claim and execute work."

2. Claude Desktop & Claude Code

  • Claude Desktop: Auto-install the MCP server configuration: bash zqk mcp install Restart Claude Desktop. The ZQK tools icon will appear in the input bar.

  • Claude Code (CLI): Register the ZQK MCP server: bash claude mcp add zqk -- zqk mcp serve

3. Windsurf (Cascade)

  • Directives: Cascade automatically respects .windsurfrules and .agents/AGENTS.md.
  • MCP Connection: Configured in ~/.codeium/windsurf/mcp_config.json: json { "mcpServers": { "zqk": { "command": "zqk", "args": ["mcp", "serve"] } } }

4. Cline / Roo Code (VS Code Extension)

  • Directives: Cline loads .clinerules from the project root.
  • MCP Connection: Automatically configured into cline_mcp_settings.json. Or add via the Cline MCP Settings tab with command zqk and args ["mcp", "serve"].

5. Gemini CLI / Antigravity / Google Agents

  • Directives: Direct native integration via .agents/AGENTS.md.
  • Execution: Run zqk CLI commands directly or connect via MCP standard I/O (zqk mcp serve).

6. Hermes, OpenClaw & Headless Swarms

  • Direct CLI Execution: Grant the agent bash permissions. The agent interacts via: bash zqk workflow whats-next --format json zqk do <bli-id>

  • TCP Loopback Proxy: If your swarm runner connects via TCP instead of stdio: bash zqk mcp proxy --tcp 127.0.0.1:7777

🔄 Autonomous Execution Protocol (zqk do)

When an agent claims or executes work, use the streamlined single-command loop:

# 1. Discover active priority plan and shovel-ready backlog items
zqk workflow whats-next

# 2. Claim and begin executing the next prioritized task
zqk do

# 3. Or target a specific Backlog Item
zqk do BLI-001

# 4. Implement code changes, then run verification to latch criteria
zqk do BLI-001 --verify

# 5. Check project health and compliance cake
zqk system check

📜 Core Directives for Autonomous Agents

  1. Kernel Primacy & State Integrity: - Process states, task ownership, roadmaps, and requirements exist exclusively in the Knowledge Kernel. - Do not store state, loops, or notes in local vendor-specific scratch directories (such as .gemini/ or .cursor/). If information is not committed to the kernel graph or registered via the CLI, it does not exist.

  2. Session Initialization & Self-Discovery: - On initial contact or when starting a session, run zqk system agent-onboard to detect your agent host and register seating. - Proactively discover current mission, active priority plans, and backlog items by executing zqk workflow whats-next. Do not stop or wait for manual human instructions if active plan work is queued.

  3. Intake & Mutation Boundaries: - Process instances live strictly under .zqk/process/ and content-addressable storage (CAS). - Never write process YAML files directly or bypass the CLI intake layer (zqk intake / zqk object create). All object creation must satisfy schema validation rules. - Project configuration is maintained in config/zqk.yaml / config/zqk-local.yaml.

  4. Lifecycle & Verification Gates: - Background tasks and test executions must be dispatched through the native scheduler (zqk scheduler start). - Use zqk test run or zqk do <bli-id> --verify to verify implementation before completing tasks. - Never use direct edits to bypass lifecycle state transitions—always use zqk object promote or zqk do.