add-plugin

name

add-plugin

description

Use this skill when the user wants to add, refactor, or generalize a `agentpay <plugin>` integration like Bitrefill. Follow the shared plugin registration path under `src/plugins`, keep plugin-specific API or scraping code under `src/lib/<plugin>` or `src/lib/<plugin>/`, reuse the existing Rust daemon signing and policy path through the shared CLI plugin context instead of reimplementing signing, and add focused CLI tests for the new plugin.

Add Plugin

Use this skill when the task is "add another plugin like Bitrefill" or "make plugin onboarding more reusable."

Ground Truth

• src/cli.ts is the main CLI entrypoint, but plugin-specific command trees should not be wired inline there.
• src/plugins/types.ts defines the shared CliPluginContext and the generic plugin registrar shape.
• src/plugins/index.ts is the registry for built-in plugins.
• src/plugins/bitrefill.ts is the reference implementation for a plugin that owns its own command tree.
• Plugin-specific HTTP or browser/bootstrap code belongs in src/lib/<plugin>.ts or src/lib/<plugin>/.
• Signing, policy checks, manual approval handling, and raw transaction broadcast plumbing stay on the existing AgentPay path exposed through CliPluginContext.

Default Architecture

1. Create src/plugins/<plugin>.ts.
2. Register the plugin in src/plugins/index.ts.
3. Keep plugin-local API normalization, transports, cookies, scraping, or challenge handling in src/lib/<plugin>*.
4. Keep src/cli.ts responsible only for assembling shared dependencies and calling registerBuiltinCliPlugins(...).
5. Reuse context.agent.runJson(...) plus context.broadcast.* for any payment flow that reaches the daemon.

Implementation Rules

• Do not add another large inline .command('<plugin>') block to src/cli.ts.
• Do not reimplement signing, nonce management, or policy logic in the plugin.
• If the plugin needs onchain payment, default to preview-first behavior and make live payment explicit with --broadcast.
• If the plugin only needs a quote plus an optional live payment path, prefer one buy-style command over a redundant separate price command.
• Keep plugin-specific error handling inside the plugin module when possible.
• If a remote API needs browser bootstrap, Cloudflare handling, or cookies, isolate that behind the plugin's transport/client layer instead of leaking it into the shared CLI.
• Pass only shared helpers through CliPluginContext; keep plugin business logic inside the plugin module.

Deterministic Workflow

1. Inspect src/plugins/bitrefill.ts to copy the current plugin structure and command style.
2. Add or extend the plugin client under src/lib/<plugin>*.
3. Add a new CliPlugin implementation under src/plugins/<plugin>.ts.
4. Register it in src/plugins/index.ts.
5. If the plugin needs signing or broadcast, use context.config, context.agent, and context.broadcast instead of shelling around the shared flow.
6. Add a focused CLI test file or extend the closest existing one under test/.
7. Run the plugin-focused tests and at least one agentpay <plugin> --help smoke check.

Testing Rule

• Prefer mocked CLI/integration tests over live third-party dependencies.
• Cover command registration, happy path output, unsupported modes, and any explicit challenge or approval state.
• If the plugin supports --broadcast, cover both preview-only and broadcast-backed flows.

References

• Read src/plugins/types.ts for the shared context contract.
• Read src/plugins/index.ts for plugin registration.
• Read src/plugins/bitrefill.ts for the current plugin pattern.
• Read the matching src/lib/<plugin>* module only when implementing that plugin's remote API behavior.