ai-orch

ai-orch

Human-Governed SDD 기반 AI orchestration 템플릿이다. 이 repo는 goose, Codex, Claude Code, oh-my-openagent/OpenCode를 조합해 사람이 도메인/비즈니스 판단을 통제하고 AI가 문서화, 계획, 구현, 테스트, self-review, PR 초안 작성을 보조하도록 구성한다.

핵심 원칙

• 사람은 도메인 규칙, 비즈니스 정책, 범위 승인, PR 리뷰, 머지, 배포를 책임진다.
• AI는 승인된 SDD 문서 범위 안에서만 분석, 계획, 구현, 테스트, self-review, PR 초안을 수행한다.
• 요구사항과 acceptance criteria가 Human Approved 상태가 아니면 구현하지 않는다.
• AI는 PR 초안 생성 이후 멈추고 사람에게 제어권을 반환한다.

기본 역할 분담

이 프로젝트의 기본 언어는 한글이다.

작업	기본 담당	기본 provider/model
문서 작성	Codex	codex-acp / gpt-5.5
리서치	Codex	codex-acp / gpt-5.5
요약 및 정리	Codex	codex-acp / gpt-5.5
아키텍처 설계	Claude Code	claude-code / default
구현 계획	Claude Code	claude-code / default
코드 작성	Claude Code	claude-code / default
리팩터링	Claude Code	claude-code / default
테스트 작성	Claude Code	claude-code / default
코드 self-review	Claude Code	claude-code / default

작업별로 provider/model을 바꿀 수 있다.

AI_CODE_PROVIDER=codex-acp AI_CODE_MODEL=gpt-5.5 scripts/sdd-implement.sh sample-feature
AI_DOC_PROVIDER=claude-code AI_DOC_MODEL=default scripts/sdd-docs.sh "topic" docs/output.md

구성 요소

• AGENTS.md: repo 전체 agent 규칙
• CLAUDE.md: Claude Code용 agent 규칙 진입점. macOS/git 환경 기준 AGENTS.md symlink
• .specify/memory/constitution.md: spec-kit 호환 project constitution
• docs/ai-governance.md: 사람/AI 권한 경계와 금지 규칙
• docs/project-settings.md: 한글 사용 및 Codex/Claude Code 역할 분담
• docs/workflow.md: SDD 작업 흐름
• docs/ai-orch-flow.md: script 입력부터 goose 실행, 산출물까지 전체 flow
• docs/goose-usage-manual.md: goose 사용 매뉴얼
• docs/sdd-spec-kit-adoption.md: spec-kit 도입 기준
• docs/specs/sample-feature/: 샘플 SDD 문서
• .goose/recipes/: goose recipe
• .claude-plugin/: Claude Code marketplace manifest
• .agents/plugins/: Codex marketplace manifest
• plugins/ai-orch/: Claude Code/Codex native command plugin
• .ai-orch/: 개인별 branch flow 실행 상태 cache. README.md만 추적하고 실행 이력은 git에서 무시
• ai-orch.protect: secret/critical file 접근 보호 공유 정책
• .opencode/: oh-my-openagent/OpenCode 설정 및 skill
• scripts/: SDD 실행 wrapper, guard, test, PR helper

Native command와 통합 entrypoint

Claude Code나 Codex의 command hinting을 사용하려면 repo-local ai-orch plugin을 등록한다. 이 plugin은 SDD 로직을 직접 구현하지 않고, command/skill을 scripts/ai-orch.sh flow로 위임한다.

Claude Code 안에서:

/plugin marketplace add shaul1991/ai-orch
/plugin install ai-orch@ai-orch

Claude Code CLI에서:

claude plugin marketplace add shaul1991/ai-orch
claude plugin install -s project ai-orch@ai-orch

Codex:

codex plugin marketplace add shaul1991/ai-orch

Codex는 plugin skill을 통해 같은 /ai-orch:* hinting을 노출한다. 설치 후 plugin 상세에 Skills가 표시되어야 한다.

local clone을 직접 등록할 때는 repo root에서 claude plugin marketplace add . 또는 codex plugin marketplace add .를 실행한다.

활성화 후 1차 command set:

/ai-orch:help
/ai-orch:init
/ai-orch:protect <action> [args...]
/ai-orch:status [feature]
/ai-orch:docs <topic> <output-markdown-path>
/ai-orch:feature <feature> [description]
/ai-orch:plan <feature>
/ai-orch:ready <feature>
/ai-orch:implement <feature>
/ai-orch:review <feature>
/ai-orch:pr <feature>

Claude Code나 Codex에서 shell command 형태로 실행할 때는 scripts/ai-orch.sh를 우선 사용한다. 이 wrapper는 실행 전에 어떤 flow를 실행할지 계획을 출력한 뒤, 기존 scripts/sdd-*.sh와 guard/test script를 순서대로 호출한다.

scripts/ai-orch.sh help
scripts/ai-orch.sh init
scripts/ai-orch.sh protect list
scripts/ai-orch.sh status
scripts/ai-orch.sh feature login "로그인 기능"
scripts/ai-orch.sh plan login
scripts/ai-orch.sh ready login
scripts/ai-orch.sh implement login
scripts/ai-orch.sh review login
scripts/ai-orch.sh pr login

계획만 보고 실행하지 않으려면:

scripts/ai-orch.sh explain implement login

scripts/ai-orch.sh로 실행한 flow는 현재 git branch 기준으로 .ai-orch/에 local 상태를 기록한다. 이 디렉터리는 개인별 실행 이력/캐시이므로 git에서 무시되며, /ai-orch:status 또는 scripts/ai-orch.sh status로 feature -> Human Approved -> plan -> ready -> implement -> review -> pr -> human review -> merge 체크리스트와 산출물 링크를 확인한다.

plugin 설치 직후 target repo에서 최초 필수 command는 /ai-orch:init 또는 scripts/ai-orch.sh init이다. init 전에는 status와 실행형 flow가 멈추고 init 실행을 안내한다. 이 command가 .ai-orch/init.json local marker(ignored), .ai-orch/README.md, .ai-orch/setting*.json, .gitignore, CLAUDE.md -> AGENTS.md symlink를 준비한다.

secret/critical file 접근은 /ai-orch:protect 또는 scripts/ai-orch.sh protect로 확인한다. 기본 정책은 ai-orch.protect, 개인 추가 차단은 .ai-orch/protect.local, 사용자가 명시 확인한 local 허용은 .ai-orch/protect.allow.local에 둔다.

설치 전제 조건

macOS 기준 권장 도구:

brew --version
node --version
npm --version
bunx --version
gh --version

필수 AI 도구:

goose --version
codex --version
claude --version
opencode --version
bunx oh-my-openagent version

신규 환경 설치

1. repo 준비

git clone https://github.com/shaul1991/ai-orch.git
cd ai-orch

2. CLI 설치

Homebrew를 사용하는 경우: