benjinus/agent-collaboration-protocol

Agent Collaboration Protocol

직접 메시지를 주고받을 수 없는 에이전트들이 공유 폴더를 휴대용 조정 버스(portable coordination bus)로 사용할 수 있게 합니다. ACP는 파괴적(breaking) 프로토콜입니다. 느슨한 마크다운 대화가 아닌, 구조화된 이벤트와 준비 게이트(readiness gates)를 갖춘 상태 머신입니다.

호환 가능한 모든 에이전트는 Markdown과 JSON을 읽고, Markdown을 작성하며, JSONL 이벤트를 추가하고, 번들된 스크립트 동작을 실행하거나 정확히 재현할 수 있어야 합니다. Codex 스레드 API, Claude 특정 훅, OpenCode 전용 상태, Kiro 전용 메타데이터 또는 숨겨진 대화 메모리에 의존하여 정확성을 확보하지 마십시오.

필수 입력

시작하기 전에 다음을 요청하십시오:

• collaboration_folder: 절대 경로 또는 저장소 상대 경로의 공유 폴더 경로.
• objective: 협업이 결정하거나 생성해야 하는 목표.
• completion_gates: 협업을 종료하기 위한 구체적인 게이트.
• participants: 모든 참여자 ID (예: server, reader, reviewer, 또는 agent-a).
• participant_id: 현재 에이전트의 ID.

필수 입력이 누락된 경우, 파일을 생성하거나 이벤트를 작성하기 전에 먼저 요청하십시오. 완료 게이트를 임의로 만들지 마십시오.

파일

ACP 폴더는 다음 파일을 사용합니다:

• protocol.json: 목표, 참여자, 완료 게이트, 현재 단계, 제안 소유자, 대기 중인 참여자 및 타임스탬프.
• events.jsonl: 추가 전용 이벤트 로그. 각 줄은 하나의 간결한 JSON 객체입니다.
• proposal.md: 현재 제안만 포함.
• review.md: 구조화된 참여자 리뷰.
• decisions.md: 승인된 결정만 포함.
• readiness.md: 열린 질문 분류, 차단 요소, 연기된 비차단 항목 및 구현 준비 상태.
• conclusion.md: 최종 논의 결론. 진행 여부(proceed), 미진행(not proceed), 연기(defer), 또는 차단(blocked) 상태를 명시하고, 그 이유와 구현 방법(또는 불가능 이유), 그리고 다음 조치를 포함합니다.

state.log, discussion.md, 또는 opinions.md를 생성하거나 사용하지 마십시오. 이들은 프로토콜 파일이 아니며 완료 게이트나 지침에 포함되어서는 안 됩니다.

초기화

번들된 스크립트 사용을 권장합니다:

python3 <skill>/scripts/init_collaboration.py \
  --folder <collaboration_folder> \
  --participant <participant_id> \
  --participant <other_participant_id> \
  --objective "<objective>" \
  --completion "<completion gate>" \
  --completion "<another gate>"

--resume 옵션이 제공되지 않으면 초기화는 protocol.json이 이미 존재할 경우 실패합니다. 반복된 초기화는 추가 작업이 아닙니다.

이벤트

scripts/append_event.py를 사용하거나 그 동작을 정확히 재현하십시오. 런타임이 스크립트를 실행할 수 없는 경우가 아니라면 이벤트를 수동으로 작성하지 마십시오.

필수 이벤트 필드:

• seq: events.jsonl 내의 연속적인 정수.
• from: protocol.json에 나열된 참여자 ID.
• event: 허용된 이벤트 이름.
• at: ISO-8601 UTC 타임스탬프.
• summary: 하나의 짧은 문장.

권장 필드:

• doc: 협업 폴더 기준 상대 경로.
• reply_to: 이전 이벤트의 seq.

허용된 이벤트:

• initialized
• proposal_submitted
• review_submitted
• proposal_revised
• question_classified
• decision_proposed
• decision_accepted
• readiness_passed
• completed
• blocked

모든 응답은 이전 이벤트에 응답할 때 reply_to를 사용해야 합니다. reply_to는 이전에 존재하는 이벤트를 가리켜야 합니다. 이벤트 타임스탬프는 seq가 증가함에 따라 과거로 돌아가서는 안 됩니다. 실수가 발견되면 blocked 이벤트를 추가하거나 새로운 수정 이벤트를 추가하십시오. 이전 이벤트를 다시 작성하지 마십시오.

단계

에이전트는 protocol.json.currentPhase와 protocol.json.waitingFor에 따라 행동해야 합니다:

• drafting: 제안 소유자가 proposal.md를 업데이트한 후 proposal_submitted를 추가합니다.
• reviewing: waitingFor에 나열된 참여자만 review.md에 구조화된 리뷰를 추가한 후 review_submitted를 추가합니다.
• revising: 제안 소유자가 필요한 변경 사항을 처리하고 proposal_revised를 추가합니다.
• decision_review: 제안 소유자가 먼저 readiness.md의 모든 열린 질문을 분류하고 question_classified를 추가합니다. 그런 다음에만 waitingFor에 나열된 참여자가 decisions.md의 명시적 결정을 수락하고 decision_accepted를 추가합니다.
• readiness_check: 참여자가 모든 질문을 분류하고, 차단 요소를 해결하며, 준비 상태를 통과한 후 제안 소유자가 conclusion.md를 작성합니다.
• completed: 사용자가 명시적으로 새 라운드를 시작하지 않는 한 중지합니다.
• blocked: 차단 요소가 해결될 때까지 중지합니다.

completed는 이전에 readiness_passed 이벤트가 있는 경우에만 유효합니다. completed는 conclusion.md를 참조해야 합니다. decisions.md만으로 완료하지 마십시오. 결정은 입력이며, conclusion.md가 협업 목표에 대한 최종 답변입니다.

