add-connector

name	add-connector
description	Use when adding a new protocol connector to the taktora-connector framework (e.g. "add an MQTT connector", "scaffold a new connector crate", "create a taktora-connector-<proto>"). Carries the mechanical steps and the taktora- specific gotchas that the prose guide does not spell out as commands.

add-connector

This skill is the action companion to the connector guide. The guide is the source of truth for why and how the framework fits together; read it first:

docs/guides/adding-a-connector.md

Do not re-derive the architecture here — open the guide for the trait contract, the file-by-file walkthrough, and the spec/RFC loop. This skill only lists the executable steps and the gotchas that bite if you skip them.

0. Source of truth

• Connector guide: docs/guides/adding-a-connector.md (full narrative).
• Reference connector to copy: crates/taktora-connector-can (the minimal complete connector — copy and rename it).
• Publish-order guard: scripts/check-publish-deps.sh.

1. Scaffold the two crate directories

Every connector is two crates: the published taktora-connector-<proto> and a publish = false taktora-connector-<proto>-tests. Create both skeletons with the bundled helper (refuses to overwrite existing crates):

.claude/skills/add-connector/scaffold.sh <proto>

Then follow the guide to fill Cargo.toml, routing.rs, options.rs, health.rs, the backend trait + mock/real, the gateway/bridge/registry/ dispatcher, and connector.rs.

2. The *-tests publish = false split (do not skip)

The tests crate is mandatory, not optional. Internal dev-dependencies on sibling workspace crates inside a published crate break release-plz's publish topological sort (it ignores dev-dep edges, but cargo publish's verify step resolves them). Keep every internal dev-dep in the publish = false *-tests crate. The guide's Step 12 shows the exact Cargo.toml.

3. Verify the publish order before you push

After wiring both crates into the workspace, run the guard that encodes the trap above and fails on a version-bearing internal dev-dep in a publishable crate:

./scripts/check-publish-deps.sh

This is the same check CI runs. A green run here means the split is correct.

4. Build / test / lint at CI's exact flags

cargo build --workspace
cargo test --workspace --all-features -- --test-threads=1
cargo clippy --workspace --all-targets --all-features -- -D warnings
typos

Two gotchas baked into those flags:

• --test-threads=1 is required, not a preference. Tests stand up iceoryx2 nodes and shared-memory segments and touch a process-wide allocator; running them in parallel exhausts /dev/shm on constrained runners and cross-talks between tests. Serial execution isolates each test's shared-mem resources.
• Always lint with --all-features. The real protocol backend lives behind a default-off *-integration feature, so a bare cargo clippy never compiles it. If the backend is also platform-gated (CAN/EtherCAT are Linux-only), cfg-gated files escape clippy on macOS entirely — run the clippy line on the target platform before merging.

5. Spec + traceability

The connector also needs its feat::/req::/spec::/test:: paperwork and a draft -> open status promotion before code, then req:: flipped to implemented with :links: once it lands. That whole loop, and the sphinx-build -W gate that enforces it, is in the guide (sections 2, 4, 5) — follow it there.