Version the skill around V1 production and V2 beta protocol profiles

[armandocodecr]

Addresses #6.

Makes the skill version-aware so an agent cannot mix V1 and V2, and documents both versions instead of excluding one.

Before this, constitution.md scoped itself to V1 and said V2 was "intentionally excluded ... until the version-aware architecture in issue #6 is implemented", pointing at a V2 profile that did not exist. The rest of the repo documented V1 without saying so.

Structure

constitution.md now holds what is true regardless of version — the foundational principles, API and network laws, agent conduct — plus a new Article I that governs version selection and explains both versions at a compressed level, with the same depth for each.

Two profiles carry the version-specific rules:

• skills/protocol/v1.md — production, the default for every integration.
• skills/protocol/v2.md — beta, clearly labelled throughout.

They live under skills/ rather than a top-level protocol/ so the repo keeps one convention for bundled references. SKILL.md gains a version block before the workflow and routes to the profiles. The consistency script needed no change: it globs all tracked markdown, so the new files are covered.

The version rule

Availability is bound to the network, which is the part most worth getting right:

• Mainnet: V1 only. V2 is not deployed there.
• Testnet: both. V2 is deployed on testnet, so building on it there is legitimate, labelled beta.

Explaining V2 is always in scope; what is restricted is which network an integration targets. The *-develop-v2-crosschain branches stay outside both profiles.

Existing references

The thirteen API, React SDK and Blocks files plus the README now declare the version they document. They were already correct V1 content — verified that no V2 field names leak into them — they simply did not say so. skills/api/trustlines.md is marked as applying to both versions instead, since trustlines are a Stellar network requirement rather than a protocol-version concern.

Scope

This PR covers the contract and business-model layer. The V2 API, React SDK and Blocks surfaces are deliberately not documented, since that work is not finished and belongs to another area; the V1 markers say so explicitly so an agent does not assume silence means absence. V2 here is limited to contract semantics: roles and their composition constraints, threshold approvals, the state model, dispute behaviour, operations and the mutability rule.

Two contract findings validated in trustlesswork-smart-contract-stellar are folded in: withdraw-remaining-funds is no longer marked "validation pending" and now states the V1 semantics confirmed in that repo's issue #117, and the Trustless Work fee address is documented as a network-level property (hardcoded on the mainnet lineage, a parameter on testnet, in both versions) rather than a version difference.

For whoever owns the integration layer

The @trustless-work/escrow v5 SDK builds request paths as /escrow/${type}/v2, while this skill documents unversioned routes. Whether that v2 denotes the API version or the contract version was not resolved here, and it matters: an agent reading "V2 is beta" alongside a /v2 route will draw the wrong conclusion. Worth settling before the integration references are updated.

Remaining from the issue

• Per-rule links from each statement to the exact contract file that validates it.
• Stable commit/WASM/deployment references for V2. Still blocked: the contract repository has no deployment manifest tying a branch to a deployed contract.
• Consistency checks that fail when a V2 field appears in a V1 file.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: cddc5f72-7ccc-46ec-b0d7-26c0acc476bb

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}