@goplausible/openclaw-algorand-plugin 0.5.0

package/lib/x402-fetch.ts

@@ -0,0 +1,213 @@
+/**
+ * x402-fetch: Agent-oriented HTTP fetch with x402 payment protocol support.
+ *
+ * Two-step flow:
+ * 1. Fetch URL → if 402, returns structured PaymentRequirements + instructions
+ * 2. Agent builds payment via algorand-mcp tools, retries with paymentHeader
+ *
+ * No @x402-avm/fetch dependency — plain fetch() with manual 402 parsing.
+ */
+
+export interface X402FetchParams {
+  url: string;
+  method?: string;
+  headers?: Record<string, string>;
+  body?: string;
+  paymentHeader?: string;
+}
+
+export interface X402FetchResult {
+  status: number;
+  paymentRequired?: boolean;
+  x402Version?: number;
+  accepts?: unknown[];
+  instructions?: string;
+  headers?: Record<string, string>;
+  body?: string;
+  paymentSettled?: unknown;
+  error?: string;
+}
+
+const PAYMENT_INSTRUCTIONS = `To pay for this resource, follow these steps using algorand-mcp tools:
+
+1. Check wallet: wallet_get_info { network: "<network>" }
+   — Map CAIP-2 identifier to network:
+     "algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=" → "testnet"
+     "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=" → "mainnet"
+
+2. Build fee payer transaction (facilitator sponsors fees for the group):
+   make_payment_txn {
+     from: "<feePayer from accepts[].extra.feePayer>",
+     to: "<feePayer>",
+     amount: 0,
+     fee: 2000,
+     flatFee: true,
+     network: "<network>"
+   }
+   — fee: 2000 covers both transactions in the group (1000 each). flatFee: true prevents SDK override.
+
+3. Build payment transaction (fee = 0 since facilitator covers it):
+   — For native ALGO (asset "0"):
+     make_payment_txn { from: "<your_address>", to: "<payTo>", amount: <maxAmountRequired>, fee: 0, flatFee: true, network: "<network>" }
+   — For ASA (asset is ASA ID):
+     make_asset_transfer_txn { from: "<your_address>", to: "<payTo>", assetIndex: <asset>, amount: <maxAmountRequired>, fee: 0, flatFee: true, network: "<network>" }
+
+4. Group the transactions:
+   assign_group_id { transactions: [fee_payer_txn, payment_txn] }
+
+5. Sign ONLY the payment transaction (index 1) with wallet:
+   wallet_sign_transaction { transaction: <grouped_payment_txn>, network: "<network>" }
+   — Leave the fee payer transaction (index 0) unsigned — the facilitator signs it.
+
+6. Encode the unsigned fee payer transaction to base64:
+   encode_unsigned_transaction { transaction: <grouped_fee_payer_txn> }
+   — Returns base64 bytes of the unsigned transaction (canonical algosdk encoding).
+
+7. Construct the PAYMENT-SIGNATURE payload as JSON:
+   {
+     "x402Version": 2,
+     "scheme": "exact",
+     "network": "<CAIP-2 network identifier from accepts>",
+     "payload": {
+       "paymentGroup": ["<base64 from encode_unsigned_transaction>", "<base64 from wallet_sign_transaction>"],
+       "paymentIndex": 1
+     },
+     "accepted": <the exact accepts[] entry you chose — copy it verbatim as an object, including all fields: scheme, network, price, payTo, asset, maxAmountRequired, extra, etc.>
+   }
+
+   IMPORTANT: The "accepted" field MUST be an exact copy of the accepts[] entry you chose to pay with.
+   Without it, the server cannot match your payment to a requirement and will reject with 402.
+
+8. Retry the request using x402_fetch with paymentHeader set to the JSON string above.
+
+Load the algorand-interaction skill for the full x402 payment workflow reference.`;
+
+export async function x402Fetch(params: X402FetchParams): Promise<X402FetchResult> {
+  const { url, method = "GET", headers = {}, body, paymentHeader } = params;
+
+  const requestHeaders: Record<string, string> = { ...headers };
+
+  if (paymentHeader) {
+    // x402 v2 protocol requires base64-encoded JSON in the PAYMENT-SIGNATURE header
+    const encoded = Buffer.from(paymentHeader).toString("base64");
+    requestHeaders["PAYMENT-SIGNATURE"] = encoded;
+  }
+
+  try {
+    const fetchOptions: RequestInit = {
+      method,
+      headers: requestHeaders,
+    };
+
+    if (body && (method === "POST" || method === "PUT" || method === "PATCH")) {
+      fetchOptions.body = body;
+      if (!requestHeaders["Content-Type"]) {
+        requestHeaders["Content-Type"] = "application/json";
+      }
+    }
+
+    const response = await fetch(url, fetchOptions);
+
+    // Collect response headers
+    const responseHeaders: Record<string, string> = {};
+    response.headers.forEach((value, key) => {
+      responseHeaders[key] = value;
+    });
+
+    // Handle 402 Payment Required
+    if (response.status === 402) {
+      return await handle402Response(response, responseHeaders);
+    }
+
+    // Handle all other responses
+    const responseBody = await response.text();
+
+    const result: X402FetchResult = {
+      status: response.status,
+      headers: responseHeaders,
+      body: responseBody,
+    };
+
+    // Check for payment settlement response header
+    const paymentResponse =
+      responseHeaders["payment-response"] ||
+      responseHeaders["x-payment-response"];
+    if (paymentResponse) {
+      try {
+        result.paymentSettled = JSON.parse(paymentResponse);
+      } catch {
+        result.paymentSettled = paymentResponse;
+      }
+    }
+
+    if (!response.ok) {
+      result.error = `HTTP ${response.status}: ${response.statusText}`;
+    }
+
+    return result;
+  } catch (err) {
+    return {
+      status: 0,
+      error: `Fetch failed: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+async function handle402Response(
+  response: Response,
+  responseHeaders: Record<string, string>,
+): Promise<X402FetchResult> {
+  let bodyText = "";
+  try {
+    bodyText = await response.text();
+  } catch {
+    // Body may not be readable
+  }
+
+  // Try to parse x402 payment requirements
+  let parsed: {
+    x402Version?: number;
+    accepts?: unknown[];
+    error?: string;
+    resource?: unknown;
+  } | null = null;
+
+  // First, check the payment-required header (base64-encoded JSON)
+  const paymentRequiredHeader = responseHeaders["payment-required"];
+  if (paymentRequiredHeader) {
+    try {
+      const decoded = Buffer.from(paymentRequiredHeader, "base64").toString("utf-8");
+      parsed = JSON.parse(decoded);
+    } catch {
+      // Header not valid base64 JSON — try body next
+    }
+  }
+
+  // Fallback: try parsing the body as JSON
+  if (!parsed) {
+    try {
+      parsed = JSON.parse(bodyText);
+    } catch {
+      // Not JSON — return raw
+    }
+  }
+
+  if (parsed && parsed.accepts && Array.isArray(parsed.accepts)) {
+    return {
+      status: 402,
+      paymentRequired: true,
+      x402Version: parsed.x402Version || 2,
+      accepts: parsed.accepts,
+      instructions: PAYMENT_INSTRUCTIONS,
+    };
+  }
+
+  // Fallback: 402 but not standard x402 format
+  return {
+    status: 402,
+    paymentRequired: true,
+    error: "Received 402 but could not parse x402 payment requirements",
+    body: bodyText,
+    headers: responseHeaders,
+  };
+}

package/memory/algorand-plugin.md

@@ -0,0 +1,82 @@
+# Algorand Plugin Guide
+
+This plugin enables three core capabilities:
+
+1. **Algorand Development** — Smart contracts, typed clients, React frontends via AlgoKit CLI and skills
+2. **Blockchain Interaction** — Algorand MCP server (99 tools) via mcporter
+3. **x402 Payment Protocol** — HTTP-native payments with Algorand as first-class chain
+
+## Skill Routing
+
+| Capability | Task | Skill |
+|------------|------|-------|
+| Development | CLI, examples, general workflows | `algorand-development` |
+| Development | TypeScript contracts & tools | `algorand-typescript` |
+| Development | Python contracts & tools | `algorand-python` |
+| Interaction | Blockchain interaction via MCP | `algorand-interaction` |
+| x402 | TypeScript x402 development | `algorand-x402-typescript` |
+| x402 | Python x402 development | `algorand-x402-python` |
+
+## Using Algorand MCP Tools
+
+The Algorand MCP server is configured in **mcporter** as `algorand-mcp`. Call tools like this:
+
+```bash
+# List all tools
+mcporter list algorand-mcp
+
+# Call a tool
+mcporter call algorand-mcp.wallet_get_info
+mcporter call algorand-mcp.get_account_info address=XXXXX network=testnet
+mcporter call algorand-mcp.search_assets name=USDC network=mainnet
+```
+
+**Key tool categories:**
+- `wallet_*` — Wallet operations (get_info, create, send transactions)
+- `get_account_*` / `search_*` — Account and asset queries
+- `algo_*` / `asa_*` — ALGO and ASA transfers
+- `nfd_*` — NFD (.algo) name lookups
+- `tinyman_*` — DEX swaps
+- `get_knowledge_*` — Developer documentation
+
+## Key things to remember
+
+- Always check wallet with `wallet_get_info` before blockchain operations
+- Use `get_knowledge_doc` for Algorand developer documentation
+- Mainnet = real value — always confirm with user before mainnet transactions
+- Default to testnet during development
+- Every transaction costs 0.001 ALGO minimum
+- Account needs 0.1 ALGO base + 0.1 per asset/app opt-in (MBR)
+
+## Common Mainnet Assets
+
+| Asset | ASA ID | Decimals |
+|-------|--------|----------|
+| ALGO | native (0) | 6 |
+| USDC | 31566704 | 6 |
+| USDT | 312769 | 6 |
+| goETH | 386192725 | 8 |
+| goBTC | 386195940 | 8 |
+
+## Important patterns
+
+- **NEVER use PyTEAL or Beaker** — these are legacy. Use Algorand TypeScript or Algorand Python.
+- **NEVER use AlgoExplorer** — obsolete. Use Allo.info for block/account/transaction data.
+- **NFD (.algo names)**: Always use `depositAccount` field for transactions.
+
+## External resources
+
+- GoPlausible: https://goplausible.com
+- Algorand: https://algorand.co
+- Algorand x402: https://x402.goplausible.xyz
+- Algorand x402 test endpoints: https://example.x402.goplausible.xyz/
+- Algorand x402 Facilitator: https://facilitator.goplausible.xyz
+- Testnet Faucet: https://lora.algokit.io/testnet/fund
+- Testnet USDC Faucet: https://faucet.circle.com/
+- Algorand Developer Docs: https://dev.algorand.co/
+- Algorand Developer Docs Github : https://github.com/algorandfoundation/devportal
+- Algorand Developer Examples Github : https://github.com/algorandfoundation/devportal-code-examples
+- GoPlausible x402-avm Documentation and Example code : https://github.com/GoPlausible/.github/blob/main/profile/algorand-x402-documentation/README.md
+- GoPlausible x402-avm Examples template Projects : https://github.com/GoPlausible/x402-avm/tree/branch-v2-algorand-publish/examples/
+- CAIP-2 Specification : https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md
+- Coinbase x402 Protocol : https://github.com/coinbase/x402

package/openclaw.plugin.json

@@ -0,0 +1,30 @@
+{
+  "id": "openclaw-algorand-plugin",
+  "name": "Algorand Integration",
+  "description": "Algorand blockchain integration with MCP and skills — by GoPlausible",
+  "version": "0.1.0",
+  "skills": [
+    "skills/algorand-development",
+    "skills/algorand-typescript",
+    "skills/algorand-python",
+    "skills/algorand-interaction",
+    "skills/algorand-x402-typescript",
+    "skills/algorand-x402-python"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enableX402": {
+        "type": "boolean",
+        "default": true,
+        "description": "Enable x402 micropayments skills"
+      }
+    }
+  },
+  "uiHints": {
+    "enableX402": {
+      "label": "Enable x402 Micropayments"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@goplausible/openclaw-algorand-plugin",
+  "version": "0.5.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Algorand blockchain integration for OpenClaw — by GoPlausible",
+  "author": "GoPlausible <info@goplausible.com>",
+  "homepage": "https://goplausible.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GoPlausible/openclaw-algorand-plugin"
+  },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "algorand",
+    "blockchain",
+    "mcp",
+    "x402",
+    "goplausible"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "main": "index.ts",
+  "files": [
+    "index.ts",
+    "setup.ts",
+    "lib/",
+    "skills/",
+    "memory/",
+    "openclaw.plugin.json"
+  ],
+  "openclaw": {
+    "extensions": ["./index.ts"]
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "algorand-mcp": "latest"
+  }
+}

package/setup.ts

@@ -0,0 +1,80 @@
+import * as p from "@clack/prompts";
+import { execSync } from "node:child_process";
+import { ALGORAND_MCP, GOPLAUSIBLE_SERVICES } from "./lib/mcp-servers.js";
+
+export interface AlgorandPluginConfig {
+  enableX402: boolean;
+}
+
+export async function runSetup(
+  existingConfig?: Partial<AlgorandPluginConfig>
+): Promise<AlgorandPluginConfig | null> {
+  p.intro("🔷 Algorand Plugin Setup — powered by GoPlausible");
+
+  // Step 1: Verify algorand-mcp binary is available
+  let mcpAvailable = false;
+  let mcpPath = "";
+  try {
+    mcpPath = execSync("which algorand-mcp", { encoding: "utf-8" }).trim();
+    mcpAvailable = true;
+  } catch {
+    // Binary not found in PATH
+  }
+
+  if (mcpAvailable) {
+    p.note(
+      `MCP Server: ${ALGORAND_MCP.name}\n` +
+        `Type: ${ALGORAND_MCP.type} (local)\n` +
+        `Command: ${ALGORAND_MCP.command}\n` +
+        `Path: ${mcpPath}\n` +
+        `Status: ✅ Available`,
+      "Algorand MCP"
+    );
+  } else {
+    p.log.warn(
+      `algorand-mcp binary not found in PATH.\n\n` +
+        `Options:\n` +
+        `  • Run with npx: npx algorand-mcp\n` +
+        `  • Install globally: npm install -g algorand-mcp\n` +
+        `  • Add node_modules/.bin to PATH`
+    );
+  }
+
+  // Step 2: x402 integration
+  const enableX402 = await p.confirm({
+    message: "Enable x402 micropayments integration?",
+    initialValue: existingConfig?.enableX402 ?? true,
+  });
+
+  if (p.isCancel(enableX402)) {
+    p.cancel("Setup cancelled.");
+    return null;
+  }
+
+  // Summary
+  const config: AlgorandPluginConfig = {
+    enableX402: enableX402 as boolean,
+  };
+
+  p.note(
+    `x402 Micropayments: ${config.enableX402 ? "Enabled" : "Disabled"}\n\n` +
+      `MCP Server Setup:\n` +
+      `  The Algorand MCP server (${ALGORAND_MCP.command}) provides 99 blockchain tools.\n` +
+      `  Configure it in your coding agent's MCP config:\n` +
+      `  • Claude Code: .mcp.json\n` +
+      `  • Cursor: .cursor/mcp.json\n` +
+      `  • OpenCode: opencode.json`,
+    "Configuration"
+  );
+
+  p.outro(
+    `🔷 Algorand plugin configured!\n\n` +
+      `   Next steps:\n` +
+      `   1. Run \`openclaw algorand-plugin init\` to add plugin memory\n` +
+      `   2. Configure algorand-mcp in your coding agent's MCP config\n` +
+      `   3. Restart OpenClaw gateway\n\n` +
+      `   Docs: ${GOPLAUSIBLE_SERVICES.website}`
+  );
+
+  return config;
+}

package/skills/algorand-development/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: algorand-development
+description: Comprehensive guide for Algorand development with AlgoKit — project initialization, CLI commands, example search, contract building workflows, ARC standards, and error troubleshooting. This is the parent skill for language-agnostic Algorand development. Use when working with AlgoKit CLI, searching for examples, understanding ARC standards, creating new projects, or troubleshooting errors. Strong triggers include "algokit init", "algokit project run build", "start localnet", "find an example", "search for contract", "ARC-4", "ARC-56", "logic eval error", "transaction rejected", "overspend", "create a new project", "initialize project".
+---
+
+# Algorand Development
+
+This is the aggregated parent skill for language-agnostic Algorand development tools, workflows, and standards. Use the reference files below to find detailed guidance for each topic.
+
+## Quick Start
+
+```bash
+# Install AlgoKit CLI
+pipx install algokit
+
+# Create a new project
+algokit init -n my-project -t typescript --answer preset_name production --defaults
+
+# Development cycle
+algokit project run build    # Compile contracts
+algokit project run test     # Run tests
+algokit localnet start       # Start local network
+algokit project deploy localnet  # Deploy
+```
+
+## Reference Guide
+
+Navigate to the appropriate reference based on your task.
+
+### AlgoKit CLI Commands
+
+Build, test, deploy, and manage local networks with AlgoKit CLI.
+
+- [use-algokit-cli.md](./references/use-algokit-cli.md) — CLI workflow and common commands
+- [use-algokit-cli-reference.md](./references/use-algokit-cli-reference.md) — Full CLI command reference
+
+### Searching Algorand Examples
+
+Find working contract examples and code patterns from Algorand Foundation repositories using WebFetch with raw GitHub URLs.
+
+- [search-algorand-examples.md](./references/search-algorand-examples.md) — Search workflow and priority repos
+- [search-algorand-examples-reference.md](./references/search-algorand-examples-reference.md) — WebFetch patterns and knowledge base reference
+
+### Creating Projects
+
+Initialize new Algorand projects using AlgoKit templates.
+
+- [create-project.md](./references/create-project.md) — Project creation workflow
+- [create-project-reference.md](./references/create-project-reference.md) — Templates, presets, and CLI options
+
+### Building Smart Contracts
+
+General workflow for building Algorand smart contracts (language-agnostic steps).
+
+- [build-smart-contracts.md](./references/build-smart-contracts.md) — Contract building workflow
+- [build-smart-contracts-reference.md](./references/build-smart-contracts-reference.md) — Repository priorities and pattern lookups
+
+### Implementing ARC Standards
+
+ARC-4 ABI encoding, ARC-32/ARC-56 application specifications, and related standards.
+
+- [implement-arc-standards.md](./references/implement-arc-standards.md) — ARC overview and key standards
+- [implement-arc-standards-arc4.md](./references/implement-arc-standards-arc4.md) — ARC-4 ABI types, encoding, and method invocation
+- [implement-arc-standards-arc32-arc56.md](./references/implement-arc-standards-arc32-arc56.md) — Application specification format and usage
+
+### Troubleshooting Errors
+
+Diagnose and fix common Algorand development errors.
+
+- [troubleshoot-errors.md](./references/troubleshoot-errors.md) — Error diagnosis overview
+- [troubleshoot-errors-contract.md](./references/troubleshoot-errors-contract.md) — Smart contract and logic errors
+- [troubleshoot-errors-transaction.md](./references/troubleshoot-errors-transaction.md) — Transaction and account errors
+
+## Topic Quick Reference
+
+| Topic | Files | Description |
+| ----- | ----- | ----------- |
+| AlgoKit CLI | 2 | Build, test, deploy commands and localnet management |
+| Search Examples | 2 | WebFetch patterns for finding Algorand code examples |
+| Create Project | 2 | algokit init templates, presets, and options |
+| Build Contracts | 2 | Language-agnostic contract building workflow |
+| ARC Standards | 3 | ARC-4 ABI, ARC-32/56 app specs |
+| Troubleshoot | 3 | Error diagnosis for contracts and transactions |
+
+## How to Use This Skill
+
+1. **Start here** to understand which reference you need
+2. **Read the topic `.md`** file for step-by-step guidance
+3. **Consult the `-reference.md`** file for detailed API/CLI details
+4. **For language-specific content**, see the `algorand-typescript` or `algorand-python` parent skills

package/skills/algorand-development/references/build-smart-contracts-reference.md

@@ -0,0 +1,79 @@
+# Algorand Smart Contract Development Workflow Reference
+
+Follow this exact order when building smart contracts in either Algorand TypeScript or Algorand Python.
+
+## Step 1: Search Documentation
+
+Use `search_algorand_knowledge_sources` for conceptual guidance, best practices, and official documentation.
+
+If no results: proceed with caution, explain limitations, use known patterns.
+
+## Step 2: Retrieve Canonical Examples
+
+Use GitHub tools to get code from these repositories in priority order:
+
+### Priority 1: DevPortal Code Examples
+`algorandfoundation/devportal-code-examples`
+- TypeScript: `projects/typescript-examples/contracts/`
+- Python: `projects/python-examples/contracts/`
+- Always include corresponding test files
+
+### Priority 2: Puya Compiler Examples
+- TypeScript: `algorandfoundation/puya-ts` -> `examples/`
+- Python: `algorandfoundation/puya` -> `examples/`
+- Examples: hello_world_arc4, voting, amm
+
+### Priority 3: AlgoKit Templates
+- TypeScript: `algorandfoundation/algokit-typescript-template`
+- Python: `algorandfoundation/algokit-python-template`
+
+### Priority 4: AlgoKit Utilities
+- `algorandfoundation/algokit-cli`
+- `algorandfoundation/algokit-client-generator-ts`
+- `algorandfoundation/algokit-utils-ts`
+
+## Step 3: Pattern-Specific Lookups
+
+For specific patterns, search these locations:
+
+### Box Storage
+- TypeScript: `devportal-code-examples/projects/typescript-examples/contracts/BoxStorage/`
+- Python: `puya/examples/voting/` or `puya/examples/amm/` (BoxMap patterns)
+
+### Common Patterns
+State management, ABI methods, inner transactions: Start in `contracts/` subdirectories of Priority 1 repos.
+
+| Scenario | TypeScript Path | Python Path |
+|----------|----------------|-------------|
+| Box storage | `typescript-examples/contracts/BoxStorage/` | `puya/examples/voting/`, `puya/examples/amm/` |
+| Inner transactions | `puya-ts/examples/` (search for itxn) | `puya/examples/` (search for itxn) |
+| ARC-4 methods | `puya-ts/examples/hello_world_arc4/` | `puya/examples/hello_world_arc4/` |
+| State management | GlobalState, LocalState in examples | GlobalState, LocalState in examples |
+
+## Step 4: Generate Code
+
+- Carefully adapt canonical examples
+- Preserve all safety checks and efficient patterns
+- For TypeScript: follow rules from the `algorand-typescript` skill
+- For Python: follow rules from the `algorand-python` skill
+
+## Step 5: Include Tests
+
+- Always include or suggest integration tests
+- Use generated clients for testing contracts
+- Only include unit tests if explicitly requested by user
+
+## Step 6: Build and Test
+
+```bash
+algokit project run build   # Compile contracts
+algokit project run test    # Run tests
+```
+
+Iterate on fixes if compilation errors or test failures occur.
+
+### Key Points
+
+- **Use CLI for deployment**: `algokit project deploy localnet` handles large app specs
+- **Use `methodSignature` for calls**: Simpler than passing full app spec
+- **Get App ID from deployment output**: Required for all MCP calls

package/skills/algorand-development/references/build-smart-contracts.md

@@ -0,0 +1,52 @@
+# Building Smart Contracts
+
+Create modern Algorand smart contracts in Algorand TypeScript (PuyaTs) or Algorand Python (PuyaPy) -- statically-typed subsets compiled to TEAL bytecode by the Puya compiler.
+
+## Core Workflow
+
+1. **Search documentation** for concepts and best practices
+2. **Retrieve canonical examples** from priority repositories
+3. **Generate code** adapting examples to requirements
+4. **Include integration tests** using generated clients
+5. **Build and test** with AlgoKit commands
+
+## How to Proceed
+
+1. **Search documentation first:**
+   - Use `get_knowledge_doc` or `list_knowledge_docs` from the Algorand MCP server (Remote Full or Local) for conceptual guidance
+   - Categories: `arcs`, `sdks`, `algokit`, `algokit-utils`, `tealscript`, `puya`, `developers`, `clis`, `nodes`
+   - If MCP unavailable, use web search: `site:dev.algorand.co {concept}`
+
+2. **Retrieve canonical examples:**
+   - Use WebFetch with raw GitHub URLs from priority repositories:
+   - Priority 1: `https://raw.githubusercontent.com/algorandfoundation/devportal-code-examples/main/`
+   - Priority 2: `https://raw.githubusercontent.com/algorandfoundation/puya-ts/main/examples/` (TypeScript) or `https://raw.githubusercontent.com/algorandfoundation/puya/main/examples/` (Python)
+   - Priority 3: `https://raw.githubusercontent.com/algorandfoundation/algokit-typescript-template/main/` or `https://raw.githubusercontent.com/algorandfoundation/algokit-python-template/main/`
+   - Always include corresponding test files
+
+3. **Generate code:**
+   - Choose TypeScript or Python based on user preference
+   - Adapt examples carefully, preserving safety checks
+   - Follow syntax rules from the language-specific skill (`algorand-typescript` or `algorand-python`)
+
+4. **Include tests:**
+   - Always include or suggest integration tests
+   - Use generated clients for testing contracts
+
+5. **Build and test:**
+   ```bash
+   algokit project run build   # Compile contracts
+   algokit project run test    # Run tests
+   ```
+
+## Important Rules
+
+- **NEVER use PyTEAL or Beaker** -- these are legacy, superseded by Puya
+- **NEVER write raw TEAL** -- always use Algorand TypeScript or Algorand Python
+- **NEVER import external libraries** into contract code
+- **Always search docs first** before writing code
+- **Always retrieve examples** from priority repositories
+
+## References
+
+- [Detailed Workflow](./build-smart-contracts-reference.md)