Merge pull request #11 from rnqhstmd/feat/grill-me-and-phase0

[FEATURE] 순차 QA와 Phase 0 API + Jina Reader를 도입한다.

Author: rnqhstmd

.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "ttutak",
       "source": "./",
       "description": "개발 자동화 플러그인. PRD, 설계, 구현, 리뷰, PR까지 에이전트 팀이 처리합니다.",
-      "version": "1.3.0"
+      "version": "1.4.0"
     }
   ]
 }

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ttutak",
   "description": "개발 자동화 플러그인. PRD, 설계, 구현, 리뷰, PR까지 에이전트 팀이 처리합니다.",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "author": {
     "name": "rnqhstmd"
   },

.claude/skills/context/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: context
-version: 1.0.0
+version: 1.1.0
 description: |
   도메인 컨텍스트 관리. 신규 생성, 문서 기반 생성, 코드베이스 스캔, 기존 도메인 갱신, git 히스토리 기반 진행도 동기화를 상황에 맞게 자동 판단합니다.
+  Q&A는 1문 1답 순차로 진행하며 권장 답변을 제시합니다.
   context/{도메인}/ 디렉토리와 README.md, PROJECTS.md, glossary.md, architecture.md를 만듭니다.
 argument-hint: "[도메인명] [--from <파일경로>] [--sync]"
 allowed-tools:
@@ -40,7 +41,8 @@ Arguments 문자열에서 아래 규칙으로 파싱한다:
 - **모호하고 일반적인 표현을 허용하지 않는다.** 답변이 "효율화", "개선" 같은 추상어로만 구성되면 구체화를 요청한다.
 - **누락된 데이터를 가정하지 않는다.** 사용자가 모르는 항목은 ❓로 남기되, 빈칸이 있다는 것을 명시한다.
 - **정량화를 요구한다.** "많이", "자주" 대신 숫자를 묻는다. 정확하지 않아도 추정치라도 기록한다.
-- **충분한 정보가 모일 때까지 산출물로 넘어가지 않는다.** 필수 질문 답변이 모두 모호하면 1라운드 더 진행한다.
+- **충분한 정보가 모일 때까지 산출물로 넘어가지 않는다.** 모호한 답변에는 그 자리에서 파고들기 질문으로 구체화를 요청하고, 충분한 정보가 모인 후에만 다음 단계로 진행한다.
+- **모든 질문에 권장 답변을 제시한다.** 사용자가 결정 부담을 덜 수 있도록, 현재 맥락에서 가장 가능성 높은 답 또는 합리적 추정을 options 첫 번째에 `(Recommended)` 라벨로 반드시 제시한다.
 
 ## 모드 자동 판단
 
@@ -164,45 +166,77 @@ Q&A 기반으로 새 도메인을 생성한다.
 - 인자가 없으면 도메인명과 한 줄 설명을 묻는다.
 - `context/{도메인}/`이 이미 존재하면 갱신 모드(D)로 전환할지 묻는다.
 
