Protocol Specification

The complete specification for the Tick data layer and coordination protocol. Everything an agent or human needs to read, write, and coordinate through TICK.md files.

1. Data Layer

Tick’s data layer is built on three primitives: Markdown for human readability, YAML frontmatter for machine-parseable structure, and Git for versioning and audit. The Markdown file is the database.

Master Task File (TICK.md)

Every Tick project has a single source of truth: TICK.md. This file uses a structured format combining YAML document-level frontmatter, Markdown tables for the agent registry, and repeated YAML+Markdown blocks for individual tasks.

Document Header

The file begins with YAML frontmatter containing project-level metadata:

---
project: adgena-v2
title: Adgena V2 Launch
schema_version: "1.0"
created: 2026-02-05T09:00:00-05:00
updated: 2026-02-07T14:32:00-05:00
default_workflow: [backlog, todo, in_progress, review, done]
id_prefix: TASK
next_id: 43
---

Agent Registry

Immediately after the frontmatter, a Markdown table registers all participants — both human and bot:

## Agents
| Agent | Type | Roles | Status | Working On | Last Active |
|-------|------|-------|--------|------------|-------------|
| @gianni      | human | owner,any    | online  | TASK-001 | 2026-02-07T14:28:00 |
| @claude-code | bot   | engineer     | idle    | -        | 2026-02-07T14:30:00 |
| @content-bot | bot   | copywriter   | working | TASK-003 | 2026-02-07T14:32:00 |
| @qa-bot      | bot   | tester       | idle    | -        | 2026-02-07T14:15:00 |

Agent status values: online, idle, working, offline. The Working On column tracks the currently claimed task.

Individual Task Schema

Each task is a self-contained block with YAML metadata in a fenced code block followed by a Markdown description:

### TASK-001 · Build avatar selection UI

```yaml
id: TASK-001
status: review
priority: urgent        # urgent | high | medium | low
assigned_to: @gianni
claimed_by: null
created_by: @gianni
created_at: 2026-02-05T09:00:00-05:00
updated_at: 2026-02-07T14:28:00-05:00
due_date: 2026-02-14
tags: [frontend, avatar, v2-launch]
depends_on: []
blocks: [TASK-004, TASK-005]
estimated_hours: 8
actual_hours: 6.5
detail_file: tasks/TASK-001.md
history:
  - ts: 2026-02-05T09:00:00  who: @gianni  action: created
  - ts: 2026-02-05T09:15:00  who: @claude-code  action: claimed
  - ts: 2026-02-07T14:00:00  who: @claude-code  action: released
  - ts: 2026-02-07T14:28:00  who: @gianni  action: claimed
```

> Build the avatar grid selector for video generation pipeline.
> Must support keyboard nav and preview on hover.

Task Field Reference

History Entry Format

Each history entry records a single atomic action:

history:
  - ts: 2026-02-05T09:00:00
    who: @gianni
    action: created
    note: "Initial task"
  - ts: 2026-02-05T09:15:00
    who: @claude-code
    action: claimed
  - ts: 2026-02-07T14:00:00
    who: @claude-code
    action: status_change
    from: in_progress
    to: review

Valid actions: created, claimed, released, status_change, assigned, commented, priority_change, dependency_added, dependency_removed.

2. Coordination Protocol

The coordination protocol defines how multiple agents safely interact with the same task file without conflicts. It is the “rules of the road” that every participant must follow.

Claim / Release Cycle

The fundamental unit of coordination is the claim/release cycle. Before an agent works on a task, it must claim it. When done, it releases the claim.

1. Check availability — Verify claimed_by is null and all depends_on tasks are done.
2. Acquire lock — Set the file lock via .tick.lock (timeout: 30s default).
3. Write claim — Set claimed_by: @agent, append history entry, commit.
4. Release lock — Remove the file lock.
5. Do work — The agent performs its task.
6. Release claim — Set claimed_by: null, update status, append history, commit.

If an agent crashes or times out, the lock expires and another agent can claim the task. The previous agent’s partial work is preserved in git history.

State Transitions

Tasks move through workflow states defined in default_workflow. Transitions are validated against the project configuration:

workflow:
  states: [backlog, todo, in_progress, review, done]
  transitions:
    backlog: [todo]
    todo: [in_progress, backlog]
    in_progress: [review, blocked]
    review: [done, in_progress]
    blocked: [todo, in_progress]
    done: [reopened]

Invalid transitions are rejected by the CLI. For example, moving directly from backlog to in_progress is not allowed — it must go through todo first.

Role-Based Access

Agents are assigned roles that control which tasks they can claim and which transitions they can perform:

Conflict Resolution

When two agents attempt to claim the same task simultaneously, the file-level lock prevents data corruption. The first agent to acquire the lock wins. The second agent receives a conflict error and must retry after a configurable delay.

locking:
  timeout_seconds: 30
  retry_attempts: 3
  retry_delay_ms: 500

For distributed teams using a git remote, Tick follows a pull-before-write strategy: always pull latest before acquiring the lock, and push immediately after releasing. Git merge conflicts on the YAML blocks are handled by the CLI with automatic resolution for non-overlapping changes.

Context Handoff

When a new agent picks up a task, Tick assembles a context package containing everything needed to resume work:

• Task metadata from TICK.md (status, priority, dependencies, history)
• Full history log showing all previous agents’ actions and notes
• Detail file content (if detail_file is specified)
• Related task summaries (from depends_on and blocks)
• Agent registry (to understand who else is working on what)

$ tick context TASK-042
# Returns structured context suitable for LLM prompt injection

Trust Levels

Safety Rails

• History immutability — No agent can modify or delete history entries. The append-only log is the auditable record of all actions.
• Transition validation — The CLI enforces valid state transitions. Agents cannot skip states.
• Dependency enforcement — Tasks with unmet dependencies cannot be claimed.
• Rate limiting — Configurable limits on concurrent claims and change frequency.
• Human approval gates — Specific transitions can require human approval regardless of agent role.