agent-protocol

•

185393 months ago

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.

Quick Install

npxskills add majiayu000/claude-skill-registry--skill agent-protocol

Instructions

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

Intake work in .agentprotocol/TODO.md.
Create a work item with create.ts (build-only by default; add --plan for plan + build).
Write or refine plan.md if needed; keep it flexible (PRDs, user stories, specs).
Execute from build.md with tasks, verification, and append-only log.
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.

Loading…

Related Skills

skill-creator

Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.

367,360

coding-agent

Run Codex CLI, Claude Code, OpenCode, or Pi Coding Agent via background process for programmatic control.

359,326