> For the complete documentation index, see [llms.txt](https://gotts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gotts.gitbook.io/docs/prd-product-requirements/prd.md). # PRD Index > **Last Updated**: 2026-02-14 > > This directory contains all Product Requirements Documents for the Gotts project. PRDs define the ideal specification; implementation docs and code live elsewhere. *** ## Canonical PRD Map | PRD | Domain | Package | Implementation Docs | | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | [mcp-server/](/docs/gotts-safe-mcp-server/mcp-server.md) | Gotts Safe: 147 tools across 29 categories (profile-gated), safety, wallet, config, data sources | `packages/safe` (`@gotts.ai/safe`) | [`docs/safe/`](https://github.com/wpank/gotts.ai-monorepo/blob/main/docs/safe/README.md) | | [skills/](/docs/skills/skills.md) | Gotts Skills: slash commands for user-facing workflows | `packages/safe/skills/`, `.claude/commands/` | [`CLAUDE.md`](https://github.com/wpank/gotts.ai-monorepo/blob/main/CLAUDE.md) | | [agents/](/docs/agents/agents.md) | Gotts Agents: autonomous agent definitions and delegation rules | `packages/safe/agents/` | [`CLAUDE.md`](https://github.com/wpank/gotts.ai-monorepo/blob/main/CLAUDE.md) | | [vault/](/docs/gotts-vaults/vault.md) | Gotts Vaults (ERC-4626 + ERC-8004 + V4 hooks + am-AMM). Vault tools integrated into Gotts Safe via `vault` profile. | `packages/vault` (`@gotts.ai/vault`) | [`packages/vault/docs/`](https://github.com/wpank/gotts.ai-monorepo/blob/main/packages/vault/docs/README.md) | | [devenv/](/docs/devenv/devenv.md) | Developer Environment: full Uniswap stack (V2/V3/V4/UniswapX/ERC-8004) on local Anvil, debug UI, seed scripts, scenario simulation. Foundation for `vault/05-local-dev.md`. | `packages/devenv` (`@gotts.ai/devenv`) | — | | [webenv/](https://github.com/wpank/gotts.ai-monorepo/blob/main/prd/webenv/README.md) | Webenv: browser-based Uniswap test environment. Tevm in-process EVM, fork mode (Ethereum/Base), WebMCP server, 15-view debug UI, state sharing. | `packages/webenv` (`@gotts.ai/webenv`) | — | | [website/](/docs/website/website.md) | Gotts web properties: landing page (`gotts.ai`), on-chain dashboard app, and agent account portal | `apps/web` | — | | [shared/](https://github.com/wpank/gotts.ai-monorepo/blob/main/prd/shared/README.md) | Cross-cutting content: market context, glossary, chains | — | — | *** ## Complete File Index Every file in the `prd/` tree, grouped by subdirectory. Use this to find the right document without opening sub-READMEs. ### Gotts Safe (`mcp-server/`) -- 18 files Gotts Safe specification: 147 tools across 29 categories (profile-gated), safety, wallets, config, deployment, ecosystem listings, and testing. Vault tools are unified into Gotts Safe via the `vault` profile. | File | What's Inside | | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [README.md](/docs/gotts-safe-mcp-server/mcp-server.md) | Index, tool count summary by category (147 total / 34 write), related PRD links | | [01-overview.md](/docs/gotts-safe-mcp-server/mcp-server/01-overview.md) | Vision, goals (G1-G24), non-goals, design philosophy, 8 user personas | | [02-architecture.md](/docs/gotts-safe-mcp-server/mcp-server/02-architecture.md) | High-level architecture, tool router, profile system, tool count budget, tool annotations, LLM-optimized descriptions | | [03-tools-data.md](/docs/gotts-safe-mcp-server/mcp-server/03-tools-data.md) | **Data & Analytics (9)**, **Historical Data (5)**, **Token Directory (4)** -- Phase 1 read-only tools | | [03b-tools-portfolio-pnl.md](/docs/gotts-safe-mcp-server/mcp-server/03b-tools-portfolio-pnl.md) | **Portfolio & P\&L (10)** -- balance tracking, performance metrics, P\&L reports | | [04-tools-trading.md](/docs/gotts-safe-mcp-server/mcp-server/04-tools-trading.md) | **Trading (5)**, **Approval/Permit (4)** -- Phase 2 execution tools | | [05-tools-liquidity.md](/docs/gotts-safe-mcp-server/mcp-server/05-tools-liquidity.md) | **Liquidity (9)** + **LP Optimization (3)** -- Phase 3 LP operations | | [06-tools-realtime.md](/docs/gotts-safe-mcp-server/mcp-server/06-tools-realtime.md) | **Streaming/SSE (5)**, **Protocol Fees (7)** -- Phase 4 real-time data | | [07-tools-advanced.md](/docs/gotts-safe-mcp-server/mcp-server/07-tools-advanced.md) | **CCA/Token Launch (9)**, **Intelligence (13)**, **External Data/x402 (8)** -- Phase 5-6 | | [08-tools-infra.md](/docs/gotts-safe-mcp-server/mcp-server/08-tools-infra.md) | **Safety (6)** + **Safety Extensions (2)** + **Session Key Management (3)** + **Wallet Management (3)** + **Deployment (1)** + **Local Testnet (4)** + **Utility (3)** | | [09-safety.md](/docs/gotts-safe-mcp-server/mcp-server/09-safety.md) | 15-layer defense-in-depth: TEE keys, prompt injection defense, policy engine, simulation, on-chain guards, MCP integrity, hook safety, reputation gates, SIWE auth | | [10-wallets.md](/docs/gotts-safe-mcp-server/mcp-server/10-wallets.md) | 5 wallet types: local key, Privy (with full policy engine details + Base contract addresses), Safe, ZeroDev, generic viem | | [11-config.md](/docs/gotts-safe-mcp-server/mcp-server/11-config.md) | `UNISWAP_MCP_` env var convention, `.env.example`, Zod startup validation, `--health` flag, structured startup logs, JSON schema config file | | [12-milestones.md](/docs/gotts-safe-mcp-server/mcp-server/12-milestones.md) | 7 implementation phases, success metrics, evaluation framework | | [13-distribution.md](/docs/gotts-safe-mcp-server/mcp-server/13-distribution.md) | Synergies, npm distribution strategy, `mcpName` field, semver semantics, competitive comparison | | [14-deployment.md](/docs/gotts-safe-mcp-server/mcp-server/14-deployment.md) | Production deployment: Fly.io / Railway / Cloudflare Workers (TypeScript SDK + Durable Objects) / Docker | | [15-install-wizard.md](/docs/gotts-safe-mcp-server/mcp-server/15-install-wizard.md) | `npx @gotts.ai setup` — @clack/prompts flow, 9-client format table, backup→merge→write config injection | | [16-registries.md](/docs/gotts-safe-mcp-server/mcp-server/16-registries.md) | Ecosystem listings: official MCP Registry (`server.json`), Smithery (`smithery.yaml`), Docker MCP Catalog, one-click install deeplinks | | [17-testing.md](/docs/gotts-safe-mcp-server/mcp-server/17-testing.md) | Testing: MCP Inspector (interactive + CI), InMemoryTransport unit tests, LLM tool selection evaluation tests | ### Gotts Agents (`agents/`) -- 13 files Gotts Agents: autonomous specialist agents that execute multi-step DeFi workflows. 32 agents across 9 categories. | File | What's Inside | | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [README.md](/docs/agents/agents.md) | Index, 32-agent reference table with categories, models, and delegation targets | | [01-overview.md](/docs/agents/agents/01-overview.md) | Vision, design principles (safety-first, acyclic delegation, no transitive trust) | | [02-architecture.md](/docs/agents/agents/02-architecture.md) | How agents work, delegation DAG, markdown file structure with YAML frontmatter, directory layout | | [03-agents-execution.md](/docs/agents/agents/03-agents-execution.md) | **trade-executor**, **liquidity-manager**, **cross-chain-executor** -- write operations, swap/LP/bridge workflows | | [04-agents-research.md](/docs/agents/agents/04-agents-research.md) | **pool-researcher**, **token-analyst**, **opportunity-scanner**, **portfolio-analyst** -- read-only analysis and reports | | [05-agents-strategy.md](/docs/agents/agents/05-agents-strategy.md) | **lp-strategist**, **risk-assessor** -- LP recommendations and independent risk evaluation (APPROVE/VETO) | | [06-agents-development.md](/docs/agents/agents/06-agents-development.md) | **hook-builder**, **integration-architect** -- V4 hook Solidity generation and integration architecture design | | [07-agents-infra.md](/docs/agents/agents/07-agents-infra.md) | **safety-guardian**, **wallet-provisioner** -- terminal nodes that never delegate to other agents | | [08-agents-economy.md](/docs/agents/agents/08-agents-economy.md) | **treasury-manager**, **token-deployer**, **identity-verifier**, **protocol-fee-seeker**, **agent-service-broker** -- self-funding, ERC-8004, x402 | | [09-agents-vault.md](/docs/agents/agents/09-agents-vault.md) | **vault-manager**, **vault-strategist**, **vault-watchdog**, **vault-creator**, **vault-allocator**, **vault-executor** -- ERC-4626 vault management and monitoring | | [13-agents-realtime.md](/docs/agents/agents/13-agents-realtime.md) | **market-monitor**, **position-monitor** -- continuous market and position surveillance | | [10-composition.md](/docs/agents/agents/10-composition.md) | 14 multi-agent composition patterns (pipeline, fan-out, approval gate, etc.), anti-patterns, delegation rules | | [11-safety.md](/docs/agents/agents/11-safety.md) | Agent-level safety architecture, behavior testing, 15-layer defense model applied to agents | | [12-milestones.md](/docs/agents/agents/12-milestones.md) | 7 implementation phases, metrics, synergies, agent reference tables | ### Gotts Skills (`skills/`) -- 11 files Gotts Skills: user-facing interfaces that parse intent, delegate to agents, and return results. 68 skills with slash commands. | File | What's Inside | | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [README.md](/docs/skills/skills.md) | Index, 68-skill reference table with primary agent and slash command for each | | [01-overview.md](/docs/skills/skills/01-overview.md) | Vision, design principles, relationship to existing skills in `packages/safe/skills/` | | [02-architecture.md](/docs/skills/skills/02-architecture.md) | Skill types (direct, single-agent, multi-agent, composite), skill-agent-MCP mapping, reference doc architecture | | [03-skills-trading.md](/docs/skills/skills/03-skills-trading.md) | **execute-swap**, **batch-swap**, **submit-limit-order**, **cross-chain-swap**, **bridge-tokens**, **plan-swap** | | [04-skills-liquidity.md](/docs/skills/skills/04-skills-liquidity.md) | **manage-liquidity**, **rebalance-position** -- add/remove/collect with range optimization | | [05-skills-research.md](/docs/skills/skills/05-skills-research.md) | **analyze-pool**, **compare-pools**, **research-token**, **scan-opportunities**, **find-yield**, **portfolio-report**, **track-performance** | | [06-skills-strategy.md](/docs/skills/skills/06-skills-strategy.md) | **optimize-lp**, **lp-strategy**, **assess-risk**, **hedge-il** -- LP recommendations and independent risk assessment | | [07-skills-development.md](/docs/skills/skills/07-skills-development.md) | **build-hook**, **design-hook**, **design-integration**, **audit-integration**, **test-hook**, **setup-dca** -- V4 development workflows | | [08-skills-infra.md](/docs/skills/skills/08-skills-infra.md) | **setup-agent-wallet**, **check-safety**, **halt-agents**, **rotate-session-keys**, **verify-mcp-integrity**, **validate-intent**, **audit-approvals**, **revoke-approvals** -- infrastructure and emergency controls | | [09-skills-advanced.md](/docs/skills/skills/09-skills-advanced.md) | Composite workflows (**research-and-trade**, **full-lp-workflow**, **cross-chain-arbitrage**, **self-funding-setup**), Agent Capital Markets (**manage-treasury**, **deploy-agent-token**, **verify-agent**, **configure-x402**), Vault (**deposit-vault**, **manage-vault**, **vault-strategy**), CCA (**participate-cca**, **launch-token-cca**) | | [10-commands.md](/docs/skills/skills/10-commands.md) | Slash command registry for Claude Code, SKILL.md file template and structure | | [11-milestones.md](/docs/skills/skills/11-milestones.md) | 8 implementation phases, metrics, synergy maps, evaluation framework | ### Gotts Vaults (`vault/`) -- 22 files Gotts Vaults: ERC-4626 + ERC-8004 + Uniswap V4 hooks. Permissionless vault infrastructure for autonomous agents. | File | What's Inside | | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [README.md](/docs/gotts-vaults/vault.md) | Index, implementation status overview table, PRD-to-code workflow | | [DECISIONS.md](/docs/gotts-vaults/vault/decisions.md) | Design decision log: adopted mechanisms, anti-abuse controls, deferred items with research sources | | [IMPLEMENTATION-STATE.md](/docs/gotts-vaults/vault/implementation-state.md) | What's actually built vs spec: gaps by acceptance gate, tool coverage, layer-by-layer status | | [00-quickstart.md](/docs/gotts-vaults/vault/00-quickstart.md) | **Canonical onboarding** (persona-based: Participant/Creator/Manager), ERC-4337 batch paths, capability fallback | | [01-overview.md](/docs/gotts-vaults/vault/01-overview.md) | Vision, problem statement, design principles, goals/non-goals, canonical fee structure | | [02-personas.md](/docs/gotts-vaults/vault/02-personas.md) | 14 agent personas: Strategy, Curator, Trading, Allocator, Meta-Vault, Arbitrage, Yield, Developer, Auditor, Watchdog, etc. | | [03-custody.md](/docs/gotts-vaults/vault/03-custody.md) | 4 wallet architectures (TEE, Smart Accounts, MPC, Time-Delayed Proxy), policy engine, prompt injection defense, identity protection | | [04-architecture.md](/docs/gotts-vaults/vault/04-architecture.md) | System architecture, package structure, data flows, **state machine diagrams**, **sequence diagrams** | | [05-local-dev.md](/docs/gotts-vaults/vault/05-local-dev.md) | One-command testnet setup, debug UI for vault inspection, multi-agent swarm simulation with 5 autonomous agents | | [06-contracts.md](/docs/gotts-vaults/vault/06-contracts.md) | Solidity specs in 3 parts: **Part A** (core v1), **Part B** (Phase 2-3 safety), **Part C** (expansion). ERC-4626 compat guarantees, v1 totalAssets. | | [07-sdk.md](/docs/gotts-vaults/vault/07-sdk.md) | TypeScript SDK: VaultFactoryClient, VaultClient, StrategyEngine, CCABidder, HookDeployer, x402Gateway, ReputationReader, SharePoolClient, ProxyClient, MonitorBot | | [08-mcp-tools.md](/docs/gotts-vaults/vault/08-mcp-tools.md) | **Canonical tool counts** (24 core + 5 am-AMM + 6 proxy + 8 deferred + 6 marketplace = 49 total). **Error taxonomy**. Parameter conventions. | | [09-agents-skills.md](/docs/gotts-vaults/vault/09-agents-skills.md) | 4 core agents (vault-creator, vault-manager, vault-strategist, vault-allocator), 5 core skills, optional proxy agents | | [10-safety.md](/docs/gotts-vaults/vault/10-safety.md) | 15-layer vault defense (refs [shared/safety-layers.md](/docs/prd-shared/safety-layers.md)), **v1 monitoring requirements**, testing checklist | | [11-config.md](/docs/gotts-vaults/vault/11-config.md) | Wallet provider env vars, protocol variables, config schema with TypeScript interfaces | | [12-dependencies.md](/docs/gotts-vaults/vault/12-dependencies.md) | Tech stack: Solidity deps (OpenZeppelin, v4-core, v4-periphery), TS deps (MCP SDK, Uniswap SDKs, viem), debug UI deps | | [13-performance.md](/docs/gotts-vaults/vault/13-performance.md) | MCP latency targets (p95/p99), contract gas targets per operation, proxy module performance | | [14-milestones.md](/docs/gotts-vaults/vault/14-milestones.md) | 5 phases (Weeks 1-25+): factory + vault core, MCP + SDK, safety hardening, reputation engine, mainnet readiness | | [15-metrics.md](/docs/gotts-vaults/vault/15-metrics.md) | Core launch gates, operating KPIs (30/90-day targets), reputation KPIs, deferred KPIs | | [16-synergies.md](/docs/gotts-vaults/vault/16-synergies.md) | Growth mechanics: identity-to-capital flywheel, reputation-to-safety, auto-market-to-UX, share token composability, Uniswap volume flywheel | | [17-testing.md](/docs/gotts-vaults/vault/17-testing.md) | **Testing strategy**: invariant properties, fuzzing ranges, fork test scenarios, integration test matrix, CI gate requirements | | [18-deployment.md](/docs/gotts-vaults/vault/18-deployment.md) | **Deployment runbook**: deployment order, constructor args, post-deployment verification, multi-sig setup, monitoring bootstrap | | [19-threat-model.md](/docs/gotts-vaults/vault/19-threat-model.md) | **Threat model**: attacker taxonomy, attack trees, threat-to-layer mapping, residual risk register | ### Developer Environment (`devenv/`) -- 6 files Protocol-level developer environment: full Uniswap stack deployment (V2/V3/V4/UniswapX/ERC-8004), debug web UI, seed scripts, and scenario simulation. The infrastructure layer that `vault/05-local-dev.md` builds on top of. | File | What's Inside | | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [README.md](/docs/devenv/devenv.md) | Index, purpose, relationship to vault/05-local-dev.md, quick-start commands | | [01-overview.md](/docs/devenv/devenv/01-overview.md) | Vision, goals, two modes (from-scratch / fork), one-command UX, package layout, ports, tech stack, non-goals | | [02-uniswap-stack.md](/docs/devenv/devenv/02-uniswap-stack.md) | 7-phase deployment (WETH9+Permit2 → V2 → V3 → V4 → Universal Router → UniswapX → ERC-8004), INIT\_CODE\_HASH handling, mock tokens, liquidity seeding, `UniswapDeployment` type, state persistence, vitest fixtures, compiler version strategy | | [03-debug-ui.md](/docs/devenv/devenv/03-debug-ui.md) | 8-view web UI (Protocol Overview, Pool Explorer, Swap, Liquidity, UniswapX Orders, Agent Identity, Chain Controls, Key Management), tech stack, wagmi config, auto-refresh hooks | | [04-scripts.md](/docs/devenv/devenv/04-scripts.md) | Seed scripts (tokens, liquidity, swaps, agents), maintenance scripts (provision-liquidity, make-swap, manage-keys, time-travel, snapshot), shell orchestration, `.env.devenv` | | [05-simulation.md](/docs/devenv/devenv/05-simulation.md) | Time-travel patterns, scenario library (crash/volume-spike/new-pool/agent-onboard), `AgentHarness` class, `SwarmRunner` class, agent log format, vitest integration, CI state caching | ### Webenv (`webenv/`) — 10 files Browser-based Uniswap test environment: Tevm in-process EVM, fork mode (Ethereum/Base/custom), WebMCP server, 15-view debug UI, IndexedDB persistence, URL-shareable state. | File | What's Inside | | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | [README.md](https://github.com/wpank/gotts.ai-monorepo/blob/main/prd/webenv/README.md) | Index, purpose, relationship to devenv, quick-start commands | | [01-overview.md](https://github.com/wpank/gotts.ai-monorepo/blob/main/prd/webenv/01-overview.md) | Vision, goals, three deployment modes (fresh/fork-ethereum/fork-base), architecture, comparison to devenv, package layout, tech stack | | [02-tevm-runtime.md](https://github.com/wpank/gotts.ai-monorepo/blob/main/prd/webenv/02-tevm-runtime.md) | Tevm integration, Web Worker architecture, fork mode runtime, CORS strategy, viem transport adapter, Anvil RPC mapping, performance characteristics | | [03-deployment-pipeline.md](https://github.com/wpank/gotts.ai-monorepo/blob/main/prd/webenv/03-deployment-pipeline.md) | 7-phase from-scratch deployment, fork mode contract discovery, artifact bundling, progress reporting, caching | | [04-ui.md](https://github.com/wpank/gotts.ai-monorepo/blob/main/prd/webenv/04-ui.md) | 15-view UI specification (12 devenv + Scenarios + State + WebMCP), three-mode landing screen, data layer | | [05-chain-controls.md](https://github.com/wpank/gotts.ai-monorepo/blob/main/prd/webenv/05-chain-controls.md) | Mining, time travel, snapshots, balance manipulation, fork-specific controls (reset fork, fork info panel) | | [06-seeding.md](https://github.com/wpank/gotts.ai-monorepo/blob/main/prd/webenv/06-seeding.md) | Token deployment and liquidity seeding (from-scratch and fork mode), storage slot manipulation, whale impersonation | | [07-scenarios.md](https://github.com/wpank/gotts.ai-monorepo/blob/main/prd/webenv/07-scenarios.md) | Scenario runner (crash, volume-spike, new-pool, agent-onboard), composition, browser-specific adaptations | | [08-state-persistence.md](https://github.com/wpank/gotts.ai-monorepo/blob/main/prd/webenv/08-state-persistence.md) | IndexedDB storage, fork state caching, URL-shareable snapshots, state export/import, cross-tab sync | | [09-testing.md](https://github.com/wpank/gotts.ai-monorepo/blob/main/prd/webenv/09-testing.md) | Three-tier test strategy (\~330 tests): unit (happy-dom), integration (Tevm + fork + WebMCP), E2E (Playwright) | | [10-webmcp.md](https://github.com/wpank/gotts.ai-monorepo/blob/main/prd/webenv/10-webmcp.md) | WebMCP: browser MCP server, dual transport (WebSocket + Streamable HTTP), tool registry (\~69 tools), handler extraction pattern, control panel | ### Gotts Website (`website/`) -- 10 files Gotts web properties: the `gotts.ai` landing page, the on-chain dashboard app, the agent account portal, and the shared design system. Four sub-domains sharing one design language. | File | What's Inside | | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [README.md](/docs/website/website.md) | Domain index, product-to-URL map, relationship to protocol PRDs, design constraints | | [landing-page/README.md](/docs/website/website/landing-page.md) | Landing page index and scope summary | | [landing-page/01-overview.md](/docs/website/website/landing-page/01-overview.md) | Product vision, problem statement, market context, personas (developers/strategists/builders), product suite, security overview, protocol economics, Uniswap integration, standards, non-goals, open questions, glossary | | [app/README.md](/docs/website/website/app.md) | App index and scope summary | | [app/01-overview.md](/docs/website/website/app/01-overview.md) | Vision, personas, vault explorer (list + detail), agent directory (list + profile), connected wallet view, navigation structure, data sources, non-goals, milestones | | [portal/README.md](/docs/website/website/portal.md) | Portal index and scope summary | | [portal/01-overview.md](/docs/website/website/portal/01-overview.md) | Vision, personas, custody setup wizard (TEE/Smart Account/MPC), ERC-8004 registration flow, agent profile management, full onboarding sequence, write operations, security model, milestones | | [design/README.md](/docs/website/website/design.md) | Design system index, scope, consumer list | | [design/01-overview.md](/docs/website/website/design/01-overview.md) | Brand identity, design principles, color system (semantic tokens, tier/status colors), typography (Inter + JetBrains Mono, type scale), spacing and layout grid, component library (primitives, data display, tables, forms, feedback), iconography, motion rules, dark/light mode, responsive strategy, accessibility (WCAG 2.1 AA), per-product application notes, copy standards | ### Shared (`shared/`) -- 10 files Cross-cutting reference content used by all domain PRDs. Deduplicated to avoid drift. | File | What's Inside | | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [doc-standards.md](/docs/prd-shared/doc-standards.md) | **Spec semantics** (normative vs informative), **document type classification**, **doc linter checklist**. All PRDs must conform. | | [market-context.md](/docs/prd-shared/market-context.md) | Agent Capital Markets overview (Feb 2026): x402 stats, ERC-8004, Clanker, BankrBot, MCP ecosystem data, infrastructure stats | | [glossary.md](/docs/prd-shared/glossary.md) | Protocol terminology: MCP, V2/V3/V4, UniswapX, ERC-7683, ERC-8004, sqrtPriceX96, tick, hook, intent, etc. | | [chains.md](/docs/prd-shared/chains.md) | 11 supported chains with chain IDs, native currencies, Uniswap version support, **two-layer chain support model**, key contract addresses | | [safety-layers.md](/docs/prd-shared/safety-layers.md) | **Canonical 15-layer defense model** (single source of truth). Scope matrix, TEE limitations. Referenced by all safety docs. | | [implementation-delta.md](/docs/prd-shared/implementation-delta.md) | Consolidated PRD-vs-codebase status for every tool, agent, skill, and infrastructure component | | [onboarding-workflow.md](/docs/prd-shared/onboarding-workflow.md) | End-to-end agent onboarding: wallet setup, ERC-8004 registration, guardian config, funding, migration paths | | [credential-architecture.md](/docs/prd-shared/credential-architecture.md) | Who holds keys, where keys live, failure/recovery matrix, key rotation | | [user-journeys.md](/docs/prd-shared/user-journeys.md) | **User journeys and friction analysis**: 7 market-segment personas, funnel stages, friction taxonomy, 5 journey maps (passive depositor, agent operator, vault creator, vault manager, developer), cross-persona progression arcs, competitive UX benchmarks | | [tui-package.md](/docs/prd-shared/tui-package.md) | **@gotts.ai/tui**: Shared terminal UI package — 12 modules (colors, icons, tty, spinner, format, box, banner, logger, table, tasks, reporter, prompts), design principles, dependency rationale, integration patterns | *** ## Cross-Domain Dependency Map All four PRD domains form a layered architecture. Skills invoke agents, agents call MCP tools, tools interact with the protocol. The vault extends the core stack with its own tools, contracts, and agents. ``` ┌──────────────────────────────────────────────────────────────────────┐ │ USER / LLM INTENT │ └────────────────────────────┬─────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────────────────┐ │ SKILLS (prd/skills/) │ │ │ │ execute-swap ──────────────► trade-executor │ │ manage-liquidity ──────────► liquidity-manager │ │ analyze-pool ──────────────► pool-researcher │ │ research-and-trade ────────► token-analyst + risk-assessor │ │ + trade-executor │ │ full-lp-workflow ──────────► opportunity-scanner + lp-strategist │ │ + risk-assessor + liquidity-manager │ │ deploy-agent-token ────────► token-deployer │ │ manage-vault ──────────────► vault-manager │ │ vault-strategy ────────────► vault-strategist │ └────────────────────────────┬─────────────────────────────────────────┘ │ delegates via Task(subagent_type:...) ▼ ┌──────────────────────────────────────────────────────────────────────┐ │ AGENTS (prd/agents/) — 32 agents │ │ │ │ Execution: trade-executor, liquidity-manager, cross-chain-executor │ │ Research: pool-researcher, token-analyst, opportunity-scanner, │ │ portfolio-analyst, pnl-analyst │ │ Strategy: lp-strategist, risk-assessor │ │ Dev: hook-builder, integration-architect, integration-advisor │ │ Infra: safety-guardian (terminal), wallet-provisioner (terminal)│ │ Economy: treasury-manager, token-deployer, identity-verifier, │ │ protocol-fee-seeker, agent-service-broker, │ │ competition-participant, strategy-optimizer, yield-scout │ │ Real-Time: market-monitor, position-monitor │ │ Vault: vault-manager, vault-strategist, vault-watchdog, │ │ vault-auctioneer, vault-creator, vault-allocator, │ │ vault-executor │ │ │ │ Delegation DAG (acyclic): │ │ trade-executor ──► safety-guardian, risk-assessor │ │ liquidity-manager ──► safety-guardian, risk-assessor, │ │ pool-researcher │ │ treasury-manager ──► trade-executor, liquidity-manager, │ │ risk-assessor │ │ vault-manager ──► safety-guardian, risk-assessor │ │ vault-strategist ──► pool-researcher, risk-assessor │ └────────────────────────────┬─────────────────────────────────────────┘ │ calls MCP tools ▼ ┌──────────────────────────────────────────────────────────────────────┐ │ GOTTS SAFE (prd/mcp-server/ + vault profile) │ │ │ │ Profile: data (18) │ trader (27) │ lp (37) │ vault (40) │ │ Profile: fees (25) │ erc8004 (28) │ intelligence (38) │ full (147) │ │ Profile: dev (all + testnet + debug) │ │ │ │ Core: Data, Historical, Token Dir, Trading, Liquidity, Streaming │ │ Protocol Fees, Approval, Safety, Testnet, Utility │ │ CCA/Token Launch, Intelligence, x402 External, ERC-8004 Identity │ │ ─ ─ ─ ─ ─ ─ ─ ─ Vault Profile (unified) ─ ─ ─ ─ ─ ─ ─ ─ │ │ Vault Ops, Vault Strategy, Vault Identity, am-AMM Auction │ └────────────────────────────┬─────────────────────────────────────────┘ │ ┌───────────────────┴───────────────────┐ │ │ ▼ ▼ ┌──────────────────────┐ ┌──────────────────────────────┐ │ UNISWAP PROTOCOL │ │ GOTTS VAULTS SDK │ │ │ │ (packages/vault/) │ │ V2, V3, V4 │ │ VaultClient, StrategyEngine │ │ UniswapX │ │ CCABidder, HookDeployer │ │ Universal Router │ │ AgentVaultCore (spec) │ │ Permit2 │ │ AgentVaultFactory (spec) │ │ ERC-7683 │ │ VaultHook (spec) │ │ TokenJar/Firepit │ │ StrategyAuctionModule (am-AMM) │ │ CCA/Liquidity Launch │ │ │ │ am-AMM (Bunni v2) │ │ SDK imported by vault tools │ │ │ │ registered in Gotts Safe │ └───────────────────────┘ └──────────────────────────────┘ ``` ### Phase Coordination Across Domains Implementation phases have cross-domain dependencies. Building a feature in one domain may unblock work in another. | If you build... | It unblocks... | | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | Gotts Safe Profile system | All domains: agents select minimal tool surface for their use case | | Gotts Safe Phase 5 (prompt defense, rep gates) | Agents: safety-guardian hardening, reputation-gated agent access | | Gotts Safe Phase 6 (CCA tools) | Skills: `participate-cca`, `launch-token-cca`; Agents: `token-deployer` CCA path | | Gotts Safe Phase 7 (intelligence tools) | Skills: enhanced `research-token`, `assess-risk`; Agents: all research agents gain intelligence tools | | Vault Phase 1-2 (factory, core tools) | Skills: `deposit-vault`, `manage-vault`; Agents: `vault-manager`, `vault-strategist` | | Vault Phase 3 (am-AMM + proxy safety) | am-AMM management auctions, `vault-auctioneer` agent, time-delayed execution | | Vault Phase 4 (adapter architecture) | Pluggable strategy integrations, `forceDeallocate()` exits | For detailed artifact-level status, see [shared/implementation-delta.md](/docs/prd-shared/implementation-delta.md). *** ## Ownership and Governance ### Document Standards All PRDs MUST conform to the spec semantics and quality gates defined in [shared/doc-standards.md](/docs/prd-shared/doc-standards.md). Key rules: * **Normative** (MUST/SHALL) language only in sections tagged `(Normative)` * **Informative** sections provide background, rationale, and examples * Every feature in a user journey must have a contract spec, tool/SDK spec, and acceptance tests -- or be marked `[Deferred]` * See [shared/doc-standards.md](/docs/prd-shared/doc-standards.md) for the full doc linter checklist ### Document Types This `prd/` directory contains three types of documents. See [shared/doc-standards.md](/docs/prd-shared/doc-standards.md) for the complete file-level classification. | Type | Purpose | Examples | | ------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | **PRD** | Product requirements and acceptance criteria (normative) | Most files -- overviews, tools, safety, contracts, SDK | | **OPS** | Deployment/runbooks and operational procedures (informative) | `mcp-server/14-deployment.md`, `mcp-server/15-install-wizard.md`, `vault/18-deployment.md` | | **REF** | Reference material, glossary, context, citations (informative) | `shared/*.md`, `vault/research-citations.md`, `vault/DECISIONS.md` | ### What belongs in PRDs * Product vision, goals, and non-goals * Feature specifications and acceptance criteria * Architecture decisions and design principles * Persona definitions and user journeys * Performance targets and success metrics * Milestone plans and scope definitions ### What does NOT belong in PRDs * API reference (belongs in `docs/` or `packages/*/docs/`) * Setup guides and runbooks (belong in OPS-typed files within `prd/` or in `docs/`) * Code conventions (belongs in `CLAUDE.md`) * AI asset definitions (agents in `packages/safe/agents/`, skills in `packages/safe/skills/`) *** ## PRD-to-Doc Update Workflow Any meaningful product change must update both the requirement side (PRD) and the implementation side (docs). Neither side is complete without the other. ``` 1. UPDATE PRD Edit the relevant PRD file(s) in prd/ | v 2. DIFF vs CURRENT Compare updated PRD against current implementation | state (code, IMPLEMENTATION-STATE.md, docs) v 3. PLAN CHANGES Write an implementation plan for the delta | v 4. IMPLEMENT Execute the plan, updating code | v 5. UPDATE DOCS Update implementation docs to match new behavior: | - docs/mcp-server/* for core MCP changes | - packages/vault/docs/* for vault changes | - packages/safe/agents/* and packages/safe/skills/* for agent/skill changes v 6. UPDATE STATE For vault: update prd/vault/IMPLEMENTATION-STATE.md For core: verify docs reflect actual tool surface ``` ### Review Gate A PRD or docs change is not complete unless: 1. Both sides of the canonical map are updated (requirements + implementation docs). 2. If the change affects vault, `IMPLEMENTATION-STATE.md` and `DRIFT-MATRIX.md` are updated. 3. If the change affects AI assets, mirrors are regenerated (`yarn sync:ai`) and drift check passes (`yarn check:ai-drift`). 4. Links in canonical index files (`prd/README.md`, `docs/README.md`, `packages/vault/docs/README.md`) are verified. *** ## Related Resources * [**docs/README.md**](/docs/readme.md) — Runtime and implementation docs index * [**CLAUDE.md**](https://github.com/wpank/gotts.ai-monorepo/blob/main/CLAUDE.md) — Project conventions, tech stack, architecture overview * [**TODO.md**](https://github.com/wpank/gotts.ai-monorepo/blob/main/TODO.md) — Active project work items