Document the human-agent Project protocol

[ineedjet]

Summary

Document the reusable GitHub-native protocol for human-agent processes in more operational detail than the README overview.

Protocol to capture

• The issue is the durable work object and remains owned by its repository.
• A Project represents an action performed on issues, not a topic, methodology, repository, or agent identity.
• Project Status is the process state machine: queue, optional claimed/working state, human review, and accepted completion.
• The agent dequeues a bounded batch, reads the issue and relevant comment history, produces a review artifact, then moves the item to review.
• Acceptance advances the item; returning it to the queue requests rework. A comment is explicit feedback, while a silent return is still a rejection signal.
• Replacement proposals preserve and supersede previous proposals instead of deleting review history.
• Transitions are idempotent or compensate for partial side effects.
• One issue may participate in multiple Projects because each Project adds process-local state.
• Multiple workers require a claim or lease convention to prevent duplicate processing.

Scope guidance

A dedicated Project is justified when queue membership, process state, human validation, and repeated agent execution must be observable independently from issue state. Do not create a Project for one-off automation or passive grouping.

Acceptance criteria

• The protocol is documented in the repository.
• The document distinguishes process state from durable issue metadata.
• It defines rework, history preservation, idempotency, and multi-worker claiming.
• It includes one concrete state-machine example.
• It explains when not to use this pattern.

Reference process

The first validated process is Clarification:

Incoming -> Review -> Clarified
     ^         |
     +---------+  rework