oozoofrog/apple-harness

Apple Harness

원본 apple-harness의 의도를 Codex 오케스트레이션으로 옮긴 스킬입니다.

When to use

• 새 기능을 처음부터 끝까지 구현해야 할 때
• 대규모 UI 리팩터링이나 복합 프레임워크 통합이 필요할 때
• 단일 파일 수정이 아니라 단계별 검증 루프가 필요할 때

Do not use when

• 단일 파일 수정이나 짧은 버그 픽스처럼 작은 작업 → apple-craft
• 구현 없이 리뷰·감사만 필요한 작업 → apple-review
• PLAN→DESIGN→BUILD→EVALUATE 아티팩트를 유지할 필요가 없는 작업

Quick start

1. harness-spec.md와 features.json으로 목표와 기능 상태를 먼저 적는다.
2. 현재 라운드에서 다룰 기능 하나를 고른다.
3. DESIGN → BUILD → EVALUATE를 한 사이클로 실행한다.
4. 최대 3라운드 안에 수렴하지 않으면 pivot / rescope / escalate를 검토한다.

Shared artifacts

작업 산출물은 기본적으로 .codex/harness/ 아래에 둔다.

• harness-spec.md — 제품/기능 스펙
• features.json — 기능 목록과 상태
• design-spec.md — 디자인 토큰·화면 구조
• evaluation-round-N.md — 검증 피드백

Use references

• references/harness-design-principles.md
• references/apple-hig-map.md
• references/walkthrough-liquid-glass-settings.md

Orchestration flow

1. PLAN — 요구사항을 구조화하고 harness-spec.md, features.json을 만든다.
2. DESIGN — Pencil이 가능하면 화면 구조와 디자인 토큰을 design-spec.md에 남긴다.
3. BUILD — 우선순위가 가장 높은 기능부터 작은 단위로 구현한다.
4. EVALUATE — 빌드, 프리뷰, 런타임, 접근성, 설계 일치 여부를 점검한다.
5. 실패한 항목이 있으면 최대 3라운드까지 반복한다.

Agent mapping

• Codex app/CLI에서는 .codex/agents/harness-*.toml custom agents를 우선 사용한다.
• 현재 환경에 custom agent 호출이 없으면 built-in subagent 또는 로컬 작업으로 역할을 분리한다.
• 평가 단계는 가능하면 read-only 역할로 유지하고, 구현 단계와 쓰기 범위를 분리한다.

Guardrails

• features.json의 기능 항목은 삭제하지 말고 상태만 변경한다.
• 한 번에 한 기능 또는 명확히 분리된 write scope만 다룬다.
• 빌드 성공 전 파괴적 후속 작업을 밀어붙이지 않는다.

Review Harness

• mode: required
• 공통 기준: ../../../docs/review-harness.md
• planner: harness-spec.md, features.json, 필요 시 design-spec.md를 먼저 정의한다
• generator: builder가 기능 구현과 디자인 반영을 수행한다
• evaluator: evaluator/reviewer가 빌드, 프리뷰, 런타임, 접근성, 설계 일치 여부를 검토한다
• 평가축: feature completeness, functionality, visual design, code quality, acceptance criteria 충족
• artifacts/evidence: .codex/harness/*, build log, preview, evaluation round 문서
• pass condition: 핵심 acceptance criteria가 충족되고, 실패 항목은 최대 3라운드 안에 수렴하거나 명시적으로 남아야 한다
• 자동 다음 행동: pass면 다음 기능 또는 종료, refine이면 builder 재수행, pivot이면 설계 전환, rescope면 spec 갱신, 3라운드 초과 시 escalate한다

Output expectation

• 라운드별 결과
• 완료/실패 기능 목록
• 남은 리스크와 다음 액션