firstmate — 한 명의 선장이 크루를 몰기 위한 에이전트 배포판

1. 출처와 신원

기계 검증 자료는 공개 evidence index와 delivery receipt에 함께 보존한다.

2. 읽기 전에

핵심 질문: 여러 코딩 에이전트를 직접 창 순회하며 관리하는 부담을, firstmate의 위임·감독 규약이 실제로 줄일 수 있는가?

멘탈 모델

firstmate는 새 모델이나 단일 실행 파일이 아니다. 리포지토리 안의 운영 계약, 셸 스크립트, 상태 파일, 하네스·백엔드 어댑터를 결합한 명령권 계층이다. captain은 first mate 한 명과 대화하고, 프로젝트 변경은 격리된 crewmate가 수행한다는 구분이 핵심이다.

먼저 알아야 할 것

• Git worktree: 워커 작업 공간의 격리 단위.
• agent harness: Claude Code 등 실제 에이전트 실행 표면.
• runtime backend: tmux 또는 문서화된 실험 백엔드.
• evidence kind: 프로젝트 주장, 정적 지지, 테스트 존재, 외부 확인을 실행 관측과 구분한다.

예상 소요

판정만 10분, 구현·위험까지 25분, 클레임과 발생 원장까지 40분.

점검 질문

1. 내 환경에 Git·인증된 GitHub CLI·하네스·백엔드·호환 셸이 이미 있는가?
2. 버전 릴리스가 없는 main 기반 채택을 허용할 수 있는가?
3. 실행 전 별도 격리 trial로 runtime reliability를 검증할 계획이 있는가?

3. 채택 판단

• 채택 후보: macOS/Linux, Git·Bash·GitHub CLI·에이전트 하네스·세션 백엔드에 익숙하고 여러 에이전트를 병렬 운영하는 개인.
• 보류 후보: SemVer 릴리스가 필수인 조직, 외부 toolchain을 줄여야 하는 환경, runtime 보증이 선행돼야 하는 중요 프로젝트.

4. 실제 구현

정적으로 지지된 경로

• bin/fm-spawn.sh: clean·distinct worktree와 안전한 base를 확인하고, 증명이 부족하면 launch를 거부한다.
• bin/fm-send.sh: durable steering inbox와 terminal typing을 구분하고, exact target을 요구하며 불확실한 전달을 맹목 재시도하지 않는다.
• bin/fm-watch.sh와 bin/fm-crew-state.sh: durable wake와 crew state를 파일 기반으로 물질화한다.
• bin/fm-control.sh: interrupt, exit, relaunch로 한정된 lifecycle control을 제공한다.
• bin/fm-teardown.sh: dirty 또는 landed proof가 부족한 작업의 제거를 거부하고 명시적 force 경로만 discard를 허용한다.
• bin/fm-arm-command-policy.mjs: 명령을 실행·확장하지 않는 좁은 정적 parser로 protected boundary의 pipeline, redirection, wrapper, substitution 같은 broad shell construct를 거부한다.

테스트와 CI의 의미

선택한 테스트에는 batch spawn, Herdr control smoke, fail-closed gate, 문서 audience, ignored configuration 경계가 포함된다. CI는 read-only contents permission으로 구성됐고 pinned commit의 push run 33084431817은 GitHub 메타데이터상 success다. 이는 test-present 및 external-confirmed 근거이지 이 문서가 실행한 시험은 아니다.

5. 아키텍처와 제어 흐름

1. captain이 하나의 first mate에게 목표를 전달한다.
2. first mate가 하네스와 런타임 백엔드를 선택하고, spawn 경로가 안전한 worktree 조건을 검사한다.
3. crewmate가 격리된 작업 공간에서 변경을 수행한다.
4. send·watch·crew-state 경로가 지시와 상태를 durable file boundary에 기록한다.
5. control은 허용된 lifecycle verb만 노출하고, teardown은 landed proof가 부족하면 멈춘다.
6. 검증·forge 결과가 갖춰진 뒤에만 결과가 captain-facing surface로 돌아온다는 것이 프로젝트의 운영 의도다.

설계상 중요한 점은 “agents own judgment, scripts own mechanics”다. 다만 실제 하네스·백엔드 조합에서 이 경계가 얼마나 안정적으로 유지되는지는 실행 review가 필요하다.

6. 첫 실행과 온보딩

요구 표면

• Git
• 정상 forge 작업을 위한 인증된 GitHub CLI
• 지원되는 agent harness
• tmux 같은 session/runtime backend 또는 문서화된 실험 백엔드
• Bash-compatible shell

프로젝트가 제시하는 시작 방식 not run

git clone https://github.com/kunchenguid/firstmate.git
cd firstmate
# 이 디렉터리에서 선택한 agent harness를 시작

루트 application manifest와 lockfile은 없다. plugin-local .opencode/plugins/package.json 42 bytes는 인벤토리에 있지만 실질 검토 대상으로 선택하지 않았다. 따라서 “앱 하나 설치”보다 “리포지토리와 외부 toolchain을 통합”하는 온보딩으로 보는 편이 정확하다.

