docs(agents): 스킬 선택과 실행 우선순위를 정한다

AGENTS.md

@@ -71,16 +71,9 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
 **These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
 
 ## 지시 우선순위
-충돌 시 항상 더 높은 우선순위의 지시를 따른다.
+우선순위는 1) system/developer 지시와 플랫폼 도구 권한, 2) 사용자의 명시적 요청, 3) 이 저장소의 CORE EXECUTION PRINCIPLES 및 적용 가능한 프로젝트 규칙, 4) 아래 프로젝트 실행 생명주기, 5) 활성화된 전문 스킬의 작업 범위, 6) 플러그인 실행 선호와 기본 모델 동작 순이다. 상위 역할의 지시와 도구 권한을 Markdown으로 변경하거나 우회하지 않는다. 사용자 요청도 상위 지시 및 도구 권한을 넘을 수 없다.
 
-1. 사용자 직접 지시
-2. `AGENTS.md`
-3. 프로젝트별 제약 조건
-4. `oh-my-openagent` 플러그인의 `agents` / `workflows` / `hooks`
-5. `superpowers` skills
-6. 기본 모델 동작
-
-사용자 직접 지시가 명확할 경우 사용자 지시가 최우선이다. plugin / skill / workflow 지시가 `CORE EXECUTION PRINCIPLES`와 충돌하면 `CORE EXECUTION PRINCIPLES`를 따른다. 불확실하거나 모호한 경우 추측하지 말고 확인하거나, 가능한 최소 범위의 안전한 조치를 취한다.
+프로젝트가 통제하는 절차에서는 Superpowers가 주 생명주기이며, 전문 스킬은 해당 단계의 좁은 전문 영역을 맡는다. 플러그인은 도구와 실행 보조를 제공할 뿐 별도의 경쟁 절차를 만들지 않는다. 플러그인에 주입된 상위 역할 지시는 이 문서로 덮어쓸 수 없다. 불확실하면 근거를 확인하고 최소 안전 범위에서 진행한다.
 
 ## 커뮤니케이션 규칙
 - **"질문에 대한 답변과 설명은 한국어로 한다."**
@@ -109,24 +102,42 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
 - 최소 변경
 - 단순한 구현
 - 검증 가능한 결과
+- 요청이 구체적이면 불필요한 인터뷰 없이 관련 생명주기의 첫 미완료 단계부터 시작한다.
 
 ### 확장 모드
-- 사용자가 명시적으로 요청한 경우에만 사용한다.
-- 대규모 리팩토링, 브레인스토밍, 다중 에이전트 실행, 병렬 workflow를 허용한다.
+- 대규모 리팩터링, 다중 에이전트 실행, 병렬 workflow 확장은 사용자가 명시적으로 허용한 경우에만 한다. 작은 작업은 단일 경로로 처리한다.
 
-## oh-my-openagent 제어 정책
-- `oh-my-openagent`는 opencode의 플러그인 기반 실행 오케스트레이션 계층이다.
-- `oh-my-openagent`는 의사결정 권한이 아니라 실행 보조 권한만 가진다.
-- 작은 작업에는 multi-agent 실행이나 과도한 workflow를 사용하지 않는다.
-- 병렬 실행은 명확한 이득이 있을 때만 사용한다.
-- 모든 `oh-my-openagent` 동작은 `CORE EXECUTION PRINCIPLES`를 따라야 한다.
+## Skill Orchestration
 
-## superpowers 사용 정책
-- `superpowers`는 선택적 스킬 계층이다.
-- `superpowers` skill은 필요한 경우에만 사용한다.
-- `superpowers`가 과도한 리팩토링, 불필요한 범위 확장, 가정 기반 실행을 유도하면 따르지 않는다.
-- `superpowers`를 사용할 때도 최소 변경, 단순성, 검증 가능성을 우선한다.
-- 모든 `superpowers` 동작은 `CORE EXECUTION PRINCIPLES`를 따라야 한다.
+작업을 시작할 때 질문/조사, 신규 설계, 불명확한 요구사항, 버그, 아키텍처, API, 보안, 리뷰, 테스트/검증, 기존 작업 이어하기 중 하나 이상으로 분류한다. 활성 하위 단계마다 주 소유 스킬 하나를 정하고, 필요한 좁은 보완 스킬만 추가한다. 현재 호스트에서 발견·접근 가능한 스킬만 사용하고, implicit 선택이 허용된 경우에도 `deny`/`ask` 및 agent/tool 권한을 준수한다. 스킬이 없거나 접근이 막히면 한계를 알리고 가능한 부분만 수행한다. 호스트가 현재 해석한 설치 스킬 본문을 먼저 읽는다. 이미 로드된 동일 본문과 끝난 질문·계획·리뷰 결과는 재사용하며 되풀이하지 않는다. 일반 질문·조사·문서 작업은 제품 구현 생명주기를 자동 시작하지 않는다.
+
+| 작업 | 주 생명주기와 선택 스킬 |
+|---|---|
+| 새 기능/설계 | Superpowers `brainstorming`으로 설계. 필요할 때만 `deep-interview`, `domain-modeling`, `codebase-design`을 좁게 보완한다. |
+| 요구사항이 중요하게 미정 | 임시 소유자 `deep-interview`; 아래 종료 기준을 만족하면 요약을 기존 PRD에 통합하고 설계 단계로 이동한다. |
+| 도메인 용어/사업 모델 변경 | 실제 용어집 또는 도메인 모델 변경이면 `domain-modeling`; 단순 조회에는 호출하지 않는다. |
+| REST/API 설계 | `brainstorming` 설계 단계 안에서 `api-and-interface-design`으로 계약을 구체화하고, 인증/신뢰 경계가 관련되면 `security-and-hardening`을 보완한다. |
+| 버그 | `systematic-debugging` → 재현 회귀 테스트/TDD → 단일 실행 경로 → 해당 시 `requesting-code-review` → `verification-before-completion`. |
+| 아키텍처 검토 | 목적에 맞는 읽기 전용 분석. 구체적 대안 설계는 `codebase-design`; 별도 사용자 요청 없이는 HTML/그릴 워크플로를 자동 호출하지 않는다. |
+| 계획 | `writing-plans`. 승인된 설계와 유효한 계획이 함께 있으면 첫 미완료 단계부터 이어가고, 설계만 확정됐다면 새 인터뷰 없이 빠진 계획만 작성한다. |
+| 계획 실행 | `executing-plans` 또는 `subagent-driven-development` 중 하나만 사용한다. 실제 도구가 지원하고 사용자가 고른 방법 및 독립성에 맞춘다. 둘을 중첩하지 않는다. |
+| 구현 테스트 단계 | `test-driven-development`; 버그 경로에서는 `systematic-debugging`이 진단을 소유하고 TDD는 회귀 테스트 단계만 맡는다. |
+| 코드 리뷰/피드백 | 완료된 작업의 단일 리뷰는 `requesting-code-review`; 보안 기준이 필요하면 범위를 좁혀 보완한다. 받은 피드백의 기술적 평가는 `receiving-code-review`. |
+| CI/CD, UI, 운영성, 성능 | 실제 pipeline 변경에는 `ci-cd-and-automation`, UI/accessibility 작업에는 `frontend-ui-engineering`, telemetry에는 `observability-and-instrumentation`, 측정된 bottleneck에는 `performance-optimization`을 조건부 보완으로 사용한다. |
+| 검증/통합 | 완료 주장 전 `verification-before-completion`. `finishing-a-development-branch`는 통합이 실제 범위일 때만 사용하며, 요청 없는 commit/push/정리를 하지 않는다. |
+| 격리/병렬 읽기 | 실제 구현 경로가 필요할 때 기존/native 격리 수단을 먼저 확인하는 `using-git-worktrees`. 독립 읽기 트랙 병렬화는 허용된 경우에만 `dispatching-parallel-agents`; SDD 구현자를 별도로 병렬 중첩하지 않는다. |
+
+`deep-interview`는 목표, 범위, 제약, 성공 기준, 맥락 중 중요한 미해결 사항이 있거나 해석이 충돌/핵심 조건이 빠졌거나 사용자가 명시한 경우에만 잠시 소유한다. 질문은 한 번에 하나씩 한다. 해당 점수법에서 전체 불확실성 0.20 이하뿐 아니라 모든 중요한 결정이 해결되어야 종료하며, 중요한 차원 하나라도 0.50 이하로 충분히 확정되지 않으면 계속한다. 해결된 문제를 반복 인터뷰하지 않는다. 이 스킬은 산출물/의존성을 정하지 않는다. 자동 `.scratch`나 별도 명세를 만들지 말고 요약을 기존 PRD에 반영한다.
+
+`grilling`은 계획·결정·아이디어 전반에 대한 스트레스 테스트이며 아키텍처 전용이 아니다. 사용자가 원하거나 구체적인 아키텍처 대안을 비교할 때 주로 쓴다. 회차마다 의존 조건이 해결된 질문을 묶어 묻고 답변을 기다리며, 종료 시 사용자의 공유 이해 확인을 받는다. 그릴의 다중 질문 회차와 다른 스킬의 한 번에 하나 질문 규칙을 동시에 적용하지 않는다. `codebase-design`은 모듈 규모와 무관한 depth/seam/locality 및 exposed interface를 다루고, `api-and-interface-design`은 내부·외부 API 계약의 안정성/errors/compatibility를 다룬다. 두 skill을 internal/public로만 나누지 않는다. 둘 다 별도의 전체 설계나 인터뷰 절차를 대체하지 않는다.
+
+### 자동 선택과 실행 경계
+
+- Codex 스킬 자동 호출은 설치 정의의 `agents/openai.yaml` `policy.allow_implicit_invocation: false`로 막을 수 있다(기본값은 true). 명시적 호출은 별개다.
+- OpenCode의 `metadata['opencode/autoinvoke']='false'`는 모델 자동 선택 노출을 숨기지만 직접 호출을 막지 않는다. `permission.skill`의 deny/ask와 agent/tool 권한은 별도 제어다. `disable-model-invocation`은 OpenCode의 문서화된 동등 설정이 아니다.
+- `improve-codebase-architecture`와 `setup-matt-pocock-skills`는 `disable-model-invocation: true` 및 Codex implicit false가 있다. OpenCode autoinvoke metadata는 없어 광고될 수 있다. 프로젝트 정책상 명시 전용이지만 Markdown이 OpenCode backend/hook 차단을 강제하는 것은 아니다. “기존 코드 구조 개선 후보 찾기”나 일반 HTML 요청만으로 실행하지 않는다. 사용자가 skill 이름으로 명시 호출한 경우에만 그 workflow를 고려하며, 요청 범위를 넘어 HTML 생성/브라우저 열기/grilling을 흉내 내지 않는다. 허용된 읽기 전용 `codebase-design` 분석은 별개다. `setup-matt-pocock-skills`는 별도 일회성 명시 요청에만 쓴다.
+- 빠진 스킬이나 필수 참고 파일이 있으면 한계를 알리고 가능한 부분 확인만 한다. 완전한 절차를 수행했다고 주장하지 않는다. 스킬 설치나 메타데이터 변경으로 제한을 우회하지 않는다. gstack은 어느 단계에서도 사용하거나 설치하지 않는다.
+- 웹 대상 스킬의 예시는 적용 가능한 통제만 참고한다. iOS 코드에 서버 cookie/CSP 등을 옮겨 적용하지 않으며 SodaLive의 실제 API와 스타일을 따른다.
 
 ## 에이전트 동작 원칙
 - 추측하지 말고 근거 파일을 읽고 결정한다.
