okstra 0.3.0 → 0.5.0

package/README.kr.md

@@ -0,0 +1,157 @@
+# okstra
+
+> npm: [`okstra`](https://www.npmjs.com/package/okstra) · 설치: `npx -y okstra@latest install`
+>
+> English: [`README.md`](README.md)
+
+## 1. 용도
+
+`okstra` 는 **Claude Code 안에서 lead + worker 모델로 작업을 cross-verify 하기 위한 정형화된 task 실행 러너**입니다. Claude lead 가 phase 진행을 주도하고, 독립된 분석 worker 3종 — **Claude · Codex · Gemini** — 와 최종 보고서 작성을 전담하는 report-writer 를 dispatch 합니다.
+
+설계의 세 가지 원칙:
+
+- **단일 진입점 (`prepare_task_bundle`)**: 어떤 호출자(스킬, bash CLI, in-session) 가 들어와도 같은 task 디렉터리 구조 · 매니페스트 · 검증 경로를 산출합니다.
+- **task 정체성의 영구화**: `<project-id>/<task-group>/<task-id>` stable task key 가 phase 간 / 세션 간 / 모델 업그레이드 사이의 컨텍스트를 잇습니다.
+- **lead/worker 계약 강제**: 산출 schema 와 검증 절차가 `templates/` + `validators/` 에 묶여 있고, worker roster 는 phase 별로 고정되어 있습니다.
+
+okstra 는 단발성 코드 리뷰 도구가 **아닙니다**. **여러 phase 로 나뉘고, 여러 에이전트가 의견을 내야 하며, 각 phase 의 출력이 다음 phase 의 입력이 되는** 작업을 위한 도구입니다.
+
+## 2. 구조
+
+### 2.1 repo 레이아웃
+
+```
+okstra/                          npm 패키지 = repo 루트
+├── package.json                 name: "okstra"
+├── bin/okstra                   노드 CLI 진입점
+├── src/                         설치자 + 리졸버 (install, paths, doctor, check-project, uninstall)
+├── tools/build.mjs              runtime/ 동기화 스크립트 (prepack 에서 호출)
+├── runtime/                     gitignored 빌드 산출물; ~/.okstra 로 배포되는 유일한 자산
+├── scripts/                     python + bash 런타임 소스
+├── skills/                      Claude Code 스킬 마크다운 소스 (스킬 11종)
+├── agents/                      lead SKILL.md + workers/
+├── prompts/, templates/, validators/
+├── docs/kr/                     한국어 상세 매뉴얼 (architecture.md, cli.md)
+├── tests/, tests-e2e/
+├── .claude-plugin/plugin.json   보조 skills-CLI 채널 매니페스트
+├── .github/workflows/           release-please.yml, release.yml
+└── RELEASING.md, CHANGELOG.md, README.md, README.kr.md
+```
+
+`runtime/` 은 `prepack` 시점에 `tools/build.mjs` 가 `scripts/`, `skills/`, `agents/`, `prompts/`, `templates/`, `validators/` 로부터 다시 빌드합니다. npm 에 publish 되고 `~/.okstra` 로 복사되는 유일한 산출물입니다.
+
+### 2.2 설치 후 사용자 머신 레이아웃
+
+```
+~/.okstra/                       런타임 홈, `okstra install` 이 생성
+├── version                      패키지 버전 stamp
+├── lib/python/                  okstra_project/, okstra_ctl/, okstra_token_usage/, lib/
+├── bin/                         okstra.sh, codex-exec, gemini-exec, ...
+├── installed-skills.json        설치된 스킬 매니페스트 (uninstall 이 사용)
+├── recent.jsonl, active.jsonl   run 인덱스
+├── projects/                    프로젝트별 메타데이터 미러
+└── archive/                     완료된 run
+
+~/.claude/skills/                Claude Code 가 자동 인식
+└── okstra-*/SKILL.md            스킬 11종 (§3.3 참조)
+
+<프로젝트 루트>/.project-docs/okstra/
+├── project.json                 {projectId, projectRoot, ...} (`/okstra-setup` 이 작성)
+├── discovery/{task-catalog,latest-task}.json
+└── tasks/<task-group>/<task-id>/   task bundle (runs, manifest, reports)
+```
+
+### 2.3 단일 권위 요약
+
+| 리소스 | 위치 | 소유자 |
+|---|---|---|
+| 런타임 코드 (python + bash) | `~/.okstra/{lib/python, bin}` | `okstra install` |
+| agents/prompts/templates/validators | npm 패키지의 `runtime/` | `okstra` 패키지 자체 (`okstra paths` 로 해석) |
+| 스킬 마크다운 | `~/.claude/skills/<name>/SKILL.md` | `okstra install` (`installed-skills.json` 에 트래킹) |
+| 프로젝트 메타데이터 | `<project>/.project-docs/okstra/` | `/okstra-setup` + 프로젝트 자체 |
+| Run 인덱스 | `~/.okstra/{recent,active}.jsonl` | `prepare_task_bundle` |
+
+## 3. 사용 매뉴얼
+
+### 3.1 최초 셋업 (머신당 1회)
+
+```bash
+npx -y okstra@latest install
+```
+
+`~/.okstra/{lib/python, bin, version}`, `~/.claude/skills/` 아래 스킬 마크다운 11개, `~/.okstra/installed-skills.json` 을 생성합니다. 재실행은 idempotent — 파일별 hash 를 비교하고 바뀐 파일만 갱신합니다.
+
+검증:
+
+```bash
+npx -y okstra@latest doctor
+```
+
+`result: OK` 라인이 보이면 준비 완료입니다. FAIL row 가 있으면 그 줄에 바로 복구 방법이 인쇄됩니다 (대개는 install 재실행).
+
+### 3.2 프로젝트 등록 (프로젝트당 1회)
+
+CLI 에서:
+
+```bash
+cd <대상 프로젝트>
+npx -y okstra@latest setup --project-id <id>     # 예: INV-1234, fontsninja, okstra
+```
+
+또는 Claude Code 세션 안에서 동일한 슬래시 커맨드:
+
+```
+/okstra-setup
+```
+
+둘 다 `<project>/.project-docs/okstra/project.json` 을 작성합니다. CLI 는 `--project-id` 가 주어지면 non-interactive 로 동작하므로 CI 에서 사용할 수 있고, 슬래시 커맨드는 `AskUserQuestion` 으로 prompt 합니다. 이 파일이 존재하기 전에는 다른 모든 사용자 스킬이 실행을 거부합니다.
+
+### 3.3 일상 명령
+
+Claude Code 세션 안에서 사용하는 슬래시 커맨드:
+
+| 커맨드 | 용도 |
+|---|---|
+| `/okstra-run` | 새 task 시작 (또는 기존 task 의 다음 phase 이어가기) |
+| `/okstra-status` | phase / 상태 조회, task 의 workStatus 설정 |
+| `/okstra-history` | 과거 task 목록, 이어할 task 선택 |
+| `/okstra-schedule` | task-group 전체에 대한 작업 계획표 생성 |
+| `/okstra-time-summary` | 소요 시간 분석 (lead + worker 별) |
+| `/okstra-report-finder` | task-key 로 최종 보고서 조회 |
+| `/okstra-setup` | 프로젝트별 부트스트랩 (§3.2) |
+
+이 외에 `okstra-context-loader`, `okstra-team-contract`, `okstra-convergence`, `okstra-report-writer` 4종은 lead 가 phase 진행 도중 내부적으로 호출하는 스킬로, 사용자가 직접 부르는 일은 거의 없습니다.
+
+### 3.4 CLI 모드 (선택)
+
+Claude Code 세션 밖에서 task 를 시작하려면:
+
+```bash
+~/.okstra/bin/okstra.sh \
+  --project-id <id> \
+  --task-group <group> \
+  --task-id <id> \
+  --task-type <error-analysis|implementation-planning|...> \
+  --task-brief ./brief.md
+```
+
+새 `claude` 프로세스를 띄워 lead 역할로 동작시킵니다. 전체 인자 목록은 `okstra.sh --help` 또는 [`docs/kr/cli.md`](docs/kr/cli.md) 참조.
+
+### 3.5 운영 명령
+
+| 커맨드 | 용도 |
+|---|---|
+| `npx -y okstra@latest paths` | 런타임 경로 출력 (`--field <name>` 또는 `--shell`) |
+| `npx -y okstra@latest doctor` | 런타임 + 스킬 + python import 진단 |
+| `npx -y okstra@latest ensure-installed` | Idempotent 체크, stale 이면 자동 재설치 (스킬이 내부적으로 호출) |
+| `npx -y okstra@latest setup --project-id <id>` | 현재 프로젝트를 등록 (`.project-docs/okstra/project.json`) |
+| `npx -y okstra@latest check-project` | 현재 프로젝트가 `setup` 으로 등록됐는지 검증 |
+| `npx -y okstra@latest uninstall` | 런타임 + 스킬 제거; 사용자 데이터(`recent.jsonl`, `projects/`, …)는 보존 |
+| `npx -y okstra@latest uninstall --purge -y` | 사용자 데이터까지 모두 제거 |
+
+## 4. 더 읽을 자료
+
+- [`docs/kr/architecture.md`](docs/kr/architecture.md) — 한국어 상세 매뉴얼: prompt contract, team contract, storage model, task type 별 phase 규칙, lifecycle, workflow.
+- [`docs/kr/cli.md`](docs/kr/cli.md) — `okstra.sh` 의 모든 인자 / 옵션과 인터랙티브 입력 흐름.
+- [`RELEASING.md`](RELEASING.md) — 버전 컷과 publish 절차 (release-please + 수동 fallback).
+- [`CHANGELOG.md`](CHANGELOG.md) — release 별 변경 이력.