Codifica

Overview

Codifica is a file-based protocol for coordinating work between humans and AI agents. It treats project state as plain text committed with the code, so changes are reviewable, auditable, and portable.

The problem it solves: most human↔AI collaboration happens in transient chat context and tool-specific UIs. That makes it difficult to review what changed, understand why it changed, reproduce decisions, and coordinate multiple contributors (human or agent) without conflicts or loss of context. Codifica moves the shared state into versioned files so the workflow inherits Git's guarantees and review practices.

Codifica is intentionally Git-native: the primary interface is the repository history (diffs, reviews, and merges). The protocol standardizes how work, decisions, and constraints are recorded so that humans and agents can collaborate without relying on a specific platform.

Codifica is not a task manager, not a SaaS product, and not a Kanban system. It does not replace human ownership, judgment, or review.

Protocol

Codifica defines a small set of artifacts and conventions:

• codifica.json: project-level configuration — protocol version, state file locations, agent permissions, file scope rules, and runtime constraints.
• work.md: the shared state file where tasks, acceptance criteria, review notes, execution logs, and state transitions are recorded. Can be split across multiple files for scalability.

A typical task entry records:

• identifiers and type (id, type)
• current state and ownership (state, owner)
• priority and dependencies (priority, depends_on)
• what "done" means (acceptance)
• structured input context (context: files, references, constraints)
• execution notes with summaries (execution_notes, summary)
• produced artifacts (artifacts)
• provenance metadata (provenance: session ID, commit SHA)
• an auditable history of transitions (state_transitions)

The protocol assumes normal development workflow: work is proposed as changes to these files (and code), reviewed via diffs, and accepted by merging.

Starter templates

Get a copyable starter setup from: starter-templates/v0.2.

Multi-Agent Coordination

Codifica v0.2 is designed for multi-agent systems. When work distributes across isolated agents, context is typically lost — each agent has its own session, workspace, and memory. Codifica solves this by acting as a shared memory layer that all agents read and write.

Task claiming

Agents claim tasks via atomic Git commits (state + owner + timestamp in a single commit). If a push fails because another agent claimed first, the agent picks a different task. No race conditions, no distributed locks.

Structured handoffs

When one agent's output feeds into another agent's work, the handoff is explicit: dependencies (depends_on), structured context (context), produced artifacts (artifacts), and scannable summaries (summary). No side-channel communication needed.

Cross-agent queryability

Any agent can answer "what did the marketing agent do this week?" by scanning work.md for owner, state, completed_at, and summary fields. Structured data, not chat transcripts.

Provenance

Every transition and execution note can carry provenance metadata (session ID, commit SHA) so a human reviewing a Git diff can trace actions back to their source across multiple agents.

Philosophy

Codifica prefers constraints over autonomy:

• work is explicit and scoped
• agent behavior is bounded by written rules
• the human remains accountable for outcomes

Codifica prefers durable state over dashboards:

• the source of truth is text, not a UI
• state is readable without any service
• history is preserved by version control

Codifica prefers traceability over output:

• the "why" is recorded with the change
• review is a first-class step, not an afterthought
• provenance connects actions to agents and sessions

Humans express intent and judgment. Agents execute explicit contracts. Codifica preserves truth and causality.

Examples

Example 1: Define a task with context and dependencies

A work.md task captures intent, constraints, and structured context:

- id: FEAT-102
  type: build
  state: todo
  owner: agent:builder
  title: Implement user login flow
  priority: high
  depends_on:
    - FEAT-101

  acceptance:
    - Login form validates email and password
    - Successful login redirects to dashboard

  context:
    files:
      - src/auth/login.ts
      - docs/auth-architecture.md
    references:
      - FEAT-101
    constraints:
      - "Must be backward compatible with v2.x clients"

Example 2: Record completion with summary and artifacts

When an agent completes work, it records a scannable summary and produced files:

execution_notes:
  - by: agent:builder
    note: |
      Implemented login flow with email/password validation.
      Added redirect logic to dashboard on success.
    summary: "Implemented login flow with validation and redirect"
    timestamp: 2026-02-15T14:30:00Z
    provenance:
      session_id: sess_abc123

artifacts:
  - path: src/auth/login.ts
    type: code
  - path: src/auth/login.test.ts
    type: test

completed_at: 2026-02-15T14:30:00Z

Example 3: Cross-agent handoff

Agent B's task depends on Agent A's completed work. The handoff is fully explicit:

- id: MARKETING-014
  type: build
  state: todo
  owner: agent:marketing
  title: Write pricing blog post
  depends_on:
    - RESEARCH-012

  context:
    files:
      - assets/RESEARCH-012/pricing.csv
    references:
      - RESEARCH-012
    notes: |
      Use the competitor analysis from RESEARCH-012.
      See its execution_notes for methodology.