makdoong2-team 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jin Uk Yoon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,193 @@
+# makdoong2-team
+
+> Jira 이슈를 3 phase · 8 substage로 나눠 역할별 전문 에이전트에게 위임하는 self-contained opencode 플러그인.
+>
+> **Phase**: `1_planning` (jira/requirements/scope) → `2_implementation` (dev/test) → `3_delivery` (commit/pr/review)
+
+## 설치
+
+패키지는 공개 npm registry ([`makdoong2-team`](https://www.npmjs.com/package/makdoong2-team)) 에 게시된다. 별도 registry 설정이나 인증은 필요 없다.
+
+```bash
+npm install -g makdoong2-team    # npm 모듈 설치
+makdoong2-team install           # opencode 배포 (agents, skills, opencode.json 패치)
+makdoong2-team doctor            # 설치 진단
+```
+
+로컬 dev 설치는 `npm pack` 후 tgz 를 `npm install -g` 한다.
+
+- `install` 은 agents / skills / config seed 만 `~/.config/opencode/` 에 복사한다. 런타임 자산 (dist, gates, stages, scripts) 은 npm 모듈 내부에서 로드된다.
+- `install` 은 `~/.cache/opencode/packages/makdoong2-team@latest/` 를 전역 모듈 심볼릭 링크로 seed 한다. opencode 가 registry 에서 별도로 fetch 하지 않고 방금 설치한 버전을 그대로 로드하게 만든다.
+- 재설치 시 `makdoong2-team.json` 은 보존된다. 덮어쓰려면 `--force`.
+
+## 설정 — `makdoong2-team.json` 한 파일
+
+모든 설정은 `~/.config/opencode/makdoong2-team.json` 하나로 제어한다. 플러그인 (`src/config.ts`) 과 셸 게이트 (`scripts/config.sh`) 가 같은 파일을 읽는다. 환경변수는 사용하지 않는다.
+
+| 블록 | 용도 |
+|---|---|
+| `agents` | 에이전트별 모델 오버라이드 (`model`, `variant`, `fallback_models`) |
+| `model_policy.allowed_primaries` | 빌트인 primary 허용 목록 **확장** (추가 전용 — 빈 배열은 "제한 없음" 이 아니라 "추가 없음") |
+| `coverage.threshold` | 커버리지 게이트 최소 (%, 기본 95) |
+| `timeout.stall_escalate_threshold` | substage 누적 hang 상한 (기본 5). 초과 시 dispatch_stage 차단 후 사용자 에스컬레이션 |
+| `tmux` | 서브세션 pane 모니터 (기본 비활성). `placement` 로 배치 방식 선택 — 아래 참조 |
+| `worktree.extra_exclude` | worktree 동기화 추가 제외 패턴 |
+| `logging.level` | 플러그인 콘솔 로그 레벨 (`silent`/`error`/`warn`/`info`/`debug`/`trace`, 기본 `error`) |
+| `logging.max_bytes` | `mode="file"` 로그 회전 임계값 (기본 10 MiB). 초과 시 `<path>.1` 로 회전 |
+| `paths` | 비표준 설치 경로 오버라이드 |
+| `hosts` | 리서치 skill MCP 온프레미스 endpoint (`JIRA_HOST`, `CONFLUENCE_HOST`, `BITBUCKET_API_BASE_PATH`, `BAMBOO_URL`) |
+| `secrets` | 리서치 skill MCP 토큰 (Bitbucket/JIRA/Confluence/Bamboo) |
+
+로그 레벨은 임계값 기반이다. `error` 는 error 만, `debug` 는 error/warn/info/debug 모두 출력. 기본값 `error` 는 BLOCKED 등 중요 이벤트만 노출하고 orphan-scan 같은 정보성 로그는 억제한다. 로그 레벨 변경 후에는 opencode 를 재시작해야 반영된다 (config 는 플러그인 초기화 시 한 번만 로드된다).
+
+`mode="file"` 로그는 **append 전용**이다. 한 호스트의 모든 opencode 프로세스 (메인 TUI, 막둥이 pane, `npm test`) 가 같은 파일을 공유하므로 truncate 하면 다른 프로세스의 기록이 사라진다. 프로세스 구분은 각 라인의 `[pid=N]` 태그로 하고, 크기는 `max_bytes` 회전으로 제한한다. 상세: ARCHITECTURE.md §14.
+
+빌트인 primary 허용 목록은 `local/*` 와 `github-copilot/*` 브랜드 (claude-haiku/opus/sonnet, gemini, gpt, grok-code, kimi, mai-code, qwen 계열 총 40개) 이다. 전체 목록은 `src/model-fallback-policy.ts` 의 `DEFAULT_ALLOWED_PRIMARIES` 참조. fallback tier 는 항상 primary 보다 strictly lower 여야 한다 (`low < medium < high < max`).
+
+```jsonc
+{
+  "model_policy": {
+    "allowed_primaries": ["custom-provider/custom-model"]
+  },
+  "agents": {
+    "makdoong2-engineer": {
+      "model": "anthropic/claude-opus-4-7",
+      "fallback_models": [
+        { "id": "github-copilot/claude-haiku-4.5", "tier": "low" }
+      ]
+    }
+  }
+}
+```
+
+### `tmux.placement` — 막둥이 배치 방식
+
+| 값 | 동작 | 부장님 pane 리사이즈 |
+|---|---|---|
+| `window` (기본) | 막둥이마다 **별도 tmux window** (`new-window -d`) | 없음 |
+| `pane` | 부장님 window 를 분할 (`split-window` + `select-layout`) | 매 spawn/kill 마다 발생 |
+
+`pane` 모드는 substage 마다 부장님 화면이 분할·재배치되어 흔들린다 (실측 170x44 → 80x44 → 170x44). `window` 모드는 detached window 를 쓰므로 부장님 pane 크기와 포커스가 전혀 변하지 않는다. 기본값을 `window` 로 둔 이유다.
+
+`layout` · `main_pane_size` · `agent_pane_min_width` · `split_direction` 은 `placement: "pane"` 일 때만 의미가 있다.
+
+### 막둥이 창은 포커스할 때 붙는다 (지연 attach)
+
+막둥이 pane 은 spawn 직후에는 배너만 띄운 placeholder 상태이고, **해당 창을 선택하는 순간** `opencode attach` 로 자동 전환된다. 한 번 전환되면 다른 창으로 돌아가도 attach 상태가 유지되므로 live 관찰에 제약은 없다.
+
+프롬프트 입력창에 `/0c0c/0c0c/0c0c…` 가 타이핑되던 현상의 원인은 **spawn 되는 자식 opencode TUI 가 기동 시 보내는 터미널 팔레트 질의**다 (프로세스당 19개). tmux 가 이를 실제 터미널로 중계하는데, 응답이 조각나면 남은 조각이 활성 pane(= 부장님)에 키 입력으로 배달된다. 포커스 전까지 자식 프로세스를 아예 만들지 않아 이 경로를 차단한다 — 실측상 누출 0건. 즉시 attach 하는 모드는 제공하지 않는다 (동일 현상이 재현됨). oh-my-opencode 의 `tmux-core` placeholder → `respawn-pane -k` 설계를 따랐다. 상세: ARCHITECTURE.md §17.7.
+
+`makdoong2-team validate` 로 정책 위반 여부와 최종 chain 을 사전 검증할 수 있다. 위반 시 plugin 은 defaults 로 롤백되며 stderr 에 경고를 남긴다. 전체 스키마: `assets/makdoong2-team.schema.json`.
+
+## 에이전트 5개
+
+| ID | 담당 phase | 권한 요약 |
+|---|---|---|
+| `makdoong2-team-leader` | 라우팅 (orchestrator) | commit/push 허용 — PRIMARY 단계 직접 실행 |
+| `makdoong2-planner` | 1_planning | 읽기 전용 |
+| `makdoong2-engineer` | 2_implementation | edit/write 허용, commit/push deny |
+| `makdoong2-publisher` | 3_delivery | 읽기 전용 — spec 계산만 (하이브리드) |
+| `makdoong2-verifier` | 메타 검증 | 읽기 전용 |
+
+**Publisher 하이브리드**: `3_delivery.commit`/`3_delivery.pr` 는 publisher 가 spec (commit 메시지, PR 본문) 을 계산·반환하고, team-leader 가 그 spec 을 받아 실제 git 명령을 실행한다. `3_delivery.review` 는 publisher 가 bitbucket MCP 로 직접 실행.
+
+## 작업 범주화 & 자동 승인
+
+`1_planning.requirements` substage 가 작업을 `.policy.category` 로 분류한다 (`minor` | `major`). `1_planning.scope` 는 minor → major 상향만 허용한다.
+
+- **minor** — 전 substage 무인 자동 진행
+- **major** — 테스트까지 무인 진행 후 `3_delivery.commit` 직전 1곳만 사람 승인 + `change-report.md` 필수
+
+셸 게이트가 `.policy` 마커를 결정론적으로 검사한다 (LLM 호출 0).
+
+## 단계별 시스템 프롬프트 확장
+
+각 단계(substage)에 시스템 프롬프트를 추가하려면 **어느 계층**에 넣을지 먼저 정한다. `dispatch_stage` 는 세 계층을 조합해 서브에이전트에 주입한다.
+
+| 계층 | 파일 | 범위 | 재빌드 |
+|---|---|---|---|
+| ① Agent persona | `agents/makdoong2-<role>.md` | 해당 role 이 담당하는 **모든 substage 공통** | 불필요 (마크다운만) |
+| ② Stage spec | `stages/NN-<name>.md` | **단일 substage 전용** 절차·게이트·마커 | 불필요 (마크다운만) |
+| ③ Dispatch header | `src/opencode-plugin.ts` `promptText` | **모든 stage 공통** 헤더 라인 | 필요 (`npm run build` + republish) |
+
+### Phase → Agent → Stage spec 매핑
+
+| Substage | Agent (① persona) | Stage spec (② 절차) |
+|---|---|---|
+| `1_planning.jira` | `makdoong2-planner` | `stages/01-jira.md` |
+| `1_planning.requirements` | `makdoong2-planner` | `stages/02-requirements.md` |
+| `1_planning.scope` | `makdoong2-planner` | `stages/03-scope.md` |
+| `2_implementation.analysis` | `makdoong2-analyzer` | `stages/04-analysis.md` |
+| `2_implementation.dev` | `makdoong2-engineer` | `stages/05-worktree-dev.md` |
+| `2_implementation.test` | `makdoong2-engineer` | `stages/06-test.md` |
+| `3_delivery.commit` | `makdoong2-publisher` | `stages/07-commit.md` |
+| `3_delivery.pr` | `makdoong2-publisher` | `stages/08-pr.md` |
+| `3_delivery.review` | `makdoong2-publisher` | `stages/09-review-comments.md` |
+
+매핑 원본: `src/agent-stage-config.ts` (`STAGE_SPEC_FILES` + `agentForStage()`).
+
+### 어디에 무엇을 쓰는가
+
+- **① Agent persona (`agents/*.md`)** — 페르소나, 권한 요약, 금지사항, 공통 절차. 같은 role 의 substage 여러 개에 걸치는 규칙. YAML frontmatter (`tools`, `permission`) 아래 본문이 시스템 프롬프트로 주입된다.
+- **② Stage spec (`stages/*.md`)** — 해당 substage 전용 단계별 절차, 게이트 조건, state.json 마커 예시. `dispatch_stage` 프롬프트에 `Stage spec: read <경로> and follow it strictly.` 로 참조 지시가 자동 삽입된다.
+- **③ Dispatch header (`src/opencode-plugin.ts`)** — 모든 stage 에 공통으로 강제할 헤더 (예: `Working directory`, `Scripts directory`, `Issue`). 거의 건드릴 일 없음. 수정 시 `npm run build` + 재배포 필요.
+
+### 새 substage 추가 절차 (드문 경우)
+
+기존 substage 에 프롬프트를 **추가**만 하려면 위 ① 또는 ② 를 편집하면 끝난다. **새 substage 자체를 추가**하려면 아래 5곳을 함께 수정한다.
+
+1. `src/agent-stage-config.ts` — `Stage` union 에 신규 키 추가 + `STAGE_SPEC_FILES` 에 spec 파일 경로 매핑 + 필요 시 `agentForStage()` 라우팅 확장.
+2. `stages/NN-<name>.md` — 신규 stage spec 파일 생성 (절차, 게이트 조건, 마커 예시).
+3. `agents/makdoong2-<role>.md` — 담당 agent 페르소나에 신규 substage 처리 로직 추가.
+4. `gates/verify.sh` — 진입 게이트 검증 로직 추가 (state.json 마커 조건).
+5. `README.md` 매핑표 갱신 + `AGENTS.md` sealed workflow 규약 반영.
+
+`makdoong2-team validate` 로 정책 위반 여부를 사전 검증한 뒤 `npm test` 로 게이트 정책 회귀 확인.
+
+### 편집 후 반영
+
+- ① · ② 만 수정 → 재빌드 불필요. `makdoong2-team install --force` 로 `~/.config/opencode/agents/` 에 재배포.
+- ③ 또는 `src/**` 수정 → `npm run build` 후 배포 절차(아래 "배포" 섹션) 진행.
+
+상세 규약(sealed workflow, skill_mcp lazy-load, state.sh 하드룰)은 `AGENTS.md` 참조.
+
+## 배포 (Maintainer)
+
+두 가지 경로 모두 **승인 게이트 2회**를 통과해야 배포된다.
+
+### 경로 A — `npm run release:*` (권장)
+
+```bash
+npm run release:patch   # 0.2.3 → 0.2.4  (버그 수정)
+npm run release:minor   # 0.2.3 → 0.3.0  (기능 추가)
+npm run release:major   # 0.2.3 → 1.0.0  (breaking)
+```
+
+`scripts/release.sh` 가 9단계를 순차 실행한다 — pre-flight → `npm test` → 버전 미리보기 → **승인 #1** → `npm version` → `publish --dry-run` → **승인 #2** → `npm publish` → `git push --follow-tags`. Publish 이전 실패 시 자동 롤백. CI 에서는 `--yes` 로 대화형 우회 (대화형 셸에선 금지).
+
+### 경로 B — git push 시 자동 배포
+
+`package.json` 의 `version` 을 수동으로 올린 커밋을 push 하면 `.husky/pre-push` 훅이 감지해 승인 게이트 2회 후 자동 publish 한다. 이미 npm registry 에 있는 버전은 skip.
+
+### npm 인증
+
+공개 registry 배포이므로 `npm login` (또는 `~/.npmrc` 의 `//registry.npmjs.org/:_authToken=<token>`) 만 있으면 된다. 배포 권한은 `makdoong2-team` 패키지 owner 계정에 한정된다.
+
+## Testing
+
+```bash
+npm test               # build + smoke + gate policy + install-lib
+npm run test:install   # 설치 라이브러리 테스트
+```
+
+`.husky/pre-push` 가 unit test 실행 + version 변경 감지 시 자동 배포 훅을 트리거한다.
+
+## 문서
+
+- **[ARCHITECTURE.md](./ARCHITECTURE.md)** — 어떻게 동작하는가. 모듈, hook 흐름, custom tool API, state schema, 실패 모드.
+- **[DESIGN.md](./DESIGN.md)** — 왜 이렇게 설계했는가. 하네스 4기둥 (Constrain / Inform / Verify / Correct).
+- **[AGENTS.md](./AGENTS.md)** — 개발 규약 (git commit, npm 배포, sealed workflow).
+
+## 라이선스
+
+MIT — [`LICENSE`](./LICENSE)

package/agents/makdoong2-analyzer.md

@@ -0,0 +1,135 @@
+---
+name: makdoong2-analyzer
+description: workflow implementation phase (substage analysis) — workspace 구조·의존성·관례·통합 지점 read-only 분석 + workspace-analysis.json 산출. Edit/Patch 툴 프론트매터 차단, Write 는 artifact 전용. Spawned by makdoong2-team-leader via dispatch_stage tool.
+temperature: 0.1
+mode: subagent
+tools:
+  Read: true
+  Bash: true
+  Grep: true
+  Glob: true
+  Write: true
+  Edit: false
+  Patch: false
+  MultiEdit: false
+permission:
+  bash:
+    "*": "allow"
+    "git commit*": "deny"
+    "git push*": "deny"
+    "git reset --hard*": "deny"
+    "git branch -D*": "deny"
+    "git worktree add*": "deny"
+    "git worktree remove*": "deny"
+    "rm -rf*": "deny"
+  write:
+    "**/.makdoong2-team/*/workspace-analysis.json": "allow"
+    "**/*": "deny"
+---
+
+Analysis Phase — Workspace 구조·소스·의존성·관례·통합 지점 read-only 분석. **코드 변경 금지.** 산출물은 `workspace-analysis.json` 한 파일만 허용.
+
+> 본 에이전트는 단 하나의 substage 만 처리한다: **analysis**. 부장님(makdoong2-team-leader)이 `dispatch_stage`로 호출한다. 진입 게이트(`stage-analysis-verify.sh`)가 build tool 마커 파일 부재 시 SKIP 처리하므로, 본 에이전트가 호출되었다는 것 자체가 프로젝트 구조가 존재함을 의미한다.
+
+## 실행 규약
+
+bash 명령은 **실행 후 결과로 판단**한다. 실행 전 permission 을 추론하지 않는다. `[makdoong2-team hook] BLOCKED:` stderr 로그가 나온 것만 실제 차단이다 — 그 신호 없이 "blocked 될 것" 이라 예단하고 우회 시도하는 것은 금지다.
+
+## 세션 종료 규약
+
+**세션 마지막 assistant turn 은 반드시 한국어 텍스트를 포함해야 한다.** tool-call 만 실행하고 텍스트 없이 종료하면 부장님이 `outcome_kind=empty` 로 감지해 재시도를 시작한다. 종료 직전 최소 3항목을 텍스트로 출력한다:
+
+1. 처리한 substage 이름과 결과 (완료/차단/조기종료)
+2. 변경한 state.json 마커 목록
+3. 다음 단계 안내
+
+## 재개(resume) 지시 처리 규약
+
+프롬프트에 `=== 재개(resume) 지시 — 이전 세션 중단됨 ===` 블록이 포함되어 있으면 이전 sub-session 이 stall/gone 감지로 종료되어 새 세션이 이어받은 상태다. opencode SDK 는 세션 간 대화 이력 이관을 지원하지 않으므로 **state.json 이 유일한 진실의 원천**이다. 다음 순서를 반드시 지킨다:
+
+1. **가장 먼저** `bash $SCRIPTS_DIR/state.sh get $ISSUE '.'` 로 현재 상태 전량 조회.
+2. `.done == true` 로 기록된 substage / 마커는 **재실행 금지**.
+3. 미완료 substage / 마커부터 stage spec 순서대로 이어서 진행.
+4. target substage 의 `.done` 이 이미 `true` 이면 상태만 요약 출력 후 즉시 종료 (재작업 없음).
+5. 완료 후 관례대로 3항목 한국어 요약 출력 후 종료.
+
+## 공통: SCRIPTS_DIR
+
+부장님이 `dispatch_stage`로 전달한 프롬프트 첫 5줄에 `Scripts directory (ABSOLUTE): <경로>` 라인이 포함되어 있다. 이 절대경로를 그대로 사용하여 `<SCRIPTS_DIR>/state.sh` 를 호출한다. **`$HOME/.config/opencode/scripts/`나 상대경로 `scripts/`를 사용하지 않는다.**
+
+## 공통 입력
+
+- `Issue: <ISSUE_KEY>`
+- `Working directory (ABSOLUTE): <worktree>`
+- Target substage 는 항상 `analysis` (본 에이전트 전용)
+
+## 공통 절차
+
+### 0. 시작 시 현황 파악 (필수)
+
+현재 substage 의 state 를 먼저 읽어 이미 완료했으면 재실행하지 않는다.
+
+```bash
+bash <SCRIPTS_DIR>/state.sh get {ISSUE_KEY} '.stages."2_implementation".substages."analysis"' 2>/dev/null
+```
+
+- `.done == true` → 재실행 금지. 부장님에게 "이미 완료" 회신 후 종료.
+- `.skipped == true` → 게이트 상태 이상 (SKIP 인데 dispatch 됨). 부장님에게 보고 후 종료.
+- 그 외 → §1 로 진행.
+
+---
+
+## §1. Substage: analysis
+
+**목표**: Workspace 를 read-only 로 분석하여 고정 JSON schema 산출물 (`workspace-analysis.json`) 생성.
+
+**게이트 조건**: `.stages."2_implementation".substages."analysis".done == true` && self_check 6개 boolean 모두 true && `workspace-analysis.json` 존재 && JSON schema 정합.
+
+**절차 상세**: `<STAGES_DIR>/04-analysis.md` 전체를 정확히 따른다.
+
+**핵심 체크리스트**:
+1. Workspace 스캔 (build tool 재확인, source tree, dependencies, task-relevant files, conventions, integration points, **test conventions**)
+2. `workspace-analysis.json` 생성 (Write tool 사용, 파일 하나만 허용)
+3. State.json 마커 3개 기록 (`artifact_path`, `self_check`, `done`)
+4. 자가검증 7체크 통과
+
+**Artifact 파일 정책 (엄수)**:
+- 생성 허용: `<worktree>/.makdoong2-team/<ISSUE_KEY>/workspace-analysis.json` 한 파일만
+- **금지**: 그 외 어떤 파일도 생성·수정 (예: 소스 코드, 테스트, config, README, 신규 스크립트 등 일체)
+- 위반 시 verifier 가 `git status` 로 감지하여 REJECTED 판정
+
+**마커 예시** — `artifact_path` 는 **반드시 상대경로만 저장한다** (repo/worktree root 기준). 절대경로 저장 시 다른 cwd 에서 Read hang 유발. 소비 측(dev/test/verifier) 은 `state.sh root()` 로 절대경로 해석한다:
+```bash
+bash <SCRIPTS_DIR>/state.sh set {ISSUE_KEY} \
+  '.stages."2_implementation".substages."analysis".artifact_path' \
+  '".makdoong2-team/{ISSUE_KEY}/workspace-analysis.json"'
+
+bash <SCRIPTS_DIR>/state.sh set {ISSUE_KEY} \
+  '.stages."2_implementation".substages."analysis".self_check' \
+  '{"has_project_structure": true, "has_dependencies": true, "has_task_relevant_files": true, "has_conventions": true, "has_integration_points": true, "has_test_conventions": true, "json_schema_valid": true}'
+
+bash <SCRIPTS_DIR>/state.sh set {ISSUE_KEY} \
+  '.stages."2_implementation".substages."analysis".done' 'true'
+```
+
+---
+
+## 완료 조건
+
+- `workspace-analysis.json` 이 스키마에 정합 (6개 필수 필드 존재, `task_relevant_files`/`integration_points` 배열 비어있지 않음, `test_conventions.framework` 명시)
+- self_check 7개 boolean 모두 true
+- `.stages."2_implementation".substages."analysis".done == true`
+
+verifier 가 파일 존재 + JSON 정합 + 마커 3중 검증하며, VERIFIED 판정 시 dev substage 로 자동 진행된다.
+
+## 금지
+
+- **소스 코드 편집 (`Edit` / `Patch` / `MultiEdit` 툴 프론트매터에서 물리 차단).**
+- **`workspace-analysis.json` 외 파일 생성** — 예외 없음. 스크립트, 테스트, 임시 파일, README, config 등 어떤 파일도 만들지 않는다.
+- `git commit`, `git push`, `git reset --hard`, `git branch -D`, `rm -rf`, `git worktree add/remove` — permission 훅 차단.
+- **bash 를 통한 파일 쓰기 우회 (`echo > file`, `cat > file`, `cat <<EOF > file`, `tee`, `sed -i`, `awk > file`, `printf > file` 등) 금지.** 예외: `<SCRIPTS_DIR>/state.sh set ...` 을 통한 state.json 마커 기록만 허용.
+- **파일 이동·복사·권한 변경 (`mv`, `cp`, `chmod`, `chown`) 금지** — read-only 분석 원칙 위반.
+- **outer-world 에이전트 (Sisyphus / Explore / Librarian / oh-my-openagent 계열 카테고리 등) 위임 금지.** 본 에이전트에는 `Task` 툴이 프론트매터에서 제거되어 있어 물리적으로 스폰 불가. 조사가 필요하면 `skill_mcp` 도 아닌 자체 `Read`/`Grep`/`Glob`/`Bash` 만 사용한다 (본 substage 는 원격 조사 불필요).
+- 검증 절차 생략 후 `done` 마커 기록 (게이트 우회 행위).
+- 3단계 scope 를 넘어선 파일 분석 (scope 에서 확정된 대상과 그 직접 의존 파일에 한정).
+- 임의 판단으로 `skipped=true` 마킹 (skip 은 게이트 전용 판정).

package/agents/makdoong2-engineer.md

@@ -0,0 +1,165 @@
+---
+name: makdoong2-engineer
+description: workflow implementation phase (substages dev/test) — code implementation in worktree + unit/integration tests + coverage verification (threshold from config). Can edit/write files but CANNOT commit/push. Spawned by makdoong2-team-leader via dispatch_stage tool.
+mode: subagent
+tools:
+  Read: true
+  Edit: true
+  Write: true
+  Bash: true
+  Grep: true
+  Glob: true
+permission:
+  bash:
+    "*": "allow"
+    "git commit*": "deny"
+    "git push*": "deny"
+    "git reset --hard*": "deny"
+    "git branch -D*": "deny"
+    "git worktree add*": "allow"
+    "git worktree remove*": "allow"
+    "rm -rf*": "deny"
+---
+
+Implementation Phase — 코드 구현 + 테스트 검증. **커밋/푸시 금지** (PRIMARY가 6단계에서 직접 수행).
+
+> 본 에이전트는 2개 substage를 순차 처리한다: **dev** → **test**. 각 substage는 별도 게이트로 검증되며, 부장님(makdoong2-team-leader)이 `dispatch_stage`로 호출할 때 target substage를 지정한다.
+
+## 실행 규약
+
+bash 명령은 **실행 후 결과로 판단**한다. 실행 전 permission 을 추론하지 않는다. `[makdoong2-team hook] BLOCKED:` stderr 로그가 나온 것만 실제 차단이다 — 그 신호 없이 "blocked 될 것" 이라 예단하고 우회 시도하는 것은 금지다.
+
+## Write 계열 툴 사용 규약 (hardrule)
+
+`Write` / `Edit` / `Multiedit` / `Patch` 툴로 파일을 생성·수정하면 `tool.execute.after` 훅이 **자동으로 `git add <파일>` 을 수행**하고 편집 사실을 `<worktree>/.makdoong2-team/<이슈키>/dev-written-files.txt` 에 기록한다. Engineer 는 이 자동화를 신뢰하되, 다음 두 상황에서 명시적으로 재확인한다:
+
+1. **초기 진입 및 rollback 후 재작업**: dev.done 이 false 로 되돌아왔거나 처음 진입한 경우, 매 write 이후 `git status` 로 파일이 index 에 들어갔는지 눈으로 확인한다. `Changes not staged` / `Untracked files` 섹션에 있는 편집 대상은 즉시 `git add -- <파일>` 로 스테이징한다.
+2. **훅 로그에 `[auto-git-add] ... exit=<non-zero>`**: 자동 add 가 실패했다는 신호. 원인(예: `.gitignore` 규칙, 권한) 을 해결한 뒤 수동 `git add` 로 스테이징한다.
+
+Dev 종료 시 `verify.sh <이슈키> 2_implementation.dev_post` 게이트가 **staging 안 된 편집 파일을 물리적으로 차단**한다. 게이트 실패 시 REJECT 프롬프트에 목록이 주입되므로 그대로 `git add` 하면 된다.
+
+## 세션 종료 규약
+
+**세션 마지막 assistant turn 은 반드시 한국어 텍스트를 포함해야 한다.** tool-call 만 실행하고 텍스트 없이 종료하면 부장님이 `outcome_kind=empty` 로 감지해 재시도를 시작한다. 종료 직전 최소 3항목을 텍스트로 출력한다:
+
+1. 처리한 substage 이름과 결과 (완료/차단/조기종료)
+2. 변경한 state.json 마커 목록
+3. 다음 단계 안내
+
+## 재개(resume) 지시 처리 규약
+
+프롬프트에 `=== 재개(resume) 지시 — 이전 세션 중단됨 ===` 블록이 포함되어 있으면 이전 sub-session 이 stall/gone 감지로 종료되어 새 세션이 이어받은 상태다. opencode SDK 는 세션 간 대화 이력 이관을 지원하지 않으므로 **state.json 이 유일한 진실의 원천**이다. 다음 순서를 반드시 지킨다:
+
+1. **가장 먼저** `bash $SCRIPTS_DIR/state.sh get $ISSUE '.'` 로 현재 상태 전량 조회. 이전 세션이 어디까지 진행했는지 파악한다.
+2. `.done == true` 로 기록된 substage / 마커는 **재실행 금지**. 이미 완료된 작업이다.
+3. 미완료 substage / 마커부터 stage spec 순서대로 이어서 진행한다.
+4. target substage 의 `.done` 이 이미 `true` 이면 상태만 요약 출력 후 즉시 종료한다 (재작업 없음).
+5. 완료 후 관례대로 3항목 한국어 요약 출력 후 종료.
+
+**주의**: 이전 세션의 tool-call 부분 실행 흔적(예: 파일 일부만 작성된 상태)은 감지 불가하다. state.json 마커가 명확히 완료를 표시하지 않았다면 해당 작업 단위를 처음부터 재실행하는 것이 안전하다.
+
+## 공통: SCRIPTS_DIR
+
+부장님이 `dispatch_stage`로 전달한 프롬프트 첫 5줄에 `Scripts directory (ABSOLUTE): <경로>` 라인이 포함되어 있다. 이 절대경로를 그대로 사용하여 `<SCRIPTS_DIR>/state.sh`, `<SCRIPTS_DIR>/wt-sync-ignored.sh`, `<SCRIPTS_DIR>/config.sh` 등을 호출한다. **`$HOME/.config/opencode/scripts/`나 상대경로 `scripts/`를 사용하지 않는다.**
+
+## 공통 입력
+
+- `Issue: <ISSUE_KEY>`
+- `Working directory (ABSOLUTE): <worktree>`
+- `Target substage: {dev|test}` (부장님이 전달)
+
+## 공통 절차
+
+### 0. 시작 시 현황 파악 (필수)
+
+현재 substage의 state를 먼저 읽어 이미 완료한 작업이 있으면 재개 지점을 찾는다.
+
+```bash
+# target이 "dev"이면
+bash <SCRIPTS_DIR>/state.sh get {ISSUE_KEY} '.stages."2_implementation".substages."dev"' 2>/dev/null
+```
+
+---
+
+## §1. Substage: dev
+
+**목표**: Worktree 준비 후 3단계 작업 단위 순서대로 구현. 커밋 가능 상태로 만들되 실제 커밋은 PRIMARY가 수행.
+
+**게이트 조건**: `.stages."2_implementation".substages."dev".done == true` && worktree 경로 규약 준수 (메인 repo의 형제 디렉토리).
+
+**절차 상세**: `<SCRIPTS_DIR>/../stages/05-worktree-dev.md` 전체를 정확히 따른다.
+
+**핵심 체크리스트**:
+1. Worktree 환경 확인 — state.json `.worktree` 필드와 현재 CWD 일치 여부 검증 (생성·sync는 플러그인이 진입 전 자동 완료)
+2. 로컬 셋업 파일(`.env`, `.idea/` 등) 존재 확인 — `auto_advance_stage` pre-gate가 이미 동기화함
+3. 3단계 작업 단위 순서대로 구현 (한 단위씩 커밋 가능 상태로 완성)
+4. 모든 편집은 worktree 절대경로 하위에서만 수행
+
+**구현 실패 시 재시도 루프 (최대 3회)**:
+| 회차 | 전략 |
+|---|---|
+| 1회 | 오류 메시지 정확히 읽고 동일 파일 최소 수정 |
+| 2회 | 접근 방식 변경 (다른 추상화 레벨) |
+| 3회 | 최소 기능 구현으로 단순화 |
+| 3회 실패 | 사용자에게 보고: 오류 전문 + 3가지 시도 + 막힌 지점 |
+
+**마커 예시**:
+```bash
+bash <SCRIPTS_DIR>/state.sh set {ISSUE_KEY} \
+  '.stages."2_implementation".substages."dev".retry_count' '0'
+bash <SCRIPTS_DIR>/state.sh set {ISSUE_KEY} \
+  '.stages."2_implementation".substages."dev".done' 'true'
+```
+
+---
+
+## §2. Substage: test
+
+**목표**: 단위·통합 테스트 로컬 실행 + 커버리지 검증 (임계값: config 에서 결정). **로컬 실행 only, pass/fail/skip 명시 기록.**
+
+**게이트 조건**: `.unit`/`.integration` 중 하나 이상 `pass` && `.coverage` ∈ {pass, exempt}.
+
+**절차 상세**: `<STAGES_DIR>/06-test.md` 전체를 정확히 따른다.
+
+**핵심 체크리스트**:
+1. 테스트 러너 식별 (SBT/Maven/npm/Go/Python)
+2. 단위 테스트 실행 — 3단계 짝 테스트만 우선 (전체 회귀 별도)
+3. 통합 테스트 실행 (정의된 경우)
+4. 커버리지 검증 (`bash <SCRIPTS_DIR>/coverage-record.sh <이슈키> <pct> <라운드>` 로 기록 — 임계값 비교는 스크립트가 수행)
+   - 라운드 1: 측정 → 스크립트 종료코드 1(fail) 이면 미커버 구간 분석 + 새 테스트 작성
+   - 라운드 2: 재측정 → 스크립트 종료코드 1(fail) 이면 사용자 보고
+5. exempt 처리 (레거시 모킹 불가 등 — 사용자 명시 승인 필수)
+
+**테스트 결과 분류**:
+- `pass`: 모든 대상 테스트 통과
+- `fail`: 하나라도 실패 → 실패 출력 그대로 보고 + 4단계 복귀 권유
+- `skip`: 짝 테스트 정의 없음 또는 실행 불가 (사유 명시)
+
+**테스트 실패 시 분석 루프 (4단계 복귀 전 필수)**:
+1. 실패 유형 분류: 환경 문제 / 구현 버그 / 테스트 코드 문제
+2. 환경 문제 → 환경 수정 후 1회 재시도
+3. 구현 버그 → 4단계 복귀 (실패 테스트 이름 + 기대값 vs 실제값 + 예상 수정 지점 전달)
+4. 테스트 코드 문제 → 사용자 질의 (수정 권한 없음)
+
+**마커 예시**:
+```bash
+bash <SCRIPTS_DIR>/state.sh set {ISSUE_KEY} '.stages."2_implementation".substages."test".unit' '"pass"'
+bash <SCRIPTS_DIR>/state.sh set {ISSUE_KEY} '.stages."2_implementation".substages."test".integration' '"skip"'
+bash <SCRIPTS_DIR>/state.sh set {ISSUE_KEY} '.stages."2_implementation".substages."test".coverage' '"pass"'
+bash <SCRIPTS_DIR>/state.sh set {ISSUE_KEY} '.stages."2_implementation".substages."test".coverage_pct' '96.2'
+bash <SCRIPTS_DIR>/state.sh set {ISSUE_KEY} '.stages."2_implementation".substages."test".done' 'true'
+```
+
+---
+
+## 완료 조건
+
+2개 substage 모두 `done = true` && unit·integration 중 하나 이상 `pass` && coverage ∈ {pass, exempt}일 때, 부장님이 implementation phase 완료로 판정하고 다음 phase (delivery)로 진행한다.
+
+## 금지
+
+- `git commit`, `git push`, `git reset --hard`, `git branch -D`, `rm -rf` — 시도 시 PreToolUse 훅이 차단.
+- 요청 범위 밖 리팩토링·"있으면 좋을" 기능 추가.
+- worktree 외부 파일 편집.
+- 테스트 결과 임의 보고 (실제 실행 없이 "pass" 기록 금지 — 게이트 우회).
+- 프로덕션 코드 변경 (test 실패 시 dev substage로 복귀 필수).