view release on metacpan or  search on metacpan

porting-sdk/SUBAGENT_PLAYBOOK.md  view on Meta::CPAN

### .NET
- This host has NO `dotnet` SDK installed. Agents working on .NET must do source-audit only and document explicitly that `dotnet build` / `dotnet test` were not run; user must verify on a machine with the SDK installed.
- Service uses `_tools` / `_toolOrder` protected dicts. Public `Tools` accessor was added; reflection-based CLI loaders use it.

### Java
- Agent test framework: gradle. `gradle test` for the suite.
- Examples: `examples/<Name>.java` in default package (no `package` declaration). FQCN is just the class name.
- Build classpath needs gradle prep before reflection-based loaders work.

### PHP
- Composer-based. `./vendor/bin/phpunit` for tests.
- Logger.php uses bare `STDERR` inside namespace `SignalWire\Logging` — should be `\STDERR`. Failed under `php -S` per prior audit. **Fix this when touching that file.**
- 9 known stubs: 3 in `src/SignalWire/Relay/Client.php` (lines ~92, ~244, ~252), 8 in `src/SignalWire/Skills/Builtin/*.php`.

### Ruby
- `bundle exec rake test` for the suite.
- `lib/signalwire/swml/service.rb`'s `serve` method had a `Rack::Handler::WEBrick` issue against Rack 3.2.5; fixed in commit `7837101`. If touching that file, preserve the rackup-gem fallback.

### Perl
- `prove -lr t/` for the suite.
- ContextBuilder fix: `lib/SignalWire/Contexts.pm` already has the FULL DSL implementation. The bug is `lib/SignalWire/Agent/AgentBase.pm` does `require SignalWire::Contexts::ContextBuilder` which loads the 28-line stub instead. Fix: point at the rea...

### C++
- CMake-based. `cmake --build build` and `cmake --build build --target <example>` for individual examples.
- One known stub: `// TODO: token validation hook would go here` in relay code.

### TypeScript
- `npm test` runs vitest. Examples run via `npx tsx <path>` because Node 18+ doesn't natively load .ts.
- BDD-style tests (`it('text')`) — `audit_test_parity` will report many false-positive misses; resolve via PORT_TEST_OMISSIONS.md or renames.

### Python
- The reference SDK. Most audits should be clean here. Search-related code is in `signalwire/search/` and is in skip lists.
- `Logger.py:118 STDERR` no longer applies (PHP-only).

---

## Port_surface.json status (gating diff_port_surface and audit_docs)

| Port | enumerate script | port_surface.json | gates audit_docs / diff_port_surface |
|---|---|---|---|
| Python | `scripts/enumerate_python.py` (in porting-sdk) | n/a (it IS the reference) | n/a |
| TypeScript | **MISSING** | **MISSING** | **BLOCKED** until written |
| PHP | **MISSING** | **MISSING** | **BLOCKED** |
| .NET | **MISSING** | **MISSING** | **BLOCKED** |
| Java | `scripts/enumerate_surface.py` | present | usable |
| Ruby | `scripts/enumerate_surface.rb` | present | usable |
| Perl | `scripts/enumerate_surface.pl` | present | usable |
| C++ | `scripts/enumerate_surface.py` | present | usable |
| Go | `cmd/enumerate-surface` | present | usable |
| Rust | **MISSING** | **MISSING** | **BLOCKED** until written |

For ports flagged BLOCKED: each AUDIT+FIX dispatch must include a task to write the enumerate script (if missing) before audit_docs / diff_port_surface can be run as receipts.

---

## Lessons learned — track new ones here

### From the killed agents (2026-04-29)

- **Composer permissions issue** (PHP relay): `composer.lock` had wrong owner from a prior run. Agent stopped at the perms issue. Sub-agents need `chown` permission OR the prompt should pre-fix permissions.
- **Stale build dirs** (Java): `.gradle.old-root-owned/` and `build.old-root-owned/` left from prior owner. Same root-cause as above.
- **Discovery during read** (Perl): agent found that `Contexts.pm` already had the full DSL, but `ContextBuilder.pm` was the stub. The fix is a 1-line `require` change, NOT writing 600 lines of new code. The prompt now flags this in the per-port arch...
- **Force-push history gap** (Go): the 4/28 force-push erased 20 PRs. Any agent touching Go must understand that `pkg/relay/*.go` PR-merged content from #133-#176 is real and recently-restored; not to be regressed.

### From the successful Rust agent (2026-04-29)

- **`signalwire.connect` shape** — Python sends params nested under `authentication`. The audit fixture watches the top level too. Agent emitted both. Future agents: replicate the dual emission OR document the deviation.
- **`signalwire.event` ack semantics** — Python ack is `{jsonrpc, id, result:{}}` (no method field). Audit fixture only marks event-dispatched on a frame with `method == "signalwire.event"` from the client. Harness explicitly emits the method-beari...
- **DataMap-based skills** — `api_ninjas_trivia` and `weather_api` are DataMap-based per Python (the platform fetches the URL). Audit expects the SDK to issue HTTP. Harness simulates the platform by extracting the webhook URL from the DataMap and e...
- **Audit script bugs** — `audit_skills_dispatch` and `audit_rest_transport` originally matched `src/skills/`/`src/rest/` greedily, picking TS first regardless. Fixed by requiring `package.json` for TS and `Cargo.toml` for Rust. **The audit program...
- **`port_surface.json` MISSING for 4 ports** (TS, PHP, .NET, Rust). Agents working on those ports must write `enumerate_<lang>.<ext>` as part of their work to enable diff_port_surface and audit_docs.

---

## Choosing the next port to dispatch

Order by complexity/value if working through the whole list:

1. **PHP** — biggest concrete workload (3 relay stubs + 8 skill stubs). Best stress test for the playbook.
2. **.NET** — relay client + source-audit only (no dotnet on host). Good for catching playbook gaps around verification-without-build.
3. **Perl** — small (1 stub: ContextBuilder pointer fix is 1-line). Good for validating playbook on tiny work.
4. **C++** — small (1 stub: relay TODO). Good for validating multi-language mechanics.
5. **Go** — 4 stubs (bedrock + WithConfigFile + cXML). Already has port_surface.json.
6. **Java** — 0 stubs but 71 cheat tests + 28 missing examples. Test-rewrite work.
7. **TypeScript** — 0 stubs but 40 cheat tests + 40 missing examples. Same as Java + needs enumerate_ts.
8. **Ruby** — 0 stubs but 53 cheat tests + 34 missing examples. Test-rewrite work.

Each port also needs the 4 BLOCKED audits' prerequisites (enumerate_<lang>.<ext> for TS/PHP/.NET/Rust).

---

## Final dispatch checklist (use before pressing send)

Before invoking the Agent tool:

- [ ] Prompt opens with the four NON-NEGOTIABLE RULES (pull, no-push, match-python, read-docs).
- [ ] **MODE is explicitly stated** (AUDIT / FIX / AUDIT+FIX) with the exact language from the "Dispatch modes" section.
- [ ] Architecture notes for this specific port included verbatim (copy from "Per-port architecture notes" above).
- [ ] Each task has a Python reference (file:line:method). Tasks without a Python reference should be flagged for the user before dispatch.
- [ ] Audit programs the agent will run as receipts are listed with absolute paths.
- [ ] The REPORT FORMAT section is included verbatim — agent must produce all 5 sections.
- [ ] Final reminder: "Begin by pulling and reading the docs."
- [ ] `run_in_background: true` if you want to do other work in parallel; `false` if the agent's report is on the critical path.
- [ ] Model is `opus` per the user's standing instruction.