agent-core-plugin

OpenCode 플러그인 — orchestrator 에이전트가 의도를 분류하고 7개 스킬을 Phase Gate로 실행합니다.
9명의 전문가 에이전트가 병렬로 구현·분석하며, 작업 히스토리와 컨텍스트는 SQLite에 누적됩니다.

🗂️ 개요

agent-core-plugin은 OpenCode 위에서 동작하는 플러그인입니다.

플러그인을 등록하면 orchestrator 라는 primary 에이전트와 9개의 전문가 서브에이전트가 자동으로 등록됩니다.
/core-* 슬래시 커맨드 또는 자연어로 작업을 요청하면, orchestrator가 의도를 분류해 적합한 스킬을 Phase Gate 규칙에 따라 실행합니다.

작업 히스토리·프로젝트 컨텍스트·문서 템플릿은 SQLite에 저장되어 세션이 바뀌어도 맥락이 유지됩니다.

⚡ 시작하기

1. OpenCode 설치

# macOS / Linux
curl -fsSL https://opencode.ai/install | bash

# 설치 확인
opencode --version

OpenCode는 Bun 런타임 기반입니다. 자세한 내용은 공식 문서를 참고하세요.

2. OpenCode에 플러그인 등록

~/.config/opencode/opencode.json (전역) 또는 프로젝트 루트 opencode.json:

{
  "plugins": ["agent-core-plugin"]
}

플러그인이 설치되어 있지 않으면 OpenCode가 자동으로 설치합니다.
최신 버전으로 업데이트하려면 npm install -g agent-core-plugin@latest 를 직접 실행하세요.

OpenCode 재시작 후 즉시 사용 가능합니다.

🤝 OMO 공존 설정

oh-my-openagent와 함께 사용할 때는 에이전트 역할을 분리해서 운영하는 것을 권장합니다.

| 에이전트 | 역할 | |---------|------| | orchestrator (agent-core) | 스킬 라우팅 · Phase Gate 하네스 적용 | | Sisyphus 등 (OMO) | OMO 워크플로우 전용 | | OpenCode 기본 에이전트 | 기본 동작 유지 |

{
  "plugins": [
    "agent-core-plugin",
    "oh-my-openagent",
    "@ex-machina/opencode-anthropic-auth",
    "cursor-oauth-opencode"
  ]
}

| 플러그인 | 설명 | |---------|------| | agent-core-plugin | 이 플러그인 | | oh-my-openagent | OMO 워크플로우 에이전트 | | @ex-machina/opencode-anthropic-auth | Anthropic 계정 인증 | | cursor-oauth-opencode | Cursor OAuth 연동 |

하나의 작업에서는 에이전트를 자주 전환하지 않는 것이 안정적입니다.

🧠 에이전트 구조

Orchestrator (primary)

@orchestrator 로 직접 지정하거나, /core-* 커맨드 실행 시 자동으로 활성화됩니다.

역할:

• 모든 메시지를 7개 스킬 중 하나로 분류
• 활성 스킬 절차만 시스템에 주입 (7개 전문 동시 주입 없음)
• 각 스킬을 Phase Gate 규칙에 따라 단계적으로 실행
• 전문가 에이전트를 병렬 spawn해 실제 작업 위임

하네스 규칙 (Hard Blocks):

• 스킬 없이 진행 금지 — 모든 요청은 반드시 스킬로 분류 후 처리
• Phase 순서 위반 금지 — ✅ Phase N 완료 마커 없이 다음 Phase 진입 불가
• 직접 구현 금지 — trivial(단일 파일, 5줄 이하) 외에는 반드시 전문가에게 위임
• 병렬 강제 — 복수 전문가는 순차 실행 금지, 항상 동시 spawn
• git commit·push 절대 금지
• .env, secrets.* 읽기·쓰기 금지

의도 분류 순서:

1. 자연어 매핑   → 스킬 감지 즉시 실행
2. 스킬 이어받기 → 직전 질문의 답변이면 해당 스킬 계속
3. 짧은 되묻기   → 진행 중인 작업이 있고 의도 모호할 때
4. 일반 응답     → 피드백·메타 질문 등 나머지 경우

Expert Subagents

orchestrator가 스킬 실행 중 agent(name: "...") 툴로 spawn하는 전문가 서브에이전트입니다.
각 에이전트는 도메인 특화 시스템 프롬프트(config)를 가지며, 복수 선택 시 항상 병렬로 실행됩니다.
spawn 시 project context만 얇게 주입됩니다 (history·external 미주입).

