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: 목적별 상대 링크 목록이 탐색과 유지보수에 가장 적합하다.