-### B-2. 검증 질문 (1라운드)
-
-AskUserQuestion으로 아래 5개를 한 번에 묻는다:
-
-1. **문제**: 이 도메인에서 풀려는 문제가 뭔가?
-2. **현재 프로세스**: 지금은 어떻게 하고 있는가?
-3. **안 하면**: 이걸 안 하면 어떻게 되는가?
-4. **사용자/규모**: 예상 사용자와 규모는?
-5. **담당**: 이 도메인의 담당 PM/PO와 주요 개발자는?
-
-### B-3. 답변 품질 판단
-
-답변을 받은 뒤 아래를 확인한다:
-
-- 5개 중 3개 이상 구체적 → **B-4단계로 진행**
-- 모호한 답변이 3개 이상 → **심화 질문 1라운드 추가** (B-3-1단계)
-
-모호함 판단 기준:
+### B-2. 순차 검증 질문
+
+아래 5개 질문을 프레임으로 삼아 **1개씩 순차적으로** 질문한다. 각 답변에 따라 다음 행동이 결정된다.
+
+**질문 프레임 (순서대로)**:
+1. 이 도메인에서 풀려는 문제가 뭔가요?
+2. 지금은 어떻게 하고 있나요?
+3. 이걸 안 하면 어떻게 되나요?
+4. 예상 사용자와 규모는?
+5. 이 도메인의 담당 PM/PO와 주요 개발자는?
+
+**순차 질문 루프** (모든 프레임이 완전히 해소될 때까지):
+
+1. 현재 프레임의 질문을 `AskUserQuestion(questions: [질문 1개])`으로 제시한다. **권장 답변(코드베이스/git blame/맥락에서 추정한 답)을 options 첫 번째에 `(Recommended)` 라벨로 제시**한다. 단, Q1(문제)·Q3(안 하면) 같은 주관 영역으로 추정이 어색한 경우, 발상 기준점을 주기 위해 예시 후보 1개를 `{ label: "예: ..." }` 형식으로 대체 제시한다.
+
+   `options` 구조:
+   - 권장 답변 가능: `{ label: "{권장 답변} (Recommended)", description: "권장 답변 설명" }`
+   - 권장 답변 어려운 주관 영역: `{ label: "예: {예시}", description: "발상 기준점" }` (선택적)
+   - `{ label: "Other로 입력", description: "Other로 이동해서 자연어로 답변을 입력해주세요" }`
+   - `{ label: "모르겠음", description: "아직 불명확합니다" }`
+
+2. 답변을 평가한다:
+   - **명확하고 충분**: 다음 프레임으로 이동
+   - **모호하거나 불완전**: 파고들기 질문을 생성하여 현재 위치에 이어서 진행 (파고들기 질문에도 동일 규칙((Recommended) 또는 예시 후보 + Other)이 적용된다). **파고들기는 같은 프레임에서 최대 2회까지만 반복**한다. 2회 초과 시 ❓로 기록하고 강제로 다음 프레임으로 이동한다.
+   - **결정 의존성 발견**: 이 답변이 후속 프레임의 전제 또는 형태를 바꾸면, 영향받는 프레임을 재구성하거나 종속 질문을 추가한다.
+   - **코드베이스로 답 가능**: 직접 탐색(Glob/Grep/Read) 후 확인하고 다음 프레임으로 이동
+   - **"모르겠음" 선택**: ❓로 기록하고 다음 프레임으로 이동
+
+3. 모든 프레임이 해소되면 **공유 이해 확인(align)** 단계를 거친다. 수렴된 답변을 "프레임 → 답변" 형식으로 요약하여 다음과 같이 확인한다:
+   ```
+   AskUserQuestion(
+     questions: [{
+       question: "정리된 답변을 context 작성에 사용하기 전에 확인해주세요.\n\nQ1: 문제 → ...\nQ2: 현재 프로세스 → ...\nQ3: 안 하면 → ...\nQ4: 사용자/규모 → ...\nQ5: 담당 → ...",
+       header: "정리 확인",
+       options: [
+         { label: "맞습니다 (Recommended)", description: "이대로 context 작성으로 진행" },
+         { label: "수정 필요", description: "Other로 이동해서 수정할 질문 번호와 새 답변을 입력해주세요 (예: 'Q3: 마이그레이션 리스크 누적')" }
+       ],
+       multiSelect: false
+     }]
+   )
+   ```
+   "맞습니다"면 B-4로 진행. "수정 필요"면 사용자가 Other에 입력한 `Q번호: 새 답변` 패턴을 파싱하여 해당 프레임을 재질문 큐에 추가한 뒤 루프 재진입한다. 입력이 패턴과 일치하지 않거나 번호를 식별할 수 없으면, 어떤 프레임을 수정할지 선택형 질문으로 다시 묻는다. **Align 라운드는 최대 3회**로 제한한다. 3회 초과 시 마지막 답변으로 강제 확정하고 미해결 프레임을 ❓로 기록한 뒤 B-4로 진행한다.
+
+**모호함 판단 기준**:
 - 정량 수치 없이 "많다", "자주", "크다"만 있는 경우
 - 대상이 불명확한 경우 ("사용자들", "팀원들")
 - "효율화", "개선", "자동화" 등 추상어만 있는 경우
 
-### B-3-1. 심화 질문 (선택적, 최대 1라운드)
-
-모호했던 항목에 대해서만 구체화를 요청한다:
-
-- 현재 프로세스 비용을 정량화할 수 있는가? (주당 시간, 빈도, 인력)
-- 성공 기준을 숫자로 말할 수 있는가?
-- 더 단순한 대안은 검토했는가?
-- 실패 시 영향 범위는?
-
-여전히 모르는 항목은 ❓로 남기고 진행한다. 2라운드 이상 반복하지 않는다.
+**파고들기 예시**:
+- 수치가 없으면: "주당 몇 시간, 혹은 월 몇 건 규모인가요?"
+- 대상이 모호하면: "구체적으로 어떤 팀/역할의 사용자인가요?"
+- 추상어만 있으면: "'효율화'가 달성되면 현재 대비 무엇이 어떻게 달라지나요?"
 
 ### B-4. 관련 프로젝트 확인
 
