gremlins

# Gremlins Gremlins는 백그라운드 코딩 에이전트(이른바 "gremlins")를 실행하여 전체 소프트웨어 개발 주기(plan → implement → review-code → address-code)를 자율적으로 수행하는 Rust CLI 도구입니다. 목표나 GitHub 이슈가 주어지면 gremlin은 무인으로 엔드투엔드 실행되며, 사용자별 상태 디렉터리에 아티팩트를 기록하고 선택적으로 풀 리퀘스트를 엽니다. 플릿 관리자는 실행 중, 중단된, 완료된 gremlin을 추적하며 stop, land, close 같은 작업을 제공합니다. **상태:** 완전히 새롭고 활발히 개발 중입니다. 거친 부분, 스트림 타임아웃, 병렬 gremlin으로 인한 간헐적 병합 충돌을 예상하세요. ## 주요 기능 - **자율 파이프라인:** 사람의 개입 없이 plan, implement, review, address-code 단계를 실행합니다. - **플릿 관리:** CLI 하위 명령으로 gremlin을 추적, 중지, 랜딩, 닫기, 정리합니다. - **다중 저장소 지원:** 서로 다른 저장소에서 gremlin을 실행하며, 상태는 gremlin별로 격리됩니다. - **큐 시스템:** 대기 중인 gremlin 실행을 추가, 목록화, 실행, 재큐잉, 비웁니다. - **병렬 실행:** fan-out/fan-in 의미론으로 여러 review 또는 다른 단계를 동시에 실행합니다. - **아티팩트 바인딩:** URI(file, git, opaque)와 보간을 통해 단계 간에 데이터를 전달합니다. - **사용자 정의 가능한 정의:** 재사용 가능한 패턴, 프롬프트, 클라이언트 재정의가 있는 YAML 기반 단계 정의. - **GitHub 통합:** `gh` CLI를 통해 PR 열기, Copilot 리뷰 요청, CI 검사 대기, 병합을 수행합니다. ## CLI 하위 명령 - `launch <name>` — 정의 이름으로 백그라운드 gremlin을 시작합니다. - `resume` — 기록된 단계에서 기존 gremlin을 다시 생성합니다. - `stop` — 실행 중인 gremlin에 SIGTERM을 보냅니다. - `land` — 완료된 gremlin을 현재 브랜치에 랜딩합니다. - `rm` — gremlin의 상태 디렉터리와 워크트리를 삭제합니다. - `close` — gremlin을 닫힘으로 표시합니다. - `log` — gremlin의 로그 파일을 tail합니다. - `ack` / `skip` — 사람 입력을 기다리는 gremlin을 확인 또는 건너뜁니다. - `queue` — 실행 큐를 관리합니다(add, list, run, requeue, clear, set-state, stop). - `prompt-for-assistant` — 어시스턴트 설정 프롬프트를 출력합니다. - `artifacts` — 아티팩트 키와 바인딩을 검사합니다. - `clean` — 완료된 gremlin 상태 디렉터리를 정리합니다. ## 구성 Gremlins는 단계가 있는 YAML 정의를 사용합니다. 주요 구성 요소는 다음과 같습니다. - **`default_client`:** 필수 `provider:model` 문자열(예: `xai:grok-4`). - **`base_ref`:** 워크트리를 분기할 Git ref(기본값 `current`). - **`github_integration`:** `gh` CLI 통합을 활성화합니다. - **`bootstrap`:** CLI 소스 플래그, 실행 명령, 워크트리별 명령, 아티팩트 바인딩. - **`prompts` / `prompt_dir`:** 이름이 지정된 프롬프트 맵과 프롬프트 해석용 디렉터리. - **`stage-definitions`:** 재사용 가능한 이름이 지정된 단계 패턴. - **`land`:** 랜딩용 사용자 정의 exec 단계(예: `gh pr merge`). - **`stages`:** 단계 또는 병렬 그룹의 순서 있는 목록. ### 단계 유형 **프리미티브:** `agent`, `exec`, `loop`, `parallel`, `sequence`. **레시피:** `plan`, `plan-gh`, `implement`, `verify`, `github-open-pr`, `github-push-to-pr-branch`, `github-request-copilot-review`, `github-wait-copilot`, `github-wait-ci` 같은 미리 정의된 YAML 단계. ### 병렬 그룹 `type: parallel`과 `body:` 목록으로 형제 단계를 동시에 실행합니다. `max_concurrent`, `cancel_on_error`, `error_policy`(any/all)를 지원합니다. ### 아티팩트 바인딩 단계는 URI를 통해 아티팩트를 바인딩하고 보간할 수 있습니다: - `file://session/<name>` — 세션 아티팩트 파일. - `git://ref/<name>` — Git ref 이름. - `git://commit/<sha>` — 커밋 SHA. - `git://range/<base>..<head>` — 커밋 범위/로그. - `opaque://pr/<n>` — 불투명 PR 식별자. ## 설치 `gh`(GitHub CLI)와 `git`이 필요합니다. `cargo build`로 빌드합니다. Make 대상에는 `test`, `rust-test`, `rust-fmt`, `rust-fmt-check`, `rust-clippy`, `check`가 있습니다. ## 예시 ```sh gremlins launch local # 번들된 local.yaml gremlins launch gh # 번들된 gh.yaml gremlins launch gh --plan '#42' --wait ``` 프로젝트 로컬 정의는 `.gremlins/<name>.yaml`을 통해 번들된 정의를 재정의할 수 있습니다. ## 사용 사례 - GitHub 이슈로부터 일상적인 코드 변경 자동화. - 서로 다른 모델이나 초점으로 병렬 코드 리뷰 실행. - 여러 저장소에 걸쳐 여러 자율 코딩 에이전트 관리. - CI/CD 및 GitHub 워크플로(PR 생성, Copilot 리뷰, CI 검사)와 통합.