Specification & Grammar Reference
Formal H2C block grammar, field types, and context management commands for AI-to-AI communication.
Block Types
Architecture Block
Declares project architecture, framework, libraries, auth, and file structure. Fields: id, fw, lib, auth, struct, notes. Typically the first block in a workflow.
Build Execution Block
Initiates a build step on a target file. Fields: id, target, desc. Paired with BUILD:DONE for completion tracking.
Build Completion Block
Confirms a build step finished. Fields: id, diff, rev. The diff field uses [filename~revision] format for versioning.
Test Execution Block
Triggers a test suite. Fields: id, target, framework. Paired with TEST:PASS or TEST:FAIL for results.
Test Result Block
Reports test outcomes with metrics. Fields: id, count, coverage. Supports pass/fail status and coverage reporting.
Context Update Block
Tracks workflow layer transitions. Fields: ~progress, ~next, ~active_files. CTX fields use ~ prefix. Mandatory on every layer change.
Handshake Block (v1.4)
Mandatory first block of every chain. Fields: version, capabilities. Negotiates protocol version and features between agents.
Error Recovery Block (v1.4)
Explicit malformed block rejection. Fields: ref_id, error, hint. Replaces silent discard of invalid blocks.
Context Management Commands
Prune
Removes old blocks from the context window. Fields: keep, pruned, reason. Mandatory every 5 messages. Keeps active blocks while pruning completed ones.
Compact
Consolidates message history into a summary. Fields: summary, keep_active, pruned_history. Mandatory every 20 messages with pass/fail counters.
Freeze
Archives history when COMPACT is no longer sufficient (~100 msgs). Fields: snapshot, baseline. Resets PRUNE and COMPACT counters.
Orchestration End
Terminal block signaling workflow completion. Fields: final (complete|error|timeout), est_token, pass_count, fail_count.
Formal Grammar (BNF)
<message> ::= <block>
<block> ::= "[" <type> ":" <subtype> "]" "\n" <fields>
<type> ::= "ARCH" | "BUILD" | "TEST" | "CTX" | "STATE" | "ORCH" | "SKILL"
<subtype> ::= "PLAN" | "EXEC" | "DONE" | "FIX" | "REVERT" | "NACK"
| "RUN" | "PASS" | "FAIL"
| "PRIMITIVES" | "UPDATE" | "PRUNE" | "COMPACT" | "FREEZE"
| "NEGOTIATE" | "FINDINGS" | "ACK" | "END" | "PROMPT"
<fields> ::= <field> ("|" <field>)*
<field> ::= <key> ":" <value> | "~" <key> ":" <value>
<key> ::= [a-zA-Z_][a-zA-Z0-9_]*
<value> ::= <int> | <signed_int> | <rev> | <list> | <string>
<int> ::= [0-9]+
<signed_int> ::= ["+" | "-"] <int>
<rev> ::= <string> "~" <int>
<list> ::= "[" <string> ("," <string>)* "]"
<string> ::= [^\|\n\[\]\:]+
<env-ref> ::= "::env(" <identifier> ")"EBNF ISO 14977 compliant. See the full SPEC.md on GitHub for the complete formal specification, AST model, and opcodes.
Field Reference
| Field | Type | Used In | Description |
|---|---|---|---|
id | string | All blocks | Unique identifier for correlation |
fw | string | ARCH:PLAN | Framework and version (e.g. python3.11) |
lib | string | ARCH:PLAN | Dependencies (comma-separated) |
struct | list | ARCH:PLAN | File/directory structure |
diff | list_rev | BUILD:DONE | Changed files with revision [file~N] |
rev | int | BUILD:DONE | Revision number (monotonic) |
cycle_id | string | BUILD:FIX, TEST:FAIL, TEST:PASS | Unique fix cycle identifier |
~progress | string | CTX:UPDATE | Current layer and status (layer=N,status=X) |
~active_files | list_rev | CTX:UPDATE | Files currently in play with revision |
keep | list_ids | CTX:PRUNE | Blocks to retain |
pruned | list_ids | CTX:PRUNE | Blocks to remove |
summary | list | CTX:COMPACT | Max 5 entries summarizing pruned history |
baseline | int | CTX:FREEZE | Message number at freeze point |
est_token | int | ORCH:END | Estimated token consumption |
Ready to Implement H2C?
The specification is open-source (MIT). No dependencies, no runtime — just plain text.