| 에이전트 | 담당 영역 | |---------|---------| | 🔧 backend | REST/GraphQL API, 비즈니스 로직, 트랜잭션, 인증·인가 | | 🎨 frontend | 컴포넌트 설계, 상태관리, 렌더링 성능, 접근성 (WCAG 2.1 AA) | | 📱 mobile | iOS(Swift), Android(Kotlin), React Native, Flutter — 생명주기·권한·오프라인·스토어 가이드라인 | | 🧪 qa | 테스트 전략, 엣지케이스 도출, 회귀 위험 분석 | | 🔒 security | OWASP Top 10, XSS/CSRF/SQLi, 모바일 보안, 시크릿 관리 | | ⚡ performance | 렌더링 최적화, N+1, 쿼리 튜닝, 번들 사이즈 | | 🗄️ dba | 스키마 정규화, 인덱스 설계, 마이그레이션 안전성 | | 🚀 devops | CI/CD, Docker/K8s, GitHub Actions, 인프라 as Code | | 🏛️ architecture | 레이어 분리, SOLID, DDD, 모듈 경계, 의존성 |

📋 스킬 목록

| 커맨드 | 설명 | |--------|------| | /core-dev | 신규 기능 개발 및 기존 코드 수정 | | /core-debug | 버그 원인 진단 및 최소 범위 수정 | | /core-test | 테스트 전략 수립 및 코드 작성 | | /core-review | 코드 검토 또는 PR diff 분석 (GitHub · GitLab · Bitbucket) | | /core-audit | 보안 취약점 · 성능 전체 감사 | | /core-doc | 설계 문서 · API 명세 · README 생성 | | /core-setup | 프로젝트 컨텍스트 수집 · 외부파일 등록 · 문서 템플릿 설정 · 저장 항목 관리 |

/core-dev   로그인 기능 만들어줘
/core-debug 버튼 클릭하면 오류 나
/core-test  인증 모듈 테스트 짜줘
/core-review PR #42 리뷰해줘
/core-audit 보안 취약점 검토해줘
/core-doc   API 명세 문서화해줘
/core-setup 프로젝트 컨텍스트 저장해줘

커맨드 없이 자연어만 입력해도 orchestrator가 의도를 감지해 라우팅합니다.

🔄 Phase Gate 파이프라인

모든 스킬은 Phase Gate 구조로 실행됩니다.

• 순서 보장 — ✅ Phase N 완료 마커 출력 후 다음 Phase 진입
• 유저 입력 게이트 — 입력이 필요한 Phase에서는 응답 전까지 진행 금지
• 병렬 spawn 강제 — 전문가는 반드시 agent 툴로 동시 실행

/core-dev 실행 흐름:

Phase 0: Scope Check      — Small(직접 실행) / Medium / Large 분류
Phase 1: Read Before Write — 대상 파일 전체 읽기, 패턴·컨벤션 파악
Phase 2: Expert 선택      — 번호 입력 대기 [유저 입력 게이트]
Phase 3: Spawn Experts    — 선택된 expert 병렬 구현
Phase 4: Verify           — 타입 체크, 변경 범위 확인
          └─ agent_context_write(type="history") → 완료 리포트

전문가 선택 화면 예시 (/core-review):

리뷰할 전문가를 선택하세요 (번호 입력, 기본값: 4):

1. [ ] backend      — API, 비즈니스 로직
2. [ ] frontend     — UI, 컴포넌트, 상태관리
3. [ ] mobile       — iOS, Android, React Native, Flutter
4. [✓] qa           — 테스트, 엣지케이스
5. [ ] security     — 인증, 취약점
6. [ ] performance  — N+1, 쿼리, 번들
7. [ ] dba          — 스키마, 마이그레이션, 쿼리 튜닝
8. [ ] devops       — CI/CD, 컨테이너, 배포
9. [ ] architecture — 모듈 경계, 의존성, 확장성

입력 예시: 1,3,4 또는 all

💾 컨텍스트 저장소

저장된 내용은 orchestrator 세션에서 시스템 프롬프트에 자동 주입됩니다.
매 턴 DB에 쓰지 않고 읽기만 하며, 주입량은 상한(cap)이 적용됩니다.

| 테이블 | 내용 | 저장 방식 | |--------|------|-----------| | context | 프로젝트 개요, 스택, git 히스토리 | 프로젝트당 1행, upsert | | external_files | 외부 설계 문서 · 스펙 요약 | 프로젝트 + slug 기반, upsert | | templates | /core-doc 실행 시 적용할 문서 템플릿 | 전체 공용 — slug 기반, upsert (프로젝트 무관) | | history | 스킬별 작업 완료 기록 | row 단위 누적, ID 기반 개별 삭제 가능 |

관리 도구

저장된 항목은 /core-setup → 모드 4로 조회·삭제할 수 있습니다.

| 도구 | 용도 | |------|------| | agent_context_write | 항목 저장·갱신 | | agent_context_manage | 목록(list) · 전문 조회(read) · 삭제(delete) |

read 예시 — 주입에서 잘린 항목 확인:

agent_context_manage(action=read, type=context)
agent_context_manage(action=read, type=external, slug=design-spec)
agent_context_manage(action=read, type=template, slug=doc-template-기획서)
agent_context_manage(action=read, type=history, id=42)

DB 경로 — 단일 글로벌 파일, 모든 프로젝트 공유