@@ -140,7 +151,7 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
 - iOS 코드 스타일은 `docs/agent-guides/code-style.md`를 참조한다.
 - Cursor/Copilot 규칙은 `docs/agent-guides/sodalive-ios-development.md`를 참조한다.
 - 커밋 상세 가이드/절차는 `.opencode/skills/commit-policy/SKILL.md`를 단일 기준으로 사용한다.
-- 커밋 작업 시작 시 `skill` 도구로 `commit-policy`를 먼저 로드한다.
+- 커밋 작업 시작 시 `commit-policy`를 먼저 로드한다. OpenCode에서는 `skill` 도구를 사용하고, Codex에서는 발견된 `SKILL.md` 또는 `.opencode/skills/commit-policy/SKILL.md`를 읽는다.
 - 기본 커밋 형식은 `<type>(scope): <description>`를 사용하고, 제목(description)은 한글 명령형/간결한 현재형으로 작성한다.
 - `git commit` 직후 `work/scripts/check-commit-message-rules.sh`를 실행해 규칙 준수 여부를 확인한다.
 

docs/agent-guides/agent-execution-policy.md

@@ -1,53 +1,35 @@
 # 에이전트 실행 정책 상세 가이드
 
-`AGENTS.md`의 실행 정책을 보완하는 상세 설명이다. 충돌 시 `AGENTS.md`의 우선순위 체계를 먼저 따른다.
+이 문서는 `AGENTS.md`의 Skill Orchestration 및 우선순위 정책을 보완한다. 지시 우선순위의 기준은 root `AGENTS.md` 하나이며, 이 문서는 별도 계층을 만들지 않는다.
 
