seokang-sk 0.3.0 → 0.5.0

package/README.MD

@@ -1,76 +1,155 @@
 # SeoKang Codex 스킬
 
-## 설치와 기준 저장소
+이 패키지는 Codex가 SeoKang의 작업 방식과 코드 스타일을 따라 기획, 개발, 점검, 배포하도록 준비해 주는 설치 도구입니다. 개발자가 아니어도 아래 순서대로 복사해서 실행하면 됩니다.
 
-- 배포 패키지: `seokang-sk`
-- 설치 명령: `sk setup`
-- 수정 가능한 원본 저장소: `~/.agents/skills`
-- 동기화 대상 Codex 런타임: `~/.codex`
+## 처음 설치하는 분은 여기만 보세요
 
-핵심 규칙은 단순하다.
+### 1. 준비물 설치
 
-`sk`는 최종적으로 `~/.agents/skills`의 로컬 저장소를 기준으로 동작해야 한다.
+아래 세 가지가 필요합니다.
 
-즉, npm으로 배포한 뒤에도 `~/.agents/skills/skills/sk-feature-workflow/SKILL.md` 같은 스킬 파일을 로컬에서 바로 수정할 수 있어야 한다. 배포 패키지는 설치 진입점과 디스패치만 담당하고, 실제 기준 원본은 로컬 저장소에 남는다.
+- [Codex 앱](https://openai.com/codex/)
+- [Node.js](https://nodejs.org/) 20 이상
+- [Git](https://git-scm.com/downloads)
 
-중요:
-- `~/.agents/skills`는 이 저장소의 repo root다.
-- 실제 skill 폴더는 `~/.agents/skills/skills/` 아래에 둔다.
-- `docs/`, `codex-config/`, `scripts/`는 지원 폴더이고, `skills/`가 skill 묶음 폴더다.
+Windows에서는 Git을 설치할 때 함께 제공되는 **Git Bash**를 사용하세요. macOS에서는 **터미널**을 사용하면 됩니다.
 
-## 30초 구조 요약
+> [!IMPORTANT]
+> 이 설정은 Codex가 매번 승인창을 띄우지 않고 파일과 명령을 다룰 수 있도록 `approval_policy = "never"`, `sandbox_mode = "danger-full-access"`를 사용합니다. 개인 PC와 신뢰할 수 있는 프로젝트에서만 설치하고, 비밀번호·토큰·OTP를 Codex 대화나 프로젝트 파일에 넣지 마세요.
 
-- repo root는 `~/.agents/skills`다.
-- 실제 skill은 `~/.agents/skills/skills/sk-이름/SKILL.md` 형태로 둔다.
-- `docs/`, `codex-config/`, `scripts/`는 지원 폴더이며, `skills/`만 skill 묶음 폴더다.
+터미널에 아래 명령을 한 줄씩 입력해 준비가 끝났는지 확인합니다.
 
-## 처음 설치
+```bash
+node --version
+npm --version
+git --version
+```
+
+세 명령 모두 버전 숫자가 나오면 다음 단계로 넘어갑니다. `command not found` 또는 `명령을 찾을 수 없습니다`가 나오면 해당 프로그램을 먼저 설치한 뒤 터미널을 새로 여세요.
+
+### 2. SeoKang 스킬 설치
+
+아래 두 줄을 순서대로 실행합니다.
 
 ```bash
 npm install -g seokang-sk
-sk setup
+sk setup --skip-notion
+```
+
+`sk setup --skip-notion`은 설치 중 어려운 Notion 주소를 묻지 않고, 필요한 원본을 사용자 폴더의 `~/.agents/skills`에 준비해 Codex 설정을 동기화합니다. 마지막에 다음 문구가 나오면 설치가 끝난 것입니다.
+
+```text
+✅ 완료: setup이 끝났습니다.
+```
+
+Codex가 열려 있었다면 완전히 종료한 뒤 다시 실행하세요.
+
+### 3. 설치 확인
+
+```bash
+sk check
+sk help
+```
+
+- `pass` 또는 `✅` 항목은 정상입니다.
+- Notion이나 DB를 아직 쓰지 않는다면 관련 `warn`은 설치 실패가 아닙니다.
+- 무엇을 해야 할지 모르겠다면 출력된 `recommended_action` 명령만 그대로 실행하면 됩니다.
+
+## 프로젝트에서 사용하기
+
+### 이미 있는 프로젝트에 적용
+
+터미널에서 프로젝트 폴더로 이동한 뒤 아래 명령을 실행합니다.
+
+```bash
 cd /path/to/project
 sk init
-sk status
+sk style audit
+sk check
 ```
 
-- DB safe-read login-path alias를 프로젝트 track 기준으로 맞추려면 아래 명령을 사용한다.
+`/path/to/project`는 실제 프로젝트 폴더로 바꿔야 합니다. 경로 입력이 어렵다면 `cd `까지 입력한 뒤 프로젝트 폴더를 터미널 창으로 끌어다 놓고 Enter를 누르세요.
+
+`sk init`은 기존 `build.gradle`, properties, `package.json`을 새로 만들거나 덮어쓰지 않습니다. `.sk` 작업 상태와 `AGENTS.md`의 SeoKang 코드 스타일 구간만 준비합니다.
+
+### 새 프로젝트 만들기
+
+새 프로젝트를 둘 상위 폴더로 먼저 이동합니다. 화면을 만드는 프로젝트는 frontend, API와 서버를 만드는 프로젝트는 backend를 선택합니다.
 
 ```bash
-sk setup --configure-db-safe-read
+# 화면 프로젝트
+sk create frontend sample-office
+
+# API 서버 프로젝트
+sk create backend sample-api --package com.mycompany.sample
+```
+
+- `sample-office`, `sample-api`는 원하는 영문 프로젝트 이름으로 바꿉니다.
+- backend의 `com.mycompany.sample`은 사용할 패키지명으로 바꿉니다.
+- 이미 존재하는 폴더에는 starter를 덮어쓰지 않습니다.
+- 생성이 실패하면 불완전한 프로젝트 폴더를 남기지 않습니다.
+
+프로젝트를 Codex에서 연 뒤 평소 말하듯 요청하면 됩니다.
+
+```text
+$sk-plan 예약 관리 화면과 서버 구조를 계획해줘
+$sk-feature 계획한 예약 관리 기능을 구현해줘
+$sk-bugfix 저장 버튼을 눌러도 저장되지 않는 문제를 고쳐줘
+$sk-git
+$sk-deploy
 ```
 
-- Notion 문서까지 함께 쓸 계획이면 설치 후 한 번 더 아래 명령을 실행한다.
+## 업데이트
+
+설치 후 새 버전을 받으려면 먼저 변경 가능 여부를 확인하고 업데이트합니다.
 
 ```bash
-sk setup --configure-notion
+sk update --dry-run
+sk update
+sk check
 ```
 
-- `Records` / `Projects` 데이터베이스 URL에 Notion id가 들어 있으면 `data source id`는 setup 중 자동으로 추출한다.
+로컬에서 직접 고친 파일이 있거나 원격과 충돌할 가능성이 있으면 `sk update`는 강제로 덮어쓰지 않고 중단합니다.
+
+## 자주 막히는 문제
+
+### `npm` 명령을 찾을 수 없음
+
+Node.js가 설치되지 않았거나 설치 전 터미널을 계속 사용 중인 상태입니다. Node.js를 설치하고 터미널을 완전히 닫았다가 다시 여세요.
+
+### `sk` 명령을 찾을 수 없음
+
+터미널을 새로 연 뒤 `npm install -g seokang-sk`를 다시 실행하세요. Windows PowerShell에서 `sk.ps1` 실행 정책 오류가 나오면 Git Bash를 열어 같은 명령을 실행합니다.
 
-- Notion 문서 기록이 `invalid_grant`, `unauthorized`, `forbidden` 같은 인증 오류로 실패하면 아래 명령으로 MCP 인증을 다시 연결한다.
-- `Tool ... not found`처럼 특정 Notion tool만 빠진 경우는 로그인 문제가 아닐 수 있으니, exact error를 남기고 남아 있는 Notion MCP tool로 우회 가능한지 먼저 확인한다.
-- `notion-query-data-sources` / `query_data_sources`는 더 이상 Notion 기록의 1차 탐색 경로로 두지 않는다.
-- local config에 data source id가 있으면 `fetch` / `create_pages` / `update_page`를 먼저 쓰고, lookup이 필요할 때만 `search -> fetch` 순서로 보완한다.
+### `sk setup을 실행하려면 git이 필요합니다`
+
+Git을 설치한 뒤 터미널을 새로 열고 `git --version`을 확인한 다음 `sk setup --skip-notion`을 다시 실행하세요.
+
+### Notion 또는 DB 경고가 나옴
+
+기본 설치에는 필요하지 않은 선택 설정입니다. 실제로 사용할 때만 아래 명령을 실행합니다.
 
 ```bash
-codex mcp login notion
+sk setup --configure-notion
+sk setup --configure-db-safe-read
 ```
 
-자세한 구조 문서:
+### 그래도 해결되지 않음
 
-- `docs/sk-setup-architecture.md`
-- `docs/sk-cli-guide.md`
-- `docs/sk-notion-workspace.md`
+아래 명령 결과를 복사해 설치를 도와주는 사람에게 전달하세요. 비밀번호, 토큰, OTP는 함께 보내지 마세요.
 
-자동화 기준 문서:
+```bash
+sk check
+sk status
+```
 
-- `docs/automations/server-log-check.md`
-- `docs/automations/daily-thread-retrospective.md`
+## 설치 구조를 더 알고 싶은 분
 
-이 저장소는 SeoKang 개인 개발 워크플로를 Codex Skill과 공용 Codex 데스크톱 설정 원본으로 관리하기 위한 저장소다.
+- npm 패키지 `seokang-sk`: 최초 설치와 명령 연결
+- `~/.agents/skills`: 수정 가능한 스킬 원본 저장소
+- `~/.codex`: Codex가 실제로 읽는 동기화 설정
 
-기능 개발, 버그 수정, 리팩토링, 기획, 배포뿐 아니라 문서화와 Notion 기록까지 포함한 작업 방식을 정리한다.
+자세한 내용은 [sk CLI 가이드](docs/setup/sk-cli-guide.md)와 [설치 구조](docs/setup/sk-setup-architecture.md)를 참고하세요.
 
 ---
 
@@ -78,11 +157,19 @@ codex mcp login notion
 
 ```text
 .
+|- docs/
+|  |- setup/               # 설치/런타임/Notion/Subagent 가이드
+|  |- automations/         # 자동화 기준 문서
+|  |- policies/            # 공통 정책
+|  |- playbooks/           # specialist 체크리스트
+|  |- templates/           # 출력/기록 템플릿
+|  |- refactor/            # 구조 개편 decision log
 |- skills/
 |  |- sk-feature-workflow  # 기능 작업 메인 오케스트레이터
 |  |- sk-bugfix-workflow   # 버그 수정 워크플로
 |  |- sk-refactor          # 리팩토링 워크플로
 |  |- sk-plan              # 기획/설계 응답 워크플로
+|  |- sk-counseling-feedback # 상담 녹음 로컬 전사·난이도·HTML 피드백
 |  |- sk-db                # DB 변경 워크플로
 |  |- sk-design-system     # 디자인 시스템 점검/구축
 |  |- sk-docs              # 변경 문서 작성
@@ -93,108 +180,53 @@ codex mcp login notion
 |  |- agents/              # ~/.codex/agents 공용 원본
 |  |- rules/               # ~/.codex/rules 공용 원본
 |- templates/
-|  |- agent/               # 프로젝트용 AGENT.MD bootstrap 템플릿
+|  |- agent/               # 프로젝트용 AGENTS.md bootstrap 템플릿
 |- scripts/                # 공용 설치 / 보조 스크립트
 ```
 
 - 실제 skill 엔트리는 `skills/sk-*/SKILL.md`다.
 
+## 하네스 지원 파일
+
+- 작업 계약 템플릿: `docs/templates/task-contract.md`
+- 영향도 맵 템플릿: `docs/templates/impact-map.md`
+- 하네스 워크플로 기준: `docs/playbooks/harness-workflow.md`
+- default/fallback 체크: `node scripts/check_no_unauthorized_defaults.mjs <path ...>`
+- DDL comment 체크: `node scripts/check_ddl_comments.mjs <path ...>`
+- 문서 링크 무결성 체크: `node scripts/check_docs_integrity.mjs <path ...>`
+- GPT-5.6 기본/agent 모델 배치 체크: `node scripts/check_codex_model_routing.mjs`
+- custom agent 실제 적용 smoke: 호출 직전 UTC 시각과 `spawn_agent`가 반환한 task path를 사용해 `node scripts/check_codex_agent_runtime.mjs --role <agent-name> --agent-path <task-name> --since <ISO-8601>` 실행 (`--thread-id <uuid>`도 지원)
+- CLI smoke 체크: `node scripts/check_sk_cli_smoke.mjs`
+- UI runtime router 체크: `node scripts/check_ui_runtime_router.mjs`
+- automation safety 체크: `node scripts/check_automation_safety.mjs`
+- 전체 하네스: `npm run check:harness`
+- 하네스는 subagent 대체가 아니라 preflight/check 레이어다.
+
 ## 어디를 수정하나
 
 - skill 동작 변경: `skills/sk-*/SKILL.md`
 - 설치/런타임 설정 변경: `codex-config/**`, `scripts/**`
-- 프로젝트용 AGENT.MD 기본 틀 변경: `templates/agent/*.md`
+- 프로젝트용 AGENTS.md 기본 틀 변경: `templates/agent/*.md`
 - 사용법/운영 가이드 변경: `docs/**`, `README.MD`
 
 ---
 
-## 목적
-
-- 기능/버그/리팩터링 작업을 명확히 분리한다.
-- 코드 변경뿐 아니라 문서와 기록까지 같은 규칙으로 관리한다.
-- 회사 맥북, 집 윈도우처럼 데스크톱이 달라도 같은 Codex 셋업을 재현한다.
-- 반복되는 Codex 설정 수정을 로컬 수작업이 아니라 저장소 원본 기준으로 동기화한다.
-
-## 실행 방식
-
-- `sk`는 별도 앱 UI가 아니라 CLI 명령으로만 동작한다.
-- `sk setup`이 sync하는 대상은 `~/.codex`이고, `sk init`은 현재 프로젝트의 `.sk/` 상태를 준비한다. 필요하면 `--agent-md`로 프로젝트 루트 `AGENT.MD`도 함께 만든다.
-- 옵션과 예시는 `sk help`, `sk help <command>`, `<command> --help`로 바로 확인한다. 예: `sk help init`, `sk init --help`
-- OMX가 `omx setup`처럼 짧아 보이는 이유는 npm 전역 CLI로 설치되기 때문이다.
-- 지금 `sk`도 최초 1회만 `npm link`로 등록하면 이후에는 `sk setup`, `sk init`만 기억하면 된다.
-- 실행 전제:
-  - Node.js 20+
-  - Windows는 Git Bash 권장
+## 저장소를 직접 개발하는 분
 
-## 저장소를 직접 개발할 때
-
-- 최초 1회만 이 저장소에서 전역 CLI를 등록한다.
+일반 설치자는 이 절을 건너뛰어도 됩니다. 이 저장소 자체를 수정하는 개발자만 repo 루트에서 최초 한 번 `npm link`를 실행합니다.
 
 ```bash
-cd /c/Users/<user>/.agents/skills
+cd ~/.agents/skills
 npm link
+sk setup --skip-notion
 ```
 
-- 그 다음부터는 어디서든 이 세 줄이면 된다.
+Windows Git Bash에서는 사용자 경로에 맞춰 `cd /c/Users/<user>/.agents/skills`를 사용합니다. 저장소 안에서 전역 링크 없이 확인해야 할 때만 `sh ./sk <command>` fallback을 사용합니다.
 
-```bash
-sk setup
-sk init
-sk check
-sk status
-```
-
-- Notion 기록을 쓸 계획이면 최초 1회는 아래처럼 사용자별 Notion 위치도 같이 설정한다.
-
-```bash
-sk setup --configure-notion
-```
-
-- 다른 프로젝트를 바로 지정하고 싶으면 `init`, `status`, `memory` 계열에 `--cwd`를 붙이면 된다.
-  - `sk init --cwd /path/to/project`
-  - `sk status --cwd /path/to/project`
-- npm link 없이도 저장소 안에서는 fallback으로 `sh ./sk setup`을 계속 쓸 수 있다.
-- `sk` 사용 흐름 설명은 `docs/sk-cli-guide.md`를 기준 문서로 본다.
-
-## 첫 설치 예제
-
-권장 새 PC 흐름:
-
-1. Codex 설치
-2. `npm install -g seokang-sk`
-3. `sk setup`
-4. 작업할 프로젝트 루트에서 `sk init`
-5. `sk check`
-6. 필요하면 `sk status`
-
-### Windows Git Bash
-
-```bash
-sk setup
-cd /c/path/to/project
-sk init
-sk check
-sk status
-```
-
-### macOS / Linux
-
-```bash
-sk setup
-cd /path/to/project
-sk init
-sk check
-sk status
-```
-
-### 저장소 로컬 fallback 예제
-
-```bash
-cd /c/Users/<user>/.agents/skills
-sh ./sk setup
-sh ./sk check
-sh ./sk status
-```
+- `sk help <command>`: 명령별 옵션과 예시 확인
+- `sk init --cwd /path/to/project`: 다른 프로젝트 초기화
+- `sk status --cwd /path/to/project`: 다른 프로젝트 상태 확인
+- [상세 CLI 가이드](docs/setup/sk-cli-guide.md)를 기준 문서로 사용
 
 ---
 
@@ -204,6 +236,7 @@ sh ./sk status
 - `sk-bugfix`: 근거 기반 버그 수정
 - `sk-refactor`: 기능 변경 없는 구조 개선
 - `sk-plan`: 기획/설계 응답
+- `sk-counseling-feedback`: 상담 녹음을 로컬 전사하고 난이도와 3단계 코칭 피드백을 단일 HTML로 생성
 - `sk-git`: 변경 파일 기준 commit/push
 - `sk-deploy`: 서버/NAS 배포와 npm publish 배포
 
@@ -238,19 +271,21 @@ sh ./sk status
 - `~/.codex/rules/skills-shared.rules`는 저장소 원본을 그대로 복사한다.
 - `~/.codex/sk/notion/workspace.json`은 사용자별 Notion workspace 설정 파일이다.
 - setup 중 기존 대상 파일이 바뀌면 현재 작업 디렉터리의 `.sk/backups/setup/**` 아래에 백업을 남긴다.
+- 기존 활성 config가 source와 다르면 `sk setup`은 config 전체 교체만 건너뛰고 app-managed key를 보존한다. agent만 갱신할 때는 `sk sync-agents --dry-run` 후 `sk sync-agents`를 사용한다.
 - 공용 기본값은 `approval_policy = "never"`, `sandbox_mode = "danger-full-access"`다.
-- 현재 설정은 Playwright MCP 승인창이 `workspace-write + never`에서도 계속 나타나는 현상을 확인한 뒤, `danger-full-access + never`까지 실험해 보기 위한 강한 기본값이다.
+- 기본 작업 모델은 `gpt-5.6-sol`, reasoning effort는 `high`다.
+- 탐색형 custom agent는 Terra를 사용하고, 명세·리뷰·DB·UI/Figma 역할은 Sol High를 사용한다. 정확한 배치는 `docs/setup/codex-subagents.md`를 따른다.
+- Ultra는 상시 기본값으로 두지 않고, 대규모 구조 감사처럼 병렬 분해 이득이 분명한 일회성 작업에서만 선택한다.
+- 현재 설정은 승인창 없이 공용 설정 동기화를 진행하기 위한 강한 기본값이며, UI 런타임 검증은 Playwright MCP 대신 Browser / Chrome / Computer Use 라우터를 기본 경로로 둔다.
 - CLI로 쓰면 `codex --sandbox danger-full-access -a never`와 같은 기준이다.
 - shared subagent를 실제로 사용할 수 있도록 공용 source에서 `multi_agent` feature를 켠다.
+- `/goal`, Automations, Skills 중심 운영 기준은 `docs/setup/codex-workflows.md`를 따른다.
 
-설치 명령:
-
-```bash
-sh ~/.agents/skills/scripts/install_codex_shared_setup.sh
-```
+일반 사용자 설치 명령:
 
 ```bash
-sh /c/Users/<user>/.agents/skills/scripts/install_codex_shared_setup.sh
+npm install -g seokang-sk
+sk setup --skip-notion
 ```
 
 새 CLI 명령:
@@ -281,42 +316,47 @@ sk search "reviewer"
 
 호환성:
 
-- 기준 설치 스크립트는 `scripts/install_codex_shared_setup.sh` 하나다.
-- 전역 CLI 등록을 원하면 이 저장소 루트에서 최초 1회 `npm link`를 실행한다.
-- Windows에서도 Git Bash 환경에서 동일한 `.sh`를 실행한다.
-- Windows에서 `sh` 명령이 없으면 Git for Windows(Git Bash)를 설치한 뒤 다시 실행한다.
+- 일반 사용자 기준 설치 진입점은 `npm install -g seokang-sk` → `sk setup --skip-notion`이다.
+- `scripts/install_codex_shared_setup.sh`는 저장소 개발과 이전 설치 방식의 호환용으로만 유지한다.
+- 이 저장소를 직접 개발할 때만 repo 루트에서 최초 1회 `npm link`를 실행한다.
+- Windows의 저장소 로컬 `.sh` fallback은 Git Bash에서만 실행한다.
 - Windows PowerShell에서 실행 정책 때문에 `sk.ps1`이 막히면 `sk.cmd`를 쓰거나 생성된 `sk.ps1`을 비활성화해 `sk.cmd`가 우선 잡히게 한다.
 - 기존 `scripts/install_codex_shared_rules.sh`는 새 설치 스크립트를 호출하는 래퍼로 유지한다.
 - `scripts/sk.sh`는 Node 기반 `scripts/sk.mjs`를 호출하는 Git Bash 표준 진입점이다.
 - repo 루트 `./sk`는 npm link를 쓰지 않을 때의 fallback 진입점이다.
 - 다른 프로젝트를 지정해야 하면 대부분의 명령에서 `--cwd /path/to/project`를 같이 쓰면 된다.
 - `sk setup`이 설치와 동기화를 맡는다.
-- `sk init`이 프로젝트 상태 준비를 맡는다.
+- `sk create`가 새 프로젝트 전체 생성을 맡고 `sk init`은 기존 프로젝트 profile 연결을 맡는다.
 
 상태 디렉터리:
 
-- `sk init`은 현재 작업 디렉터리 아래 `.sk/`를 만들고, `--agent-md`를 붙이면 프로젝트 루트 `AGENT.MD`도 함께 만든다.
+- `sk init`은 현재 작업 디렉터리 아래 `.sk/`와 프로젝트 루트 `AGENTS.md`의 managed style block을 준비한다.
 - `sk setup`은 관리용 저장소 `~/.agents/skills/.sk/`를 setup 상태/백업 기준 경로로 사용한다.
 - `.sk/setup-scope.json`: 마지막 init/setup 기록
 - `.sk/project-memory.json`: 다음 세션이 읽을 구조화 메모
 - `.sk/notepad.md`: 우선 컨텍스트/작업 메모
 - `.sk/backups/setup/**`: setup 중 덮어쓰기 전에 남긴 백업
-- Notion workspace 설정은 `~/.codex/sk/notion/workspace.json`을 쓴다.
+- Notion workspace 설정은 `~/.codex/sk/notion/workspace.json`을 쓰고, 작업 문서 outbox는 `~/.codex/sk/notion/outbox`를 쓴다.
 
 중요 제한:
 
 - `skills-shared.rules`는 shell prefix 자동 허용만 처리한다.
-- Notion/Figma/Playwright 같은 MCP/tool 승인 정책은 `shared-config.toml`에서 함께 관리한다.
+- Notion/Figma MCP와 Browser / Chrome / Computer Use를 나누는 런타임 검증 라우팅은 `shared-config.toml`과 관련 playbook에서 함께 관리한다.
 - 공용 subagent 등록은 `shared-config.toml`의 `[agents.*]`와 `codex-config/agents/seokang/*.toml`에서 함께 관리한다.
 - `danger-full-access`는 workspace 밖 파일, 홈 디렉터리, SSH, 네트워크, 외부 명령 실행까지 sandbox 제한 없이 진행할 수 있게 한다.
 - `approval_policy = "never"`라서 승인창도 띄우지 않는다.
-- 기본 분석용 공용 subagent는 `read-only sandbox`를 기본으로 하며, `Notion MCP`와 `Playwright`는 agent 파일에서 명시적으로 비활성화한다.
-- 브라우저 재현, 콘솔/네트워크 증거, Notion 조회/기록은 전용 tool subagent를 두지 않고 메인 agent가 직접 수행한다.
-- Notion 관련 조회/기록은 MCP 우선을 기본으로 한다. 인증/권한 실패가 나면 exact error를 먼저 보고한다.
-- Notion 실패를 숨기기 위해 Playwright로 notion.so를 기본 경로처럼 사용하지 않는다. 웹 UI fallback은 사용자가 명시적으로 요청한 경우에만 허용한다.
-- 같은 설정은 Playwright만이 아니라 현재 세션 전체에 적용된다.
+- 기본 분석용 공용 subagent TOML은 `read-only sandbox`로 두지만, 현재 task의 live permission override가 있으면 부모 권한이 우선할 수 있다. `Notion MCP`, `Playwright`, `Browser`, `Chrome`, `Computer Use` 같은 tool 작업은 agent 지침에서 금지한다.
+- 브라우저 재현, 콘솔/네트워크 증거, Notion 조회/publish는 전용 tool subagent를 두지 않고 메인 agent 또는 Codex 자동화가 수행한다.
+- Notion과 Figma 관련 조회/작업은 plugin(MCP) 경로를 기본으로 사용한다.
+- 작업 문서 작성은 local outbox를 기본으로 하고, Notion 조회/publish는 MCP 우선을 기본으로 한다. 인증/권한 실패가 나면 exact error를 먼저 보고한다.
+- Figma도 browser/manual 확인보다 MCP tool 호출을 기본 경로로 두고, 우회는 exact error와 범위 불명확성이 정리된 뒤에만 사용한다.
+- Notion 실패를 숨기기 위해 브라우저 자동화로 notion.so를 기본 경로처럼 사용하지 않는다. 웹 UI fallback은 사용자가 명시적으로 요청한 경우에만 허용한다.
+- UI 런타임 검증이 필요하면 메인 agent가 Browser / Chrome / Computer Use 라우터로 실제 앱/브라우저 상태를 확인한다.
+- 로컬 dev URL은 Browser, 사용자 Chrome 세션/쿠키/기존 탭은 Chrome, 앱/OS-level UI는 Computer Use를 우선한다.
+- Computer Use로 브라우저 검증을 해야 하면 사용자 현재 탭을 쓰지 않고 전용 테스트 창 또는 탭을 열어 검증한 뒤 닫는다.
+- 사용자가 명시적으로 Playwright를 요청하지 않았다면 UI 런타임 검증에서 `PWCLI`, `playwright_cli.sh`, `@playwright/mcp`, standalone Playwright 기반 browser-use fallback을 사용하지 않는다.
 - 이 설정은 보안 유지형이 아니라 실험/자동화 우선 설정이다.
-- 현재 데스크톱 빌드 기준으로도 Playwright MCP 승인창 제거는 보장되지 않으므로, 실제 효과는 새 세션에서 직접 확인해야 한다.
+- Browser / Chrome / Computer Use 플러그인 제공 여부는 Codex 데스크톱 세션의 tool surface를 기준으로 확인한다.
 
 다른 프로젝트에도 프로젝트별 rules가 필요하면 각 프로젝트 루트의 `.codex/rules/*.rules`에 별도로 추가해서 관리한다.
 
@@ -362,18 +402,20 @@ LOCAL_JAR_PATH=./build/libs/km-admin-api.jar
 - API 계약 변경 시 전체 이름/응답 구조 확인
 - 리팩터링은 동작 유지가 전제
 - build 성공과 정상 동작은 별개로 본다
-- Notion 기록을 임의로 생략하지 않는다
+- Notion outbox 문서를 임의로 생략하지 않는다
 
 ---
 
-## 설치 스크립트 사용법
+## 호환용 설치 스크립트 사용법
 
-- 이 설치 스크립트는 이 저장소의 공용 Codex 설정을 로컬 `~/.codex`로 한 번에 복사/동기화한다.
+- 일반 사용자는 이 절 대신 README 맨 위의 npm 설치 절차를 사용합니다.
+- 이 설치 스크립트는 저장소 개발자가 공용 Codex 설정을 로컬 `~/.codex`로 복사·동기화할 때 사용하는 호환 경로다.
 - 같은 설치 스크립트가 공용 subagent도 `~/.codex/agents/seokang`으로 함께 동기화한다.
 - 내부적으로는 `scripts/sk.mjs setup` 흐름을 호출한다.
 - macOS shell 설치 예시: `sh ~/.agents/skills/scripts/install_codex_shared_setup.sh`
 - Windows Git Bash shell 설치 예시: `sh /c/Users/<user>/.agents/skills/scripts/install_codex_shared_setup.sh`
-- 이 저장소의 공용 Codex 설정이 바뀌면 같은 설치 스크립트를 다시 실행한다.
+- 기존 설치에서 shared agent만 바뀌면 설치 스크립트를 다시 실행하지 않고 `sk sync-agents`를 사용한다.
+- source와 다른 활성 config는 setup에서 교체하지 않고 그대로 보존된다.
 - 로컬 대상 파일이 source와 다르면 설치 스크립트가 덮어쓰기 전에 `.sk/backups/setup/**` 아래에 백업을 남긴다.
 - Windows에서 `sh`를 인식하지 못하면 Git for Windows(Git Bash)를 설치한 뒤 같은 `.sh` 명령을 다시 실행한다.
 
@@ -382,18 +424,34 @@ LOCAL_JAR_PATH=./build/libs/km-admin-api.jar
 - `setup`
   - `~/.agents/skills` 저장소를 준비하거나 재사용하고, config/rules/shared agents를 sync한 뒤 check까지 실행한다.
   - 최초 setup 시 interactive 환경이면 사용자별 Notion workspace 설정 파일도 함께 만들 수 있다.
-  - `--dry-run`, `--verbose`, `--configure-notion`, `--skip-notion`을 지원한다.
+  - `--dry-run`, `--verbose`, `--configure-notion`, `--skip-notion`과 Notion fast path 옵션(`--records-data-source-id`, `--projects-data-source-id`, `--project-page-url`, `--history-data-source-id`, `--record-type`)을 지원한다.
+- `update`
+  - canonical skills 저장소가 clean이고 upstream으로 fast-forward 가능할 때만 갱신한다.
+  - dirty/ahead/diverged 상태에서는 강제 reset 없이 중단한다.
+- `create`
+  - `sk create backend <name> --package <root.package>` 또는 `sk create frontend <name>`으로 승인된 starter를 생성한다.
+  - backend 선택 기능은 `--capabilities cache,excel`처럼 versioned capability로만 추가한다.
+- `sync-agents`
+  - `config.toml`, rules, Notion, 프로젝트 상태를 건드리지 않고 `~/.codex/agents/seokang/*.toml`만 백업 후 동기화한다.
+  - 기존 설치의 모델/지침 변경은 `sk sync-agents --dry-run` 확인 후 `sk sync-agents`로 반영한다.
+  - `--scope <user|project>`, `--cwd <path>`, `--dry-run`, `--verbose`를 지원한다.
 - `init`
-  - 현재 프로젝트 루트의 `.sk/` 상태 파일을 준비한다.
-  - `--agent-md`를 붙이면 프로젝트 루트에 `AGENT.MD` 초안도 함께 만든다.
-  - `--cwd <path>`, `--agent-md`, `--dry-run`, `--force`, `--verbose`를 지원한다.
+  - 현재 프로젝트 루트의 `.sk/`와 `AGENTS.md` managed style block을 준비한다.
+  - 기존 build/properties/package 파일은 생성하거나 덮어쓰지 않는다.
+  - 기존 `--agent-md`는 호환 alias로 유지한다.
+  - `--cwd <path>`, `--no-style`, `--dry-run`, `--force`, `--verbose`를 지원한다.
+- `style`
+  - `sk style audit`은 profile/starter/capability drift를 검사한다.
+  - `sk style apply`는 AGENTS managed block과 profile 상태만 갱신한다.
 - `check`
   - 현재 설치가 source와 일치하는지 확인한다.
-  - Notion workspace 설정 파일 존재 여부와 필수 필드도 함께 확인한다.
-  - `--cwd <path>`, `--json`을 지원한다.
+  - Codex workflow 상태(`multi_agent`, `/goal`, automation 기준 문서, skill 원본)도 함께 확인한다.
+  - Notion workspace 설정 파일, outbox 자동화 기준 문서, fast path cache 준비 상태도 함께 확인한다.
+  - drift나 선택적 설정 경고에는 `recommended_action`을 함께 제공한다.
+  - `--cwd <path>`, `--track <name>`, `--json`을 지원한다.
 - `status`
   - 현재 `.sk` 상태, memory/notepad, Notion workspace 설정 상태, 최근 backup, check 결과를 함께 보여준다.
-  - `--cwd <path>`, `--json`을 지원한다.
+  - `--cwd <path>`, `--track <name>`, `--json`을 지원한다.
 - `memory`
   - `.sk/project-memory.json`과 `.sk/notepad.md`를 초기화하고 읽는다.
   - `show`, `init`, `add-note`, `add-directive`를 지원한다.
@@ -415,25 +473,28 @@ LOCAL_JAR_PATH=./build/libs/km-admin-api.jar
   - `db_impact_reviewer`
   - `ui_flow_mapper`
   - `design_checker`
-- 설정과 유지보수 방법은 `docs/codex-subagents.md`에 정리했다.
-- `sk-feature`, `sk-bugfix`, `sk-db`는 shared subagent가 설치되어 있으면 사용자가 따로 지시하지 않아도 내부적으로 dispatch할 수 있도록 설계한다.
-- 기본 분석용 subagent는 `Notion MCP`와 `Playwright`를 직접 사용하지 않고, 이런 tool 작업은 메인 agent가 맡는다.
+- 설정과 유지보수 방법은 `docs/setup/codex-subagents.md`에 정리했다.
+- 공통 Runtime Delegation 조건이 충족되면 skill의 지시만으로 적합한 custom agent를 호출하며, 사용자가 매번 별도로 요청할 필요는 없다.
+- 교차 레이어·외부 기준 대조·반복 workflow 마찰·비단순 회귀 위험이 없고 독립 lane도 없는 단순 작업에는 호출 수를 강제하지 않는다.
+- 위임 판단을 사용자 출력 형식으로 노출하지 않고 실제 실행 이력만 기록한다.
+- 기본 분석용 subagent는 `Notion MCP`, `Playwright`, `Browser`, `Chrome`, `Computer Use`를 직접 사용하지 않고, 이런 tool 작업은 메인 agent가 맡는다.
 
-## 프로젝트 AGENT.MD
+## 프로젝트 AGENTS.md
 
-- `AGENT.MD`는 프로젝트별 고정 규칙 문서다.
-- `README`는 사람용 개요/설치 문서, `.sk/*`는 세션 메모, `AGENT.MD`는 agent가 먼저 읽어야 할 프로젝트 계약서로 분리해서 쓴다.
+- `AGENTS.md`는 Codex가 기본 탐색하는 프로젝트별 고정 규칙 문서다.
+- `README`는 사람용 개요/설치 문서, `.sk/*`는 세션 메모, `AGENTS.md`는 agent가 먼저 읽어야 할 프로젝트 계약서로 분리해서 쓴다.
+- 기존 `AGENT.MD`만 있는 프로젝트는 `sk init` 실행 시 내용을 보존해 `AGENTS.md`로 마이그레이션하고 style managed block을 덧붙인다.
 - 성능 차이가 크지 않은 한 기본 초안은 한글로 생성하고, 명령어/식별자/경로만 원문을 유지한다.
 - 새 프로젝트에서 바로 만들려면 아래처럼 시작한다.
 
 ```bash
-sk init --agent-md
+sk init
 ```
 
 - 다른 프로젝트를 미리 준비할 때는 아래처럼 쓴다.
 
 ```bash
-sk init --cwd /path/to/project --agent-md
+sk init --cwd /path/to/project
 ```
 
 - 기본 템플릿 원본은 `templates/agent/base.md`, `templates/agent/frontend.md`, `templates/agent/backend.md`, `templates/agent/codex.md`다.