agi-connect/agent-collaboration-protocol

Agent Collaboration Protocol

ACP는 서로 직접 메시지를 주고받을 수 없는 에이전트들을 위한 공유 폴더 조정 프로토콜입니다. 이는 구조화된 JSONL 이벤트, 턴 소유권, 준비 게이트, 그리고 동결된 산출물을 갖춘 상태 머신입니다. 느슨한 마크다운 토론이 아닙니다.

호환되는 모든 에이전트는 마크다운/JSON을 읽고 쓸 수 있어야 하며, JSONL 이벤트를 추가할 수 있어야 하고, 번들된 스크립트 동작을 실행하거나 정확히 재현할 수 있어야 합니다. 프로토콜 정확성을 위해 숨겨진 스레드 상태, 공급업체별 API, 또는 대화 메모리에 의존하지 마십시오.

필수 입력

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

• collaboration_folder: 절대 경로 또는 리포지토리 기준 공유 폴더 경로.
• objective: 협업이 결정하거나 생산해야 하는 목표.
• objective_gates: 목표별 게이트. 프로토콜은 산출물 게이트를 자동으로 생성합니다.
• participants: 모든 참여자 ID (예: server, reader, reviewer, agent-a).
• participant_id: 현재 에이전트의 신원.
• primary_deliverable_type: adr, design-spec, implementation-plan, decision-memo, review-report, test-plan, custom 중 하나.
• primary_deliverable_file: 내장 유형의 경우 선택 사항, custom의 경우 필수. 마크다운이어야 합니다.
• primary_deliverable_checklist: custom의 경우 필수.
• deliverables_mode: 선택 사항, 기본값은 internal. external은 repoRoot가 필요합니다.
• deliverables_dir: 선택 사항, 기본값은 deliverables.

필수 입력이 누락된 경우, 파일을 생성하거나 이벤트를 작성하기 전에 물어보십시오. 목표 게이트를 직접 만들지 마십시오.

파일

ACP 스키마 v2 폴더는 다음 프로토콜 파일을 사용합니다:

• protocol.json: protocol: "acp", schemaVersion: 2, 목표, 참여자, 생성된 게이트 및 목표 게이트, 산출물 선언, 현재 단계, 제안 소유자, 대기 중인 참여자, 타임스탬프.
• events.jsonl: 추가 전용 이벤트 로그. 각 줄은 하나의 간결한 JSON 객체입니다.
• proposal.md: 현재 제안/변경 요약.
• review.md: 구조화된 참여자 리뷰.
• decisions.md: 안정적인 ID를 가진 간결한 수락된 결정 색인.
• readiness.md: 미해결 질문 분류, 목표 게이트, 생성된 산출물 게이트, 산출물 스냅샷, 차단 요소, 준비 결과.
• conclusion.md: 최종 프로토콜 영수증. 기본 산출물이 아닙니다.
• deliverables/: 실제 마크다운 산출물 및 선택적 첨부 파일.

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

산출물

ACP는 프로토콜 상태와 산출물 아티팩트를 분리합니다:

• 모든 완료 가능한 협업에는 선언된 기본 마크다운 산출물이 필요합니다.
• conclusion.md는 최종 영수증이며, 동결된 산출물과 준비 결과를 참조합니다.
• 내장 산출물 유형은 adr, design-spec, implementation-plan, decision-memo, review-report, test-plan입니다.
• custom은 명시적인 마크다운 파일과 체크리스트가 필요합니다.
• 지원 산출물은 마크다운입니다. 첨부 파일은 산출물 디렉토리 아래에 비마크다운 파일일 수 있습니다.
• internal 모드는 산출물을 협업 폴더 내부에 저장합니다.
• external 모드는 산출물을 리포지토리 루트 기준 디렉토리에 저장하고 이벤트, 준비, 결론에서 external:<file> 참조를 사용합니다.
• 산출물에는 Status: Draft, Status: In Review, 또는 Status: Frozen이 포함되어야 합니다.
• 제안 소유자는 deliverable_frozen으로 기본 산출물을 동결합니다. 동결은 엄격하며 동결 해제/재동결 경로가 없습니다.

초기화

번들 스크립트를 선호합니다:

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

외부 산출물의 경우:

python3 <skill>/scripts/init_collaboration.py \
  --folder <repo>/.acp/<run> \
  --participant <participant_id> \
  --participant <other_participant_id> \
  --objective "<objective>" \
  --primary-deliverable-type adr \
  --deliverables-mode external \
  --repo-root ../.. \
  --deliverables-dir docs/architecture \
  --completion "<objective gate>"

초기화 프로그램은 프로토콜 파일과 기본 산출물에 대한 템플릿을 생성합니다. --resume이 제공되지 않는 한 protocol.json이 이미 존재하면 실패합니다.

이벤트

scripts/append_event.py를 사용하거나 그 동작을 정확히 재현하십시오. 필수 이벤트 필드:

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

허용된 이벤트:

• initialized
• deliverable_drafted
• deliverable_revised
• deliverable_frozen
• proposal_submitted
• review_submitted
• proposal_revised
• question_classified
• decision_proposed
• decision_accepted
• readiness_passed
• completed
• blocked