-## 우선순위 체계
-아래 순서가 높을수록 우선한다.
+## 충돌 및 소유권
 
-1. 사용자 직접 지시
-2. `AGENTS.md`
-3. 프로젝트별 제약 조건
-4. `oh-my-openagent` 플러그인의 `agents` / `workflows` / `hooks`
-5. `superpowers` skills
-6. 기본 모델 동작
+| 조합 | 공유 작업 | 고유 소유권 | 트리거·순서·우선 |
+|---|---|---|---|
+| `brainstorming` / `deep-interview` | 새 제품 목표와 요구사항 구체화 | brainstorming은 설계, deep-interview는 중요 미결정의 질문/요약 | 목표·범위·제약·성공·맥락의 중요 미결정, 충돌 또는 사용자 요청에서만 deep-interview를 임시 선행 소유자로 쓴 뒤 요약을 기존 PRD에 합치고 brainstorming으로 간다. 확정 사항이면 인터뷰 반복 없이 설계한다. |
+| `brainstorming` / `grilling` | 설계 아이디어와 결정 검토 | brainstorming은 설계안 생성, grilling은 계획·결정·아이디어의 적대적 스트레스 테스트 | 사용자 요청 또는 구체적 대안 비교 시 설계 후 선택적으로 grilling. 모든 설계에 grilling을 붙이지 않는다. 한 번에 하나 질문과 다중 frontier 질문 회차를 병행하지 않는다. |
+| `brainstorming` / `codebase-design` | 모듈 경계 및 설계 판단 | brainstorming은 전체 설계 절차, codebase-design은 모듈 규모와 무관하게 depth/seam/locality 및 exposed interface의 설계 어휘 | 설계 중 구체적인 module seam/interface 문제가 필요할 때 좁게 보완한다. codebase-design만으로 인터뷰나 전체 설계 절차를 대체하지 않는다. |
+| `codebase-design` / `api-and-interface-design` | 모듈/API 경계와 contract | codebase-design은 depth/seam/locality와 module design, api-and-interface-design은 내부·외부 공개 계약의 안정성/errors/compatibility | 내부 type/function 계약이나 REST/GraphQL 계약을 설계할 때 계약 문제는 API 전용 skill owner, seam/depth 문제는 codebase-design owner로 분리한다. 필요한 단계만 순차/보완하고 internal/public 경계로 범위를 제한하지 않는다. |
+| `requesting-code-review` / `security-and-hardening` | 보안 관련 변경 검토 | requesting-code-review는 완료 작업의 단일 리뷰, security-and-hardening은 적용 가능한 보안 기준 | 보안 기준이 필요한 리뷰에서만 좁은 보완으로 사용한다. 별도 보안 리뷰 요구는 보안 범위를 소유하지만 리뷰 절차를 중복하지 않는다. |
+| `systematic-debugging` / 일반 조사 | 실패 현상과 근거 파악 | systematic-debugging은 재현 가능한 버그의 가설 기반 진단, 일반 조사는 질문/정보 수집 | 실패/오동작이면 systematic-debugging으로 원인을 진단한 후 회귀 테스트/TDD, 단일 수정 경로, 검증 순. 버그가 아닌 탐색에는 디버깅 생명주기를 강제하지 않는다. |
 
