init: readme 작성 하네스 설계
This commit is contained in:
DongHyeonka
@@ -0,0 +1,171 @@
|
||||
# Org OS 하네스 — Claude Code용 에이전트 운영체계
|
||||
|
||||
Org OS 하네스는 제품·개발·운영·GTM 업무를 여러 AI 역할에 배분하고, 단계별 산출물과 사람 승인을 파일 계약으로 연결하는 Claude Code 프로젝트 하네스입니다. <!-- claim-id: C-IDENTITY -->
|
||||
|
||||
이 저장소의 핵심은 역할 프롬프트의 개수가 아니라 **누가 무엇을 만들고, 어떤 근거로 검토하며, 어느 조건에서 다음 단계로 갈 수 있는지**를 명시하는 데 있습니다. 워크플로 그래프, 역할·권한, typed artifact, 실행 증거를 각각 정본 파일과 hook으로 연결합니다. <!-- claim-id: C-VALUE -->
|
||||
|
||||
<!-- section-id: overview -->
|
||||
## 무엇을 제공하나요?
|
||||
|
||||
일반적인 새 작업은 `/ceo-intake`에서 의도와 작업 규모를 구조화한 뒤, 선택된 plan에 따라 discovery·decision·design·build·verification·acceptance로 진행됩니다. 짧은 작업은 light 경로로 줄이고, 회사 수립이나 디자인 방향처럼 별도 수명주기가 필요한 일은 전용 workflow로 분리합니다. <!-- claim-id: C-ENTRY-MODEL -->
|
||||
|
||||
이 하네스가 연결하는 범위는 다음과 같습니다.
|
||||
|
||||
- 역할과 family를 이용한 작업 라우팅
|
||||
- 단계별 입력·출력 artifact와 검토 권한
|
||||
- 상태 전이 전 exit gate와 사람 승인
|
||||
- subagent 실행, 도구 사용, 증거 기록, 종료 검증 hook
|
||||
- 프로젝트별 report·evidence·state 저장소
|
||||
|
||||
<!-- section-id: operating-model -->
|
||||
## 핵심 운영 모델
|
||||
|
||||
1. **계약이 실행보다 먼저입니다.** `workflow-contracts.yaml`이 stage, command, artifact bundle, reviewer capability, exit gate를 정의하고 `state_engine.py`가 그 그래프를 읽습니다. <!-- claim-id: C-CONTRACT-MODEL -->
|
||||
2. **판단과 구현의 협업 방식이 다릅니다.** 현재 family 정책은 판단·설계·분석을 멤버별로 격리하는 fan-out과 코드·실행을 한 concrete worker로 모으는 collapse를 구분합니다. <!-- claim-id: C-COLLAB-MODEL -->
|
||||
3. **중요 결정은 자동 완주하지 않습니다.** 전체 cascade는 방향 수용과 release 승인 같은 사람 결정 지점에서 멈추도록 정의되어 있습니다. <!-- claim-id: C-HUMAN-BOUNDARY -->
|
||||
4. **결과보다 provenance를 함께 남깁니다.** workflow와 artifact는 append-only event 및 id+SHA-256 snapshot으로 연결되고, report는 새 시도마다 새 파일로 발급됩니다. <!-- claim-id: C-PROVENANCE-MODEL -->
|
||||
|
||||
Claude Code가 이 프로젝트의 `.claude/settings.json`을 로드하면 PreToolUse, PostToolUse, SubagentStart, SubagentStop, Stop 이벤트가 각각 도구 경계·증거 원장·subagent 등록·종료 검증에 연결됩니다. <!-- claim-id: C-HOOK-MODEL -->
|
||||
|
||||
<!-- section-id: quick-start -->
|
||||
## 시작하기
|
||||
|
||||
### 1. 필수 도구 확인
|
||||
|
||||
핵심 hook과 테스트에는 Python 3.10 이상과 PyYAML 6.0 이상이 필요합니다. `requirements.txt`는 PyYAML 6.0.1과 jsonschema 4.10.3을 고정합니다. <!-- claim-id: C-PREREQUISITES -->
|
||||
|
||||
저장소 루트에서 의존성을 설치합니다.
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
<!-- claim-id: C-INSTALL-COMMAND -->
|
||||
|
||||
### 2. 워크스페이스 지정
|
||||
|
||||
산출물 경로는 `ORGOS_WORKSPACE` 환경변수를 먼저 사용하고, 없으면 `.orgos-workspace`의 첫 유효 줄을 사용합니다. 둘 다 없으면 strict 운영 hook은 exit 2로 중단합니다. <!-- claim-id: C-WORKSPACE-RESOLUTION -->
|
||||
|
||||
저장소 자체를 점검할 때는 테스트용 `_sandbox`를 명시할 수 있습니다. 실제 작업에서는 별도의 프로젝트 디렉터리를 지정하십시오.
|
||||
|
||||
```bash
|
||||
export ORGOS_WORKSPACE=_sandbox
|
||||
python3 .claude/hooks/doctor.py
|
||||
```
|
||||
<!-- claim-id: C-DOCTOR-COMMAND -->
|
||||
|
||||
`doctor.py`는 hook 배선, 참조 스크립트, Python 의존성, workspace, 참조 무결성을 점검하고 hard failure가 있으면 비영점으로 종료합니다. <!-- claim-id: C-DOCTOR-SCOPE -->
|
||||
|
||||
### 3. 첫 워크플로 시작
|
||||
|
||||
Claude Code에서 일반적인 새 제품·개발·운영 요청은 `/ceo-intake`로 시작합니다. 이 단계가 `decision-brief`와 `workload-profile`을 만들고 다음 plan의 입구를 정합니다. `/doctor`, `/consult`, 독립 `/design-system`처럼 자체 목적이 있는 command는 예외입니다. <!-- claim-id: C-FIRST-COMMAND -->
|
||||
|
||||
<!-- section-id: workflows -->
|
||||
## 작업에 맞는 워크플로 선택
|
||||
|
||||
| 경로 | 적합한 작업 | 공식 흐름과 종단 |
|
||||
|---|---|---|
|
||||
| **cascade** | 근거 탐색, 방향 결정, 설계, 명세, 구현, 검증, release를 모두 거치는 작업 | `/ceo-intake` → `/ground` → `/decide` → `/design` → `/spec` → `/build` → `/review-output` → `/release-check` → `released` <!-- claim-id: C-WORKFLOW-CASCADE --> |
|
||||
| **wave** | 계획한 여러 작업을 wave로 실행하고 검증·수용하는 작업 | `/ceo-intake` → `/plan-wave` → `/run-wave` → `/review-output` → `/release-check` → `released` <!-- claim-id: C-WORKFLOW-WAVE --> |
|
||||
| **light** | 저위험·two-way-door·single-role이며 고객·매출·보안 영향이 없는 작업 | `/ceo-intake` → `/run-wave` → `/review-output` → `acceptance` <!-- claim-id: C-WORKFLOW-LIGHT --> |
|
||||
| **venture-bootstrap** | company context가 아직 template인 새 회사·제품의 수립 | founder context를 채운 뒤 `/ceo-intake --plan venture-bootstrap` → `/venture-validate` → `/company-bootstrap` → `bootstrap-complete` <!-- claim-id: C-WORKFLOW-VENTURE --> |
|
||||
|
||||
`/run-cascade`는 cascade의 현재 stage와 다음 command를 계산하는 상위 드라이버입니다. `/design-direction`은 제품 cascade에 종속된 방향 탐색 child workflow이고, `/design-system`과 `/consult`는 각각 코드 UI 검증과 독립 자문 산출물에 초점을 둡니다. <!-- claim-id: C-SPECIALIZED-WORKFLOWS -->
|
||||
|
||||
다음 흐름은 `workflow-contracts.yaml`에 정의된 cascade stage와 사람 결정 경계를 요약합니다. <!-- claim-id: C-CASCADE-VISUAL -->
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["intake<br/>/ceo-intake"] --> B["discovery<br/>/ground"]
|
||||
B --> C["decide<br/>/decide"]
|
||||
C --> D{"사람 방향 수용"}
|
||||
D --> E["design<br/>/design"]
|
||||
E --> F["spec<br/>/spec"]
|
||||
F --> G["build<br/>/build"]
|
||||
G --> H["verification<br/>/review-output"]
|
||||
H --> I["acceptance<br/>/release-check"]
|
||||
I --> J{"사람 release 승인"}
|
||||
J --> K["released"]
|
||||
```
|
||||
|
||||
<!-- visual-id: cascade-flow -->
|
||||
|
||||
<!-- section-id: architecture -->
|
||||
## 저장소 구조와 책임
|
||||
|
||||
실행 그래프의 정본은 `org-os/06-agent-work/workflow-contracts.yaml`입니다. 역할·권한 정책은 `org-os/00-role-registry/`에 있고, Claude Code용 command·agent·skill·hook은 `.claude/` 아래에서 이 계약을 소비하거나 검증합니다. <!-- claim-id: C-ARCH-SOURCE -->
|
||||
|
||||
| 경로 | 책임 |
|
||||
|---|---|
|
||||
| `org-os/00-role-registry/` | 역할, capability family, lens, 권한과 라우팅 정책 |
|
||||
| `org-os/06-agent-work/` | workflow graph, artifact vocabulary, 협업·실행 정책 |
|
||||
| `.claude/commands/` | 사용자가 호출하는 slash command 정의 |
|
||||
| `.claude/agents/` | registry에서 생성되는 worker·lead·router·resolver 카드 |
|
||||
| `.claude/skills/` | concrete role별 작업 방법과 자기검증 절차 |
|
||||
| `.claude/hooks/` | 상태 엔진, 도구 경계, report·evidence 검증, 생성기와 렌더러 |
|
||||
| `.claude/schemas/` | workflow artifact와 report의 typed schema |
|
||||
| `.claude/tests/` | hook 강제기와 workflow 계약 테스트 |
|
||||
| `benchmark/` | golden task, 실행 ledger, plain 대 harness 비교 |
|
||||
| `docs/` | 설계·계획·감사 이력 |
|
||||
|
||||
<!-- claim-id: C-DIRECTORY-MAP -->
|
||||
|
||||
현재 registry는 75개 AI 역할과 최종 사람 소유자 `HUMAN-001`, 28개 routing family, 12개 평가 lens를 정의합니다. agent generator의 현재 정합 계약은 101개 agent card입니다. <!-- claim-id: C-ROLE-MODEL -->
|
||||
|
||||
기여할 때는 산출된 `.claude/agents/*.md`만 직접 고치기보다 역할·family·method·tool 정본을 먼저 수정하고 생성기 정합 검사를 통과시키는 구조를 따르십시오. <!-- claim-id: C-GENERATED-AGENTS -->
|
||||
|
||||
<!-- section-id: artifacts -->
|
||||
## 워크스페이스와 산출물
|
||||
|
||||
`ORGOS_WORKSPACE`가 상대 경로이면 저장소 루트 아래 프로젝트 디렉터리로 해석되고, 절대 경로이면 그대로 사용됩니다. workspace 아래에는 실행 결과와 상태가 다음처럼 분리됩니다. <!-- claim-id: C-WORKSPACE-LAYOUT -->
|
||||
|
||||
```text
|
||||
<workspace>/
|
||||
├── completion-records/<workflow>/ # 불변 .report.yaml과 사람용 .md
|
||||
├── evidence/ # 실행·파일 receipt와 근거
|
||||
├── reports/ # INDEX와 사람이 읽는 집계 뷰
|
||||
├── state/ # workflow·artifact·acceptance event
|
||||
├── slack-inbox/ · slack-outbox/ # 승인 정책을 따르는 알림 큐
|
||||
└── design-system/ # 해당 프로젝트에 UI 산출물이 있을 때
|
||||
```
|
||||
|
||||
report는 `<workspace>/completion-records/<workflow>/<role>-<UTC timestamp>.report.yaml` 형식으로 새로 발급됩니다. 실행 command와 exit code, 작성 파일 경로와 SHA-256은 evidence ledger의 receipt로 남길 수 있지만, workspace를 해석하지 못한 계측 hook은 기록을 생략할 수 있습니다. <!-- claim-id: C-REPORT-RECEIPTS -->
|
||||
|
||||
<!-- section-id: verification -->
|
||||
## 검증 방법과 증거 수준
|
||||
|
||||
다음 명령은 README 작성 과정에서 대상 스크립트와 경로를 **정적으로 확인**했습니다. 이 작업트리에서는 의존성 설치나 대상 테스트 suite를 실행하지 않았으므로, 정적 통과를 실제 실행 성공으로 해석하면 안 됩니다.
|
||||
|
||||
| 목적 | 명령 | 성공 신호와 현재 확인 수준 |
|
||||
|---|---|---|
|
||||
| hook·workspace preflight | `python3 .claude/hooks/doctor.py` | hard failure가 없고 exit 0. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-DOCTOR --> |
|
||||
| agent card 정합 | `python3 .claude/hooks/gen_agents.py --check` | 101개 카드 계약과 생성 내용 정합. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-AGENTS --> |
|
||||
| 전체 저장소 suite | `python3 .claude/tests/run_all.py` | preflight 뒤 모든 `test_*.py`가 green이고 exit 0. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-TESTS --> |
|
||||
| golden task 목록 | `python3 .claude/hooks/benchmark.py list` | 정의된 13개 task를 출력. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-BENCHMARK --> |
|
||||
|
||||
`run_all.py`는 artifact registry check, doctor, reference lint를 거친 뒤 `.claude/tests/test_*.py`를 suite별 제한시간과 함께 순차 실행합니다. 하나라도 실패하거나 timeout이면 exit 1입니다. <!-- claim-id: C-TEST-RUNNER -->
|
||||
|
||||
GitHub Actions는 Python 3.12와 Node 20, `_sandbox` workspace에서 의존성을 설치하고 doctor, reference lint, agent generation check, 전체 test suite를 분리해 실행하도록 정의돼 있습니다. <!-- claim-id: C-CI -->
|
||||
|
||||
벤치마크에는 13개 golden task가 정의돼 있지만 현재 실행 ledger에는 GT-01과 GT-R2의 plain·harness 표본만 있습니다. 두 과제는 first-pass acceptance, test pass rate, unnecessary change lines에서 모두 동률이므로 현재 데이터는 하네스의 품질 우위를 입증하지 않습니다. <!-- claim-id: C-BENCHMARK-STATUS -->
|
||||
|
||||
<!-- section-id: limitations -->
|
||||
## 현재 상태와 한계
|
||||
|
||||
- `company-context.yaml`과 `founder-context.yaml`은 현재 `template` 상태입니다. 회사 수립 경로를 사용하려면 사람이 founder context를 채우고 venture-bootstrap을 거쳐야 합니다. <!-- claim-id: C-LIMIT-CONTEXT -->
|
||||
- 강제 hook은 Claude Code가 이 저장소의 `.claude/settings.json`을 로드한 세션 경계 안에서 동작합니다. 다른 실행 환경에서 같은 강제를 자동으로 보장하지 않습니다. <!-- claim-id: C-LIMIT-HOOKS -->
|
||||
- UI preview는 DOM mount, bundle, 대비, focus, 반응형 screenshot 같은 render health를 검사하지만 시각적 차별성·타이포그래피·비례·spacing의 미학 품질을 판정하지 않습니다. <!-- claim-id: C-LIMIT-UI -->
|
||||
- Node 18 이상과 D2 0.6 이상은 관련 기능의 권장 도구이고, Marp 3 이상은 선택 사항입니다. 전체 UI render에는 Chrome 또는 Chromium 계열 실행 파일도 필요합니다. <!-- claim-id: C-LIMIT-TOOLS -->
|
||||
- plain 대 harness의 현재 실행 표본은 저난도 bugfix 두 과제뿐이며 결과는 동률입니다. 설계·문서·의사결정 과제에 대한 품질 향상은 아직 실증되지 않았습니다. <!-- claim-id: C-LIMIT-EVIDENCE -->
|
||||
|
||||
<!-- section-id: reference -->
|
||||
## 정본 파일 지도
|
||||
|
||||
- Workflow와 artifact: [workflow-contracts.yaml](org-os/06-agent-work/workflow-contracts.yaml) · [artifact vocabulary](org-os/06-agent-work/artifact-type-vocabulary.yaml)
|
||||
- 역할과 라우팅: [roles.yaml](org-os/00-role-registry/roles.yaml) · [capability-families.yaml](org-os/00-role-registry/capability-families.yaml)
|
||||
- 권한과 실행: [tool-permission-matrix.yaml](org-os/00-role-registry/tool-permission-matrix.yaml) · [execution-policy.yaml](org-os/06-agent-work/execution-policy.yaml)
|
||||
- 런타임 요구사항: [tool-versions.yaml](.claude/tool-versions.yaml) · [requirements.txt](requirements.txt)
|
||||
- Claude Code 어댑터: [commands](.claude/commands/) · [hooks](.claude/hooks/) · [schemas](.claude/schemas/) · [tests](.claude/tests/)
|
||||
- 실증 자료: [golden tasks](benchmark/golden-tasks.yaml) · [benchmark report](benchmark/BENCHMARK.md)
|
||||
- 설계와 변경 이력: [docs](docs/)
|
||||
|
||||
README는 첫 판단과 운영 진입에 필요한 정보만 유지합니다. 세부 규칙을 바꿀 때는 위 정본을 수정하고 관련 생성·검증 경로를 함께 확인하십시오.
|
||||
@@ -0,0 +1,171 @@
|
||||
# Org OS 하네스 — Claude Code용 에이전트 운영체계
|
||||
|
||||
Org OS 하네스는 제품·개발·운영·GTM 업무를 여러 AI 역할에 배분하고, 단계별 산출물과 사람 승인을 파일 계약으로 연결하는 Claude Code 프로젝트 하네스입니다. <!-- claim-id: C-IDENTITY -->
|
||||
|
||||
이 저장소의 핵심은 역할 프롬프트의 개수가 아니라 **누가 무엇을 만들고, 어떤 근거로 검토하며, 어느 조건에서 다음 단계로 갈 수 있는지**를 명시하는 데 있습니다. 워크플로 그래프, 역할·권한, typed artifact, 실행 증거를 각각 정본 파일과 hook으로 연결합니다. <!-- claim-id: C-VALUE -->
|
||||
|
||||
<!-- section-id: overview -->
|
||||
## 무엇을 제공하나요?
|
||||
|
||||
일반적인 새 작업은 `/ceo-intake`에서 의도와 작업 규모를 구조화한 뒤, 선택된 plan에 따라 discovery·decision·design·build·verification·acceptance로 진행됩니다. 짧은 작업은 light 경로로 줄이고, 회사 수립이나 디자인 방향처럼 별도 수명주기가 필요한 일은 전용 workflow로 분리합니다. <!-- claim-id: C-ENTRY-MODEL -->
|
||||
|
||||
이 하네스가 연결하는 범위는 다음과 같습니다.
|
||||
|
||||
- 역할과 family를 이용한 작업 라우팅
|
||||
- 단계별 입력·출력 artifact와 검토 권한
|
||||
- 상태 전이 전 exit gate와 사람 승인
|
||||
- subagent 실행, 도구 사용, 증거 기록, 종료 검증 hook
|
||||
- 프로젝트별 report·evidence·state 저장소
|
||||
|
||||
<!-- section-id: operating-model -->
|
||||
## 핵심 운영 모델
|
||||
|
||||
1. **계약이 실행보다 먼저입니다.** `workflow-contracts.yaml`이 stage, command, artifact bundle, reviewer capability, exit gate를 정의하고 `state_engine.py`가 그 그래프를 읽습니다. <!-- claim-id: C-CONTRACT-MODEL -->
|
||||
2. **판단과 구현의 협업 방식이 다릅니다.** 현재 family 정책은 판단·설계·분석을 멤버별로 격리하는 fan-out과 코드·실행을 한 concrete worker로 모으는 collapse를 구분합니다. <!-- claim-id: C-COLLAB-MODEL -->
|
||||
3. **중요 결정은 자동 완주하지 않습니다.** 전체 cascade는 방향 수용과 release 승인 같은 사람 결정 지점에서 멈추도록 정의되어 있습니다. <!-- claim-id: C-HUMAN-BOUNDARY -->
|
||||
4. **결과보다 provenance를 함께 남깁니다.** workflow와 artifact는 append-only event 및 id+SHA-256 snapshot으로 연결되고, report는 새 시도마다 새 파일로 발급됩니다. <!-- claim-id: C-PROVENANCE-MODEL -->
|
||||
|
||||
Claude Code가 이 프로젝트의 `.claude/settings.json`을 로드하면 PreToolUse, PostToolUse, SubagentStart, SubagentStop, Stop 이벤트가 각각 도구 경계·증거 원장·subagent 등록·종료 검증에 연결됩니다. <!-- claim-id: C-HOOK-MODEL -->
|
||||
|
||||
<!-- section-id: quick-start -->
|
||||
## 시작하기
|
||||
|
||||
### 1. 필수 도구 확인
|
||||
|
||||
핵심 hook과 테스트에는 Python 3.10 이상과 PyYAML 6.0 이상이 필요합니다. `requirements.txt`는 PyYAML 6.0.1과 jsonschema 4.10.3을 고정합니다. <!-- claim-id: C-PREREQUISITES -->
|
||||
|
||||
저장소 루트에서 의존성을 설치합니다.
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
<!-- claim-id: C-INSTALL-COMMAND -->
|
||||
|
||||
### 2. 워크스페이스 지정
|
||||
|
||||
산출물 경로는 `ORGOS_WORKSPACE` 환경변수를 먼저 사용하고, 없으면 `.orgos-workspace`의 첫 유효 줄을 사용합니다. 둘 다 없으면 strict 운영 hook은 exit 2로 중단합니다. <!-- claim-id: C-WORKSPACE-RESOLUTION -->
|
||||
|
||||
저장소 자체를 점검할 때는 테스트용 `_sandbox`를 명시할 수 있습니다. 실제 작업에서는 별도의 프로젝트 디렉터리를 지정하십시오.
|
||||
|
||||
```bash
|
||||
export ORGOS_WORKSPACE=_sandbox
|
||||
python3 .claude/hooks/doctor.py
|
||||
```
|
||||
<!-- claim-id: C-DOCTOR-COMMAND -->
|
||||
|
||||
`doctor.py`는 hook 배선, 참조 스크립트, Python 의존성, workspace, 참조 무결성을 점검하고 hard failure가 있으면 비영점으로 종료합니다. <!-- claim-id: C-DOCTOR-SCOPE -->
|
||||
|
||||
### 3. 첫 워크플로 시작
|
||||
|
||||
Claude Code에서 일반적인 새 제품·개발·운영 요청은 `/ceo-intake`로 시작합니다. 이 단계가 `decision-brief`와 `workload-profile`을 만들고 다음 plan의 입구를 정합니다. `/doctor`, `/consult`, 독립 `/design-system`처럼 자체 목적이 있는 command는 예외입니다. <!-- claim-id: C-FIRST-COMMAND -->
|
||||
|
||||
<!-- section-id: workflows -->
|
||||
## 작업에 맞는 워크플로 선택
|
||||
|
||||
| 경로 | 적합한 작업 | 공식 흐름과 종단 |
|
||||
|---|---|---|
|
||||
| **cascade** | 근거 탐색, 방향 결정, 설계, 명세, 구현, 검증, release를 모두 거치는 작업 | `/ceo-intake` → `/ground` → `/decide` → `/design` → `/spec` → `/build` → `/review-output` → `/release-check` → `released` <!-- claim-id: C-WORKFLOW-CASCADE --> |
|
||||
| **wave** | 계획한 여러 작업을 wave로 실행하고 검증·수용하는 작업 | `/ceo-intake` → `/plan-wave` → `/run-wave` → `/review-output` → `/release-check` → `released` <!-- claim-id: C-WORKFLOW-WAVE --> |
|
||||
| **light** | 저위험·two-way-door·single-role이며 고객·매출·보안 영향이 없는 작업 | `/ceo-intake` → `/run-wave` → `/review-output` → `acceptance` <!-- claim-id: C-WORKFLOW-LIGHT --> |
|
||||
| **venture-bootstrap** | company context가 아직 template인 새 회사·제품의 수립 | founder context를 채운 뒤 `/ceo-intake --plan venture-bootstrap` → `/venture-validate` → `/company-bootstrap` → `bootstrap-complete` <!-- claim-id: C-WORKFLOW-VENTURE --> |
|
||||
|
||||
`/run-cascade`는 cascade의 현재 stage와 다음 command를 계산하는 상위 드라이버입니다. `/design-direction`은 제품 cascade에 종속된 방향 탐색 child workflow이고, `/design-system`과 `/consult`는 각각 코드 UI 검증과 독립 자문 산출물에 초점을 둡니다. <!-- claim-id: C-SPECIALIZED-WORKFLOWS -->
|
||||
|
||||
다음 흐름은 `workflow-contracts.yaml`에 정의된 cascade stage와 사람 결정 경계를 요약합니다. <!-- claim-id: C-CASCADE-VISUAL -->
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["intake<br/>/ceo-intake"] --> B["discovery<br/>/ground"]
|
||||
B --> C["decide<br/>/decide"]
|
||||
C --> D{"사람 방향 수용"}
|
||||
D --> E["design<br/>/design"]
|
||||
E --> F["spec<br/>/spec"]
|
||||
F --> G["build<br/>/build"]
|
||||
G --> H["verification<br/>/review-output"]
|
||||
H --> I["acceptance<br/>/release-check"]
|
||||
I --> J{"사람 release 승인"}
|
||||
J --> K["released"]
|
||||
```
|
||||
|
||||
<!-- visual-id: cascade-flow -->
|
||||
|
||||
<!-- section-id: architecture -->
|
||||
## 저장소 구조와 책임
|
||||
|
||||
실행 그래프의 정본은 `org-os/06-agent-work/workflow-contracts.yaml`입니다. 역할·권한 정책은 `org-os/00-role-registry/`에 있고, Claude Code용 command·agent·skill·hook은 `.claude/` 아래에서 이 계약을 소비하거나 검증합니다. <!-- claim-id: C-ARCH-SOURCE -->
|
||||
|
||||
| 경로 | 책임 |
|
||||
|---|---|
|
||||
| `org-os/00-role-registry/` | 역할, capability family, lens, 권한과 라우팅 정책 |
|
||||
| `org-os/06-agent-work/` | workflow graph, artifact vocabulary, 협업·실행 정책 |
|
||||
| `.claude/commands/` | 사용자가 호출하는 slash command 정의 |
|
||||
| `.claude/agents/` | registry에서 생성되는 worker·lead·router·resolver 카드 |
|
||||
| `.claude/skills/` | concrete role별 작업 방법과 자기검증 절차 |
|
||||
| `.claude/hooks/` | 상태 엔진, 도구 경계, report·evidence 검증, 생성기와 렌더러 |
|
||||
| `.claude/schemas/` | workflow artifact와 report의 typed schema |
|
||||
| `.claude/tests/` | hook 강제기와 workflow 계약 테스트 |
|
||||
| `benchmark/` | golden task, 실행 ledger, plain 대 harness 비교 |
|
||||
| `docs/` | 설계·계획·감사 이력 |
|
||||
|
||||
<!-- claim-id: C-DIRECTORY-MAP -->
|
||||
|
||||
현재 registry는 75개 AI 역할과 최종 사람 소유자 `HUMAN-001`, 28개 routing family, 12개 평가 lens를 정의합니다. agent generator의 현재 정합 계약은 101개 agent card입니다. <!-- claim-id: C-ROLE-MODEL -->
|
||||
|
||||
기여할 때는 산출된 `.claude/agents/*.md`만 직접 고치기보다 역할·family·method·tool 정본을 먼저 수정하고 생성기 정합 검사를 통과시키는 구조를 따르십시오. <!-- claim-id: C-GENERATED-AGENTS -->
|
||||
|
||||
<!-- section-id: artifacts -->
|
||||
## 워크스페이스와 산출물
|
||||
|
||||
`ORGOS_WORKSPACE`가 상대 경로이면 저장소 루트 아래 프로젝트 디렉터리로 해석되고, 절대 경로이면 그대로 사용됩니다. workspace 아래에는 실행 결과와 상태가 다음처럼 분리됩니다. <!-- claim-id: C-WORKSPACE-LAYOUT -->
|
||||
|
||||
```text
|
||||
<workspace>/
|
||||
├── completion-records/<workflow>/ # 불변 .report.yaml과 사람용 .md
|
||||
├── evidence/ # 실행·파일 receipt와 근거
|
||||
├── reports/ # INDEX와 사람이 읽는 집계 뷰
|
||||
├── state/ # workflow·artifact·acceptance event
|
||||
├── slack-inbox/ · slack-outbox/ # 승인 정책을 따르는 알림 큐
|
||||
└── design-system/ # 해당 프로젝트에 UI 산출물이 있을 때
|
||||
```
|
||||
|
||||
report는 `<workspace>/completion-records/<workflow>/<role>-<UTC timestamp>.report.yaml` 형식으로 새로 발급됩니다. 실행 command와 exit code, 작성 파일 경로와 SHA-256은 evidence ledger의 receipt로 남길 수 있지만, workspace를 해석하지 못한 계측 hook은 기록을 생략할 수 있습니다. <!-- claim-id: C-REPORT-RECEIPTS -->
|
||||
|
||||
<!-- section-id: verification -->
|
||||
## 검증 방법과 증거 수준
|
||||
|
||||
다음 명령은 README 작성 과정에서 대상 스크립트와 경로를 **정적으로 확인**했습니다. 이 작업트리에서는 의존성 설치나 대상 테스트 suite를 실행하지 않았으므로, 정적 통과를 실제 실행 성공으로 해석하면 안 됩니다.
|
||||
|
||||
| 목적 | 명령 | 성공 신호와 현재 확인 수준 |
|
||||
|---|---|---|
|
||||
| hook·workspace preflight | `python3 .claude/hooks/doctor.py` | hard failure가 없고 exit 0. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-DOCTOR --> |
|
||||
| agent card 정합 | `python3 .claude/hooks/gen_agents.py --check` | 101개 카드 계약과 생성 내용 정합. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-AGENTS --> |
|
||||
| 전체 저장소 suite | `python3 .claude/tests/run_all.py` | preflight 뒤 모든 `test_*.py`가 green이고 exit 0. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-TESTS --> |
|
||||
| golden task 목록 | `python3 .claude/hooks/benchmark.py list` | 정의된 13개 task를 출력. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-BENCHMARK --> |
|
||||
|
||||
`run_all.py`는 artifact registry check, doctor, reference lint를 거친 뒤 `.claude/tests/test_*.py`를 suite별 제한시간과 함께 순차 실행합니다. 하나라도 실패하거나 timeout이면 exit 1입니다. <!-- claim-id: C-TEST-RUNNER -->
|
||||
|
||||
GitHub Actions는 Python 3.12와 Node 20, `_sandbox` workspace에서 의존성을 설치하고 doctor, reference lint, agent generation check, 전체 test suite를 분리해 실행하도록 정의돼 있습니다. <!-- claim-id: C-CI -->
|
||||
|
||||
벤치마크에는 13개 golden task가 정의돼 있지만 현재 실행 ledger에는 GT-01과 GT-R2의 plain·harness 표본만 있습니다. 두 과제는 first-pass acceptance, test pass rate, unnecessary change lines에서 모두 동률이므로 현재 데이터는 하네스의 품질 우위를 입증하지 않습니다. <!-- claim-id: C-BENCHMARK-STATUS -->
|
||||
|
||||
<!-- section-id: limitations -->
|
||||
## 현재 상태와 한계
|
||||
|
||||
- `company-context.yaml`과 `founder-context.yaml`은 현재 `template` 상태입니다. 회사 수립 경로를 사용하려면 사람이 founder context를 채우고 venture-bootstrap을 거쳐야 합니다. <!-- claim-id: C-LIMIT-CONTEXT -->
|
||||
- 강제 hook은 Claude Code가 이 저장소의 `.claude/settings.json`을 로드한 세션 경계 안에서 동작합니다. 다른 실행 환경에서 같은 강제를 자동으로 보장하지 않습니다. <!-- claim-id: C-LIMIT-HOOKS -->
|
||||
- UI preview는 DOM mount, bundle, 대비, focus, 반응형 screenshot 같은 render health를 검사하지만 시각적 차별성·타이포그래피·비례·spacing의 미학 품질을 판정하지 않습니다. <!-- claim-id: C-LIMIT-UI -->
|
||||
- Node 18 이상과 D2 0.6 이상은 관련 기능의 권장 도구이고, Marp 3 이상은 선택 사항입니다. 전체 UI render에는 Chrome 또는 Chromium 계열 실행 파일도 필요합니다. <!-- claim-id: C-LIMIT-TOOLS -->
|
||||
- plain 대 harness의 현재 실행 표본은 저난도 bugfix 두 과제뿐이며 결과는 동률입니다. 설계·문서·의사결정 과제에 대한 품질 향상은 아직 실증되지 않았습니다. <!-- claim-id: C-LIMIT-EVIDENCE -->
|
||||
|
||||
<!-- section-id: reference -->
|
||||
## 정본 파일 지도
|
||||
|
||||
- Workflow와 artifact: [workflow-contracts.yaml](org-os/06-agent-work/workflow-contracts.yaml) · [artifact vocabulary](org-os/06-agent-work/artifact-type-vocabulary.yaml)
|
||||
- 역할과 라우팅: [roles.yaml](org-os/00-role-registry/roles.yaml) · [capability-families.yaml](org-os/00-role-registry/capability-families.yaml)
|
||||
- 권한과 실행: [tool-permission-matrix.yaml](org-os/00-role-registry/tool-permission-matrix.yaml) · [execution-policy.yaml](org-os/06-agent-work/execution-policy.yaml)
|
||||
- 런타임 요구사항: [tool-versions.yaml](.claude/tool-versions.yaml) · [requirements.txt](requirements.txt)
|
||||
- Claude Code 어댑터: [commands](.claude/commands/) · [hooks](.claude/hooks/) · [schemas](.claude/schemas/) · [tests](.claude/tests/)
|
||||
- 실증 자료: [golden tasks](benchmark/golden-tasks.yaml) · [benchmark report](benchmark/BENCHMARK.md)
|
||||
- 설계와 변경 이력: [docs](docs/)
|
||||
|
||||
README는 첫 판단과 운영 진입에 필요한 정보만 유지합니다. 세부 규칙을 바꿀 때는 위 정본을 수정하고 관련 생성·검증 경로를 함께 확인하십시오.
|
||||
@@ -0,0 +1,271 @@
|
||||
--- README.md (current)
|
||||
+++ README.md (candidate)
|
||||
@@ -1,120 +1,171 @@
|
||||
-# Org OS 하네스 — 실행 안내
|
||||
+# Org OS 하네스 — Claude Code용 에이전트 운영체계
|
||||
|
||||
-회사를 AI 에이전트로 운영하는 파일 기반 운영체계. 개발 + 비즈니스(수익)를 함께 다룬다.
|
||||
-규칙·구조는 [CLAUDE.md](CLAUDE.md), 상태/기록 구분은 [org-os/06-agent-work/README.md](org-os/06-agent-work/README.md).
|
||||
+Org OS 하네스는 제품·개발·운영·GTM 업무를 여러 AI 역할에 배분하고, 단계별 산출물과 사람 승인을 파일 계약으로 연결하는 Claude Code 프로젝트 하네스입니다. <!-- claim-id: C-IDENTITY -->
|
||||
|
||||
-## 🚀 어떤 커맨드부터? — 항상 `/ceo-intake`
|
||||
+이 저장소의 핵심은 역할 프롬프트의 개수가 아니라 **누가 무엇을 만들고, 어떤 근거로 검토하며, 어느 조건에서 다음 단계로 갈 수 있는지**를 명시하는 데 있습니다. 워크플로 그래프, 역할·권한, typed artifact, 실행 증거를 각각 정본 파일과 hook으로 연결합니다. <!-- claim-id: C-VALUE -->
|
||||
|
||||
-**새 워크플로**는 **`/ceo-intake`**로 시작한다 — 사용자 요청을 Decision Brief(mode·tier·후보 직무)로 정리한다. (모순 아님: **기존 wf-id**는 선행 gating 산출물이 있으면 중간 stage에서 재개 가능 — B. 참조. `state_engine`이 전이 선행조건을 검증한다.)
|
||||
-그다음은 **상황(tier·명확도)에 따라** 갈린다:
|
||||
+<!-- section-id: overview -->
|
||||
+## 무엇을 제공하나요?
|
||||
|
||||
-### 새 회사/제품을 처음 세울 때(venture-bootstrap)
|
||||
+일반적인 새 작업은 `/ceo-intake`에서 의도와 작업 규모를 구조화한 뒤, 선택된 plan에 따라 discovery·decision·design·build·verification·acceptance로 진행됩니다. 짧은 작업은 light 경로로 줄이고, 회사 수립이나 디자인 방향처럼 별도 수명주기가 필요한 일은 전용 workflow로 분리합니다. <!-- claim-id: C-ENTRY-MODEL -->
|
||||
|
||||
-company-context가 아직 `template`이면 제품 cascade 전에 회사부터 세운다:
|
||||
+이 하네스가 연결하는 범위는 다음과 같습니다.
|
||||
|
||||
-1. `org-os/01-company/founder-context.yaml`을 채운다(status: filled).
|
||||
-2. `/ceo-intake --plan venture-bootstrap` → `/venture-validate`(기회탐색+9-gate 검증) → `/company-bootstrap`(C-Level 수렴 + 사람 승인 + company-context 원자 commit).
|
||||
-3. 완료되면 공식 company-context.status = `provisional`. 이제 `/ground`부터 제품 cascade를 탄다.
|
||||
+- 역할과 family를 이용한 작업 라우팅
|
||||
+- 단계별 입력·출력 artifact와 검토 권한
|
||||
+- 상태 전이 전 exit gate와 사람 승인
|
||||
+- subagent 실행, 도구 사용, 증거 기록, 종료 검증 hook
|
||||
+- 프로젝트별 report·evidence·state 저장소
|
||||
|
||||
-기존 회사(status ∈ {provisional, operating})면 곧장 `/ceo-intake` → `/ground`.
|
||||
+<!-- section-id: operating-model -->
|
||||
+## 핵심 운영 모델
|
||||
|
||||
-### A. 새 전략 결정 (신규 제품·수익·방향, 아이디어 불명확) — 전체 cascade
|
||||
+1. **계약이 실행보다 먼저입니다.** `workflow-contracts.yaml`이 stage, command, artifact bundle, reviewer capability, exit gate를 정의하고 `state_engine.py`가 그 그래프를 읽습니다. <!-- claim-id: C-CONTRACT-MODEL -->
|
||||
+2. **판단과 구현의 협업 방식이 다릅니다.** 현재 family 정책은 판단·설계·분석을 멤버별로 격리하는 fan-out과 코드·실행을 한 concrete worker로 모으는 collapse를 구분합니다. <!-- claim-id: C-COLLAB-MODEL -->
|
||||
+3. **중요 결정은 자동 완주하지 않습니다.** 전체 cascade는 방향 수용과 release 승인 같은 사람 결정 지점에서 멈추도록 정의되어 있습니다. <!-- claim-id: C-HUMAN-BOUNDARY -->
|
||||
+4. **결과보다 provenance를 함께 남깁니다.** workflow와 artifact는 append-only event 및 id+SHA-256 snapshot으로 연결되고, report는 새 시도마다 새 파일로 발급됩니다. <!-- claim-id: C-PROVENANCE-MODEL -->
|
||||
+
|
||||
+Claude Code가 이 프로젝트의 `.claude/settings.json`을 로드하면 PreToolUse, PostToolUse, SubagentStart, SubagentStop, Stop 이벤트가 각각 도구 경계·증거 원장·subagent 등록·종료 검증에 연결됩니다. <!-- claim-id: C-HOOK-MODEL -->
|
||||
+
|
||||
+<!-- section-id: quick-start -->
|
||||
+## 시작하기
|
||||
+
|
||||
+### 1. 필수 도구 확인
|
||||
+
|
||||
+핵심 hook과 테스트에는 Python 3.10 이상과 PyYAML 6.0 이상이 필요합니다. `requirements.txt`는 PyYAML 6.0.1과 jsonschema 4.10.3을 고정합니다. <!-- claim-id: C-PREREQUISITES -->
|
||||
+
|
||||
+저장소 루트에서 의존성을 설치합니다.
|
||||
+
|
||||
+```bash
|
||||
+pip install -r requirements.txt
|
||||
```
|
||||
-/ceo-intake 의도 → Decision Brief(tier=heavy, divergent→converge)
|
||||
- ↓
|
||||
-/ground discovery: 시장·사용자·경쟁·재무 근거 접지 + option-set(≥2) 발산 (결정 전, anchoring 방지)
|
||||
- ↓
|
||||
-/decide converge: C-Level(CPO·CFO·CTO·COO)이 근거·옵션을 하나로 수렴 → CEO ExecutiveDecisionPacket
|
||||
- ↓ ← 사용자(HUMAN-001) 승인 게이트 (go/no-go)
|
||||
-/design 아키텍트·데이터·디자인·보안 설계 fan-out → 큰 설계문서
|
||||
- ↓ (UI-bearing이면 design-system 서브파이프라인 포함 → 실제 preview_ui 렌더 게이트가 프론트 BUILD 선행조건)
|
||||
-/spec PM·아키텍트 → 기능명세(PRD·api-contract·수용기준)
|
||||
- ↓
|
||||
-/build 구현 family(collapse) + QA/보안 감사 → completion-record
|
||||
- ↓
|
||||
-/review-output Parent 수용 검토(Accepted/Changes-Requested/Blocked)
|
||||
- ↓
|
||||
-/release-check Release Acceptance(DRAI + 인간 게이트)
|
||||
+<!-- claim-id: C-INSTALL-COMMAND -->
|
||||
+
|
||||
+### 2. 워크스페이스 지정
|
||||
+
|
||||
+산출물 경로는 `ORGOS_WORKSPACE` 환경변수를 먼저 사용하고, 없으면 `.orgos-workspace`의 첫 유효 줄을 사용합니다. 둘 다 없으면 strict 운영 hook은 exit 2로 중단합니다. <!-- claim-id: C-WORKSPACE-RESOLUTION -->
|
||||
+
|
||||
+저장소 자체를 점검할 때는 테스트용 `_sandbox`를 명시할 수 있습니다. 실제 작업에서는 별도의 프로젝트 디렉터리를 지정하십시오.
|
||||
+
|
||||
+```bash
|
||||
+export ORGOS_WORKSPACE=_sandbox
|
||||
+python3 .claude/hooks/doctor.py
|
||||
+```
|
||||
+<!-- claim-id: C-DOCTOR-COMMAND -->
|
||||
+
|
||||
+`doctor.py`는 hook 배선, 참조 스크립트, Python 의존성, workspace, 참조 무결성을 점검하고 hard failure가 있으면 비영점으로 종료합니다. <!-- claim-id: C-DOCTOR-SCOPE -->
|
||||
+
|
||||
+### 3. 첫 워크플로 시작
|
||||
+
|
||||
+Claude Code에서 일반적인 새 제품·개발·운영 요청은 `/ceo-intake`로 시작합니다. 이 단계가 `decision-brief`와 `workload-profile`을 만들고 다음 plan의 입구를 정합니다. `/doctor`, `/consult`, 독립 `/design-system`처럼 자체 목적이 있는 command는 예외입니다. <!-- claim-id: C-FIRST-COMMAND -->
|
||||
+
|
||||
+<!-- section-id: workflows -->
|
||||
+## 작업에 맞는 워크플로 선택
|
||||
+
|
||||
+| 경로 | 적합한 작업 | 공식 흐름과 종단 |
|
||||
+|---|---|---|
|
||||
+| **cascade** | 근거 탐색, 방향 결정, 설계, 명세, 구현, 검증, release를 모두 거치는 작업 | `/ceo-intake` → `/ground` → `/decide` → `/design` → `/spec` → `/build` → `/review-output` → `/release-check` → `released` <!-- claim-id: C-WORKFLOW-CASCADE --> |
|
||||
+| **wave** | 계획한 여러 작업을 wave로 실행하고 검증·수용하는 작업 | `/ceo-intake` → `/plan-wave` → `/run-wave` → `/review-output` → `/release-check` → `released` <!-- claim-id: C-WORKFLOW-WAVE --> |
|
||||
+| **light** | 저위험·two-way-door·single-role이며 고객·매출·보안 영향이 없는 작업 | `/ceo-intake` → `/run-wave` → `/review-output` → `acceptance` <!-- claim-id: C-WORKFLOW-LIGHT --> |
|
||||
+| **venture-bootstrap** | company context가 아직 template인 새 회사·제품의 수립 | founder context를 채운 뒤 `/ceo-intake --plan venture-bootstrap` → `/venture-validate` → `/company-bootstrap` → `bootstrap-complete` <!-- claim-id: C-WORKFLOW-VENTURE --> |
|
||||
+
|
||||
+`/run-cascade`는 cascade의 현재 stage와 다음 command를 계산하는 상위 드라이버입니다. `/design-direction`은 제품 cascade에 종속된 방향 탐색 child workflow이고, `/design-system`과 `/consult`는 각각 코드 UI 검증과 독립 자문 산출물에 초점을 둡니다. <!-- claim-id: C-SPECIALIZED-WORKFLOWS -->
|
||||
+
|
||||
+다음 흐름은 `workflow-contracts.yaml`에 정의된 cascade stage와 사람 결정 경계를 요약합니다. <!-- claim-id: C-CASCADE-VISUAL -->
|
||||
+
|
||||
+```mermaid
|
||||
+flowchart LR
|
||||
+ A["intake<br/>/ceo-intake"] --> B["discovery<br/>/ground"]
|
||||
+ B --> C["decide<br/>/decide"]
|
||||
+ C --> D{"사람 방향 수용"}
|
||||
+ D --> E["design<br/>/design"]
|
||||
+ E --> F["spec<br/>/spec"]
|
||||
+ F --> G["build<br/>/build"]
|
||||
+ G --> H["verification<br/>/review-output"]
|
||||
+ H --> I["acceptance<br/>/release-check"]
|
||||
+ I --> J{"사람 release 승인"}
|
||||
+ J --> K["released"]
|
||||
```
|
||||
|
||||
-> **한 번에 걷고 싶으면 — `/run-cascade`** (상위 오케스트레이터). 위 A를 개별 커맨드로 일일이 부르는 대신, `/run-cascade`가 `state_engine`을 재사용해 현재 stage를 확인 → 필요한 stage만 실행 → 산출물 검증 → **사람 결정 지점(DECIDE go/no-go·RELEASE 수용)에서 정지**한다. 사용자는 처음에 문제·목표만 주고 중요한 결정에서만 개입한다. 자동 승인·자동 완주는 하지 않으며(사람 게이트가 존재 이유), 각 stage의 강제(spawn 게이트·validator·전이)는 그대로 작동한다. 사람이 승인하면 `/run-cascade --workflow <wf>`로 재개.
|
||||
+<!-- visual-id: cascade-flow -->
|
||||
|
||||
-### B. 방향이 이미 명확하면 — **중간부터 시작**
|
||||
-- 결정은 섰고 설계부터 → `/design` → `/spec` → `/build`
|
||||
-- 설계도 섰고 명세부터 → `/spec` → `/build`
|
||||
-- 명세·디자인도 있고 바로 개발 → `/build`
|
||||
+<!-- section-id: architecture -->
|
||||
+## 저장소 구조와 책임
|
||||
|
||||
-### C. 단순·저위험 작업 — 경량 경로 (cascade 생략)
|
||||
-```
|
||||
-/ceo-intake (tier=light) → /run-wave (family collapse 실행) → /review-output
|
||||
+실행 그래프의 정본은 `org-os/06-agent-work/workflow-contracts.yaml`입니다. 역할·권한 정책은 `org-os/00-role-registry/`에 있고, Claude Code용 command·agent·skill·hook은 `.claude/` 아래에서 이 계약을 소비하거나 검증합니다. <!-- claim-id: C-ARCH-SOURCE -->
|
||||
+
|
||||
+| 경로 | 책임 |
|
||||
+|---|---|
|
||||
+| `org-os/00-role-registry/` | 역할, capability family, lens, 권한과 라우팅 정책 |
|
||||
+| `org-os/06-agent-work/` | workflow graph, artifact vocabulary, 협업·실행 정책 |
|
||||
+| `.claude/commands/` | 사용자가 호출하는 slash command 정의 |
|
||||
+| `.claude/agents/` | registry에서 생성되는 worker·lead·router·resolver 카드 |
|
||||
+| `.claude/skills/` | concrete role별 작업 방법과 자기검증 절차 |
|
||||
+| `.claude/hooks/` | 상태 엔진, 도구 경계, report·evidence 검증, 생성기와 렌더러 |
|
||||
+| `.claude/schemas/` | workflow artifact와 report의 typed schema |
|
||||
+| `.claude/tests/` | hook 강제기와 workflow 계약 테스트 |
|
||||
+| `benchmark/` | golden task, 실행 ledger, plain 대 harness 비교 |
|
||||
+| `docs/` | 설계·계획·감사 이력 |
|
||||
+
|
||||
+<!-- claim-id: C-DIRECTORY-MAP -->
|
||||
+
|
||||
+현재 registry는 75개 AI 역할과 최종 사람 소유자 `HUMAN-001`, 28개 routing family, 12개 평가 lens를 정의합니다. agent generator의 현재 정합 계약은 101개 agent card입니다. <!-- claim-id: C-ROLE-MODEL -->
|
||||
+
|
||||
+기여할 때는 산출된 `.claude/agents/*.md`만 직접 고치기보다 역할·family·method·tool 정본을 먼저 수정하고 생성기 정합 검사를 통과시키는 구조를 따르십시오. <!-- claim-id: C-GENERATED-AGENTS -->
|
||||
+
|
||||
+<!-- section-id: artifacts -->
|
||||
+## 워크스페이스와 산출물
|
||||
+
|
||||
+`ORGOS_WORKSPACE`가 상대 경로이면 저장소 루트 아래 프로젝트 디렉터리로 해석되고, 절대 경로이면 그대로 사용됩니다. workspace 아래에는 실행 결과와 상태가 다음처럼 분리됩니다. <!-- claim-id: C-WORKSPACE-LAYOUT -->
|
||||
+
|
||||
+```text
|
||||
+<workspace>/
|
||||
+├── completion-records/<workflow>/ # 불변 .report.yaml과 사람용 .md
|
||||
+├── evidence/ # 실행·파일 receipt와 근거
|
||||
+├── reports/ # INDEX와 사람이 읽는 집계 뷰
|
||||
+├── state/ # workflow·artifact·acceptance event
|
||||
+├── slack-inbox/ · slack-outbox/ # 승인 정책을 따르는 알림 큐
|
||||
+└── design-system/ # 해당 프로젝트에 UI 산출물이 있을 때
|
||||
```
|
||||
|
||||
-### D. 외부·독립 컨설팅 문서·덱이 필요하면 — `/consult`
|
||||
-```
|
||||
-/consult 주제 · 자료=<문서> · 대상=<repo>
|
||||
- → 엔게이지먼트 유형으로 family 선택:
|
||||
- • 비즈니스 자문 → FAM-CONSULTING (EM + 전략/운영/조직·변화/디지털/재무·리스크)
|
||||
- • 문서·콘텐츠 설계 → FAM-DOC-CONSULT (DOC-LEAD + 라이터/정보아키텍트/비주얼/개발자교육)
|
||||
- → 진단→권고 storyline → 문서(.md) + 덱(.pptx/.pdf/.html, 시그니처 도해 SVG)
|
||||
-```
|
||||
-컨설팅은 LENS-ADVISORY(외부·제3자 관점) — 사내 결정(`/decide`)·전략분석(`FAM-STRATEGY`)과 별개의 독립 자문 산출물. 제안까지(최종 결정은 사람).
|
||||
+report는 `<workspace>/completion-records/<workflow>/<role>-<UTC timestamp>.report.yaml` 형식으로 새로 발급됩니다. 실행 command와 exit code, 작성 파일 경로와 SHA-256은 evidence ledger의 receipt로 남길 수 있지만, workspace를 해석하지 못한 계측 hook은 기록을 생략할 수 있습니다. <!-- claim-id: C-REPORT-RECEIPTS -->
|
||||
|
||||
-### E. 실제 UI·디자인 시스템을 코드로 만들고 보고 싶으면 — `/design-system`
|
||||
-```
|
||||
-/design-system 주제 · dir=<프로젝트>/design-system
|
||||
- ① design-brief(제약층: brief→references→tokens→decisions→donts, skill=design-craft)
|
||||
- ② DES-PLATFORM → tokens.css(CSS변수 SoT) + components/*.jsx (var(--*)만 소비)
|
||||
- ③ ENG-FE → screens/*.jsx (컴포넌트 조립만) + preview.jsx
|
||||
- ④ preview_ui.py → 패키지매니저 자동감지(pnpm/yarn/npm)→build→headless chrome 렌더검증+반응형 스크린샷+정적 CSS 품질(대비·포커스)
|
||||
- ⑤ 스크린샷 육안검증 → 고치고 preview 재실행(무제한 반복 루프). 스크린샷 존재 ≠ 품질(빈 #root·대비 실패면 게이트 실패)
|
||||
-```
|
||||
-Figma 없이 **코드로** 실제 UI를 만들고 headless chrome으로 확인한다(무료 Figma의 read rate-limit 회피). 산출: `<프로젝트>/design-system/`(tokens·components·screens·preview.png).
|
||||
+<!-- section-id: verification -->
|
||||
+## 검증 방법과 증거 수준
|
||||
|
||||
-> **`/design` ⊃ `/design-system`(UI-bearing이면 통합)** — `/design`은 cascade의 **설계 판단** 단계(아키텍트·데이터·디자인·보안이 *무엇을 만들지* fan-out으로 결정). 이 워크플로가 **사용자 대면 UI를 만들면**(BUILD에 `FAM-ENG-FRONTEND` 포함) `/design`의 fam-design 분기가 **`/design-system` 서브파이프라인을 그대로 돈다** — 산출 `design-type: design-system`은 **실제 `preview_ui` 렌더 게이트(receipt)를 통과해야** 프론트 BUILD가 열린다(`state_engine`이 강제; 산문만으론 안 됨). non-UI 워크플로(백엔드·인프라·의사결정)는 design-system을 요구하지 않는다. `/design-system`은 **독립 실행**(디자인만 반복)도 가능. 디자인·비주얼 직무는 *프레임워크 서술*이 아니라 **제약층(design-brief) + skill**(`design-craft`·`diagram-craft`)로 일한다 — 다이어그램은 **D2 우선**(Mermaid는 폴백).
|
||||
+다음 명령은 README 작성 과정에서 대상 스크립트와 경로를 **정적으로 확인**했습니다. 이 작업트리에서는 의존성 설치나 대상 테스트 suite를 실행하지 않았으므로, 정적 통과를 실제 실행 성공으로 해석하면 안 됩니다.
|
||||
|
||||
-## 커맨드 = 계층, 이전 산출물을 읽는다
|
||||
+| 목적 | 명령 | 성공 신호와 현재 확인 수준 |
|
||||
+|---|---|---|
|
||||
+| hook·workspace preflight | `python3 .claude/hooks/doctor.py` | hard failure가 없고 exit 0. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-DOCTOR --> |
|
||||
+| agent card 정합 | `python3 .claude/hooks/gen_agents.py --check` | 101개 카드 계약과 생성 내용 정합. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-AGENTS --> |
|
||||
+| 전체 저장소 suite | `python3 .claude/tests/run_all.py` | preflight 뒤 모든 `test_*.py`가 green이고 exit 0. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-TESTS --> |
|
||||
+| golden task 목록 | `python3 .claude/hooks/benchmark.py list` | 정의된 13개 task를 출력. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-BENCHMARK --> |
|
||||
|
||||
-| 커맨드 | phase | 호출 계층 | 입력(must-read) | 산출/handoff |
|
||||
-|---|---|---|---|---|
|
||||
-| `/run-cascade` | **전 cascade 오케스트레이터** | Orchestrator(`state_engine`) | 아이디어/문제 또는 `--workflow <wf>` | GROUND→…→BUILD 순차 진행, **사람 게이트서 정지**(자동 완주 X) |
|
||||
-| `/ceo-intake` | intake | CEO | 사용자 요청 | Decision Brief → /ground 또는 /run-wave |
|
||||
-| `/ground` | GROUND/discovery | strategy·PM·UX·CI·pricing | Decision Brief | 근거+option-set(≥2) → /decide |
|
||||
-| `/decide` | DECIDE/converge | C-Level → CEO | discovery 근거+옵션 | ExecutiveDecisionPacket → /design (사람 go/no-go) |
|
||||
-| `/design` | DESIGN | 아키텍트·데이터·디자인·보안 | 승인 결정+verdict | 큰 설계문서(+UI면 design-system·preview 렌더 게이트) → /spec |
|
||||
-| `/spec` | DETAIL | PM·아키텍트 | 설계문서 | 기능명세 → /build |
|
||||
-| `/build` | BUILD | ENG(collapse)+QA | 설계+명세(+UI면 렌더된 design-system) | completion-record → /review-output |
|
||||
-| `/review-output` | review | Parent | completion-record | 수용/반려 |
|
||||
-| `/release-check` | release | DRAI+HUMAN | 수용 결과 | 릴리스 승인(인간 게이트) |
|
||||
-| `/consult` | CONSULT | FAM-CONSULTING(EM+5분과) | 주제+자료+대상repo | 컨설팅 문서(.md)+덱(.pptx/.pdf/.html) |
|
||||
-| `/design-system` | DESIGN-SYSTEM | DES-PLATFORM+ENG-FE | design-brief(제약) | 코드 디자인시스템(tokens·components·screens)+preview.png |
|
||||
+`run_all.py`는 artifact registry check, doctor, reference lint를 거친 뒤 `.claude/tests/test_*.py`를 suite별 제한시간과 함께 순차 실행합니다. 하나라도 실패하거나 timeout이면 exit 1입니다. <!-- claim-id: C-TEST-RUNNER -->
|
||||
|
||||
-- **fan-out**(판단·설계·수익): 역할별 격리 subagent → 각자 보고서 → 상위가 원본 읽고 종합.
|
||||
-- **collapse**(코드·실행): family 1에이전트 단일 보고서(효율).
|
||||
-- 전 단계 공통: 불변보고서(`new_report.py`)·토큰게이트(`token_ledger.py`)·dissent게이트(`validate_report.py`)·태그(`report_tags.py`)·작업전 Slack(`slack_inbox.py`).
|
||||
+GitHub Actions는 Python 3.12와 Node 20, `_sandbox` workspace에서 의존성을 설치하고 doctor, reference lint, agent generation check, 전체 test suite를 분리해 실행하도록 정의돼 있습니다. <!-- claim-id: C-CI -->
|
||||
|
||||
-## 결과는 어디에
|
||||
-산출물·상태는 **프로젝트별 root 폴더**로 나간다(`<project>/`, 현재 워크스페이스=`.orgos-workspace` 또는 env `ORGOS_WORKSPACE`, 미설정 시 중단 — 조용한 test 기본값 없음(WorkspaceNotSetError)). org-os는 SSOT(정의·계약)만 남긴다 — 훅은 [.claude/hooks/_workspace.py](.claude/hooks/_workspace.py)로 경로를 해석한다.
|
||||
-- **불변 보고서(SoT, 에이전트끼리)**: `<project>/completion-records/<workflow>/*.report.yaml`
|
||||
-- **대표용 MD**: 같은 이름 `.md` + 목차 `<project>/reports/INDEX.md` + 토큰 `<project>/reports/TOKENS.md`
|
||||
-- **디자인 시스템**: `<project>/design-system/`(tokens·components·screens·preview.png)
|
||||
-- **워크스페이스**: 산출물은 `ORGOS_WORKSPACE`가 가리키는 프로젝트 폴더로 나간다. 하네스 자기검증용 `_sandbox/`가 기본 데모 워크스페이스.
|
||||
-- **Slack 보고**: 부모=종합 결정 + 스레드 답글=역할별 개별 판정(`#clean-architecture-전체`)
|
||||
+벤치마크에는 13개 golden task가 정의돼 있지만 현재 실행 ledger에는 GT-01과 GT-R2의 plain·harness 표본만 있습니다. 두 과제는 first-pass acceptance, test pass rate, unnecessary change lines에서 모두 동률이므로 현재 데이터는 하네스의 품질 우위를 입증하지 않습니다. <!-- claim-id: C-BENCHMARK-STATUS -->
|
||||
|
||||
-## 검증
|
||||
-```bash
|
||||
-ORGOS_WORKSPACE=<프로젝트> python3 .claude/hooks/doctor.py # 실행 무결성 preflight(설정·hook·의존성·workspace·참조). workspace 미설정이면 FAIL(P0-1 fail-closed 설계)
|
||||
-CLAUDE_PROJECT_DIR="$PWD" ORGOS_WORKSPACE=_sandbox python3 .claude/tests/run_all.py # 전체(doctor+lint_refs+모든 test_*) — CI 진입점
|
||||
-CLAUDE_PROJECT_DIR="$PWD" python3 .claude/hooks/gen_agents.py --check # 101 에이전트 정합
|
||||
-```
|
||||
+<!-- section-id: limitations -->
|
||||
+## 현재 상태와 한계
|
||||
|
||||
-## 품질 검증 상태 (정직 — 과대주장 금지)
|
||||
-이 하네스는 **절차·신뢰경계는 강제되지만, "plain Claude보다 결과가 낫다"는 아직 증명되지 않았다.**
|
||||
-- **측정 인프라는 실재**: `benchmark.py run --execute`가 골든태스크를 plain vs 하네스로 실제 실행(nested claude CLI)하고 pytest·git diff로 객관 채점한다(위조 점수 없음).
|
||||
-- **지금까지 실증**: 단순 버그픽스(GT-01·GT-R2)는 **plain==harness**(둘 다 만점). 하네스가 과차단·과설계를 하지 않음(해 없음)은 확인됐으나 **lift(우위)는 없음** — 단순 과제는 하네스를 exercise하지 않기 때문.
|
||||
-- **미증명**: 하네스의 가치가설(다관점 fan-out·근거접지·사람게이트)이 발휘되는 **모호·설계·의사결정 과제(GT-09~12)는 자동채점 fixture가 없어 아직 측정 못 함**. head-to-head rubric 채점을 붙여야 "품질이 높다"를 말할 수 있다.
|
||||
-```bash
|
||||
-python3 .claude/hooks/benchmark.py list # 골든태스크 목록
|
||||
-python3 .claude/hooks/benchmark.py run --task GT-01 --arm plain --execute # 실제 실행·객관채점(예산 소비)
|
||||
-python3 .claude/hooks/benchmark.py compare # → benchmark/BENCHMARK.md (plain vs 하네스 delta)
|
||||
-```
|
||||
-> 판정 규칙: 어떤 role/fan-out/framework가 이 비교에서 delta≤0이면 비용만 늘리는 것 → 제거/경량화 후보. **증명 안 된 것을 증명된 척하지 않는다.**
|
||||
+- `company-context.yaml`과 `founder-context.yaml`은 현재 `template` 상태입니다. 회사 수립 경로를 사용하려면 사람이 founder context를 채우고 venture-bootstrap을 거쳐야 합니다. <!-- claim-id: C-LIMIT-CONTEXT -->
|
||||
+- 강제 hook은 Claude Code가 이 저장소의 `.claude/settings.json`을 로드한 세션 경계 안에서 동작합니다. 다른 실행 환경에서 같은 강제를 자동으로 보장하지 않습니다. <!-- claim-id: C-LIMIT-HOOKS -->
|
||||
+- UI preview는 DOM mount, bundle, 대비, focus, 반응형 screenshot 같은 render health를 검사하지만 시각적 차별성·타이포그래피·비례·spacing의 미학 품질을 판정하지 않습니다. <!-- claim-id: C-LIMIT-UI -->
|
||||
+- Node 18 이상과 D2 0.6 이상은 관련 기능의 권장 도구이고, Marp 3 이상은 선택 사항입니다. 전체 UI render에는 Chrome 또는 Chromium 계열 실행 파일도 필요합니다. <!-- claim-id: C-LIMIT-TOOLS -->
|
||||
+- plain 대 harness의 현재 실행 표본은 저난도 bugfix 두 과제뿐이며 결과는 동률입니다. 설계·문서·의사결정 과제에 대한 품질 향상은 아직 실증되지 않았습니다. <!-- claim-id: C-LIMIT-EVIDENCE -->
|
||||
+
|
||||
+<!-- section-id: reference -->
|
||||
+## 정본 파일 지도
|
||||
+
|
||||
+- Workflow와 artifact: [workflow-contracts.yaml](org-os/06-agent-work/workflow-contracts.yaml) · [artifact vocabulary](org-os/06-agent-work/artifact-type-vocabulary.yaml)
|
||||
+- 역할과 라우팅: [roles.yaml](org-os/00-role-registry/roles.yaml) · [capability-families.yaml](org-os/00-role-registry/capability-families.yaml)
|
||||
+- 권한과 실행: [tool-permission-matrix.yaml](org-os/00-role-registry/tool-permission-matrix.yaml) · [execution-policy.yaml](org-os/06-agent-work/execution-policy.yaml)
|
||||
+- 런타임 요구사항: [tool-versions.yaml](.claude/tool-versions.yaml) · [requirements.txt](requirements.txt)
|
||||
+- Claude Code 어댑터: [commands](.claude/commands/) · [hooks](.claude/hooks/) · [schemas](.claude/schemas/) · [tests](.claude/tests/)
|
||||
+- 실증 자료: [golden tasks](benchmark/golden-tasks.yaml) · [benchmark report](benchmark/BENCHMARK.md)
|
||||
+- 설계와 변경 이력: [docs](docs/)
|
||||
+
|
||||
+README는 첫 판단과 운영 진입에 필요한 정보만 유지합니다. 세부 규칙을 바꿀 때는 위 정본을 수정하고 관련 생성·검증 경로를 함께 확인하십시오.
|
||||
@@ -0,0 +1,7 @@
|
||||
schema-version: 1
|
||||
mode: bootstrap
|
||||
target-rel: README.md
|
||||
generated-hash: sha256:2e57d3f0e5477bf5f091501e436554860125857e560c9119993d7d5eb262ad93
|
||||
target-before-hash: sha256:0686e6df63886ee361c919fc27c39ceb6925cd7b7994fce402b82e356cfca7c7
|
||||
repository-snapshot-hash: sha256:1eaa580e67e33d16a6115eb8f66fd034446436fb8f3bf70842ee9fd91b60ca64
|
||||
review-score: 93
|
||||
@@ -0,0 +1,230 @@
|
||||
schema-version: 1
|
||||
claims:
|
||||
- id: C-IDENTITY
|
||||
type: factual
|
||||
statement: Org OS 하네스는 제품·개발·운영·GTM 업무를 여러 AI 역할에 배분하고, 단계별 산출물과 사람 승인을 파일 계약으로 연결하는 Claude Code 프로젝트 하네스입니다.
|
||||
section: overview
|
||||
sources: [{fact-id: F-IDENTITY-CORE}, {fact-id: F-WORKFLOW-CASCADE}]
|
||||
status: supported
|
||||
- id: C-VALUE
|
||||
type: factual
|
||||
statement: 워크플로 그래프, 역할·권한, typed artifact, 실행 증거를 각각 정본 파일과 hook으로 연결합니다.
|
||||
section: overview
|
||||
sources: [{fact-id: F-ARCH-STATE-ARTIFACT}, {fact-id: F-ARCH-HOOKS}, {fact-id: F-ARTIFACT-PROVENANCE}]
|
||||
status: supported
|
||||
- id: C-ENTRY-MODEL
|
||||
type: factual
|
||||
statement: 일반적인 새 작업은 `/ceo-intake`에서 의도와 작업 규모를 구조화한 뒤, 선택된 plan에 따라 discovery·decision·design·build·verification·acceptance로 진행됩니다.
|
||||
section: overview
|
||||
sources: [{fact-id: F-WORKFLOW-ENTRY}, {fact-id: F-WORKFLOW-CASCADE}, {fact-id: F-WORKFLOW-WAVE-LIGHT}]
|
||||
status: supported
|
||||
- id: C-CONTRACT-MODEL
|
||||
type: factual
|
||||
statement: "`workflow-contracts.yaml`이 stage, command, artifact bundle, reviewer capability, exit gate를 정의하고 `state_engine.py`가 그 그래프를 읽습니다."
|
||||
section: operating-model
|
||||
sources: [{fact-id: F-ARCH-STATE-ARTIFACT}]
|
||||
status: supported
|
||||
- id: C-COLLAB-MODEL
|
||||
type: factual
|
||||
statement: 현재 family 정책은 판단·설계·분석을 멤버별로 격리하는 fan-out과 코드·실행을 한 concrete worker로 모으는 collapse를 구분합니다.
|
||||
section: operating-model
|
||||
sources: [{fact-id: F-ARCH-COLLABORATION}]
|
||||
status: supported
|
||||
- id: C-HUMAN-BOUNDARY
|
||||
type: factual
|
||||
statement: 전체 cascade는 방향 수용과 release 승인 같은 사람 결정 지점에서 멈추도록 정의되어 있습니다.
|
||||
section: operating-model
|
||||
sources: [{fact-id: F-WORKFLOW-CASCADE}, {fact-id: F-WORKFLOW-SPECIALIZED}]
|
||||
status: supported
|
||||
- id: C-PROVENANCE-MODEL
|
||||
type: factual
|
||||
statement: workflow와 artifact는 append-only event 및 id+SHA-256 snapshot으로 연결되고, report는 새 시도마다 새 파일로 발급됩니다.
|
||||
section: operating-model
|
||||
sources: [{fact-id: F-ARCH-STATE-ARTIFACT}, {fact-id: F-ARTIFACT-PROVENANCE}]
|
||||
status: supported
|
||||
- id: C-HOOK-MODEL
|
||||
type: factual
|
||||
statement: Claude Code가 이 프로젝트의 `.claude/settings.json`을 로드하면 PreToolUse, PostToolUse, SubagentStart, SubagentStop, Stop 이벤트가 각각 도구 경계·증거 원장·subagent 등록·종료 검증에 연결됩니다.
|
||||
section: operating-model
|
||||
sources: [{fact-id: F-ARCH-HOOKS}]
|
||||
status: supported
|
||||
- id: C-PREREQUISITES
|
||||
type: factual
|
||||
statement: 핵심 hook과 테스트에는 Python 3.10 이상과 PyYAML 6.0 이상이 필요합니다. `requirements.txt`는 PyYAML 6.0.1과 jsonschema 4.10.3을 고정합니다.
|
||||
section: quick-start
|
||||
sources: [{fact-id: F-PREREQ-TOOLS}]
|
||||
status: supported
|
||||
- id: C-INSTALL-COMMAND
|
||||
type: factual
|
||||
statement: pip install -r requirements.txt
|
||||
section: quick-start
|
||||
sources: [{fact-id: F-PREREQ-TOOLS}]
|
||||
status: supported
|
||||
- id: C-WORKSPACE-RESOLUTION
|
||||
type: factual
|
||||
statement: 산출물 경로는 `ORGOS_WORKSPACE` 환경변수를 먼저 사용하고, 없으면 `.orgos-workspace`의 첫 유효 줄을 사용합니다. 둘 다 없으면 strict 운영 hook은 exit 2로 중단합니다.
|
||||
section: quick-start
|
||||
sources: [{fact-id: F-ARTIFACT-LAYOUT}]
|
||||
status: supported
|
||||
- id: C-DOCTOR-COMMAND
|
||||
type: factual
|
||||
statement: python3 .claude/hooks/doctor.py
|
||||
section: quick-start
|
||||
sources: [{fact-id: F-CI-WORKFLOW}, {fact-id: F-ARTIFACT-LAYOUT}]
|
||||
status: supported
|
||||
- id: C-DOCTOR-SCOPE
|
||||
type: factual
|
||||
statement: "`doctor.py`는 hook 배선, 참조 스크립트, Python 의존성, workspace, 참조 무결성을 점검하고 hard failure가 있으면 비영점으로 종료합니다."
|
||||
section: quick-start
|
||||
sources: [{fact-id: F-VERIFY-SUITE}, {fact-id: F-CI-WORKFLOW}]
|
||||
status: supported
|
||||
- id: C-FIRST-COMMAND
|
||||
type: factual
|
||||
statement: Claude Code에서 일반적인 새 제품·개발·운영 요청은 `/ceo-intake`로 시작합니다.
|
||||
section: quick-start
|
||||
sources: [{fact-id: F-WORKFLOW-ENTRY}, {fact-id: F-WORKFLOW-SPECIALIZED}]
|
||||
status: supported
|
||||
- id: C-WORKFLOW-CASCADE
|
||||
type: factual
|
||||
statement: "`/ceo-intake` → `/ground` → `/decide` → `/design` → `/spec` → `/build` → `/review-output` → `/release-check` → `released`"
|
||||
section: workflows
|
||||
sources: [{fact-id: F-WORKFLOW-CASCADE}]
|
||||
status: supported
|
||||
- id: C-WORKFLOW-WAVE
|
||||
type: factual
|
||||
statement: "`/ceo-intake` → `/plan-wave` → `/run-wave` → `/review-output` → `/release-check` → `released`"
|
||||
section: workflows
|
||||
sources: [{fact-id: F-WORKFLOW-WAVE-LIGHT}]
|
||||
status: supported
|
||||
- id: C-WORKFLOW-LIGHT
|
||||
type: factual
|
||||
statement: "`/ceo-intake` → `/run-wave` → `/review-output` → `acceptance`"
|
||||
section: workflows
|
||||
sources: [{fact-id: F-WORKFLOW-WAVE-LIGHT}]
|
||||
status: supported
|
||||
- id: C-WORKFLOW-VENTURE
|
||||
type: factual
|
||||
statement: founder context를 채운 뒤 `/ceo-intake --plan venture-bootstrap` → `/venture-validate` → `/company-bootstrap` → `bootstrap-complete`
|
||||
section: workflows
|
||||
sources: [{fact-id: F-WORKFLOW-VENTURE}]
|
||||
status: supported
|
||||
- id: C-SPECIALIZED-WORKFLOWS
|
||||
type: factual
|
||||
statement: "`/run-cascade`는 cascade의 현재 stage와 다음 command를 계산하는 상위 드라이버입니다. `/design-direction`은 제품 cascade에 종속된 방향 탐색 child workflow이고, `/design-system`과 `/consult`는 각각 코드 UI 검증과 독립 자문 산출물에 초점을 둡니다."
|
||||
section: workflows
|
||||
sources: [{fact-id: F-WORKFLOW-SPECIALIZED}]
|
||||
status: supported
|
||||
- id: C-CASCADE-VISUAL
|
||||
type: factual
|
||||
statement: 다음 흐름은 `workflow-contracts.yaml`에 정의된 cascade stage와 사람 결정 경계를 요약합니다.
|
||||
section: workflows
|
||||
sources: [{fact-id: F-WORKFLOW-CASCADE}, {fact-id: F-WORKFLOW-SPECIALIZED}]
|
||||
status: supported
|
||||
- id: C-ARCH-SOURCE
|
||||
type: factual
|
||||
statement: 실행 그래프의 정본은 `org-os/06-agent-work/workflow-contracts.yaml`입니다. 역할·권한 정책은 `org-os/00-role-registry/`에 있고, Claude Code용 command·agent·skill·hook은 `.claude/` 아래에서 이 계약을 소비하거나 검증합니다.
|
||||
section: architecture
|
||||
sources: [{fact-id: F-ARCH-STATE-ARTIFACT}, {fact-id: F-ARCH-DIRECTORIES}]
|
||||
status: supported
|
||||
- id: C-DIRECTORY-MAP
|
||||
type: factual
|
||||
statement: 저장소 구조와 책임
|
||||
section: architecture
|
||||
sources: [{fact-id: F-ARCH-DIRECTORIES}]
|
||||
status: supported
|
||||
- id: C-ROLE-MODEL
|
||||
type: factual
|
||||
statement: 현재 registry는 75개 AI 역할과 최종 사람 소유자 `HUMAN-001`, 28개 routing family, 12개 평가 lens를 정의합니다. agent generator의 현재 정합 계약은 101개 agent card입니다.
|
||||
section: architecture
|
||||
sources: [{fact-id: F-ARCH-ROLE-MODEL}]
|
||||
status: supported
|
||||
- id: C-GENERATED-AGENTS
|
||||
type: factual
|
||||
statement: 기여할 때는 산출된 `.claude/agents/*.md`만 직접 고치기보다 역할·family·method·tool 정본을 먼저 수정하고 생성기 정합 검사를 통과시키는 구조를 따르십시오.
|
||||
section: architecture
|
||||
sources: [{fact-id: F-ARCH-DIRECTORIES}, {fact-id: F-ARCH-ROLE-MODEL}]
|
||||
status: supported
|
||||
- id: C-WORKSPACE-LAYOUT
|
||||
type: factual
|
||||
statement: "`ORGOS_WORKSPACE`가 상대 경로이면 저장소 루트 아래 프로젝트 디렉터리로 해석되고, 절대 경로이면 그대로 사용됩니다."
|
||||
section: artifacts
|
||||
sources: [{fact-id: F-ARTIFACT-LAYOUT}]
|
||||
status: supported
|
||||
- id: C-REPORT-RECEIPTS
|
||||
type: factual
|
||||
statement: report는 `<workspace>/completion-records/<workflow>/<role>-<UTC timestamp>.report.yaml` 형식으로 새로 발급됩니다. 실행 command와 exit code, 작성 파일 경로와 SHA-256은 evidence ledger의 receipt로 남길 수 있지만, workspace를 해석하지 못한 계측 hook은 기록을 생략할 수 있습니다.
|
||||
section: artifacts
|
||||
sources: [{fact-id: F-ARTIFACT-PROVENANCE}]
|
||||
status: supported
|
||||
- id: C-CMD-DOCTOR
|
||||
type: factual
|
||||
statement: python3 .claude/hooks/doctor.py
|
||||
section: verification
|
||||
sources: [{fact-id: F-CI-WORKFLOW}]
|
||||
status: supported
|
||||
- id: C-CMD-AGENTS
|
||||
type: factual
|
||||
statement: python3 .claude/hooks/gen_agents.py --check
|
||||
section: verification
|
||||
sources: [{fact-id: F-ARCH-ROLE-MODEL}, {fact-id: F-CI-WORKFLOW}]
|
||||
status: supported
|
||||
- id: C-CMD-TESTS
|
||||
type: factual
|
||||
statement: python3 .claude/tests/run_all.py
|
||||
section: verification
|
||||
sources: [{fact-id: F-VERIFY-SUITE}]
|
||||
status: supported
|
||||
- id: C-CMD-BENCHMARK
|
||||
type: factual
|
||||
statement: python3 .claude/hooks/benchmark.py list
|
||||
section: verification
|
||||
sources: [{fact-id: F-MATURITY-BENCHMARK}]
|
||||
status: supported
|
||||
- id: C-TEST-RUNNER
|
||||
type: factual
|
||||
statement: "`run_all.py`는 artifact registry check, doctor, reference lint를 거친 뒤 `.claude/tests/test_*.py`를 suite별 제한시간과 함께 순차 실행합니다. 하나라도 실패하거나 timeout이면 exit 1입니다."
|
||||
section: verification
|
||||
sources: [{fact-id: F-VERIFY-SUITE}]
|
||||
status: supported
|
||||
- id: C-CI
|
||||
type: factual
|
||||
statement: GitHub Actions는 Python 3.12와 Node 20, `_sandbox` workspace에서 의존성을 설치하고 doctor, reference lint, agent generation check, 전체 test suite를 분리해 실행하도록 정의돼 있습니다.
|
||||
section: verification
|
||||
sources: [{fact-id: F-CI-WORKFLOW}]
|
||||
status: supported
|
||||
- id: C-BENCHMARK-STATUS
|
||||
type: factual
|
||||
statement: 벤치마크에는 13개 golden task가 정의돼 있지만 현재 실행 ledger에는 GT-01과 GT-R2의 plain·harness 표본만 있습니다. 두 과제는 first-pass acceptance, test pass rate, unnecessary change lines에서 모두 동률이므로 현재 데이터는 하네스의 품질 우위를 입증하지 않습니다.
|
||||
section: verification
|
||||
sources: [{fact-id: F-MATURITY-BENCHMARK}]
|
||||
status: supported
|
||||
- id: C-LIMIT-CONTEXT
|
||||
type: factual
|
||||
statement: "`company-context.yaml`과 `founder-context.yaml`은 현재 `template` 상태입니다. 회사 수립 경로를 사용하려면 사람이 founder context를 채우고 venture-bootstrap을 거쳐야 합니다."
|
||||
section: limitations
|
||||
sources: [{fact-id: F-MATURITY-CONTEXT}, {fact-id: F-WORKFLOW-VENTURE}]
|
||||
status: supported
|
||||
- id: C-LIMIT-HOOKS
|
||||
type: factual
|
||||
statement: 강제 hook은 Claude Code가 이 저장소의 `.claude/settings.json`을 로드한 세션 경계 안에서 동작합니다. 다른 실행 환경에서 같은 강제를 자동으로 보장하지 않습니다.
|
||||
section: limitations
|
||||
sources: [{fact-id: F-ARCH-HOOKS}]
|
||||
status: supported
|
||||
- id: C-LIMIT-UI
|
||||
type: factual
|
||||
statement: UI preview는 DOM mount, bundle, 대비, focus, 반응형 screenshot 같은 render health를 검사하지만 시각적 차별성·타이포그래피·비례·spacing의 미학 품질을 판정하지 않습니다.
|
||||
section: limitations
|
||||
sources: [{fact-id: F-PREREQ-UI}]
|
||||
status: supported
|
||||
- id: C-LIMIT-TOOLS
|
||||
type: factual
|
||||
statement: Node 18 이상과 D2 0.6 이상은 관련 기능의 권장 도구이고, Marp 3 이상은 선택 사항입니다. 전체 UI render에는 Chrome 또는 Chromium 계열 실행 파일도 필요합니다.
|
||||
section: limitations
|
||||
sources: [{fact-id: F-PREREQ-TOOLS}, {fact-id: F-PREREQ-UI}]
|
||||
status: supported
|
||||
- id: C-LIMIT-EVIDENCE
|
||||
type: factual
|
||||
statement: plain 대 harness의 현재 실행 표본은 저난도 bugfix 두 과제뿐이며 결과는 동률입니다. 설계·문서·의사결정 과제에 대한 품질 향상은 아직 실증되지 않았습니다.
|
||||
section: limitations
|
||||
sources: [{fact-id: F-MATURITY-BENCHMARK}]
|
||||
status: supported
|
||||
@@ -0,0 +1,13 @@
|
||||
schema-version: 1
|
||||
mode: bootstrap
|
||||
profile: generic
|
||||
repository-snapshot-hash: sha256:1eaa580e67e33d16a6115eb8f66fd034446436fb8f3bf70842ee9fd91b60ca64
|
||||
artifacts:
|
||||
readme-request.yaml: sha256:1b836226cd3aff5eb108ebafe053d5f4ca7b1376a93d19a9bd47d3aaa6b9dcac
|
||||
repository-facts.yaml: sha256:93020532ad2cd0fc40b55d299acfeebf33ba3ac76bcceb1133ec7696d9ba5a3f
|
||||
readme-brief.yaml: sha256:d1d9c930dc36800f4d8bf00c8b5bc51f57e107a19c735d2b4b006cbfed87f663
|
||||
readme-outline.yaml: sha256:a2f39fcc3988f1c2b04e47ca07ec68ca547aecbf698ca63341f9337a994cfe06
|
||||
README.candidate.md: sha256:2e57d3f0e5477bf5f091501e436554860125857e560c9119993d7d5eb262ad93
|
||||
claim-map.yaml: sha256:5404d520fdf3dd92d2787310f1f31b6710620a0d00412319da7fa0a622eaf67c
|
||||
visual-plan.yaml: sha256:870e85cb973b0ee2b3ecf139e0ad6d06f203ed3340cf26d2e3c649f41ff1e5ad
|
||||
review-findings.yaml: sha256:1ef3f845fa9a6457188aba426ea6723a9d645ccc64a6803d304a76bfde750995
|
||||
@@ -0,0 +1,59 @@
|
||||
schema-version: 1
|
||||
project-profile:
|
||||
primary: generic
|
||||
secondary:
|
||||
- workflow-harness
|
||||
- configuration-repository
|
||||
audiences:
|
||||
primary:
|
||||
- 저장소를 처음 사용하는 운영자와 개발자
|
||||
- 하네스의 역할·워크플로·검증 계약을 변경하는 기여자
|
||||
secondary:
|
||||
- 에이전트 운영 모델과 증거 체계를 평가하는 기술 리더
|
||||
reader-outcomes:
|
||||
- 이 저장소가 해결하는 운영 문제와 적용 범위를 30초 안에 설명한다.
|
||||
- 필수 도구와 워크스페이스를 설정하고 preflight 진입점을 찾는다.
|
||||
- cascade·wave·light·venture 경로 가운데 작업에 맞는 흐름을 고른다.
|
||||
- 역할·워크플로·훅·산출물의 정본과 변경 위치를 구분한다.
|
||||
- 정적 검증과 실제 실행 증거의 차이 및 현재 실증 한계를 확인한다.
|
||||
project-story:
|
||||
value-proposition: 역할 선택부터 사람 승인, 산출물 검증, 증거 기록까지를 Claude Code 명령·계약·훅으로 연결하는 파일 기반 에이전트 운영 하네스다.
|
||||
problem: 여러 에이전트가 긴 작업을 수행하면 역할 경계, 선행 산출물, 승인 주체, 실행 증거가 산문과 대화 안에서 쉽게 분리된다.
|
||||
target-reader: Claude Code에서 복수 역할의 제품·개발·운영 워크플로를 일관된 계약으로 운용하려는 사용자와 기여자
|
||||
notable-traits:
|
||||
- text: workflow-contracts가 단계, 산출물 bundle, 검토 권한, exit gate를 한 그래프로 정의한다.
|
||||
fact-ids: [F-WORKFLOW-CASCADE, F-ARCH-STATE-ARTIFACT]
|
||||
- text: 역할 75개를 28개 family로 라우팅하고 현재 생성기 계약은 101개 agent card의 정합을 검사한다.
|
||||
fact-ids: [F-ARCH-ROLE-MODEL, F-ARCH-COLLABORATION]
|
||||
- text: Claude Code hook이 도구 사용, 증거 기록, subagent 수명주기, 종료 검증을 연결한다.
|
||||
fact-ids: [F-ARCH-HOOKS, F-ARTIFACT-PROVENANCE]
|
||||
- text: 프로젝트별 workspace에 불변 report와 append-only 상태·증거 기록을 분리한다.
|
||||
fact-ids: [F-ARTIFACT-LAYOUT, F-ARTIFACT-PROVENANCE]
|
||||
- text: 전체 테스트 진입점과 plain 대 harness 벤치마크는 존재하지만 현재 품질 우위 표본은 제한적이다.
|
||||
fact-ids: [F-VERIFY-SUITE, F-MATURITY-BENCHMARK]
|
||||
maturity: 실행 계약과 검증 코드는 구현되어 있으나 회사 컨텍스트는 template이고 품질 우위 실증은 초기 표본에 머문 상태
|
||||
limitations:
|
||||
- 강제 hook은 Claude Code가 이 프로젝트의 .claude/settings.json을 로드한 세션에서 적용된다.
|
||||
- 현재 company-context와 founder-context는 template 상태라 회사 수립 경로에 사람 입력이 필요하다.
|
||||
- 기록된 plain 대 harness 실행 표본은 두 저난도 과제뿐이며 모두 동률이다.
|
||||
- UI 렌더와 덱 출력 같은 일부 경로는 Node, 브라우저, D2 또는 Marp 같은 추가 도구에 의존한다.
|
||||
narrative-variant: custom
|
||||
reader-journey:
|
||||
- reader-question: 이 저장소는 무엇을 어떤 방식으로 운영하는가?
|
||||
section-id: overview
|
||||
- reader-question: 대화형 프롬프트와 다른 핵심 운영 원칙은 무엇인가?
|
||||
section-id: operating-model
|
||||
- reader-question: 사용 전에 무엇을 설치하고 어떤 workspace를 지정해야 하는가?
|
||||
section-id: quick-start
|
||||
- reader-question: 작업 크기와 목적에 맞는 workflow는 무엇인가?
|
||||
section-id: workflows
|
||||
- reader-question: 규칙과 실행 코드는 어디에 있고 서로 어떻게 연결되는가?
|
||||
section-id: architecture
|
||||
- reader-question: 실행 결과와 증거는 어디에 어떤 형태로 남는가?
|
||||
section-id: artifacts
|
||||
- reader-question: 저장소 정합과 품질 주장을 어떻게 검증하는가?
|
||||
section-id: verification
|
||||
- reader-question: 도입 전에 받아들여야 할 현재 한계는 무엇인가?
|
||||
section-id: limitations
|
||||
- reader-question: 세부 계약을 직접 확인하거나 변경하려면 어디를 읽는가?
|
||||
section-id: reference
|
||||
@@ -0,0 +1,142 @@
|
||||
schema-version: 1
|
||||
sections:
|
||||
- id: overview
|
||||
title-guidance: Org OS 하네스 개요
|
||||
level: 2
|
||||
purpose: 프로젝트의 정체성, 대상 독자, 해결하려는 운영 문제를 빠르게 판단시킨다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- Claude Code 기반 파일형 운영 하네스라는 구체적 정의
|
||||
- 개발과 비즈니스 workflow를 함께 다루는 범위
|
||||
- 대화 프롬프트 모음이 아니라 계약과 검증을 연결한다는 가치
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 프로젝트 정체성을 이해하는 데 별도 그림이 필요한가?
|
||||
rationale: 제목과 두 문단의 구체적인 정의가 그림보다 빠르게 전달된다.
|
||||
|
||||
- id: operating-model
|
||||
title-guidance: 핵심 운영 모델
|
||||
level: 2
|
||||
purpose: 역할 라우팅, 상태 전이, 사람 게이트, 증거 기록이 어떤 원칙으로 결합되는지 설명한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- workflow-contracts 중심의 상태·산출물 계약
|
||||
- fan-out과 collapse의 구분
|
||||
- immutable artifact와 사람 승인 경계
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 핵심 원칙을 이해하는 데 관계도가 필요한가?
|
||||
rationale: 세 가지 원칙을 짧은 목록으로 분리하는 편이 더 명확하다.
|
||||
|
||||
- id: quick-start
|
||||
title-guidance: 시작하기
|
||||
level: 2
|
||||
purpose: 필수 도구, 의존성, workspace, preflight, 첫 slash command까지의 최소 경로를 제공한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- Python과 PyYAML 최소 버전
|
||||
- requirements 설치 명령과 수동 검증 한계
|
||||
- ORGOS_WORKSPACE 우선순위와 유효한 디렉터리 조건
|
||||
- doctor 성공 신호
|
||||
- 일반 workflow의 첫 명령 /ceo-intake
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 설치와 첫 실행 순서를 이해하는 데 그림이 필요한가?
|
||||
rationale: 복사 가능한 명령 블록과 예상 결과가 가장 직접적이다.
|
||||
|
||||
- id: workflows
|
||||
title-guidance: 작업에 맞는 워크플로 선택
|
||||
level: 2
|
||||
purpose: cascade, wave, light, venture-bootstrap, 전문 진입점을 입력·단계·종단 기준으로 구분한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- cascade 전체 흐름과 사람 결정 지점
|
||||
- wave와 light의 차이
|
||||
- venture-bootstrap의 사람 입력과 결과
|
||||
- run-cascade, design-direction, design-system, consult의 범위
|
||||
visual-slot:
|
||||
decision: include
|
||||
reader-question: cascade의 여덟 단계와 사람 승인 지점은 어떤 순서인가?
|
||||
rationale: 단계와 gate가 연속되는 관계는 표보다 흐름도가 더 빠르게 전달한다.
|
||||
purpose: intake부터 release까지의 공식 cascade와 사람 승인 경계를 한 화면에 보여준다.
|
||||
|
||||
- id: architecture
|
||||
title-guidance: 저장소 구조와 책임
|
||||
level: 2
|
||||
purpose: 정본 계약, Claude Code 어댑터, 생성 카드, 테스트와 벤치마크의 책임을 구분한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- org-os와 .claude 하위 디렉터리의 책임 표
|
||||
- workflow-contracts에서 state_engine과 agent generator로 이어지는 관계
|
||||
- 기여자가 규칙별로 수정할 위치
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 디렉터리별 변경 위치를 찾는 데 두 번째 그림이 필요한가?
|
||||
rationale: 경로와 책임을 직접 짝지은 표가 탐색에 더 적합하고 시각물 한도도 지킨다.
|
||||
|
||||
- id: artifacts
|
||||
title-guidance: 워크스페이스와 산출물
|
||||
level: 2
|
||||
purpose: workspace 선택 규칙과 report, evidence, state, human view의 저장 위치·불변성을 설명한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- ORGOS_WORKSPACE와 pointer의 우선순위
|
||||
- completion-records, evidence, reports, state 경로
|
||||
- report 새 파일 발급과 receipt의 실행 증거
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 산출물 경로를 찾는 데 그림이 필요한가?
|
||||
rationale: 작은 디렉터리 tree와 책임 설명이면 충분하다.
|
||||
|
||||
- id: verification
|
||||
title-guidance: 검증 방법과 증거 수준
|
||||
level: 2
|
||||
purpose: preflight, agent generation, 전체 suite, CI, benchmark를 목적과 검증 수준별로 제공한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- doctor, gen_agents --check, run_all 명령
|
||||
- 정적 확인과 실제 실행의 차이
|
||||
- CI의 분리 실행 경로
|
||||
- benchmark list와 현재 표본의 해석
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 검증 명령 선택에 그림이 필요한가?
|
||||
rationale: 목적·명령·성공 신호·수준을 짝지은 표가 더 정확하다.
|
||||
|
||||
- id: limitations
|
||||
title-guidance: 현재 상태와 한계
|
||||
level: 2
|
||||
purpose: template context, 제한된 benchmark, 선택 도구와 hook 경계를 과장 없이 밝힌다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- company와 founder context의 template 상태
|
||||
- 두 저난도 benchmark만 실행됐고 동률이라는 결과
|
||||
- UI 미학은 자동 판정하지 않는다는 한계
|
||||
- 일부 기능의 추가 도구 의존성과 Claude Code session 경계
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 현재 한계를 이해하는 데 시각화가 필요한가?
|
||||
rationale: 근거와 영향을 한 줄씩 연결한 목록이 더 정직하고 명료하다.
|
||||
|
||||
- id: reference
|
||||
title-guidance: 정본 파일 지도
|
||||
level: 2
|
||||
purpose: 세부 workflow, 역할, 권한, 실행 정책, 도구 버전, command 정의로 직접 이동시킨다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- workflow-contracts, roles, families, permissions, execution policy 링크
|
||||
- command, hook, schema, test 디렉터리 링크
|
||||
- 상세 설계 이력은 docs로 분리
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 세부 정본을 찾는 데 그림이 필요한가?
|
||||
rationale: 목적별 상대 링크 목록이 탐색과 유지보수에 가장 적합하다.
|
||||
@@ -0,0 +1,46 @@
|
||||
schema-version: 1
|
||||
target:
|
||||
repository: /home/donghyeon/workspace/ai-tool/company-haness
|
||||
readme-path: README.md
|
||||
mode: bootstrap
|
||||
profile-override: generic
|
||||
project-intent:
|
||||
purpose: 대상 저장소의 핵심 운영 흐름, 구조, 검증 방법을 실제 파일 근거에 맞춰 설명한다.
|
||||
positioning: AI 에이전트 기반 회사 운영 하네스를 처음 접하는 사용자와 기여자를 위한 저장소 진입 문서다.
|
||||
maturity: 현재 저장소에서 확인되는 구현과 한계를 과장 없이 문서화한다.
|
||||
audience:
|
||||
primary:
|
||||
- 저장소를 처음 사용하는 운영자와 개발자
|
||||
- 하네스에 기여하려는 개발자
|
||||
secondary:
|
||||
- 에이전트 워크플로와 산출물 계약을 검토하는 기술 리더
|
||||
reader-actions:
|
||||
- 프로젝트의 목적과 적용 범위를 빠르게 파악한다.
|
||||
- 대표 진입점과 최소 사용 흐름을 선택한다.
|
||||
- 주요 디렉터리와 산출물 위치를 찾는다.
|
||||
- 저장소가 정의한 검증 명령과 현재 한계를 확인한다.
|
||||
content-policy:
|
||||
language: ko-KR
|
||||
tone: 간결하고 기술적이며 검증 수준을 명시하는 설명체
|
||||
target-length: long
|
||||
preserve-existing-copy: false
|
||||
detail-docs-policy: summary-and-link
|
||||
visual-policy:
|
||||
mode: when-useful
|
||||
max-visuals: 1
|
||||
preferred-formats:
|
||||
- mermaid
|
||||
placeholder-format: HTML 주석 기반 제작 사양
|
||||
must-include:
|
||||
- 프로젝트 개요와 대상 독자
|
||||
- 대표 워크플로 진입점과 선택 기준
|
||||
- 저장소 구조와 주요 책임
|
||||
- 최소 사용 절차
|
||||
- 검증 명령과 검증 수준
|
||||
- 산출물 위치
|
||||
- 현재 한계
|
||||
must-exclude:
|
||||
- 저장소 근거가 없는 기능·버전·성능 우위 주장
|
||||
- 비밀 값 또는 개인 환경의 절대 경로
|
||||
- 상세 설계 이력의 장문 복제
|
||||
protected-sections: []
|
||||
@@ -0,0 +1,547 @@
|
||||
schema-version: 1
|
||||
repository-snapshot-hash: sha256:1eaa580e67e33d16a6115eb8f66fd034446436fb8f3bf70842ee9fd91b60ca64
|
||||
project-name: Org OS 하네스
|
||||
languages: [Python, YAML, Markdown]
|
||||
frameworks: [Claude Code]
|
||||
facts:
|
||||
- id: F-IDENTITY-CORE
|
||||
category: identity
|
||||
key: project-identity-and-purpose
|
||||
value:
|
||||
name: Org OS 하네스
|
||||
purpose: 회사 전체를 AI 에이전트로 운영하는 파일 기반 운영체계로, 개발과 비즈니스 업무를 함께 다룬다.
|
||||
runtime: Claude Code의 subagent, project command, hook
|
||||
assertion-type: declared
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: CLAUDE.md
|
||||
line-start: 1
|
||||
line-end: 3
|
||||
source-kind: project-documentation
|
||||
|
||||
- id: F-WORKFLOW-ENTRY
|
||||
category: workflow
|
||||
key: new-workflow-entrypoint
|
||||
value:
|
||||
command: /ceo-intake
|
||||
applies-to: [cascade, wave, light, venture-bootstrap]
|
||||
normal-outputs: [decision-brief, workload-profile]
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: org-os/06-agent-work/workflow-contracts.yaml
|
||||
line-start: 46
|
||||
line-end: 54
|
||||
source-kind: workflow-contract
|
||||
- path: org-os/06-agent-work/workflow-contracts.yaml
|
||||
line-start: 103
|
||||
line-end: 124
|
||||
source-kind: workflow-contract
|
||||
|
||||
- id: F-WORKFLOW-CASCADE
|
||||
category: workflow
|
||||
key: cascade-stage-map
|
||||
value:
|
||||
terminal-stage: released
|
||||
stages:
|
||||
- {stage: intake, command: /ceo-intake, output: [decision-brief, workload-profile]}
|
||||
- {stage: discovery, command: /ground, output: [grounding-package]}
|
||||
- {stage: decide, command: /decide, output: [executive-decision-packet]}
|
||||
- {stage: design, command: /design, output: conditional-design-bundle}
|
||||
- {stage: spec, command: /spec, output: conditional-spec-bundle}
|
||||
- {stage: build, command: /build, output: [completion-record]}
|
||||
- {stage: verification, command: /review-output, output: [quality-gate-review]}
|
||||
- {stage: acceptance, command: /release-check, output: [release-decision]}
|
||||
release-exit-gates: [release-approved, no-unresolved-critical-risks, human-gate]
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: org-os/06-agent-work/workflow-contracts.yaml
|
||||
line-start: 46
|
||||
line-end: 101
|
||||
source-kind: workflow-contract
|
||||
|
||||
- id: F-WORKFLOW-WAVE-LIGHT
|
||||
category: workflow
|
||||
key: wave-and-light-selection
|
||||
value:
|
||||
wave:
|
||||
commands: [/ceo-intake, /plan-wave, /run-wave, /review-output, /release-check]
|
||||
terminal-stage: released
|
||||
light:
|
||||
commands: [/ceo-intake, /run-wave, /review-output]
|
||||
terminal-stage: acceptance
|
||||
omitted-stage: plan
|
||||
intended-for: 저위험·two-way-door·single-role이며 고객·매출·보안 영향이 없는 작업
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: org-os/06-agent-work/workflow-contracts.yaml
|
||||
line-start: 103
|
||||
line-end: 119
|
||||
source-kind: workflow-contract
|
||||
- path: org-os/06-agent-work/execution-plans.yaml
|
||||
line-start: 23
|
||||
line-end: 37
|
||||
source-kind: execution-plan
|
||||
|
||||
- id: F-WORKFLOW-VENTURE
|
||||
category: workflow
|
||||
key: venture-bootstrap
|
||||
value:
|
||||
entry: /ceo-intake --plan venture-bootstrap
|
||||
subsequent-commands: [/venture-validate, /company-bootstrap]
|
||||
founder-input: org-os/01-company/founder-context.yaml
|
||||
required-founder-status: filled
|
||||
output: org-os/01-company/company-context.yaml
|
||||
output-status: provisional
|
||||
terminal-stage: bootstrap-complete
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: org-os/06-agent-work/workflow-contracts.yaml
|
||||
line-start: 121
|
||||
line-end: 130
|
||||
source-kind: workflow-contract
|
||||
- path: org-os/06-agent-work/execution-plans.yaml
|
||||
line-start: 38
|
||||
line-end: 47
|
||||
source-kind: execution-plan
|
||||
- path: org-os/01-company/founder-context.yaml
|
||||
line-start: 1
|
||||
line-end: 5
|
||||
source-kind: company-context-input
|
||||
|
||||
- id: F-WORKFLOW-SPECIALIZED
|
||||
category: workflow
|
||||
key: specialized-entrypoints
|
||||
value:
|
||||
/run-cascade: 전체 cascade를 state_engine으로 순회하고 사람 결정 게이트에서 중단·재개하는 상위 드라이버
|
||||
/design-direction: 제품 cascade의 child workflow로 발산·선택·prototype·비평을 거쳐 approved-direction을 산출
|
||||
/design-system: 기존 스택을 조사해 reuse/adapt/create를 선택하고 코드 UI와 렌더 미리보기를 검증
|
||||
/consult: 비즈니스 자문 또는 문서 자문 family를 선택해 문서와 덱을 산출
|
||||
assertion-type: declared
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: .claude/commands/run-cascade.md
|
||||
line-start: 1
|
||||
line-end: 24
|
||||
source-kind: command-definition
|
||||
- path: .claude/commands/design-direction.md
|
||||
line-start: 1
|
||||
line-end: 25
|
||||
source-kind: command-definition
|
||||
- path: .claude/commands/design-system.md
|
||||
line-start: 1
|
||||
line-end: 10
|
||||
source-kind: command-definition
|
||||
- path: .claude/commands/consult.md
|
||||
line-start: 1
|
||||
line-end: 12
|
||||
source-kind: command-definition
|
||||
|
||||
- id: F-ARCH-DIRECTORIES
|
||||
category: architecture
|
||||
key: repository-directory-responsibilities
|
||||
value:
|
||||
org-os/00-role-registry: 역할·family·lens·상태 전이·권한 정책의 원천
|
||||
org-os/06-agent-work: workflow·artifact·협업·실행 계약
|
||||
.claude/commands: 사용자 workflow 진입점
|
||||
.claude/agents: registry에서 생성되는 실행 역할·resolver·router 카드
|
||||
.claude/skills: 역할별 작업 방법
|
||||
.claude/hooks: 상태 엔진·검증·증거 원장·렌더러·생성기
|
||||
.claude/schemas: report와 typed artifact 스키마
|
||||
.claude/tests: 하네스 강제기와 workflow 계약 테스트
|
||||
benchmark: golden task와 plain-vs-harness 비교 자료
|
||||
project-workspace: completion record·evidence·report·state·UI 산출물
|
||||
assertion-type: derived
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: CLAUDE.md
|
||||
line-start: 5
|
||||
line-end: 43
|
||||
source-kind: architecture-documentation
|
||||
- path: .claude/hooks/_workspace.py
|
||||
line-start: 1
|
||||
line-end: 15
|
||||
source-kind: runtime-path-implementation
|
||||
|
||||
- id: F-ARCH-ROLE-MODEL
|
||||
category: architecture
|
||||
key: role-family-lens-model
|
||||
value:
|
||||
reference-ai-roles: 75
|
||||
final-human-owner: HUMAN-001
|
||||
routing-families: 28
|
||||
evaluation-lenses: 12
|
||||
generated-agent-cards-contract: 101
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: org-os/00-role-registry/roles.yaml
|
||||
line-start: 1
|
||||
line-end: 20
|
||||
source-kind: role-registry
|
||||
- path: org-os/00-role-registry/capability-families.yaml
|
||||
line-start: 1
|
||||
line-end: 13
|
||||
source-kind: family-registry
|
||||
- path: org-os/00-role-registry/lens-registry.yaml
|
||||
line-start: 1
|
||||
line-end: 25
|
||||
source-kind: lens-registry
|
||||
- path: .claude/hooks/gen_agents.py
|
||||
line-start: 814
|
||||
line-end: 836
|
||||
source-kind: generator-contract
|
||||
|
||||
- id: F-ARCH-COLLABORATION
|
||||
category: architecture
|
||||
key: fan-out-collapse-policy
|
||||
value:
|
||||
family-defaults: {fan-out: 21, collapse: 6, coordination-only: 1}
|
||||
fan-out: 판단·설계·분석 family의 멤버를 격리 실행하고 상위가 원본 보고서를 읽어 종합
|
||||
collapse: 코드·실행 family를 하나의 concrete worker 실행으로 축소
|
||||
wave-max-concurrency: 5
|
||||
heavy-tier-min-independent-verifiers: 3
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: org-os/00-role-registry/capability-families.yaml
|
||||
line-start: 14
|
||||
line-end: 34
|
||||
source-kind: family-registry
|
||||
- path: org-os/06-agent-work/execution-policy.yaml
|
||||
line-start: 10
|
||||
line-end: 57
|
||||
source-kind: execution-policy
|
||||
|
||||
- id: F-ARCH-STATE-ARTIFACT
|
||||
category: architecture
|
||||
key: trusted-state-and-artifact-runtime
|
||||
value:
|
||||
workflow-contract-source: org-os/06-agent-work/workflow-contracts.yaml
|
||||
workflow-contract-responsibility: stage graph·role capability·artifact kind·bundle·exit gate
|
||||
canonical-runtime-events: [workflow-events.jsonl, artifact-events.jsonl, acceptance-events.jsonl, human-signoff.jsonl]
|
||||
materialized-view: workflow.yaml
|
||||
artifact-identity: immutable artifact id plus SHA-256 snapshot
|
||||
generated-registry: org-os/06-agent-work/generated/artifact-registry.yaml
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: .claude/hooks/state_engine.py
|
||||
line-start: 2
|
||||
line-end: 11
|
||||
source-kind: runtime-implementation
|
||||
- path: .claude/hooks/state_engine.py
|
||||
line-start: 32
|
||||
line-end: 38
|
||||
source-kind: runtime-implementation
|
||||
- path: .claude/hooks/artifact_contract.py
|
||||
line-start: 2
|
||||
line-end: 39
|
||||
source-kind: artifact-validation-implementation
|
||||
- path: .claude/hooks/compile_artifact_registry.py
|
||||
line-start: 2
|
||||
line-end: 7
|
||||
source-kind: artifact-registry-compiler
|
||||
|
||||
- id: F-ARCH-HOOKS
|
||||
category: architecture
|
||||
key: claude-code-hook-wiring
|
||||
value:
|
||||
PreToolUse: guard_tools.py
|
||||
PostToolUse: evidence_ledger.py
|
||||
SubagentStart: subagent_register.py
|
||||
SubagentStop: stop_validate.py
|
||||
Stop: stop_validate.py --main
|
||||
limitation: 강제 동작은 Claude Code가 프로젝트의 .claude/settings.json을 로드할 때 적용된다.
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: .claude/settings.json
|
||||
line-start: 3
|
||||
line-end: 66
|
||||
source-kind: claude-code-configuration
|
||||
- path: CLAUDE.md
|
||||
line-start: 58
|
||||
line-end: 68
|
||||
source-kind: runtime-limit-documentation
|
||||
|
||||
- id: F-ARTIFACT-LAYOUT
|
||||
category: artifacts
|
||||
key: workspace-resolution-and-layout
|
||||
value:
|
||||
resolution-order: [ORGOS_WORKSPACE environment variable, .orgos-workspace pointer]
|
||||
unresolved-behavior: strict operational hooks fail closed with exit 2
|
||||
directories:
|
||||
completion-records: <workspace>/completion-records/<workflow>/
|
||||
evidence: <workspace>/evidence/
|
||||
reports: <workspace>/reports/
|
||||
state: <workspace>/state/
|
||||
slack-inbox: <workspace>/slack-inbox/
|
||||
slack-outbox: <workspace>/slack-outbox/
|
||||
design-system: <workspace>/design-system/
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: .claude/hooks/_workspace.py
|
||||
line-start: 1
|
||||
line-end: 15
|
||||
source-kind: runtime-path-implementation
|
||||
- path: .claude/hooks/_workspace.py
|
||||
line-start: 44
|
||||
line-end: 94
|
||||
source-kind: runtime-path-implementation
|
||||
- path: .claude/hooks/_workspace.py
|
||||
line-start: 97
|
||||
line-end: 118
|
||||
source-kind: runtime-path-implementation
|
||||
|
||||
- id: F-ARTIFACT-PROVENANCE
|
||||
category: artifacts
|
||||
key: immutable-reports-and-receipts
|
||||
value:
|
||||
report-path: <workspace>/completion-records/<workflow>/<role>-<UTC timestamp>.report.yaml
|
||||
report-policy: 새 시도마다 새 파일을 발급하며 기존 report를 덮어쓰지 않는다.
|
||||
acceptance-history: 별도 append-only acceptance event로 관리
|
||||
receipt-ledger: <workspace>/evidence/ledger.jsonl
|
||||
receipt-records: [executed command and exit code, written artifact path and SHA-256]
|
||||
receipt-hook-limitation: workspace를 해석하지 못하면 계측을 생략하고 도구 실행 자체는 막지 않는다.
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: .claude/hooks/new_report.py
|
||||
line-start: 2
|
||||
line-end: 48
|
||||
source-kind: report-path-implementation
|
||||
- path: .claude/hooks/evidence_ledger.py
|
||||
line-start: 2
|
||||
line-end: 22
|
||||
source-kind: evidence-ledger-implementation
|
||||
|
||||
- id: F-PREREQ-TOOLS
|
||||
category: prerequisites
|
||||
key: runtime-tool-versions
|
||||
value:
|
||||
required:
|
||||
python: {minimum: '3.10', tested: '3.12.3'}
|
||||
PyYAML: {minimum: '6.0', tested: '6.0.1', pinned: '6.0.1'}
|
||||
recommended:
|
||||
jsonschema: {minimum: '4.0', tested: '4.10.3', pinned: '4.10.3'}
|
||||
node: {minimum: '18.0', tested: '24.14.0'}
|
||||
d2: {minimum: '0.6', tested: '0.7.1'}
|
||||
optional:
|
||||
marp: {minimum: '3.0', fallback: HTML deck}
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: .claude/tool-versions.yaml
|
||||
line-start: 1
|
||||
line-end: 16
|
||||
source-kind: tool-version-configuration
|
||||
- path: requirements.txt
|
||||
line-start: 1
|
||||
line-end: 7
|
||||
source-kind: dependency-manifest
|
||||
|
||||
- id: F-PREREQ-UI
|
||||
category: prerequisites
|
||||
key: design-system-preview-tools
|
||||
value:
|
||||
required-for-full-render-check: [detected package manager and project build command, Google Chrome or Chromium-compatible executable]
|
||||
checked-properties: [non-empty mounted DOM, generated JavaScript bundle, CSS contrast, keyboard focus visibility, responsive viewport screenshots]
|
||||
limitation: render health를 검사하지만 시각적 차별성·타이포·비례·spacing의 미학 품질은 판정하지 않는다.
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: .claude/hooks/preview_ui.py
|
||||
line-start: 2
|
||||
line-end: 41
|
||||
source-kind: UI-verification-implementation
|
||||
- path: .claude/hooks/preview_ui.py
|
||||
line-start: 54
|
||||
line-end: 79
|
||||
source-kind: UI-verification-implementation
|
||||
- path: .claude/hooks/preview_ui.py
|
||||
line-start: 541
|
||||
line-end: 541
|
||||
source-kind: UI-verification-limitation
|
||||
|
||||
- id: F-VERIFY-SUITE
|
||||
category: verification
|
||||
key: full-test-runner
|
||||
value:
|
||||
entrypoint: .claude/tests/run_all.py
|
||||
preflight: [compile_artifact_registry.py --check, doctor.py, lint_refs.py]
|
||||
test-discovery: .claude/tests/test_*.py
|
||||
execution: suites run sequentially with a per-suite timeout
|
||||
failure-contract: any failed or timed-out suite produces exit 1
|
||||
no-preflight-option: --no-preflight
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: .claude/tests/run_all.py
|
||||
line-start: 2
|
||||
line-end: 11
|
||||
source-kind: test-runner
|
||||
- path: .claude/tests/run_all.py
|
||||
line-start: 23
|
||||
line-end: 30
|
||||
source-kind: test-runner
|
||||
- path: .claude/tests/run_all.py
|
||||
line-start: 53
|
||||
line-end: 80
|
||||
source-kind: test-runner
|
||||
|
||||
- id: F-CI-WORKFLOW
|
||||
category: verification
|
||||
key: github-actions-ci
|
||||
value:
|
||||
triggers: {push: [main, fix/**, feat/**], pull-request: [main]}
|
||||
environment: {python: '3.12', node: '20', workspace: _sandbox}
|
||||
steps: [install pinned Python dependencies, attempt D2 0.7.1 installation, run doctor, run lint_refs, run gen_agents --check, run all tests with --no-preflight]
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: .github/workflows/ci.yml
|
||||
line-start: 1
|
||||
line-end: 46
|
||||
source-kind: CI-workflow
|
||||
|
||||
- id: F-MATURITY-CONTEXT
|
||||
category: limitation
|
||||
key: current-company-context-state
|
||||
value:
|
||||
company-context-status: template
|
||||
founder-context-status: template
|
||||
validation-stage: pre-traction
|
||||
implication: 회사 수립 경로는 사람이 founder context를 채우고 venture-bootstrap을 거쳐야 한다.
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: org-os/01-company/company-context.yaml
|
||||
line-start: 13
|
||||
line-end: 51
|
||||
source-kind: company-context
|
||||
- path: org-os/01-company/founder-context.yaml
|
||||
line-start: 1
|
||||
line-end: 17
|
||||
source-kind: company-context-input
|
||||
|
||||
- id: F-MATURITY-BENCHMARK
|
||||
category: limitation
|
||||
key: benchmark-evidence-status
|
||||
value:
|
||||
golden-tasks: 13
|
||||
executed-samples: {plain: 2, harness: 2}
|
||||
measured-dimensions: 3
|
||||
unexecuted-dimensions: 8
|
||||
observed-result:
|
||||
first-pass-acceptance: tie
|
||||
tests-pass-rate: tie
|
||||
unnecessary-change-lines: tie
|
||||
weighted-composite-delta: 0
|
||||
conclusion: 현재 표본은 하네스의 품질 우위를 입증하지 않는다.
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: benchmark/BENCHMARK.md
|
||||
line-start: 1
|
||||
line-end: 20
|
||||
source-kind: generated-benchmark-report
|
||||
- path: benchmark/runs.jsonl
|
||||
line-start: 1
|
||||
line-end: 4
|
||||
source-kind: benchmark-run-ledger
|
||||
|
||||
commands:
|
||||
- id: CMD-1
|
||||
command: pip install -r requirements.txt
|
||||
cwd: .
|
||||
source: {path: .github/workflows/ci.yml, line-start: 30, line-end: 31, source-kind: CI-workflow}
|
||||
verification:
|
||||
status: discovered
|
||||
method: static extraction
|
||||
level: repository-declared
|
||||
limitations: [Repository Evidence Analyst가 실행하지 않음.]
|
||||
|
||||
- id: CMD-2
|
||||
command: python3 .claude/tests/run_all.py
|
||||
cwd: .
|
||||
source: {path: .claude/tests/run_all.py, line-start: 7, line-end: 9, source-kind: test-runner-usage}
|
||||
verification:
|
||||
status: discovered
|
||||
method: static extraction
|
||||
level: repository-declared
|
||||
limitations: [Repository Evidence Analyst가 실행하지 않음.]
|
||||
|
||||
- id: CMD-3
|
||||
command: python3 .claude/hooks/doctor.py
|
||||
cwd: .
|
||||
source: {path: .github/workflows/ci.yml, line-start: 36, line-end: 37, source-kind: CI-workflow}
|
||||
verification:
|
||||
status: discovered
|
||||
method: static extraction
|
||||
level: repository-declared
|
||||
limitations: [유효한 ORGOS_WORKSPACE 또는 .orgos-workspace 포인터가 필요함., Repository Evidence Analyst가 실행하지 않음.]
|
||||
|
||||
- id: CMD-4
|
||||
command: python3 .claude/hooks/lint_refs.py
|
||||
cwd: .
|
||||
source: {path: .github/workflows/ci.yml, line-start: 39, line-end: 40, source-kind: CI-workflow}
|
||||
verification:
|
||||
status: discovered
|
||||
method: static extraction
|
||||
level: repository-declared
|
||||
limitations: [Repository Evidence Analyst가 실행하지 않음.]
|
||||
|
||||
- id: CMD-5
|
||||
command: python3 .claude/hooks/compile_artifact_registry.py --check
|
||||
cwd: .
|
||||
source: {path: .claude/tests/run_all.py, line-start: 57, line-end: 60, source-kind: test-runner-preflight}
|
||||
verification:
|
||||
status: discovered
|
||||
method: static extraction
|
||||
level: repository-observed-invocation
|
||||
limitations: [Repository Evidence Analyst가 실행하지 않음.]
|
||||
|
||||
- id: CMD-6
|
||||
command: python3 .claude/hooks/gen_agents.py --check
|
||||
cwd: .
|
||||
source: {path: .github/workflows/ci.yml, line-start: 42, line-end: 43, source-kind: CI-workflow}
|
||||
verification:
|
||||
status: discovered
|
||||
method: static extraction
|
||||
level: repository-declared
|
||||
limitations: [Repository Evidence Analyst가 실행하지 않음.]
|
||||
|
||||
- id: CMD-7
|
||||
command: python3 .claude/hooks/benchmark.py list
|
||||
cwd: .
|
||||
source: {path: .claude/hooks/benchmark.py, line-start: 11, line-end: 15, source-kind: benchmark-implementation}
|
||||
verification:
|
||||
status: discovered
|
||||
method: static extraction
|
||||
level: repository-observed-invocation
|
||||
limitations: [Repository Evidence Analyst가 실행하지 않음.]
|
||||
|
||||
- id: CMD-8
|
||||
command: python3 .claude/hooks/benchmark.py compare
|
||||
cwd: .
|
||||
source: {path: .claude/hooks/benchmark.py, line-start: 16, line-end: 19, source-kind: benchmark-implementation}
|
||||
verification:
|
||||
status: discovered
|
||||
method: static extraction
|
||||
level: repository-observed-invocation
|
||||
limitations: [기존 benchmark run ledger를 비교하며 새 표본을 생성하지 않음., Repository Evidence Analyst가 실행하지 않음.]
|
||||
|
||||
- id: CMD-9
|
||||
command: python3 .claude/hooks/benchmark.py run --task GT-01 --arm plain --execute
|
||||
cwd: .
|
||||
source: {path: .claude/hooks/benchmark.py, line-start: 11, line-end: 15, source-kind: benchmark-implementation}
|
||||
verification:
|
||||
status: discovered
|
||||
method: static extraction
|
||||
level: repository-observed-invocation
|
||||
limitations: [Claude CLI와 외부 실행 예산이 필요할 수 있음., Repository Evidence Analyst가 실행하지 않음.]
|
||||
@@ -0,0 +1,7 @@
|
||||
{
|
||||
"git-sha": "00db337cfb3a22feb0b4d8529f23d72067f9ce16",
|
||||
"dirty": true,
|
||||
"diff-hash": "sha256:1eaa580e67e33d16a6115eb8f66fd034446436fb8f3bf70842ee9fd91b60ca64",
|
||||
"scanned-at": null,
|
||||
"file-count": 893
|
||||
}
|
||||
@@ -0,0 +1,51 @@
|
||||
schema-version: 1
|
||||
verdict: PASS
|
||||
score: 93
|
||||
scores:
|
||||
project-specificity:
|
||||
score: 5
|
||||
evidence:
|
||||
- overview·operating-model·architecture가 workflow contract, hook, 역할 registry, workspace 산출물 체계를 구체적으로 설명한다.
|
||||
- F-IDENTITY-CORE, F-ARCH-STATE-ARTIFACT, F-ARCH-HOOKS, F-ARCH-ROLE-MODEL
|
||||
reader-journey:
|
||||
score: 4
|
||||
evidence:
|
||||
- 개요 → 운영 모델 → 시작하기 → workflow 선택 → 구조 → 검증 → 한계 → 정본 링크 순서가 brief의 reader journey와 일치한다.
|
||||
- 30초 독자에게 대상 독자는 다소 암시적이지만 프로젝트 정체성과 용도는 첫 두 문단에서 파악된다.
|
||||
technical-explanation:
|
||||
score: 5
|
||||
evidence:
|
||||
- workflow-contracts, state_engine, 사람 gate, hook event, append-only event와 SHA-256 provenance의 관계가 사실 범위 안에서 설명된다.
|
||||
- F-WORKFLOW-CASCADE, F-ARCH-STATE-ARTIFACT, F-ARTIFACT-PROVENANCE
|
||||
task-usability:
|
||||
score: 4
|
||||
evidence:
|
||||
- 의존성 설치, ORGOS_WORKSPACE 지정, doctor, 첫 slash command와 목적별 검증 명령이 복사 가능한 형태로 제공된다.
|
||||
- verification.json은 명령 5개 중 4개를 정적 확인하고 pip 설치 1개를 manual-required로 명시한다.
|
||||
prose-clarity:
|
||||
score: 5
|
||||
evidence:
|
||||
- ko-KR 기술 문체가 일관되고 표·목록·짧은 문단으로 긴 문서의 탐색성이 유지된다.
|
||||
- 정적 확인과 실제 실행 성공을 명시적으로 구분해 과장된 성공 표현을 피한다.
|
||||
visual-judgment:
|
||||
score: 5
|
||||
evidence:
|
||||
- 유일한 Mermaid 흐름도가 cascade stage와 두 사람 결정 경계를 직접 설명하며 장식적 시각물을 추가하지 않는다.
|
||||
- visual-plan의 must-show, relationships, emphasize, avoid 요구를 충족한다.
|
||||
hard-gates:
|
||||
passed: true
|
||||
failures: []
|
||||
reader-simulations:
|
||||
30-seconds:
|
||||
outcome: PASS
|
||||
evidence:
|
||||
- 제목과 첫 두 문단에서 Claude Code용 파일 기반 에이전트 운영 하네스라는 정체성, 존재 이유, 적용 업무를 파악할 수 있다.
|
||||
5-minutes:
|
||||
outcome: PASS
|
||||
evidence:
|
||||
- 시작하기, workflow 선택표, 저장소 구조, 검증 수준, 현재 한계를 통해 가치·실행·구조·제약을 모두 확인할 수 있다.
|
||||
contributor:
|
||||
outcome: PASS
|
||||
evidence:
|
||||
- architecture 표가 정본과 생성물을 구분하고, verification 표가 검사 명령을 제공하며, reference가 상세 계약과 docs로 연결한다.
|
||||
findings: []
|
||||
@@ -0,0 +1,10 @@
|
||||
# README 품질 검토
|
||||
|
||||
- 판정: **PASS**
|
||||
- 가중 점수: **93/100**
|
||||
- Hard gate: 모두 통과
|
||||
- 독자 시뮬레이션: 30초·5분·기여자 모두 통과
|
||||
|
||||
후보 문서는 Org OS의 workflow 계약, 사람 승인 경계, hook, workspace 산출물과 검증 체계를 저장소 고유 정보로 설명합니다. 정보 흐름과 한국어 가독성이 좋고, 기여자가 정본·생성물·검증 경로를 구분할 수 있습니다.
|
||||
|
||||
검증 수준도 정직합니다. 현재 증거는 정적 검증이며 대상 테스트 suite를 실행한 결과가 아닙니다. `pip install -r requirements.txt`는 manual-required이고, 나머지 문서 명령은 스크립트와 경로의 정적 존재만 확인됐다는 제한을 README가 명시합니다.
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"schema-version": 1,
|
||||
"run-id": "20260717-rewrite",
|
||||
"repo-id": "company-haness",
|
||||
"mode": "bootstrap",
|
||||
"target-repository": "/home/donghyeon/workspace/ai-tool/company-haness",
|
||||
"harness-version": "0.1.0",
|
||||
"started-at": null,
|
||||
"tool-adapter": "codex",
|
||||
"input-hashes": {}
|
||||
}
|
||||
@@ -0,0 +1,283 @@
|
||||
{
|
||||
"schema-version": 1,
|
||||
"mode": "bootstrap",
|
||||
"current": "APPLIED",
|
||||
"history": [
|
||||
{
|
||||
"state": "INITIALIZED"
|
||||
},
|
||||
{
|
||||
"state": "INPUT_CAPTURED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "request",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": null
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "REPOSITORY_SNAPSHOTTED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "snapshot",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"diff-hash": "sha256:1eaa580e67e33d16a6115eb8f66fd034446436fb8f3bf70842ee9fd91b60ca64"
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "FACTS_EXTRACTED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "facts",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"fact_ids": [
|
||||
"F-IDENTITY-CORE",
|
||||
"F-WORKFLOW-ENTRY",
|
||||
"F-WORKFLOW-CASCADE",
|
||||
"F-WORKFLOW-WAVE-LIGHT",
|
||||
"F-WORKFLOW-VENTURE",
|
||||
"F-WORKFLOW-SPECIALIZED",
|
||||
"F-ARCH-DIRECTORIES",
|
||||
"F-ARCH-ROLE-MODEL",
|
||||
"F-ARCH-COLLABORATION",
|
||||
"F-ARCH-STATE-ARTIFACT",
|
||||
"F-ARCH-HOOKS",
|
||||
"F-ARTIFACT-LAYOUT",
|
||||
"F-ARTIFACT-PROVENANCE",
|
||||
"F-PREREQ-TOOLS",
|
||||
"F-PREREQ-UI",
|
||||
"F-VERIFY-SUITE",
|
||||
"F-CI-WORKFLOW",
|
||||
"F-MATURITY-CONTEXT",
|
||||
"F-MATURITY-BENCHMARK"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "PROJECT_PROFILED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "profile",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"profile": "generic"
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "README_PLANNED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "brief",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": null
|
||||
},
|
||||
{
|
||||
"name": "outline",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"section_ids": [
|
||||
"overview",
|
||||
"operating-model",
|
||||
"quick-start",
|
||||
"workflows",
|
||||
"architecture",
|
||||
"artifacts",
|
||||
"verification",
|
||||
"limitations",
|
||||
"reference"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "README_DRAFTED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "conformance",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"sections": [
|
||||
"overview",
|
||||
"operating-model",
|
||||
"quick-start",
|
||||
"workflows",
|
||||
"architecture",
|
||||
"artifacts",
|
||||
"verification",
|
||||
"limitations",
|
||||
"reference"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "claim_map",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"claims": [
|
||||
"C-IDENTITY",
|
||||
"C-VALUE",
|
||||
"C-ENTRY-MODEL",
|
||||
"C-CONTRACT-MODEL",
|
||||
"C-COLLAB-MODEL",
|
||||
"C-HUMAN-BOUNDARY",
|
||||
"C-PROVENANCE-MODEL",
|
||||
"C-HOOK-MODEL",
|
||||
"C-PREREQUISITES",
|
||||
"C-INSTALL-COMMAND",
|
||||
"C-WORKSPACE-RESOLUTION",
|
||||
"C-DOCTOR-COMMAND",
|
||||
"C-DOCTOR-SCOPE",
|
||||
"C-FIRST-COMMAND",
|
||||
"C-WORKFLOW-CASCADE",
|
||||
"C-WORKFLOW-WAVE",
|
||||
"C-WORKFLOW-LIGHT",
|
||||
"C-WORKFLOW-VENTURE",
|
||||
"C-SPECIALIZED-WORKFLOWS",
|
||||
"C-CASCADE-VISUAL",
|
||||
"C-ARCH-SOURCE",
|
||||
"C-DIRECTORY-MAP",
|
||||
"C-ROLE-MODEL",
|
||||
"C-GENERATED-AGENTS",
|
||||
"C-WORKSPACE-LAYOUT",
|
||||
"C-REPORT-RECEIPTS",
|
||||
"C-CMD-DOCTOR",
|
||||
"C-CMD-AGENTS",
|
||||
"C-CMD-TESTS",
|
||||
"C-CMD-BENCHMARK",
|
||||
"C-TEST-RUNNER",
|
||||
"C-CI",
|
||||
"C-BENCHMARK-STATUS",
|
||||
"C-LIMIT-CONTEXT",
|
||||
"C-LIMIT-HOOKS",
|
||||
"C-LIMIT-UI",
|
||||
"C-LIMIT-TOOLS",
|
||||
"C-LIMIT-EVIDENCE"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "VISUALS_PLANNED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "visual_plan",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"visuals": [
|
||||
"cascade-flow"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "STRUCTURALLY_VALIDATED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "github_markdown",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": null
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "TECHNICALLY_VERIFIED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "verify",
|
||||
"ok": true,
|
||||
"warnings": [
|
||||
"manual verification required: pip install -r requirements.txt (unsupported-static-verifier)"
|
||||
],
|
||||
"data": {
|
||||
"schema-version": 1,
|
||||
"state": "PASS_WITH_MANUAL",
|
||||
"verification-level": "static",
|
||||
"execution-verified": false,
|
||||
"checks": {
|
||||
"commands": {
|
||||
"total": 5,
|
||||
"verified": 4,
|
||||
"manual-required": 1,
|
||||
"failed": 0
|
||||
},
|
||||
"paths": {
|
||||
"total": 15,
|
||||
"verified": 15,
|
||||
"failed": 0
|
||||
},
|
||||
"anchors": {
|
||||
"total": 0,
|
||||
"verified": 0,
|
||||
"failed": 0
|
||||
},
|
||||
"readme-contracts": {
|
||||
"total": 0,
|
||||
"verified": 0,
|
||||
"failed": 0
|
||||
}
|
||||
},
|
||||
"failures": [],
|
||||
"limitations": [
|
||||
"manual verification required: pip install -r requirements.txt (unsupported-static-verifier)"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "secret_scan",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": null
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "QUALITY_REVIEWED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "review",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"verdict": "PASS",
|
||||
"score": 93,
|
||||
"findings": []
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "READY_FOR_APPLY",
|
||||
"gates": []
|
||||
},
|
||||
{
|
||||
"state": "APPLIED",
|
||||
"gates": []
|
||||
}
|
||||
],
|
||||
"rework": {
|
||||
"iterations": 0,
|
||||
"findings": {}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,33 @@
|
||||
{
|
||||
"schema-version": 1,
|
||||
"state": "PASS_WITH_MANUAL",
|
||||
"verification-level": "static",
|
||||
"execution-verified": false,
|
||||
"checks": {
|
||||
"commands": {
|
||||
"total": 5,
|
||||
"verified": 4,
|
||||
"manual-required": 1,
|
||||
"failed": 0
|
||||
},
|
||||
"paths": {
|
||||
"total": 15,
|
||||
"verified": 15,
|
||||
"failed": 0
|
||||
},
|
||||
"anchors": {
|
||||
"total": 0,
|
||||
"verified": 0,
|
||||
"failed": 0
|
||||
},
|
||||
"readme-contracts": {
|
||||
"total": 0,
|
||||
"verified": 0,
|
||||
"failed": 0
|
||||
}
|
||||
},
|
||||
"failures": [],
|
||||
"limitations": [
|
||||
"manual verification required: pip install -r requirements.txt (unsupported-static-verifier)"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,32 @@
|
||||
schema-version: 1
|
||||
visuals:
|
||||
- id: cascade-flow
|
||||
section: workflows
|
||||
type: sequence-diagram
|
||||
purpose: intake부터 released까지의 공식 cascade stage와 두 사람 결정 경계를 한 화면에 설명한다.
|
||||
placeholder-text: Mermaid flowchart로 stage별 slash command와 방향 수용·release 승인 gate를 순서대로 표시한다.
|
||||
must-show:
|
||||
- intake부터 acceptance까지의 여덟 stage
|
||||
- 각 stage의 slash command
|
||||
- decide 이후 사람 방향 수용
|
||||
- acceptance 이후 사람 release 승인
|
||||
- released 종단
|
||||
relationships:
|
||||
- intake -> discovery -> decide
|
||||
- decide -> 사람 방향 수용 -> design
|
||||
- design -> spec -> build -> verification -> acceptance
|
||||
- acceptance -> 사람 release 승인 -> released
|
||||
emphasize:
|
||||
- 사람 gate에서는 자동 완주하지 않음
|
||||
- 화살표는 workflow stage 순서임
|
||||
avoid:
|
||||
- wave와 light 경로를 같은 흐름에 섞기
|
||||
- artifact 세부 필드를 diagram에 모두 넣기
|
||||
- 사람 승인을 AI 자동 승인처럼 표현하기
|
||||
placement:
|
||||
after-section-id: workflows
|
||||
accessibility:
|
||||
alt-text: ceo-intake에서 ground, decide, 사람 방향 수용, design, spec, build, review-output, release-check, 사람 release 승인을 거쳐 released에 도달하는 cascade 순서
|
||||
production:
|
||||
format: mermaid
|
||||
status: embedded
|
||||
Reference in New Issue
Block a user