Agent Task Envelope Execution Guidance and Command Syntax Conventions
Comprehensive architectural, operational, and command syntax reference for Agent Task Envelope resolution and prepare-context execution in the ZQK Knowledge Kernel.
1. Architectural Overview & Design Philosophy
In the ZQK Knowledge Kernel, autonomous coding agents do not operate on ungrounded conversational strings, nor do persistent objects store bloated static instructions. Instead, task generation and worker execution follow a strict Dual-Layer Context Hydration Model:
-
Persist Layer (
PromptLayerPersist): - Represents the persistent state stored in CAS underagent_task(.zqk/process/agent_tasks/). - Strictly contains dynamic task facts (plan references, personas, problem statements, upstream deliverables) and relational object IDs (policy references, skill references). - Marked byzqk_task_envelope_v1inTaskEnvelopeMarker. - Never embeds static policy bodies, skill instruction bodies, or massive AST code censuses directly onto the task object. This invariant guarantees token budget conservation, prevents relational drift, and ensures changes to policies or skills propagate instantly to all future executions. -
Execute Layer (
PromptLayerExecute): - Assembled just-in-time immediately prior to worker subagent dispatch or local execution. - Performed byzqk agent prepare-context(or programmatic callers likeAssemblePreparedContext). - Inlines active policies, seals verified skills, injects AST observer hints, and hydrates upstream verified deliverables into a complete, token-budgeted prompt.
To bridge the persist layer and execute layer, every generated task envelope embeds a standard Execution Resolution Header:
Resolve at execute: `zqk object get <id>`, `zqk agent prepare-context <ATK>`, or `zqk workflow whats-next`.
This instruction explicitly directs receiving agents on how to dynamically resolve object references without cold-starting or assuming missing context.
2. Command Syntax Conventions: zqk agent prepare-context
The zqk agent prepare-context command is the central entrypoint for assembling an agent's execution context.
2.1 Positional vs. Flag Invocations
To ensure maximum ergonomic flexibility across automated orchestrators, human operators, and legacy task envelopes, zqk agent prepare-context supports both positional arguments and flag aliases:
| Invocation Style | Syntax | Notes |
|---|---|---|
| Canonical Positional (Preferred) | zqk agent prepare-context <task_id> |
Canonical modern syntax used in generated envelopes and CLI help. |
Flag Alias (--task-id) |
zqk agent prepare-context --task-id <task_id> |
Supported alias matching task envelope headers and legacy scripts. |
Flag Alias (--task) |
zqk agent prepare-context --task <task_id> |
Standard single-word flag alias for consistency with other CLI commands. |
| Ad-Hoc / Unminted Task | zqk agent prepare-context --description "<text>" |
Generates context for ad-hoc tasks not yet minted into the kernel. |
2.2 Precedence and Resolution Semantics
When invoking zqk agent prepare-context:
- Positional Precedence: If a positional task ID argument is provided, it is accepted as the primary task ID.
- If a flag (
--taskor--task-id) is also provided with the same task ID, they match and resolution succeeds seamlessly. -
If a flag is provided with a conflicting task ID, the positional argument takes precedence. 2. Flag Fallback: If no positional argument is provided, the CLI inspects
--taskand--task-id. -
If
--taskis supplied, its value is used as the task ID. - If
--task-idis supplied, its value is used as the task ID. - If both
--taskand--task-idare supplied with matching values, resolution succeeds. 3. Negative Adversarial Boundary (Conflicting Flags & Malformed Identifiers): -
If both
--taskand--task-idare provided without a positional argument and their values differ (e.g.zqk agent prepare-context --task ATK-1 --task-id ATK-2), the command fails-closed immediately with a clear, actionable diagnostic:text conflicting flags: --task="ATK-1" and --task-id="ATK-2"; specify only one task flag or supply a single positional argument -
If a malformed task identifier containing whitespace or invalid characters (e.g. path traversal
..or forbidden symbols/\"'<>|&;$+"") is provided in either positional arguments or flags (e.g.zqk agent prepare-context "ATK 100"or--task "ATK/bad"`), the command fails-closed immediately with validation error diagnostics:text malformed task identifier "ATK 100": must not contain whitespace malformed task identifier "ATK/bad": contains invalid characters
- Mandatory Input Gate:
If neither a task ID (positional or flag) nor an ad-hoc
--descriptionis supplied, the command refuses to execute:text prepared context required: task_id or description
3. Options & Flags Reference
| Flag | Type | Default | Description |
|---|---|---|---|
--task <id> |
string |
"" |
Task ID alias (alternative to positional task_id or --task-id). |
--task-id <id> |
string |
"" |
Task ID alias (alternative to positional task_id or --task). |
--persona-ref <id> |
string |
"" |
Persona identifier (PER-*) for skill and prompt binding. |
--description <text> |
string |
"" |
Ad-hoc task description when no persistent task ID is given. |
--depth <int> |
int |
1 |
Related-object subgraph exploration depth for task context assembly. |
--tdd |
bool |
true |
Include Test-Driven Development (TDD) governance guidance. |
--format <format> |
string |
"" |
Output format (json, agent-prompt, yaml, etc.). |
4. Context Assembly Pipeline
When zqk agent prepare-context executes, it performs the following deterministic hydration steps via AssemblePreparedContext:
flowchart TD
CLI["CLI Invocation<br/>(positional / --task / --task-id)"] --> Parse["Arg & Flag Resolution"]
Parse --> InputCheck{"Has TaskID or Description?"}
InputCheck -- No --> Err["Fail-Closed: prepared context required"]
InputCheck -- Yes --> LoadTask["Load Task Object from CAS"]
LoadTask --> Subgraph["Query Subgraph (depth=N)<br/>Dependencies, Criteria, Deliverables"]
Subgraph --> Persona["Resolve Persona (opts or task.assignee_persona_ref)"]
Persona --> Policies["Load Active Governance Policies & Standing Mandates"]
Policies --> Skills["Load Persona-Bound Skills & Cryptographic Seals"]
Skills --> Format["Format Prepared Prompt (json or agent-prompt)"]
Format --> Output["Deliver to stdout / Subagent Dispatch"]
-
Storage Tuple Extraction: Retrieves transactional security context and object storage provider from the active workspace.
-
Task & Subgraph Query: Reads the target
agent_taskobject from CAS. Queries downstream and upstream dependency nodes up to--depthgenerations. -
Upstream Deliverable Splicing: If upstream dependencies have completed and recorded artifacts (
artifacts: [...]), they are rendered in the prompt underUpstream Verified Deliverablesso the worker builds upon verified prior work. -
Policy & Skill Compilation: Discovers active standing policies (
POL-*) and binds the target persona's skills (ASK-*), verifying cryptographic integrity seals. -
AST Observer Hints: Injects AST navigation symbols and directives to prevent hallucinated paths while avoiding monolithic source dumps.
5. Traceability and Verification
This specification satisfies the following Knowledge Kernel contracts:
- Requirement:
REQ-001(Agent Task Context Preparation Instruction Parity) - Criteria:
CRIT-001: Static Floor Invariant: Task envelope template instructs valid CLI invocation for agent prepare-context (zqk agent prepare-context <ATK>/<task-id>).CRIT-001: Operational Dynamic Proof: Verify agent prepare-context successfully accepts both canonical positional syntax and --task aliases.CRIT-001: Negative Adversarial Boundary: Enforce validation failure when conflicting or malformed task identifiers are provided.CRIT-001: Compliance Documentation: Update and maintain AGENT_TASK_ENVELOPE_INSTRUCTIONS.md documenting canonical invocation conventions per POL-DOC-001.- Policies:
POL-DOC-001(Mandatory documentation clarity and completeness)POL-DEFAULT-f746cccc03ce5694(Test-Driven Development and Continuous Verification)POL-DEFAULT-60a14e239d552b9e(Fail-Closed Safety and Invariant Gate Enforcement)