-충돌 시 항상 더 높은 우선순위의 지시를 따른다. 사용자 직접 지시가 명확할 경우 사용자 지시가 최우선이다.
+한 작업의 실행 단계마다 주 소유자는 하나다. 추가 스킬은 좁은 기준만 보완하며 전체 생명주기를 다시 시작하지 않는다. API 계약·보안 보완은 brainstorming의 설계 단계 안에서 수행하고, 설계가 승인되면 빠진 계획 단계로 인계한다. 이미 승인된 설계와 유효한 계획이 있으면 첫 미완료 단계로 이어간다. 설계만 확정된 경우 계획이 없으므로 `writing-plans`로 계획을 먼저 보완한다. grilling은 회차마다 답변을 기다리고, 의존 결정이 모두 정리된 종료 시점에 공유 이해 확인을 받는다.
 
-## CORE EXECUTION PRINCIPLES 적용
-- plugin / skill / workflow 지시가 `CORE EXECUTION PRINCIPLES`와 충돌하면 `CORE EXECUTION PRINCIPLES`를 따른다.
-- 불확실하거나 모호한 경우 추측하지 말고 확인하거나, 가능한 최소 범위의 안전한 조치를 취한다.
-- 모든 실행은 단순성, 최소 변경, 검증 가능성을 우선한다.
+## 호스트 및 권한 경계
 
-## oh-my-openagent 제어 정책
-- `oh-my-openagent`는 opencode의 플러그인 기반 실행 오케스트레이션 계층이다.
-- `oh-my-openagent`는 의사결정 권한이 아니라 실행 보조 권한만 가진다.
-- 작은 작업에는 multi-agent 실행이나 과도한 workflow를 사용하지 않는다.
-- 병렬 실행은 명확한 이득이 있을 때만 사용한다.
-- 모든 `oh-my-openagent` 동작은 `CORE EXECUTION PRINCIPLES`를 따라야 한다.
+- Codex의 `agents/openai.yaml` `policy.allow_implicit_invocation: false`는 implicit skill invocation을 막는다. OpenAI 공식 문서상 기본값은 true다.
+- OpenCode `metadata['opencode/autoinvoke']='false'`는 모델 자동 선택 노출만 숨기며, 명시적 호출을 막는 권한 규칙이 아니다. `permission.skill`의 `deny`/`ask`와 agent/tool 권한은 별개다. `disable-model-invocation`은 OpenCode native 설정으로 문서화되어 있지 않다.
+- 현재 OpenCode 도구는 이 두 skill을 광고할 수 있다. `improve-codebase-architecture`와 `setup-matt-pocock-skills`는 설치본에서 `disable-model-invocation: true`, Codex implicit false지만 OpenCode autoinvoke metadata가 없다. 따라서 OpenCode 자동 선택을 backend에서 막는다고 주장하지 않는다. 이 프로젝트 정책상 둘 다 명시 skill-name 요청만 허용한다. Markdown은 backend/hook denial을 강제하지 않는다. 구조 개선 후보 탐색만으로 HTML/브라우저/grilling workflow를 실행 또는 흉내 내지 않는다. 일반 HTML 산출물 요청만으로도 improve skill 호출을 승인한 것이 아니다. 허용된 읽기 전용 `codebase-design` 분석은 별개다. setup 스킬은 별도 일회성 요청에만 쓴다.
+- Markdown 정책은 상위 역할/플랫폼 권한을 덮거나 우회하지 않는다. 설치 스킬 또는 필수 참고 파일이 없으면 제한을 알리고 부분 확인만 수행하며 완전한 검증으로 표현하지 않는다. 메타데이터나 전역 설정 변경으로 제한을 우회하지 않는다. gstack은 어느 단계에서도 사용하거나 설치하지 않는다.
+- Addy의 웹 예시는 해당되는 통제만 참고한다. iOS에 서버 cookie/CSP 같은 설정을 이식하지 않고 실제 SodaLive API와 스타일을 따른다.
 
