ask-navigator

Ask Navigator

Ask-navigator는 Shipyard의 네비게이터입니다: 목표까지의 경로가 보이지 않는 안개에 싸인 작업을 가져와 저장소 이슈 트래커 상의 결정 티켓 지도로 변환한 후, 세션당 하나의 티켓을 처리하며 경로가 명확해질 때까지 작업합니다. 결정만을 생산하며 결과물을 만들지 않습니다: 경로가 명확해지면 핸드오프하고 직접 구축하지 않습니다. 전달은 /oh-my-claudecode:launch의 몫입니다.

역할 계약. 선장(인간)이 목적지(W1)와 지도(W2)에 서명합니다; 네비게이터는 그 외 모든 것을 초안하며 선장에게 속한 질문에는 절대 답하지 않습니다 — 에이전트가 스스로의 질문에 답하는 심문 세션은 역할을 위반할 뿐 아니라 프로세스 자체를 깨뜨립니다. 사실은 네비게이터의 일입니다; 결정은 선장의 일입니다.

안개 테스트. 다음 두 질문 중 하나라도 '아니오'인 작업은 안개가 있습니다:

1. Q1 — 목적지를 한 문장으로 말할 수 있습니까? 이 작업이 찾아가는 명세, 결정, 또는 변경사항을 말합니다.
2. Q2 — 첫 세 가지 결정을 지금 바로 정확히 말할 수 있습니까? 아직 그 어느 것에도 답할 수 없더라도 말입니다.

둘 다 예 → 지도가 필요 없습니다; /oh-my-claudecode:launch를 실행하세요 (안개 게이트는 답이 '아니오'일 때만 작업을 여기로 보냅니다). 하나라도 아니오 → 먼저 지도를 작성하세요. ask-navigator는 직접 호출할 수도 있습니다: 느슨한 아이디어, launch의 안개 게이트가 넘긴 잔여 질문, 또는 인수 없이(열린 지도를 계속 진행) 호출하세요.

지도 홈

지도는 저장소 이슈 트래커에 navigator:map 레이블이 붙은 단일 이슈입니다; 그 결정 티켓들은 지도의 하위 이슈입니다. 트래커는 /oh-my-claudecode:drydock에 의해 기록되어 있어야 합니다; 기록된 것이 없다면 한 번 물어보고(GitHub / GitLab / 로컬 마크다운) 지도의 Notes에 답을 기록하세요.

• 트래커 기반 (GitHub, GitLab 또는 기록된 트래커): 하나의 지도 이슈, 티켓당 하위 이슈, 기본적인 차단/하위 관계 지원. 동시 세션과 트래커의 UI가 프론티어를 렌더링합니다 — 지도는 인간이 이미 보는 곳에 있습니다. 트래커에 아직 없으면 navigator:map 레이블을 생성하세요; 티켓 유형은 레이블이 아닌 티켓 본문에 있습니다.
• 로컬 마크다운 대안: .omc/wayfinder/<map-slug>/map.md + decisions/NN-<slug>.md (티켓당 하나의 파일, 의존성 순서대로 번호 지정). 로컬 모드는 동시 할당 보장이 없습니다: 지도의 Notes에 한 번 명시된 단일 운전자 규칙을 따릅니다.

지도는 색인일 뿐, 저장소가 아닙니다: 결정은 정확히 한 곳 — 자신의 티켓 — 에 존재합니다. 지도는 각 해결을 한 줄로 요약하고 링크합니다; 세부 사항을 다시 서술하지 않습니다.

문서 언어

지도와 티켓 산문은 /oh-my-claudecode:drydock과 동일한 문서 언어 계약을 따릅니다: CONTEXT.md 프론트매터에 documentLanguage가 있으면 읽고; 야드(yard)가 설치되지 않은 경우 차팅(W2) 중에 언어 질문을 한 번 하고 해결된 태그를 지도의 Notes에 기록하여 이후 launch 실행이 상속받도록 합니다. 경로, 레이블, 슬래시 명령어, navigator:map 레이블, 티켓 유형 이름(research, loft, grilling, task), HITL/AFK, blockedBy는 안정적인 토큰이며 모든 언어에서 바이트 단위로 안정적으로 유지됩니다.

지도 차팅

느슨한 아이디어(또는 launch의 잔여 질문)와 함께 호출됩니다. 차팅은 한 세션의 작업입니다; 아무것도 직접 해결하지 않습니다.

