pipeline-claude

파이프라인 실행

파이프라인 실행을 시작하거나 재개합니다. $1은 실행할 PIPELINE입니다 — ./.pipeline/ 아래의 해당 폴더를 가리킵니다. (v1 파이프라인은 반복 파일 경로로 이름이 지정될 수도 있습니다; 사전 조건 참조)

수행할 작업

당신은 슈퍼바이저로서 메인 세션(depth 0)에서 실행됩니다. 직접 반복을 수행하지 않습니다. 대신 단일 pipeline-manager 서브에이전트(depth 1)를 생성하여 전체 체인을 구동합니다 — 각 반복마다 새로운 step-executor를 생성하고 단계 사이에 pipeline-improver / pipeline-script-creator를 실행합니다 (이를 구동하는 pipeline next CLI는 반복당 UI 이벤트를 자동으로 내보내고 외부 워크트리 훅을 직접 실행합니다) — 그리고 실행이 완료되거나, 중단되거나, 범위를 벗어난 차단(blocker)에 도달하면 구조화된 보고서를 반환합니다.

당신은 depth 0에 머무릅니다. 세 가지 작업이 메인 세션에 있어야 하고 서브에이전트가 수행할 수 없기 때문입니다: (a) 실행의 liveness lockfile에 대한 안정적인 pid 소유, (b) 외부 조건(병합될 차단 PR)을 몇 시간 동안 기다렸다가 재개, (c) 최종적으로 결과를 사람에게 전달. 따라서 당신의 작업은: 실행 ID 생성(또는 --resume 시 기존 ID 재진입 — "재개 절차" 참조), UI 추적 설정, 매니저 생성, 그리고 그 보고서에 따라 조치 — 중첩 차단(blocker) 폴링-대기 실행 및 매니저 재호출을 통한 재개 포함.

중요 — 토큰 규율: 거의 읽지 않음

이 스킬은 슈퍼바이저이지, 읽기 담당자가 아닙니다. 모든 반복 파일은 각자의 새로운 컨텍스트에서 step-executor에 의해 읽힙니다; 단계별 모델 결정은 pipeline-manager 내부에서 발생합니다.