-## superpowers 사용 정책
-- `superpowers`는 선택적 스킬 계층이다.
-- `superpowers` skill은 필요한 경우에만 사용한다.
-- `superpowers`가 과도한 리팩토링, 불필요한 범위 확장, 가정 기반 실행을 유도하면 따르지 않는다.
-- `superpowers`를 사용할 때도 최소 변경, 단순성, 검증 가능성을 우선한다.
-- 모든 `superpowers` 동작은 `CORE EXECUTION PRINCIPLES`를 따라야 한다.
+## 운영 체크
 
-## 실행 모드
-### 기본 모드: 보수적 실행
-- 최소 변경
-- 단순한 구현
-- 검증 가능한 결과
-
-### 확장 모드
-- 사용자가 명시적으로 요청한 경우에만 사용한다.
-- 대규모 리팩토링, 브레인스토밍, 다중 에이전트 실행, 병렬 workflow를 허용한다.
-
-## 작업 절차 체크리스트
+- `AGENTS.md`에서 작업 종류를 분류하고 적용 가능한 현재 호스트 스킬 본문을 읽는다. 동일 본문/완료 결과는 재사용한다.
 - 변경 전: 유사 기능 코드를 먼저 찾아 네이밍/예외/응답 패턴을 맞춘다.
 - 변경 중: 공개 API 스키마를 임의 변경하지 말고 작은 단위로 안전하게 수정한다.
 - 변경 후: 영향 범위 파일에 대해 빌드/테스트/로그/다국어 키를 점검한다.
-- 커밋 직후: `commit-policy` 스킬을 로드하고 메시지 검증 스크립트를 실행한다.
-
-## 문서 유지보수 규칙
-- 문서 작성, 분리, 유지보수 규칙은 `docs/agent-guides/documentation-policy.md`를 참조한다.
+- 커밋 작업 시작 시 `AGENTS.md`의 호스트별 방법으로 `commit-policy`를 먼저 읽고, 커밋 직후 메시지 검증 스크립트를 실행한다. 커밋 자체는 사용자 요청이 있을 때만 한다.
+- 빌드·테스트·검증 명령은 `docs/agent-guides/build-test-verification.md`, 스타일은 `docs/agent-guides/code-style.md`, 문서 절차는 `docs/agent-guides/documentation-policy.md`를 따른다.
+- 작은 변경은 단일 경로로 한다. 다중 에이전트 또는 병렬 확장은 명시적 허용이 있고 실제 독립 작업인 경우에만 한다. 계획 실행은 `executing-plans` 또는 `subagent-driven-development` 중 하나다.
+- 문서 전용 작업은 TDD를 형식적으로 적용하지 않는다. 해당 대체 검증 근거와 실제 실행 결과를 작업 계획에 기록한다.