1. 감사 실행, 결과는 연기. /oh-my-claudecode:drydock --check 감사를 보고 전용 모드로 실행합니다: 결과가 차팅을 절대 차단하지는 않지만(지도는 결정을 생산하고 슬롯 랜딩을 생산하지 않습니다), 지도의 Notes에 그대로 기록됩니다 — launch의 야드 게이트가 작업이 최종적으로 전달 단계에 들어갈 때 그 부채를 수집할 것입니다. 야드가 전혀 설치되지 않은 경우(CONTEXT.md 없음, docs/adr/ 없음), /oh-my-claudecode:drydock을 한 번 제안합니다; 선장이 거절하면 트래커 전용 모드로 진행하고 모든 퇴적물을 연기합니다(퇴적물 참조).
2. W1 — 목적지 이름 정하기. "deep-interview"와 함께 스킬 도구를 호출하여 이 지도가 무엇을 찾아가는지 파악합니다: 명세, 결정, 또는 변경사항. 목적지가 범위를 고정하므로 먼저 결정됩니다. W1은 선장 서명입니다: 목적지 설명을 제시하고 명시적 확인을 받으세요. 인터뷰의 도움에도 선장이 목적지를 진술할 수 없다면, 오류가 아닙니다 — 최상의 후보들을 순위별로 제시하고 선장이 차팅할 하나를 고르거나 작업을 보류하도록 하세요.
3. 프론티어 매핑. "deep-interview"로 다시 심문하되, 너비 우선으로: 한 스레드에 깊이 파고들지 말고 전체 공간에 걸쳐 퍼져나가며 열린 결정들과 지금 취할 수 있는 첫 단계들을 표면화합니다. 안개가 드러나지 않는다면 — 목적지까지의 경로가 이미 명확하고 여정이 한 세션에 들어맞는다면 — 지도가 필요 없습니다: 중단하고 /oh-my-claudecode:launch를 권장합니다.
4. W2 — 지도 서명. 제안된 지도를 제시합니다: 목적지, 유형과 차단 관계가 있는 초기 티켓들, 안개 스케치. W2는 선장 서명입니다: 여기서 세분화가 잘못되면 이후 모든 세션이 낭비됩니다. 서명될 때까지 반복합니다.
5. 지도와 티켓 생성. 지도에 navigator:map 레이블을 붙입니다; 하위 티켓을 생성합니다; 두 번째 패스에서 차단 관계를 연결합니다(이슈는 서로를 참조하려면 ID가 필요합니다). 아직 티켓으로 만들 만큼 선명하지 않은 모든 것은 Not yet specified에 남깁니다.
6. 연구 서브에이전트 실행. 방금 생성된 각 research 티켓에 대해, 백그라운드 서브에이전트를 생성하여 병렬로 해결합니다(티켓 유형 참조), 티켓이 링크할 수 있는 곳에 결과를 캡처합니다.
7. 세션 종료 포인터와 함께 중단합니다: 지도 링크, 프론티어에 있는 티켓 수, "다음 세션에 /oh-my-claudecode:ask-navigator를 실행하여 다음 결정을 처리하세요."

지도 작업

지도(링크 또는 번호)와 함께 호출되거나 인수 없이(열린 지도를 이어받음) 호출됩니다. 티켓은 선택 사항입니다: 티켓 없이 다음 프론티어 티켓을 가져오며, 선장이 선택해야 하는 것은 아닙니다.

