team

team은 Gajae-Code의 tmux 기반 다중 워커 실행 모드입니다. 현재 tmux 리더 윈도우를 분할해 실제 gjc 워커 CLI 세션을 띄웁니다. 워커 조율에는 .gjc/state/team/ 아래의 상태 파일과 gjc team api interop 표면을 사용합니다.

이것은 선택적 실행 모드이며 필수 핸드오프가 아닙니다. 조율된 병렬 워커가 실제로 도움이 될 때만 사용하세요. 세션 안에서 끝나는 제한된 병렬 작업이라면 보통 네이티브 서브에이전트로 충분합니다.

team vs 네이티브 서브에이전트

네이티브 서브에이전트는 team 실행을 보완할 수 있지만, tmux team 런타임의 상태 기반 조율 계약을 대체하지는 못합니다.

호출

gjc team [N:agent-type] "<task description>"

N:agent-type은 워커 수와 공유 역할 프롬프트를 지정합니다. 단순 gjc team "task"는 기본값으로 executor 워커 3개를 띄웁니다. gjc team 1:executor "task"는 명시적 단일 워커 형식입니다. 워커 수는 최대 20개로 제한됩니다.

gjc team 2:executor "split implementation and verification for this bug fix"
gjc team 3:executor "analyze feature X and report flaws"
gjc team "debug flaky integration tests"

team은 연결된 tmux 리더 페인 안에서 띄워야 합니다. GJC App이나 tmux 밖의 평범한 세션이라면 먼저 셸에서 gjc CLI를 실행하세요.

전제 조건

tmux 밖에서는 non-dry-run 런치가 team 상태나 worktree를 만들기 전에 실패합니다.

런치 동작

non-dry-run 런치 시 gjc team은:

• 인자(N, agent-type, task)를 파싱하고 현재 tmux 리더 컨텍스트를 감지합니다.
• .gjc/state/team/<team>/ 아래에 team 상태를 초기화합니다 (config.json, manifest.v2.json, tasks/task-1.json, mailbox/worker-1.json).
• 현재 윈도우를 분할합니다. 워커 1은 리더 오른쪽에, 추가 워커는 오른쪽 열에 쌓이며 대략 50/50 레이아웃을 유지합니다.
• 각 워커를 GJC_TEAM_NAME, GJC_TEAM_WORKER_ID, GJC_TEAM_STATE_ROOT가 설정된 완전한 gjc 워커 CLI 세션으로 띄웁니다.
• 리더에게 제어를 돌려줍니다. 리더는 기존 왼쪽 페인에 그대로 머뭅니다.

워커는 team 상태 루트를 공유하는 전용 git worktree에서 돌 수 있습니다. 리더 모니터링 중 처리 방식:

• clean-ahead 워커 히스토리는 리더에 머지됩니다.
• 분기된 히스토리는 cherry-pick됩니다.
• 충돌은 중단·기록되어 리더 메일박스에 보고됩니다.

라이프사이클

gjc team status <team-name>
gjc team resume <team-name>
gjc team shutdown <team-name>

• status / resume — 스냅샷을 읽고 대기 중인 워커-worktree 통합을 적용하는 모니터 경로입니다. 태스크 카운트, 워커 상태, tmux 타깃/페인 증거, integration_by_worker를 반환합니다.
• shutdown — 기록된 워커 페인만 종료합니다(저장된 tmux 타깃에 여전히 속하고 리더 페인이 아님을 확인한 뒤). 워커를 stopped로 표시하고 태스크 상태에서 phase를 설정합니다: 모든 태스크 완료 시 complete, 실패/차단 태스크 존재 시 failed, 작업이 pending/in-progress로 남으면 cancelled. tmux 세션은 절대 죽이지 않으며 .gjc/state/team/<team>을 증거로 보존합니다.

머신 판독 interop

태스크 라이프사이클 작업에는 gjc team api를 사용합니다:

gjc team api claim-task --input '{"team_name":"my-team","worker_id":"worker-1"}' --json
gjc team api transition-task-status --input '{"team_name":"my-team","task_id":"task-1","to":"completed","worker_id":"worker-1","claim_token":"<claim-token>","evidence":"summary of completed work"}' --json

표준 워커 라이프사이클은 worker-startup-ack → claim-task → transition-task-status(claim token, 워커 id, 완료 증거 포함) → release-task-claim입니다. 전체 작업 목록은 gjc team api --help로 확인하세요.

dry-run 상태

gjc team ... --dry-run --json은 tmux 페인을 띄우지 않고 실제 런치와 동일한 머신 판독 상태 트리를 만듭니다. 생성된 상태는 일회성 스모크 테스트/리뷰 상태로 취급하세요 — .gjc/state/team 내용을 커밋하지 말고, 더 이상 필요 없으면 생성된 team 디렉터리를 삭제하세요.

환경 변수

워커 CLI 선택은 팀메이트 전용입니다. 허용 값은 auto 또는 gjc뿐입니다. codex, claude, gemini 같은 레거시/provider 값은 런치 전에 거부됩니다.

GJC_TEAM_WORKER_COMMAND="bun packages/coding-agent/src/cli.ts" gjc team executor "update docs and report"

전체 목록은 환경 변수를 보세요.

team과 ultragoal 함께 쓰기

team과 ultragoal은 잘 어울립니다. ultragoal은 리더 소유로 지속되고, team은 눈에 보이는 병렬 실행 레인을 제공합니다.

워커 역할 제약:

• 태스크와 검증 증거만 반환합니다.
• 목표 상태를 소유하지 않습니다.
• 워커 원장(ledger)을 쓰지 않습니다.
• gjc ultragoal checkpoint를 실행해서는 안 됩니다.

워커 태스크가 종결된 뒤 체크포인트 권한은 리더에게 남습니다. ultragoal은 team을 자동으로 띄우지 않습니다.