Protocol spec

Normative operational requirements for theta-spec compliant implementations. The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are used per RFC 2119.

For explanatory guides with examples, check the protocol guide.

---

Operations

This protocol defines six operations. Implementations MUST support all six of them to be considered compliant.

Operation	Input	Output	Network	Description
Validate	theta.toml	Diagnostics	No	Structural and semantic validation
Lock	theta.toml	theta.lock	MAY (git fetch)	Resolve all dependencies, pin versions
Materialize	theta.lock	.theta/	No	Populate the materialization directory from locked sources
Cast to	theta.toml + .theta/	Harness config files	No	Convert manifest to harness-specific format
Cast from	Harness config files	theta.toml + source files	No	Import harness-specific config into a manifest
Check	theta.toml + theta.lock + .theta/	Diagnostics	No	Full pipeline validation (structural + reachability + content quality)

Protocol artifacts

Artifact	Lifecycle	Description
theta.toml	User-authored	The manifest — MUST be committed to version control
theta.lock	Generated by lock	Pinned dependency graph — MUST be committed to version control
.theta/	Generated by materialize	Materialization directory — derived artifact, SHOULD be gitignored

.theta/ is a protocol-level requirement: it is the directory through which resolved resources are made available to downstream operations (cast, check). Its contents are fully determined by theta.lock.

---

Validate

Implementations MUST validate theta.toml against the published JSON Schema for the declared schema version before any operation that consumes the manifest (lock, materialize, cast, check).

• Invalid manifests MUST cause immediate failure with actionable diagnostics
• Validation MUST cover structural conformance (schema) and semantic constraints defined in the manifest spec

---

Lock

Resolves all declared dependencies and produces a deterministic lockfile.

Determinism

• The lock operation MUST be fully deterministic
  • Same theta.toml MUST produce the same theta.lock
• The lock path MUST NOT invoke LLM calls

Lockfile contents

The lockfile MUST pin:

• Exact content hash for every local-path dependency
• Exact commit SHA for every git dependency
• The schema version from theta.toml

Source resolution

The lock operation resolves each dependency based on its SourceRef or LocalOrGitRef type:

Type	Resolution
path	Content hash (SHA-256) of the source file or directory
git	Clone/fetch into local cache, resolve ref to commit SHA
system	Read from system store, content hash

Staleness

Implementations MUST detect when theta.toml has changed relative to theta.lock.

Implementations SHOULD re-resolve automatically when the lockfile is stale.

Local cache

Resolved remote dependencies MUST be cached following XDG Base Directory conventions:

• Default: ~/.cache/theta/
• Override: $XDG_CACHE_HOME/theta/ if set

Caching SHOULD be content-addressed where possible (git commit SHAs, URL content hashes).

---

Materialize

Reads theta.lock and populates .theta/ with all resolved resources. The materialization directory is a flat projection of the locked dependency graph.

.theta/ structure

Path	Source
.theta/system.md	Resolved system prompt
.theta/rules/<name>.md	Resolved rule files
.theta/skills/<name>/	Resolved skill packages
.theta/subagents/<name>/theta.toml	Resolved ref-subagent manifests (recursive)

• .theta/ is a derived artifact — SHOULD be gitignored
• Materialization SHOULD NOT access the network. Implementations MAY re-fetch a commit already pinned in theta.lock if the local cache is missing, but MUST NOT resolve new refs during materialization
• Orphan entries (locked resources that no longer exist in the manifest) SHOULD be removed

Post-materialization validation

After materialization, implementations MUST validate that resolved resources satisfy the requirements defined in the manifest spec:

• Skill directories MUST satisfy the materialized skill requirements
• Rule files MUST exist and MUST NOT be empty
• Subagent refs MUST point to a valid theta.toml

Invalid dependencies MUST cause immediate failure with actionable diagnostics.

---

Cast to

Converts a theta.toml manifest into harness-specific configuration files.

Inputs and outputs

• Input: theta.toml (the manifest) + .theta/ (materialized resources)
• Output: harness-specific configuration files written to the project directory

Implementations SHOULD ensure that .theta/ is up to date before casting (implicit sync).

Determinism

• Casting MUST be deterministic: same manifest + same .theta/ contents + same target MUST produce the same output files
• Casting MUST NOT access the network
• Casting MUST NOT invoke LLM calls

Lossy casting

• Casting MAY be lossy — not all manifest fields are representable in every target harness
• Casting MUST NOT be silently lossy — when a field cannot be represented, the implementation MUST emit a warning
• Lossy casting MUST NOT cause failure
• When the target has less granularity, casting SHOULD err toward the more restrictive interpretation

Multi-harness

• A single manifest MAY contain [harness.<name>] sections for multiple targets
• When casting to harness X, implementations MUST read common sections plus [harness.X]
• All other [harness.*] sections MUST be ignored

Output validation

Implementations SHOULD validate cast output against known harness constraints and emit diagnostics:

• Hard limits (harness will reject or truncate) SHOULD produce warnings
• Soft limits (harness recommends but does not enforce) SHOULD produce hints

Known constraints are documented per-harness in the instructions guide and harness reference.

Cast notes

Implementations SHOULD provide a way to surface known limitations and clarifying notes for each harness. These notes describe lossy transforms, format normalization, and other non-obvious behaviors that may affect round-trip fidelity.

---

Cast from

Imports harness-specific configuration files into a theta.toml manifest.

Inputs and outputs

• Input: harness-specific configuration files from the project directory
• Output: theta.toml + extracted source files (system prompt, rules, etc.)

Information preservation

• Import MUST NOT silently discard information
• Config that maps to a common theta-spec field MUST go in the corresponding common section
• Harness-specific config with no common equivalent MUST go in [harness.<name>]

Merge behavior

If a theta.toml already exists, import MUST warn and SHOULD offer to merge or skip.

---

Check

Full-pipeline validation combining structural, reachability, and content quality checks.

Phases

• Structural — validate theta.toml against the JSON Schema and manifest spec constraints
• Reachability — verify that all declared local paths exist, git refs are resolvable, and system store entries are present
• Content quality — detect placeholder or empty source files that need user attention

Lock and materialization checks

• If theta.lock exists, check MUST verify consistency with theta.toml
• If .theta/ exists, check MUST verify that materialized contents match locked expectations
• Check SHOULD report stale locks or missing materializations as warnings, not errors