Update project structure and rules

.gitignore

@@ -51,3 +51,6 @@ rust/Cargo.lock
 .DS_Store
 Thumbs.db
 Desktop.ini
+
+# ── Agent-Ops private rules ───────────────────────
+agent-ops/rules/private/

CLAUDE.md

@@ -0,0 +1,17 @@
+# 공통 규칙
+
+- 기존 구조를 우선한다. 새 파일 생성보다 기존 파일 수정을 우선한다.
+- 코드 변경 전 관련 domain rule을 먼저 확인한다.
+- 요청 범위를 넘는 변경을 하지 않는다.
+- 불확실하면 단정하지 말고 후보를 제시한다.
+
+아래 요청은 `agent-ops/skills/common/router.md`를 읽고 수행한다.
+- agent-ops 초기화
+- domain rule 생성
+- skill 생성
+- git commit / git push
+- 버전 올려줘
+- agent-ops 업데이트 / 진입 파일 재적용
+
+`agent-ops/rules/project/rules.md`와
+`agent-ops/rules/private/rules.md`를 읽고 작업을 시작한다. 파일이 없을경우 무시한다.

agent-ops/rules/project/domain/dart/rules.md

@@ -0,0 +1,37 @@
+# dart
+
+## 목적 / 책임
+
+Toki Socket의 Dart/Flutter 구현체를 담당한다. ProtobufClient, ProtobufServer 등 핵심 클래스를 제공하며, 크로스 언어 테스트의 기준 구현으로 동작한다.
+
+## 포함 경로
+
+- `dart/lib/` — 공개 API 및 구현
+- `dart/test/` — 동일 언어 단위/통합 테스트
+- `dart/crosstest/` — 크로스 언어 테스트 (Go, Kotlin과 연동)
+- `dart/pubspec.yaml` — 패키지 의존성
+
+## 제외 경로
+
+- `dart/lib/src/packets/` — protocol 도메인
+
+## 주요 구성 요소
+
+- `ProtobufClient` — 소켓 클라이언트 기반 클래스
+- `ProtobufServer` — 소켓 서버 기반 클래스
+
+## 유지할 패턴
+
+- `dart pub get` 후 `dart test`로 테스트 실행
+- crosstest는 상대방 언어 서버/클라이언트가 실행 중인 상태에서 수행
+- Available 표시 조건: 동일 언어 테스트 + 크로스 언어 테스트 통과
+
+## 다른 도메인과의 경계
+
+- **protocol**: proto 타입을 사용하지만, proto 파일 자체는 protocol 도메인
+- **go/kotlin**: crosstest에서 상호 연동하지만, 각 구현체 내부 로직은 독립
+
+## 금지 사항
+
+- Dart 구현체에 Go/Kotlin 특화 로직을 추가하지 않는다
+- proto 원본 파일 변경 시 proto 도메인 규칙을 먼저 따른다

agent-ops/rules/project/domain/go/rules.md

@@ -0,0 +1,40 @@
+# go
+
+## 목적 / 책임
+
+Toki Socket의 Go 구현체를 담당한다. TCP/WebSocket 서버·클라이언트, TLS 지원, 타입 헬퍼 함수를 제공하며, 서버·툴링·스크립팅 용도로 사용된다.
+
+## 포함 경로
+
+- `go/*.go` — 핵심 구현 (packets/ 제외)
+- `go/test/` — 동일 언어 테스트
+- `go/crosstest/` — 크로스 언어 테스트
+- `go/go.mod`, `go/go.sum` — 모듈 의존성
+- `go/examples/` — 사용 예제
+
+## 제외 경로
+
+- `go/packets/` — protocol 도메인
+
+## 주요 구성 요소
+
+- `TcpServer` / `TcpClient` — TCP 서버/클라이언트
+- `WsServer` / `WsClient` — WebSocket 서버/클라이언트
+- `Communicator` — 메시지 라우팅 및 요청-응답 상관관계 공통 로직
+- `AddListenerTyped`, `AddRequestListenerTyped`, `SendRequestTyped` — 타입 헬퍼
+
+## 유지할 패턴
+
+- `go test ./...`로 테스트 실행
+- `ParserMap`으로 타입명 → 파서 함수 등록
+- TLS 변형은 기본 구현과 같은 인터페이스 유지
+
+## 다른 도메인과의 경계
+
+- **protocol**: packets/ 패키지를 import하지만, 패키지 내용은 protocol 도메인
+- **dart/kotlin**: crosstest에서 상호 연동
+
+## 금지 사항
+
+- `go/packets/` proto 파일을 메시지 스키마 변경 목적으로 편집하지 않는다
+- Communicator에 애플리케이션 도메인 로직(인증, 세션 등)을 추가하지 않는다

agent-ops/rules/project/domain/kotlin/rules.md

@@ -0,0 +1,35 @@
+# kotlin
+
+## 목적 / 책임
+
+Toki Socket의 Kotlin/Android 구현체를 담당한다. Android 및 JVM 환경을 대상으로 하며, 현재 구현 진행 중이다.
+
+## 포함 경로
+
+- `kotlin/src/` — 구현 소스
+- `kotlin/crosstest/` — 크로스 언어 테스트
+- `kotlin/build.gradle.kts`, `kotlin/settings.gradle.kts` — Gradle 빌드 설정
+
+## 제외 경로
+
+- `kotlin/src/**/packets/` — protocol 도메인
+
+## 주요 구성 요소
+
+- (구현 진행 중 — Dart/Go 구조 참고)
+
+## 유지할 패턴
+
+- `./gradlew test`로 테스트 실행
+- `./gradlew run -PmainClass=...`으로 crosstest 실행
+- Available 표시 조건: 동일 언어 테스트 + 크로스 언어 테스트 통과
+
+## 다른 도메인과의 경계
+
+- **protocol**: proto 타입을 사용하지만, 스키마 정의는 protocol 도메인
+- **dart/go**: crosstest에서 상호 연동
+
+## 금지 사항
+
+- Kotlin proto 복사본에서 메시지 스키마를 변경하지 않는다
+- 아직 Available이 아니므로 README의 구현 상태를 임의로 변경하지 않는다

agent-ops/rules/project/domain/protocol/rules.md

@@ -0,0 +1,39 @@
+# protocol
+
+## 목적 / 책임
+
+와이어 포맷 명세와 proto 정의를 관리한다. PacketBase 프레이밍, 타입 라우팅, 요청-응답 상관관계, 하트비트의 공식 계약을 정의한다.
+
+## 포함 경로
+
+- `dart/lib/src/packets/` — proto 원본 및 Dart 생성 코드 (정식 원본)
+- `go/packets/` — Go용 proto 복사본 (go_package 옵션만 추가)
+- `kotlin/src/**/packets/` — Kotlin용 proto 복사본 (Java 패키지 옵션만 추가)
+- `PROTOCOL.md` — 공식 와이어 포맷 명세
+- `VERSIONING.md` — 프로토콜/패키지 버전 정책
+
+## 제외 경로
+
+- `dart/lib/src/` (packets/ 외) — Dart 구현체 로직 (dart 도메인)
+- `go/*.go` (packets/ 외) — Go 구현체 로직 (go 도메인)
+
+## 주요 구성 요소
+
+- `message_common.proto` — PacketBase, 메시지 타입 정의 (Dart 원본)
+- `PacketBase` — 모든 패킷의 공통 래퍼 (type_name, payload, correlation_id)
+
+## 유지할 패턴
+
+- proto 원본은 `dart/lib/src/packets/`에서만 편집
+- Go/Kotlin proto는 언어별 옵션만 추가. 메시지 스키마는 건드리지 않는다
+- 변경 후 반드시 `tools/generate_proto.sh` + `tools/check_proto_sync.sh` 실행
+
+## 다른 도메인과의 경계
+
+- **dart/go/kotlin**: 구현체가 proto 타입을 사용하지만, 타입 정의 자체는 protocol 도메인
+- **tools**: proto 생성/검증 스크립트는 tools 도메인. proto 파일 자체는 protocol 도메인
+
+## 금지 사항
+
+- proto 파일을 Go/Kotlin 복사본에서 직접 편집하지 않는다 (메시지 스키마 변경은 Dart 원본에서만)
+- PROTOCOL.md에 정의되지 않은 프레이밍 방식을 구현체에서 임의로 추가하지 않는다

agent-ops/rules/project/domain/tools/rules.md

@@ -0,0 +1,34 @@
+# tools
+
+## 목적 / 책임
+
+Proto 생성·동기화 스크립트와 크로스 언어 테스트 인프라를 담당한다. 모든 언어 구현체가 공통으로 사용하는 빌드 도구를 관리한다.
+
+## 포함 경로
+
+- `tools/` — proto 생성/검증 스크립트
+- `*/crosstest/` — 각 언어의 크로스 언어 테스트 진입점
+
+## 제외 경로
+
+- `dart/lib/`, `go/*.go`, `kotlin/src/` — 각 언어 구현체 도메인
+
+## 주요 구성 요소
+
+- `tools/generate_proto.sh` — 모든 언어용 proto 바인딩 생성
+- `tools/check_proto_sync.sh` — 언어 간 proto 스키마 동기화 검증
+
+## 유지할 패턴
+
+- proto 변경 후 항상 generate → check_sync 순서로 실행
+- crosstest는 상대 서버가 먼저 시작된 상태에서 클라이언트 측 실행
+
+## 다른 도메인과의 경계
+
+- **protocol**: 스크립트가 proto 파일을 읽지만, proto 파일 자체는 protocol 도메인
+- **dart/go/kotlin**: crosstest 코드는 각 언어 도메인 경로에 있지만 tools 도메인으로 분류
+
+## 금지 사항
+
+- `check_proto_sync.sh` 실패를 무시하고 다음 단계로 진행하지 않는다
+- crosstest를 단일 언어 unit test로 대체하지 않는다

agent-ops/rules/project/rules.md

@@ -0,0 +1,60 @@
+# 프로젝트 규칙
+
+## 응답 언어
+
+한국어로 응답한다.
+
+## 프로젝트 개요
+
+**Toki Socket** — 다중 언어/플랫폼 간 양방향 통신을 위한 바이너리 소켓 프로토콜 라이브러리.
+
+- Protocol Buffers 기반 직렬화
+- TCP 4바이트 빅엔디안 길이 프리픽스 프레이밍 / WebSocket 바이너리 프레임
+- 타입 기반 메시지 라우팅, 요청-응답 상관관계, 내장 하트비트
+- 현재 구현 완료: Dart, Go / 진행 중: Kotlin / 계획: C#, Swift, Python, Rust
+
+## 주요 구조
+
+```
+dart/          — Dart/Flutter 구현체 (lib/, test/, crosstest/)
+go/            — Go 구현체 (*.go, test/, crosstest/)
+kotlin/        — Kotlin/Android 구현체 (src/, crosstest/)
+tools/         — proto 생성/동기화 스크립트
+PROTOCOL.md    — 와이어 포맷 명세 (정식 스펙)
+PORTING_GUIDE.md — 새 언어 구현 가이드
+VERSIONING.md  — 프로토콜/패키지 버전 정책
+```
+
+## 기술 스택
+
+| 영역 | 기술 |
+|------|------|
+| 직렬화 | Protocol Buffers (proto3) |
+| 전송 | TCP, WebSocket/WSS |
+| Dart | dart pub, protoc_plugin |
+| Go | Go modules, google.golang.org/protobuf |
+| Kotlin | Gradle, protobuf-kotlin |
+| Proto 관리 | tools/generate_proto.sh, tools/check_proto_sync.sh |
+
+## 프로젝트 특화 컨벤션
+
+- proto 정의는 `dart/lib/src/packets/message_common.proto`가 정식 원본이다. Go/Kotlin은 언어별 옵션(go_package, java 패키지)만 추가 허용
+- proto 변경 시 반드시 `tools/generate_proto.sh` 실행 후 `tools/check_proto_sync.sh`로 동기화 확인
+- 새 언어 구현은 PORTING_GUIDE.md에 따라 동일 언어 테스트 + 크로스 언어 테스트 통과 후 Available 표시
+- 프로토콜 버전과 패키지 버전은 분리 관리 (VERSIONING.md 참조)
+
+## 도메인 매핑
+
+| 경로 패턴 | 도메인 | rules.md |
+|----------|--------|----------|
+| `dart/**` | dart | `agent-ops/rules/project/domain/dart/rules.md` |
+| `go/**` | go | `agent-ops/rules/project/domain/go/rules.md` |
+| `kotlin/**` | kotlin | `agent-ops/rules/project/domain/kotlin/rules.md` |
+| `dart/lib/src/packets/`, `go/packets/`, `kotlin/src/**/packets/` | protocol | `agent-ops/rules/project/domain/protocol/rules.md` |
+| `tools/**`, `*/crosstest/**` | tools | `agent-ops/rules/project/domain/tools/rules.md` |
+
+## 스킬 라우팅
+
+| 요청 키워드 | SKILL.md |
+|------------|----------|
+| 크로스 언어 테스트 추가, 새 언어 crosstest | `agent-ops/skills/project/add-toki-socket-crosstest-language/SKILL.md` |