Codifica Protocol Agent

---

name: codifica

description: Keep context when work moves between agents or between you and a human. Uses the Codifica protocol to give every agent a shared, persistent memory of tasks, decisions, and handoffs — stored as plain text in Git.

version: 1.0.0

homepage: https://github.com/davidedicillo/codifica

metadata: {"openclaw":{"emoji":"📋","requires":{"anyBins":["git"]}}}

---

# Codifica Protocol Agent

You are operating in a repository that uses the **Codifica protocol (v0.2)** — a file-based protocol for coordinating work between humans and AI agents.

Codifica uses plain text files committed with the code. There is no external service, no API, no database. Git is the audit log.

Before doing any work

1. Read `codifica.json` at the repo root

2. Read the spec file it references (the `spec` field — typically `codifica-spec.md`)

3. Read ALL state files matching the `state` field (may be a string, glob, or array)

**Do not proceed without reading the spec.**

If `codifica.json` does not exist in the repo, this protocol does not apply — work normally.

Understanding codifica.json

{
  "protocol": "codifica",
  "version": "0.2",
  "spec": "codifica-spec.md",
  "state": "work.md",
  "assets": "assets/",
  "rules": "strict"
}

Key fields:

If `rules` is an object, check:

Finding work

Scan all state files for tasks where:

Pick by priority: `critical` > `high` > `normal` > `low`.

Among equal priority, prefer tasks with no `depends_on` (leaf tasks first).

Claiming a task

Before starting work, you MUST claim the task in a single atomic commit:

1. Set `state: in_progress`

2. Set `owner: agent:<your-name>`

3. Set `claimed_at: <ISO-8601 timestamp>`

4. Add a `state_transitions` entry recording the claim

Commit all these changes together. If you are working with a remote, push immediately. If the push fails (another agent claimed first), do NOT start work — pull, re-evaluate, and pick a different task.

An `unassigned` task in `in_progress` is a protocol violation.

Reading context before starting

Before starting a task, read its `context` field:

If the task has `depends_on`, also read the dependency tasks' `execution_notes` (especially the `summary`) and `artifacts` for handoff context.

Doing the work

Follow the task's `acceptance` criteria. Respect any `context.constraints`. Work within the `file_scope` defined in `codifica.json`.

Recording completion

When you complete work, update the task in the state file:

1. Add an `execution_notes` entry:

```yaml

execution_notes:

- by: agent:<your-name>

note: |

Description of what you did.

summary: "Single line, max 120 chars, scannable answer"

timestamp: <ISO-8601>

provenance:

session_id: <your-session-id-if-available>

```

2. Record any files you produced in `artifacts`:

```yaml

artifacts:

- path: src/feature/new-file.ts

type: code

- path: assets/TASK-ID/output.csv

type: csv

```

3. Move the task to the appropriate next state:

- For `build` tasks: `in_progress` → `to_be_tested`

- For other types (`test`, `investigate`, `followup`): `in_progress` → `done` (may skip `to_be_tested`)

- Set `completed_at: <ISO-8601>` when moving to `done`

4. Add a `state_transitions` entry:

```yaml

state_transitions:

- from: in_progress

to: to_be_tested

by: agent:<your-name>

reason: "Work completed, ready for testing"

timestamp: <ISO-8601>

```

5. Commit with a message referencing the task ID: `FEAT-101: implement login flow`

Rules you MUST follow

Requesting a block

If you discover a genuine blocker (missing dependency, failing test, ambiguous requirement):

Answering questions about work

When asked about what work has been done (by you or other agents):

This is the structured alternative to reading chat transcripts.

Conflicts

If your push fails due to a Git conflict:

1. Pull the latest state

2. Re-evaluate whether your changes still apply

3. Retry or yield to human resolution

Conflicts on the same task should be escalated to a human.

Task states reference

todo → in_progress → to_be_tested → done
         ↓                            ↑
       blocked ──→ todo ──────────────┘
         ↓
       rejected ──→ todo (human-only reopen)

Only humans may move tasks to `blocked` or `rejected`.

Only humans may reopen tasks from `rejected`.