init: company-haness 설계
This commit is contained in:
DongHyeonka
@@ -0,0 +1,41 @@
|
||||
---
|
||||
description: 설계·기능명세·디자인을 기반으로 실제 개발을 진행한다. 구현 family(collapse) + QA. cascade 5단계(BUILD).
|
||||
---
|
||||
|
||||
당신은 Orchestrator다. **BUILD phase (workflow-stage = `build`)** — 승인된 설계+명세+디자인을 실제 **구현**한다.
|
||||
입력: `/spec` 세부 명세 + `/design` 설계 + 디자인 산출물 경로(인자, `--workflow <wf>`). substantial 경로면 **must-read**.
|
||||
|
||||
## 절차
|
||||
0. **변경 분류 — 문서 게이트를 위험도에 비례시킨다(paperwork ∝ risk/tier, finding #8)**. 모든 빌드에 PRD/API계약/데이터모델/위협모델을 **일괄** 요구하지 않는다. `governance-tiers.yaml` `risk-classification-rubric`(risk × reversibility × blast-radius)로 먼저 분류:
|
||||
- **light path — 단순 변경**(버그픽스 · 문서 · 설정/ops · 작은 수정; risk Low · two-way-door · single-role → tier light): 선행 설계 문서 **불요**. 최소 접지만 요구 = ①현재 동작/재현 ②smallest-safe-change 계획 ③검증(테스트/재현 receipt). 구현 루프(아래)를 그대로 돌린다. **단순 변경을 설계 부재로 Blocked 처리하지 않는다.**
|
||||
- **substantial path — 새 표면/실질 변경**(새 공개 API · 스키마/데이터모델 신설 · 교차팀 blast · 보안/프라이버시/법무 접촉 · one-way-door → tier standard/heavy): 아래 1번 선행조건 게이트 적용.
|
||||
- 경계 판단(하나라도 해당이면 substantial로 승격): 새 공개 계약/표면 · 데이터모델 변경 · 마이그레이션/비가역 · 보안·PII·법무 접촉 · 프로덕션/고객/매출 blast · 교차팀 영향.
|
||||
1. **선행조건 게이트 — 상태엔진이 강제(substantial 경로만, finding #13)**: `python3 .claude/hooks/state_engine.py guard --workflow <wf> --to build` 를 호출한다. 이 guard는 **핵심 게이트** `spec→build` = **spec-accepted + must-read-designs-accepted**(`workflow-contracts.yaml`에서 workload-profile에 따라 계산된 design/spec bundle이 전부 Accepted)를 강제한다 — 현재 프롬프트 문구가 아니라 **엔진이 실제로 차단**한다.
|
||||
- **exit 2면 구현을 시작하지 않는다** — 미충족 설계를 payload에 담은 typed
|
||||
`artifact-kind: blocked-report`(blocker + resume-condition)를 제출하고 `block-workflow`를 호출한다.
|
||||
- **light 경로는 이 guard를 호출하지 않는다**(단순 변경을 설계 부재로 false-Blocked 처리 금지, finding #8). light 변경은 `light` plan(intake→run→verification)으로 흐르며 설계 게이트가 적용되지 않는다. 단, 도중에 새 표면·비가역·보안 접촉이 드러나면 즉시 substantial로 승격하고 이 guard를 적용한다.
|
||||
- exit 0이면 substantial은 `enter-stage --workflow <wf> --to build --actor OPS-ORCH`, light는
|
||||
해당 plan gate 통과 후 `enter-stage --to run --actor OPS-ORCH`로 현재 실행 stage를 연다.
|
||||
2. **실행(collapse) — 구현 루프를 척추로(first-class, finding #8)**: `role_selector.py plan --profile <workload-profile.yaml>`가 구현 owner 1명(필요 시 contributor/reviewer)을 고른 뒤 concrete worker를 직접 spawn한다. family는 actor가 아니다. 프레임워크를 나열하고 얇은 report로 끝내지 말고 이 루프를 실제로 돈다:
|
||||
- **inspect** → **smallest safe change plan** → **implement** → **targeted verify(합리적이면 실패 테스트/재현 먼저)** → **broader verify(lint/typecheck/unit/integration)** → **inspect own diff** → **report(검증한 것 vs 실행하지 않은 것을 명시)**.
|
||||
- inspect = 현재 동작 재현 + 기존 코드·컨벤션·**호출부(callers)** 탐색(탐색 없이 바로 코딩 금지). 프레임워크는 각 단계를 '잘' 하는 방법이지 루프를 대체하지 않는다.
|
||||
- **context-package(spawn 전 필수 게이트, finding #4)**: 구현 에이전트를 띄우기 전 단일 컴파일러로 패키지를 만들고 검증한다 — `python3 .claude/hooks/context_package.py --compile --workflow <wf> --task <task> --role <role> --mode converge --tier <tier> [--target-repo <repo>]`로 발급 → 스켈레톤 placeholder(objective·allowed-tools·task-boundaries·must-read·non-goals·target-repo·acceptance-tests·evidence-plan)를 채움(target-repo=대상 저장소, acceptance-tests=수용검사, evidence-plan=빌드/테스트 receipt로 E4/E5 접지) → `python3 .claude/hooks/context_package.py <pkg>`가 **exit 0**일 때만 spawn(누락/빈 필드/위장 placeholder면 금지 — finding P0-2). **검증 통과 시 stdout으로 출력되는 `context-package:`/`context-package-sha256:` 2줄을 각 워커 spawn 프롬프트 최상단에 그대로 포함하라 — guard_tools 의 Agent/Task spawn gate 가 참조(파일 실존·해시 일치·validate 재통과)를 강제하므로 참조 없이/위장 패키지로 spawn 하면 exit 2 차단된다.** **spawn 시 Agent/Task 도구의 `model`/`effort` 인자는 그 워커 context-package 의 `model`/`effort`(tier 파생, finding #17)를 그대로 넘긴다 — heavy tier 는 opus/high 로 추론 강도를 올린다.** 필드 정의·규칙은 `org-os/06-agent-work/context-package-spec.yaml`. objective/boundaries 즉석 추론 금지.
|
||||
- 후보 family는 FAM-ENG-FRONTEND(프론트) · FAM-ENG-BACKEND(서버/API) · FAM-PLATFORM-INFRA(인프라)이며 signal과 required artifact로 최소 role을 선택한다.
|
||||
- `tags:[<주제>,build]` 불변 completion-record(작업요약·산출물·검증·handoff).
|
||||
3. **검증(audit) — tier 비례**: light면 targeted+broader verify receipt로 충분. 검증 명령은 `verify_run.py --workflow <wf> --agent <role> --session <id> --category <category> --subject <criterion> [--source-revision-sha256 <sha>] -- <command> <args...>`로 실행한다. standard 이상이면 `QA` + 필요 시 FAM-SECURITY 후보에서 planner가 고른 concrete 보안 역할을 producer와 분리한다. tier=heavy면 병렬 감사 팬아웃(≥3, 과반 반증→Blocked).
|
||||
4. **게이트/보고**: validate_report(E4/E5는 실행/실존 아티팩트) · token_ledger · render_report + Slack 스레드.
|
||||
|
||||
## 산출/handoff
|
||||
- `artifact-kind: completion-record` 보고서 + 구현 산출물 + 검증 기록. `submit-artifact --workflow <wf> --report <path> --actor OPS-ORCH`가 실제 파일/schema/id/hash를 검증해 다음 gate의 근거로 삼는다.
|
||||
- active Method의 현재 completion step은 `artifact-refs`로 자기 자신을 참조하지 않는다. 이전 step(예: api-contract)은 trusted exact `report-id+sha256`로 참조하고, 현재 step에는 `output-binding: current-artifact`를 쓴다. producer 자기 judgment는 `self-check-results`+receipt로, 독립 reviewer judgment는 원본 submit 후 exact `method-judgment-review`로 기록한 다음 Accepted 처리한다.
|
||||
- **stage 완료:** completion-record를 제출한 뒤 현재 stage(`build` 또는 `run`)를
|
||||
`complete-stage --workflow <wf> --actor OPS-ORCH --evidence <build.report.yaml>`로 완료한다.
|
||||
`/review-output`이 verification을 연다.
|
||||
- **다음**: `/review-output`(Parent 수용) → `/release-check`(Release Acceptance + 인간 게이트). `/review-output` 진입 guard가 `build→verification`(또는 light면 `run→verification`) = **completion-record-present**를 강제한다.
|
||||
|
||||
## 규칙
|
||||
- **문서 게이트는 위험도에 비례**(finding #8): substantial(새 표면·비가역·보안·교차팀) 작업만 "설계 Accepted 후 구현"을 강제한다. 단순 변경(버그픽스·문서·ops·작은 수정)은 full PRD/API계약/데이터모델/위협모델 없이 진행 — 단, 도중 새 표면·비가역·보안이 드러나면 즉시 승격. **과잉 차단(false Blocked)도 과소 검증도 금지.**
|
||||
- substantial 경로에서 설계 충돌·부재 발견 시 임시 우회 대신 BlockedReport.
|
||||
- **구현 루프를 실제로 돈다**(프레임워크 나열+얇은 report 금지): inspect→plan→implement→targeted verify→broader verify→diff 재점검→report. 상세는 `.claude/skills/build-loop`.
|
||||
- 구현은 collapse(효율)이나 tier=heavy 리뷰는 fan-out 감사. external side-effect(배포/PR/secret)는 기본 금지.
|
||||
- 근거 없는 '통과' 금지 — 테스트/CI 아티팩트를 evidence(E4/E5)로. report는 **검증한 것 vs 실행하지 않은 것**을 정직히 구분한다.
|
||||
@@ -0,0 +1,104 @@
|
||||
---
|
||||
description: OPS-ORCH가 EXEC-CEO 역할 계약으로 Decision Brief를 만들고 mode/tier를 선언한다.
|
||||
---
|
||||
|
||||
당신은 concrete executor `OPS-ORCH`다. 먼저
|
||||
`python3 .claude/hooks/intake_classifier.py "<request>"`로 요청을 분류한다.
|
||||
`light-operational`은 CEO 산출물을 만들지 않고 direct owner → verify → review의 light plan으로,
|
||||
`substantial`은 필요한 설계/명세 계약만 계산해 delivery로, `strategic`만 executive decision plane으로
|
||||
보낸다. 전략 경로의 Decision Brief author는 concrete role `EXEC-CEO`이며 `FAM-CEO`는 metadata다.
|
||||
|
||||
## 절차
|
||||
1. 사용자 의도를 한 문장으로 재진술한다.
|
||||
2. **mode**를 선언한다: `collaboration-modes.yaml`의 mode-decision-checklist로 divergent(아이디어) vs converge(결정) 판정. 불명확하면 converge.
|
||||
3. **tier**를 제안한다: `governance-tiers.yaml`의 risk-classification-rubric으로 risk/reversibility/blast-radius를 평가해 light/standard/heavy 파생. production/customer/revenue 접촉이면 독립 tier-check 필요.
|
||||
4. Decision Brief의 `candidate-families`를 비어 있지 않게 선언한다. 모든 값은
|
||||
`capability-families.yaml`의 등록 ID여야 하며 중복을 허용하지 않는다. `mode=divergent`이면
|
||||
`governance-tiers.yaml`의 tier별 이론 렌즈 바닥(light 3, standard 5+contrarian,
|
||||
heavy all-relevant+contrarian)을 만족하는 candidate set이어야 한다. 미등록 값이나 부족한 set은
|
||||
제출 단계에서 hard fail이다.
|
||||
5. Decision Brief의 `mode`/`tier`/`candidate-families`와 Workload Profile의
|
||||
`required-capabilities`/risk/surfaces를 하나의 planning profile로 합쳐
|
||||
`role_selector.py plan --profile <planning-profile.yaml>`로 계산한다. family는 후보 집합이며
|
||||
coverage·독립성·token budget을 만족하는 concrete role만 선택한다. `status: blocked`이면 진행하지
|
||||
않는다. `required-capabilities`는 등록 capability만 쓰며 실제 concrete role 커버리지로 충족해야 한다
|
||||
(`competitive-intelligence`는 반드시 `GTM-CI`; family 이름만으로 대체 불가).
|
||||
6. typed **Workload Profile**을 판정한다. UI 여부는 오직 `payload.surfaces.ui`에 기록하고,
|
||||
`deliverable-profile`·`deliverable-kind`·build-family로 다시 추론하지 않는다. UI면
|
||||
`surface-archetype`과 `experience-change`도 반드시 판정한다. `public-website`, `new-product`,
|
||||
`major-redesign` 중 하나면 `/experience-foundation`이 design-direction보다 먼저 강제된다.
|
||||
7. Decision Brief를 **report-header(BLUF)로 시작**해 작성한다.
|
||||
|
||||
## 출력 계약과 원자적 종료
|
||||
|
||||
Decision Brief와 Workload Profile은 서로 다른 typed artifact다. `deliverable-profile`,
|
||||
`deliverable-kind`, build-family 같은 별도 UI 추론값을 만들지 않는다.
|
||||
|
||||
1. `state_engine.py init-workflow --workflow <wf> --plan <plan> --tier <tier>`.
|
||||
2. 아래 두 스냅샷을 각각 `new_report.py --workflow <wf> --role EXEC-CEO --stub
|
||||
--artifact-kind <kind> --stage intake`로 발급해 채운다.
|
||||
3. 각각 `validate_report.py <path>` 후
|
||||
`state_engine.py submit-artifact --workflow <wf> --report <path> --actor OPS-ORCH`로 제출한다.
|
||||
4. `state_engine.py check-company-context-ready --workflow <wf>`가 실패하면 intake를 완료하지 않는다.
|
||||
5. 모두 통과하면 `state_engine.py complete-stage --workflow <wf> --actor OPS-ORCH
|
||||
--evidence <workload-profile-path>`로 `intake.completed`를 기록한다. `/ground`가 다음 stage를 연다.
|
||||
workflow.yaml이나 facts를 직접 고치지 않는다.
|
||||
|
||||
Decision Brief payload:
|
||||
```yaml
|
||||
report-type: workflow-artifact
|
||||
artifact-kind: decision-brief
|
||||
artifact-version: 1
|
||||
identity:
|
||||
artifact-id: <minted-id>
|
||||
workflow-id: <wf>
|
||||
stage: intake
|
||||
producer-role-id: EXEC-CEO
|
||||
report-header:
|
||||
bottom-line: <한 문장 결론/권고>
|
||||
decision-needed:
|
||||
needed: true/false
|
||||
approver: <사람 또는 EXEC-CEO>
|
||||
confidence:
|
||||
value: High/Med/Low
|
||||
derived-from: evidence
|
||||
risks: []
|
||||
evidence:
|
||||
- source-uri: <실존 파일 경로>
|
||||
grade: E0-E5
|
||||
payload:
|
||||
mode: divergent / converge
|
||||
tier: light / standard / heavy
|
||||
candidate-families: [FAM-CEO, FAM-CPO, FAM-CTO, FAM-CFO, FAM-QA]
|
||||
```
|
||||
|
||||
Workload Profile payload:
|
||||
|
||||
```yaml
|
||||
report-type: workflow-artifact
|
||||
artifact-kind: workload-profile
|
||||
artifact-version: 1
|
||||
identity: { artifact-id: <minted-id>, workflow-id: <wf>, stage: intake, producer-role-id: EXEC-CEO }
|
||||
report-header: <동일 BLUF 계약>
|
||||
payload:
|
||||
surfaces: { ui: true, public-api: false, persistence: false, infrastructure: false }
|
||||
surface-archetype: public-website
|
||||
experience-change: new-product
|
||||
risk: { security-bearing: false, data-migration: false, external-side-effect: false }
|
||||
required-capabilities: [product, design, frontend]
|
||||
product-feature: true
|
||||
```
|
||||
|
||||
## 금지
|
||||
- report-header 없이 종료 금지. evidence 없는 confidence:High 금지.
|
||||
- workflow queue/state 직접 조작(→ Orchestrator), 사용자 승인 대체 금지.
|
||||
|
||||
## 회사 부트스트랩 진입(venture-bootstrap)
|
||||
|
||||
새 **회사/제품군을 처음 세우는** 경우에만 `--plan venture-bootstrap`을 명시한다(자동 선택 금지 — 기존 제품 cascade와 충돌 방지).
|
||||
|
||||
1. `org-os/01-company/founder-context.yaml`의 `status`를 확인한다. `template`이면 **사람에게 채우도록 요청**하고(창업자 강점·시간·자본·유통역량·리스크 내성·hard-constraints), `status: filled`로 바뀌기 전에는 다음 단계로 진행하지 않는다(founder-setup 게이트가 `founder-context-present`를 강제).
|
||||
2. Decision Brief를 작성하고 `plan=venture-bootstrap`, `tier`를 선언한다.
|
||||
3. 상태 초기화 후 다음: `/venture-validate`.
|
||||
|
||||
기존 회사(공식 company-context.status ∈ {provisional, operating})면 이 절을 건너뛰고 제품 cascade(`/ground` 등)로 간다. 제품 진입 gate는 회사 문맥 준비를 runtime에서 강제한다(template면 거부).
|
||||
@@ -0,0 +1,20 @@
|
||||
---
|
||||
description: 벤처결정(C-Level converge + 사람 승인)→company-context candidate→원자적 commit. venture-bootstrap 3단계.
|
||||
---
|
||||
|
||||
당신은 Orchestrator다. **venture-bootstrap: venture-decision + company-context-commit.** `/venture-validate`의 검증된 옵션을 하나로 수렴해 회사 문맥을 확정한다. 재사용 단위는 `/decide` 명령이 아니라 **공통 converge 계약**(`org-os/06-agent-work/collaboration-modes.yaml`의 `converge`: synthesis + report-header + decision-record). **모든 상태 전이는 OPS-ORCH가 집행**한다.
|
||||
|
||||
1. **guard/진입:** `guard --workflow <wf> --to venture-decision`이 `venture-options-validated`를
|
||||
확인하면 `enter-stage --workflow <wf> --to venture-decision --actor OPS-ORCH`로 진입한다.
|
||||
2. **venture-decision(수렴):** C-Level이 독립 평가하고 EXEC-CEO가 converge 종합해 `artifact-kind: venture-decision`을 산출한다.
|
||||
3. **원장 등록:** `python3 .claude/hooks/state_engine.py submit-artifact --workflow <wf> --report <path> --actor OPS-ORCH`.
|
||||
4. **사람 승인(해시 바인딩):** `state_engine.py review-artifact --workflow <wf> --report <path>
|
||||
--decision accepted --reviewer HUMAN-001`. 엔진이 exact id+sha를 결속하고 self-review를 거부한다.
|
||||
5. **완료/commit 진입:** `complete-stage --workflow <wf> --actor OPS-ORCH --evidence <path>` 후
|
||||
`enter-stage --workflow <wf> --to company-context-commit --actor OPS-ORCH`.
|
||||
6. **company-context candidate 작성:** `<workspace>/completion-records/<wf>/company-context.candidate.yaml` — 선택 결정을 `strategic-decisions`(accepted-by: HUMAN-001, source-decision-id=venture-decision id), 확정 사실을 `facts`(provenance), 시장 가정을 `hypotheses`(validation-status: untested, falsification-criteria). `status: provisional`, `candidate-status: bootstrap`.
|
||||
7. **atomic commit:** `python3 .claude/hooks/commit_company_context.py --workflow <wf> --candidate <candidate-path> --require-human`. (lint Hard Fail 0 + human receipt 검증 통과 시에만 공식 파일 원자 교체 + company-context artifact 등록. 실패 시 공식 파일 무변경.) 공식 `company-context.yaml` 직접 Edit/Write는 guard_tools가 차단한다.
|
||||
8. **완료/종료:** commit gate 통과 후 `complete-stage`로 company-context-commit을 완료하고
|
||||
`enter-stage --to bootstrap-complete --actor OPS-ORCH`, 이어 terminal stage도 `complete-stage`로 닫는다.
|
||||
9. **다음:** 제품 cascade(`/ground` …)가 이제 `company-context-ready`를 통과한다. 제품 intake는
|
||||
`company-context-ref`·`venture-decision-id`·`company-decision-ids`를 참조한다.
|
||||
@@ -0,0 +1,92 @@
|
||||
---
|
||||
description: 외부·독립 컨설팅 관점으로 진단→권고하고 문서+PPT를 산출한다. engagement 유형(비즈니스/문서)으로 family를 데이터 분기 → render_consult.
|
||||
---
|
||||
|
||||
당신은 Orchestrator다. **CONSULT** — LENS-ADVISORY(외부·제3자 독립 자문)로 주제를 진단하고 대표용 **문서 + 덱(PPT)**을 낸다.
|
||||
입력(인자): 컨설팅 주제 + must-read 자료(문서/대상 프로젝트 경로). 예: `/consult 클린아키텍처 적용 · 자료=<doc> · 대상=<repo>`.
|
||||
|
||||
구조: **lead가 프레임+종합, 분과가 격리 fan-out.** 실제 컨설팅 엔게이지먼트 방식(웹조사 근거: Pyramid·MECE·Diátaxis·C4·액션타이틀).
|
||||
|
||||
## Engagement 바인딩(0단계에서 하나 선택 → lead/workers/output-contract가 여기서 결정된다)
|
||||
|
||||
이 커맨드는 **두 컨설팅 family를 데이터로 분기**한다. 0단계에서 `${eng}`를 판정해 아래 표의 한 행을 고르면, `lead`·`workers`·`frame`·`analyze`·`synthesize`·`output-contract`가 **그 행에서 바인딩**되고, 이어지는 ①②③ 절차는 하드코딩된 분과가 아니라 **바인딩된 `${lead}`/`${workers}`를 그대로 실행**한다. 즉 문서 엔게이지먼트는 절대 비즈니스 분과로 새지 않는다(두 경로 대칭).
|
||||
|
||||
```yaml
|
||||
engagements:
|
||||
business: # 채택·전략·운영·재무 의사결정 (기본값)
|
||||
when: 전략/운영/조직/기술투자/재무 의사결정을 진단·권고해야 할 때
|
||||
family: FAM-CONSULTING
|
||||
lead: consult-em # ① FRAME · ③ SYNTHESIZE
|
||||
workers: # ② ANALYZE fan-out (격리 subagent, 각자 자기 관점만)
|
||||
- id: consult-strat lens: 전략 frameworks: Five Forces·BCG·3-Horizons
|
||||
- id: consult-ops lens: 운영·프로세스 frameworks: Lean·DMAIC·Value-Stream·TOM
|
||||
- id: consult-org lens: 조직·변화 frameworks: 7S·ADKAR·Kotter
|
||||
- id: consult-digital lens: 디지털·기술 frameworks: Digital-Maturity·TOGAF·use-case
|
||||
- id: consult-fin lens: 재무·리스크 frameworks: DCF·QoE·Three-Lines
|
||||
frame: consult-em → SCQA + 이슈트리(MECE) + Day-1 가설 (workstream 경계·shared-constraints)
|
||||
synthesize: consult-em → Pyramid Principle 종합 + storyline
|
||||
output-contract: 진단→권고 storyline. exhibit=정량·전략 아키타입(워터폴/2x2/하비볼/밸류체인/벤치마크/이슈트리/프로세스); 구조·흐름은 D2.
|
||||
doc-consulting: # 기술 문서의 논리흐름·정보구조·다이어그램·학습성
|
||||
when: 문서·콘텐츠 설계 자문(문서 구조/IA/다이어그램/학습성 개선)이 목적일 때
|
||||
family: FAM-DOC-CONSULT
|
||||
lead: doc-lead # ① FRAME · ③ SYNTHESIZE
|
||||
workers: # ② ANALYZE fan-out (격리 subagent, 각자 자기 관점만)
|
||||
- id: doc-writer lens: 테크니컬 라이팅 frameworks: Diátaxis(튜토리얼/하우투/레퍼런스/설명)·문장·단일독해
|
||||
- id: doc-ia lens: 정보구조 frameworks: 정보 아키텍처·progressive disclosure·탐색모델
|
||||
- id: doc-visual lens: 다이어그램·시각화 frameworks: C4·abstraction-first·diagram-as-code(D2)
|
||||
- id: doc-edu lens: 학습성·인지부하 frameworks: cognitive-load·curse-of-knowledge·작업기억
|
||||
cross-practice-optional: consult-digital # 기술 정확성 검증이 중요하면 교차 분과로 추가
|
||||
frame: doc-lead → 문서 목적·독자·스토리라인 프레이밍 + Diátaxis 유형판정 + 아웃라인(문서 workstream 경계)
|
||||
synthesize: doc-lead → Pyramid Principle 종합 + 문서 스토리라인
|
||||
output-contract: 문서 개선안 storyline. exhibit=정보구조/다이어그램 중심(C4·의존성·흐름은 D2 우선, 정량은 아키타입).
|
||||
```
|
||||
|
||||
판정 규칙: 요청·자료의 목적이 **"문서 자체(구조·읽기흐름·다이어그램·학습성)를 좋게 만드는 것"**이면 `doc-consulting`, **"사업/기술/재무 의사결정을 내리는 것"**이면 `business`(기본값). scorecard 모호하면 사용자에게 1문장 확인.
|
||||
|
||||
## 절차 (모든 단계는 위에서 바인딩된 `${eng}`의 `lead`/`workers`를 실행 — 하드코딩 아님)
|
||||
|
||||
0. **판정 + Pre-work**: 위 표에서 `${eng}` 선택 → `${lead}`·`${workers}` 바인딩. `slack_inbox.py`·`report_tags.py --tag <주제>`로 관련 과거 결정·동료 보고서 must-read. workflow-id 정한다(`wf-<slug>`).
|
||||
- `business` → lead=`consult-em`, workers=`consult-strat/ops/org/digital/fin`.
|
||||
- `doc-consulting` → lead=`doc-lead`, workers=`doc-writer/doc-ia/doc-visual/doc-edu`(+옵션 `consult-digital`).
|
||||
- **context-package(spawn 전 필수 게이트, finding P0-2)**: 이 커맨드의 **모든 subagent spawn(lead·각 worker)**도 cascade/wave와 동일하게 패키지를 거친다 — `python3 .claude/hooks/context_package.py --compile --workflow <wf> --task <task> --role <role> --mode <divergent|converge> --tier <tier> [--lens <LENS>]`로 발급 → placeholder 채움 → `python3 .claude/hooks/context_package.py <pkg>`가 exit 0이어야 하고, **출력된 `context-package:`/`context-package-sha256:` 2줄을 그 subagent spawn 프롬프트 최상단에 포함**한다. guard_tools 의 spawn gate 가 이를 강제하므로 참조 없이 consult 분과를 spawn 하면 차단(exit 2)된다.
|
||||
1. **① FRAME — `${lead}`** (subagent: 바인딩된 lead):
|
||||
- `business`(consult-em): 주제를 **SCQA**로 프레이밍, **이슈트리(MECE)** 분해, **Day-1 가설**. 각 분과 workstream 경계 + shared-constraints.
|
||||
- `doc-consulting`(doc-lead): 문서의 **목적·독자·핵심 스토리라인**을 프레이밍, **Diátaxis 유형 판정**과 아웃라인으로 문서 workstream 경계 + shared-constraints.
|
||||
- 공통: must-read 자료를 반드시 읽힌다. 프레임 없는 fan-out 금지.
|
||||
2. **② ANALYZE — `${workers}` fan-out**(격리 subagent, 각자 자기 관점만, 표의 `frameworks` 적용):
|
||||
- `business`: `consult-strat`·`consult-ops`·`consult-org`·`consult-digital`·`consult-fin`.
|
||||
- `doc-consulting`: `doc-writer`(Diátaxis·단일독해)·`doc-ia`(정보구조·progressive disclosure)·`doc-visual`(C4·diagram-as-code·D2)·`doc-edu`(인지부하·학습성). 기술 정확성이 중요하면 `consult-digital`을 교차 분과로 추가.
|
||||
- 각자 `new_report.py`로 불변 `.report.yaml`(report-header BLUF + 근거). 최종 메시지=경로+1줄.
|
||||
- tier·shared-constraints·토큰게이트(`token_ledger`) 적용. 주제 범위가 좁으면 관련 분과만 선택(scorecard) — 단 **다른 family의 분과로 대체 금지**(business에서 doc-writer, doc에서 consult-fin을 부르지 않는다).
|
||||
3. **③ SYNTHESIZE — `${lead}`**(subagent: 바인딩된 lead — business=consult-em, doc-consulting=doc-lead):
|
||||
- `${workers}`의 `.report.yaml`을 **전부 읽고(rehydration)** Pyramid Principle로 종합.
|
||||
- 종합 `.report.yaml`은 `synthesized-by`·`linked-reports`(분과 전부)·`conflicts`(이견 보존, 없으면 [])를 **필수** 포함(hook 강제).
|
||||
- 대표 문서·덱용 **`storyline:` 블록**을 만든다(output-contract에 맞는 exhibit 선택):
|
||||
```yaml
|
||||
storyline:
|
||||
title: ...; client: ...; date: ...
|
||||
scqa: { situation, complication, question, answer } # answer=지배 메시지
|
||||
slides:
|
||||
- action-title: "완결문장·정량 주장(≤15단어, 새 정보)"
|
||||
exhibit: { type: d2|waterfall|matrix2x2|harvey|valuechain|benchmark|issuetree|process|mermaid, ... }
|
||||
body: [ "근거 불릿" ]; evidence: [E#]
|
||||
```
|
||||
- 규칙: **one-message-per-slide**, 액션타이틀은 라벨이 아니라 takeaway.
|
||||
- exhibit 타입 2계열: **정량·개념 차트** = `consult_exhibits.py` 손제작 SVG 아키타입(워터폴/2x2/하비볼/밸류체인/벤치마크/이슈트리/프로세스). **소프트웨어 구조·흐름·의존성 그래프** = `{type: d2, code: "...", layout: elk}` → render_consult가 **d2 CLI로 실물 SVG 산출(1급)**. Mermaid(`{type: mermaid}`)는 최후 폴백만 — 실무급 시각자료가 아니다(자제). `doc-consulting`이면 doc-visual이 처방한 C4/의존성 그림을 D2로 실물 산출(`diagram-craft` 스킬).
|
||||
4. **④ RENDER**: `python3 .claude/hooks/render_consult.py <종합>.report.yaml --outdir <wf>/deliverables --marp`
|
||||
→ `-report.md`(문서) + `-deck.md`(Marp) + `-deck.html`(오프라인 발표) + `-deck.pptx/.pdf`(marp). exhibit SVG는 `img/`.
|
||||
- **렌더 열화 확인**: stdout 마지막 줄 `RENDER_STATUS: OK|DEGRADED`와 `<stem>-render.json`(status/degraded_exhibits)를 확인한다. `DEGRADED`면 d2/mermaid/exhibit 렌더가 실패해 **코드-텍스트 폴백 SVG**로 대체된 것 — 발표 전 렌더러(d2/mmdc CLI)를 설치하거나 exhibit 타입을 바꿔 재렌더한다. degraded를 성공으로 취급하지 않는다.
|
||||
- **발표·게시 산출이면 `--strict` 추가**: `render_consult.py ... --marp --strict` — degraded면 **비영점 종료**로 하드 게이트(#16). 초안 미리보기는 기본(exit 0 + 마커)로, 최종 발표물은 `--strict`로 폴백 없는 실물 렌더를 강제한다.
|
||||
5. **⑤ 게이트/보고**: `validate_report`(종합=synthesis 게이트) · `render_report`(INDEX) · Slack **스레드**(부모=lead 종합, 답글=분과별 개별 판정).
|
||||
|
||||
## 산출/handoff
|
||||
- `completion-records/<wf>/<lead-stamp>.report.yaml`(종합) + 분과 보고서들 + `deliverables/*-report.md`·`*-deck.{html,pptx,pdf}` + `*-render.json`(렌더 상태).
|
||||
- **다음**: 권고가 결정으로 가면 `/decide`(승인) 또는 설계로 `/design`. 컨설팅은 제안까지 — 최종 결정은 사람/CEO.
|
||||
|
||||
## 규칙
|
||||
- lead 없이 분과만 돌리지 않는다(프레임 없는 fan-out 금지). 분과는 자기 관점만 — 종합·최종결정은 lead/사람.
|
||||
- **engagement 경로를 섞지 않는다**: 문서 엔게이지먼트는 doc-family(doc-lead + doc-writer/ia/visual/edu)만, 비즈니스는 consult-family(consult-em + strat/ops/org/digital/fin)만. 표에서 바인딩된 `${lead}`/`${workers}` 밖으로 나가지 않는다.
|
||||
- 종합은 요약으로 dissent를 죽이지 않는다(synthesis-rehydration). 근거 없는 confidence:High 금지, source-uri 실존.
|
||||
- 컨설팅은 LENS-ADVISORY(외부·독립) — 사내 전략분석(FAM-STRATEGY)·최종 방향결정(FAM-CEO)과 구분. external side-effect 기본 금지.
|
||||
- 도해는 실무 시각문법(Zelazny/McKinsey: 단일 강조색·직접라벨·zero-baseline)을 렌더러가 강제. 소프트웨어 구조·흐름은 **D2 우선**(diagram-craft 스킬), Mermaid는 최후 폴백만 — 실무급 시각자료가 아니다.
|
||||
- 렌더 열화(degraded)를 조용히 성공으로 처리하지 않는다: render_consult의 `RENDER_STATUS`/`*-render.json`/폴백 SVG의 `ORGOS-RENDER-DEGRADED` 마커로 감지·보고.
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
description: C-Level이 discovery의 근거·선택지를 읽고 하나로 수렴(converge)해 방향을 정한다. cascade 2단계(DECIDE).
|
||||
---
|
||||
|
||||
당신은 Orchestrator다. **DECIDE phase (workflow-stage = `decide`)** — `/ground`(discovery)가 접지한 **근거 + option-set**을 의사결정권자층이 읽고 **하나로 수렴(converge)** 한다: 방향·트레이드오프·go/no-go. **근거를 새로 만들지 않는다**(그건 GROUND). divergent fan-out = 각 C-Level이 렌즈별로 옵션을 평가 → CEO가 하나로 수렴.
|
||||
입력: `/ground` 산출 **grounding-evidence + option-set**(인자, `--workflow <wf>`). **반드시 must-read.** (근거·선택지가 입력이다.)
|
||||
|
||||
## 언제
|
||||
tier=heavy 전략 결정(신규 제품/수익/방향), 또는 발산된 option-set에서 하나로 수렴해야 할 때. C-Level은 '예비'가 아니라 **수렴 결정층**이다.
|
||||
|
||||
## 상태엔진 게이트(진입) — discovery→decide 선행조건 강제
|
||||
1. **guard(진입 게이트):** `python3 .claude/hooks/state_engine.py guard --workflow <wf> --to decide`.
|
||||
- 이 게이트는 `discovery→decide`의 선행조건 = **grounding-evidence-present + option-set-present(≥2)** 를 강제한다. **exit 2면 진행하지 않는다** — 근거·선택지 없이 결정 금지 → `/ground`로 되돌리는 **BlockedReport**(미충족 사유 포함). exit 0이면 진행.
|
||||
- (option-set이 아직 없으면 `/ground`를 먼저 완료하라는 신호다 — anchoring 방지의 핵심.)
|
||||
- exit 0이면 `state_engine.py enter-stage --workflow <wf> --to decide --actor OPS-ORCH`로
|
||||
`decide.running`을 연 뒤 작업한다.
|
||||
|
||||
## 절차
|
||||
2. **pre-work**: `/ground`의 grounding-evidence + option-set + `slack_inbox.py` + `report_tags.py --tag <주제>`를 must-read.
|
||||
3. **fan-out(divergent) = per-lens 옵션 평가**: family는 `resolve-family`로 concrete role list를 고르는 metadata일 뿐 spawn 대상이 아니다. Orchestrator가 concrete C-Level 역할을 각각 격리 호출한다.
|
||||
- **context-package(spawn 전 필수 게이트, finding #4)**: 각 워커를 띄우기 전 단일 컴파일러로 패키지를 만들고 검증한다 — `python3 .claude/hooks/context_package.py --compile --workflow <wf> --task <task> --role <role> --mode divergent --tier <tier> [--lens <LENS>] [--target-repo <repo>]`로 발급 → 스켈레톤 placeholder(objective·allowed-tools·task-boundaries·must-read[option-set 포함]·non-goals·target-repo·acceptance-tests·evidence-plan)를 채움 → `python3 .claude/hooks/context_package.py <pkg>`가 **exit 0**일 때만 spawn(누락/빈 필드/위장 placeholder면 금지 — finding P0-2). **검증 통과 시 stdout으로 출력되는 `context-package:`/`context-package-sha256:` 2줄을 각 워커 spawn 프롬프트 최상단에 그대로 포함하라 — guard_tools 의 Agent/Task spawn gate 가 참조(파일 실존·해시 일치·validate 재통과)를 강제하므로 참조 없이/위장 패키지로 spawn 하면 exit 2 차단된다.** **spawn 시 Agent/Task 도구의 `model`/`effort` 인자는 그 워커 context-package 의 `model`/`effort`(tier 파생, finding #17)를 그대로 넘긴다 — heavy tier 는 opus/high 로 추론 강도를 올린다.** 필드 정의·규칙은 `org-os/06-agent-work/context-package-spec.yaml`. objective/boundaries 즉석 추론 금지.
|
||||
- `exec-cpo`(제품가치·고객문제) · `exec-cfo`(비용·ROI·자본효율) · `exec-cto`(기술 타당성·안정성·moat) · `exec-coo`(운영 실행성) · 제품-기술 충돌 시 `exec-cpto`.
|
||||
- 각자 자기 렌즈로만 **옵션을 평가·순위** → 불변 경로(`new_report.py --workflow <wf> --role <role>`)에 `tags:[<주제>,decide]` 달아 보고서 작성 → 경로+BLUF 반환.
|
||||
4. **종합(converge)**: `EXEC-CEO`가 하위 보고서를 **전부 읽고** 합의·충돌 보존한 **ExecutiveDecisionPacket**을 쓴다. `OPS-ORCH`는 단계 집행·제출만 한다. standard/heavy payload에는 `selected-option-id`, `evaluation-criteria`, 2개 이상의 `option-evaluations`(각 scores+evidence-refs), `tradeoffs`, `dissent`, `kill-criteria`, `revisit-conditions`, `evidence-refs`가 모두 필수다. `decide-direction`의 세 step을 `method-execution`으로 결속하며, `recommendation` 한 줄만으로는 제출되지 않는다.
|
||||
5. **게이트**: `validate_report.py`(BLUF·evidence·dissent) 통과. `token_ledger.py`로 워커 토큰 적재+예산 check(초과 시 collapse 강등). `render_report.py`로 대표용 MD.
|
||||
6. **보고(Slack 스레드)**: 부모=ExecutiveDecisionPacket + 각 C-Level 개별 agent-report를 스레드 답글(report-templates slack-reporting).
|
||||
|
||||
## 산출/handoff
|
||||
- `artifact-kind: executive-decision-packet`으로 발급하고 `submit-artifact --workflow <wf> --report <path> --actor OPS-ORCH`로 등록한다. HUMAN-001(또는 계약상 decision-approver)이 `review-artifact --report <path> --decision accepted --reviewer HUMAN-001`로 **그 id+sha revision**을 승인해야 `/design` gate가 통과한다. 다른 report의 Accepted는 인정되지 않는다.
|
||||
- **stage 완료:** 정확한 ExecutiveDecisionPacket revision이 승인된 뒤 `state_engine.py complete-stage
|
||||
--workflow <wf> --actor OPS-ORCH --evidence <exec-packet.report.yaml>`로 `decide.completed`를 기록한다.
|
||||
결정 작성자와 stage 집행자는 분리되며, 집행자는 OPS-ORCH다.
|
||||
- **다음**: `/design`(승인된 결정을 설계로 전개). `/design` 진입 guard가 `decide→design`(decision-packet-accepted + evidence-grade-min)을 강제한다.
|
||||
|
||||
## 규칙
|
||||
- **근거를 새로 만들지 않는다** — discovery의 근거·option-set을 읽고 **수렴**한다. 역할 선택은 `role-selection-scorecard`·`drai-matrix`(ExecutiveDecisionPacket DRAI) 기반. 임의 선발 금지.
|
||||
- 이견 삭제 금지(합의/충돌 보존). 고위험 최종 승인은 사람(HUMAN-001). AI는 권고까지.
|
||||
- **mid-start**: 승인된 decision-packet이 이미 있으면 `/design`부터 시작 가능(engine guard가 확인).
|
||||
@@ -0,0 +1,153 @@
|
||||
---
|
||||
description: direction-input-brief(불변)를 입력으로 discovery→3안 독립발산→단일수렴(평균금지)→승자 prototype→비평 재작업 루프→finalize를 거쳐 approved-direction을 산출한다. 제품 cascade 종속 child(1회성 사이클), 모든 전이는 OPS-ORCH 집행.
|
||||
---
|
||||
|
||||
당신은 Orchestrator다. **design-direction** — 제품 cascade(`/design`)에 종속된 **child plan**이다(`execution-plans.yaml` `design-direction`). 입력은 부모 workflow `<p>`가 이미 `/decide`에서 accepted한 **product-decision** report-id `<PD>`와, 부모가 발산 이전에 **불변화(freeze)한** `direction-input-brief` 경로다. 공개 웹·신규 제품·대규모 리디자인이면 부모의 `/experience-foundation`이 이미 approved여야 하며, brief는 accepted competitive benchmark/experience blueprint/wireframe set exact ref+SHA를 포함한다. 이 IA·콘텐츠·screen purpose는 세 방향 모두 동일하다. 브리프는 여기서 만들지 않고 수정하지도 않는다(발산 이후 항목인 reference-cluster/color-palette/typography/layout-grammar/tokens/visual-metaphor가 섞여 있으면 `python3 .claude/hooks/lint_design_direction.py <brief> direction-input-brief`가 거부한다 — 발산 전 고착 방지). **모든 상태 전이는 OPS-ORCH가 집행**한다(워커·`des-director`·`des-visual`은 보고서만 생산).
|
||||
|
||||
**활성 cycle 포인터**: `design-direction-active`는 읽기 전용이며 canonical `artifact-submitted` 이벤트 순서에서 각 artifact-kind의 최신 revision을 사용한다.
|
||||
|
||||
## 0. dedup — 동일 바인딩(parent+product-decision+brief-hash) 중복 방지
|
||||
1. brief의 sha256을 계산한다(dedup·staleness 판정에 쓴다).
|
||||
2. 기존 자식 조회:
|
||||
```
|
||||
python3 .claude/hooks/state_engine.py find-child-direction --parent-workflow <p> --product-decision <PD> --direction-input-brief-sha256 <brief-sha256>
|
||||
```
|
||||
- **없음(`None`)** → 신규 cycle. 새 child workflow-id를 정한다(예: `<p>-direction-<PD 앞 8자>`, 사람이 추적 가능하면 형식은 자유 — dedup은 이름이 아니라 원장의 `parent-workflow-id`+`product-decision-id` 필드로 판정된다).
|
||||
- **있고 `stage != design-direction-approved` 이며 `stale=False`(브리프 해시 동일)** → **running**: 그 `workflow-id`로 **resume**한다 — 현재 stage에서 `guard`로 다음 스테이지 가능 여부만 확인하고 이어서 진행(처음부터 다시 밟지 않는다).
|
||||
- **있고 `stage == design-direction-approved` 이며 `stale=False`** → **approved 재사용**: 이미 승인된 방향이 있다. 새로 발산하지 않고 그 child의 approved-direction report를 그대로 반환한다(멱등).
|
||||
- **있고 `stale=True`(그 사이 브리프가 바뀜)** → 기존 child는 낡은 바인딩이다. 과거 child는 건드리지 않고(불변 이력 보존) **새 child workflow-id로 신규 cycle**을 연다.
|
||||
3. **init(신규/resume 공통, idempotent):**
|
||||
`python3 .claude/hooks/state_engine.py init --workflow <child> --plan design-direction --parent-workflow <p> --product-decision <PD> --direction-input-brief <brief-path>`
|
||||
부모 원장 실존 + `<PD>`가 부모에서 **정확히** accepted 됐는지(위조/substring 우회 불가, `_al_accepted_ids`) + brief 파일 실존을 검증한 뒤에만 원장을 만든다(위반 시 exit 1, 원장 미생성). 이미 원장이 있으면 그대로 반환(overwrite 없음). stage는 자동으로 `design-direction-intake`.
|
||||
4. **intake 완료 → discovery 진입:** `guard --workflow <child> --to design-direction-discovery`가
|
||||
parent binding과 brief lint를 통과하면 `complete-stage --workflow <child> --actor OPS-ORCH
|
||||
--to design-direction-discovery` 후 `enter-stage --workflow <child> --to design-direction-discovery
|
||||
--actor OPS-ORCH`를 실행한다.
|
||||
|
||||
## 0.5 pre-direction — DES-PROD 제품/UX 프레이밍 (frame-divergence 선행 input, **필수**)
|
||||
> **왜 이 스텝이 있나(F3 fix, 2026-07-16 실측):** §1 discovery의 method인 `DES-DIRECTOR/frame-divergence` 계약의 `required-inputs`는 **DES-PROD/`pre-direction` 이 same-workflow Accepted 로 산출한 `direction-input-brief`** 를 요구한다(`org-os/00-role-registry/role-working-methods/design.yaml`, 둘 다 active). 이 스텝을 건너뛰면 §1의 `des-director` spawn이 `context_package.py` handoff 게이트에서 `handoff input:direction-input-brief 부재`로 **hard block** 된다(과거엔 이 스텝이 문서에 없어 사이클이 첫 spawn에서 막혔다). 브리프 **파일**은 부모 `/design`이 동결하지만, 계약이 요구하는 **Accepted upstream 산출물**은 여기서 DES-PROD가 만든다 — 제품/UX 프레이밍이 비주얼 발산 프레이밍보다 앞서는 더 풍부한 흐름이다.
|
||||
|
||||
`des-prod`(role-id DES-PROD, method-id `pre-direction`)를 context-package로 spawn(mode=converge, must-read=direction-input-brief + 부모 product-decision, task-boundaries에 **brief 수정 금지**·**비주얼 해법 지정 금지**). DES-PROD는 동결 브리프를 **분석·정당화**(수정 아님)하여, 대표화면이 왜 signature moment인지와 3안이 두고 갈라질 `divergence-axes` 후보(≥2, tension만 — 구체 팔레트/타이포/레이아웃/메타포 금지)를 낸다. 이 리포트의 primary-artifact 는 동결 브리프.
|
||||
- `new_report.py --workflow <child> --role DES-PROD --stub --artifact-kind pre-direction-framing
|
||||
--stage design-direction-discovery`로 typed envelope를 발급해 채운다(report-header BLUF 필수).
|
||||
- 등재: `artifact-kind: pre-direction-framing`으로 `submit-artifact --actor OPS-ORCH`.
|
||||
- **수용**: producer DES-PROD와 다른 DES-DIRECTOR가 `review-artifact --decision accepted --reviewer DES-DIRECTOR`로 정확한 revision을 승인한다.
|
||||
- 이 뒤 §1의 `des-director` context-package 검증이 통과한다(handoff input 충족). **context_package `--role` 은 소문자 카드명**(`des-prod`/`des-director`)으로 넘긴다 — 카드 파일명과 case-verbatim 일치해야 함(F2).
|
||||
|
||||
## 1. design-direction-discovery — 불변 brief 분석 + 발산 영역 계약
|
||||
`des-director`(DES-DIRECTOR)를 context-package로 spawn(mode=converge, must-read=direction-input-brief만 — 다른 방향 자료 없음, task-boundaries에 **brief 수정 금지**를 명시). direction-input-brief를 **분석만**(수정 아님) 하여 findings·constraints-restated·opportunity-notes를 낸다. 이때 브리프의 `representative-screen-requirement`를 구체 화면 하나(id/kind/description, kind ∈ first-entry\|core-task\|signature-moment)로 못박는다 — 다음 divergence의 3안이 전부 이 화면을 구현한다.
|
||||
- `new_report.py --workflow <child> --role DES-DIRECTOR --stub --artifact-kind direction-discovery
|
||||
--stage design-direction-discovery`로 envelope를 발급하고 payload에 필수 필드를 쓴다.
|
||||
- 린트: `python3 .claude/hooks/lint_design_direction.py <path> direction-discovery`(hard fail 0).
|
||||
- 등재: `artifact-kind: direction-discovery`로 `submit-artifact --actor OPS-ORCH`.
|
||||
- 이어서 DES-DIRECTOR가 **별도 `divergence-charter`**를 만든다. `direction-set`이라는 이름을 여기서
|
||||
쓰지 않는다 — charter는 작업 전 지시서이고 direction-set은 작업 후 결과 묶음이다. charter는 정확히
|
||||
3개 방향에 대해 design-question·layout-topology·navigation-model·typography-voice·imagery-strategy·
|
||||
motion-model·dominant/exclusive/forbidden-primitives를 정의하고, 모든 방향 쌍이 6개 축 중 최소 4개에서
|
||||
갈라짐을 `pairwise-separation`으로 증명한다. 팔레트 이름만 다르거나 같은 centered-card shell을 공유하면
|
||||
lint hard fail이다.
|
||||
- `new_report.py ... --artifact-kind divergence-charter --stage design-direction-discovery`로 발급 →
|
||||
`lint_design_direction.py <path> divergence-charter` → submit → producer와 다른 design-approver가 accepted.
|
||||
- 완료/진입: direction-discovery와 accepted divergence-charter가 모두 있을 때만 `complete-stage
|
||||
--to design-direction-divergence` → `enter-stage --to design-direction-divergence`.
|
||||
|
||||
## 2. design-direction-divergence — 3안 독립 발산(평균 없음)
|
||||
`des-visual`(DES-VISUAL)을 **3개의 완전히 격리된 subagent**로 띄운다. 이 workflow는 판단 난도가 높으므로
|
||||
`tier: light`를 사용할 수 없다(최소 standard). 각 run은:
|
||||
- 별도 `--task`(예: `direction-a`/`direction-b`/`direction-c`)로 `python3 .claude/hooks/context_package.py --compile --workflow <child> --task direction-a --role DES-VISUAL --mode divergent --tier <tier>`를 각각 컴파일 → `context_package.py <pkg>` exit 0 검증 → 출력된 `context-package:`/`context-package-sha256:` 2줄을 그 spawn 프롬프트 최상단에 포함(guard_tools spawn gate 강제). 이 패키지의 sha256이 그 방향의 `context-package-id`가 된다.
|
||||
- OPS-ORCH가 spawn 직전 발급하는 고유 값(예: `<child>-divergence-<task>-<UTCstamp>`)을 `producer-run-id`로 그 워커에 전달 — 워커는 자기 산출물의 `producer-run-id` 필드에 그대로 echo한다. 3개 run 모두 값이 달라야 하고(hard fail — `_directions_diverged`), 이 값들은 나중에 `/design-review`의 distinctiveness 리뷰어가 이 run과 겹치지 않는지 판별하는 기준이 된다.
|
||||
- **must-read/non-goals에 형제 방향의 산출물·경로를 명시적으로 배제**한다. must-read는 direction-input-brief + direction-discovery + 자기 id의 divergence-charter 항목이다. 다른 방향 charter 항목과 산출물은 읽지 않는다.
|
||||
- 각 run은 동일한 **의미적 signature moment**를 자기 charter의 조형 영역에서 구현한다. direction-set에는
|
||||
reference-cluster(3~6, 방향 쌍 name 중복 최대 1)·visual thesis·layout/interaction grammar·typography-token
|
||||
direction·primitive-inventory와 함께 hash-bound reference-board·full-size-preview·coded-slice를 넣는다.
|
||||
foundation 적용 작업은 direction-set top-level에 experience-blueprint/wireframe-set exact ref+SHA를,
|
||||
각 방향에 동일한 `content-contract-sha256: <wireframe-set SHA>`를 기록한다.
|
||||
- 각 방향을 같은 실제 viewport에서 **개별 full-size로 렌더**한다. 비교 이미지는 그 PNG들의 contact sheet로
|
||||
만들며, 세 앱을 좁은 iframe 세 칸에 넣어 responsive breakpoint를 왜곡하지 않는다. `preview_ui.py` receipt는
|
||||
build/DOM/contrast/focus/viewport의 **render-health 증거**일 뿐 심미 품질 증거로 부르지 않는다.
|
||||
- `new_report.py ... --artifact-kind direction-set --stage design-direction-divergence`로 발급한
|
||||
envelope payload에 `direction-cycle-id`·`representative-screen`·`directions`·`comparison-preview`를
|
||||
넣고 `divergence-charter-ref`+sha256으로 작업 전 계약에 바인딩한다. 린트는 envelope payload를 검증한다.
|
||||
- 세 안은 동일한 accepted blueprint/wireframe의 콘텐츠·IA·task/state contract를 사용한다. 바꾸는 것은 visual/interaction expression이며, 정보구조를 바꿔 서로 다른 문제를 푸는 것처럼 보이게 하지 않는다. 품질 평가는 absolute 점수만 쓰지 않고 benchmark의 table-stakes/avoid/differentiation에 대한 pairwise 비교를 기록한다.
|
||||
- **선택 전 비교감사(필수)**: 새 DES-VISUAL run을 `method-id: compare-directions`로 spawn한다. 이 run만
|
||||
sibling isolation의 예외이며 charter·3안 원본·reference board·full-size preview를 모두 읽는다. 모든 방향
|
||||
쌍을 layout/navigation/type/imagery/motion/primitives 6축으로 비교하고 4축 미만 차이, 공통 primitive shell,
|
||||
reference 과다중복을 blocking으로 기록한다. `comparative-divergence-audit` verdict는 pass|revise|re-diverge.
|
||||
foundation 적용 작업은 competitive benchmark exact ref+SHA 및 최소 3개의
|
||||
`benchmark-relative-findings`(table-stakes/avoid/differentiation 대비)를 추가한다.
|
||||
- `lint_design_direction.py --divergence-bundle <audit> <direction-set> <charter>` 통과 후 audit를 submit하고,
|
||||
producer와 다른 DES-DIRECTOR가 accepted한다. **audit pass 전에는 decision 진입 불가**다.
|
||||
- 등재 + 완료/진입: `directions-diverged`와 `divergence-audit-passed`가 모두 참일 때만
|
||||
`complete-stage --to design-direction-decision` → `enter-stage --to design-direction-decision`.
|
||||
|
||||
## 3. design-direction-decision — 단일 수렴(평균 금지)
|
||||
`des-director`(DES-DIRECTOR, synthesis-lead)가 3안의 **원본**(coded-slice·개별 report)을 전부 읽는다(synthesis-rehydration, 요약 아님). HUMAN-001의 결정은 A/B/C/NONE이다.
|
||||
- A/B/C: `selection-decision: selected`와 정확히 1개 `selected-direction-id`를 기록한다. `rejected-directions`는 나머지를 모두 덮고, `locked-invariants` ≥3, `adopted-elements` 최대 1개다.
|
||||
- NONE: `selection-decision: none-of-the-above`, selected id/locked/adopted 요소 없이 세 안을 모두 사유와 함께 reject한다. 엔진은 prototype으로 보내지 않고 `design-direction-discovery`로 되돌린다. 세 안을 평균내거나 가장 덜 나쁜 안을 고르지 않는다.
|
||||
어느 경우든 **`secondary-influence-id` 필드는 절대 넣지 않는다**. `direction-set-ref`+`direction-set-sha256`로 direction-set에 바인딩하고 `parent-workflow-id`/`product-decision-id`/`direction-input-brief-sha256`를 그대로 echo한다.
|
||||
- 린트(번들 검증): `python3 .claude/hooks/lint_design_direction.py --bundle <selected-direction-path> <direction-set-path>`.
|
||||
- **수용**: 시각 방향은 취향·브랜드 판단을 포함하므로 HUMAN-001이 `review-artifact --decision accepted
|
||||
--reviewer HUMAN-001`로 승인한다. EXEC-CPO/에이전트 단독 승인은 상태엔진이 거부한다.
|
||||
- 등재 + 완료/진입: HUMAN-001 승인 뒤 selected면 prototype으로 진행한다. none-of-the-above면
|
||||
`complete-stage --actor OPS-ORCH --to design-direction-discovery` →
|
||||
`enter-stage --to design-direction-discovery --actor OPS-ORCH`로 돌아가 brief framing을 재검토한다.
|
||||
|
||||
## 4. design-direction-prototype — 승자 핵심흐름 coded prototype
|
||||
승자 방향의 locked-invariants/adopted-elements를 그대로 지키며 DES-VISUAL+ENG-FE가 대표 화면 하나가 아니라
|
||||
**핵심 흐름(core-flow, 여러 화면/상태)**을 코드로 확장한다. 이 단계에서는 방향 전용 토큰만 쓰며,
|
||||
DES-PLATFORM의 공용 컴포넌트/시스템화는 visual-craft pass 뒤 `/design-system`에서 한다. 거친 탐색값을 일찍
|
||||
시스템화해 generic component shell로 굳히지 않는다. `revision`은 첫 사이클이면 1, critique 재작업이면 +1.
|
||||
- `python3 .claude/hooks/preview_ui.py <prototype-dir> --out <prototype-dir>/preview.png --viewports 360,768,1280 --check-css [--states "loading=...,empty=...,error=..."]` → 이 receipt가 `preview-receipt-ref`/`preview-receipt-sha256`.
|
||||
- `artifact-kind: winner-prototype`, stage=`design-direction-prototype` envelope payload에
|
||||
direction-cycle-id, selected-direction-ref+sha256, prototype-path+sha256,
|
||||
preview-receipt-ref+sha256, revision을 쓴다. 린트는 payload를 검증한다.
|
||||
- 등재 + 완료/진입: `winner-prototype` submit 후 `complete-stage --actor OPS-ORCH
|
||||
--to design-direction-critique` → `enter-stage --to design-direction-critique --actor OPS-ORCH`.
|
||||
|
||||
## 5. design-direction-critique — `/design-review` 7-lens 패널 → verdict로 라우팅
|
||||
`/design-review --workflow <child>`를 호출한다(패널 절차는 `design-review.md` 참고 — producer-run-id ≠ reviewer-run-id를 그 커맨드가 강제한다). 반환된 `design-review-panel` 아티팩트를 이 커맨드가 등재하고 전이를 라우팅한다(design-review.md 자체는 상태를 전이시키지 않는다):
|
||||
- 등재: `artifact-kind: design-review-panel`로 `submit-artifact`.
|
||||
- **verdict = pass** → `complete-stage --actor OPS-ORCH --to design-direction-finalize
|
||||
--evidence <panel-path>` → `enter-stage --to design-direction-finalize --actor OPS-ORCH`.
|
||||
- **verdict = minor-revision** → `complete-stage --actor OPS-ORCH --to design-direction-prototype
|
||||
--evidence <panel-path>` → `enter-stage --to design-direction-prototype --actor OPS-ORCH`.
|
||||
같은 cycle/selected-direction을 유지하고 revision만 올린다.
|
||||
- **verdict = concept-flaw** → `complete-stage --actor OPS-ORCH --to design-direction-divergence` →
|
||||
`enter-stage --to design-direction-divergence --actor OPS-ORCH`. 새 cycle artifact는 새 id로 submit한다.
|
||||
|
||||
## 6. design-direction-finalize — approved-direction 불변 report + 부모 원장 기록
|
||||
**`approved-direction`은 `lint_design_direction.py`에 전용 kind가 없다** — 별도 lint 커맨드로 미리 검증할 수 없으며, `state_engine.py`가 **전이 시점에** `_has_direction_approval`으로 링크·id·hash·receipt 바인딩만 검증한다. 따라서 direction-cycle-id·critique-report-refs·critique-pass-receipt·locked-invariants·approved-at 등 설계 명세의 구조적 필드 존재는 lint로 강제되지 않는다 — **operator가 수동으로 ensure해야 한다**.
|
||||
|
||||
`des-director`가 `artifact-kind: approved-direction` report를 불변 경로에 쓰고 `submit-artifact --actor OPS-ORCH`로 등록한다.
|
||||
- **수용**: producer와 다른 EXEC-CPO가 `review-artifact --decision accepted --reviewer EXEC-CPO`로 승인한다.
|
||||
- **부모 원장 기록(유일한 등록 경로)**: `python3 .claude/hooks/state_engine.py register-direction-approval --parent-workflow <p> --child-workflow <child> --report <workspace-상대경로> --report-sha256 <sha>` — child stage가 finalize/approved인지, report 파일 실존+hash 일치, 부모에 기존 충돌 approval이 없는지 전부 재검증한 뒤에만 부모 원장에 `design-direction-approval`(report-ref/report-sha256/child-workflow-id)을 기록한다(guard_tools가 직접 YAML 편집을 막으므로 이 CLI가 유일한 경로).
|
||||
- 완료/진입: exact 8점 approval 검증이 통과하면 `complete-stage --workflow <child>
|
||||
--actor OPS-ORCH --to design-direction-approved --evidence <report-path>` →
|
||||
`enter-stage --workflow <child> --to design-direction-approved --actor OPS-ORCH`, 마지막으로 terminal
|
||||
stage를 `complete-stage`로 닫는다.
|
||||
- **다음**: 부모 cascade는 `python3 .claude/hooks/state_engine.py check-direction-approved --workflow <p>`(**부모** workflow로 질의 — child로 질의하면 finalize에서도 YES가 나올 수 있어 "전이 가능"과 "최종 승인"을 혼동한다)로 승인 완료를 확인하고 `/design-system`·`/spec`으로 진행한다.
|
||||
|
||||
## 규칙 / 불변식
|
||||
- **격리**: divergence의 3 run과 critique의 7 lens는 각자 독립 context-package로 spawn한다 — 형제의 산출물을 must-read에 넣지 않는다(발산·비평의 다양성이 여기서 나온다).
|
||||
- **격리 예외**: comparative-divergence-audit만 세 방향 원본을 함께 읽는다. 비교 렌즈를 격리하면
|
||||
"다르다"는 주장을 검증할 수 없다.
|
||||
- **리뷰 veto**: critique는 7개 lens 모두 pass여야 한다. distinctiveness/visual-craft concerns,
|
||||
blocking·critical finding, unresolved-dissent는 DES-DIRECTOR synthesis가 덮을 수 없다.
|
||||
- **평균 금지**: decision은 정확히 1개를 고르거나 none-of-the-above로 전부 거절한다(`secondary-influence-id` 금지). adopted-elements는 최대 1개, locked-invariants는 침범 불가.
|
||||
- **producer ≠ reviewer**: 어떤 divergence run이 만든 방향도 critique에서 자기 자신을 심사하지 않는다(`/design-review` 참고).
|
||||
- **스크린샷 존재 ≠ 품질**: `preview_ui.py`는 반드시 **실제로 실행**해 evidence-ledger receipt(exit 0)를 남긴다 — 문서만으로 렌더를 위장할 수 없다.
|
||||
- **모든 상태 전이는 OPS-ORCH가 집행**한다(state-transition-rules.yaml의 design-direction 9개 전이 전부 `allowed-by: [OPS-ORCH]`).
|
||||
- 보고서는 불변이며 직접 원장 편집 대신 `submit-artifact`/`review-artifact`/
|
||||
`complete-stage`/`enter-stage`/`register-direction-approval`만 쓴다.
|
||||
- 권한: npm/vite/headless chrome 로컬 빌드·렌더는 허용 범위(design-system.md와 동일). slack/PR/deploy/secret/db-write 등 external side-effect는 기본 금지.
|
||||
- report-header(BLUF) 없이 종료 금지. evidence 없는 confidence:High 금지.
|
||||
- **submit은 승인과 다르다.** 다음 워커 spawn 전 producer와 다른 권한 있는 reviewer가 `review-artifact`해야 method-contract handoff gate가 통과한다.
|
||||
- **coded-slice 는 디렉터리가 아니라 파일 경로여야 한다(F6)** — `_directions_diverged`(state_engine)와 `lint_design_direction._file_sha` 가 `open(coded-slice)` 로 hash 대조하므로 디렉터리면 크래시한다. direction-set 의 각 direction 은 `coded-slice` 를 대표 파일(예: `directions/<id>/Workbench.jsx`)로, `coded-slice-sha256` 을 그 파일 해시로 채운다(워커 프롬프트에도 명시).
|
||||
- **direction-set을 OPS-ORCH가 쓰면 orchestrate 계약 full 준수가 필요하다(F7)** — envelope의
|
||||
top-level `method-execution`에 active contract hash와 required step-results를 두고, accept 전
|
||||
`validate_report.py`를 통과시킨다.
|
||||
|
||||
## 산출/handoff
|
||||
- `completion-records/<child>/approved-direction-<ts>.report.yaml`(불변) + 부모 원장 `design-direction-approval` 링크.
|
||||
- 중간 산출물: `direction-discovery`·`direction-set`·`selected-direction`·`winner-prototype`·`design-review-panel`(각 completion-records/<child>/ 경로, 통합 원장 artifacts에 등재).
|
||||
- **다음**: 승인된 방향을 입력으로 `/design-system`(코드 디자인 시스템 확정) 또는 직접 `/spec`으로 진행.
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
description: 선택된 direction의 winner-prototype을 7-lens(제품적합·사용성·차별성·시각완성도·시스템화·시장기억성·구현가능성) 패널로 감사해 DES-DIRECTOR 종합 verdict(pass/minor-revision/concept-flaw)를 산출한다. producer-run-id ≠ reviewer-run-id. `/design-direction`의 -critique 스테이지가 호출한다(단독 실행도 가능).
|
||||
---
|
||||
|
||||
당신은 Orchestrator다. **design-review** — `design-direction` child(`<child>`)의 **활성 cycle** winner-prototype을 7개 독립 렌즈로 감사하는 패널이다. 입력(인자): `--workflow <child>`. 이 커맨드 **자체는 상태를 전이시키지 않는다** — `design-review-panel` 아티팩트를 산출할 뿐이며, `record`+`transition`(verdict 라우팅)은 호출자(`/design-direction`의 -critique 스테이지)의 책임이다.
|
||||
|
||||
## 0. pre-work
|
||||
활성 cycle의 `winner-prototype`(대상 코드 + preview-receipt)과 `direction-set`(3개 방향의 `producer-run-id` 목록 — 배제용)을 읽는다. **핵심 불변식**: 이 두 산출물을 만든 divergence run의 `producer-run-id`는, 이번 패널의 어떤 `reviewer-run-id`와도 겹쳐서는 안 된다(`_critique_panel_ok`가 강제) — 방향을 만든 바로 그 실행이 자기 자신을 심사하는 것을 막는다. OPS-ORCH는 critique마다 **새** run-id를 발급한다(divergence 때 쓴 값을 재사용하지 않는다).
|
||||
|
||||
## 1. 7-lens 패널 — 각자 완전히 격리된 subagent
|
||||
각 렌즈를 독립 context-package로 spawn한다(mode=divergent, must-read=winner-prototype+selected-direction만 — 서로의 리뷰는 못 읽는다):
|
||||
`python3 .claude/hooks/context_package.py --compile --workflow <child> --task review-<lens> --role <ROLE> --mode divergent --tier <tier>` → `context_package.py <pkg>` exit 0 → 출력된 `context-package:`/`context-package-sha256:` 2줄을 spawn 프롬프트 최상단에 포함(guard_tools spawn gate 강제). 컴파일된 패키지의 sha256(또는 그 task 값)을 `reviewer-run-id`로 그 워커에 전달 — 워커는 자기 산출물의 `reviewer-run-id` 필드에 echo한다.
|
||||
|
||||
| lens | 질문 | subagent |
|
||||
|---|---|---|
|
||||
| product-fit | 고객 문제가 이해 가능한 흐름으로 해결되는가 | `des-prod`(DES-PROD) |
|
||||
| usability | 실제 사용자 행동·불편·맥락에서 사용 가능한가 | `ux-researcher`(UX-RESEARCHER) |
|
||||
| distinctiveness | 이 방향이 시각적으로 무엇을 주장하는지가 다른 안·인터넷 평균과 구별되는가 | `des-visual`(DES-VISUAL) — **반드시 새 격리 run**. divergence에서 이 방향(들)을 만든 그 run이면 안 된다 — 새 context-package·새 `reviewer-run-id`로 spawn한다 |
|
||||
| visual-craft | 타입·위계·비례·spacing·imagery·motion·optical polish가 출시 가능한 완성도인가 | `des-visual`(DES-VISUAL) — distinctiveness와 별도 새 run. annotated finding은 화면 영역/근거를 지목한다 |
|
||||
| systematizability | 디자이너·엔지니어가 반복해서 쓸 수 있는 토큰/컴포넌트로 시스템화 가능한가 | `des-platform`(DES-PLATFORM) |
|
||||
| market-memorability | 시장이 수용할 가치 언어로 번역·기억될 수 있는가 | `gtm-pmm`(GTM-PMM) |
|
||||
| implementability | 실제 프론트엔드 구현·성능·접근성 관점에서 구현 가능한가 | `eng-fe`(ENG-FE) |
|
||||
|
||||
각 리뷰어는 자기 렌즈로만 판단하고 typed `workflow-artifact` envelope를 쓴다. 개별 lens review도
|
||||
artifact-kind=`design-lens-review`를 명시하고, payload에 `reviewer-role-id`·`reviewer-run-id`·`lens`·
|
||||
`verdict`(`pass|revise|blocking`)·`findings`를 둔다. finding은 severity와 화면 영역/코드/렌더 근거를 갖는다.
|
||||
|
||||
## 2. 종합(converge) — DES-DIRECTOR
|
||||
`des-director`(DES-DIRECTOR)가 7개 리뷰 **원본**을 전부 읽는다(synthesis-rehydration — 요약이 아니라 원본, dissent 보존). 스스로를 단독 평가자로 두지 않고 트레이드오프를 드러내 하나의 `synthesis`로 수렴한다:
|
||||
- `role-id: DES-DIRECTOR`, `verdict` ∈ `pass` \| `minor-revision` \| `concept-flaw`, `unresolved-dissent`(리뷰 간 남은 이견 — 없으면 빈 리스트, 삭제 금지).
|
||||
- **verdict 판단 기준**: 개별 lens 중 `blocking`이 있으면 `concept-flaw`, `revise`가 있으면 최소
|
||||
`minor-revision`, 7개 전부 `pass`이고 unresolved-dissent가 없을 때만 `pass`다. 특히 distinctiveness와
|
||||
visual-craft는 veto lens이며 synthesis가 concerns를 비차단 의견으로 낮출 수 없다.
|
||||
|
||||
## 3. `design-review-panel` 아티팩트 조립
|
||||
`new_report.py --workflow <child> --role DES-DIRECTOR --stub --artifact-kind design-review-panel
|
||||
--stage design-direction-critique`로 발급한 envelope payload에 direction-cycle-id, target-prototype,
|
||||
preview-receipt, reviews(7개 id+sha), synthesis를 묶는다.
|
||||
|
||||
`state_engine.py`는 전이 시점에 `_critique_panel_ok`로 7개 lens의 정확한 coverage, 각 hash-bound 원본
|
||||
review와 panel 요약의 lens/run/verdict 일치, producer/reviewer 분리, 모든 개별 verdict=pass,
|
||||
blocking/critical finding 부재, unresolved-dissent=[]를 검증한다. synthesis 문자열만 `pass`로 쓰는 우회는 막힌다.
|
||||
|
||||
## handoff
|
||||
최종 메시지 = `design-review-panel` 경로 + `synthesis.verdict` + 1줄 bottom-line. 상태 변경은 하지
|
||||
않는다. 호출자가 `submit-artifact`한 뒤 verdict에 따라 `complete-stage --to ...`와 `enter-stage`를
|
||||
호출한다.
|
||||
|
||||
## 규칙
|
||||
- 7 렌즈 전원 독립 spawn(fan-out) — 서로의 결론을 못 읽는다. 종합만 DES-DIRECTOR가 원본 재적재로 한다.
|
||||
- producer-run-id ≠ reviewer-run-id는 자기신고가 아니라 `state_engine`이 direction-set의 실제 `producer-run-id` 집합과 대조해 강제한다 — 위조/재사용은 전이 시점에 fail-closed로 거부된다.
|
||||
- report-header(BLUF) 없이 종료 금지. evidence 없는 confidence:High 금지. external side-effect(slack/PR/deploy 등) 기본 금지.
|
||||
- **mid-start 아님**: 이 커맨드는 매 -critique 호출마다 7 렌즈를 새로 돈다(과거 패널 재사용 금지 — 프로토타입이 바뀌면 판단도 새로 나와야 한다).
|
||||
@@ -0,0 +1,83 @@
|
||||
---
|
||||
description: 기존 프로젝트를 먼저 discovery하고 reuse/adapt/create를 판단한 뒤, design-brief(제약층)에서 코드 디자인 시스템+화면을 만들고 headless chrome으로 실제 UI를 렌더·품질검증한다. Figma 불필요·rate-limit 없음.
|
||||
---
|
||||
|
||||
당신은 Orchestrator다. **DESIGN-SYSTEM** — 상위 제약(design-brief)에서 **코드 디자인 시스템 + 화면 + 실제 UI 미리보기·품질검증**을 산출한다.
|
||||
입력(인자): 주제/제품 + 대상 디렉터리(기본 `design-system/`). 예: `/design-system <프로젝트> 개발자 콘솔 · dir=design-system`.
|
||||
|
||||
**층 관계(중요)**: design-brief=제약(무엇을), design-craft skill=방법(어떻게), **디자인 시스템=코드로 굳힌 tokens+컴포넌트(재사용 실체)**, 프론트 코드=매체. DESIGN.md·skill의 대체가 아니라 완성이다.
|
||||
|
||||
조직 정본은 `org-os/08-design/`이다. `generated/DESIGN.md`는 그 정본에서 생성된 도구 어댑터일 뿐이며 제품 전략·IA·와이어프레임을 대신하지 않는다. 프로젝트는 전체 정본을 복사하지 않고 selected release exact ref/SHA + component subset + 명시적 delta만 `ui-design.design-system-bindings`에 연결한다.
|
||||
|
||||
**대원칙: 스택을 못박지 않는다. discovery가 정한다.** 기존 프로젝트가 있으면 그 stack·토큰·컴포넌트를 **먼저 재사용**한다. 스택은 *고정값*이 아니라 **preset(선택지)**다 — 그린필드일 때만 `greenfield-react` 프리셋을 쓴다. 예전처럼 React+CSS+Vite를 전사 기본으로 강제하면, 이미 Vue/Tailwind/디자인시스템/브랜드가 있는 프로젝트를 무시하고 밀도·컨벤션이 안 맞는 화면을 찍어낸다.
|
||||
|
||||
## 절차
|
||||
0. **Pre-work**: `report_tags.py --tag <주제>`로 관련 과거 결정 must-read. workflow-id 정한다(`wf-<slug>`).
|
||||
|
||||
0b. **design-direction 승인 게이트(Task 13 — Blocker 10)**: `/design-system`은 `/design` 3b를 거치지 않고 **단독으로도 호출**될 수 있으므로, 여기서 다시 확인한다 — `design.md`의 선행 게이트를 우회해 곧장 이 커맨드로 들어오는 경로를 막는다. **부모 cascade workflow**(`<PARENT-cascade-wf>` — 이 design-system 작업이 속한 상위 제품 cascade. design-direction **child** workflow가 아니다)를 대상으로:
|
||||
```
|
||||
python3 .claude/hooks/state_engine.py check-direction-approved --workflow <PARENT-cascade-wf>
|
||||
```
|
||||
**부모로 질의해야 하는 이유**: `_has_direction_approval`의 parent-shape 는 child 가 `design-direction-approved` stage 까지 실제로 종료됐음을 요구한다 — child workflow-id 로 질의하면 `design-direction-finalize` 단계에서도 YES 가 나올 수 있어 "전이 가능"과 "최종 승인"을 혼동한다(`design-direction.md` 6번 참고).
|
||||
- **standard/heavy tier** + `NO`(exit 3) → **진행하지 않는다.** BlockedReport(사유: 승인된 design-direction 없음 — 먼저 `/design-direction`을 완주하거나 `/design`의 선행 게이트를 통해 진입해야 함)를 내고 종료.
|
||||
- **light tier** + `NO` → 하드 블록 아님. **경고**를 report-header risks 에 남기고, 기존에 부모 원장에 기록된 승인이 있으면(과거 cycle) 그것을 **상속**해 진행한다(없으면 승인 없이 진행 — light 는 과설계 금지 원칙상 허용).
|
||||
- `YES`(exit 0) → 정상 진행.
|
||||
- **brief-phase 요구**: 이 게이트를 통과했다는 것은 design-direction 이 이미 `finalize`(brief-phase=system-ready 로 취급)를 지났다는 뜻 — 이 커맨드는 그 승인된 방향의 locked-invariants/selected-direction 을 존중하며 시스템을 만든다(방향을 재발산하지 않는다).
|
||||
|
||||
0c. **experience + 조직 release 게이트**:
|
||||
- `python3 .claude/hooks/state_engine.py check-experience-foundation --workflow <PARENT-cascade-wf>`가 `NO`면 해당 workload가 요구하는 foundation을 먼저 완주한다.
|
||||
- `python3 .claude/hooks/compile_design_system.py --check` 후 `python3 .claude/hooks/design_registry.py --surface <surface> --state <candidate|stable>`로 필요한 최소 subset을 조회한다.
|
||||
- `org-os/08-design/releases/<version>.yaml`의 exact SHA와 release-id, component-ids, 프로젝트 delta(tokens/components)를 `ui-design.design-system-bindings`에 기록한다. release state와 project delta는 별도이며 로컬 복제를 stable 정본처럼 승격하지 않는다.
|
||||
|
||||
1. **① DISCOVERY (필수·최우선 — brief보다 먼저)**: 대상 프로젝트에 **기존 시스템이 있는지 먼저 조사**한다. 아무 것도 조사하지 않고 스택을 고르는 것은 금지.
|
||||
- **stack**: `package.json`/lockfile/설정으로 프레임워크(React/Vue/Svelte/…)·번들러(Vite/Next/…)·언어·CSS 방식(CSS변수/Tailwind/CSS-in-JS) 식별. (없으면 = greenfield)
|
||||
- **design-system**: 기존 디자인시스템/컴포넌트 라이브러리/테마 존재 여부·위치(예: `design-system/`, `packages/ui`, MUI/Chakra/자체).
|
||||
- **tokens·brand**: 기존 토큰 SoT(CSS 변수/theme 파일)·브랜드 색·타이포·로고·간격 규율.
|
||||
- **components**: 재사용 가능한 기존 컴포넌트 인벤토리(무엇이 이미 있나 → 다시 만들지 말 것).
|
||||
- **data-density**: 데이터 밀도(대시보드/테이블 과밀 vs 마케팅/저밀도) — 토큰·레이아웃 결정에 직결.
|
||||
- 산출: discovery 노트를 `design-brief.yaml`의 `existing-system`(있으면)에 기록.
|
||||
|
||||
2. **② 판단: reuse / adapt / create** (근거를 `design-brief.yaml`의 `stack-decision`에):
|
||||
- **reuse** — 적합한 기존 디자인시스템/토큰/컴포넌트가 있으면 **그것을 소비**한다. 새 시스템을 만들지 않는다. 대상 디렉터리 대신 기존 컴포넌트·토큰 위에서 화면을 조립.
|
||||
- **adapt** — 부분적 시스템(토큰만/일부 컴포넌트)이면 **그 컨벤션 안에서 확장**한다. 새 축을 함부로 도입하지 않는다.
|
||||
- **create** — 기존 시스템이 없거나(그린필드) 부적합하면 **preset을 골라** 새로 만든다.
|
||||
- preset `greenfield-react`: **React + CSS 변수(tokens.css) + Vite**. (이것이 유일한 preset이 아니라 그린필드 React용 기본 preset이다.)
|
||||
- 대상 프로젝트가 이미 다른 스택이면 create여도 **그 스택의 토큰·컴포넌트 관례**를 따른다(React를 강요하지 않는다).
|
||||
|
||||
3. **③ design-brief** (skill: `design-craft` + `design-brief-spec.yaml`): 대상에 `design-brief.yaml`을 세운다 — brief(무엇/누구/달성) → references(구체 신호 3~6, "modern/clean" 금지) → tokens(값+의도+경계) → decisions(판단로직) → donts(5+). **references·tokens는 discovery 결과(기존 브랜드·데이터밀도)를 반영**한다(빈 추론층=generic). **이게 없으면 컴포넌트 생성 금지**.
|
||||
|
||||
4. **④ 구현** (판단에 따라):
|
||||
- **reuse/adapt** — 기존 토큰/컴포넌트 위에서 화면(screens)을 조립. 기존 컴포넌트에 없는 것만 그 시스템의 관례로 추가.
|
||||
- **context-package(spawn 전 필수 게이트, finding P0-2)**: `des-platform` 및 FAM-ENG-FRONTEND 후보에서 planner가 고른 concrete role을 띄우기 전 `python3 .claude/hooks/context_package.py --compile … && python3 .claude/hooks/context_package.py <pkg>`(exit 0)로 패키지를 만들고, 출력된 package path/hash를 spawn 프롬프트에 포함한다. design-brief는 must-read/shared-constraints로 동봉한다.
|
||||
- **create · greenfield-react preset** (subagent `des-platform` → 선택된 frontend concrete role):
|
||||
- `src/tokens.css` — 토큰을 CSS 변수로(값+경계 주석). `--accent`는 primary/focus 전용 등 경계 반영.
|
||||
- `src/components/*.jsx` (+`components.css`) — Button(variant)·Card·Input 등 재사용 컴포넌트, **토큰만 소비**(`var(--*)`, 하드코딩 색 금지). 컴포넌트별 판단로직·금지 반영. **`:focus-visible` 가시 표식 필수**(outline을 죽이면 box-shadow 등으로 대체).
|
||||
- `src/screens/*.jsx` — 컴포넌트를 **조립만**(새 스타일 금지). `src/preview.jsx`에 컴포넌트 갤러리 + 화면 + **상태(loading/empty/error/overflow) 데모**를 건다.
|
||||
- 근거·산출은 `.report.yaml`(report-header BLUF).
|
||||
|
||||
5. **⑤ 미리보기 + 품질 게이트(실제 UI 검증)**:
|
||||
`python3 .claude/hooks/verify_run.py --workflow <wf> --agent <role> --session <id> --category acceptance-criteria --subject ui-render-gate [--source-revision-sha256 <sha>] -- python3 .claude/hooks/preview_ui.py <dir> --out <dir>/preview.png --viewports 360,768,1280 --check-css [--states "loading=/#/loading,empty=/#/empty,error=/#/error"]`
|
||||
→ npm install→vite build→로컬서버→**렌더 검증(dump-dom)+반응형 스크린샷+정적 CSS 품질(대비·포커스)**. **Figma·rate-limit 없이** 실제 렌더.
|
||||
**중요 — 스크린샷 존재 ≠ 품질**: preview_ui는 build 성공+PNG 존재만으로 통과시키지 않는다. 앱이 런타임에 안 붙어 `#root`가 비면(빈 화면), 빌드가 빈 번들이면, WCAG 대비가 critical이면, 포커스 표식이 없으면 **게이트가 실패(비영점)**한다. 스크린샷을 읽어 육안 검증도 병행(accent 남발·하드코딩색·정렬·클리핑·데이터밀도).
|
||||
|
||||
6. **⑥ 게이트/보고**: report-header(BLUF)로 종합 + 산출 경로(패키지·PNG들·게이트 결과). 게이트 실패 시 **고치고 preview 재실행**(개선 루프).
|
||||
`python3 .claude/hooks/lint_design_system_adherence.py --ui-report <ui-design.report.yaml> --target <dir>`로 release SHA, raw color token, local component-id 중복, 조직 component의 무신고 로컬 재구현을 검사한다. 정당한 로컬 확장만 `delta.components`에 id와 사유를 남긴다. DESIGN.md 변경 검토는 `python3 .claude/hooks/compile_design_system.py --diff <project-DESIGN.md>`로 정본 대비 unified diff를 확인한다.
|
||||
|
||||
## 스택 (preset — 고정 아님)
|
||||
**기본 스택은 없다. discovery가 결정한다.**
|
||||
- 기존 프로젝트 있음 → 그 stack/tokens/components **우선 재사용(reuse/adapt)**. 다른 스택을 덮어씌우지 않는다.
|
||||
- `greenfield-react` preset(그린필드 React용): React + CSS 변수 + Vite. tokens는 `tokens.css`의 CSS 변수 = design-brief 토큰 1:1(SoT). 컴포넌트는 **`var(--*)`만 소비**(하드코딩 색 금지). Tailwind-first(토큰 갇힘)·순수HTML(컴포넌트 없음) 아님.
|
||||
- 그 외 스택(create이지만 non-React) → 해당 생태계의 토큰·컴포넌트 관례로.
|
||||
|
||||
## 규칙 / 불변식
|
||||
- **discovery-first**: 기존 stack/design-system/brand/components/data-density를 조사하지 않고 스택을 못박지 않는다. 기존 시스템이 있으면 create보다 reuse/adapt 우선.
|
||||
- design-brief 없이 컴포넌트 생성 금지(제약>묘사). references는 형용사가 아니라 구체 신호(기존 브랜드·밀도 반영).
|
||||
- 컴포넌트는 토큰만 소비 — 하드코딩 색 금지(component CSS에 hex 금지, 토큰은 tokens.css/기존 토큰 SoT에만).
|
||||
- 화면은 컴포넌트 조립 — 화면에서 새 컴포넌트 스타일을 만들지 않는다(디자인 시스템 SoT 보존).
|
||||
- **품질은 게이트를 통과해야 성립**: preview_ui의 렌더 검증·대비·포커스·반응형 게이트를 통과하지 못하면 "완료"가 아니다. 스크린샷 존재만으로 품질 주장 금지. 품질은 반복 개선 루프(build→검증→고치기)에서 나온다 — 무료 Figma와 달리 여기선 무제한.
|
||||
- report-header 없이 종료 금지. evidence 실존. external side-effect(배포/PR 등) 기본 금지 — npm/vite/chrome 로컬 빌드는 허용 범위.
|
||||
|
||||
## 산출/handoff
|
||||
- `<dir>/`(또는 reuse 시 기존 시스템 위): design-brief.yaml(+existing-system·stack-decision)·tokens·components·screens·preview + `preview.png`(들, 반응형).
|
||||
- engine 선택은 tool-neutral이다. local HTML/Stitch/Figma/v0/Framer 중 가용 adapter를 쓰되 `.claude/schemas/design-engine-output.artifact.schema.json`의 `screen-refs/editable-source/preview-url/screenshots/design-system-ref/source-provenance/verification`을 항상 내고 `validate_design_engine_output.py`로 검증한다.
|
||||
- **다음**: 실제 제품 연결은 이 컴포넌트로 화면 확장(`/build`), 또는 디자인 검토가 필요하면 이 코드를 Figma로(선택, gated).
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
description: 승인된 결정에 대한 설계를 호출한다. 아키텍처/데이터/디자인/보안 설계 직무 fan-out → 큰 설계문서. cascade 3단계(DESIGN).
|
||||
---
|
||||
|
||||
당신은 Orchestrator다. **DESIGN phase (workflow-stage = `design`)** — 수렴된 결정을 실제 **설계**로 전개한다.
|
||||
입력: `/decide` 산출 **ExecutiveDecisionPacket**(인자, `--workflow <wf>`) + (있으면) `/ground` grounding-evidence. **must-read.** 승인 안 된 결정으로 설계 시작 금지.
|
||||
|
||||
## 상태엔진 게이트(진입) — decide→design 선행조건 강제
|
||||
1. **guard(진입 게이트):** `python3 .claude/hooks/state_engine.py guard --workflow <wf> --to design`.
|
||||
- 이 게이트는 `decide→design`의 선행조건 = **decision-packet-accepted(review-state Accepted) + evidence-grade-min(tier)** 을 강제한다. **exit 2면 진행하지 않는다** — 승인 안 된 결정/증거등급 미달이면 `/decide`(및 Parent 수용)로 되돌리는 **BlockedReport**(미충족 사유). exit 0이면 진행.
|
||||
- exit 0이면 `state_engine.py enter-stage --workflow <wf> --to design --actor OPS-ORCH`로
|
||||
`design.running`을 연다.
|
||||
|
||||
## experience-foundation 선행 게이트(공개 웹·신규 제품·대규모 리디자인)
|
||||
|
||||
typed workload가 `surface-archetype: public-website` 또는 `experience-change: new-product|major-redesign`인 UI 작업이면 visual direction보다 먼저 `/experience-foundation`을 완주한다.
|
||||
|
||||
1. `state_engine.py find-child-experience --parent-workflow <wf> --product-decision <PD>`로 dedup한다.
|
||||
2. 없으면 `/experience-foundation --parent-workflow <wf> --product-decision <PD>`를 실행하고, 있으면 현재 stage부터 재개한다.
|
||||
3. `state_engine.py check-experience-foundation --workflow <wf>`가 `YES`가 될 때까지 direction-input-brief 작성과 `/design-direction` init을 시작하지 않는다. 엔진도 design-direction init/intake와 design→spec에서 다시 강제한다.
|
||||
4. direction-input-brief는 accepted benchmark/blueprint/wireframe exact ref+SHA를 포함한다. 이 IA·콘텐츠·screen contract는 이후 3개 시각 방향에서 동일하다.
|
||||
|
||||
## design-direction 선행 게이트(UI-bearing standard/heavy, Task 13 — Blocker 10: `/design-system` 직행 우회 차단)
|
||||
DESIGN stage 진입 직후 intake의 typed `workload-profile.surfaces.ui`를 확인한다. 이것만이 UI-bearing의 정본이며 `deliverable-kind`나 build-family fallback은 없다. UI=true이고 tier가 standard/heavy면 승인된 design-direction 없이 `/spec`으로 갈 수 없다.
|
||||
1. **dedup 조회(중복 cycle 금지)**: product-decision report-id `<PD>`(`/decide`가 accepted한 것)와 direction-input-brief 경로·sha256을 정하고, `python3 .claude/hooks/state_engine.py find-child-direction --parent-workflow <wf> --product-decision <PD> --direction-input-brief-sha256 <sha>`로 조회한다(JSON 또는 `null` stdout, 항상 exit 0):
|
||||
- **`null`(없음)** → 신규: experience-foundation 게이트를 확인한 뒤 새 child workflow-id로 `/design-direction --parent-workflow <wf> --product-decision <PD> --direction-input-brief <path>`를 spawn한다.
|
||||
- **있고 `stage != design-direction-approved`이며 `stale=false`** → **running**: 같은 child workflow-id로 `/design-direction`을 **resume**(처음부터 다시 밟지 않는다).
|
||||
- **있고 `stage == design-direction-approved`이며 `stale=false`** → **approved 재사용**: 이미 승인된 방향이 있다. 새로 발산하지 않고(멱등) 바로 다음(3b/스펙)으로 진행한다.
|
||||
- **있고 `stale=true`(그 사이 brief가 바뀜)** → 기존 child는 건드리지 않는다(불변 이력 보존). **새 child workflow-id로 신규 cycle**을 연다.
|
||||
2. child가 `design-direction-approved`에 도달할 때까지 — `check-direction-approved --workflow <wf>`가
|
||||
`YES`를 반환할 때까지 — 부모의 design `complete-stage`가
|
||||
`design-direction-gate-satisfied` 미충족으로 차단된다.
|
||||
|
||||
## 절차
|
||||
2. **pre-work**: 승인된 Packet + (있으면) ground grounding-evidence + `slack_inbox.py` + `report_tags.py`를 must-read. 공유 제약(scope/non-goals/glossary)을 `shared-constraints`로 동봉(발산 충돌 방지).
|
||||
3. **minimum-sufficient fan-out(divergent)**: `role_selector.py plan --profile <workload-profile.yaml>`로 owner/contributor/independent reviewer를 계산하고 선택된 concrete role만 spawn한다. family는 candidate metadata이며 card/actor가 아니다.
|
||||
- **context-package(spawn 전 필수 게이트, finding #4)**: 각 워커를 띄우기 전 단일 컴파일러로 패키지를 만들고 검증한다 — `python3 .claude/hooks/context_package.py --compile --workflow <wf> --task <task> --role <role> --mode divergent --tier <tier> [--lens <LENS>] [--target-repo <repo>]`로 발급 → 스켈레톤 placeholder(objective·allowed-tools·task-boundaries·must-read·non-goals·target-repo·acceptance-tests·evidence-plan)를 이 phase 문맥(승인 packet·ground evidence·shared-constraints 포함)으로 채움 → `python3 .claude/hooks/context_package.py <pkg>`가 **exit 0**일 때만 spawn한다. 출력된 `context-package:`/`context-package-sha256:`를 spawn 프롬프트에 포함하고 package의 model/effort를 그대로 사용한다. FAM-DESIGN 후보에서 선택된 디자인 role과 `DOC-VISUAL`은 design-brief도 채운다.
|
||||
- 후보 family: FAM-ARCHITECTURE-TECH(RFC/ADR·서비스 경계) · FAM-DESIGN(UX/UI·디자인시스템) · FAM-DATA(데이터) · FAM-SECURITY(위협모델). planner가 필요한 최소 role만 고른다.
|
||||
- 각자 자기 설계 산출물 → `tags:[<주제>,design]` 불변 보고서 → 경로+BLUF.
|
||||
3b. **UI-bearing 분기 — 디자인 파이프라인을 DESIGN에 통합(조건부)**.
|
||||
`workload-profile.payload.surfaces.ui == true`일 때만 코드 디자인 시스템 서브파이프라인을 돈다.
|
||||
family 선택 결과로 UI 여부를 다시 추론하지 않는다. `/design-system` 절차: ①승인된 experience blueprint/wireframes 확인 → ②조직 design release exact attach → ③프로젝트 discovery →
|
||||
④reuse/adapt/create 판단 → ⑤design-brief → ⑥tokens/components/screens → ⑦ `preview_ui` 품질 gate.
|
||||
- 산출물을 `artifact-kind: ui-design` 또는 `approved-design-direction`으로 발급해 `submit-artifact`한다. `ui-design`은 product-quality-auditor, 전체 아키텍처는 architecture-auditor, API 설계는 technical-accuracy-auditor, 위협모델은 security-auditor가 exact revision을 리뷰한다.
|
||||
- **게이팅 불변식(엔진 강제)**: `/design-system` 파이프라인이 제출한 canonical `artifact-kind: ui-design`은 acceptance_log에 accepted여도 **evidence-ledger에 통과한 `preview_ui` receipt(exit 0, `--contrast-only` 단독 아님)가 있어야** `spec→build`의 `must-read-designs-accepted`를 충족한다 — 렌더된 적 없는 산문만으로 프론트 BUILD를 여는 것을 `state_engine`이 차단한다. preview_ui를 **실제로 돌려** receipt를 남겨라.
|
||||
- **non-UI 워크플로**(`workload-profile.payload.surfaces.ui == false`)는 ui-design을 요구하지 않는다(과설계 금지). UX/화면이 없으면 이 분기를 건너뛴다.
|
||||
4. **종합(큰 설계문서)**: `ARCH-SOLUTION`이 structured projection을 먼저 읽고, standard에서는 충돌·dissent·저신뢰만 원문 확장하며 heavy에서는 전 원문을 읽어 **overall-design**을 작성한다. `source-artifact-refs`는 exact id+sha256을 담고 `conflicts`를 보존한다.
|
||||
5. **게이트/보고**: validate_report·token_ledger·render_report + Slack 스레드.
|
||||
|
||||
## 산출/handoff
|
||||
- 각 산출물은 contract의 artifact-kind(`overall-design`, 조건부 `api-design|data-model|threat-model|ui-design|approved-design-direction`)로 각각 submit/review한다. 모든 payload는 승인된 최신
|
||||
ExecutiveDecisionPacket의 `basis-artifact-id`와 `basis-artifact-sha256`을 동일하게 담는다.
|
||||
`design-accepted`는 required bundle 전체가 latest effective Accepted이고 같은 decision revision에
|
||||
결속될 때만 참이다. 동시에 필요한 계약 쌍(`overall-design↔api-design|data-model|threat-model`,
|
||||
`approved-design-direction↔ui-design`)은 별도 reviewer가 양쪽 exact id+sha와 계약 dimensions를 담은
|
||||
`compatibility-review(verdict: Passed)`를 제출해야 번들 승인이 성립한다.
|
||||
- **stage 완료:** workload-profile에서 계산한 required design bundle 전체가 exact revision으로
|
||||
Accepted된 뒤 `complete-stage --workflow <wf> --actor OPS-ORCH --evidence <design.report.yaml>`를
|
||||
실행한다. 설계 판단자와 stage 집행자를 분리한다.
|
||||
- **다음**: `/spec`(설계 기반 세부 기능 명세). `/spec` 진입 guard가 `design→spec`(design-accepted **+** UI-bearing standard/heavy면 `design-direction-gate-satisfied`)을 강제한다 — 위 design-direction 선행 게이트를 통과하지 못했으면 여기서 다시 막힌다.
|
||||
|
||||
## 규칙
|
||||
- 설계는 하나로 억지 병합하지 않는다 — 조금씩 달라도 상위가 원본 읽고 종합(synthesis-rehydration).
|
||||
- `workflow-contracts.yaml`의 workload-profile 조건부 design/spec bundle을 갖춘다(다음 BUILD의 선행조건이며 엔진의 `must-read-designs-accepted` 게이트가 이를 강제한다). **UI-bearing이면 `ui-design`이 포함되며 실제 `preview_ui` 렌더 receipt가 필수다** — 스크린샷 존재 ≠ 품질, 산문 ≠ UI 설계.
|
||||
- 결정/구현은 공식 문서·표준·1차 자료 근거(WebFetch/WebSearch/context7).
|
||||
- **mid-start**: 설계가 이미 Accepted면 `/spec`부터 시작 가능(engine guard가 확인).
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
description: 하네스 실행 무결성 preflight 점검(orgos doctor) — 설정·hook 배선·의존성·workspace·참조 무결성.
|
||||
---
|
||||
|
||||
당신은 실행 전 하네스가 실제로 "켜져" 있는지 점검한다.
|
||||
|
||||
## 절차
|
||||
1. 다음을 실행한다:
|
||||
```bash
|
||||
python3 .claude/hooks/doctor.py
|
||||
```
|
||||
2. 출력의 섹션별 `[ OK ]/[WARN]/[FAIL]`을 읽는다. 종료코드가 0이 아니면(=FAIL 존재) **먼저 고친다**.
|
||||
3. 점검 항목(spec 2026-07-10-p0-execution-integrity, C7):
|
||||
- `.claude/settings.json` 존재 + hook 배선이 C7 배선표와 일치(PreToolUse/PostToolUse/SubagentStart/SubagentStop/Stop).
|
||||
- 배선이 참조하는 hook 스크립트 실존(부재 = 형제 WP 진행 중 → WARN).
|
||||
- python3 + pyyaml.
|
||||
- workspace 해석(ORGOS_WORKSPACE 또는 `.orgos-workspace`).
|
||||
- `lint_refs.py`가 있으면 커맨드→agent 참조 무결성까지.
|
||||
|
||||
## 규칙
|
||||
- FAIL이 있으면 실행 흐름(/plan-wave, /run-wave, cascade)을 시작하기 전에 해소한다.
|
||||
- WARN은 대개 병렬 WP가 스크립트를 아직 만들지 않은 상태다 — 배선 자체는 유효하다.
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
description: 공개 웹·신규 제품·대규모 리디자인에서 경쟁 경험 근거→경험 전략→IA blueprint→무채색 wireframe을 승인하는 design-direction 선행 child workflow.
|
||||
---
|
||||
|
||||
당신은 concrete executor `OPS-ORCH`다. 이 커맨드는 부모 cascade의 승인된 product decision에 종속된 `experience-foundation` child plan을 실행한다. 시각 방향·색·폰트·그림자·메타포를 결정하지 않는다.
|
||||
|
||||
입력: `--parent-workflow <PARENT> --product-decision <PD> [--workflow <CHILD>]`.
|
||||
|
||||
## 시작과 중복 방지
|
||||
|
||||
1. `state_engine.py find-child-experience --parent-workflow <PARENT> --product-decision <PD>`를 호출한다.
|
||||
2. `null`이면 `state_engine.py init-workflow --workflow <CHILD> --plan experience-foundation --parent-workflow <PARENT> --product-decision <PD> --tier <tier>`로 만든다. 기존 child가 있으면 현재 stage부터 재개한다.
|
||||
3. 모든 산출물은 `workflow-artifact` envelope, child workflow-id, 현재 stage, exact SHA 참조를 사용한다. 생산자와 reviewer는 달라야 한다.
|
||||
|
||||
## 1. Competitive experience benchmark
|
||||
|
||||
`GTM-CI`가 owner, `STR-ANALYST`가 보조한다. `competitive-experience-benchmark`에는 named reference 최소 5개, direct/adjacent/substitute 중 최소 2개 class, 실제 URL, 365일 이내 캡처, desktop+mobile screenshot exact hash, 핵심 flow, IA, interaction, content strategy, evidence-bound strengths/weaknesses를 넣는다. 종합은 `table-stakes/adopt/adapt/avoid/differentiation-opportunities/unresolved-questions`로 분리하고 `no-copy-attestation: true`를 선언한다. category 이름만 나열하거나 형용사만 쓰면 제출하지 않는다.
|
||||
|
||||
`submit-artifact` 후 `product-quality-auditor`가 exact revision을 Accepted해야 `experience-benchmark → experience-strategy`가 열린다.
|
||||
|
||||
## 2. Experience strategy decision
|
||||
|
||||
`EXEC-CPO`가 benchmark 원문을 읽고 `experience-strategy`를 작성한다. experience thesis, target users, JTBD, value proposition, differentiation, message hierarchy, success metrics와 benchmark exact ref/SHA를 포함한다. `decision: proceed`만 후보가 된다. `EXEC-CEO` 또는 `HUMAN-001`이 exact revision을 Accepted한다.
|
||||
|
||||
그 exact strategy revision을 기준으로 `EXEC-CTO` 또는 `EXEC-CPTO`가 `experience-technical-feasibility`를, `EXEC-COO`가 `experience-operational-feasibility`를 독립 작성한다. 두 보고서는 strategy ref/SHA, 부모/product decision, 명시적 제약·리스크·완화와 `verdict: feasible|revise|blocked`를 포함한다. 둘 다 서로 다른 decision approver에게 exact Accepted되고 verdict가 `feasible`일 때만 information architecture로 이동한다. C-Level은 시각 해법을 정하지 않으며 지속 가능한 기술·운영 경계만 검증한다.
|
||||
|
||||
## 3. Information architecture / experience blueprint
|
||||
|
||||
`DOC-IA` owner와 `DES-PROD`, 필요 시 `DOC-WRITER`·`DOC-EDU`가 같은 strategy를 읽는다. `experience-blueprint`에 strategy+benchmark exact ref/SHA, content model, page inventory/sitemap, navigation model, message hierarchy, task flows, default/loading/empty/error/partial/completed state matrix, responsive priorities, accessibility intent, metrics를 넣는다. `product-quality-auditor`가 exact revision을 Accepted한다.
|
||||
|
||||
## 4. Wireframes
|
||||
|
||||
`DES-PROD`가 blueprint의 핵심 screen/section을 무채색 구조로 만든다. `wireframe-set`은 blueprint exact ref/SHA와 각 화면의 목적·primary action·content priority·desktop/mobile·states, 그리고 information scent/task completion/cognitive load/responsive hierarchy 검증을 포함한다. `art-direction-deferred: true`여야 하며 color palette, typography, shadows, visual metaphor를 넣지 않는다. `design-approver`가 exact revision을 Accepted한다.
|
||||
|
||||
## 5. 부모 연결과 승인
|
||||
|
||||
네 산출물이 모두 현재 exact Accepted 상태이고 cross-reference가 일치하면:
|
||||
|
||||
```bash
|
||||
python3 .claude/hooks/state_engine.py register-experience-foundation --parent-workflow <PARENT> --child-workflow <CHILD>
|
||||
python3 .claude/hooks/state_engine.py complete-stage --workflow <CHILD> --actor OPS-ORCH --to foundation-approved --evidence <wireframe-report>
|
||||
python3 .claude/hooks/state_engine.py enter-stage --workflow <CHILD> --to foundation-approved --actor OPS-ORCH
|
||||
python3 .claude/hooks/state_engine.py check-experience-foundation --workflow <PARENT>
|
||||
```
|
||||
|
||||
마지막 명령이 `YES`가 아니면 `/design-direction`을 시작하지 않는다. 부모 링크는 child와 benchmark/strategy/blueprint/wireframe의 id+path+SHA를 모두 묶으며, 최신 revision이 바뀌거나 product decision이 supersede되면 fail-closed한다.
|
||||
|
||||
## Handoff
|
||||
|
||||
`direction-input-brief`에는 승인된 benchmark, experience-blueprint, wireframe-set의 exact ref/SHA와 `org-os/08-design/releases/index.yaml`에서 고른 design-system release를 넣는다. 콘텐츠·IA·화면 목적은 이후 세 방향 모두 동일하게 유지한다.
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
description: 동일 모델·동일 요청에서 현재 하네스(A)와 experience-foundation 입력(B)의 수정 전 첫 결과를 블라인드 비교한다.
|
||||
---
|
||||
|
||||
`org-os/06-agent-work/first-draft-experiment-spec.yaml`을 정본으로 사용한다. Hyeonworks 시작 manifest는 `hyeonworks/experiments/experience-foundation-ab/experiment.yaml`이다.
|
||||
|
||||
1. `python3 .claude/hooks/first_draft_experiment.py plan <manifest>`로 준비 상태와 B arm 필수 입력을 확인한다.
|
||||
2. model-id와 request exact SHA를 동결한다. A/B 모두 같은 model-id·request를 쓰며 generation attempt는 arm별 정확히 한 번이다.
|
||||
3. A에는 foundation 입력을 주지 않는다. B에는 accepted competitive benchmark, experience blueprint, wireframe set, generated DESIGN.md, 필요한 component registry subset을 exact ref/SHA로 준다. B는 전체 사이트가 아니라 동일 대표 section/core screen만 생성한다.
|
||||
4. 첫 출력 직후 revision 0에서 desktop/mobile을 캡처한다. 수정·재생성·best-of 선택은 금지한다.
|
||||
5. arm 정보를 가린 상태로 UX-RESEARCHER 또는 DES-DIRECTOR가 `first-draft-evaluation`을 작성하고 HUMAN-001이 exact revision을 승인한다.
|
||||
6. `python3 .claude/hooks/first_draft_experiment.py validate <manifest> --require-complete` 후 `compare`한다. completed 이전에는 품질 우위 주장을 하지 않는다.
|
||||
|
||||
이 명령은 외부 모델 호출을 자동 승인하거나 비용을 발생시키지 않는다. 실제 generation command는 사용자가 선택한 실행 환경에서 동일 receipt 조건으로 두 번 수행하고 manifest에 exact output/evaluation ref+SHA를 기록한다.
|
||||
@@ -0,0 +1,55 @@
|
||||
---
|
||||
description: 문제·시장·사용자·경쟁·재무 근거를 접지하고 선택지(option-set)를 발산한다. cascade 1단계(GROUND/discovery). 결정 전.
|
||||
---
|
||||
|
||||
당신은 Orchestrator다. **GROUND phase (workflow-stage = `discovery`)** — 결정을 내리기 **전에**, 문제·시장·사용자·경쟁·재무 근거를 접지하고 **선택지(option-set, ≥2 옵션 + 각 옵션의 근거)** 를 발산한다. **결정이 아니라 발산**이다(수렴/결정은 다음 `/decide`가 한다 — anchoring 제거).
|
||||
입력: `/ceo-intake` 산출 **Decision Brief**(인자, `--workflow <wf>`). **반드시 must-read.** (결정 Packet이 아니라 intake 브리프가 입력이다.)
|
||||
|
||||
## 상태엔진 게이트(진입) — 이 단계로 전이 가능한지 먼저 확인
|
||||
1. **workflow-id 확정.** 새 workflow 생성과 intake bundle 제출은 `/ceo-intake`가 담당한다.
|
||||
`facts.decision-brief-present`나 직접 원장 편집은 gate 우회이므로 금지한다.
|
||||
2. **guard(진입 게이트):** `python3 .claude/hooks/state_engine.py guard --workflow <wf> --to discovery`.
|
||||
- **exit 2면 진행하지 않는다** — 미충족 사유를 typed `artifact-kind: blocked-report`
|
||||
payload의 blocker + resume-condition에 담아 제출하고 `block-workflow`를 호출한다.
|
||||
- exit 0이면 진행. (finding P0-1: workspace 미설정이면 엔진이 **fail-closed(exit 2)** 로 전이를 거부한다 — 조용한 우회 없음. ORGOS_WORKSPACE=<project> 를 설정하라.)
|
||||
- exit 0이면 `python3 .claude/hooks/state_engine.py enter-stage --workflow <wf> --to discovery
|
||||
--actor OPS-ORCH`로 `discovery.running`을 연 뒤 작업한다.
|
||||
|
||||
## 절차
|
||||
3. **pre-work**: Decision Brief + `slack_inbox.py` + `report_tags.py --tag <주제>`를 must-read.
|
||||
4. **minimum-sufficient fan-out(divergent)**: `FAM-*`은 실행 agent가 아니라 candidate metadata다.
|
||||
Decision Brief의 `mode`/`tier`/`candidate-families`와 Workload Profile의
|
||||
`required-capabilities`/risk/surfaces를 합친 planning profile을
|
||||
`role_selector.py plan --profile <planning-profile.yaml>`에 넣는다. 미등록 family, 이론 렌즈 부족,
|
||||
필수 capability 미커버로 `status: blocked`이면 spawn하지 않는다. family member 전체를 호출하지 않는다.
|
||||
실제 source contribution은 다음 tier 바닥을 만족해야 한다.
|
||||
|
||||
- light: 서로 다른 렌즈 최소 3개
|
||||
- standard: 서로 다른 렌즈 최소 5개이며 정확히 하나는 `LENS-CONTRARIAN`
|
||||
- heavy: candidate family에서 파생되는 all-relevant 렌즈 전부와 정확히 하나의 `LENS-CONTRARIAN`
|
||||
|
||||
- **context-package(spawn 전 필수 게이트, finding #4)**: 각 워커를 띄우기 전 단일 컴파일러로 패키지를 만들고 검증한다 — `python3 .claude/hooks/context_package.py --compile --workflow <wf> --task <task> --role <role> --mode divergent --tier <tier> [--lens <LENS>] [--target-repo <repo>]`로 발급 → 스켈레톤 placeholder(objective·allowed-tools·task-boundaries·must-read·non-goals·target-repo·acceptance-tests·evidence-plan)를 이 phase 문맥으로 채움 → `python3 .claude/hooks/context_package.py <pkg>`가 **exit 0**일 때만 spawn(누락/빈 필드/위장 placeholder면 금지 — finding P0-2). **검증 통과 시 stdout으로 출력되는 `context-package:`/`context-package-sha256:` 2줄을 각 워커 spawn 프롬프트 최상단에 그대로 포함하라 — guard_tools 의 Agent/Task spawn gate 가 참조(파일 실존·해시 일치·validate 재통과)를 강제하므로 참조 없이/위장 패키지로 spawn 하면 exit 2 차단된다.** **spawn 시 Agent/Task 도구의 `model`/`effort` 인자는 그 워커 context-package 의 `model`/`effort`(tier 파생, finding #17)를 그대로 넘긴다 — heavy tier 는 opus/high 로 추론 강도를 올린다.** 필드 정의·규칙은 `org-os/06-agent-work/context-package-spec.yaml`. objective/boundaries 즉석 추론 금지.
|
||||
discovery에서는 `--lens`가 선택이 아니라 필수다. 같은 context package/report/run을 여러 렌즈로
|
||||
재사용하지 않는다. package의 `assigned-lens`가 그 concrete role의 registry lens와 맞지 않으면 차단된다.
|
||||
- `str-analyst`(시장·포트폴리오·경쟁 지형) · `prod-pm`(제품가치·문제 실재) · `ux-researcher`(사용자 페인·맥락) · `gtm-ci`(경쟁 해자·취약점) · `gtm-revops`/`gtm-pricing`(수익모델·단가 타당성).
|
||||
- 각자는 `artifact-kind: grounding-contribution` 불변 보고서를 제출한다. payload에는
|
||||
`assigned-lens`, `producer-run-id`, `context-package-ref`, `context-package-sha256`, `findings`,
|
||||
`evidence-urls`가 필수다. 보고서 identity의 producer role을 다른 문자열로 자기신고해 대체할 수 없다.
|
||||
- Workload Profile이 `surface-archetype: public-website` 또는 `experience-change:
|
||||
new-product|major-redesign`이면 `GTM-CI`가 `artifact-kind: competitive-market-grounding`을 반드시
|
||||
제출한다. named competitor/substitute, 고객 대안, 강점/약점, 차별화 가설, evidence URL을 포함한다.
|
||||
상세 UI screenshot 비교는 별도 `/experience-foundation` 책임이며 여기서는 요구하지 않는다.
|
||||
5. **종합(option-set 발산)**: `STR-ANALYST`가 projection을 먼저 읽고, 충돌·dissent·저신뢰 항목만 원문을 확장한다(heavy는 전 원문). **problem-structure + analysis-synthesis + grounding-evidence + option-set**(≥2)을 내며 `conflicts`를 보존한다. 각 source를 `report-id`+`report-ref`+`report-sha256`+`producer-role-id`+`context-package-ref`+`context-package-sha256`+`assigned-lens`+`producer-run-id`로 exact 결속하고 `lens-coverage`를 기록한다. `OPS-ORCH`는 단계 집행·제출만 한다.
|
||||
6. **게이트/보고**: validate_report·token_ledger·render_report + Slack 스레드(부모=option-set 종합, 답글=역할별).
|
||||
|
||||
## 산출/handoff
|
||||
- `completion-records/<wf>/ground-<stamp>.report.yaml`: `role-id/producer-role-id: STR-ANALYST`, `artifact-kind: grounding-package`. payload에 **problem-structure, analysis-synthesis, evidence, options ≥2, source-contributions, lens-coverage**를 두고 `strategy-analysis`의 세 step을 `method-execution`으로 결속한다. 공개형/신규/대규모이면 `competitive-market-grounding-ref`도 exact id/ref/SHA로 결속한다. `state_engine.py submit-artifact --workflow <wf> --report <path> --actor OPS-ORCH` 한 번으로 kind·option 수·id·sha를 파생 등록한다.
|
||||
- **stage 완료:** option-set 종합을 제출한 뒤 `python3 .claude/hooks/state_engine.py complete-stage
|
||||
--workflow <wf> --actor OPS-ORCH --evidence <ground.report.yaml>`로 `discovery.completed`를 기록한다.
|
||||
`/decide`가 `decide` stage를 연다.
|
||||
- **다음**: `/decide`(discovery의 근거·option-set을 읽고 하나로 수렴). `/decide` 진입 guard가 `discovery→decide`에서 grounding/option 존재뿐 아니라 `grounding-lens-coverage-satisfied`를 강제한다. report/context/run 중복, role-lens 불일치, 다른 workflow/stage, live SHA 불일치, stale/superseded source, tier 렌즈 부족, contrarian 부재, 필수 GTM-CI 근거 중 하나라도 있으면 완료되지 않는다.
|
||||
|
||||
## 규칙
|
||||
- **결정하지 않는다 — 근거를 접지하고 선택지를 발산**한다(자기채점 금지, evidence 접지). 옵션은 최소 2개, 각각 근거를 단다.
|
||||
- 실측 데이터 없으면 E2 상한·confidence Med 이하. 근거 없는 confidence:High 금지.
|
||||
- **mid-start**: 기존 `<wf>`가 이미 discovery 이후 stage거나 intake 브리프가 있으면 그 지점부터 재개 가능(engine guard가 검증). "항상 /ceo-intake"는 **새 워크플로**에만 적용.
|
||||
@@ -0,0 +1,44 @@
|
||||
---
|
||||
description: OPS-ORCH가 Decision Brief로부터 wave를 계획한다(통합 상태원장).
|
||||
---
|
||||
|
||||
당신은 등록된 concrete role `OPS-ORCH`로서 wave를 계획한다. `FAM-ORCH`는 family metadata이며
|
||||
actor/spawn target이 아니다. **workflow-stage = `plan`.** 제품/기술/재무 결정을 새로 만들지 않는다(제안·조율만).
|
||||
입력: 최신 Decision Brief(`/ceo-intake` 산출) + `--workflow <wf>`.
|
||||
|
||||
## 상태엔진 게이트(진입) — intake→plan
|
||||
0. **workflow-id 확정 + intake**: `/ceo-intake`가 wave 원장과 typed decision-brief/workload-profile을 `submit-artifact`해야 한다. `facts.*-present` 직접 기록은 금지된다.
|
||||
1. **guard(진입 게이트):** `python3 .claude/hooks/state_engine.py guard --workflow <wf> --to plan` — `intake→plan`(decision-brief-present)을 강제한다. exit 2면 계획하지 않는다(브리프 없으면 `/ceo-intake`로). exit 0이면 진행.
|
||||
exit 0이면 `enter-stage --workflow <wf> --to plan --actor OPS-ORCH`로 `plan.running`을 연다.
|
||||
|
||||
## 절차
|
||||
2. 최신 Decision Brief의 `mode`/`tier`/`candidate-families`를 읽는다.
|
||||
3. `role-selection-scorecard.yaml`로 후보 **family**를 점수화한다(candidate-family, 0-3 rubric-anchors, tie-break). wave ≤ 5 family.
|
||||
4. **Task Ledger**(`state/<wf>/plan.md`)를 작성하고, **Progress Ledger는 통합 상태원장**(`state/<wf>/workflow.yaml`의 `progress:`)에 쓴다 — 별도 `progress.yaml`을 만들지 않는다(하나의 wf-id, 하나의 원장, #7).
|
||||
|
||||
## 산출 1: state/<wf>/plan.md (Task Ledger, 1회)
|
||||
- known-facts / facts-to-look-up / step-plan(단계별 어느 family가 무엇을 산출)
|
||||
|
||||
## 산출 2: 통합 원장 progress: (Progress Ledger — state_engine이 소유·기록)
|
||||
초기 progress를 통합 원장에 기록한다(별도 파일 아님):
|
||||
```bash
|
||||
python3 .claude/hooks/state_engine.py progress --workflow <wf> \
|
||||
--round 1 --progressing true --stall 0 \
|
||||
--next <FAM-...> \
|
||||
--set is_request_satisfied=false --set is_in_loop=false \
|
||||
--set instruction="<다음 family에 줄 지시>" \
|
||||
--set governance_limits="max_rounds=12,max_stalls=3,max_resets=2"
|
||||
```
|
||||
결과 `progress:` 스키마(통합 원장 `state/<wf>/workflow.yaml` 하위):
|
||||
`{ round, is_request_satisfied, is_in_loop, is_progress_being_made, next(=next_family), instruction, stall_count, governance_limits, wave_families }` — governance-tiers 준수.
|
||||
|
||||
## 상태엔진 완료
|
||||
- 계획을 `artifact-kind: wave-plan` envelope로 제출하고, 권한 있는 별도 reviewer가 exact revision을
|
||||
수용한다. 이후 `complete-stage --workflow <wf> --actor OPS-ORCH --evidence <wave-plan.report.yaml>`로
|
||||
`plan.completed`를 기록한다. `/run-wave`가 `run`을 연다.
|
||||
|
||||
## 규칙
|
||||
- max_stalls/max_rounds 초과 시 자동 replan + OPS-ORCH→CEO escalate(governance_limits는 원장 progress에 보존).
|
||||
- tier=heavy면 plan-signoff(사람 승인) 전 실행 wave를 Running으로 전이 금지.
|
||||
- 산출물은 report-header(BLUF)로 시작(Stop hook 강제).
|
||||
- **light 경로(저위험)**: plan-wave를 건너뛰고 바로 `/run-wave`가 `intake→run`으로 진입할 수 있다(`light` plan, execution-plans.yaml). plan-wave는 wave(다단계) 계획에만 필요하다.
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
description: Release Acceptance를 실행한다(DRAI + 인간 게이트).
|
||||
---
|
||||
|
||||
당신은 Release Acceptance를 조율한다(최종 결정권은 사람). **workflow-stage = `released`.**
|
||||
입력: `<workflow-id>`(인자, `--workflow <wf>`).
|
||||
|
||||
## 상태엔진 게이트(진입) — acceptance→released 선행조건 강제
|
||||
0. Release decision을 기록하기 전에는 `released` guard가 실패하는 것이 정상이다. 먼저 아래 절차로
|
||||
신뢰 가능한 decision event를 만든 뒤 guard를 실행한다.
|
||||
명령은 `python3 .claude/hooks/state_engine.py guard --workflow <wf> --to released`이다.
|
||||
- 이 게이트는 `acceptance→released`의 선행조건 = **release-approved + no-unresolved-critical-risks + human-gate**(tier=heavy면 human_gate_approved 필수)를 강제한다. **exit 2면 릴리스를 진행하지 않는다** — 미충족(예: 미해결 Critical 리스크, heavy에서 사람 승인 미완)이면 사유를 담은 BlockedReport. exit 0이면 진행.
|
||||
|
||||
## 절차
|
||||
1. `drai-matrix.yaml`의 `ReleaseAcceptance` DRAI를 적용한다: recommender(EXEC-VPENG, PROD-PO, QA, SRE, SEC-APPSEC), auditor(OPS-ORCH, SEC-ENGINEER), decider(EXEC-CEO, HUMAN-001).
|
||||
2. `state-transition-rules.yaml`의 `Approved → Closed` 조건 확인: release_acceptance_status=Approved, unresolved_critical_risks=false.
|
||||
3. tier(governance-tiers)를 확인: **heavy면 plan-signoff(사람 승인) 필수**. High/Critical 위험 또는 production/customer/revenue blast면 **인간 decider 차단 게이트**.
|
||||
4. 실제 신호 확인: 테스트/CI 아티팩트가 evidence(E4/E5)로 첨부됐는지(validate_report 기준).
|
||||
|
||||
## 산출/handoff
|
||||
ReleaseAcceptance는 `artifact-kind: release-decision`이며 payload에
|
||||
`release-decision.status: Approved|Held|Rejected`와 `unresolved-critical-risks: boolean`을 둔다.
|
||||
사람 decider가 `state_engine.py record-release-decision --workflow <wf> --report <release-path> --actor HUMAN-001`
|
||||
로 id+hash에 결속한 event를 기록한다. heavy는 별도의 guard-protected human signoff도 필요하다.
|
||||
- **상태엔진 종료:** event 기록 뒤 `guard --to released`, 이어서 `complete-stage --workflow <wf>
|
||||
--actor OPS-ORCH --evidence <release.report.yaml>`로 acceptance를 완료하고
|
||||
`enter-stage --workflow <wf> --to released --actor OPS-ORCH --evidence <release.report.yaml>`를 실행한다.
|
||||
실제 릴리스/후속 확인까지 끝나면 released도 `complete-stage`로 닫는다.
|
||||
- **다음**: released. 릴리스 후속 운영은 워크플로 종료 처리.
|
||||
|
||||
## 규칙
|
||||
- 근거(테스트 통과 등) 없는 릴리스 승인 금지. 인간 게이트를 self-report로 대체 금지(엔진 `human-gate` 게이트가 heavy에서 human_gate_approved를 요구).
|
||||
@@ -0,0 +1,77 @@
|
||||
---
|
||||
description: OPS-ORCH가 QA/감사 role의 exact review를 조율한다.
|
||||
---
|
||||
|
||||
당신은 concrete executor `OPS-ORCH`다. 검토 산출물 producer/reviewer는 계약에 등록된 `QA`,
|
||||
`EXEC-VPENG`, `SEC-ENGINEER` 같은 concrete role이어야 하며 family ID는 actor가 아니다.
|
||||
**workflow-stage = `verification`→`acceptance`.**
|
||||
입력: 검토 대상 `<workflow-id>`(인자, `--workflow <wf>`).
|
||||
|
||||
## 상태엔진 게이트(진입) — build→verification 선행조건 강제
|
||||
- **guard(진입 게이트):** `python3 .claude/hooks/state_engine.py guard --workflow <wf> --to verification`.
|
||||
- 이 게이트는 `build→verification`(cascade) 또는 `run→verification`(wave/light)의 선행조건 = **completion-record-present**를 강제한다. **exit 2면 검토를 시작하지 않는다** — completion-record가 없으면 `/build`(또는 `/run-wave`)를 먼저 완료하라는 신호(미충족 사유 포함 BlockedReport). exit 0이면 진행.
|
||||
- exit 0이면 `state_engine.py enter-stage --workflow <wf> --to verification --actor OPS-ORCH`로
|
||||
`verification.running`을 연다.
|
||||
|
||||
## 불변 스냅샷 + append-only 이벤트 모델 (#14)
|
||||
리포트(`.report.yaml`)는 **불변 SNAPSHOT**이다 — 검토 결과로 그 파일의 상태를 고치지 않는다.
|
||||
대신 검토 결정(Accepted/Changes-Requested/Blocked)을 **append-only 이벤트**로 남긴다
|
||||
(`acceptance_log.py` → `<workspace>/state/acceptance-events.jsonl`). 그래야 어느 스냅샷이
|
||||
최신 시도인지·무엇이 수락됐는지·무엇을 대체(supersede)했는지 감사 가능하게 추적된다.
|
||||
|
||||
## 절차
|
||||
1. 검토 대상 리포트를 특정한다: 해당 workflow/role의 **최신 시도 스냅샷**
|
||||
(`completion-records/<workflow>/<role>-*.report.yaml` 중 최신 `attempt-id`).
|
||||
이미 내려진 최신 수락 상태는 아래로 조회한다:
|
||||
```bash
|
||||
python3 .claude/hooks/acceptance_log.py latest-accepted --workflow <WF> --role <ROLE>
|
||||
```
|
||||
2. 그 리포트의 `report-header`·`evidence`를 확인한다.
|
||||
3. **evidence 검증**(validate_report와 동일 기준): source-uri 실존, grade 정합(E4/E5는 실행/실존 아티팩트), confidence:High는 E3+ 근거 필수. 새 workflow의 Passed check는 일반 Bash receipt가 아니라 아래처럼 실제 exit code를 소유하는 runner로 실행한다:
|
||||
```bash
|
||||
python3 .claude/hooks/verify_run.py \
|
||||
--workflow <WF> --agent QA --session <SESSION-ID> \
|
||||
--category test --subject <CHECK-SUBJECT> \
|
||||
--source-revision-sha256 <64-HEX-SOURCE-REVISION> -- \
|
||||
<test-runner> <test-args...>
|
||||
```
|
||||
shell 문자열이 아니라 argv를 직접 넘긴다. 출력된 `receipt-id`를 quality check에 결속한다.
|
||||
4. `state-transition-rules.yaml`의 `Submitted-for-Review → Accepted` 조건 확인: acceptance-decision-present, quality_gate_status=Passed, handoff-to 또는 closure-reason.
|
||||
5. 결정한다:
|
||||
- **Accepted**: 조건 충족.
|
||||
- **Changes-Requested**: required-changes를 구체적으로 명시.
|
||||
- **Blocked**: blocked-report + resume-condition 작성 → OPS-ORCH가 queue 등록.
|
||||
6. **정확한 revision을 권한 있는 reviewer가 검토한다**(리포트를 수정하지 말 것):
|
||||
```bash
|
||||
python3 .claude/hooks/state_engine.py review-artifact \
|
||||
--workflow <WF> --report <COMPLETION-REPORT-PATH> \
|
||||
--decision <DECISION> --reviewer QA
|
||||
```
|
||||
엔진은 등록 artifact의 id+sha256, producer, reviewer capability와 self-review=false를 검증한다.
|
||||
- 이 결정이 이전 시도를 대체하면(재작업 후 수락 등) 그 이전 스냅샷의 report-id를
|
||||
`--supersedes <PRIOR-REPORT-ID>`로 함께 넘긴다(계보 연결 → 태그 검색에서 낡은 것 자동 제외).
|
||||
- Changes-Requested/Blocked면 그 스냅샷이 rejected로 기록되어, 이후 수정본은
|
||||
`new_report.py --supersedes <이 report-id>`로 새 스냅샷을 만든다.
|
||||
|
||||
## 상태엔진 전이(종료) — 결정에 따라 stage 전진/차단
|
||||
7. QA가 `artifact-kind: quality-gate-review` 보고서를 낸다. payload에는 `quality-gate.status`,
|
||||
`blocker-open`, 검토한 completion의 `reviewed-artifact-id`/`reviewed-artifact-sha256`를 넣는다. 각 `checks[].category`는 결속한 typed receipt의 `verification_category`와 같아야 하고, Passed는 `assertion_status=passed`, `exit_code=0`이어야 한다. standard/heavy Passed receipt는 completion과 동일한 source revision hash가 필수다. 그 뒤:
|
||||
`state_engine.py record-quality-gate --workflow <wf> --review <review-path> --actor QA`.
|
||||
8. 검토 결정에 따라 stage를 완료/진입한다:
|
||||
- **Accepted**이고 quality event가 Passed/false면 `complete-stage --workflow <wf>
|
||||
--actor OPS-ORCH --evidence <review-path>`로 verification을 완료한 후
|
||||
`enter-stage --workflow <wf> --to acceptance --actor OPS-ORCH`를 실행한다.
|
||||
(`verification→acceptance` gate를 두 호출 모두 재확인한다.)
|
||||
- **Changes-Requested**: stage를 전진시키지 않는다(리포트는 rejected 이벤트로 기록, 수정본은 새 스냅샷).
|
||||
- **Blocked**: `artifact-kind: blocked-report`에 blocker + resume-condition을 작성한 뒤
|
||||
`state_engine.py block --workflow <wf> --report <path> --actor OPS-ORCH`.
|
||||
|
||||
## 산출
|
||||
`acceptance-decision`. report-header(BLUF)로 시작: bottom-line=결정, decision-needed(needed/approver), confidence(evidence 파생), risks, evidence.
|
||||
그리고 위 6단계로 **append된 acceptance-event-id** + 7단계로 수행한 **state 전이**를 산출에 명시한다(결정=이벤트, 리포트 mutation 아님).
|
||||
- **다음**(Accepted): cascade/wave는 `/release-check`(Release Acceptance + 인간 게이트)로 진행한다. light plan은 `acceptance`가 종단이므로 release-check/released 전이를 실행하지 않는다.
|
||||
|
||||
## 규칙
|
||||
- completion-record 없이 Accepted 처리 금지. self-reported quality_gate만으로 통과 금지(근거 확인 필수).
|
||||
- 리포트 스냅샷은 **불변** — 상태 변화는 `acceptance_log.py` 이벤트로만. 리포트 파일을 덮어쓰지 않는다(guard_tools가 차단).
|
||||
- 최신 수락 상태는 이벤트 원장(`latest-accepted`)이 정본 — 스냅샷 개별 파일이 아니다.
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
description: 아이디어/문제를 입력받아 GROUND→DECIDE→DESIGN→SPEC→BUILD 전 cascade를 하나로 걷는 상위 오케스트레이터. state_engine을 재사용하는 얇은 드라이버 — 사람 결정 지점에서 멈춘다(자동 승인·자동 완주 금지).
|
||||
---
|
||||
|
||||
당신은 **Cascade Orchestrator**다. 사용자는 처음에 문제/목표만 주고, **중요한 결정 지점에서만** 개입한다. 너는 전 과정을 일관되게 걷되, 스스로 새 엔진을 만들지 않고 **`state_engine`을 재사용**한다. 이것은 편의 층이자 "단계를 건너뛰지 못하게" 하는 보증이다 — 각 stage의 실제 강제(context-package spawn 게이트·validator·token/lens 게이트·상태 전이)는 그대로 작동한다.
|
||||
|
||||
입력(인자): `--workflow <wf>` (기존 워크플로 재개) **또는** 새 아이디어/문제 서술(새 워크플로 시작).
|
||||
|
||||
## 불변식 (반드시 지킨다)
|
||||
- **평행 엔진 금지**: stage 판별·전이는 오직 `state_engine.py`
|
||||
(`next`/`guard`/`complete-stage`/`enter-stage`). 상태를 직접 조작하지 않는다.
|
||||
- **사람 게이트에서 멈춘다**: `next`가 `advance.human-gate.required: true`를 주면 **정지**하고 사람 승인을 요청한다. 자동 승인·자동 완주 금지(이게 존재 이유다).
|
||||
- **stage를 건너뛰지 않는다**: 각 stage는 그 stage 커맨드 절차를 그대로 수행한다(그 산출물이 없으면 다음으로 못 간다 — 엔진이 guard로 막는다).
|
||||
- **불변 보고**: 모든 산출물은 report-header(BLUF)로 시작. 우회 금지.
|
||||
|
||||
## 절차 (루프)
|
||||
|
||||
### 0. 진입
|
||||
- 새 아이디어면 먼저 **`/ceo-intake`**를 수행해 Decision Brief(mode/tier/candidate-families) + `wf-<slug>`를 만들고 `state_engine.py init --workflow <wf> --plan cascade --tier <tier>`로 원장을 연다. 기존 `--workflow <wf>`면 그대로 재개.
|
||||
|
||||
### 1. 다음-스텝 조회 (매 라운드)
|
||||
```
|
||||
python3 .claude/hooks/state_engine.py next --workflow <wf>
|
||||
```
|
||||
반환 JSON을 읽는다:
|
||||
- `current-stage` / `current-command` — 현재 stage와 그 작업 커맨드
|
||||
- `next-stage` / `next-command` — 다음 stage와 커맨드
|
||||
- `advance.ok` — `current→next` 전이 guard 통과 여부(=현 stage 산출물이 Accepted인가)
|
||||
- `advance.reasons` — 미충족 사유(현 stage에서 무엇을 더 해야 하는지)
|
||||
- `advance.human-gate.{required,approver,what}` — 사람 결정 지점 여부
|
||||
- `terminal` — 종단(released) 도달
|
||||
|
||||
### 2. 분기
|
||||
- **`terminal: true`** → cascade 완료. 최종 요약(BLUF + 각 stage 산출물 경로 목록) 후 종료.
|
||||
- **`advance.human-gate.required: true`** → **정지.** 현 stage까지의 산출물을 종합하고 **decision-needed 보고**를 낸다:
|
||||
- BLUF: 무슨 결정이 필요한가(예: go/no-go 방향 확정, 릴리스 수용) · **승인자**(`advance.human-gate.approver`, 예: HUMAN-001) · 근거(옵션셋/기각사유/증거등급).
|
||||
- 사용자에게 승인을 요청하고 **멈춘다**. (사람이 승인하면 acceptance_log/`signoff`로 기록되고, 사용자가 `/run-cascade --workflow <wf>`를 다시 부르면 `next`가 게이트 해제를 감지해 재개한다.)
|
||||
- **`stage-status: running`** → `current-command`의 절차를 수행한다. typed artifact를
|
||||
`submit-artifact`로 제출하고 exact revision을 `review-artifact`로 수용한 뒤 그 command가
|
||||
`complete-stage`를 실행한다. 그 뒤 1번으로 돌아간다.
|
||||
- **`stage-status: completed`이고 human-gate 아님** → `advance.ok`를 확인한 뒤
|
||||
`enter-stage --workflow <wf> --to <next-stage> --actor OPS-ORCH`로 다음 stage를 `running`으로 연다.
|
||||
`advance.ok: false`면 reason을 해소할 때까지 진입하지 않는다.
|
||||
|
||||
### 3. blocker
|
||||
- 어떤 stage에서 guard가 미충족 설계·증거로 막히면 typed `artifact-kind: blocked-report`
|
||||
(blocker + resume-condition)를 제출하고 `block-workflow`로 side-state에 들어간다. 해소 증빙은
|
||||
`resume-evidence`로 제출한 뒤 `resume-workflow`로 정확한 `blocked-from` stage를 재개한다.
|
||||
|
||||
## stage↔커맨드 지도 (참고 — `next`가 알려줌)
|
||||
`intake`→`/ceo-intake` · `discovery`→`/ground` · `decide`→`/decide` · `design`→`/design` · `spec`→`/spec` · `build`→`/build` · `verification`→`/review-output` · `acceptance`→`/release-check` · `released`=cascade/wave 종단. light plan은 `acceptance` 자체가 종단이며 `/release-check`를 호출하지 않는다.
|
||||
|
||||
## 사람이 멈추는 지점 (human-gate)
|
||||
- **DECIDE go/no-go**: C-Level이 옵션·근거를 종합한 뒤 방향 확정 — 승인자 HUMAN-001(위임 시 EXEC-CEO). 오케스트레이터는 여기서 멈춘다.
|
||||
- **RELEASE 수용**: `acceptance→released`(release-approved + human-gate) — DRAI decider=사람. heavy tier는 엔진이 signoff 파일로 하드 강제.
|
||||
- **tier=heavy plan-signoff**: 실행 전 사람 승인(governance-tiers).
|
||||
- 그 외 stage는 자동으로 다음으로 흐르되, **각 전이는 엔진 guard를 통과해야만** 진행된다(산출물·증거 미충족이면 자동으로 막힘).
|
||||
|
||||
## 금지
|
||||
- 사람 게이트 자동 통과·자동 완주 금지. `signoff`/acceptance를 에이전트가 자처 금지(guard 차단).
|
||||
- state 직접 편집 금지(원장은 guard 보호) — 오직 `state_engine.py` CLI.
|
||||
- report-header 없이 종료 금지. evidence 없는 confidence:High 금지.
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
description: OPS-ORCH가 family metadata를 concrete role들로 해석해 wave를 실행한다.
|
||||
---
|
||||
|
||||
당신은 등록된 concrete executor `OPS-ORCH`로서 **통합 상태원장**(`state/<wf>/workflow.yaml`의
|
||||
`progress:`)의 `next`(=family metadata)를 실행한다. `FAM-ORCH`나 `next_family`를 actor로 쓰지 않는다.
|
||||
**workflow-stage = `run`.** 진행상태는 별도 `progress.yaml`이 아니라 이 통합 원장이 SoT다(#7).
|
||||
입력: `<workflow-id>`(인자, `--workflow <wf>`).
|
||||
|
||||
## 상태엔진 게이트(진입) — plan→run 또는 (light) intake→run
|
||||
- **guard(진입 게이트):** `python3 .claude/hooks/state_engine.py guard --workflow <wf> --to run`.
|
||||
- `/plan-wave`를 거친 wave면 `plan→run`(wave-plan-present)을 강제한다. **plan-wave 없이 바로 실행하는 light 경로**(저위험: two-way-door·single-role·고객/매출/보안 영향 없음)면 원장을 `light` plan으로 만들고(`state_engine.py init --workflow <wf> --plan light --tier light`, decision-brief 기록) `intake→run`(decision-brief-present)으로 진입한다 — 이 경량 경로를 `light` plan으로 정식화(execution-plans.yaml).
|
||||
- exit 2면 실행하지 않는다(계획/브리프 부재 → `/plan-wave` 또는 `/ceo-intake`). exit 0이면 진행.
|
||||
- exit 0이면 `enter-stage --workflow <wf> --to run --actor OPS-ORCH`로 `run.running`을 연다.
|
||||
|
||||
## 절차
|
||||
0. **작업 전 입력 수집(pre-work).** (a) 관련 Slack을 읽는다 — `mcp__slack__slack_get_channel_history`로 채널 히스토리를 받아 `slack_inbox.py --workflow <wf>`에 파이프 → `slack-inbox/<wf>.md` 생성. (b) 관련 태그의 **동료 보고서**를 찾는다 — `report_tags.py --tag <주제>`. 이 둘을 워커 must-read에 넣어, 워커가 이미 내려진 결정·요청·제약을 반영하게 한다.
|
||||
1. `python3 .claude/hooks/role_selector.py plan --profile <workload-profile.yaml>`로 concrete
|
||||
owner/contributor/independent reviewer를 계산한다. family members는 candidate pool이지 spawn list가 아니다.
|
||||
family ID 자체를 context-package의 `--role`이나 spawn target으로 넘기지 않는다. 선택된 concrete role에
|
||||
**context-package**를 **단일 컴파일러로** 만들어 전달한다:
|
||||
`python3 .claude/hooks/context_package.py --compile --workflow <wf> --task <task> --role <CONCRETE-ROLE> --mode <mode> --tier <tier> [--lens <LENS>] [--target-repo <repo>]`로 스켈레톤을 발급 → placeholder를 채운다(`mode`/`tier`/`assigned-lens` + delegation 4필드 objective/output-format/allowed-tools/task-boundaries + must-read[slack-inbox·동료 태그 보고서 포함] + `tags` + token-budget + P0 필수 workspace/target-repo/acceptance-tests/non-goals/evidence-plan). forbidden-context(secrets/PII/raw-log) 제외. **spawn 전 `python3 .claude/hooks/context_package.py <pkg>`가 exit 0(통과)** 이어야 워커를 띄운다(누락/빈 필드/위장 placeholder면 금지 — finding P0-2로 `none`/`ALL`/`unlimited`/`self-assertion` 등 sentinel 값과 미실존 must-read·가짜 역할카드도 거부한다). **검증 통과 시 validate가 `context-package:`/`context-package-sha256:` 2줄을 stdout에 출력한다 — 이 2줄을 각 워커 spawn 프롬프트 최상단에 그대로 포함해야 한다.** guard_tools 의 Agent/Task spawn gate 가 이 참조(파일 실존·해시 일치·validate 재통과)를 강제하므로, 참조 없이 또는 위장/변조 패키지로 Org OS 워커를 spawn 하면 **차단(exit 2)** 된다(helper 서브에이전트는 면제). 필드 정의·규칙은 `org-os/06-agent-work/context-package-spec.yaml`.
|
||||
2. **collaboration-default 분기**(`capability-families.yaml` + `execution-policy.yaml` fan-out-collapse-policy):
|
||||
- **collapse family**(구현·실행): 멤버 role을 1 에이전트로 통합 실행 → 단일 `.report.yaml`. 시작 전 `collaboration-map.yaml` design-to-build-contract의 must-read 설계가 Accepted인지 확인(없으면 BlockedReport).
|
||||
- **fan-out family**(판단·설계·분석·수익): planner가 고른 role만 격리 subagent로 병렬 호출한다. 각 워커는 report 경로+1줄 bottom-line을 반환한다. 종합자는 light에서 structured projection만, standard에서 projection 우선 후 충돌·dissent·저신뢰만 원문 확장, heavy에서 전 원문을 읽는다. 워커는 스스로 종합하지 않는다.
|
||||
- **오버라이드**: tier=heavy → collapse도 감사 팬아웃(≥3, 과반 반증→Blocked). tier=light&converge → fan-out도 단일 종합. context-package.`fan-out-roles` 있으면 그 role만 분리.
|
||||
- **렌즈 상한(권고 #2, 2축 모델)**: fan-out 워커 선택은 **lens 다양성 × sub-specialty 커버리지** 2축으로 본다(lens-registry `sub-specialty-axis`). 같은 lens라도 **서로 다른 sub-specialty(예: application vs system architecture, PM vs TPO)는 중복이 아니다** — distinct sub-specialty는 tier 상한까지 허용한다(전문분야를 삭제하지 않는다). 위반은 (a) 같은 lens+같은/미분화 sub-specialty를 2명 이상, 또는 (b) distinct sub-specialty 수가 tier 상한 초과일 때다(heavy는 sub-angle 분화 permissive). 선택 후 `python3 .claude/hooks/lens_cap.py --tier <t> --roles r1,r2,…`로 검증(exit 2면 진짜 중복만 줄인다).
|
||||
- **공유 제약 pre-brief(권고 #3)**: 한 phase에서 병렬 fan-out할 때, 각 워커 context-package에 승인된 ExecutiveDecisionPacket + 공통 설계제약(`shared-constraints`: 스코프/비목표/용어)을 **동봉**한다 — 발산 다양성은 유지하되 '충돌하는 결정'만 사전 정렬(Cognition).
|
||||
- **토큰 예산(권고 #1)**: 예산은 per-wave다. planner가 추정치를 예산 안에 맞추고, spawn 전 `token_ledger.py check`로 재확인한다. 초과 시 남은 fan-out을 축소하거나 tier 상향을 요청한다. 실제 usage는 SubagentStop usage observer가 자동 적재하며 수동 log는 호환 경로다.
|
||||
3. `execution-policy.yaml` 준수: **pipeline**(배리어 아님), converge는 선행 트레이스 공유·divergent는 병렬 격리.
|
||||
4. **보고서는 불변(immutable)이다 — 절대 덮어쓰지 말 것.** 각 산출물 경로는 `python3 .claude/hooks/new_report.py --workflow <wf> --role <role>`로 **새 버전 파일**을 발급받아 쓴다(`completion-records/<wf>/<role>-<UTCstamp>.report.yaml`). 재작업/수정도 새 파일로 남긴다(guard_tools가 기존 `.report.yaml` 덮어쓰기/Edit를 차단). 파일은 `report-header`(BLUF)로 시작(SoT). **대표용 MD는 `python3 .claude/hooks/render_report.py <report.yaml> [--members ...] [--type ...]`로 렌더**하고, 마지막에 `render_report.py --index`로 목차(워크플로별 append-only)를 갱신한다.
|
||||
5. **통합 원장 progress 갱신(별도 progress.yaml 아님)**: 매 라운드 `python3 .claude/hooks/state_engine.py progress --workflow <wf> --round <N> --progressing <true|false> --stall <M> --next <FAM-...> [--set is_request_satisfied=<bool>]` 로 `state/<wf>/workflow.yaml`의 `progress:`를 갱신한다.
|
||||
- 요청 미충족 & 진전 있음: stage는 계속 `run.running`이다. self-transition하지 않고 다음 round를 돈다.
|
||||
정체/상한 초과면 typed blocked-report를 제출하고 `block-workflow`로 **replan + OPS-ORCH→CEO escalate**한다.
|
||||
- 요청 충족: completion-record를 제출한 뒤 `complete-stage --workflow <wf> --actor OPS-ORCH
|
||||
--evidence <completion-record>`로 `run.completed`를 기록한다. `/review-output`이 verification을 연다.
|
||||
6. wave 종료 시 `python3 .claude/hooks/token_ledger.py dashboard`로 토큰 대시보드(`reports/TOKENS.md`)를 갱신한다(대표가 tokens/wave·cost-per-decision을 눈으로 확인).
|
||||
7. **결과 보고(Slack) — 스레드 규약(기본).** fan-out wave는 **부모=종합 결정** 1건(`notify_slack.py report <synthesis.report.yaml>`)을 승인 채널에 올리고, **각 워커의 개별 agent-report(템플릿 3)를 그 부모 메시지의 스레드 답글**(`mcp__slack__slack_reply_to_thread`)로 붙인다 — 누가 어떤 판단을 했는지 다 보이되 채널 스팸은 없다. 각 답글은 `직무·렌즈·토큰` 헤더 + BLUF + 근거/산출물 + 결정필요(승인자) + 리스크 + `cc #태그`. collapse wave는 부모 1건만.
|
||||
|
||||
## 규칙
|
||||
- report-header 없는 산출·evidence 없는 confidence:High는 수용 금지(stop_validate/validate_report가 강제 차단).
|
||||
- fan-out 종합 시 raw-chat-log/tool-trace/secrets/PII는 여전히 배제(`.report.yaml`만 재적재).
|
||||
- external side-effect(slack/PR/deploy/secret/db-write)는 기본 금지(guard_tools 강제).
|
||||
- 다음 단계 라우팅은 통합 원장 `progress.next`(=next_family)로만(별도 progress.yaml 폐지 — 하나의 wf-id·하나의 원장).
|
||||
- **역할 선택은 `role-selection-scorecard.yaml` 기반으로 한다 — Orchestrator 임의 선발 금지.** 선택 근거(candidate-family·rubric·tie-break)를 남긴다.
|
||||
- **cascade 건너뛰기 금지(`collaboration-map.yaml`).** tier=heavy 전략 결정(신규 제품/수익/방향)은 **DECIDE phase(C-Level 심의 → CEO 종합 ExecutiveDecisionPacket)를 DESIGN 워커보다 먼저** 실행한다. 승인된 Packet을 DESIGN 워커 must-read로 내려보낸다. C-Level은 '아이디어 없을 때 부르는' 예비가 아니라 **방향·트레이드오프를 정하는 결정층**이다.
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
description: 설계를 기반으로 개발용 기능 명세를 만든다. PM/아키텍트 fan-out → PRD·api-contract·수용기준. cascade 4단계(DETAIL/SPEC).
|
||||
---
|
||||
|
||||
당신은 Orchestrator다. **DETAIL/SPEC phase (workflow-stage = `spec`)** — 설계를 **구현 가능한 기능 명세**로 세분화한다.
|
||||
입력: `/design` overall-design + 도메인 설계 산출물 경로(인자, `--workflow <wf>`). **must-read.**
|
||||
|
||||
## 상태엔진 게이트(진입) — design→spec 선행조건 강제
|
||||
0. **guard(진입 게이트):** `python3 .claude/hooks/state_engine.py guard --workflow <wf> --to spec`.
|
||||
- 이 게이트는 `design→spec`의 선행조건 = **design-accepted(설계 산출물 review-state=Accepted)** 를 강제한다. **exit 2면 진행하지 않는다** — 설계 미승인이면 `/design`(및 Parent 수용)으로 되돌리는 **BlockedReport**(미충족 사유). exit 0이면 진행.
|
||||
- exit 0이면 `state_engine.py enter-stage --workflow <wf> --to spec --actor OPS-ORCH`로
|
||||
`spec.running`을 연다.
|
||||
|
||||
## 절차
|
||||
1. **pre-work**: 설계 산출물(RFC/ADR·data-model·UX·threat-model) + `slack_inbox.py` + `report_tags.py`를 must-read.
|
||||
2. **minimum-sufficient fan-out(divergent)**: family는 candidate metadata이며 `role_selector.py plan --profile <workload-profile.yaml>`가 artifact coverage와 독립 리뷰를 만족하는 concrete role만 고른다.
|
||||
- **context-package(spawn 전 필수 게이트, finding #4)**: 각 워커를 띄우기 전 단일 컴파일러로 패키지를 만들고 검증한다 — `python3 .claude/hooks/context_package.py --compile --workflow <wf> --task <task> --role <role> --mode divergent --tier <tier> [--lens <LENS>] [--target-repo <repo>]`로 발급 → 스켈레톤 placeholder(objective·allowed-tools·task-boundaries·must-read·non-goals·target-repo·acceptance-tests·evidence-plan)를 이 phase 문맥으로 채움(acceptance-tests에 이 컴포넌트의 Given/When/Then 수용기준을 접지) → `python3 .claude/hooks/context_package.py <pkg>`가 **exit 0**일 때만 spawn(누락/빈 필드/위장 placeholder면 금지 — finding P0-2). **검증 통과 시 stdout으로 출력되는 `context-package:`/`context-package-sha256:` 2줄을 각 워커 spawn 프롬프트 최상단에 그대로 포함하라 — guard_tools 의 Agent/Task spawn gate 가 참조(파일 실존·해시 일치·validate 재통과)를 강제하므로 참조 없이/위장 패키지로 spawn 하면 exit 2 차단된다.** **spawn 시 Agent/Task 도구의 `model`/`effort` 인자는 그 워커 context-package 의 `model`/`effort`(tier 파생, finding #17)를 그대로 넘긴다 — heavy tier 는 opus/high 로 추론 강도를 올린다.** 필드 정의·규칙은 `org-os/06-agent-work/context-package-spec.yaml`. objective/boundaries 즉석 추론 금지.
|
||||
- 후보 family는 FAM-PRODUCT-MGMT(PRD·수용기준)와 FAM-ARCHITECTURE-TECH(api-contract·인터페이스)이며 전원 호출하지 않는다.
|
||||
- 각자 컴포넌트별 세부 명세 → `tags:[<주제>,spec]` 불변 보고서 → 경로+BLUF.
|
||||
3. **종합(세부 구현문서)**: PM/아키텍트 lead가 projection-first로 읽고 충돌·dissent·저신뢰만 원문 확장해 통합한다(heavy는 전 원문). `conflicts` 필수.
|
||||
4. **게이트/보고**: validate_report·token_ledger·render_report + Slack 스레드.
|
||||
|
||||
## 산출/handoff
|
||||
- 각 명세는 contract의 artifact-kind(`acceptance-criteria`, 조건부 `prd|api-contract|data-contract|migration-plan`)로 submit/review한다. 모든 payload는 승인된 최신 `overall-design`의
|
||||
`basis-artifact-id`와 `basis-artifact-sha256`을 동일하게 담는다. `spec-accepted`는 required bundle
|
||||
전체가 latest effective Accepted이고 같은 design revision에 결속될 때만 참이다. PRD는
|
||||
product-quality-auditor, API 계약은 technical-accuracy-auditor, data/migration 계약은
|
||||
data-quality-auditor가 리뷰한다. 동시에 필요한 `prd↔api-contract`, `data-contract↔migration-plan`,
|
||||
`api-contract↔data-contract` 쌍은 exact id+sha `compatibility-review(verdict: Passed)`가 추가로 필요하다.
|
||||
- **stage 완료:** required spec bundle 전체가 exact revision으로 Accepted된 뒤 `state_engine.py
|
||||
complete-stage --workflow <wf> --actor OPS-ORCH --evidence <spec.report.yaml>`를 실행한다.
|
||||
- **다음**: `/build`(설계+명세+디자인 기반 구현). `/build` 진입 guard가 **핵심 게이트** `spec→build`(spec-accepted + must-read-designs-accepted)를 강제한다.
|
||||
|
||||
## 규칙
|
||||
- 명세는 설계와 정합해야 한다(설계 없는 명세 금지). 각 기능은 검증가능한 수용기준(Given/When/Then)을 갖는다.
|
||||
- api-contract·인터페이스는 구현 family가 그대로 소비할 계약이다 — 모호성 제거.
|
||||
- **mid-start**: 명세가 이미 Accepted면 `/build`부터 시작 가능(engine guard가 must-read-designs까지 확인).
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
description: 기회탐색(발산)→벤처검증(9-gate)로 opportunity-cluster와 검증된 venture-option을 산출한다. venture-bootstrap 2단계.
|
||||
---
|
||||
|
||||
당신은 Orchestrator다. **venture-bootstrap: opportunity-discovery + venture-validation.** 회사 정의 이전이므로 company-context를 강근거로 쓰지 않는다(§7.1 상한). 입력: `org-os/01-company/founder-context.yaml`(must-read), `org-os/06-agent-work/venture-option-spec.yaml`, `org-os/06-agent-work/venture-validation-map.yaml`. **모든 상태 전이는 OPS-ORCH가 집행**한다(워커·EXEC-CEO는 보고서만 생산).
|
||||
|
||||
1. **founder stage:** intake가 completed면 `guard --to founder-setup` 후 `enter-stage --to founder-setup
|
||||
--actor OPS-ORCH`를 실행한다. founder-context.yaml `status: filled`을 확인한 뒤 `complete-stage`로
|
||||
founder-setup을 완료하고, `guard --to opportunity-discovery` → `enter-stage`로 진입한다.
|
||||
2. **opportunity-discovery(발산):** `venture-validation-map.opportunity-discovery-roles.diverge` 역할 + `contrarian`(EXEC-CFO=경제구조 반증)로 **divergent** fan-out. 각 워커는 context_package로 spawn(mode=divergent, must-read=founder-context+venture-option-spec). `STR-ANALYST`가 서로 다른 payload.id의 opportunity-cluster ≥2를 산출한다(spec `opportunity-cluster.required` 충족, 중복·완전성 검사). OPS-ORCH는 제출·상태 전이만 맡고 문제/결정을 생성하지 않는다. 제품명 이전 **문제 클러스터**부터.
|
||||
3. **원장 등록:** 각 cluster를 `artifact-kind: opportunity-cluster`로 만들고 `state_engine.py submit-artifact --workflow <wf> --report <path> --actor OPS-ORCH`로 제출한다.
|
||||
4. **stage 완료/진입:** opportunity cluster 제출 후 `complete-stage --workflow <wf> --actor OPS-ORCH
|
||||
--evidence <path>`, 이어서 `enter-stage --workflow <wf> --to venture-validation --actor OPS-ORCH`.
|
||||
5. **venture-validation:** 각 옵션 × 9-gate를 `venture-validation-map.gates`의 primary/auditor로 fan-out(dissent 보존). `unknown` 허용, `kill-criteria` 필수. 산출: venture-option 보고서(spec `venture-option.required` 충족) + validation-result. `EXEC-CEO`가 두 cluster exact id+sha를 source-artifact-refs로 결속해 종합하되 상태 전이는 하지 않는다.
|
||||
6. **등록 + 수용 + 완료:** 종합을 `artifact-kind: venture-validation`으로 submit하고, producer와 다른
|
||||
`product-quality-auditor`(`EXEC-CPO`/`EXEC-CPTO`/`PROD-PO`/`QA`/`HUMAN-001`)가 exact revision을
|
||||
`review-artifact`로 승인한다. 이후 `complete-stage`로
|
||||
`venture-validation.completed`를 기록한다.
|
||||
7. **다음:** `/company-bootstrap`(venture-decision→commit→bootstrap-complete 전이는 거기서 집행).
|
||||
|
||||
산출물: `completion-records/<wf>/opportunity-clusters-*.report.yaml`, `venture-option-*.report.yaml`(불변, new_report). 모든 spawn은 context_package 컴파일러+validator를 거친다.
|
||||
Reference in New Issue
Block a user