From 2c2c5cd863ac3f6815e79502ed937eab3978fe18 Mon Sep 17 00:00:00 2001 From: Jarrod Watts Date: Thu, 12 Mar 2026 14:17:40 +1100 Subject: [PATCH] docs: define agw rename compatibility strategy --- README.md | 6 ++ app/README.md | 4 +- meta/decisions.md | 3 +- meta/prd.md | 10 +++- meta/product.md | 11 +++- meta/rename-compatibility-strategy.md | 83 +++++++++++++++++++++++++++ meta/user-flows.md | 12 +++- 7 files changed, 122 insertions(+), 7 deletions(-) create mode 100644 meta/rename-compatibility-strategy.md diff --git a/README.md b/README.md index 4e6dfe8..44d90ad 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,12 @@ MCP server for Abstract wallet, chain, and Portal API data. +## Naming Roadmap + +The current published package is `@abstract-foundation/agw-mcp`, and the commands below reflect what works today. The repo plan is to rename the canonical repo/package/binary identity to `agw`, while keeping `@abstract-foundation/agw-mcp` and `agw-mcp` as compatibility shims during the migration window. + +See [meta/rename-compatibility-strategy.md](meta/rename-compatibility-strategy.md) for the locked rollout, binary, and install-flow rules. + ## Quick Start ```bash diff --git a/app/README.md b/app/README.md index 7aaec18..b1ce6a7 100644 --- a/app/README.md +++ b/app/README.md @@ -1,6 +1,8 @@ # AGW MCP Hosted Onboarding App -This package hosts the browser-side onboarding flow for `agw-mcp init`. +This package hosts the browser-side onboarding flow for the CLI bootstrap path: `agw-mcp init` today, and `agw init` once the rename release ships. + +See `../meta/rename-compatibility-strategy.md` for the canonical package/binary migration rules. ## Entry Point diff --git a/meta/decisions.md b/meta/decisions.md index aa35e22..835cc40 100644 --- a/meta/decisions.md +++ b/meta/decisions.md @@ -2,7 +2,7 @@ | id | date | decision | rationale | status | | --- | --- | --- | --- | --- | -| ADR-001 | 2026-02-18 | Use standalone `agw-mcp` repo | Separate release/security surface from SDK monorepo | accepted | +| ADR-001 | 2026-02-18 | Use standalone repo (initially `agw-mcp`) | Separate release/security surface from SDK monorepo; canonical rename handled later by ADR-020 | superseded | | ADR-002 | 2026-02-18 | Session-key-only model for v1 | Align with AGW non-custodial design | accepted | | ADR-003 | 2026-02-18 | Local stdio MCP first | Faster iteration with lower operational risk | accepted | | ADR-004 | 2026-02-18 | Direct-to-main autonomous mode | Maximize unattended overnight throughput | accepted | @@ -21,3 +21,4 @@ | ADR-017 | 2026-02-18 | Enforce session-key least-privilege defaults | Align with AGW session-key safety model and reduce autonomous agent blast radius | accepted | | ADR-018 | 2026-02-18 | Require AGW action parity for write/sign tools | Keep MCP execution paths aligned with official AGW SDK action semantics | accepted | | ADR-019 | 2026-02-18 | Harden loop runtime for unattended operation | Add stale-lock recovery, retries, and overnight wrapper to reduce operational interruptions | accepted | +| ADR-020 | 2026-03-12 | Converge repo/package/binary identity on `agw` with `@abstract-foundation/agw-mcp` compatibility shim | Keeps long-term naming simple without breaking existing installs or MCP registrations | accepted | diff --git a/meta/prd.md b/meta/prd.md index b5a8550..9217392 100644 --- a/meta/prd.md +++ b/meta/prd.md @@ -1,8 +1,16 @@ -# AGW MCP PRD (v1) +# AGW PRD (v1) ## Scope Build a local stdio MCP server and local companion app for AGW users to perform common crypto wallet actions through session keys. +## Naming + Compatibility Requirements +- The steady-state repo, package, and binary identity is `agw`. +- The current package, `@abstract-foundation/agw-mcp`, must remain the migration source and compatibility install path until the rename rollout completes. +- The canonical CLI binary after the rename is `agw`; `agw-mcp` is legacy-only and should live in the compatibility package, not alongside the canonical binary. +- The MCP server alias remains `agw` so client configuration names stay stable. +- Local state migration from `~/.agw-mcp` is a separate follow-up; the rename release should not force re-onboarding. +- Detailed rollout rules live in `meta/rename-compatibility-strategy.md`. + ## Core Tool Surface (v1) - `get_wallet_address` - `get_balances` diff --git a/meta/product.md b/meta/product.md index fa85647..f078327 100644 --- a/meta/product.md +++ b/meta/product.md @@ -1,8 +1,17 @@ -# Product Brief: AGW MCP +# Product Brief: AGW ## Mission Enable Abstract users with AGW wallets to use AI agents for common wallet operations through session keys. +## Product Identity +- Canonical long-term product identity: `agw` +- Current shipping repo identity: `Abstract-Foundation/agw-mcp` +- Canonical repo target after rename: `Abstract-Foundation/agw` +- Current shipping npm identity: `@abstract-foundation/agw-mcp` +- Canonical CLI target after rename: `agw` +- Compatibility package/binary during migration: `@abstract-foundation/agw-mcp` and `agw-mcp` +- Source of truth for rollout constraints: `meta/rename-compatibility-strategy.md` + ## Primary User (v1) - End users of Abstract Global Wallet who want AI-assisted wallet interactions. diff --git a/meta/rename-compatibility-strategy.md b/meta/rename-compatibility-strategy.md new file mode 100644 index 0000000..89066a4 --- /dev/null +++ b/meta/rename-compatibility-strategy.md @@ -0,0 +1,83 @@ +# AGW Rename + Compatibility Strategy + +## Decision Summary + +- The canonical product, repo, package, and CLI identity should converge on `agw`. +- The currently published package, `@abstract-foundation/agw-mcp`, remains the compatibility entry point during the migration window. +- The canonical CLI binary becomes `agw`. +- The legacy CLI binary `agw-mcp` remains available only through the compatibility package. +- The MCP server alias stays `agw` throughout the migration so agent config names do not churn. + +## Surface Map + +| Surface | Current shipping identity | Canonical identity | Compatibility strategy | +| --- | --- | --- | --- | +| GitHub repo | `Abstract-Foundation/agw-mcp` | `Abstract-Foundation/agw` | Rename the repo when the `agw` package launch is ready; rely on GitHub redirects instead of maintaining two long-lived repos. | +| npm package | `@abstract-foundation/agw-mcp` | `agw` | Dual-publish at launch. After that, keep `@abstract-foundation/agw-mcp` as a thin compatibility shim that points users to `agw`. | +| CLI binary | `agw-mcp` | `agw` | The `agw` package ships only `agw`. The compatibility package ships only `agw-mcp` and forwards into the same implementation. | +| MCP server name | `agw` | `agw` | No change. Existing MCP client registrations keep working without renaming the server alias. | +| Local state directory | `~/.agw-mcp` | `~/.agw` eventually | Do not rename the state directory in the same release as the package/binary rename. Keep the old path during the compatibility window and handle filesystem migration in a dedicated follow-up. | + +## Rollout Phases + +### Phase 0: Planning Before Rename Ships + +- Docs must distinguish between the current shipping package (`@abstract-foundation/agw-mcp`) and the target canonical identity (`agw`). +- No install snippet should claim `npx -y agw` works until the package is actually published. +- Planning docs should treat `agw` as the steady-state name and `@abstract-foundation/agw-mcp` as the migration source. + +### Phase 1: Rename Launch + +- Publish the canonical package as `agw`. +- Keep the implementation aligned between `agw` and `@abstract-foundation/agw-mcp`. +- Rename the repo to `agw` in the same release window so package metadata, clone URLs, badges, and issue/PR links stay coherent. +- Flip primary docs and install snippets to `agw`. + +### Phase 2: Compatibility Window + +- Keep `npx -y @abstract-foundation/agw-mcp ...` working for existing users. +- Keep the `agw-mcp` binary working through the compatibility package only. +- Show migration guidance as a single-token rewrite: + - `npx -y @abstract-foundation/agw-mcp serve` -> `npx -y agw serve` + - `agw-mcp init` -> `agw init` +- Emit a deprecation notice from the compatibility package that points users to `agw`. + +### Phase 3: Compatibility Retirement + +- Do not remove `@abstract-foundation/agw-mcp` until `agw` has been the documented default for at least one stable release cycle. +- Remove the compatibility package only in a major release. +- When the compatibility package is retired, keep the retirement notice in the final deprecated package version and in the migration docs. + +## Binary Naming Rules + +- The only long-term binary is `agw`. +- The `agw` package must not also ship an `agw-mcp` bin because dual binaries create avoidable collisions in local installs and blur the migration target. +- The `agw-mcp` binary exists only to preserve legacy install flows that invoke the old package directly. +- Examples, screenshots, CLI help text, and onboarding copy should treat `agw` as canonical once Phase 1 ships. + +## Migration Constraints + +### Docs + +- README, product docs, onboarding docs, and config examples must flip in the same release window as the `agw` publish. +- Until then, docs should explicitly label `@abstract-foundation/agw-mcp` as the current package and `agw` as the target canonical name. +- Historical documents such as changelogs and dated beta plans can keep the old name if they are clearly time-bound. + +### Package Metadata + +- `agw` needs the canonical `name`, `bin`, `repository`, `homepage`, `bugs`, badges, and install snippets. +- `@abstract-foundation/agw-mcp` should become a compatibility package, not a second independently evolving product surface. +- The compatibility package README and npm deprecation message should point directly to `agw`. + +### User Install Flows + +- Fresh-install docs should move to `npx -y agw` as soon as Phase 1 ships. +- Existing scripts and MCP registrations that reference `@abstract-foundation/agw-mcp` should continue working during the compatibility window. +- The MCP server alias remains `agw`; users only need to swap the executable/package token, not the configured server name. +- The local session/state path stays on `~/.agw-mcp` during the rename window so upgrades do not force re-onboarding. + +## Out of Scope For This Rename Ticket + +- Filesystem migration from `~/.agw-mcp` to `~/.agw` +- Package implementation changes for dual-publish or deprecation messaging +- Post-rename telemetry or package download analysis diff --git a/meta/user-flows.md b/meta/user-flows.md index 14ed8a3..0e1e431 100644 --- a/meta/user-flows.md +++ b/meta/user-flows.md @@ -1,15 +1,21 @@ # User Flows (v1) +## Naming Assumptions +- Fresh-install docs should use `agw` once the rename release ships. +- The compatibility path remains `@abstract-foundation/agw-mcp` plus the `agw-mcp` binary during the migration window. +- The MCP server alias stays `agw`, and the local state path stays `~/.agw-mcp` until a separate filesystem migration ticket lands. +- See `meta/rename-compatibility-strategy.md` for the rollout rules. + ## Flow 1: First-Time Setup -1. User installs `agw-mcp` and connects it to an MCP-compatible agent. -2. User runs `agw-mcp init`. +1. User installs the MCP server package and connects it to an MCP-compatible agent. +2. User runs `agw init` on the canonical path or `agw-mcp init` through the compatibility package during the migration window. 3. User opens the local companion app and selects a safe policy preset (or custom mode). 4. User previews the computed policy payload and risk assessment (custom mode preloads a safe default template). 5. If the policy is high risk, user explicitly confirms risk in companion UI before redirect. 6. User completes AGW session provisioning flow. 7. Companion receives callback payload, signs it with the one-time handoff secret, and forwards it to local MCP callback URL. 8. Session is persisted locally and validated. -9. User runs `agw-mcp serve` and confirms `get_session_status` is active. +9. User runs `agw serve` on the canonical path or `agw-mcp serve` through the compatibility package and confirms `get_session_status` is active. Success criteria: - Setup completes without manual file editing.