llm-wiki/.agents/plugins/wiki-superpowers/README.md

# Wiki Superpowers Antigravity Plugin

Workspace-local Antigravity CLI agent prompts for the LLM Wiki repository.

> **⚠️ Loading model (READ FIRST)**
>
> Antigravity CLI **does not** auto-load this plugin directory as native subagents. The CLI's native subagent registry is `.agents/agents/<name>/agent.json` (workspace) and `~/.gemini/antigravity-cli/agents/<name>/agent.json` (global).
>
> - **System prompt SSOT (edit here):** the 10 `agents/*.md` files in this directory.
> - **What Antigravity actually loads:** the corresponding `.agents/agents/<name>/agent.json` at the repo root.
> - **⚠️ Generator currently ABSENT:** `scripts/sync_automation.py` (the generator that would regenerate `.agents/agents/<name>/agent.json` from the gated `.md` sources here plus per-agent tool policy from `.claude/agents/<name>.md` frontmatter `tools:`) is **not present in the repo** as of 2026-06-06 (the `scripts/` dir now exists — deep-research — but `sync_automation.py` is still absent, re-checked 2026-07-14). Until it is restored, edits to a `.md` SSOT must be **applied to the corresponding `agent.json` by hand**, keeping 3-platform parity. The intended commands, once restored, are `python3 scripts/sync_automation.py agents` and `python3 scripts/sync_automation.py agents --check` (exit 2 on drift, for CI).
>
> Editing a `.md` SSOT without updating the corresponding `agent.json` means Antigravity will keep using the previous prompt. When hand-syncing, preserve the existing `toolNames` policy per agent (read-only agents do not get `write_to_file` / `replace_file_content` / `multi_replace_file_content`).

## Directory layout

```text
LLM Wiki/
  rules/                           ← top-level (Claude / Antigravity / codex-cli 공유 SSOT)
    linking-rules.md
    naming-conventions.md
    tag-taxonomy.md
    diagram-standards.md
    evidence-first-research.md
    reporting-standards.md
    advisory-depth.md
  templates/                       ← 27개 *-template.md (문서 출력 형식 정의)
  .agents/plugins/wiki-superpowers/
    plugin.json
    README.md                      ← 이 파일
    skills/
      wiki-workflow/
        SKILL.md
    agents/
      wiki-doc-author.md
      wiki-source-summarizer.md
      wiki-link-verifier.md
      wiki-research-lane.md
      wiki-adversarial-reviewer.md
      wiki-diagram-reviewer.md
      wiki-decision-researcher.md
```

플러그인은 저장소 내부에 있으므로 Antigravity가 본 프로젝트를 열 때만 적용된다. `~/.gemini/` 등 사용자 홈 디렉토리에 쓰지 않는다.

**Rules 위치**: `rules/`는 top-level 폴더로, Claude Code(`.claude/`) / Antigravity(`.agents/`) / codex-cli(`.codex/`) 모두 동일한 14개 rule 파일을 공유한다. 본 플러그인은 그 rules를 참조한다 — `.agents/plugins/wiki-superpowers/rules/`라는 별도 rules 폴더는 없다.

## Scope (what this plugin handles)

이 플러그인은 **LLM Wiki 문서 작업**을 다룬다:

- 새 raw 문서 생성 (`branch-note`, `error-note`, `interview-prep`, `job-posting`, `blog-topic`, `lecture-note`, `project-note`, `daily-note`)
- 외부 URL → raw 자료로 보존 (verbatim quote + self-grep 검증)
- 다수 raw 정독 후 합성 권고 (evidence matrix + per-file findings)
- wiki 링크 무결성·orphan·broken wikilink·cluster 누락 감사
- 리서치/감사 draft의 adversarial review (KEEP/DOWNGRADE/REJECT)

**코드 작업(Java/Clean Architecture)**은 본 플러그인 범위 밖이다. `/home/donghyeon/workspace/ca-tmpl/.agents/plugins/ca-superpowers/` 의 `ca-implementer`, `ca-architect-sentinel`, `ca-spec-reviewer`, `ca-quality-reviewer`, `gradle-runner` 사용. 본 플러그인에서 코드 review subagent 를 중복 정의하지 않는다.

## Operating Rule

