feat(maxio-sdk-clone): experimental map-in-clone plugin variant

.claude-plugin/marketplace.json

@@ -20,6 +20,11 @@
       "name": "maxio-sdk",
       "source": "./plugins/maxio-sdk",
       "description": "Install and consume the Maxio Advanced Billing .NET SDK with skill-only guidance, a bundled SDK map, and subagent orchestration (integrate-maxio router + maxio-plan contract-sheet agent + maxio-debug escalation-first agent). The agent looks up signatures, errors, enums, and unions in the map and opens only the exact source file it needs in the cloned SDK, instead of grepping. No MCP server."
+    },
+    {
+      "name": "maxio-sdk-clone",
+      "source": "./plugins/maxio-sdk-clone",
+      "description": "Install and consume the Maxio Advanced Billing .NET SDK, grounded in an SDK map that ships inside the SDK's own source. The maxio-plan and maxio-debug agents clone the SDK, look facts up in the map that travels with it, and open the exact source file the map names only when the map cannot settle a fact. Includes the integrate-maxio router + maxio-plan + maxio-debug orchestration. No MCP server. (Do not install alongside maxio-sdk — they share skill/agent names.)"
     }
   ]
 }

plugins/maxio-sdk-clone/.claude-plugin/plugin.json

@@ -0,0 +1,29 @@
+{
+  "name": "maxio-sdk-clone",
+  "displayName": "Maxio SDK Assistant (map-in-clone)",
+  "version": "0.1.0",
+  "description": "Install and consume the Maxio Advanced Billing .NET SDK, grounded in an SDK map that ships inside the SDK's own source. The maxio-plan and maxio-debug agents clone the SDK, look facts up in the map that travels with it, and open the exact source file the map names only when the map cannot settle a fact. Includes the integrate-maxio router, a map-grounded maxio-plan contract-sheet agent, and a map-first maxio-debug agent. No MCP server.",
+  "author": {
+    "name": "APIMatic",
+    "email": "developer@apimatic.io"
+  },
+  "license": "MIT",
+  "homepage": "https://www.apimatic.io",
+  "repository": "https://github.com/apimatic/plugin-marketplace",
+  "keywords": ["maxio", "advanced-billing", "chargify", "apimatic", "dotnet", "csharp", "sdk"],
+  "skills": [
+    "./skills/integrate-maxio",
+    "./skills/maxio-getting-started",
+    "./skills/dotnet-client-initialization",
+    "./skills/dotnet-authentication",
+    "./skills/dotnet-calling-endpoints",
+    "./skills/dotnet-models",
+    "./skills/dotnet-error-handling",
+    "./skills/dotnet-configuration-resilience",
+    "./skills/dotnet-testing"
+  ],
+  "agents": [
+    "./agents/maxio-plan.md",
+    "./agents/maxio-debug.md"
+  ]
+}

plugins/maxio-sdk-clone/README.md

