---
name: add-proto-socket-crosstest-language
version: 1.0.0
description: Plan and create new-language implementation scaffolding and proto_socket language-matrix integration tests. Use when adding language package README/checklist templates, crosstest folders, server-row orchestrators, subprocess clients, or review notes for Dart/Go/other language protocol compatibility tests, especially tests that must verify every supported server/client language pair over TCP and WebSocket for send, push, request-response, concurrent request nonce mapping, and protobuf typeName compatibility without cluttering the repository root.
---

# Add Proto Socket Crosstest Language

## Purpose

Create the package-local scaffold for a new Proto Socket language implementation and add or update the full language compatibility matrix. Keep implementation checklists and crosstest code inside the relevant language package or this skill's templates, preserve the repository root for shared docs, and match the Dart/Go baseline behavior.

## Plan-First Workflow

For implementation work, follow the `agent-ops/skills/common/plan/SKILL.md` loop before editing crosstest or language source files:

```text
plan skill -> agent-task/{task_name}/PLAN.md + CODE_REVIEW.md stub
implementation -> code changes + filled CODE_REVIEW.md
code-review skill -> archive or follow-up plan
```

Do not create plan files for casual analysis, status checks, or review-only requests unless the user explicitly asks for a plan. When creating a crosstest plan:

- Use a short snake_case task name under `agent-task/`.
- Read every orchestrator, helper, package test, and manifest that the change will touch before writing `PLAN.md`.
- Include the language matrix as a server-row/client-cell table.
- For each matrix gap, state whether it needs new crosstest code, existing same-language tests already cover it, or it is deferred with a reason.
- Include exact package-local validation commands and expected outcomes.
- Create the paired `CODE_REVIEW.md` stub so the implementation pass can record decisions and command output.

## Language Scaffold

When starting a new language implementation, copy the relevant files from:

```text
agent-ops/skills/project/add-proto-socket-crosstest-language/templates/
```

Use the README and checklists as package-local starting points. Fill in language-specific commands, supported transports, proto generation, same-language tests, and crosstest commands before marking the implementation available.

## Folder Rules

Use package-local `crosstest` folders:

```text
<server-language>/crosstest/<server>_<client>.<ext>
<client-language>/crosstest/<server>_<client>_client.<ext-or-main-dir>
```

Baseline examples:

```text
dart/crosstest/dart_go.dart
go/crosstest/dart_go_client/main.go
go/crosstest/go_dart.go
dart/crosstest/go_dart_client.dart
```

Avoid root-level runners and root-level package metadata unless explicitly requested. If a plan path changes, record why in the review note.

## Language Matrix

Test by server-language rows. For every supported language, run it once as the server, then run every supported language as a client against that server for TCP and WebSocket.

```text
server=dart:   client=dart, client=go, client=kotlin, ...
server=go:     client=dart, client=go, client=kotlin, ...
server=kotlin: client=dart, client=go, client=kotlin, ...
```

When adding a new language, update the matrix in both dimensions:

- Existing servers must run the new language as a client.
- The new language must run as a server for every supported client language.
- Same-language cells (`server == client`) are part of the matrix. They may be satisfied by package-local same-language tests only when those tests cover the same TCP/WS scenario set; otherwise add package-local crosstest entries.
- Do not mark a language Available until its matrix row and column pass, or deferred cells are explicitly documented with reasons.

Pairwise files are still allowed, but verification must be reported as completed server-language rows so omissions are visible.

## Test Shape

Create a server-language orchestrator plus client-language subprocess helpers. Prefer a server-row orchestrator that runs all clients for that server; a pairwise orchestrator is acceptable only when the review note lists the full matrix cells covered by all commands.

The orchestrator must:

- Start TCP and WebSocket servers.
- Run each required client helper for each protocol/phase.
- Parse subprocess stdout for `PASS` and `FAIL`.
- Fail on missing expected scenario, any `FAIL`, or non-zero subprocess exit.
- Stop servers even on subprocess failure.

The client helper must:

- Connect to requested mode/port.
- Print `INFO typeName <language>=TestData`.
- Print exactly one result line per scenario:

```text
PASS scenario=N detail=...
FAIL scenario=N error=...
```

## Required Scenarios

Run for both TCP and WebSocket:

| Scenario | Requirement |
|----------|-------------|
| 1 | Client sends fire-and-forget `TestData`; server validates `index` and `message`. |
| 2 | Server pushes `TestData(index=200, message=push from ... server)` to the client. |
| 3 | Client `sendRequest` receives `index=req.index*2` and `message=echo: req.message`. |
| 4 | Multiple concurrent `sendRequest` calls verify nonce/responseNonce routing. |

Split each protocol into `send-push` and `requests` phases when normal listeners and request listeners cannot coexist for one protobuf type. This is required for current Dart and Go communicators.

## Secure Transport Scenarios

When the language supports secure transports, add TLS+TCP and WSS coverage, or document why they are deferred.

Secure scenarios must verify:

- TLS+TCP client/server exchange `TestData`.
- WSS client/server exchange `TestData`.
- Certificates/trust setup stays in test fixtures, not machine-global stores.
- Review notes include secure test commands and environment caveats.

If deferred, ensure the language README does not claim TLS/WSS availability.

## Protocol Details

Use generated `TestData`. Current proto has no `package`; both sides must use simple type names:

```text
Dart: TestData.getDefault().info_.qualifiedMessageName -> TestData
Go:   toki.TypeNameOf(&packets.TestData{})              -> TestData
```

Log type names from both sides.

Use non-conflicting fixed ports. Keep the Dart/Go baseline ports when extending it:

```text
Dart server / Go client TCP: 29090
Dart server / Go client WS:  29092
Go server / Dart client TCP: 29190
Go server / Dart client WS:  29192
```

## Path Robustness

Resolve subprocess paths from orchestrator source location or language package root. Do not assume the command starts at repository root.

Prefer package-local commands:

```bash
(cd dart && dart run crosstest/dart_go.dart)
(cd go && go run ./crosstest)
```

For new languages, include equivalent commands in the review note.

## Verification

Run:

- Full affected matrix rows and columns, not only the new pair in both directions.
- Existing unit tests for each touched language package.
- Formatter/analyzer/compiler checks for each touched language package.

Report PATH/cache/sandbox caveats in final answer and review note; do not bake machine-specific paths into source.

## Review Note

When reviewer guidance is requested, include:

- Added files and roles.
- Path decisions and deviations.
- Matrix coverage by server row and client cell, including same-language cells.
- Scenario coverage, including secure transports or deferral reason.
- Exact package-local validation commands.
- Environment-specific caveats.