-AskUserQuestion으로 묻는다:
-- **관련 레포**: 이 도메인과 관련된 GHE 레포가 있는가? (예: `xx/factory-api`, `yy/factory-admin`)
+```
+AskUserQuestion(
+  questions: [{
+    header: "관련 레포",
+    question: "이 도메인과 관련된 GHE 레포가 있습니까? (예: xx/factory-api, yy/factory-admin)",
+    multiSelect: false,
+    options: [
+      { label: "Other로 입력", description: "Other로 이동해서 관련 레포 목록을 자연어로 입력해주세요" },
+      { label: "없음", description: "빈 테이블로 생성합니다" }
+    ]
+  }]
+)
+```
 
-레포가 있으면 각 레포의 역할도 함께 기록한다. 아직 없으면 빈 테이블로 생성한다.
+Other로 입력받은 레포 목록을 파싱하여 각 레포의 역할도 함께 기록한다. "없음"이면 빈 테이블로 생성한다.
 
 ### B-5. 디렉토리 및 문서 생성
 
@@ -372,10 +406,7 @@ PM이 정리한 텍스트 파일을 읽어서 context를 생성하거나 갱신
 
 #### C-3-3. 답변 품질 판단
 
-모드 B-3과 동일한 기준을 적용한다:
-- 5개 중 3개 이상 구체적 → C-4로 진행
-- 모호한 답변이 3개 이상 → 심화 질문 1라운드 추가 (B-3-1 절차와 동일)
-- 여전히 모르는 항목은 ❓로 남기고 진행한다. 2라운드 이상 반복하지 않는다.
+모드 B-2의 "순차 질문 루프 → 2. 답변을 평가한다" 분기 기준을 동일하게 적용한다 (명확/모호/의존성/코드베이스/모르겠음). 모호한 답변에는 파고들기 질문으로 그 자리에서 구체화를 요청하고, 여전히 모르는 항목은 ❓로 남기고 진행한다.
 
 ### C-4. context 생성 또는 갱신
 

.claude/skills/dev/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: dev
-version: 1.1.0
-description: "PRD → 설계 → 구현 → 리뷰 → 커밋/PR까지 전체 개발 사이클을 에이전트 팀이 Q&A 루프로 수행"
+version: 1.2.0
+description: "PRD → 설계 → 구현 → 리뷰 → 커밋/PR까지 전체 개발 사이클을 에이전트 팀이 순차 Q&A 루프로 수행"
 argument-hint: "<자연어 요청>"
 allowed-tools: ["Bash(git *)", "Bash(test *)", "Bash(mkdir *)", "Bash(cp *)", "Bash(mv *)", "Bash(ls *)", "Bash(find *)", "Bash(pwd *)", "Bash(basename *)", "Bash(dirname *)", "Bash(which *)", "Bash(./gradlew *)", "Bash(gh *)", "Bash(GH_HOST= *)", "Read", "Edit", "Write", "Glob", "Grep", "Task", "AskUserQuestion", "Skill"]
 ---
@@ -56,17 +56,20 @@ BASE 추출: `{branch}에서`, `{branch} 기반`, `{branch} 브랜치`에서 bra
 
 ```
 AskUserQuestion(
-  question: "어떤 방식으로 진행할까요?",
-  options: [
-    { value: "normal", label: "전체 파이프라인 — PRD → 설계 → 구현 → 리뷰 → PR" },
-    { value: "hotfix", label: "긴급 수정 — 경량 PRD → 구현 → PR" },
-    { value: "implement", label: "구현만 — 설계 없이 바로 구현" }
-  ],
-  description: "요청: {ARGS[0]}"
+  questions: [{
+    header: "진행 방식",
+    question: "어떤 방식으로 진행할까요? (요청: {ARGS[0]})",
+    multiSelect: false,
+    options: [
+      { label: "전체 파이프라인", description: "PRD → 설계 → 구현 → 리뷰 → PR" },
+      { label: "긴급 수정", description: "경량 PRD → 구현 → PR" },
+      { label: "구현만", description: "설계 없이 바로 구현" }
+    ]
+  }]
 )
 ```
 
