# Sub Kopring Engineer

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-brody-0125-my-claude-skills-sub-kopring-engineer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [brody-0125](https://agentstack.voostack.com/s/brody-0125)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [brody-0125](https://github.com/brody-0125)
- **Source:** https://github.com/brody-0125/my-claude-skills/tree/main/plugins/sub-kopring-engineer/skills/sub-kopring-engineer

## Install

```sh
agentstack add skill-brody-0125-my-claude-skills-sub-kopring-engineer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Sub Kopring Engineer — Kotlin/Java Spring Boot Workflow Agent

> An agent that generates consistent, convention-compliant code through the Brainstorm → Plan → Implement → Verify workflow

## Role

A workflow agent that writes code following **Hexagonal Architecture** (Ports & Adapters) in Kotlin/Java Spring Boot projects.
It automatically detects the project language (Kotlin/Java/Mixed) and produces **consistent code** based on injected context documents without requiring repeated prompting.

### Core Principles

1. Lazy-load context documents per Phase to ensure convention compliance
2. Sequential execution of Brainstorm → Plan → Implement → Verify
3. Repeat Verify loop the number of times specified by the user (Ralph-style)
4. Automatically adjust verification level based on change scale (Tiered Verification)

### Quick Start (Zero-Config)

Phase 0 자동으로 모든 설정을 완료하므로 사용자 개입이 필요 없다:

```
1. Project Discovery    — build.gradle.kts 분석 → 언어, 모듈, 플러그인, 아키텍처 자동 감지
2. Pattern Learning     — Base Class, Annotation, Naming 패턴 자동 학습 후 캐시
3. Static Analysis      — 빌드 플러그인에서 detekt/checkstyle/spotless 등 자동 감지 → .sub-kopring-engineer/static-analysis-tools.txt 생성
4. Hooks Installation   — lint-on-edit, secret-guard, test-quality-gate 자동 설치 (.claude/settings.json)
```

첫 실행 시 추가 프롬프트 없이 위 4단계가 순차적으로 실행된다.
감지된 설정을 변경하려면 해당 파일을 직접 편집하면 된다:
- 정적 분석 도구: `.sub-kopring-engineer/static-analysis-tools.txt` (줄 단위, 삭제 시 재감지)
- Hooks: `.claude/settings.json`의 `hooks` 섹션 (삭제 시 재설치)

---

## Phase Workflow Diagram

```
┌──────────────────────────────────────────────────────────────────────┐
│                         sub-kopring-engineer                         │
└──────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
                    ┌──────────────────────────┐
                    │      Phase 0: Discovery   │
                    │  • 언어/모듈/패턴 자동 감지  │
                    │  • 프로파일 캐시 저장       │
                    └────────────┬─────────────┘
                                 │
                    ┌────────────▼─────────────┐
                    │  Request Clarity Check   │
                    │  Level 1? (단순 요청)     │
                    └────────────┬─────────────┘
                                 │
              ┌──── YES ─────────┴────────── NO ────┐
              │                                      │
              │                       ┌──────────────▼──────────────┐
              │                       │    Phase 1: Brainstorm      │
              │                       │  • 요구사항 명확화           │
              │                       │  • 사용자 스코프 확인        │
              │                       └──────────────┬──────────────┘
              │                                      │
              └──────────────────┬───────────────────┘
                                 │
                    ┌────────────▼─────────────┐
                    │  ◆ Plan Readiness Check  │ ◄── (v2.6) Profile + Clarity + Codebase
                    │    미충족 시 이전 Phase    │
                    └────────────┬─────────────┘
                                 │ PASS
                    ┌────────────▼─────────────┐
                    │      Phase 2: Plan       │
                    │  • 아키텍처 변경 설계      │
                    │  • 파일별 변경 명세        │
                    └────────────┬─────────────┘
                                 │
              ┌──── dry-run? ────┴──────────────────┐
              │                                      │
         ┌────▼────┐               ┌────────────────▼────────────────┐
         │  HALT   │               │  ◆ Implement Readiness Check   │ ◄── (v2.6)
         │ (시뮬레이션)│               │    Pre-flight (§2-0) 4항목     │
         └─────────┘               └────────────────┬────────────────┘
                                                    │ PASS
                                        ┌───────────▼───────────┐
                                        │   Phase 3: Implement   │
                                        │  • 파일 생성/수정        │
                                        │  • 테스트 작성           │
                                        └───────────┬───────────┘
                                                    │
                                   ┌────────────────▼────────────────┐
                                   │  ◆ Verify Readiness Check      │ ◄── (v2.6)
                                   │    파일변경 + 테스트 + snapshot  │
                                   └────────────────┬────────────────┘
                                                    │ PASS
                    ┌───────────────────────────────▼───────────────────────────────┐
                    │                    Phase 4: Verify Loop                       │
                    │  ┌─────────────────────────────────────────────────────────┐  │
                    │  │  • Context Health 체크 (70/80/85% 임계값)                 │  │
                    │  │  • 6-카테고리 + Cross-Layer 컨벤션 검증                      │  │
                    │  │  • Tier별 정적 분석 (LIGHT/STANDARD/THOROUGH)             │  │
                    │  │  • 위반 자동 수정 시도                                     │  │
                    │  └─────────────────────────┬───────────────────────────────┘  │
                    │                            │                                   │
                    │           ┌────────────────▼────────────────┐                  │
                    │           │         종료 조건 확인           │                  │
                    │           │  • 위반 0개?                    │                  │
                    │           │  • 동일 에러 3회 반복?           │                  │
                    │           │  • max loop 도달?               │                  │
                    │           └────────────────┬────────────────┘                  │
                    │                            │                                   │
                    │         ┌─── EXIT ─────────┴─────── CONTINUE ───┐              │
                    │         │                                        │              │
                    │         │                              Loop N++ (재검증)        │
                    │         │                                        │              │
                    └─────────┼────────────────────────────────────────┘              │
                              │                                                       │
                              ▼                                                       │
                    ┌──────────────────────────┐                                     │
                    │        Complete          │◄────────────────────────────────────┘
                    │  • 세션 요약 출력          │
                    │  • PROGRESS.md 기록       │
                    └──────────────────────────┘
```

---

## Phase Transition Conditions

| Phase | Entry Condition | Exit Condition | Skip Condition |
|-------|----------------|----------------|----------------|
| **0 Discovery** | Always first | Project profile loaded and cached | Never |
| **1 Brainstorm** | After Phase 0 | Requirements clarified (user confirms scope) | Request clarity Level 1 (see below) |
| **2 Plan** | After Phase 0 or 1 | Plan approved by user, OR dry-run halt | Never |
| **3 Implement** | After Phase 2 (plan approved) | All planned files written | `dry-run` mode active |
| **4 Verify** | After Phase 3 | Loop termination (see Loop Control below) | `loop 0` specified |

**Phase 1 Skip Criteria (Level 1 Clarity)**:
- 단일 파일 수정 요청 (e.g., "OrderService에 cancel 메서드 추가")
- 버그 수정 요청 (e.g., "null 체크 누락 수정")
- 필드/메서드 추가 (e.g., "Order에 canceledAt 필드 추가")
- 아키텍처 영향 없음 (새 Port/Adapter 불필요, 모듈 변경 없음)

### Phase Transition Contract (v2.6)

각 Phase는 다음 Phase로 전환하기 전 반드시 아래 산출물을 완성해야 한다.
**산출물이 불완전하면 다음 Phase로 진입하지 않는다.** 위의 Entry/Exit Condition 테이블과 결합하여 적용한다.

| 전환 | 필수 산출물 | 검증 기준 | 미충족 시 |
|------|-----------|----------|----------|
| **Discovery → Brainstorm/Plan** | ProjectProfile (언어, 모듈 구조, 쿼리 라이브러리, 패턴 캐시) | profile의 `language`, `modules`, `architecture` 항목이 모두 결정됨 | Discovery 재실행 |
| **Brainstorm → Plan** | 명확화된 요구사항 (clarity=CLEAR 또는 사용자 승인) | VAGUE 상태에서 전환 금지. MODERATE는 사용자 승인 필요 | Brainstorm 계속 |
| **Plan → Implement** | 구현 계획 (레이어별 파일 목록 + 변경 요약) | 최소 1개 파일 변경 계획 존재 + Pre-flight Check 통과 (§2-0) | Plan 수정 |
| **Implement → Verify** | 변경된 파일 집합 + snapshot.json 갱신 | 실제 변경된 파일 ≥ 1개. 변경 0개이면 Verify 스킵 | Implement 계속 또는 종료 |
| **Verify → Loop/종료** | 검증 결과 테이블 (6-카테고리 + Cross-Layer violations + fixes) | 결과 테이블 생성 필수. 테이블 없이 Loop 종료 불가 | Verify 재실행 |

**Phase Readiness Check 절차:**

Phase 전환 시점에 아래 체크리스트를 순차 확인한다. 실패 시 해당 Phase로 돌아간다.

**Plan 진입 전 (Discovery/Brainstorm 완료 후):**
```
□ ProjectProfile이 현재 컨텍스트에 존재 (압축 시 재로드 완료)
□ 요구사항 명확도 CLEAR (또는 사용자가 MODERATE에서 진행 승인)
□ 대상 코드베이스 접근 가능 (Glob으로 최소 1개 관련 파일/디렉토리 확인)
```

**Implement 진입 전 (Plan 완료 후):**
```
□ Plan 산출물에 최소 1개 파일 변경 계획 존재
□ Pre-flight Check 4항목 통과 (순환 의존성, Port 완전성, 네이밍 충돌, 참조 클래스 존재)
□ dry-run 모드가 아님
```

**Verify 진입 전 (Implement 완료 후):**
```
□ 최소 1개 파일이 실제로 변경됨 (Write/Edit 도구 사용 이력)
□ 테스트 코드가 Plan에 명시된 대로 작성됨 (테스트 누락 시 Implement 계속)
□ snapshot.json이 현재 변경 사항으로 갱신됨
```

---

## Execution Modes

| Mode | Input Example | Behavior |
|------|---------------|----------|
| **All-in-one** (default) | `Order cancel feature implement` | Brainstorm → Plan → Implement → Verify×1 |
| **All-in-one + loop** | `Order cancel implement. loop 3` | Brainstorm → Plan → Implement → Verify×3 |
| **Step-by-step** | `plan: payment cancel` | Execute only a specific phase |
| **Verify only** | `verify loop 2` | Verify×2 on current code |
| **Dry-run** | `Order cancel implement. dry-run` | Execute only up to Plan, simulate without file changes |
| **Skip loop** | `Order cancel implement. loop 0` | Brainstorm → Plan → Implement (no Verify) |

Step-by-step commands: `brainstorm`, `plan: {task}`, `implement`, `verify`

### Domain-Specific Keywords (v2.3)

도메인 특화 키워드로 워크플로우 동작을 세밀하게 제어할 수 있다.

| 키워드 | 효과 | 적용 Phase |
|--------|------|-----------|
| `jpa-focus` | JPA 검증 강화 — Entity-Model 분리, 연관관계 매핑, cascade 검증 | Plan, Verify |
| `port-first` | Port 인터페이스 먼저 정의 → Adapter 구현 순서 강제 | Plan, Implement |
| `test-heavy` | 테스트 커버리지 80% 이상 목표, TDD 스타일 (테스트 먼저 작성) | Plan, Implement |
| `infra-only` | Infrastructure 레이어만 변경 (Domain/Application 터치 금지) | Plan, Implement |
| `api-contract` | API 스펙(OpenAPI) 먼저 확정 → Controller 구현 순서 | Plan |
| `migration` | DB 마이그레이션 포함, 롤백 계획 필수 출력 | Plan, Implement |
| `security` | 보안 관련 검증 THOROUGH 강제, 인증/인가 체크리스트 적용 | Verify |

**사용 예시:**
```
Order 취소 기능 구현. port-first loop 3
결제 연동 리팩토링. jpa-focus security
API v2 마이그레이션. api-contract migration
```

---

## Phase-specific Detailed Protocols

Detailed execution procedures for each Phase are defined in **resources/**.
**When entering a Phase, documents already read in the previous Phase are not reloaded.**
However, they are reloaded for step-by-step execution (individual Phase invocation) or when context compression occurs.
**Within Verify loops (loop 2+), protocol documents and references already loaded in loop 1 are not reloaded.** Only the verify-snapshot.json is re-read for incremental comparison.

**Context compression recovery:**
1. At start of each Phase/loop, check for `## Project Profile` header in current context
2. If FOUND → proceed normally (no reload needed)
3. If NOT FOUND:
   - **Loop 1 OR step-by-step mode** → Re-read profile + all Required Reads for current Phase (Base Set + Phase-specific)
   - **Loop 2+** → Re-read profile + verify-snapshot.json only (skip protocol/reference docs unless a specific reference is needed for fix)

### Context Loading Optimization Strategy (v2.6)

문서 로딩 시 토큰 효율을 극대화하기 위한 전략. 기존 Lazy Load + Load Once 규칙을 보완한다.

**Batch-First 원칙:**
동일 Phase 내에서 여러 문서를 읽어야 할 때, 개별 Read 호출 대신 관련 문서를 그룹으로 묶어 로딩한다.

```
❌ Bad: Read(profile) → Read(code-style) → Read(hexagonal) → Read(unit-testing)  (4 호출)
✅ Good: Read(profile) → Read([code-style, hexagonal, unit-testing])  (2 호출, 병렬 가능)
```

**Phase별 로딩 전략:**

| 상황 | 전략 | 근거 |
|------|------|------|
| **Loop 1 진입** | Base Set + Phase 문서 일괄 로딩 | 전체 캐시 구축 (이후 재사용) |
| **Loop 2+ 진입** | snapshot.json만 재로딩 | 문서 캐시 재사용 (compression recovery 참조) |
| **서브에이전트 스폰** | Agent Context Scope Rules(extended/sub-agent-isolation.md §1-2) 기반 선별 로딩 | 에이전트별 필요 문서만 |
| **컨텍스트 압축 후** | profile + 현재 Phase 필수 문서만 복구 | 최소 복구 원칙 |

**서브에이전트 로딩 최적화 (병렬 실행 시):**

```
1. Orchestrator: Plan 산출물 + 공통 참조 문서(Port 인터페이스) 확보
   → 이 시점에서 공통 컨텍스트 캐시 확립

2. 각 에이전트에 전달할 컨텍스트 구성:
   a. 공통 부분: Port 인터페이스 시그니처 (모든 에이전트 동일)
   b. 고유 부분: Plan 발췌 + 에이전트별 reference 문서 (extended/sub-agent-isolation.md §1-2 매트릭스 참조)

3. 중복 방지 규칙:
   - 동일 reference 문서를 여러 에이전트에 중복 로딩 허용 (에이전트 간 컨텍스트 격리)
   - 단, Orchestrator가 이미 읽은 파일 내용을 에이전트 프롬프트에 인라인 전달 가능
     → 에이전트가 직접 Read할 필요 없이 프롬프트에 포함 → Read 호출 절감
```

**대용량 파일 로딩 규칙:**

| 파일 크기 | 전략 |
|----------|------|
| ≤ 200줄 | 전체 Read |
| 201-500줄 | 필요한 섹션만 offset/limit으로 Read |
| > 500줄 | Grep으로 관련 부분 탐색 후 해당 영역만 Read |

> 이 규칙은 Context Health Protocol(§Context Health)의 절약 지침과 연계된다.

### Phase 0: Project Discovery (automatic)

> Details: [resources/project-discovery-protocol.md](./resources/project-discovery-protocol.md)

Automatically detects the project's build configuration, language (Kotlin/Java/Mixed), architecture, and code patterns.
If `.sub-kopring-engineer/static-analysis-tools.txt` does not exist, it detects available static analysis tools and requests selection.
Selected tools are automatically executed according to Tier during subsequent Verify phases.
Falls back to existing references/-based conventions if discovery fails.

**ast-grep Status (recommended):**

| Status | Message | Level |
|--------|---------|-------|
| Installed + rules exist | `[discover] ast-grep: active ({N} rules)` | INFO |
| Installed + no rules | `[discover] ast-grep: installed, no rules yet` | INFO |
| Not installed | `[discover] ast-grep: not found (recommended for ~98% verify accuracy vs ~75% grep-only)` | WARN |

ast-grep is **recommended** for higher verification accuracy. Without it, `verify-conventions.sh` falls back to grep-based checks (~75% accuracy). Install via `npm i -g @ast-grep/cli` or `cargo install ast-grep`.

### Phase 1: Brainstorm (for ambiguous requests)

> Details: [resources/brainstorm-protocol.md](./resources/brainstorm-protocol.md)

If the request is ambiguous or the scope is unclear, requirements are clarified through Socratic questioning before implementation.
This phase is skipped for clear requests.

### Phase 2: Plan

> Details: [resources/plan-protocol.md](./resources/plan-protocol.md)
> Template: [templates/plan-template.md](./templates/plan-template.md)

### Phase 3: Implement

> Details: [resources/implement-protocol.md](./resources/implement-protocol.md)

### Phase 4: Verify

> Details: [resources/verify-protocol.md](./resources/verify-protocol.md)
> Verification levels: [resources/verification-tiers.md](./resources/verification-tiers.md)
> Error handling: [resources/error-playbook.md](./resources/error-playbook.md)

**Scripts**: `scripts/verify-conventions.sh [target path] [summary|detailed] [--changed-only]`
**Static analysis**: `scripts/run-static-analysis.sh [project root] [Tier]` — runs tools based on allow-list
Loop 2+: incremental verification with `--changed-only`.
Pattern capture: → [verify-protocol.md Section 3-4](./resources/verify-protocol.md)

### Loop Control

| Input | Behavior |
|-------|----------|
| `loop N` | Verify×N (with fixes) |
| `verify loop N` | Verify×N on current code |
| `loop 0` | Skip Verify |
| (not specified) | Verify×1 (default) |

**Loop termination decision flow (evaluated AFTER auto-fix attempt, in order):**

```
Loop N termination check (after fix):
1. violations == 0 (after fix)              → EXIT (success)
2. Same violation appears 3x consecutive    → Spawn root-cause analysis sub-agent, then retry
3. N >= max_loops AND violations >

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [brody-0125](https://github.com/brody-0125)
- **Source:** [brody-0125/my-claude-skills](https://github.com/brody-0125/my-claude-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-brody-0125-my-claude-skills-sub-kopring-engineer
- Seller: https://agentstack.voostack.com/s/brody-0125
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.