이 문서는 clone, bootstrap, dependency install, import, build, test, run을 수행하지 않았다.

7. 권장 읽기 순서

1. README.md와 VISION.md — 제품 주장과 비목표를 파악하되 사실의 종점으로 쓰지 않는다.
2. AGENTS.md — authority와 운영 계약.
3. docs/architecture.md, docs/agent-control.md — 상태·감독·허용 control verb.
4. bin/fm-spawn.sh, fm-send.sh, fm-watch.sh — 실제 orchestration 경로.
5. bin/fm-control.sh, fm-teardown.sh — 운영·파괴 경계.
6. command-policy와 gate-refuse 계열 — fail-closed 보안 표면.
7. 선택 테스트와 CI workflow — 프로젝트가 무엇을 회귀로 정의하는지 확인.
8. docs/remote-secondmates.md — 원격 SSH·credential trust boundary.

8. 유지보수와 헬스

• 신선도: pinned HEAD는 관측일에 push돼 days_since_push=0.
• 릴리스: bounded response에서 releases 0, tags 0. 버전 채택 채널이 없다.
• pinned CI: default-branch commit의 push run은 success.
• 최근 20 runs: action_required 12, failure 4, success 3, in progress 1. action_required 대부분은 fork PR approval state라 default branch 파손 증거로 해석하지 않는다.
• 기여 집중: API 응답 34 accounts, top contributor 414회, 2위 13회, 3위 6회. maintenance concentration 신호이지 공식 bus-factor 측정은 아니다.
• community profile: health 57%; contributing, license, readme 존재; code of conduct, issue template, PR template은 없음.
• 인기도: stars 4,208, forks 1,399, subscribers 15. 인기도는 구현·보안·runtime 증거가 아니다.

9. 보안·개인정보·공급망

긍정적 정적 통제

• 모호하거나 지원되지 않는 lifecycle state의 refusal.
• landed-work proof가 부족한 teardown 거부.
• protected boundary에서 broad shell construct를 거부하는 정적 command parser.
• remote-secondmate 문서의 public-key authentication, strict host-key verification, no agent forwarding, host-local credentials 요구.

빈칸과 공급망 주의

• pinned tree에 SECURITY.md, CodeQL workflow, Dependabot configuration이 없다.
• published repository advisories는 0이지만, 이는 취약점 부재의 증거가 아니다.
• primary CI는 contents: read이지만 actions/checkout@v6, actions/upload-artifact@v4처럼 third-party action을 immutable commit SHA가 아닌 mutable major tag로 참조한다.
• 선택한 파일 안에서 telemetry collector는 찾지 못했으나, 선택 밖 부재를 증명하지 않는다.

Outbound·credential 경계

정상 forge 작업은 GitHub, 선택 설정은 Relay와 remote SSH host로 나갈 수 있다. 문서는 .env를 local·ignored로 취급하고 remote credential을 host-local로 유지한다.

10. 라이선스와 게시 조건

SPDX는 MIT, 저작권 고지는 Copyright (c) 2026 Kun Chen이다. 파생 분석 게시가 허용되며 저작권·허가 고지는 공개 evidence의 LICENSE.txt에 보존한다. 이 판단은 법률 자문이 아니다.

README의 미디어는 독립 라이선스·상표 상태·안전한 hotlinking 근거가 확인되지 않아 재게시하지 않는다. 비활성 의미 자리표시자만 남긴다.

11. 클레임 원장

행별 source SHA-256과 evidence kind는 공개 claim ledger에 보존한다.

12. 원본 링크·미디어 발생 원장

repository-root 계약상 README 완역 대신, README의 42개 authored occurrence를 stable ordinal과 semantic position으로 보존한다. 안전한 HTTP(S) 링크는 원래 의미 위치 묶음 아래 실제 링크로 남기며, 미디어 4개는 비활성 자리표시자로 둔다.

13. 수집 커버리지와 한계

• 완전한 recursive tree: 499 entries, 450 blobs, 13,712,152 total blob bytes, truncated=false.
• 실질 선택: 30 files, 17,854 lines, 970,046 bytes, dependency hops 1.
• GitHub REST 관측: 23 requests. 초기 repository metadata와 rate-limit preflight는 함께 시작됐고, 이후 획득은 직렬화했다. rate-limit response는 source artifact로 보존하지 않았다.
• 선택 밖 binary와 파일은 인벤토리만 했고 실질 검토하지 않았다.
• issue·PR health는 bounded latest-20 sample이며 전체 comment timeline으로 response time을 복원하지 않았다.
• dependency install, build, test, run, import, container, checkout, worktree, hooks, submodules, LFS, filters, textconv는 모두 0회다.
• bare partial object database에는 실행 가능한 working tree가 없었다.

따라서 implementation intent에 대한 근거는 있으나 runtime reliability는 알 수 없다. 실행 검증은 별도 권한과 격리된 trial이 필요하다.