-- `normal` 선택 → NORMAL 모드 (전체 Phase 실행)
+- `전체 파이프라인` 선택 → NORMAL 모드 (전체 Phase 실행)
 - `hotfix` 선택 → HOTFIX 모드
 - `implement` 선택 → 경량 구현 모드: setup → implement → complete (설계/리뷰 생략, 커밋/PR은 포함)
 
@@ -465,15 +468,18 @@ Agent에게 변경사항 diff를 전달할 때, 메인 컨텍스트 절약을 
 **유형: 선택** → AskUserQuestion 선택형:
 ```
 AskUserQuestion(
-  question: "질문 텍스트",
-  options: [
-    { value: "a", label: "레이블 — 설명" },
-    { value: "b", label: "레이블 — 설명" },
-    { value: "c", label: "직접 입력 — 위 선택지 외 직접 입력합니다" }
-  ],
-  description: "맥락 텍스트"
+  questions: [{
+    header: "카테고리",
+    question: "질문 텍스트 (맥락이 있으면 질문에 포함)",
+    multiSelect: false,
+    options: [
+      { label: "레이블A", description: "설명" },
+      { label: "레이블B", description: "설명" }
+    ]
+  }]
 )
 ```
+> 도구가 "Other" 선택지를 자동으로 제공하므로 별도 "직접 입력" 옵션을 만들지 않는다. 사용자가 Other를 선택하면 자유 입력 창이 자동으로 열린다.
 
 **유형: 자유입력** → AskUserQuestion 자유입력형:
 ```
@@ -486,21 +492,50 @@ AskUserQuestion(
 #### 변환 규칙
 
 - **(권장)** 표시가 있는 선택지는 options 배열의 첫 번째에 배치한다.
+- **모든 질문에 권장 답변을 `(Recommended)` 라벨로 제시한다.** 코드베이스/git blame/맥락에서 추정 가능하면 그 답을, 주관 영역이면 발상 기준점용 `예: {예시}` 옵션으로 대체한다.
 - **"직접 입력"** 선택지는 항상 마지막에 배치한다. 사용자가 이 옵션을 선택하면 후속 AskUserQuestion(자유입력)으로 직접 값을 받는다.
-- 질문이 **2개 이상**이면 순서대로 하나씩 AskUserQuestion을 호출한다. 이전 답변이 다음 질문의 맥락에 영향을 주는 경우 반영한다.
+- 질문이 **2개 이상**이면 **반드시 1개씩** 순서대로 AskUserQuestion을 호출한다 (배치 발사 금지). 이전 답변이 다음 질문의 맥락에 영향을 주는 경우 반영한다.
+- **코드베이스로 답할 수 있는 질문은 사용자에게 묻지 않고 직접 탐색한다** (Glob/Grep/Read).
+- **결정 의존성**: 한 답변이 후속 질문의 전제를 바꾸면 후속 질문을 재구성하거나 종속 질문을 추가한다.
 - 에이전트가 기술 용어를 사용한 경우, 사용자에게 표시할 때 **비기술적 표현으로 의역**한다. 예: "JWT vs 세션" → "로그인 유지 방식".
 - multiSelect가 필요한 경우(에이전트가 "복수 선택 가능"으로 표시): `multiSelect: true`를 추가한다.
 
+#### Align 단계 (순차 변환 종결)
+
+순차 변환으로 모든 질문이 해소되면, 수렴된 답변을 `Q번호: 답변` 형식으로 요약하여 `맞습니다 (Recommended) / 수정 필요` 확인을 받는다.
+
+```
+AskUserQuestion(
+  questions: [{
+    header: "정리 확인",
+    question: "정리된 답변을 산출물 작성에 사용하기 전에 확인해주세요.\n\nQ1: ... → ...\nQ2: ... → ...\n...",
+    multiSelect: false,
+    options: [
+      { label: "맞습니다 (Recommended)", description: "이대로 다음 단계로 진행" },
+      { label: "수정 필요", description: "Other로 이동해서 'Q번호: 새 답변' 형식으로 입력해주세요" }
+    ]
+  }]
+)
+```
+
+"수정 필요" 시 사용자가 Other에 입력한 `Q번호: 새 답변` 패턴을 파싱하여 해당 질문만 재발사한다. 패턴 불일치 시 어떤 질문을 수정할지 선택형으로 재질의한다. **Align 라운드는 최대 3회**로 제한한다. 3회 초과 시 마지막 답변으로 강제 확정하고 미해결 항목을 ❓로 기록한 뒤 다음 단계로 진행한다.
+
+> **AskUserQuestion 스키마 주의**: 도구는 `options.items.required = ["label", "description"]`만 허용하고 `value` 필드를 받지 않는다 (`additionalProperties: false`). 모든 옵션은 `label`만으로 식별하며, 사용자가 선택한 라벨이 `answers` 객체에 그대로 반환된다.
+
 #### 승인/수정 공통 패턴
 
 산출물(PRD, 설계서, 구현 계획) 확인 시 공통으로 사용하는 AskUserQuestion 패턴:
 ```
 AskUserQuestion(
-  question: "{산출물}을 확인해주세요.",
-  options: [
-    { value: "approve", label: "승인 — 다음 단계로 진행" },
-    { value: "modify", label: "수정 요청 — 수정할 부분을 알려주세요" }
-  ]
+  questions: [{
+    header: "산출물 확인",
+    question: "{산출물}을 확인해주세요.",
+    multiSelect: false,
+    options: [
+      { label: "승인", description: "다음 단계로 진행" },
+      { label: "수정 요청", description: "Other로 이동해서 수정할 부분을 자연어로 입력해주세요" }
+    ]
+  }]
 )
 ```
 사용자가 "수정 요청"을 선택하면 후속 AskUserQuestion(자유입력)으로 수정 내용을 받는다.

.claude/skills/dev/phases/phase-design.md

@@ -47,18 +47,24 @@ design-critic 결과 처리:
 
 **질문이 있으면** ("추가 확인 사항 없음"이 포함되지 않은 경우):
 - 설계 초안을 사용자에게 출력한다.
-- Agent 출력의 "확인이 필요한 사항"을 **에이전트 질문 → AskUserQuestion 변환 규칙** (SKILL.md 공유 규칙)에 따라 변환하여 사용자에게 순서대로 제시한다.
+- Agent 출력의 "확인이 필요한 사항"을 **에이전트 질문 → AskUserQuestion 변환 규칙** (SKILL.md 공유 규칙)에 따라 변환하되, **반드시 1개씩 순차 발사**하고 각 질문에 `(Recommended)` 권장 답변을 제시한다. 코드베이스로 답할 수 있는 질문은 사용자에게 묻지 않고 직접 탐색한다.
+- design-critic의 도전 사항(있으면)도 동일 규칙으로 1개씩 순차 발사한다. 단, MUST-ADDRESS 항목 표시는 Step 3의 기존 규칙대로 1개 메시지로 묶어 보여주고, 사용자 선택이 필요한 항목만 순차 발사한다.
+- 모든 질문이 해소되면 SKILL.md "Align 단계" 규칙에 따라 `Q번호: 답변` 요약 후 `맞습니다 / 수정 필요` 확인을 받는다.
 - 사용자 답변을 수렴하여 다음 반복으로 전달.
 
 **질문이 없으면** ("추가 확인 사항 없음. 설계가 완료되었습니다."):
 - **승인/수정 공통 패턴** (SKILL.md 공유 규칙)에 따라 AskUserQuestion을 사용한다:
   ```
   AskUserQuestion(
-    question: "설계를 확인해주세요.",
-    options: [
-      { value: "approve", label: "승인 — 구현 단계로 진행" },
-      { value: "modify", label: "수정 요청 — 수정할 부분을 알려주세요" }
-    ]
+    questions: [{
+      header: "설계 확인",
+      question: "설계를 확인해주세요.",
+      multiSelect: false,
+      options: [
+        { label: "승인", description: "구현 단계로 진행" },
+        { label: "수정 요청", description: "Other로 이동해서 수정할 부분을 자연어로 입력해주세요" }
+      ]
+    }]
   )
   ```
 - 승인 → phase-implement로 진행.

.claude/skills/dev/phases/phase-implement.md

@@ -55,11 +55,15 @@ hotfix가 아닌 경우 아래 정상 플로우를 따른다.
 4. AskUserQuestion으로 승인을 받는다:
    ```
    AskUserQuestion(
-     question: "구현 계획을 확인해주세요.",
-     options: [
-       { value: "approve", label: "승인 — 구현 시작" },
-       { value: "modify", label: "수정 요청 — 변경할 항목을 알려주세요" }
-     ]
+     questions: [{
+       header: "구현 계획",
+       question: "구현 계획을 확인해주세요.",
+       multiSelect: false,
+       options: [
+         { label: "승인", description: "구현 시작" },
+         { label: "수정 요청", description: "Other로 이동해서 변경할 항목을 자연어로 입력해주세요" }
+       ]
+     }]
    )
    ```
    - **승인** → Step 1.5 (배치 구성)으로 진행.