agent-protocol

name	agent-protocol
description	Human and agent coordination protocol for repos using .agentprotocol. Use to manage TODO intake, open and archived work items, and plan/build docs with deterministic indexes.
metadata	{"init":"bun ./skills/agent-protocol/scripts/init.ts","create":"bun ./skills/agent-protocol/scripts/create.ts","reindex":"bun ./skills/agent-protocol/scripts/reindex.ts","templates":"./skills/agent-protocol/assets","references":"./skills/agent-protocol/references"}

Agent Protocol

Coordinate work in repos that use .agentprotocol/. Keep work items self-contained and minimize follow-up questions.

Always load first

• Read .agentprotocol/README.md at the start of any session.
• If .agentprotocol/ is missing, offer to initialize with bun ./skills/agent-protocol/scripts/init.ts.

Core structure

• .agentprotocol/README.md: protocol contract and Active Work Index.
• .agentprotocol/TODO.md: intake queue.
• .agentprotocol/open/<ID>-<slug>/: active work items.
• .agentprotocol/archive/<ID>-<slug>/: completed or cancelled items (moved as a whole).

Workflow

1. Intake work in .agentprotocol/TODO.md.
2. Create a work item with create.ts (build-only by default; add --plan for plan + build).
3. Write or refine plan.md if needed; keep it flexible (PRDs, user stories, specs).
4. Execute from build.md with tasks, verification, and append-only log.
5. Archive by moving the whole directory to .agentprotocol/archive/.

Work selection

• If the user names a path or ID, use it.
• If not, suggest up to 3 candidates from the Active Work Index and TODO. The user chooses.
• Never auto-select.

plan.md

• Optional design surface. May include PRDs, user stories, acceptance criteria, constraints, and invariants.
• Frontmatter: id, title, status, created_at, updated_at, optional refs.
• status values: draft | ready | done | cancelled.
• ready means Open Questions is empty (or risks explicitly accepted).

build.md

• Execution surface with tasks, verification, and append-only log.
• May exist without a plan (ad-hoc).
• Frontmatter: id, status, created_at, updated_at, optional plan_id.
• status values: todo | in_progress | blocked | done | cancelled.
• If build/ exists, include a Build File Index table listing all build/*.md (sorted by path).
• build/*.md files are plain markdown by default (no required frontmatter).

Active Work Index

• .agentprotocol/README.md contains a markdown table of all open work item directories.
• Update with bun ./skills/agent-protocol/scripts/reindex.ts (deterministic; avoids manual edits).
• Use --next to include next-action extraction when desired.

IDs and timestamps

• ID is Crockford base32 encoding of UUIDv7 bytes.
• Uppercase, fixed 26 chars, left-padded with 0.
• Alphabet: 0123456789ABCDEFGHJKMNPQRSTVWXYZ.
• No zero padding in body identifiers (use US-1, not US-001).
• created_at / updated_at use RFC3339 with timezone (recommend UTC Z).

Archiving

• When a work item is done | cancelled, move the entire directory from open/ to archive/.
• Remove the row from the Active Work Index.

Migration

• For old context/ repos, follow references/migration.md.