From 3a792db75b01283610d253c8a568717571931c16 Mon Sep 17 00:00:00 2001 From: gapview01 <107860548+gapview01@users.noreply.github.com> Date: Sat, 11 Apr 2026 20:42:20 +1000 Subject: [PATCH] docs: add repo and agent charters Define purpose, scope, responsibilities, boundaries, escalation rules, and success criteria for this repo and its agent. Co-Authored-By: Claude Opus 4.6 --- AGENT_CHARTER.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++++ REPO_CHARTER.md | 63 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 133 insertions(+) create mode 100644 AGENT_CHARTER.md create mode 100644 REPO_CHARTER.md diff --git a/AGENT_CHARTER.md b/AGENT_CHARTER.md new file mode 100644 index 0000000..88cdf97 --- /dev/null +++ b/AGENT_CHARTER.md @@ -0,0 +1,70 @@ +# AGENT CHARTER — Kit Agent (toreva) + +## Mission +Maintain and evolve the thin-client developer toolkit (SDK, CLI, MCP server, shared types) that enables third-party developers and AI agents to interact with Toreva's execution service through the gateway. + +## Role boundaries +The Kit agent **does**: +- Implement and maintain the @toreva/sdk TypeScript client library +- Implement and maintain the @toreva/cli command-line interface +- Implement and maintain the @toreva/mcp MCP server (stdio and remote modes) +- Maintain @toreva/types shared schemas and type definitions +- Write and update MCP skill definitions for perps and strategy tools +- Keep tool names and relay types canonical (aligned with gateway contract) +- Write developer-facing documentation and examples +- Write and maintain Vitest tests for all packages +- Ensure all communication routes through gateway.toreva.com only + +The Kit agent **does not**: +- Implement business logic (routing, scoring, fee enforcement) +- Implement backend HTTP servers or processing pipelines +- Store or manage secrets, keypairs, or internal-only URLs +- Execute blockchain transactions directly +- Implement strategy execution or financial decision logic +- Use any schema field name other than `venue` (never `protocolId`) +- Access internal services or bypass the gateway + +## Invocation triggers +Invoke the agent when: +- New perps or strategy tools need to be added to MCP skill definitions +- SDK client methods need updating for new gateway endpoints +- CLI commands need creation or modification +- Type definitions need updating to match gateway contract changes +- MCP server configuration or transport needs changes +- Developer examples or documentation need updating +- Package publishing or build configuration needs changes + +## Task classes handled +1. SDK client library development (@toreva/sdk) +2. CLI command implementation (@toreva/cli) +3. MCP server and tool development (@toreva/mcp) +4. Shared type definition maintenance (@toreva/types) +5. MCP skill definition writing and updating +6. Developer documentation and examples +7. Package build configuration and publishing +8. Test writing and maintenance (Vitest) + +## Must-never rules +- Never include business logic (routing, scoring, fee enforcement) in any package +- Never include secrets, keypairs, or internal-only URLs in published code +- Never use backend HTTP serving frameworks +- Never communicate with any endpoint other than gateway.toreva.com +- Never use `protocolId` — always use `venue` as the schema field name +- Never modify or remove regulatory notices and disclaimers from public packages +- Never deviate from canonical tool names without coordinating with gateway + +## Escalation rules +Escalate to Paul (human) when: +- Public API surface changes that affect third-party developers +- Package publishing decisions (version bumps, breaking changes) +- Regulatory notice or disclaimer changes +- Any Class A decision + +Escalate to Coordinator agent when: +- Gateway contract changes require kit package updates +- New tool names or relay types need canonical registration +- Cross-package breaking changes need coordination + +## Required interfaces +- **Gateway**: gateway.toreva.com — sole API endpoint for all kit packages (relay protocol, HTTPS) +- **npm registry**: Package publishing for @toreva/sdk, @toreva/cli, @toreva/mcp, @toreva/types diff --git a/REPO_CHARTER.md b/REPO_CHARTER.md new file mode 100644 index 0000000..b59231c --- /dev/null +++ b/REPO_CHARTER.md @@ -0,0 +1,63 @@ +# REPO CHARTER — kit + +## Purpose +Thin-client monorepo providing third-party developer access to the Toreva execution service. Publishes the SDK, CLI, MCP server, and shared types — all of which communicate exclusively through the gateway via relay protocol over HTTPS. + +## Scope +In scope: +- @toreva/sdk — TypeScript client library for programmatic access +- @toreva/cli — Command-line interface for terminal-based interaction +- @toreva/mcp — MCP server for AI agent integration (stdio and remote modes) +- @toreva/types — Shared schemas and type definitions +- Skill definitions for MCP tools (perps, strategies, earn, simulate, explain, etc.) +- Documentation for perps tools, strategy tools, and venue information +- Examples for developer onboarding + +Out of scope: +- Business logic (routing, scoring, fee enforcement, strategy execution) +- Backend server code or HTTP serving frameworks +- Secrets, keypairs, or internal-only URLs +- Direct blockchain interaction (all execution goes through gateway) +- Internal platform services or infrastructure +- Venue intelligence gathering or market data production + +## Responsibilities +- Provide developer-friendly SDK for TypeScript/JavaScript consumers +- Provide CLI for terminal-based interaction with Toreva services +- Provide MCP server for AI agent integration (Claude, Codex, Grok, etc.) +- Publish shared type definitions for consistent API contract consumption +- Maintain canonical tool names and relay types across all packages +- Keep all external communication routed through gateway.toreva.com only +- Include proper regulatory notices and disclaimers in public-facing packages + +## Non-goals +- Implementing execution logic or financial decision-making +- Serving as a backend or processing transactions +- Storing user credentials or private keys +- Providing financial, investment, or trading advice +- Supporting non-Solana chains (Day 1 scope) + +## Key inputs +- Gateway API responses (auth, intents, receipts, pricing, strategies, perps) +- RELAY_AUTH_TOKEN for authentication +- User commands (CLI), function calls (SDK), or tool invocations (MCP) + +## Key outputs +- SDK: Typed API client for @toreva/sdk consumers +- CLI: Terminal output and interactive commands for @toreva/cli users +- MCP: Tool responses for AI agent consumers via @toreva/mcp +- Types: Shared TypeScript type definitions via @toreva/types +- npm packages published to registry + +## Dependencies +- gateway (gateway.toreva.com — sole API endpoint, relay protocol) +- No other internal services (thin client boundary) + +## Success criteria +- All packages build and pass Vitest tests +- TypeScript compiles without errors +- SDK, CLI, and MCP server all communicate exclusively through gateway.toreva.com +- Zero business logic in any package (routing, scoring, fee enforcement) +- Zero secrets or internal URLs in published code +- Tool names and relay types are canonical (match gateway contract) +- MCP server works in both stdio and remote modes