`CLAUDE.md` (저장소 루트) 가 authoritative. 이 플러그인의 역할은 CLAUDE.md 의 운영 규칙을 Antigravity CLI 안에서 강제하는 것이지, 대체하는 것이 아니다. skills 와 rules 는 CLAUDE.md 와 충돌 시 항상 CLAUDE.md 로 회귀한다.

## What Triggers What

| User intent | Skill that should load | Subagent(s) to dispatch |
| --- | --- | --- |
| Trivial lookup ("이 개념 어디 있나요", "이 파일 경로 알려줘") | `wiki-workflow` | None. One-line answer with `file:line`. Direct-Response §1만, §2~§6 마크 "N/A — trivial". |
| Direct advisory answer (개념 비교, 문서 구조 설계, 분류 선택) | `wiki-workflow` + `rules/advisory-depth.md` | None. Direct-Response Template §1~§6, exhaustive option enumeration + conditional recommendation. Real-world assumptions with falsification 명시. |
| 새 raw 문서 1개 생성 (branch-note, error-note 등) | `wiki-workflow` | `wiki-doc-author` (1 dispatch = 1 file, category-aware). |
| 외부 URL → raw 자료 보존 | `wiki-workflow` | `wiki-source-summarizer` (verbatim quote 3~5개 + self-grep). |
| 다수 raw 정독 + 합성 권고 (예: "이 5개 파일 읽고 wiki/concepts 추출 권고") | `wiki-workflow` + `rules/evidence-first-research.md` | `wiki-research-lane` (evidence matrix + per-file findings + priority recommendation). |
| wiki 링크/구조 감사 (orphan, broken wikilink, cluster 누락) | `wiki-workflow` | `wiki-link-verifier` (read-only). |
| 리서치/감사 draft 의 falsification (findings 5개+) | `wiki-workflow` | `wiki-adversarial-reviewer` (KEEP/DOWNGRADE/REJECT per finding, read-only). |
| `.drawio` 다이어그램 채점 (컨퍼런스급 기준) | `wiki-workflow` + `rules/diagram-standards.md` | `wiki-diagram-reviewer` (XML grep 기반 vertex/edge/callout/color/label 측정 → v2 minimalist deduction rubric (8항 self-check + element budget) → ≥95 PASS, read-only). |
| 기존 비-template 문서를 template 구조로 마이그레이션 | `wiki-workflow` | `wiki-doc-author` mode=migrate (기존 파일 frontmatter 보강 + Parent 섹션 추가 + slug 정정). |
| 기술 결정의 alternatives 를 신뢰도 있게 조사 (공식 문서 + 기술 블로그 근거 + Pros/Cons + 조건부 권고) | `wiki-workflow` + `rules/advisory-depth.md` Contract 2 | `wiki-decision-researcher` (WebSearch → URL 후보 → 사용자 승인 → `wiki-source-summarizer` × N×2 dispatch → 비교 매트릭스 + 조건부 권고). branch-note 의 `## 결정 사항` 표를 채울 input 산출. |
| Saving a report under `docs/superpowers/specs/` 또는 long multi-file output | `wiki-workflow` + `rules/reporting-standards.md` + `rules/advisory-depth.md` | Systematic report template (§0~§8) with Goal → Current → Gap → Action → Why → Counterargument chain per finding. |
| Long multi-file report (>3 files, OR §4 with 5+ subsections, OR ~10,000+ chars) | `wiki-workflow` + `rules/reporting-standards.md` Output Split Policy | MANDATORY SPLIT — `<topic>-report.md` + `<topic>-per-file-findings.md`; terminal returns ONLY §1, §2, §5, §6, §7 + file links. |
| 코드 작업 / 아키텍처 / Gradle | (본 플러그인 범위 밖) | ca-tmpl 의 `ca-implementer`, `ca-architect-sentinel`, `ca-spec-reviewer`, `ca-quality-reviewer`, `gradle-runner` 사용. |

여러 행이 매치되면 controller 는 위 순서대로 subagent 를 디스패치한다. 연구 + 작성 + 검수를 한 패스에 압축하지 않는다.

## Mandatory First Reads

본 워크스페이스의 모든 non-trivial 작업에서 agent 는 다음을 순서대로 읽는다:

1. `CLAUDE.md` (저장소 루트)
2. `rules/linking-rules.md` — Mandatory upward link 표 + 다중 부모 + 양방향 작성 + Cluster + Derived 파생 룰
3. `rules/naming-conventions.md` — 파일·디렉토리·branch prefix·다이어그램 명명 규칙
4. `rules/tag-taxonomy.md` — `tags:` 5계층 허용 어휘
5. `rules/evidence-first-research.md` — 연구·리뷰·다중 파일 분석 시
6. `rules/reporting-standards.md` — 보고서 저장 또는 multi-file 산출물 시
7. `rules/advisory-depth.md` — 권고·브레인스토밍·개념 설명·비교·plan 리뷰·direct-answer 자문 시 (거의 모든 non-trivial 응답)
8. `rules/diagram-standards.md` — draw.io 아키텍처 / Mermaid sequence·ER 작성 시
9. `templates/<category>-template.md` — 작업 카테고리별 출력 형식

rule 파일을 열지 못하면 agent 는 파일명에서 규칙을 추정하지 않고 BLOCKED 를 surface 한다.

## Evidence-First Discipline

본 플러그인은 모든 multi-file · multi-document · corpus-level 작업에 evidence-first 계약을 강제한다. 전체 규칙은 `rules/evidence-first-research.md` 참조. 요약:

- 파일은 본문이 열려 inspect 되기 전까지 "reviewed" 가 아님.
- 모든 multi-file 응답에는 파일당 `READ_FULL`, `READ_PARTIAL`, `NOT_READ`, `BLOCKED` 상태가 명시된 evidence matrix 포함.
- 승인된 슬라이스 밖의 파일은 `NOT_READ` 로 보고하고 절대 invent 하지 않음.
- 10개 파일 / 5,000줄 / 3+ 독립 토픽 초과 시: 작업을 여러 Read 호출로 split. document-heavy 다중 파일 연구는 `wiki-research-lane` 디스패치.

## Gemini Hard Gates (본 플러그인 특화)

기본 Antigravity 동작에 더해, 각 agent 는 4가지 강제 블록을 포함한다:

- **G1. Pre-Read Proof** — Mandatory First Reads 각 파일의 첫 줄을 verbatim 인용한 표를 응답 시작부에 출력. 비어 있으면 BLOCKED.
- **G2. Post-Write Validator** — 파일 생성/수정 후 `grep -cE` / `grep -c` / `ls` 명령을 실제 실행하고 출력을 응답에 verbatim 첨부. 위조 시 BLOCKED.
- **G3. Output Schema + V Counter** — 정해진 `{{ }}` placeholder 스키마로만 응답. `V (검증한 quote 수) = 실제 작성한 grep 명령 수` 가 일치해야 함.
- **G4. Enumerated STOP Conditions** — narrative 가 아닌 번호 매겨진 정지 조건. 하나라도 해당하면 즉시 `NEEDS_CONTEXT` 반환. 임의 채움 금지.

각 agent 파일의 해당 섹션 참조.

## Contents

본 플러그인은 다음만 보유. **rules는 본 플러그인 밖 top-level `rules/`에 있으므로 여기 나열하지 않음** (위 Mandatory First Reads §2~§8 참조).

- `plugin.json`: Antigravity 플러그인 마커.
- `README.md`: 본 파일.
- `skills/wiki-workflow/SKILL.md`: 워크플로우 가이드 — subagent dispatch decision tree, STOP self-check (23항), output-format hard gate (18항).
- `agents/wiki-doc-author.md`: 새 raw 문서 생성 + 기존 비-template 문서 마이그레이션 subagent (category-aware, mode: create | migrate).
- `agents/wiki-source-summarizer.md`: 외부 URL → raw 자료 보존 subagent (verbatim quote + self-grep).
- `agents/wiki-link-verifier.md`: orphan / broken wikilink / cluster 누락 감사 subagent (read-only).
- `agents/wiki-research-lane.md`: 다수 raw 정독 + 합성 권고 subagent (read-only).
- `agents/wiki-adversarial-reviewer.md`: 리서치/감사 draft falsification subagent (KEEP/DOWNGRADE/REJECT, read-only).
- `agents/wiki-diagram-reviewer.md`: `.drawio` 다이어그램 채점 (≥95/100 PASS, read-only, `rules/diagram-standards.md` 기준).
- `agents/wiki-decision-researcher.md`: 기술 결정의 alternatives 탐색·비교 orchestrator (WebSearch → URL 사용자 승인 → `wiki-source-summarizer` × N×2 dispatch → Contract 2 비교 매트릭스 + Contract 4 조건부 권고 + branch-note 갱신 input).