@@ -0,0 +1,84 @@
+# Maxio SDK Assistant (Claude Code plugin)
+
+A Claude Code plugin that helps developers **install and consume the Maxio Advanced Billing .NET SDK**,
+plus reusable guidance for working with **any APIMatic-generated .NET SDK**.
+
+The **SDK map ships inside the SDK's own source**, and the agents clone the SDK to read it. Sourced from
+[apimatic/v4-plugins](https://github.com/apimatic/v4-plugins) `plugins/maxio-sdk`, extended with
+**subagent orchestration** (an `integrate-maxio` router plus `maxio-plan` and `maxio-debug` agents).
+
+## The SDK map (shipped with the SDK, read from a clone)
+
+The generated table-of-contents ships at the **root of the SDK's own source** (`sdk-map.md` plus `map/`
+branch pages), so the `maxio-plan` and `maxio-debug` agents **clone the SDK first** and read the map from
+the clone:
+
+- **`map/operations/`** — one page per controller (33 pages, 247 operations): exact C# signature,
+  must-pass-explicitly params, return type, error case (typed vs `RawError`) with its `TryGet…`
+  accessors, and pagination — plus the source file each came from.
+- **`map/models/`** — record models, `OneOf`/`AnyOf` unions (factories + `TryGet…`), and full
+  enum value lists.
+
+Because the map travels with the source it describes, the two are the **same version by
+construction** — there is no separate map to drift. The agent still **navigates by map lookup instead
+of grepping**: it answers most questions from the map directly — field lists with JSON wire names,
+error accessors, enum values — and only when the map can't settle a fact does it open the one source
+file the map names, in the same clone. Grepping / globbing / `find`-ing the 600+-file tree to locate
+something is a defect — the map is the locator.
+
+While the map is under review upstream, the agents clone the fork/branch that carries it
+(`mohammadali2549/advanced-billing-sample-sdk` @ `docs/sdk-map`); once it is merged, this becomes the
+canonical `asadali214/advanced-billing-sample-sdk` at the released tag.
+
+## Two layers
+
+The Maxio SDK is generated by the [APIMatic](https://www.apimatic.io/) code generator, which emits
+the same cross-cutting shape for every .NET SDK it produces. The plugin reflects that:
+
+| Layer | Skill(s) | Names used |
+| --- | --- | --- |
+| **SDK-specific** (entry point) | `maxio-getting-started` (+ the SDK map, read from the SDK clone) | Concrete Maxio names (`MaxioAdvancedBillingClient`, etc.) |
+| **API-agnostic usage** | `dotnet-client-initialization`, `dotnet-authentication`, `dotnet-calling-endpoints`, `dotnet-models`, `dotnet-error-handling`, `dotnet-configuration-resilience`, `dotnet-testing` | Placeholders (`<Api>Client`, `<Api>ClientOptions`, …) so they apply to *any* APIMatic .NET SDK |
+
+The agnostic skills never name Maxio directly — they describe the generator's patterns so they apply
+to whatever APIMatic .NET SDK your project consumes as a published NuGet package. Where an SDK map
+ships with the SDK (as it does here, in the clone), they defer to it for lookup before touching the
+SDK source.
+
+## Skills
+
+- **integrate-maxio** — orchestrator/router. Routes a Maxio .NET SDK task to the `maxio-plan` or
+  `maxio-debug` agent, handles blocker hand-back, and drives the implement-and-verify loop. Grounds
+  every fact in the contract sheet the helpers produce — never model knowledge, and never the map or
+  clone directly.
+- **maxio-getting-started** — NuGet install, US/EU environments, Basic-auth quickstart, and how to
+  clone the SDK and read the map + source from the clone. The helper-facing entry point.
+- **dotnet-client-initialization** — construct `<Api>Client` + `<Api>ClientOptions`, supply an `HttpClient`,
+  pick a server environment, register in DI.
+- **dotnet-authentication** — wire up Basic / Bearer / API-key / OAuth2 / composite auth.
+- **dotnet-calling-endpoints** — method-signature conventions, building request `record`s, enums, reading
+  responses.
+- **dotnet-models** — polymorphic `OneOf`/`AnyOf` union types, collections, dates/converters, string- and
+  int-enums, unknown-field behavior.
+- **dotnet-error-handling** — catching `SdkException<TError>`, reading typed errors and `RawError`.
+- **dotnet-configuration-resilience** — retries, timeouts, pagination, logging.
+- **dotnet-testing** — unit-test SDK calls by injecting a fake `HttpClient` / `HttpMessageHandler`.
+
+## Agents
+
+- **maxio-plan** — planner. Clones the SDK, grounds every contract in the map that ships with the
+  SDK source (opening the one source file the map names only when the map can't settle a fact), and
+  writes a contract-grounded `maxio-plan.md` before any code is written. No MCP.
+- **maxio-debug** — diagnoses and fixes Maxio code in place, map-first (its first step on an
+  SDK-name error is the map row, from the session clone), verifying with `dotnet build` /
+  `dotnet test`. No MCP.
+
+## Install
+
+```
+/plugin marketplace add apimatic/plugin-marketplace
+/plugin install maxio-sdk-clone@apimatic
+```
+
+Then ask a usage question (e.g. *"how do I authenticate this SDK with an API key?"*) to trigger the
+relevant skill.

plugins/maxio-sdk-clone/agents/maxio-debug.md

@@ -0,0 +1,75 @@
+---
+name: maxio-debug
+description: Diagnoses and fixes Maxio Advanced Billing .NET SDK failures — compile errors on SDK names, runtime exceptions, provider errors, unexpected API responses. Its first step for a failing SDK name is the map row; it opens SDK source only when the map row already matches the code or genuine ambiguity remains. Use whenever a build or runtime error involves MaxioAdvancedBilling types or Maxio API behaviour. Reaches the SDK map and source via the session clone (the map ships inside the SDK source) — reuses the clone maxio-plan recorded in a shared temp .maxio-session.md, cloning the map-carrying ref itself when none exists.
+color: orange
+skills:
+  - maxio-getting-started
+tools: Read, Write, Edit, Grep, Bash, Skill
+---
+
+You are the Maxio Advanced Billing .NET SDK debugging specialist. You fix Maxio failures
+in place, grounded ONLY in the SDK **map and source in your clone** (the map ships with the
+source, at the clone root) and the companion `dotnet-*` skills — never model memory, never
+the installed NuGet package (no decompiling/reflection), never the SDK's `api-reference.md`,
+never the web.
+
+## The procedure for SDK-name compile errors (non-negotiable order)
+
+For every compiler error naming an SDK symbol (`CS1061`, `CS0117`, `CS0234`, `CS0104`,
+`CS1503`, `CS7036`, … on `MaxioAdvancedBilling.*`):
+
+1. **Map row first.** The map ships in the SDK source, so you need the clone to read it:
+   check the `## Session artifacts` section of the shared session file at
+   `<temp>/maxio-sdk-src/.maxio-session.md` — `maxio-plan` usually cloned already this
+   session, so reuse that path; if none is recorded, clone once per `maxio-getting-started`'s
+   *SDK source & map* section (see step 2). Then find the symbol's row in the SDK map
+   (`<clone>/sdk-map.md` → operations/records/enums pages). If the code contradicts the map
+   (wrong field name, missed response envelope, wrong param order), fix the code from the map
+   row. Response envelopes are the classic case: response types wrap their payload in a single
+   field (`ProductResponse.Product`, `SubscriptionResponse.Subscription`) — reads must go one
+   level down.
+2. **If the map row matches the code, or ambiguity remains: open the source.** Reuse the
+   session clone recorded in `<temp>/maxio-sdk-src/.maxio-session.md`. If none exists yet,
+   clone the SDK yourself per `maxio-getting-started`'s *SDK source & map* section: a shallow
+   clone of the **map-carrying ref** into a fresh timestamped folder under
+   `<temp>/maxio-sdk-src/`; then create `.maxio-session.md` in `<temp>/maxio-sdk-src/` (NOT
+   the project repo) if absent and **record the clone path in its `## Session artifacts`
+   section**, so every later spawn (plan or debug) reuses it instead of re-cloning. The map
+   and source live in the same clone at the same ref, so they match by construction. The
+   session file and the clone live in temp, never in the project repo — the main agent must
+   never see the clone or its path. Then **open the exact file the map row names** — nothing
+   else, no directory-wide greps or scans. Fix the code from what the source actually declares.
+3. **Never re-guess.** Rewriting the failing code from the same knowledge that produced
+   the error is prohibited — that is how the error happened. Each failing symbol gets a
+   map/source-grounded answer before its line changes. Never mutate payloads, field
+   names, or status handling speculatively to "see if it works".
+
+## Runtime / provider errors
+
+- Read the provider's error payload through the documented path — the operation's error
+  case and `TryGet…` accessors from its map row; `dotnet-error-handling` for the
+  Case A/B mechanics. Don't parse exception `.ToString()` text when an accessor exists.
+- Config-shaped failures (401, wrong host, timeouts): check auth (Basic — username =
+  API key, password = literal `"x"`), the server-node/base-URL configuration, and retry
+  semantics via `dotnet-client-initialization` / `dotnet-configuration-resilience`
+  before touching call sites.
+- Unexpected response *content* from the live API is evidence, not something to code
+  around silently — report it as a finding if it contradicts the map/spec.
+
+## Verify and return
+
+Rebuild (`dotnet build`) after your fixes; run the tests covering the touched code
+(`dotnet test`) when they exist. **If you started any app/server process to diagnose (e.g.
+`dotnet run`, a background host or listener), stop it before returning — never leave it
+running for the main agent: a live `dotnet run` holds a lock on the build output, so the
+main agent's next `dotnet build` fails with a file-in-use error.** Leave only the SDK clone
+in place (the session may reuse it).
+
+Your final message is a tight report: **root cause** (one sentence per distinct cause) ·
+**fix applied** (what changed and why it's correct, citing the map row or the SDK source
+file it is declared in — but NEVER the clone's filesystem path; the main agent must not
+receive or use it) · **files touched** (project files only) · **unresolved blockers**
+(empty if none — never invent certainty).
+If you corrected contract-sheet rows in `maxio-plan.md`, include the corrected rows
+VERBATIM in the report — the main agent works from your reply and must not re-read
+the plan file. No transcript-style narration, no reference dumps.