제안 소유자는 proposal_submitted 이후에 기다려야 합니다. 단계가 reviewing인 동안 소유자는 다음 작업을 폴링하거나 실제 타임아웃/차단 요소에 대해 blocked를 추가할 수 있지만 proposal.md, decisions.md, readiness.md 또는 protocol.json을 편집해서는 안 되며 필요한 리뷰가 제출될 때까지 진행 이벤트를 추가해서는 안 됩니다.

리뷰 형식

모든 review_submitted 이벤트에는 해당 이벤트의 seq와 일치하는 review.md 헤더가 있어야 합니다:

## <ISO-8601 UTC> - <participant_id> - seq <review_submitted event seq>

Context:
- Read `proposal.md` after event seq `<seq>`.

Position:
- ...

Concerns:
- ...

Required Changes:
- ...

Questions:
- ...

리뷰 헤더에 응답 대상 이벤트 seq를 사용하지 마십시오. 응답 대상 컨텍스트는 Context와 reply_to에 넣으십시오.

준비 게이트

readiness_passed 또는 completed 전에:

• 모든 열린 질문은 [resolved], [deferred_nonblocking], 또는 [blocking]으로 분류되어야 합니다.
• 모든 [deferred_nonblocking] 항목에는 Reason: ...이 포함되어야 합니다.
• [blocking] 또는 [unresolved] 항목이 남아 있어서는 안 됩니다.
• 최종 설계 체크리스트에는 Ready to implement가 포함되고 확인되어야 합니다.
• validate_collaboration.py가 통과해야 합니다.

준비 상태를 차단하는 항목은 decision_accepted도 방지합니다. 해결되지 않은 질문과 Reason: ...이 누락된 연기된 항목도 decision_accepted를 방지합니다.

최종 설계 문서는 다음을 분리해야 합니다:

• 승인된 결정(Accepted Decisions)
• 가정(Assumptions)
• 연기된 후속 조치(Deferred Follow-ups)
• 구현 차단 요소(Implementation Blockers)
• 구현 준비 완료(Ready to Implement)

최종 결론

completed 전에 conclusion.md를 로그가 아닌 결론 문서로 작성하십시오. 다음을 포함해야 합니다:

• 결정 결과(Decision Outcome): 정확히 [proceed], [do_not_proceed], 또는 [defer] 중 하나.
• 근거(Rationale).
• 승인된 결정(Accepted Decisions).
• 구현 접근 방식(Implementation Approach).
• 가정(Assumptions).
• 연기된 후속 조치(Deferred Follow-ups).
• 구현 차단 요소(Implementation Blockers).
• 다음 조치(Next Action).

[proceed]는 지금 구현을 시작해야 할 때, [do_not_proceed]는 기능이나 계획을 수행하지 말아야 할 때, [defer]는 구현 전에 후속 작업이 필요할 때 사용합니다. 협업이 차단된 동안 [blocked] 결과가 존재할 수 있지만 완료 가능한 상태는 아닙니다.

폴링 및 감시자

참여자는 단계가 completed, blocked 또는 명시적인 사용자/조정자 기한에 도달할 때까지 협업 루프를 유지해야 합니다. 유효한 이벤트 하나를 추가했다고 해서 중단하지 마십시오. 모든 작업 후에 protocol.json을 다시 읽고 다음 허용된 작업을 수행하거나 다음 이벤트를 기다리십시오.

런타임에 감시자(watcher)가 있는 경우, events.jsonl 또는 protocol.json이 변경될 때 참여자에게 알릴 수 있습니다. 감시자는 단순히 변경만 감지하고 분석이나 결정을 작성하지 않아야 합니다.

감시자가 없는 경우 다음을 사용하십시오:

python3 <skill>/scripts/next_action.py \
  --folder <collaboration_folder> \
  --participant <participant_id>

자율 참여자의 경우 차단 헬퍼를 선호합니다:

python3 <skill>/scripts/wait_for_turn.py \
  --folder <collaboration_folder> \
  --participant <participant_id>

wait_for_turn.py는 참여자가 waitingFor에 나열되거나 협업이 completed 또는 blocked 상태가 될 때 반환됩니다. 기본 30분 타임아웃이 있어 참여자 프로세스가 영구적으로 멈추는 것을 방지합니다. 외부 감독자가 취소를 담당하는 경우에만 --timeout 0을 사용하십시오. 반환 시 next_action.py를 검사하고, 자신의 차례라면 작업을 수행한 후 필수 이벤트를 추가하고 대기/작업 루프를 반복하십시오. "새 의견 확인"과 같은 수동 사용자 프롬프트는 의도된 협업 루프가 아닌 최후의 수단입니다.

참여자를 시작하는 조정자 프롬프트는 각 참여자에게 한 단계를 수행하고 종료하는 대신 이 루프를 실행하도록 요청해야 합니다. waitingFor에 나열되지 않은 참여자는 wait_for_turn.py에서 차단될 수 있지만 대기 중에는 공유 상태를 편집해서는 안 됩니다.

유효성 검증

실행:

python3 <skill>/scripts/validate_collaboration.py --folder <collaboration_folder>

유효성 검사기는 필수 파일, 사용되지 않는 파일의 부재, 이벤트 형태, seq 연속성, 타임스탬프 단조성, 단계 전환, waitingFor 소유권, reply_to, 리뷰 헤더 seq, 준비 분류, 결론 완전성 및 완료 순서를 확인합니다.

종료 코드:

• 0: 유효함.
• 1: 유효하지만 경고 있음.
• 2: 유효하지 않음.