orchestrator

name	orchestrator
description	자연어 요청을 받아 전체 개발 사이클을 자동 처리해야 할 때. — MUST TRIGGER: /nova:auto 호출, 사용자가 '전체 알아서 해줘' 유형의 요청을 할 때, 다중 에이전트 편성이 필요한 복합 작업.
description_en	Use when a natural-language request needs the entire development cycle auto-handled. — MUST TRIGGER: /nova:auto invocation, 'just handle everything' requests, or complex tasks requiring multi-agent formation.
user-invocable	false

Nova Orchestrator

적용 규칙 (on-demand 로드)

• docs/nova-rules.md §2 Generator-Evaluator 분리 + 핸드오프 (self_verify 필드)
• docs/nova-rules.md §6 복잡한 작업의 스프린트 분할 (각 스프린트 완료 = Evaluator 필수)
• docs/nova-rules.md §10 관찰성 계약 — Phase 전이·스프린트 전환 시 이벤트 기록

관찰성 훅 (v5.12.0+)

Phase 전이 시 (예: Phase A→B, pending→running→completed) 이벤트 기록:

bash hooks/record-event.sh phase_transition "$(jq -cn \
  --arg oid "$ORCHESTRATION_ID" \
  --arg phase "$PHASE_NAME" \
  --arg from "$FROM_STATUS" \
  --arg to "$TO_STATUS" \
  '{orchestration_id:$oid, phase_name:$phase, from_status:$from, to_status:$to}')"

Sprint 전환 시:

bash hooks/record-event.sh sprint_started "{...}"   # 착수
bash hooks/record-event.sh sprint_completed "{...}" # 종료 (verdict 포함)

블로커 감지/해소 시 (§7 분류):

bash hooks/record-event.sh blocker_raised "$(jq -cn --arg t \"$BTYPE\" --arg c \"$CAUSE\" '{blocker_type:$t, cause:$c}')" 2>/dev/null || true
bash hooks/record-event.sh blocker_resolved "$(jq -cn --arg t \"$BTYPE\" --arg r \"$RESOLUTION\" '{blocker_type:$t, resolution:$r}')" 2>/dev/null || true

Safe-default: 실패는 exit 0, 상위 파이프라인 영향 없음.

자연어 한 줄을 받아서 설계→구현→검증→수정 전체 파이프라인을 자동 실행한다.

핵심 원칙

• 설계가 구현보다 먼저다 (CPS)
• Generator ≠ Evaluator (역할 분리)
• 구조화된 프롬프트가 자연어보다 낫다
• 멀티 프로젝트 병렬 지원

오케스트레이션 추적 (MCP 도구) — 필수 계약

이 섹션은 soft 권고가 아니라 계약이다. 각 Phase 진행 상황은 반드시 MCP 도구로 추적한다. 세션 중단 시 .nova-orchestration.json으로 복구 지점이 되며, 누락 시 Evolve 피드백 루프의 관찰 데이터가 공백이 된다.

시점	MCP 도구 호출	누락 시 영향
Phase 0: 오케스트레이션 등록	orchestration_start — task, complexity, phases 전체 등록	세션 끊기면 복구 불가 + 외부에서 진행 조회 불가
Phase N 시작	orchestration_update — status: "running"	어느 Phase에서 끊겼는지 모름
Phase N 완료	orchestration_update — status: "completed" + result	Phase 소요 시간·산출물 메트릭 공백
Phase N 실패	orchestration_update — status: "failed" + result	실패 패턴 분석 불가
상태 확인	orchestration_status — 현재 진행 상황 조회	(조회용, 선택)

Phase 0: 오케스트레이션 등록 (무조건 최우선)

요청 분석(Phase 1) 직전에 반드시 실행한다. 분기 매트릭스 평가·Architect spawn·Design 재사용 판단 등 어떤 다른 스텝보다 먼저.

orchestration_start({
  task: "사용자 프로필 페이지 구현",
  complexity: "medium",
  phases: [
    { name: "설계", role: "Architect" },
    { name: "구현", role: "Generator" },
    { name: "검증", role: "Evaluator" }
  ]
})
→ orch-abc123   # 이 ID를 이후 모든 update에서 참조

이후 Phase마다:

orchestration_update({ orchestration_id: "orch-abc123", phase_name: "설계", status: "running" })
# ... Architect 실행 ...
orchestration_update({ orchestration_id: "orch-abc123", phase_name: "설계", status: "completed", result: "CPS 설계서 작성 완료" })
orchestration_update({ orchestration_id: "orch-abc123", phase_name: "구현", status: "running" })
# ...

Escape hatch는 단 하나 — 명시적 에러

MCP 도구 호출이 실제로 에러를 반환한 경우에만 추적 없이 진행한다. "가볍게 스킵"하거나 "이번은 필요 없을 것 같아서 생략"은 계약 위반이다.

호출 시도 후 에러 발생 시:

• stderr에 [Orchestrator] orchestration_start 호출 실패 — 추적 없이 진행: <에러 메시지> 기록
• 이후 Phase 진행은 기존 방식으로 계속

사용 불가 환경이라는 추정만으로 호출 자체를 생략하지 않는다. 반드시 시도한다.

사후 감사

세션 종료 시 hooks/audit-orchestration.sh가 이 계약 준수 여부를 자동 검사한다. Generator/Evaluator Task 호출이 있었는데 .nova-orchestration.json에 오늘자 기록이 없으면 orchestration_missing 이벤트가 기록되고, 다음 세션 Evaluator가 이를 사용자에게 보고한다.

Execution

Phase 0: 오케스트레이션 등록 (필수, 최우선)

요청을 받자마자 Phase 1 분석 이전에 orchestration_start를 호출한다. 초기에 phases 구성이 불확실하면 최소 골격(Architect/Generator/Evaluator)으로 등록 후 orchestration_update로 필요 시 보완한다. 호출 자체를 스킵하지 않는다.

등록 없이 Phase 1 이후로 넘어가면 관찰성 계약을 위반한 것이며, 사후 감사(hooks/audit-orchestration.sh)가 orchestration_missing 이벤트를 기록한다.

Phase 1: 요청 분석

사용자 요청에서 다음을 추출한다:

• 프로젝트 경로: 절대 경로 또는 현재 디렉토리 기준 상대 경로
• 작업 목표: 무엇을 만들거나 변경하는가
• 복잡도: 파일 수, 모듈 범위, 프로젝트 수로 판단
• 멀티 프로젝트 여부: 2개 이상 프로젝트에 걸친 요청인지 판단

NOVA-STATE.md가 있으면 현재 스프린트 컨텍스트와 Phase를 참고한다.

Plan/Design 재사용 분기

요청 분석 직후, Phase 2 진입 전에 기존 산출물을 확인하고 분기한다.

slug 추출 규칙:

1. 요청에서 따옴표(' 또는 ") 안의 텍스트를 추출한다. 따옴표가 없으면 플래그(--xxx)를 제외한 전체 요청 텍스트를 사용한다.
2. 공백을 -로 치환한다.
3. 한글·영문·숫자·하이픈 이외의 특수문자를 제거한다. 한글은 유지한다.
4. 최종 slug 예시:
   • "건폐율 시각화 추가" → 건폐율-시각화-추가
   • "add carousel" → add-carousel
5. 플래그 제거 후 slug가 빈 문자열이면(예: /nova:auto --fresh --design-only), 재사용 분기를 건너뛰고 fresh 동작으로 진입한다. 경고 로그: [Orchestrator] slug 추출 실패 — fresh 모드로 진행. 요청에 플래그가 없고 텍스트도 비어 있는 경우에만 요청 첫 단어를 slug로 사용한다.

후보 매칭 규칙:

• docs/plans/{slug}.md — exact match 우선
• exact match 실패 시 slug의 첫 단어로 시작하는(startsWith) 파일을 fuzzy 후보로 수집
• 후보가 2개 이상이면 사용자에게 숫자 선택 프롬프트를 출력한다:

  다음 기존 Plan 중 재사용할 것을 선택하세요:
  [1] {후보1}.md
  [2] {후보2}.md
  [f] fresh로 처음부터
  

분기 매트릭스:

우선순위: 위에서 아래로 순차 평가한다. 먼저 매칭되는 행이 적용된다. 특히 Plan과 Design이 모두 존재하면 Design 행이 우선(Phase 2·3 스킵).

조건	동작
--fresh + --deep 동시 있음	기존 Plan/Design 무시 + deepplan 스킬 호출로 Plan 생성 → PlanReuseFlow로 진입. 로그: [Orchestrator] fresh+deep 모드 — deepplan 호출 후 파이프라인 진입
--fresh 플래그 있음 (--deep 없음)	재사용 무시 → fresh Architect (escape hatch). 로그: [Orchestrator] fresh 모드 — 기존 Plan/Design 무시
docs/designs/{slug}.md 존재	Phase 2·3 스킵 → Phase 4(Generator) 직행. Dev 프롬프트 기반으로 Design 파일 내용을 사용. 로그: [Orchestrator] Design 재사용: docs/designs/{slug}.md — Phase 2·3 스킵
docs/plans/{slug}.md만 존재 + --deep	--deep 무시 + 경고 + Plan 재사용. 로그: [Orchestrator] --deep 무시 — 기존 Plan 존중. 재실행하려면 --fresh --deep
docs/plans/{slug}.md만 존재 (Design 없음, --deep 없음)	Phase 2 Architect 실행. 단, Architect 프롬프트에 Plan 경로와 내용을 반드시 포함하여 fresh 설계를 금지한다. 로그: [Orchestrator] Plan 재사용: docs/plans/{slug}.md — Architect가 Plan 기반 설계
둘 다 없음 + --deep	deepplan 스킬 호출 → docs/plans/{slug}.md 생성 → PlanReuseFlow로 진입. 로그: [Orchestrator] deepplan 호출 — Plan 생성 후 파이프라인 진입
둘 다 없음	기존 동작 유지 (fresh Architect)

--deep 처리 의사코드:

if flags.fresh and flags.deep:
    log("[Orchestrator] fresh+deep 모드 — deepplan 호출 후 파이프라인 진입")
    run_deepplan(request)   # docs/plans/{slug}.md 생성
    return PlanReuseFlow(plan_path)

if flags.fresh:
    log("[Orchestrator] fresh 모드 — 기존 Plan/Design 무시")
    return FreshFlow()

if exists(design_path):
    log("[Orchestrator] Design 재사용: {design_path} — Phase 2·3 스킵")
    return DesignReuseFlow(design_path)

if exists(plan_path) and flags.deep:
    warn("[Orchestrator] --deep 무시 — 기존 Plan 존중. 재실행하려면 --fresh --deep")
    return PlanReuseFlow(plan_path)

if exists(plan_path):
    log("[Orchestrator] Plan 재사용: {plan_path} — Architect가 Plan 기반 설계")
    return PlanReuseFlow(plan_path)

if flags.deep:
    log("[Orchestrator] deepplan 호출 — Plan 생성 후 파이프라인 진입")
    run_deepplan(request)   # docs/plans/{slug}.md 생성
    return PlanReuseFlow(plan_path)

return FreshFlow()  # 기존 동작

Design 재사용 시 Phase 3 처리: Phase 2·3을 스킵하므로, Phase 4 Dev 프롬프트는 Architect 설계서 대신 docs/designs/{slug}.md 내용을 기반으로 생성한다. Phase 3 프롬프트 변환 항목 표의 "Architect 설계서" 출처를 Design 파일로 대체한다.

Plan 재사용 시 Phase 2 처리: Architect 서브에이전트 컨텍스트에 다음을 추가한다:

기존 Plan 파일: docs/plans/{slug}.md
아래 Plan 내용을 기반으로 설계하라. 처음부터 새로 작성하지 않는다.
Plan 내용에 없는 내용을 발명하지 말고, Plan의 Solution·Sprints 구조를 설계서에 반영하라.
---
{Plan 파일 전체 내용}
---

UI 변경 사전 감지 (선택적): bash scripts/detect-ui-change.sh --planning 호출 → likely_ui 결과 표시. "UI 변경 가능성: {Yes/No}" 1줄 출력 (사용자 인지 목적, 분기 결정 X).

복잡도 판단 기준

복잡도	기준	에이전트 편성
간단	1~2 파일, 단일 프로젝트	Dev 1 → QA 1
보통	3~7 파일, 단일 프로젝트	Architect 1 → Dev 1 → QA 1
복잡	8+ 파일 또는 멀티 프로젝트	Architect N → Dev N → QA N → Fix N

인증/DB/결제/보안 관련 변경은 파일 수와 무관하게 한 단계 상향한다.

Phase 2: 설계 (Architect)

간단 복잡도는 이 단계를 건너뛴다.

Architect 에이전트를 spawn하여 CPS 설계를 수행한다.

Architect 에이전트 지시 원칙:

1. 프로젝트 코드를 직접 읽고 현재 상태를 파악한다
2. CPS(Context→Problem→Solution) 구조로 설계서를 작성한다
3. 설계 산출물에 다음을 포함한다:
   • 페이지/컴포넌트 구조
   • 디자인 토큰 (색상, 폰트, 간격 — 해당 시)
   • 데이터 흐름 및 API 경계
   • 기술 스택 및 구현 제약
   • 구현 순서 및 우선순위
   • 빌드/검증 명령

멀티 프로젝트면 각 프로젝트별 Architect를 병렬 실행한다 (run_in_background: true).

Architect 서브에이전트에 반드시 포함할 컨텍스트:

작업 디렉토리: {프로젝트_경로}
작업 목표: {사용자 요청}
역할: 구현하지 않는다. 설계서만 작성한다.
산출물: CPS 설계서 (Context/Problem/Solution + 구현 체크리스트)

--design-only 종료점

--design-only 플래그가 있으면 Phase 2 완료 후 설계 결과를 사용자에게 보여주고 종료한다. Phase 3 이후는 실행하지 않는다.

멀티 에이전트 조율 원칙

복잡(8+파일) 이상에서 병렬 에이전트 투입 시 다음을 적용한다:

태스크 의존성 DAG

스프린트 내 태스크 간 선후 관계를 명시하여 병렬 실행을 최적화한다:

[독립] A: DB 스키마  ─┐
[독립] B: API 타입    ─┤── [의존] C: API 구현 ── [의존] D: 프론트엔드
[독립] E: 테스트 셋업 ─┘

• 의존 관계가 없는 태스크는 병렬 에이전트로 동시 실행한다
• 의존 태스크는 선행 태스크 완료 후 순차 실행한다

파일 잠금 힌트

병렬 에이전트에게 "이 파일은 다른 에이전트가 수정 중"이라는 컨텍스트를 제공한다:

주의: 다음 파일은 다른 에이전트가 수정 중입니다. 읽기만 하세요:
- src/types.ts (Agent A가 수정 중)
- src/db/schema.ts (Agent B가 수정 중)

전문 에이전트 > 범용 에이전트

3개의 전문화된 에이전트가 1개의 범용 에이전트보다 일관되게 더 나은 결과를 낸다. 에이전트 편성 시 역할별 전문 에이전트(architect, senior-dev, qa-engineer)를 투입한다.

중간 진행 점검 (mid-workflow check-in)

병렬 sub-agent 실행 시 lead는 다음 시점에 진행 점검 SendMessage를 1회 권장한다 (Anthropic Managed Agents — Multiagent Orchestration 2026-05-06 패턴 흡수):

• 진행률 50% 시점: 총 N개 sub-agent 중 N/2가 idle/완료 보고를 보낸 시점.
• 5분 이상 침묵: 단일 sub-agent가 5분 이상 idle notification 없이 응답이 없을 때.
• 의존성 변동: 다른 에이전트의 산출물이 선행 가정과 다를 때 (예: 공유 스키마 변경).

너무 잦은 점검은 sub-agent의 작업 흐름을 방해하므로 위 3 조건 외에는 발송하지 않는다. 점검 메시지는 짧게: "현재 진행 단계와 막힌 부분이 있다면 한 줄로 보고하라"로 충분. 점검 후 응답이 없으면 lead가 hang 가능성을 평가해 작업 분할 또는 회수를 결정한다. (참조: https://claude.com/blog/new-in-claude-managed-agents)

구조화된 핸드오프 프로토콜

에이전트 간 전달 시 구조화된 아티팩트를 사용하여 컨텍스트 손실을 방지한다. (Anthropic 3-Agent Harness 패턴 적용)

전달 구간	아티팩트 형식	내용
Architect → Generator	CPS 설계서 + 구현 체크리스트	기존 방식 유지
Generator → Evaluator	구조화된 변경 요약	변경 파일, 의도, 주요 결정
Evaluator → Generator (Fix)	구조화된 이슈 목록	파일:라인, 심각도, 수정 방향

Generator → Evaluator 핸드오프 포맷

Generator 완료 시 다음 정보를 Evaluator에게 전달한다:

## 변경 요약
- 변경 파일: {파일 목록}
- 변경 의도: {한줄 요약}
- 주요 결정: {트레이드오프 선택 이유}
- 알려진 제한: {미구현/의도적 생략 항목}
- self_verify: (선택 — Sprint 1부터 권장)
  - confident: {확신 영역 + 한줄 근거(테스트/로직 단순성 등)}
  - uncertain: {불확실 영역 + 사유(경계값/에러 처리/동시성/외부 의존)}
  - not_tested: {실행 검증 미수행 영역 + 사유}

Evaluator는 코드 diff뿐 아니라 이 핸드오프 아티팩트를 참조하여, Generator의 의도와 실제 구현의 정합성을 검증한다.

self_verify 필드 원칙 (Sprint 1부터):

• 선택 필드 — 없어도 기존 검증 동작 (하위호환).
• confident에는 "왜 확신하는지" 한 줄 근거를 반드시 포함. 근거 없는 확신은 자기 과신으로 간주.
• uncertain/not_tested가 0건이면 오히려 의심 시그널 — Generator에게 경계값·에러 처리·외부 의존을 다시 점검하도록 지시한다.
• 근거: LLM Evaluators Recognize and Favor Their Own Generations (arXiv 2404.13076) — self-preference bias는 구조적으로 방어 필요.
• Sprint 1에서는 신호 수집만. Layer 배분 최적화는 Sprint 2, 충돌 학습은 Sprint 3, Jury 참여는 Sprint 4.

Orchestrator 수신 시 관측 (Sprint 1 채택률 측정):

• Generator 핸드오프 수신 직후 self_verify 필드 유무를 한 줄로 로그한다:

  [Handoff] self_verify: present  — confident={N}/uncertain={N}/not_tested={N}
  [Handoff] self_verify: absent   — Generator에게 필드 포함 재요청 (Sprint 1은 재요청만, 차단 X)
  

• absent인 경우 Evaluator 전달 전 Generator에게 한 번 재요청한다 (루프 금지 — 2회차도 absent면 그대로 진행).
• 이 관측 로그는 Sprint 2의 Layer 배분 최적화 근거 데이터로 활용된다.

Evaluator 전달 시 메타 필드 (absent 구분): 재요청 시도 후에도 self_verify가 없으면 Evaluator에게 아래 메타 필드를 명시적으로 포함시킨다. Evaluator는 "원래 누락"과 "재요청도 실패한 누락"을 구분해 Sprint 1 관측 데이터 품질을 유지한다.

## self_verify_meta (Orchestrator가 Evaluator에게 전달)
- status: {present | absent_initial | absent_after_retry}
- retries: {0 | 1}

• present: Generator가 1차에 포함 → Evaluator는 필드 내용을 그대로 사용
• absent_initial: 1차 누락 (재요청 전). 보통 Orchestrator가 재요청하여 이 상태로는 Evaluator에 도달하지 않음
• absent_after_retry: 재요청도 실패. 채택률 통계에서 "강한 미채택 시그널"로 집계

Evaluator → Generator (Fix) 핸드오프 포맷

FAIL 판정 시 수정 지시를 구조화하여 전달한다:

## 수정 지시
[1] {파일:라인} — {심각도} — {이슈} → {수정 방향}
[2] ...
수정 범위: 위 항목에만 한정. 다른 코드 수정 금지.

Phase 3: 프롬프트 변환

조건부 실행: Phase 1의 Design 재사용 분기에서는 이 Phase 전체가 스킵된다. 아래 표의 "Architect 설계서" 출처는 그 경로에서 docs/designs/{slug}.md로 대체되어 Phase 4 Dev 프롬프트에 직접 주입된다.

Architect의 설계서를 Dev 에이전트 프롬프트로 변환한다. 이 단계가 품질의 핵심이다 — 설계서의 구체적 정보가 구현 지침으로 주입된다.

Dev 프롬프트에 반드시 포함할 항목:

항목	출처
프로젝트 경로 (절대 경로)	요청 분석
기술 스택	Architect 설계서 (Design 재사용 시: docs/designs/{slug}.md)
파일/컴포넌트 구조	Architect 설계서 (Design 재사용 시: docs/designs/{slug}.md)
디자인 토큰	Architect 설계서 (Design 재사용 시: docs/designs/{slug}.md)
데이터 흐름	Architect 설계서 (Design 재사용 시: docs/designs/{slug}.md)
구현 순서	Architect 설계서 (Design 재사용 시: docs/designs/{slug}.md)
빌드 검증 명령	Architect 설계서 (Design 재사용 시: docs/designs/{slug}.md)
"구현만 해, 검증은 별도" 명시	항상 포함

간단 복잡도는 Architect 없이 사용자 요청에서 직접 Dev 프롬프트를 생성한다.

Phase 4: 구현 (Generator)

Dev 에이전트를 spawn한다 (senior-dev 타입).

• run_in_background: true로 비동기 실행
• 멀티 프로젝트면 프로젝트별 Dev를 병렬 실행 (각 프로젝트 독립)
• Dev에게 "구현만 하라, 검증은 별도 수행한다"를 명시

모든 Dev 에이전트 완료 대기 후 구현 결과를 수집한다.

Checkpoint: Generate 완료

구현 결과 요약을 사용자에게 보고한다:

• 변경된 파일 목록
• 주요 변경 내용 요약 (3줄 이내)

--skip-qa 플래그가 있으면 Phase 5~6을 건너뛰고 Phase 7로 이동한다.

Phase 5: 검증 (Evaluator)

QA 에이전트를 spawn한다 (qa-engineer 타입).

QA 프롬프트에 반드시 포함할 항목:

• 검증 대상 파일 목록
• 설계서 기반 검증 기준 (있는 경우)
• 빌드/테스트 명령

--strict 플래그가 있으면 Full 검증(Layer 1~3)을 강제한다. 기본은 Standard 검증이다.

멀티 프로젝트면 프로젝트별 QA를 병렬 실행한다.

검증 항목

항목	기본	--strict
빌드 성공	필수	필수
TypeScript 타입 에러	필수	필수
파일 구조 (설계서 대조)	필수	필수
실제 동작 (curl/playwright)	생략	필수
경계값 시나리오	생략	필수

Phase 5.5: UI 변경 감지 + 자동 검증 (G3 페어 게이트)

Phase 5가 PASS면 다음을 수행한다.

Phase 5.5는 5.5a (코드 기반 ux-audit Lite, 기존)와 5.5b (시각 기반 visual-self-verify, 신규) 두 단계로 구성된다.

• 5.5a는 항상 수행 (UI 변경 감지 시) — 코드 분석으로 빠른 1차 게이트
• 5.5b는 docs/plans/{slug}-intent.json 존재 시 추가 수행 — 시각 기반 G3 차단 게이트
• intent.json 미존재 (사용자가 G1 스킵 또는 비-UI plan) → 5.5b 스킵

Phase 5.5a: UI 변경 감지 + ux-audit Lite (자동, 코드 기반)

Phase 5가 PASS면 다음을 수행한다:

1. result = bash scripts/detect-ui-change.sh --post-impl

2. result.is_ui == false → 즉시 Phase 7으로 (메트릭 기록 없음)

3. result.cache_hit == true:

   • "[Nova] 이전 감사와 동일한 변경 — ux-audit Lite 생략" 1줄 출력
   • bash scripts/log-metric.sh --event ui_audit_triggered --cache_hit 1
   • Phase 7으로

4. --no-ux-audit 플래그 OR (nova-config.json 존재 AND .auto.uiAudit == false):

   • bash scripts/log-metric.sh --event ui_audit_opt_out --reason flag (또는 --reason config)
   • Phase 7으로

5. 사전 고지:

   • .nova/ui-state.json 미존재 또는 .first_ui_audit_shown == false: 다음 자세한 안내 출력 (첫 트리거 템플릿):

     [Nova] UI 변경이 감지되었습니다. ux-audit Lite(3인 평가자)를 자동 실행합니다.
     - 평가자: Newcomer · Accessibility · Cognitive Load
     - 대상 파일: {result.files}
     - 이 자동화를 끄려면: --no-ux-audit 플래그 또는 nova-config.json { "auto": { "uiAudit": false } }
     

     .nova/ui-state.json 갱신: first_ui_audit_shown = true
   • 그 외: "[Nova] UI 변경 감지 → ux-audit Lite 병행" 1줄 출력

6. ux-audit Lite 실행 (Newcomer + Accessibility + Cognitive Load 3인, 5인 Full 아님):

   • target = result.files
   • ux-audit 스킬을 Lite 모드로 호출

7. 완료 후 메트릭 기록 및 캐시 갱신:

   bash scripts/log-metric.sh --event ui_audit_completed \
     --critical N --high N --medium N --low N
   

   .nova/last-audit.json 갱신: hash, ts, result, files, stats

8. result.critical >= 1 AND (nova-config.json 미존재 OR .auto.uiAuditBlockOnCritical != false):

   • 커밋 차단 + 사용자에게 Critical 목록 보고
   • 옵션 제시: 재시도 / --no-ux-audit / 수동 fix

9. 그 외: Phase 5.5b 진입 (intent.json 존재 시) 또는 Phase 7으로

Phase 5.5b: G3 Visual Self-Verify (자동, 시각 기반)

Phase 5.5a PASS 후 다음을 수행한다 (intent.json 존재 시만):

1. intent_path = docs/plans/{slug}-intent.json 확인

   • 미존재 → 즉시 Phase 7으로 (G1 스킵된 워크플로우)

2. vsv = bash scripts/visual-self-verify.sh --intent <intent_path> --output .nova/visual-audit/{ts}.json

3. vsv.cache_hit == true:

   • "[Nova] 동일한 변경 — 시각 검증 캐시 hit (생략)" 1줄 출력
   • bash scripts/log-metric.sh --event visual_verify_cache_hit
   • Phase 7으로

4. vsv.skipped == true:

   • opt-out 메트릭 (스크립트가 자동 기록)
   • Phase 7으로

5. Agent 서브에이전트 spawn (vision-capable Claude — Anthropic API 키 불필요):

   Agent({
     description: "Visual Intent Verifier",
     subagent_type: "general-purpose",
     model: vsv.agent_model_hint == "opus" ? "opus" : undefined,
     prompt: vsv.evaluator_prompt + (vsv.screenshot_paths 존재 시 첨부)
   })
   

   • Agent는 verdict JSON 출력: {verdict, overall_score, mismatches, strengths, rationale}

6. 차단 정책 적용:

   • verdict == fail → 커밋 차단 + 사용자에게 mismatches 보고. Phase 6 (Auto-Fix) 진입 가능
   • verdict == degraded → 경고만, 차단 X. "[Nova] 시각 검증 폴백 — 사용자 수동 확인 권장" 안내
   • verdict == pass → 캐시 갱신 (.nova/last-visual-audit.json — hash + verdict + ts), Phase 7으로

7. 메트릭 기록:

   bash scripts/log-metric.sh --event visual_verify_completed \
     --verdict <pass|fail|degraded> --critical N --high N --medium N --source <source>
   

Phase 6: 수정 (Auto-Fix)

QA 결과에서 FAIL/Critical/HIGH 이슈를 추출한다.

이슈가 없으면 이 단계를 건너뛴다.

Fix 에이전트를 spawn한다 (senior-dev 타입):

• 수정 범위를 QA가 지적한 항목에만 한정한다 — 다른 코드는 건드리지 않는다
• 새 서브에이전트를 spawn한다 (이전 Dev 컨텍스트 오염 방지)
• 수정 완료 후 빌드를 확인한다

Fix 완료 후 Phase 5(검증)를 재실행한다. 재시도는 최대 1회. 2번째 FAIL 시 즉시 중단하고 사용자에게 에스컬레이션한다.

Fix 에이전트에 반드시 포함할 컨텍스트:

작업 디렉토리: {프로젝트_경로}
수정 대상: QA가 지적한 {N}건
[1] {파일:라인} — {이슈 설명} → {수정 방향}
[2] ...
주의: 지적된 항목 외 다른 코드는 수정하지 않는다.

Phase 7: 결과 보고

전체 프로세스 결과를 요약하여 보고한다.

━━━ Nova Orchestrator — 완료 ━━━━━━━━━━━━━━━━━
  요청: {원본 요청}
  투입 에이전트: Architect {N} / Dev {N} / QA {N} / Fix {N}

  ## 프로젝트별 결과
  | 프로젝트 | Dev | QA | 판정 |
  |----------|-----|-----|------|
  | {경로} | 완료 | PASS | ✓ |

  ## 수정 필요 항목
  (CONDITIONAL 또는 FAIL 시 목록)

  ## 다음 단계
  - {배포 가능 / 수동 확인 필요 항목}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

에이전트 상태 추적: Claude Code의 TeammateIdle/TaskCompleted 훅 이벤트가 가용하면, 에이전트 완료를 자동 감지하여 다음 의존 태스크를 트리거한다. 가용하지 않으면 폴링으로 대기한다.

CRITICAL: 팀원 종료 의무 (idle ≠ shutdown). TeamCreate 또는 Agent(team_name=...)로 teammate를 spawn 했다면, Phase 7 결과 보고 직후 lead가 각 teammate에게 명시적으로 SendMessage({type:"shutdown_request"}) 발송한다. teammate의 idle notification은 종료 신호가 아니며, lead가 shutdown_request를 보내고 teammate가 approve할 때까지 process가 살아 있어 tmux pane·세션 비용을 점유한다. 발송 직후 다음 단계로 진행하고 자동 idle/shutdown_response 알림으로 종료를 확인한다. 모든 teammate가 shutdown 응답한 뒤 필요 시 TeamDelete로 팀 디렉토리를 정리한다. (참조: MEMORY feedback_shutdown_idle_agents.md. v5.47.x 자기-발견 갭 — orchestrator/evolution skill에 본 의무 부재로 4 스캐너가 idle 점유한 사례)

CRITICAL: 결과 보고 직후, 반드시 NOVA-STATE.md를 갱신한다. 이 단계를 건너뛰지 마라.

NOVA-STATE.md가 있으면 Last Activity를 갱신한다:

- /nova:auto → {PASS/FAIL} — {프로젝트명} | {ISO 8601 타임스탬프}
- /nova:auto → UI 감지 → ux-audit Lite PASS — Critical N / High N / Medium N / Low N | {ISO 8601 타임스탬프}

시계열은 events.jsonl 단일 진실원 (v5.44.0+): NOVA-STATE.md의 Recent Activity / Recently Done 표에 행 추가 X. 활동 기록은 hooks/record-event.sh(자동 호출)가 .nova/events.jsonl에, v3 marker 영역은 Stop hook이 scripts/registry-render-state.sh로 자동 갱신. AI는 Current/Phase/Refs/Risks 본문 스냅샷만 손편집 — 트림 의무 없음. (상세: skills/context-chain/SKILL.md)

v3 work-item registry 갱신 (Sprint 2)

Phase 7 결과 보고 직후, orchestrator(메인 컨텍스트)가 직접 registry-write.sh 호출한다. Evaluator sub-agent는 verdict만 stdout 출력 — orchestrator가 받아 처리:

• Evaluator PASS → evaluator-pass 호출 (원자적 status=done + review_required=false + evidence)

  bash "$NOVA_PLUGIN_PATH/scripts/registry-write.sh" evaluator-pass "$WI_ID" \
    --commit-sha="$(git rev-parse HEAD)" \
    --test-output="<verification path>"
  

• 블로커 발견 → transition <wi> blocked --blocked-reason="..."
• Evaluator FAIL → status 유지 (active). Refiner sub-agent 결과 받아 메인이 재시도. transition 호출 X.

권한 경계 (Sprint 0 spec docs/specs/registry-write-authority-v3.md):

• orchestrator skill 자체는 조정자 — sub-agent들이 직접 registry-write 호출 금지
• evaluator·qa-engineer·refiner sub-agent는 판정·제안만, registry 쓰기 절대 X
• 메인(또는 orchestrator)이 verdict 받아 위 명령 1회 호출 (단일 쓰기 경로)

플래그

플래그	동작
(없음)	전체 사이클 (설계→구현→검증→수정)
--design-only	설계까지만 (구현 전 확인용)
--skip-qa	QA 생략 (빠른 프로토타이핑)
--strict	QA를 Full 검증으로 강제
--fresh	기존 Plan/Design 무시, 강제 fresh Architect (escape hatch)
--deep	Plan 없을 때 deepplan 스킬(Explorer×3→Synth→Critic→Refiner) 호출 후 파이프라인 진입. 아키텍처 전환·대형 마이그레이션에 권장
--fresh --deep	기존 Plan 무시 + deepplan으로 새 Plan 생성 후 파이프라인 진입

Input

$ARGUMENTS