Sub Kopring Engineer

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.