이 워크플로우를 따르기 전에 런타임 어댑터를 읽으십시오. 해당 문서의 런타임 매핑은 모든 참조된 플레이북과 스크립트에 적용됩니다.
Pstack 페어
두 개의 에이전트가 하나의 Herdr 또는 Rex 세션, 하나의 리포지토리에서 작업합니다. 마스터는 판단을 담당하고 사이드킥은 작업 트리를 소유합니다. 두 에이전트 사이의 모든 메시지는 페어 스토어의 파일과 파일 이름을 지정하는 한 줄짜리 프롬프트로 구성됩니다. 터미널은 기록이 되지 않습니다. 대체 화면에서 작업하는 에이전트는 스크롤백을 남기지 않기 때문입니다.
사전 조건
- Herdr (
test "${HERDR_ENV:-}" = 1) 또는 Rex (REX_BLOCK설정) 내부에 있어야 합니다. 둘 다 아니라면 그렇게 말하고 중단하십시오. - 멀티플렉서의 스킬을 로드하여 창 및 에이전트 제어를 수행합니다: Herdr의
~/.agents/skills/herdr/SKILL.md(또는 해당 파일이 없을 때는herdr --skill), 또는 Rex의rex skill show. 이 스킬의 안전 규칙은 전체 과정에 적용됩니다. Rex에서는 Rex에서 실행하기를 읽으십시오. herdr또는rex, 그리고 Python 3.11 이상 (python3)이 PATH에 있어야 합니다.scripts/pair.sh help는 모든 스토어 및 채널 작업을 나열합니다. 페어를 위해 수동으로herdr또는rex를 호출하는 대신 이 명령어를 사용하십시오.- 마스터를 자동 모드로 시작하십시오. Devin은
--permission-mode dangerous로 권한을 우회하는 것이 기본값입니다. 다른 종류의 에이전트는 마스터의 모드를 상속받습니다.pair.sh permission은 감지된 마스터 모드를 출력합니다. 기본값을 재정의하려면--permission <mode>또는--뒤에 네이티브 권한 플래그를 사용하십시오.--permission auto는 Devin 스마트 모드를 선택합니다. 변환이 없는 종류의 에이전트는--뒤에 네이티브 플래그를 사용합니다.spawn은 또한 각 종류의 폴더 신뢰 프롬프트를 건너뜁니다. 이 프롬프트는 본 적 없는 폴더에서 에이전트가 응답하지 못하게 만듭니다. pi는--approve를, Devin은--respect-workspace-trust false를 사용합니다.--뒤의 신뢰 플래그는 이를 재정의합니다. Claude와 Codex는 본 적 없는 폴더를 신뢰하도록 요청합니다. 스폰된 Claude는 또한 MCP 서버 없이 시작됩니다 (--strict-mcp-config및 빈 구성 사용). 각 서버는 세션당 하나의 프로세스이기 때문입니다.--뒤의--mcp-config는 사용자의 구성을 유지합니다. 스폰은 이 대화를 거부하고 수행할 작업과 함께 중단됩니다: 해당 리포지토리에서 에이전트를 한 번 열고 신뢰하십시오.
역할
| 마스터 | 사이드킥 | |
|---|---|---|
| 소유 | 계획, 브리핑, 검토, 결정, 인간 | 작업 트리, 테스트, 진단, 증거 |
| pstack 실행 | poteto-mode 프레이밍, how, architect, 검토 스킬 | 각 브리핑이 지정하는 플레이북 및 그 todolist |
| 작성 | 페어 스토어만 | 브리핑의 Scope 내 파일, 진행 로그 및 보고서 |
| 의사소통 | 브리핑, 방향 조정, 검토, 상명 하달, 게이트 | 진행 라인, 보고서 |
역할을 선택하십시오. 마스터: references/master.md. 사이드킥: references/sidekick.md.
페어 스토어
${XDG_STATE_HOME:-$HOME/.local/state}/pstack/pair/<slug>/ 위치에 있으며, pair.sh init으로 생성됩니다. 파일당 하나의 작성자만 있습니다.
| 경로 | 작성자 | 내용 |
|---|---|---|
pair.json | pair.sh를 통한 마스터 | 에이전트 이름, 창 ID, cwd, git 루트, 사이드킥의 폴백 및 장애 조치, 창 배치 (분할 또는 탭) |
standing-orders.md | 마스터 | 모든 브리핑에 경로로 붙여넣는 번호가 매겨진 제약 조건 |
plans/NNN-<slug>.md | 마스터 | 계획 템플릿의 하나의 계획 라운드 |
briefs/NNN-<slug>.md | 마스터 | 브리핑 템플릿의 하나의 단위 |
progress/NNN-<slug>.md | pair.sh progress를 통한 사이드킥 | 완료된 각 단계 또는 접근 방식 변경당 하나의 타임스탬프가 있는 라인; 체크인은 마스터가 아직 보지 못한 라인만 표시 |
steers/NNN-<slug>-s<k>.md | 마스터 | 단위 NNN에 대한 중간 브리핑 방향 k, 방향 템플릿 참조; supersedes:는 답변하는 반대 방향을 지정 |
reports/NNN-<slug>-s<k>.md | 사이드킥 | 방향 k에 대한 반대 의견, 방향 응답 템플릿 참조 |
reports/NNN-<slug>.md | 사이드킥 | 브리핑 NNN에 대한 증거, 보고서 템플릿 참조, 또는 계획 NNN에 대한 동의/반대 응답, 계획 응답 템플릿 참조 |
reviews/NNN-<slug>.md | 마스터 | 보고서 NNN에 대한 평결, 검토 템플릿 참조; 계획에 대한 agreed는 해당 브리핑을 잠금 해제 |
scratch/<id> | pair.sh scratch를 통한 마스터 | 리포지토리 외부의 ${XDG_STATE_HOME:-~/.local/state}/pstack/scratch/ (PSTACK_SCRATCH_ROOT로 이동 가능)에 보관되며, 단위의 커밋에서 검사를 다시 실행하기 위한 임시 작업 트리에 대한 링크. Claude와 Codex는 호스트당 한 번씩 신뢰해야 함 (kitchen.py doctor가 확인). 검토 후 제거 |
gates.md | 마스터 | 인간을 위한 미해결 질문 |
decisions.tsv | pair.sh log를 통한 마스터 | 작업 증명 기록 |
status.md | pair.sh status | 파생된 표; 수동 편집 금지 |
queue | pair.sh queue 및 dispatch를 통한 마스터 | 다음 브리핑의 경로, 하나의 슬롯 |
steps/NNN-<slug>.tsv | pair.sh step을 통한 사이드킥 | 커밋된 각 단계당 한 행: 번호, 커밋, 시간, 해결하는 노트, 요약 |
notes/NNN-<slug>-n<k>.md | pair.sh new-note 및 note를 통한 마스터 | 단계 k까지의 단위 단계 검토, 노트 템플릿 참조: 차단 항목 및 후속 조치 |
followups.md | pair.sh note를 통한 마스터 | 모든 노트의 후속 조치, 추후 브리핑 또는 이슈를 위해 |
session-handoff.md | 마스터 | 간결한 복구 및 다음 작업 컨텍스트, 부트스트랩 시 읽음 |
sessions/ | pair.sh spawn / rotate | 이전 준비 보고서; 보존된 세션 내보내기 및 타이밍 증거 |
events.tsv | 모든 pair.sh 명령어 | 메시지, 보고서, 웨이크, 로그 항목당 한 행, pair.sh metrics가 읽음 |
NNN은 계획 또는 브리핑, 보고서, 검토에서 공유되는 0으로 채워진 시퀀스이므로 하나의 단위에 대한 파일이 함께 정렬됩니다.
메시지
| 프롬프트 텍스트 | 방향 | 발신자의 도우미 | 수신자의 동작 |
|---|---|---|---|
| bootstrap (스킬 이름과 스토어 지정) | 마스터 → 사이드킥 | pair.sh spawn | 부트스트랩 단계, reports/000-ready.md, READY 회신 |
pstack-pair PLAN <plan-path> | 마스터 → 사이드킥 | pair.sh discuss | 코드에서 계획 검증, 동의 또는 반대 응답 작성, 턴 종료 |
pstack-pair BRIEF <brief-path> | 마스터 → 사이드킥 | pair.sh dispatch | 브리핑 실행, 보고서 작성, pair.sh finish 실행, REPORT 라인으로 턴 종료 |
pstack-pair BRIEF <brief-path>, 대기 중 | 마스터 → 작업 중인 사이드킥 | pair.sh queue | 마스터가 새 세션 후 디스패치; pair.sh next는 거부 |
pstack-pair STEER <steer-path> | 마스터 → 작업 중인 사이드킥 또는 반대 의견으로 일시 중지된 사이드킥 | pair.sh steer | 도착 시, 도구 호출 사이에 읽기; 동의하고 계속하거나 증거와 함께 반대하고 턴 종료 |
pstack-pair REPORT <report-path> | 사이드킥 → 마스터 | pair.sh finish (또는 notify) | 보고서 읽기, 검토 |
pstack-pair STOP <store> | 마스터 → 사이드킥 | pair.sh stop | 안전하게 일시 중지, 중지 보고서 작성 |
마스터의 dispatch 및 wait는 사이드킥의 회신(메시지 이후 작성된 보고서 또는 blocked 사이드킥)이 도착하면 반환됩니다. 멀티플렉서만의 settle은 신뢰되지 않습니다. Devin 사이드킥은 프롬프트가 도착하고 단계 사이에 유휴 상태를 표시하며, 좁은 창에서는 전체 실행이 완료된 것으로 표시될 수 있으므로 settle은 창의 "esc to interrupt" 라인과 대조하여 확인됩니다. 보고서 없이 1분 동안 유지되는 settle은 report: missing으로 대기를 종료합니다. 또한 체크인 간격이 지나도 사이드킥이 계속 작업 중이면 보고서 경로 대신 체크인 요약을 출력하며 반환됩니다. wait는 디스패치된 브리핑의 보고서가 도착하는 즉시 반환되며, 사이드킥이 이미 대기 중인 브리핑을 가져간 경우에도 마찬가지입니다. running:은 현재 작업 중인 브리핑을 나타냅니다. notify는 마스터가 유휴 상태일 때만 마스터에게 프롬프트를 보내므로 대기 중인 마스터는 절대 중단되지 않습니다. 압축 후 수신한 메시지도 이 스킬과 읽을 파일을 지정하므로 스킬을 다시 로드하고 해당 파일부터 계속하십시오.
계획 우선
구현은 두 에이전트가 모두 동의한 계획에서만 시작됩니다. 마스터는 구현, 아키텍처 및 시스템 설계를 주도합니다. plans/NNN-<slug>.md를 선택한 설계, 검토한 대안 및 각각의 장단점과 함께 초안을 작성한 다음 pair.sh discuss로 보냅니다. 사이드킥은 이러한 트레이드오프에 대해 브레인스토밍하고, 모든 단계를 코드와 대조하여 확인한 후 증거와 함께 동의 또는 반대 의견을 제시합니다. 마스터는 새로운 계획 라운드에서 수정하거나 반대 의견에 답변합니다. 응답이 동의를 표시하고 마스터가 평결 agreed로 검토를 작성할 때까지 계속됩니다. pair.sh dispatch는 plan: 줄이 동의된 계획을 지정하지 않는 기능, 버그 수정, 리팩토링, 성능 문제 또는 pstack-tdd 브리핑을 거부합니다. 읽기 전용 및 포렌식 브리핑은 계획이 필요 없습니다. 버그의 진단 브리핑은 계획보다 먼저 실행되므로 계획은 런타임 증거에 기반합니다. 세 라운드 동안 합의에 도달하지 못하면 gates.md에 두 입장을 모두 기록하고 인간에게 게이트를 엽니다.
체크인 및 방향 조정
마스터는 페어링 드라이버처럼 주도합니다. 지속적으로가 아니라 일정한 간격으로 확인하고, 키 입력이 아닌 방향을 수정합니다.
- 사이드킥은 완료된 각 todolist 단계 및 접근 방식 변경당 한 줄을
pair.sh progress를 통해progress/NNN-<slug>.md에 추가합니다. Scope 외부에 쓰거나 계획에서 벗어나기 전에 먼저 해당 줄을 작성하므로 체크인에서 이를 포착할 수 있습니다. dispatch및wait는 사이드킥이 계속 작업 중일 때 체크인 간격(--every MIN, 기본 9분) 후에 반환됩니다. 경과 시간(timebox 대비), 아직 보지 못한 진행 라인, 수정된 파일 및 Scope 외부 파일, 디스패치 이후 커밋, 방향 조정 횟수 등의 요약이 함께 제공됩니다. 사이드킥이 브랜치를 전환하거나 리베이스하여 HEAD가 더 이상 디스패치 HEAD에서 내려오지 않는 경우, 디스패치 이후 만들어진 커밋만 수정된 것으로 간주됩니다. 이 요약이 보고서 사이에 마스터가 읽는 전부입니다. 마스터는 요약이 로그를STALE로 표시할 때만 창을 읽습니다.- 방향 조정(steer)은 마스터의 중간 브리핑 수정입니다.
pair.sh new-steer후pair.sh steer로 보냅니다. 사이드킥이 작업하는 동안 입력 큐에 도착합니다. 하네스는 도구 호출 사이에 이를 전달하며 사이드킥은 단계 끝이 아닌 그 즉시 조치를 취합니다. Devin 사이드킥은 다음pair.sh step,notes또는progress에서STEER:라인으로 받습니다. 큐에 있는 메시지를 Devin에게 전달하는 Enter 키가 실행 중인 명령을 취소하기 때문입니다.--interrupt는 기다릴 수 없는 방향의 경우 먼저 실행 중인 도구 호출을 취소합니다. 방향 조정은 다음을 전달합니다: 합의된 계획이 선택하지 않은 접근 방식, 범위 이탈, 건너뛸 단계, 곧 위반될 금지 라인 또는 인간의 소식. 검토에서 마지막에 잡을 수 있는 모든 것은 검토를 기다립니다. - 사이드킥은 계획과 마찬가지로 동의하거나 반대합니다. 동의: 적용, 진행 로그에 기록, 계속. 반대: 증거와 대안을 포함한 방향 응답 작성, 알림, 턴 종료. 마스터는 반대된 방향을 대체하는 (수정되거나 철회된) 방향으로 답변하고
pair.sh steer로 사이드킥을 재개합니다. 방향당 두 라운드; 결정권은 마스터에게 있으며, 지속적인 의견 불일치는 계획 라운드로 넘어갑니다. - 브리핑당 두 번의 새로운 방향 조정. 세 번째는 브리핑이 잘못되었음을 의미합니다: 단위를 중단하고 다시 브리핑하십시오.
모든 종류의 작업 세션
모든 종류의 사이드킥(Claude, Codex, Devin, pi, Prime, Muse)은 완료된 각 브리핑에 대해 새로운 대화를 사용합니다. 스폰, 큐, 로테이션 또는 스토리지 정리 전에 Devin 또는 Pi에 대해서는 Devin 세션 수명 주기를, Prime에 대해서는 Prime 어댑터를 읽으십시오. 부분적 또는 차단된 작업은 해당 세션에 남아 있습니다. 완료된 브리핑은 마스터가 디스패치할 큐를 남깁니다. dispatch 및 discuss는 먼저 사이드킥을 자체적으로 로테이션합니다(rotated: 출력에 표시). pair.sh rotate는 마스터가 수동으로 실행하기 위해 남아 있습니다. pstack 스토어는 세션 간에 유지됩니다.
Muse 코드
모든 역할에 --kind muse를 사용하십시오. 권한, 신뢰, 사전 점검 및 종료 처리에 대해서는 Muse 어댑터를 읽으십시오. Muse는 창당 하나의 대화를 유지하므로 브리핑마다 로테이션되지 않습니다.
Prime 에이전트
사이드킥에 --kind prime-agent를 사용하십시오. 네이티브 모델 인수, 사전 점검, 방향 조정, 정확한 데몬 세션 정리 및 제공자 장애 조치에 대해서는 Prime 에이전트 어댑터를 읽으십시오. Prime은 공유 스토어 프로토콜을 사용하며 각 완료된 브리핑 후 로테이션이 필요합니다.
Pi 사이드킥 및 폴백
Pi 사이드킥은 자체 이벤트를 통해 Herdr(그리고 pstack 확장을 통해 Rex)에 상태를 보고하고 실행 중인 명령을 취소하지 않고 방향 조정을 큐에 넣습니다. 모델이 실패할 수 있는 경로 뒤에 있는 경우 --fallback devin과 함께 스폰하십시오. spawn은 먼저 모델을 확인하고 pair.sh failover는 실행 중에 폴백으로 교체합니다. 스폰하기 전에 Pi 사이드킥 참조를 읽으십시오.
사이드킥을 바쁘게 유지하기
사이드킥은 크리티컬 패스입니다. 마스터는 보고서를 몇 분 안에 처리하지만 단위는 수십 분에서 몇 시간이 걸립니다. 세 가지 습관이 사이드킥이 마스터를 기다리지 않도록 합니다.
- 다음 브리핑을 큐에 넣으십시오. 단위가 실행되는 동안 마스터는 다음 브리핑을 초안하고
pair.sh queue로 보관합니다.done보고서 후 사이드킥은 새 세션을 시작하고 마스터는 해당 브리핑을 디스패치합니다.pair.sh next는 거부합니다. 큐에는 하나의 슬롯이 있으며 실행 중인 단위의 검토에 의존하지 않는 단위만 보관하므로revise는 큐에 있는 브리핑의 재작업이 아닌 후속 브리핑이 됩니다. - 커밋에서 검토하십시오. 쓰기를 수행하는 브리핑은
commit: yes를 말하며 보고서의head:는 해당 커밋을 지정합니다. 마스터는 사이드킥이 다음 단위에서 작업하는 동안git show로 읽고pair.sh scratch <store> NNN-<slug>-review --at <head>에서 검사를 다시 실행하며 공유 트리에서는 절대 실행하지 않습니다. - 재계획 대신 수정하십시오. 마스터가 채택한 반대 의견은
agreed검토에서 번호가 매겨진 수정 사항이 됩니다. 새로운 계획 라운드는 설계가 변경된 경우를 위한 것입니다.