initialized 이후의 모든 이벤트는 이전 이벤트를 가리키는 reply_to가 필요합니다. doc 참조는 내부 모드에서는 협업 폴더에 상대적이고, 외부 모드에서는 external:<file>입니다.

모든 deliverable_* 이벤트에는 다음이 필요합니다:

• doc: 해결된 산출물 참조.
• role: primary 또는 supporting.

deliverable_frozen은 또한 최상위 sha256 필드가 필요하며, 이는 참조된 파일의 64자 소문자 16진수 SHA-256입니다. 동결된 후에는 파일 내용이 해시와 일치해야 합니다.

단계

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

• drafting: 제안 소유자가 기본 산출물을 초안하고, deliverable_drafted를 추가하고, proposal.md를 업데이트한 다음 proposal_submitted를 추가합니다.
• reviewing: 지정된 리뷰어가 proposal.md와 기본 산출물을 모두 검토하고, 구조화된 리뷰를 review.md에 추가한 다음 review_submitted를 추가합니다.
• revising: 제안 소유자가 필요에 따라 proposal.md와 산출물을 업데이트하고, 산출물이 변경된 경우 deliverable_revised를 추가한 다음 proposal_revised를 추가합니다.
• decision_review: 제안 소유자가 readiness.md의 모든 미해결 질문을 분류하고 question_classified를 추가합니다. 그런 다음 참여자는 decisions.md의 명시적 항목을 decision_accepted로 수락합니다.
• readiness_check: 제안 소유자가 필요한 산출물을 동결하고, readiness.md에 스냅샷을 기록하고, 유효성 검사를 실행한 다음 readiness_passed를 추가합니다.
• completed: 사용자가 명시적으로 새 라운드를 시작하지 않는 한 중지합니다.
• blocked: 차단기가 해결되거나 새 라운드가 시작될 때까지 중지합니다.

completed는 readiness_passed 이후에만 유효하며 conclusion.md를 참조해야 합니다.

리뷰 형식

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

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

Context:
- Read `proposal.md` after event seq `<seq>`.
- Reviewed primary deliverable: `<resolved path>`
- Reviewed supporting deliverables: `<paths or none>`

Review Scope:
- Proposal coherence
- Primary deliverable completeness
- Accepted decision traceability
- Implementation readiness

Position:
- ...

Concerns:
- ...

Required Changes:
- ...

Questions:
- ...

결정

decisions.md는 수락된 결정 색인으로, 산출물이 아닙니다. 모든 수락된 결정은 안정적인 ID를 사용해야 합니다:

### D1. <short title>

- Decision: ...
- Rationale: ...
- Reflected in: `deliverables/design-spec.md#section`

ID는 순차적이어야 합니다 (D1, D2, ...). Reflected in:은 선언된 기본 또는 지원 산출물을 가리켜야 합니다.

준비 게이트

readiness_passed 또는 completed 전에:

• 모든 미해결 질문은 [resolved], [deferred_nonblocking], 또는 [blocking]입니다.
• 모든 [deferred_nonblocking] 항목에는 Reason: ...이 포함됩니다.
• [blocking] 또는 [unresolved] 항목이 남아 있지 않습니다.
• 목표 게이트가 확인됩니다.
• 생성된 산출물 게이트가 확인됩니다.
• 기본 산출물에 Status: Frozen이 있습니다.
• 기본 산출물 SHA-256 스냅샷이 기록됩니다.
• Ready to implement가 확인됩니다.
• validate_collaboration.py가 통과합니다.

차단 또는 미해결 준비 항목은 decision_accepted도 방지합니다.

최종 결론

completed 전에 최종 영수증으로 conclusion.md를 작성하십시오. 다음을 포함해야 합니다:

• Decision Outcome: [proceed], [do_not_proceed], [defer] 중 정확히 하나.
• Rationale.
• Deliverable Receipt: 기본 경로, 유형, SHA-256, 지원 산출물, 첨부 파일.
• Accepted Decisions Summary.
• Readiness Result.
• Assumptions.
• Deferred Follow-ups.
• Implementation Blockers.
• Next Action.

blocked는 단계/이벤트이지, 완료 가능한 결과가 아닙니다.

폴링 및 와처

참여자는 단계가 completed, blocked되거나 명시적 코디네이터 마감 시간에 도달할 때까지 협업 루프를 위해 활성 상태를 유지해야 합니다.

와처가 없는 경우 다음을 사용하십시오:

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을 사용하십시오.

유효성 검사

다음을 실행하십시오:

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

유효성 검사기는 필요한 프로토콜 파일, 스키마 v2 필드, 산출물 선언, 경로 안전성, 이벤트 형태, 산출물 역할 및 해시, 단계 전환, 리뷰 제목, 결정 ID, 준비 게이트, 동결된 산출물 콘텐츠, 결론 영수증, 완료 순서를 확인합니다.

종료 코드:

• 0: 유효성 검사 통과.
• 1: 유효성 검사 통과했으나 경고 있음.
• 2: 유효성 검사 실패.