| OS | 경로 | |----|------| | macOS / Linux | ~/.local/share/agent-core/agent-core.db | | Windows | %APPDATA%\agent-core\agent-core.db |

context · external_files · history는 project_dir 컬럼으로 프로젝트별 분리됩니다.
templates는 project_dir 없이 저장되어 모든 프로젝트 세션에서 공유됩니다.

🪙 토큰 최적화 · 컨텍스트 주입

시스템 프롬프트 고정 비용을 줄이기 위해 활성 스킬·에이전트별로 주입 범위를 분기합니다.

주입 파이프라인 (experimental.chat.system.transform, 매 턴 1회)

유저 메시지 → 활성 스킬 판별 → DB 읽기(SELECT) → system.push → LLM 호출

| 대상 | 주입 내용 | |------|-----------| | orchestrator (스킬 없음) | thin 라우팅 프롬프트 + context + template slug 목록 | | orchestrator (스킬 활성) | 위 + 활성 스킬 1개 전문 + 스킬별 DB 주입 | | expert 서브에이전트 | project context만 (최대 1,500자) |

스킬별 DB 주입

| 스킬 | history | external | template | |------|---------|----------|----------| | 미정 (인사·잡담) | ✗ | ✗ | slug만 | | dev / debug | 최신 3건 | ✓ | slug만 | | review / test / audit | 최신 5건 | ✓ | slug만 | | doc / setup | ✗ | ✓ | 전문 |

주입 상한 (대표)

| 항목 | 상한 | |------|------| | context | 4,000자 (서브에이전트 1,500자) | | external | 최근 5개 · 파일당 2,000자 · 합계 6,000자 | | history | 최신 3~5건 · 건당 400자 · 합계 2,000자 | | template (doc/setup) | 파일당 3,000자 | | README 자동 첨부 (Read 시) | 가장 가까운 README 1개 · 1,200자 |

DB에 history가 수십 건 쌓여 있어도 주입은 최신 N건 cap만 적용됩니다. 오래된 항목은 action=read로 조회하세요.

기타

• 오케스트레이터 프롬프트·expert 프롬프트 이중 주입 없음 — orchestrator는 config 1회, expert는 spawn 시 각자 config 사용
• 활성 스킬은 세션별 캐시 — Phase 질문에 짧게 답해도 스킬 유지
• /core-dev 등 슬래시 커맨드로 스킬 즉시 매핑

/core-setup 수집 모드

1 — 프로젝트 기준    : git 히스토리, 파일 구조, 스택 자동 수집
2 — 외부파일 기준    : 설계 문서, 스펙, PDF 등 경로 입력 → 요약 저장
3 — 문서 템플릿 설정  : 구조 + 디자인 설정 저장 (참조 파일 기반 자동 추출 지원)
4 — 저장 항목 관리   : context·external·template·history 목록 확인 · 선택 삭제

모드 4 삭제 방식:

• 항목 선택 삭제 — 전체 목록을 번호로 표시, 원하는 항목만 삭제
• 종류 선택 후 삭제 — context / external / template / history 중 종류 먼저 선택 → 해당 항목 선택 삭제
• 전체 초기화 — "전체삭제" 입력 확인 후 삭제

⚠️ template 삭제는 전체 공용이므로 모든 프로젝트 세션에 영향을 줍니다.

모드 3 — 문서 템플릿 저장 항목:

| 범주 | 항목 | |------|------| | 구조 | 제목 형식, 섹션 순서, 출력 형식(.md/.docx/.pdf 등), 언어 | | Markdown 디자인 | 섹션 구분선, 콜아웃 스타일(GitHub/blockquote), 코드블록 태깅, 다이어그램(Mermaid/PlantUML) | | 리치 포맷 디자인 | 컬러 테마(HEX), 폰트(제목/본문), 표지, 로고·워터마크 | | 공통 | 헤더·푸터 |

시작 시 "참고할 파일 경로?"를 물어봅니다. 기존 문서를 경로로 입력하면 구조·스타일을 자동 분석해 항목별 기본값을 제안합니다.

템플릿을 등록해두면 /core-doc 실행 시 목록에서 선택해 해당 구조·디자인으로 문서를 자동 생성합니다.

🔍 PR diff 리뷰 지원 플랫폼

/core-review → 유형 2 (PR diff 리뷰) 선택 시 지원합니다.

| 플랫폼 | 인증 방식 | 사전 설정 | |--------|---------|---------| | GitHub | gh CLI | gh auth login | | GitLab (public) | glab CLI | glab auth login | | GitLab (private) | 환경변수 | GITLAB_HOST + GITLAB_TOKEN | | Bitbucket | 환경변수 | BITBUCKET_USERNAME + BITBUCKET_TOKEN |

export GITLAB_HOST=https://gitlab.mycompany.com
export GITLAB_TOKEN=glpat-xxxxxxxxxxxx

📄 라이선스

MIT