1. 지도 로드: 저해상도 뷰, 모든 티켓 본문은 아닙니다. 필요 시 티켓 전체 본문으로 확대합니다.
2. 작업 전 할당: 티켓을 선장에게 할당(트래커)하거나 Claimed-by를 설정(로컬)하여 먼저 동시 세션이 건너뛰도록 합니다. 열려 있고 할당되지 않은 티켓은 할당되지 않은 상태입니다. 할당이 불가능하면(권한 문제, 핸들 없음), 대신 티켓 댓글에 할당을 기록합니다.
3. 유형에 따라 해결(티켓 유형 참조). 필요에 따라 확대/축소합니다; 해결에 선장의 입력이 필요할 때마다 "deep-interview"와 함께 스킬 도구를 호출합니다.
4. 해결 기록: 답변을 해결 댓글/섹션으로 게시하고, 티켓을 닫고(완료로; 목적지 범위 밖으로 판단된 티켓은 'not planned'으로 닫음), 지도의 Decisions so far에 한 줄을 추가합니다 — [<티켓 제목>](링크): <한 줄 요약>.
5. 프론티어 전진: 답변이 명세 가능하게 만든 모든 안개를 졸업시킵니다(Not yet specified에서 제거하고 새 티켓을 생성하며 관계를 연결함); 답변이 티켓이 목적지 범위 밖에 있음을 드러내면 닫고 Out of scope에 한 줄을 남깁니다; 결정이 무효화한 티켓을 업데이트하거나 삭제합니다.
6. 퇴적물(퇴적물 참조).
7. 하나의 티켓 후 중단. 세션당 하나의 해결이 주기입니다 — 이는 컨텍스트 윈도우 예산이지 정책이 아닙니다. 세션 종료 포인터는 방금 해결된 것과 현재 프론티어에 있는 것을 명명합니다.

티켓 유형

모든 티켓은 HITL(선장과 함께 작업하며, 선장이 스스로를 대변) 또는 AFK(네비게이터만으로 처리)입니다. HITL 티켓은 실시간 교환을 통해서만 해결됩니다; 에이전트는 절대 선장의 역할을 대신하지 않습니다.

유형	모드	해결 방법	사용 시기
research	AFK	백그라운드 서브에이전트: 1차 출처(공식 문서, 소스 코드, 명세)를 조사하고, 인용된 마크다운 파일을 docs/research/<ticket-slug>.md에 남기고(또는 기존 관례가 있는 경우 저장소의 기존 노트 관례 사용), 티켓에서 링크	결정이 현재 작업 디렉토리 외부의 지식을 기다림
loft	HITL	"loft"와 함께 스킬 도구 호출: 티켓의 질문에 답하는 일회용 아티팩트 — 클릭 가능한 셸의 순수 로직 모듈, 또는 하나의 라우트 뒤에 있는 구조적으로 다른 UI 변형; 선장이 반응하고, 답변이 해결에 통합되며, 아티팩트는 loft/<name> 브랜치에 유지	질문은 정확하지만 산문으로는 해결할 수 없음 — 설명이 아닌 보거나 클릭해야 함
grilling	HITL	"deep-interview"와 함께 스킬 도구 호출; 각 라운드마다 선장이 결정	대화 자체가 해결 방법 — 기본 사례
task	HITL 또는 AFK	가능한 경우 네비게이터가 단독으로 처리; 그렇지 않으면 선장에게 정확한 체크리스트 전달	결정을 막고 있는 수동 작업(서비스 가입, 액세스 프로비저닝, 모양을 볼 수 있도록 데이터 이동) — 결정을 막는 일을 함으로써 자격을 얻으며, 목적지를 전달하는 것이 아님

답변은 절대 티켓 본문의 일부가 아닙니다; 해결 시 기록됩니다. 해결 중 생성된 자산은 티켓에서 링크되며, 붙여넣지 않습니다.

지도 본문

## 목적지

<이 지도의 끝에 도달했을 때의 모습: 이 작업이 찾아가는 명세, 결정 또는 변경사항. 한두 줄; 모든 세션이 티켓을 선택하기 전에 이를 기준으로 방향을 잡습니다.>

## Notes

<도메인; 모든 세션이 참조해야 할 스킬; 상시 선호사항; 연기된 drydock --check 결과(그대로); 해결된 documentLanguage 태그; 로컬 모드에 대한 트래커 모드 주의사항>

## Decisions so far

<!-- 색인: 닫힌 티켓당 한 줄, 관련성 판단에 충분하며, 세부 사항은 링크로 확대 -->

- [<닫힌 티켓 제목>](링크): <답변의 한 줄 요약>

## Not yet specified

<!-- 범위 내에 있지만 아직 티켓화할 수 없는 안개; 프론티어가 전진함에 따라 졸업함 -->

## Out of scope

<!-- 목적지 범위 밖으로 판단된 작업; 닫혔으며 절대 졸업하지 않음 -->

안개인가 티켓인가? 기준은 지금 질문을 정확히 말할 수 있는지 여부이지, 지금 답할 수 있는지가 아닙니다. 질문이 이미 선명하다면(차단되어 있더라도) 티켓화하세요. 그렇게 선명하게 표현할 수 없으면 Not-yet-specified로 남깁니다 — 안개를 티켓 크기로 미리 자르지 마세요; 하나의 안개 덩어리가 여러 티켓으로 졸업하거나 아예 없을 수도 있습니다. Out of scope는 범위 설정 행위이지 경로의 단계가 아닙니다: 범위(선명도가 아님)가 작업을 여기에 배치하며, 목적지가 다시 그려질 때만 돌아올 수 있습니다.

퇴적물

해결 결과는 결정되는 즉시 Shipyard의 문서 흔적에 기록됩니다 — launch의 Phase 1이 사용하는 동일한 슬롯입니다:

• 해결이 정리하거나 선명하게 만든 용어 → CONTEXT.md 용어집 (항목당 하나: 정의, 경계, 해결된 모호성)
• ADR 테스트를 통과한 결정(되돌리기 어렵고, 컨텍스트 없이 놀랍고, 실제 트레이드오프가 있는 경우) → docs/adr/NNNN-<slug>.md
• 비즈니스 규칙 또는 배경 사실 → docs/business/ (비즈니스 질문당 하나의 문서)

야드가 설치되지 않은 경우(선장이 차팅 시 drydock을 거절함), 건너뛰지 말고 연기하세요: 각 보류 중인 랜딩을 지도의 Notes에 Deferred sediment 제목 아래 한 줄로 기록합니다. 이후 /oh-my-claudecode:launch 실행의 야드 게이트가 설치되지 않은 표면을 결과로 처리하고, 연기된 줄이 정확히 무엇을 먼저 랜딩해야 하는지 알려줍니다.

종료 — 핸드오프, 구축하지 않음

지도는 열린 티켓이 없고 Not yet specified이 비어 있을 때 완료됩니다. 그런 다음:

1. Decisions so far를 미션 브리프로 축소합니다: 목표, 범위 경계, 비목표 — 경로가 명확해졌으므로 이제 작성 가능합니다. .omc/wayfinder/<map-slug>/brief.md에 작성하여 핸드오프가 내용이 아닌 포인터를 전달하도록 합니다.
2. 권장: "경로가 명확합니다. .omc/wayfinder/<map-slug>/brief.md의 브리프와 함께 /oh-my-claudecode:launch를 실행하세요." 지도는 작업의 로그북으로 남습니다; launch의 야드 게이트가 그 시점부터 모든 검사를 소유합니다.
3. 기본 진입점은 launch Phase 1입니다(문서 흔적은 이미 반쯤 채워져 있으며; 프론티어가 빠르게 정리됩니다). 결정이 이미 명세처럼 읽힐 때만 명세를 초안하고 launch의 Phase 2에 명세 경로로 진입할 수 있습니다.

범위 및 비목표

• 데몬, 모드, 항상 켜짐 동작, 런타임 상태 머신 없음: 지도는 일반 트래커 이슈 또는 저장소 파일입니다.
• 안개로 들어오는 요청은 항구가 라우팅할 몫입니다: /oh-my-claudecode:harbor가 넘겨준 모호한 이슈는 원래 스레드와 서명된 결정 링크를 재료로 다른 느슨한 아이디어처럼 차팅됩니다.
• Team 라이프사이클, 작업 상태 또는 런타임 상태를 절대 변경하지 않습니다; 전달 티켓을 절대 게시하지 않습니다 — 수직 슬라이스 빌드 티켓은 launch의 C3에 속하며, 네비게이터는 그 안으로 안개를 미리 자르면 안 됩니다.
• 결정을 기록하는 것 외에 절대 실행하지 않습니다. 유일한 예외는 task 티켓으로, 결정을 막는 일만 수행합니다.
• 지도의 Decisions-so-far는 색인입니다; 결정은 정확히 한 곳, 자신의 티켓에 있습니다.

완료 정의

차팅 세션은 선장이 서명한 지도와 실행된 연구 티켓으로 끝납니다. 작업 세션은 정확히 하나의 해결이 기록되고, 프론티어가 전진되며, 세션 종료 포인터가 출력되면서 끝납니다. 작업은 경로가 명확해지고 미션 브리프가 선장의 손에 있으며 /oh-my-claudecode:launch가 권장될 때 종료됩니다 — 네비게이터가 선장을 대신하여 내린 모든 결정은 기록된 위치를 가리키는 하나의 포인터로 답변 가능합니다.