GitHub 워크플로우 프로토콜
이 패키지의 모든 스킬이 공유합니다. 각 스킬은 이 파일을 가리킵니다. 실행당 한 번 이 파일을 읽고, 단계에서 지시할 때만 참조 파일을 엽니다. 실행할 스킬에 대해서는 pipeline-guide를 참조하세요.
계약 (Contracts)
모든 스킬은 ## Contract로 시작합니다. 이는 스킬이 함수로서 무엇인지 설명하는 하나의 YAML 블록입니다. 아직 계약이 없는 유틸리티 스킬은 검증기의 CONTRACT_PENDING에 나열되며, 해당 목록은 줄어들기만 합니다. Process는 방법을 설명합니다. 둘이 일치하지 않으면 계약이 우선하며, npm run validate는 가능한 부분을 확인합니다. 스킬은 계약에 대해 평가됩니다: 세계의 상태와 입력을 주고, 반환된 값과 기록된 내용을 확인합니다.
kind:item(하나의 이슈 또는 PR, 또는 하나의 발견 배치에서 작동),group(작업을 선택하고 아이템 스킬을 파견),sweep(아이템을 클레임하지 않고 여러 아이템의 상태를 복구:reconcile-github-issues만 해당),utility(다른 스킬이 Skill 도구를 통해 호출하고 문서(보고서, 결과 코멘트, 질문 라운드)를 반환하는 빌딩 블록) 또는reference(읽기만 하고 실행되지 않는 자료: 이 스킬,pipeline-guide,runner-prompts)step: Exploring, Triaging, Implementing, Shepherding 또는 Reviewing.item,group,sweep에 필수입니다.utility스킬은 어떤 단계에도 속하지 않으므로 생략할 수 있습니다.target: 스킬에 주어지는 대상:{param: issue|pr}(아이템 스킬의 경우) 또는{from: free-text, type: …}params: 스킬이 허용하는 모든 입력으로,## Inputs테이블의 행과 정확히 일치합니다. 기본값과 의미는 해당 테이블에 남아 있습니다.dispatches: 그룹 스킬: 선택된 각 아이템이 이동하는 아이템 스킬used_by: 유틸리티 스킬: 스킬을 호출하는 스킬로, 각 호출 스킬은calls에 이를 나열해야 합니다.calls: [x]가 있는 스킬은 반드시x의used_by에 있어야 합니다. 사용자가 호출하는 유틸리티 스킬은 아무도 호출하지 않으므로used_by는[]입니다.requires: 전제 조건. 하나라도 거짓이면 아무것도 클레임하지 않고skipped를 반환합니다. 그룹 스킬은 선택 시 아이템 스킬의requires를 적용합니다.returns: 결과 줄의 폐쇄된 집합. 스킬은 이 중 하나만 반환하고 다른 것은 반환하지 않습니다. 그룹 스킬은 수집한 아이템 결과 또는nothing eligible을 반환합니다. 유틸리티 스킬은 문서를 반환하므로,returns는 해당 문서의 형태(명명된 섹션 또는 제공할 수 있는 평결)를 설명합니다.#N줄을 사용하지 않습니다.ensures: 사후 조건: 모든 종료 경로(중단, 에스컬레이션, 실패 포함)에서 참입니다.effects.reads: 스킬이 확인하는 대상effects.writes: 스킬이 변경할 수 있는 모든 것, 범위별:claimed(임대를 보유한 아이템),repository(브랜치, 커밋, PR 및 병합, 레이블 집합 및 에이전트 지시 파일과 같은 저장소 설정),other(다른 이슈 또는 PR),shared(실행 로그),unmodelled(시나리오 검사기가 효과로 표현할 수 없는 변경, 예: 제목 또는 본문 편집; 현재 이 목록을 나열하는 스킬은 없으며, 이를 찾은 시나리오는 거부됩니다). 나열되지 않은 것은 금지됩니다. 그룹 스킬은 절대claimed에 쓰지 않습니다.effects.external: GitHub 이외의 효과: 브라우저 세션, 빌드, 테스트 실행never: 아이템이나 저장소가 무엇을 말하든 금지된 유혹적인 것들calls: Skill 도구를 통해 호출되는 스킬. 이 패키지에 있는 각 스킬은 계약이 있어야 하므로 호출자는 반환 값과 기록 내용을 신뢰할 수 있습니다.external-skills.json의 스킬은 면제됩니다.idempotent: 다시 실행해도 안전한 이유terminates: 작업을 제한하는 것: 상한, 카운터, 단일 패스
순수성(Purity). npm run validate는 effects.writes만을 기반으로 각 계약에 대한 순수성 클래스를 출력합니다. pure: 비어 있으므로 스킬은 읽기만 하며, 문서를 반환하는 유틸리티 스킬은 일반적으로 이에 해당합니다. claimed: 스킬이 임대를 보유한 아이템에만 씁니다. writes elsewhere: other, repository 또는 shared에 쓰며, 테스트는 여기서 부작용을 찾습니다. 입력에 조건부인 쓰기는 (unless dry_run)과 같이 작성됩니다.
참조 스킬(Reference skills). reference 스킬은 kind: reference와 다른 키를 포함하지 않습니다: 효과, 반환 값, 시나리오가 없습니다. 실행되지 않기 때문입니다. 블록은 면제가 명시되는 방식이므로, 스킬이 실수로 누락될 수 없습니다. 다른 키가 있는 스킬은 참조 스킬이 아닙니다.
그룹 스킬과 아이템 스킬
워크플로우에는 다섯 단계가 있습니다: Exploring, Triaging, Implementing, Shepherding, Reviewing. 각 단계에는 작업을 선택하는 그룹 스킬과 하나의 아이템에 대해 작업을 수행하는 아이템 스킬이 있습니다.
그룹 스킬은 후보를 찾고, 여기에 아이템 스킬의 계약 requires를 적용하고, 통과한 첫 번째 batch를 가져와(가장 오래된 순; 실패한 아이템은 배치에 포함되지 않음), 각각을 해당 URL로 아이템 스킬에 파견하고, 하나의 실행 로그 항목을 작성합니다. 그룹 스킬은 직접 아이템 작업을 수행하지 않습니다. 적격 항목 없음: nothing eligible을 기록하고 중지합니다. 작업을 절대 발명하지 마세요.
아이템 스킬은 정확히 하나의 이슈 또는 PR을 URL 또는 숫자로 받습니다 (N은 URL의 마지막 경로 세그먼트). 모든 아이템 스킬은 동일한 프레임을 가지며, 자체 Process가 중간을 채웁니다:
- 적격성(Eligibility). 계약의
requires를 직접 확인하여 직접 호출 또는 이중 파견이 안전하도록 합니다.agent:log또는agent:difficulty레이블이 있는 이슈는 부기(bookkeeping)용이며, 어떤 단계에서도 적격하지 않습니다. 적격하지 않으면 아무것도 클레임하지 않고#N skipped: <reason>을 반환합니다. 스킬은 클레임하기 전에 읽을 수 있는 모든 것을 확인하므로, 대기만 가능한 아이템은 임대 코멘트 없이 건너뜁니다. - 클레임(Claim).
claim N issue|pr LABEL STEP TTL(단계의 임대 TTL).lease_held가true이면 이 단계를 건너뜁니다: 호출자가 이미 임대를 보유하고 있습니다.failures N STEP이max_item_failures이상이면references/escalate.md를 따르고 중지합니다. - 저장소의 자체 규칙 읽기.
references/client-guidance.md: 클라이언트의AGENTS.md및 기타 에이전트 관련 파일, 아이템 레이블의 설명. 이는 이 패키지의 기본값(Trust 규칙 또는 Never 목록은 제외)보다 우선합니다. - 작업(Work). 스킬 자체 단계.
- 출력 상태 작성 후 해제(Release) (
release N issue|pr LABEL). 모든 종료 경로(성공, 중단, 에스컬레이션, 실패)에서 수행합니다.lease_held가true이면 해제하지 않음: 호출자가 수행합니다. - 실패(Failure). 단계가 실패하면 상태 레이블을 그대로 두고,
fail_item N issue|pr STEP "<reason>"을 실행하고, 해제하고,#N failed: <reason>을 반환합니다. - 결과(Result). 한 줄이며, 계약의
returns에 있는 줄 중 하나만:#N <outcome>,#N skipped: <reason>,#N noop: <reason>또는#N failed: <reason>.skipped는 아무것도 클레임되지 않고 기록되지 않았음을 의미합니다.noop는 아이템이 클레임되었지만 할 일이 없어 해제되었음을 의미하며, 임대 코멘트는 남아 있습니다. 스킬이 아이템에 수행한 다른 모든 작업에는 자체 결과 줄이 있습니다. 예:#31 ready-for-agent,#35 skipped: leased,#44 failed: could not read ADR link (404). 그룹 스킬은 파견한 아이템의 결과를 기록합니다. 아이템 스킬은write_log가true(기본값)인 경우에만 자체 실행 로그 항목(references/log.md)을 작성합니다. 그룹 스킬은 파견 시write_log를false로 설정합니다.
파견(Dispatching). 아이템 스킬의 이름으로 Skill 도구를 호출하고 세 가지를 제공합니다: 아이템의 URL, write_log=false(그룹이 로그 항목을 작성함), 그리고 이 실행의 모든 키-값 입력 중 아이템 스킬이 계약의 params에 나열한 것 (예: runner, unattended, trusted_authors, repo_guidance, pr_base_branch 및 임대 TTL). 하위 에이전트는 이 실행의 입력을 전혀 받지 않으므로, 제공되지 않은 것은 기본값으로 대체됩니다. 실행기가 하위 에이전트를 시작할 수 있으면 각 아이템을 자체 하위 에이전트로 실행하여 컨텍스트를 작게 유지하고 하나의 실패한 아이템이 나머지에 영향을 미치지 않도록 합니다. 그렇지 않으면 아이템을 하나씩 순차적으로 실행합니다. 어느 쪽이든 각 아이템의 결과를 수집합니다.
단계는 독립적입니다. 다른 단계가 실행되었거나, 실행될 것이라고 가정하지 마세요.
다른 스킬 호출
이 패키지의 스킬은 Skill 도구를 통해 서로를 호출합니다: "Skill 도구를 호출하고" 스킬 이름을 전달합니다. 다른 스킬로의 경로를 따르지 마세요: 스킬이 어디에 있는지는 패키지 설치 방법에 따라 다릅니다. 스킬의 자체 파일(references/, scripts/)은 SKILL.md가 있는 디렉토리를 기준으로 읽습니다. 다른 스킬에서 이 스킬의 파일을 열려면 Skill 도구가 스킬을 찾은 것과 같은 방식으로 이 디렉토리를 찾으세요. 실행기가 스킬을 로드한 위치를 알려주지 않으면 agent-workflow-protocol이라는 이름의 스킬 디렉토리를 찾으세요. 실행기에 Skill 도구가 없으면 해당 이름의 SKILL.md를 찾아 작성된 대로 따르세요.
두 스킬은 이 패키지의 일부가 아니며 함께 설치해야 합니다. 둘 다 mattpocock/skills에서 제공되며, external-skills.json에 고정되어 있습니다:
tdd:implement-github-issue에서 테스트 우선 개발에 사용됩니다. 누락된 경우 어쨌든 테스트 우선 개발을 수행하고 스킬을 로드할 수 없다고 말하세요.code-review:implement-github-issue및review-github-pr에서 사용됩니다. 저장소에 같은 이름의 자체 스킬이 있으면 해당 스킬이 사용됩니다. 설치된 것이 없으면 직접 diff를 검토하여 정확성, 회귀 및 누락된 테스트를 확인하세요.
스킬이 입력을 받는 방법
모든 스킬은 ## Inputs 섹션에 입력을 나열합니다. 두 형식이 허용되며 한 번의 호출에서 혼합될 수 있습니다:
- 키-값 쌍(Key-value pairs).
key=value자체 줄에, 예:issue=123또는app_url=https://staging.example.com. 이렇게 주어진 키는 해당 스킬의 기본값을 재정의합니다. - 자유 텍스트(Free text). 그 외의 모든 것. 각 스킬은 자체 자유 텍스트에서 무엇을 읽을지 명시합니다:
explore-github-repo는 첫 번째 URL을 가져오고, 아이템 스킬은 첫 번째 숫자 또는 URL을 가져오는 식입니다.
동일한 것을 가리키는 키-값 쌍과 자유 텍스트는 쌍으로 해결됩니다. 스킬이 나열하지 않은 입력은 무시되며 오류가 아닙니다.
공통 입력(Common inputs). 모든 파이프라인 스킬은 자체 Inputs 테이블에 runner와 unattended를 나열하고, 마커를 읽는 모든 스킬은 trusted_authors를 나열합니다. 이들은 모든 곳에서 동일한 의미를 갖습니다: runner는 실행 ID 및 실행 로그에 기록되는 이름입니다. unattended는 사람이 있는지 여부를 나타냅니다 (무인 실행(Unattended runs)). trusted_authors는 Trust를 확장합니다. 실행 로그 항목을 작성하는 모든 파이프라인 스킬은 log_window_days도 나열하므로 모든 단계가 로그 이슈 회전 시점에 동의합니다.
기간(Durations) (lease_ttl_*)은 1 hour, 3 hours, 30m, 2d 또는 ISO 8601 (PT1H) 형식을 사용합니다.
이름이 변경된 입력(Renamed inputs). groom_batch는 이제 triage_batch, issues_per_run은 explore_batch, log_lookback_days는 log_window_days입니다. 이전 이름은 새 이름이 설정되지 않은 경우에도 여전히 읽히며, 다음 주요 버전에서 제거될 예정입니다.
기본값(Defaults)
설정 파일은 없습니다. 모든 기본값은 여기와 이를 사용하는 각 스킬의 Inputs 섹션에 명시되어 있으며, scripts/lib.sh에 구현되어 있습니다. npm run validate는 세 가지가 일치하는지 확인하며, 여기에는 어떤 스킬이 어떤 입력을 사용하는지도 포함됩니다. 실행당 키-값 쌍으로 재정의할 수 있습니다. 값을 생략하면 스킬은 기본값으로 대체되므로, 포트, 호스트, 경로 또는 명령이 가정되지 않습니다.
| 이름 | 기본값 | 사용 위치 |
|---|---|---|
app_url | (없음) | explore-github-repo, setup-github-agent-workflow |
explore_batch | 5 | explore-github-repo |
log_window_days | 14 | explore-github-repo, triage-github-issues, triage-github-issue, implement-github-issues, implement-github-issue, shepherd-github-prs, shepherd-github-pr, review-github-prs, review-github-pr, reconcile-github-issues |
dedupe_closed_days | 30 | file-github-issues, triage-github-issue |
pr_base_branch | main | implement-github-issue, review-github-pr, setup-github-agent-workflow |
merge_method | squash | review-github-pr, setup-github-agent-workflow |
human_reviewer | (없음) | shepherd-github-pr, review-github-pr, setup-github-agent-workflow |
build_cmd | (없음) | implement-github-issue, setup-github-agent-workflow |
git_hooks_path | (없음) | implement-github-issue, shepherd-github-pr, review-github-pr, setup-github-agent-workflow |
repo_guidance | AGENTS.md | file-github-issues, triage-github-issues, triage-github-issue, implement-github-issue, shepherd-github-pr, review-github-pr, reconcile-github-issues, setup-github-agent-workflow |
lease_ttl_triage | 1 hour | triage-github-issue |
lease_ttl_implement | 3 hours | implement-github-issue |
lease_ttl_pr | 1 hour | shepherd-github-pr, review-github-pr |
ready_lane_ttl | 2 hours | shepherd-github-pr |
human_merge_paths | (없음) | review-github-pr, setup-github-agent-workflow |
triage_batch | 5 | triage-github-issues |
implement_batch | 1 | implement-github-issues |
shepherd_batch | 3 | shepherd-github-prs |
review_batch | 3 | review-github-prs |
max_shepherd_attempts | 3 | shepherd-github-pr |
max_review_rounds | 3 | review-github-pr |
max_item_failures | 3 | triage-github-issue, implement-github-issue, shepherd-github-pr, review-github-pr |
runner | unknown | explore-github-repo, triage-github-issues, triage-github-issue, implement-github-issues, implement-github-issue, shepherd-github-prs, shepherd-github-pr, review-github-prs, review-github-pr, reconcile-github-issues |
unattended | true | explore-github-repo, file-github-issues, triage-github-issues, triage-github-issue, implement-github-issues, implement-github-issue, shepherd-github-prs, shepherd-github-pr, review-github-prs, review-github-pr, reconcile-github-issues |
trusted_authors | (없음) | triage-github-issues, triage-github-issue, implement-github-issues, implement-github-issue, shepherd-github-prs, shepherd-github-pr, review-github-prs, review-github-pr, reconcile-github-issues, setup-github-agent-workflow |
write_log | true | triage-github-iss |
(원문이 잘려서 일부 내용이 누락되었습니다.)
신뢰(Trust)
trusted_authors는 신뢰된 작성자 목록입니다. 스킬이 마커(markers.md)를 처리할 때, 목록에 없는 작성자가 단계 마커를 설정하려고 하면 무시됩니다. trusted_authors의 작성자 목록 외에도, 저장소의 AGENTS.md에 나열된 모든 에이전트는 암묵적으로 신뢰됩니다. references/client-guidance.md를 참조하세요.
마커(Markers)
각 단계의 아이템 스킬은 상태 추적을 위해 마커(레이블)를 사용합니다. 마커의 전체 목록과 의미는 references/markers.md에 정의되어 있습니다. 각 스킬은 작업을 시작할 때 적절한 단계 마커를 설정하고, 완료 시 마커를 업데이트합니다.
임대(Leases)
임대 메커니즘은 여러 에이전트가 동일한 아이템에서 동시에 작업하는 것을 방지합니다. 아이템 스킬이 작업을 시작할 때 임대를 걸고(claim), 작업이 완료되면 해제(release)합니다. 임대에는 TTL(Time-To-Live)이 있어 설정된 시간이 지나면 자동으로 만료됩니다. 자세한 내용은 references/leases.md를 참조하세요.
에스컬레이션(Escalation)
아이템이 반복적으로 실패하거나 특정 조건을 충족하면 에스컬레이션됩니다. 에스컬레이션 프로세스는 references/escalate.md에 자세히 설명되어 있습니다.
핸드오프(Handoffs)
한 단계에서 다음 단계로 작업이 전달될 때 핸드오프가 발생합니다. 핸드오프 메커니즘은 references/handoffs.md에 정의되어 있습니다.
실행 로그(Run Log)
모든 실행 단계는 중앙 실행 로그에 기록됩니다. 로그의 형식과 위치는 references/log.md에 정의되어 있습니다.
무인 실행(Unattended Runs)
unattended 입력이 true(기본값)이면 에이전트는 인간의 개입 없이 자동으로 실행됩니다. false이면 에이전트는 결정적인 지점에서 인간의 승인을 기다립니다. 자세한 내용은 references/unattended.md를 참조하세요.
셸 없이 실행(Running Without a Shell)
일부 실행 환경에서는 셸이 제공되지 않을 수 있습니다. 이러한 환경에서 스킬이 어떻게 작동하는지는 references/no-shell.md에 설명되어 있습니다.
레이블(Usage)
이 패키지의 스킬은 GitHub 레이블을 사용하여 이슈와 PR의 상태를 추적합니다. 레이블의 전체 목록과 사용법은 references/labels.md에 정의되어 있습니다.
클라이언트 지침(Client Guidance)
클라이언트 저장소는 AGENTS.md 파일이나 저장소 설정을 통해 에이전트에 대한 추가 지침을 제공할 수 있습니다. 이 지침은 references/client-guidance.md에 설명된 대로 처리됩니다.
파이프라인 가이드(Pipeline Guide)
전체 파이프라인의 개요와 각 단계에서 실행할 스킬은 pipeline-guide 참조 파일에 설명되어 있습니다.
검증(Validation)
npm run validate 명령을 사용하여 모든 스킬 계약, 입력, 기본값의 일관성을 확인할 수 있습니다. 이 검증은 계약, Inputs 섹션, scripts/lib.sh의 기본값이 일치하는지 확인합니다.
외부 스킬(External Skills)
external-skills.json 파일은 이 패키지와 함께 설치해야 하는 외부 스킬을 고정합니다. 현재 고정된 외부 스킬은 tdd와 code-review입니다.