• 절대 Read로 반복 파일(steps/**/*.md)을 읽지 마십시오. 전면부(frontmatter)도 접근하지 않습니다. 매니저가 단계별 모델을 결정합니다; 당신은 파이프라인 수준 기본값만 전달합니다.
• PIPELINE.md는 전면부만 (limit: 50) 읽습니다, 체인 시작 시 한 번, model: 필드를 추출하여 pipeline_default_model로 사용하고 그 외에는 아무것도 읽지 않습니다. 그 내용을 매니저에게 전달하지 마십시오. --resume 시에는 이 읽기를 완전히 건너뜁니다 — pipeline_default_model은 기존 실행의 유지된 next.json.default_model에서 가져옵니다 ("재개 절차" 참조). 이는 재개 시 이미 필요한 next.json 읽기 외에 추가적인 manifest 읽기를 방지합니다.
• 전체를 Read할 수 있는 유일한 파일은 중첩 차단(blocker) 흐름에서 직접 작성하는 파일(이슈 본문, 부분 작업 메모)과, --resume 시에 작은 .runtime/*/next.json 오케스트레이션 커서 파일입니다 — 절대 반복 파일이나 PIPELINE.md 본문은 아닙니다.

실행기 선택 (실험적)

네 가지 모드가 있으며, 모든 모드에서 pipeline next가 다음에 실행할 것을 결정합니다 (E1) — 이를 호출하는 루프가 아닙니다. 모드 간 차이는 루프가 어디에 위치하는가와 한 단계를 무엇이 실행하는가에만 있습니다:

모드	루프 위치	단계 실행 주체
session	이 메인 세션	Agent 도구, 세션 내
manager (기본값)	pipeline-manager 서브에이전트	Agent 도구, 세션 내
driver	이 플러그인이 소유한 프로세스, 루프에 모델 없음 (pipeline drive)	단계별 새 claude -p 프로세스
standalone	driver와 동일한 소유 프로세스	자체 API 키를 사용한 Agent SDK — Claude Code 세션 없음

driver와 standalone은 하나의 루프를 공유하고 실행기만 다르므로 혼동하기 쉽습니다; 둘 중 하나를 pipeline drive(이는 driver 경로의 명령 이름이지 모드의 동의어가 아님)와 혼동하지 마십시오. 이 번들 CLI는 session, manager, driver를 구현합니다 — v1 파이프라인은 PIPELINE.md 전면부에서 runner: headless로 driver를 표기합니다 (아래 참조); standalone과 pipeline.yml 수준의 runner: 키는 동일한 네 모드 설계에 속하지만 이 번들 복사본에는 아직 연결되지 않았으므로 사용자에게 오늘 실행될 것이라고 말하지 마십시오.

절차 3단계에서 model: 읽기와 함께 runner:를 결정하십시오. v2 파이프라인에서는 pipeline.yml의 최상위 키입니다 — 거기서 Grep ^runner:를 사용하여 한 줄을 읽고 절대 단계 파일을 열지 않습니다; v1에서는 PIPELINE.md 전면부에 있으며, model:을 위해 읽는 ≤50줄 내에 이미 포함되어 있습니다. 없거나 읽을 수 없으면 ⇒ manager, 현재 동작이자 의도된 기본값입니다 (E10). 선언되었지만 아래 분기가 없는 값도 여전히 manager를 실행합니다 — 하지만 시작하기 전에 한 줄로 그 사실을 알리십시오, manifest가 선언하지 않은 모드는 작성자가 선택하지 않은 모드이기 때문입니다. 체인 길이에서 모드를 추론하지 마십시오: 보이지 않는 임계값은 하나의 명령이 두 가지 방식으로 동작하게 만듭니다.

runner: session — 메인 세션이 직접 루프 실행

pipeline-manager를 생성하지 마십시오. 세션 루프를 읽고 절차 5.1–5.3 단계 대신 따르십시오; 이 파일의 나머지 모든 것 — 1-4단계, 재개 절차, 중첩 차단(blocker) 흐름, 슈퍼바이저 불변 조건 및 보고서 형식 —은 변경 없이 적용됩니다. 당신은 여전히 depth 0의 슈퍼바이저이며 루프를 위임하는 대신 흡수했기 때문입니다.

해당 파일은 이 모드에 필요한 두 가지 사전 점검 거부 조건(CLI가 pipeline next --brief-file을 지원하기에 너무 오래됨, 그리고 execution: parallel — 그 페이로드는 세션이 열 수 없는 brief에 있음)을 명시하고 있으며, 트레이드오프를 정직하게 설명합니다: 모든 액션 및 모든 단계 보고서가 사용자가 보고 있는 컨텍스트에 도착하므로 긴 체인은 manager에 속합니다 — 이것이 바로 manager가 여전히 기본값인 이유입니다.

runner: headless (v1) — driver 모드

파이프라인이 v1이고 model:을 위해 읽은 PIPELINE.md 전면부에 runner: headless(v1의 driver 모드 표기 — 위 표 참조)도 포함된 경우, pipeline-manager를 생성하지 마십시오. 대신 번들 드라이버를 백그라운드 프로세스로 실행하고 감독합니다:

bun "${CLAUDE_PLUGIN_ROOT}/apps/pipeline-cli/src/cli.ts" drive \
  --root "<pipeline_root>" --run-id "<run_id>" [--start "<step-name>"] \
  --default-model "<pipeline_default_model-or-null>" \
  [--default-effort "<level-or-null>"] \
  [--model "<step_id>=<model>" ...] [--effort "<step_id>=<level>" ...] --json [--resume]

run_in_background: true로 실행하고 종료 시 최종 JSON에 따라 조치합니다: 종료 코드 0 → pipeline.completed 발행; 종료 코드 1 → pipeline.halted 발행 및 이유 표시; 종료 코드 3 (blocked) → 아래 중첩 차단(blocker) 흐름 실행 후 --resume으로 drive 재실행. 슈퍼바이저 역할(실행 ID, liveness, 미러 바인딩, 사람 보고)의 다른 모든 것은 변경되지 않습니다. 이 driver (v1: runner: headless) 경로는 자기 개선 액션을 건너뛰고 .feedback/<run_id>/를 그대로 둡니다 — 최종 보고서에 이를 언급하여 사용자가 수동 개선 통과를 실행할 수 있도록 하십시오. runner:가 없거나 manager인 경우, 정확히 아래와 같이 진행하십시오.

모델 선택

파이프라인(및 각 반복)은 선택적 model: 전면부 필드를 통해 Claude 모델을 선택할 수 있습니다. 기본값은 상속됩니다 — 생략 시 단계 실행기는 세션 모델을 상속합니다. 당신은 파이프라인 수준 기본값만 결정하여 매니저에 전달합니다; pipeline next CLI는 반복별 유효 모델을 결정하고(실행별 재정의 ?? step.model ?? pipeline_default_model) 매니저는 이를 각 step-executor에 Agent 도구의 호출별 model 매개변수를 통해 전달합니다. 결정된 값을 변경하지 않고 그대로 전달하십시오 — 별칭을 표준 ID로 변환하지 마십시오. Agent model 매개변수는 별칭, 표준 ID 및 inherit을 직접 허용합니다.

허용되는 model: 어휘 (종단 간): 별칭 haiku / sonnet / opus / fable 중 하나, 또는 정확한 표준 Claude 모델 ID(claude-로 시작하는 문자열, 예: claude-opus-4-8, claude-sonnet-4-6, claude-fable-5), 또는 inherit / 없음 (→ 세션 기본값).

pipeline_default_model 결정: v2 파이프라인에서 CLI는 pipeline.yml에서 defaults.model을 자체적으로 읽습니다 — null을 전달하고 CLI가 처리하도록 두십시오. 그렇지 않으면, <pipeline-root>/PIPELINE.md가 존재하는 경우 limit: 50으로 Read하고 전면부 model: 값이 허용되는 값(별칭, claude-* ID, 그대로 유지)인 경우 가져옵니다; inherit/없음 → null. PIPELINE.md가 없으면 null. 유효하지 않은 값 — 허용되는 별칭 중 하나, claude-* ID, inherit, 또는 없음이 아닌 모든 것 — 한 번 경고하고 null로 폴백합니다(중단하지 않음). (≤~10줄의 전면부 읽기는 메타데이터 추출이지 내용 읽기가 아닙니다 — step-executor가 로드하는 것을 복제하지 않습니다.)

실행별 단계 재정의 (step_model_overrides): 사용자는 특정 단계를 이 실행에만 다른 모델로 고정할 수 있습니다 — 파이프라인 파일을 편집하지 않고, 경로 뒤에 명시적 플래그(--model <step_id>=<model>, 반복 가능) 또는 자연어("steps 02-implement 및 03-refine을 fable로 실행")를 통해. 사용자가 말한 내용을 <step_id>=<model> 쌍으로 정규화하십시오: step_id는 단계의 step_id 전면부 또는 파일 이름 줄기(예: steps/02-implement.md의 경우 02-implement); model은 위의 허용 어휘를 사용합니다(inherit은 해당 단계에 세션 기본값을 강제). ID 유효성 검사를 위해 단계 파일을 읽지 않습니다 — CLI가 알 수 없는 ID에 대해 경고하고 유효하지 않은 모델을 거부합니다. 쌍을 매니저에 step_model_overrides로 전달하거나(5.1 참조), driver 경로의 경우 drive 명령에 반복되는 --model 플래그로 전달합니다. 재정의는 단계 자체의 model: 전면부를 무시합니다; 재정의가 없는 단계는 변경되지 않습니다. CLI는 초기화 시 실행 상태에 재정의를 유지하므로 재개 시 자동으로 유지됩니다 — 매니저를 재호출할 때 동일한 쌍을 다시 전달하십시오(무해하며, 삭제된 .runtime/에서도 생존). 재정의가 언급되지 않으면 완전히 생략합니다.

노력 선택 (추론 노력 — model:의 쌍둥이)

파이프라인 및 각 반복은 선택적 effort: 전면부 필드를 통해 추론 노력을 선택할 수도 있습니다 (수준: low / medium / high / xhigh / max; inherit/없음 → 세션의 노력). 모델과 정확히 동일한 사다리를 통해 결정됩니다 — 실행별 재정의 ?? 단계 effort: ?? 파이프라인 effort: ?? 상속 — 모두 pipeline next CLI 내부에서. pipeline_default_effort를 model:을 위해 이미 수행하는 동일한 PIPELINE.md 전면부 읽기에서 결정하고(동일한 유효하지 않은 값 규칙: 한 번 경고, null로 폴백), 매니저에 pipeline_default_effort로 전달하며, "03-refine을 max 노력으로 실행"과 같은 사용자 요청을 step_effort_overrides 쌍(<step_id>=<level>)으로 정규화하여 모델 쌍과 정확히 동일하게 전달합니다(driver 경로의 경우 --effort 플래그). 정직 메모: driver 실행기는 노력을 실제로 적용합니다(claude --effort per spawn); manager 모드에서 Agent 도구는 아직 호출별 노력 매개변수를 노출하지 않을 수 있습니다 — 매니저는 지원될 때 전달하고 그렇지 않으면 단계가 세션 노력을 상속합니다(pipeline-manager.md § run-step 참조).

사전 조건

• 현재 프로젝트의 ./.pipeline/ 아래에 파이프라인이 존재합니다(일반적으로 /pipeline:design으로 작성됨).
• $1은 ./.pipeline/ 아래의 파이프라인 FOLDER입니다(예: ./.pipeline/ship-feature). 이는 새로운 실행을 시작합니다 — 항상 새로운 run_id를 생성합니다. --start <step-name>은 manifest의 첫 번째 단계 대신 해당 이름의 단계에서 새로운 실행을 시작합니다. 반복 파일 경로도 허용되며, v1 파이프라인이 시작 단계를 지정하는 방식입니다. 또는 --resume [<run_id>]를 통해 기존 실행_을 원래 run_id로 재진입합니다 ("재개 절차" 참조) — 상태를 고아로 만들지 않고 죽은 세션의 실행을 계속하는 유일한 방법입니다.
• 현재 작업 디렉토리는 소비자 프로젝트의 루트입니다 — 반복에 의해 수행되는 모든 파일 편집은 여기에 적용됩니다.

저널 이벤트 발행

실행 수준 수명 주기를 <project>/.pipeline/.runtime/events.jsonl에 발행합니다; 반복별 이벤트(iteration.*, improver.*, script_creator.*, worktree.*)는 매니저가 구동하는 pipeline next CLI에 의해 프로세스 내에서 자동 발행됩니다(매니저 자체는 회고의 improver/script 이벤트만 발행합니다). 전체 실행이 하나의 session_id를 공유하므로, 아래에 등록하는 미러 바인딩을 통해 분석 훅이 매니저와 step-executor의 도구 호출을 이 실행과 연관시킬 수 있습니다. 발행은 최선의 노력입니다 — 실패가 실행을 중단시키지 마십시오.

절차 시작 시 일회성 설정: CLI를 호출하여 실행 ID를 생성하십시오 — 직접 생성하거나 형식을 발명하지 마십시오: bun "${CLAUDE_PLUGIN_ROOT}/apps/pipeline-cli/src/cli.ts" id. 출력되는 리터럴 값(예: UUIDv7 019fc762-5762-7000-a9bf-922ed8fa00be)을 캡처하십시오.

중요 — 모든 writer 호출에 run_id를 리터럴로 전달하십시오. Claude Code의 Bash 도구는 호출 간에 셸 상태를 유지하지 않으므로 내보낸 env 변수는 다음 pipeline event 호출에 도달하지 않습니다. run_id=<the-literal-id>를 k=v 인수로 모든 호출에 전달하십시오. k=v 인수에는 = 주위에 공백이 없습니다; 공백이 포함된 값은 작은따옴표로 묶으십시오.

발행 도우미 (Bun으로 실행, 성공 시 자동, 실패 시에도 exit 0 — 출력을 확인하지 마십시오):

bun "${CLAUDE_PLUGIN_ROOT}/apps/pipeline-cli/src/cli.ts" event <event-type> run_id=<literal-id> [k=v ...]

발행할 내용 (항목당 한 번 호출):

• --resume 시 이 전체 목록은 적용되지 않습니다 — 재개 절차는 기존 run_id에 대해 write-liveness + register-mirror-binding만 발행하며, pipeline.started는 절대 발행하지 않습니다(실행 재진입은 시작이 아닙니다). "재개 절차" 참조.

• 배너 후: pipeline.started run_id=<id> pipeline_name=<name> first_iteration_path=<abs> pipeline_root=<abs> default_model=<model-or-null> — default_model은 pipeline_default_model입니다(별칭 haiku/sonnet/opus/fable, 표준 claude-* ID, 또는 리터럴 null).

• pipeline.started 직후, liveness lockfile을 작성하여 독자가 종료 이벤트 없이 이 실행이 죽었음을 알 수 있도록 합니다: bun "${CLAUDE_PLUGIN_ROOT}/apps/pipeline-cli/src/cli.ts" event write-liveness run_id=<id> pid=$PPID (PowerShell: pid=$PID). 이 슈퍼바이저를 구동하는 프로세스의 OS pid를 전달하십시오 — $PPID는 지속적인 Claude 세션에 가장 적합한 이식 가능한 핸들입니다. 데몬은 이 pid가 실제로 죽은 프로세스인 경우에만 실행을 자동 폐기하므로, 신뢰할 수 없는 값은 안전한 no-op입니다.

• Im

…

[번역을 위해 잘림]