이 디렉토리는 LLM Wiki 의 9개 wiki agent 를 Codex CLI 에서 사용할 수 있는 프롬프트 템플릿입니다. .claude/agents/ 의 Claude Code agent 와 본문은 동일하지만 frontmatter 에서 tools: 와 model: 필드를 제거했습니다 (Codex 는 이 필드를 자동 파싱하지 않음). 본문 안의 Read tool / Edit tool / Write tool / Bash tool 같은 Claude Code 전용 표현도 Read / Edit / Write / shell 로 일반화했습니다. 같은 rules/ 와 templates/ 를 참조합니다.

Native generation (현재 방식)

Codex CLI 는 native subagent 를 .codex/agents/*.toml 로 등록한다 (name / description / developer_instructions + sandbox_mode). SSOT 는 .agents/plugins/wiki-superpowers/agents/<name>.md (gated body) 이고, 이 디렉토리의 .md 와 .toml 은 그 대응 variant 이다.

⚠️ 자동 생성기 scripts/sync_automation.py 는 현재 repo 에 없다(2026-06-06 확인; scripts/ 는 존재하나 sync_automation.py 만 부재 — 2026-07-14 재확인). 아래 명령은 생성기가 복원되면 쓰는 의도된 경로이며, 그 전까지는 SSOT .md 편집 시 대응 .toml 을 수기로 맞춰 3 플랫폼 패리티를 유지한다.

# (생성기 복원 시) .md (+ .claude/agents frontmatter tools:) -> .toml
python3 scripts/sync_automation.py agents
python3 scripts/sync_automation.py agents --check  # exit 2 on drift (CI 용)

Commands(슬래시 명령) 도 같은 (현재 부재) 스크립트로 동기화되도록 설계됐다. .claude/commands/*.md (현재 23개 — invest-* 6 + project/project-spec 2 = 8개는 Claude 전용 비동기화, 나머지 15개가 mirror) 를 SSOT 로:

# (생성기 복원 시) -> .agents/skills/<cmd>/SKILL.md (codex) + .agents/workflows/<cmd>.md (antigravity)
python3 scripts/sync_automation.py commands
python3 scripts/sync_automation.py commands --check # exit 2 on drift

Codex 는 .agents/skills/<cmd>/SKILL.md 를 skill 로 자동 디스커버리하고 $<cmd> / /skills 로 호출한다. 인자는 placeholder 없이 자연어(각괄호 prose). Antigravity 는 .agents/workflows/<cmd>.md 를 /<cmd> 슬래시로 인식한다.

.md SSOT 를 편집한 뒤 대응 .toml 을 갱신해야(생성기 부재 시 수기) .toml 에 반영된다. 권한은 .claude/agents/<name>.md frontmatter 의 tools: 에서 파생된다 — Edit/Write 가 있으면 sandbox_mode = "workspace-write", 없으면 "read-only".

아래 "Pattern" 의 codex exec "$(cat ...md)" 수동 호출은 native .toml 자동 등록 이전의 legacy 방식이다. 일회성 실행에는 여전히 쓸 수 있으나, 표준 경로는 위 native .toml 이다.

Pattern

codex exec \
  -C /home/donghyeon/Documents/LLM\ Wiki \
  -s read-only \
  "$(cat .codex/agents/wiki-link-verifier.md)

Scope: project:keycloak-patterns"

Sandbox 권장 설정

Agent	권장 sandbox
`wiki-doc-author` (mode=create / migrate)	`-s workspace-write` (파일 생성·수정 필요)
`wiki-source-summarizer`	`-s workspace-write` (raw/ 에 파일 생성)
`wiki-link-verifier`	`-s read-only` (audit only)
`wiki-research-lane`	`-s read-only` (synthesis recommendation only)
`wiki-adversarial-reviewer`	`-s read-only` (falsification only)
`wiki-diagram-reviewer`	`-s read-only` (scoring only)
`wiki-decision-researcher`	`-s workspace-write` (wiki-source-summarizer 디스패치로 raw 자료 N×2개 생성)

write 권한을 read-only agent 에 주면 오용 위험. read-only 도구에 workspace-write 부여 금지.

Scope

LLM Wiki 의 .codex/agents/ 는 문서 작업 전용 — 7개 prompt:

wiki-doc-author — 새 raw 문서 생성 + 기존 비-template 문서 마이그레이션 (1 dispatch = 1 논리적 문서 (target + Parent hub); supports branch-note, error-note, interview-prep, job-posting, blog-topic, lecture-note, project-note, daily-note)
wiki-source-summarizer — 외부 URL → raw 자료 보존 (verbatim quote + self-grep)
wiki-link-verifier — orphan / broken wikilink / Cluster 누락 감사 (read-only)
wiki-research-lane — 다수 raw 정독 → 합성 권고 (read-only)
wiki-adversarial-reviewer — 리서치/감사 draft falsification (read-only)
wiki-diagram-reviewer — .drawio 다이어그램 컨퍼런스급 채점 (read-only)
wiki-decision-researcher — 기술 결정 alternatives orchestrator (WebSearch + URL 후보 + wiki-source-summarizer dispatch + 비교 매트릭스 + 조건부 권고)

코드 작업 (Java / Clean Architecture) 은 본 vault 범위 밖. ca-tmpl 의 .codex/agents/ (ca-implementer, ca-architect-sentinel, ca-spec-reviewer, ca-quality-reviewer, gradle-runner) 사용.

Workflow Contracts

7개 prompt 모두 다음 top-level rules 를 참조합니다 — Codex CLI 는 자동 로드하지 않으므로 호출 시 explicit 으로 전달:

rules/linking-rules.md
rules/naming-conventions.md
rules/tag-taxonomy.md
rules/diagram-standards.md
rules/evidence-first-research.md
rules/reporting-standards.md
rules/advisory-depth.md

각 agent 의 Mandatory First Reads 섹션에 어떤 rule 을 정독해야 하는지 명시되어 있습니다.

Codex 호출 예시

1. 새 branch-note 생성

codex exec \
  -C /home/donghyeon/Documents/LLM\ Wiki \
  -s workspace-write \
  "$(cat .codex/agents/wiki-doc-author.md)

Mode: create
Category: branch-note
Title: 'branch / feature-keycloak-patterns (root)'
File slug: feature-keycloak-patterns
Parent: keycloak-patterns (project slug)
Sources: 필요시 채움 (feature- prefix 면 ≥1개 필수)
Initial seed: OIDC 패턴 학습 작업 묶음"

2. 기존 비-template 노트 마이그레이션

codex exec \
  -C /home/donghyeon/Documents/LLM\ Wiki \
  -s workspace-write \
  "$(cat .codex/agents/wiki-doc-author.md)

Mode: migrate
Category: error-note
Title: 'error / Keycloak OIDC discovery 실패 (2026-05-25)'
Target path: raw/errors/oidc-discovery-failure-2026-05-25.md
Parent: feature-keycloak-patterns-1-1 (branch slug)"

3. URL → raw 자료 보존

codex exec \
  -C /home/donghyeon/Documents/LLM\ Wiki \
  -s workspace-write \
  "$(cat .codex/agents/wiki-source-summarizer.md)

URL: https://www.keycloak.org/docs/latest/securing_apps/#_oidc
source_type: official-doc
Parent: feature-keycloak-patterns-1-1
이 자료가 정당화하는 결정: oauth2-proxy provider=keycloak-oidc 설정 근거"

4. 링크 무결성 감사

codex exec \
  -C /home/donghyeon/Documents/LLM\ Wiki \
  -s read-only \
  "$(cat .codex/agents/wiki-link-verifier.md)

Scope: project:keycloak-patterns"

5. 다수 raw 정독 + 합성 권고

codex exec \
  -C /home/donghyeon/Documents/LLM\ Wiki \
  -s read-only \
  "$(cat .codex/agents/wiki-research-lane.md)

Slice:
- raw/branch-notes/feature-keycloak-patterns-1-1.md
- raw/branch-notes/feature-keycloak-patterns-1-2.md
- raw/official-docs/oidc-discovery-keycloak-official.md
Research question: 이 3개 노트에서 wiki/concepts/oidc-handshake 로 추출할 핵심 사실 식별
Target output type: wiki-concept-draft"

6. Adversarial review

codex exec \
  -C /home/donghyeon/Documents/LLM\ Wiki \
  -s read-only \
  "$(cat .codex/agents/wiki-adversarial-reviewer.md)

Master report path: docs/superpowers/specs/2026-05-26-keycloak-audit-report.md
Per-file findings path: docs/superpowers/specs/2026-05-26-keycloak-audit-per-file-findings.md
Source corpus: raw/branch-notes/"

7. 다이어그램 채점

codex exec \
  -C /home/donghyeon/Documents/LLM\ Wiki \
  -s read-only \
  "$(cat .codex/agents/wiki-diagram-reviewer.md)

Target diagrams:
- raw/diagrams/keycloak-patterns/architecture-overview-2026-05-26.drawio
- raw/diagrams/keycloak-patterns/architecture-deployment-2026-05-26.drawio
Standards file: rules/diagram-standards.md"

Recommended Workflow

문서 작업의 표준 흐름:

캡처: wiki-doc-author (mode=create) 또는 wiki-source-summarizer 로 raw 자료 등록
검증: wiki-link-verifier 로 새 raw 가 cluster 에 올바르게 연결되었는지 점검
합성: 충분한 raw 가 모이면 wiki-research-lane 으로 wiki/concepts 또는 wiki/projects 추출 권고
검수: findings ≥ 5 인 큰 보고서면 wiki-adversarial-reviewer 로 falsification
다이어그램: project-note 의 .drawio 가 생성·수정되면 wiki-diagram-reviewer 로 ≥95 점 확인

기존 비-template 문서가 있다면 wiki-doc-author (mode=migrate) 로 normalize 후 위 흐름 진입.

Note: 다른 CLI 와의 일관성

본 .codex/agents/ 의 7개 파일은 .claude/agents/ 와 본문 내용이 같지만, frontmatter 와 tool 표현이 codex 환경에 맞춰 정리되어 있습니다 — tools:/model: 필드 제거, 본문의 Read tool/Edit tool 등은 일반화. Claude Code 와 Codex 는 같은 작업 정의를 공유하지만 invocation 방식이 다릅니다:

CLI	Agent 파일 위치	자동 등록	Skill 폴더	frontmatter	특수 기능
Claude Code	`.claude/agents/`	✓	`.claude/skills/`	`tools:` + `model: sonnet` 유지	Skill 이 dispatch decision tree 처리
Codex	`.codex/agents/`	✗ (수동 cat + exec)	(없음)	`tools:` / `model:` 제거됨	`-s` sandbox flag 로 권한 제어
Antigravity	`.agents/plugins/wiki-superpowers/agents/`	✓ (plugin)	`.agents/plugins/wiki-superpowers/skills/`	`tools:` / `model:` 없음, G1~G4 hard gates	Gemini 4가지 실패 모드 차단

3개 모두 동일한 rules/ 와 templates/ 를 참조하므로, 어느 CLI 에서 작업해도 산출물의 형식·검증 기준은 일치합니다.