critesjosh · critesjosh · Jan 13, 2026
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "aztec",
-  "version": "1.0.0",
-  "description": "Claude Code plugin for Aztec smart contract and application development. Provides specialized agents, skills, and commands for building privacy-preserving applications on Aztec Network.",
+  "version": "2.0.0",
+  "description": "Claude Code plugin for Aztec smart contract and application development. Supports multiple Aztec versions (devnet, testnet, mainnet) with auto-detection from Nargo.toml.",
   "author": {
     "name": "critesjosh"
   },
@@ -12,10 +12,15 @@
     "privacy",
     "zk-rollup",
     "blockchain",
-    "web3"
+    "web3",
+    "multi-version"
   ],
   "license": "MIT",
   "repository": "https://github.com/critesjosh/aztec-claude-plugin",
+  "config": {
+    "defaultVersion": "devnet",
+    "supportedVersions": ["devnet", "testnet", "mainnet"]
+  },
   "mcpServers": {
     "context7": {
       "command": "npx",

diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,5 @@
 # Local configuration
-network.json
+.aztec-version
 
 # Claude Code local settings
 .claude/settings.local.json

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -2,6 +2,42 @@
 
 This project uses the Aztec Network for privacy-preserving smart contract development. Follow these guidelines when working with Aztec contracts and applications.
 
+## Version Detection
+
+This plugin supports multiple Aztec versions. **Default: devnet** (latest development).
+
+### Detecting Project Version
+
+When working with a user's Aztec project, detect their version:
+
+1. **Check for `.aztec-version`** file in project root (manual override)
+2. **Parse `Nargo.toml`** for the `aztec` dependency tag:
+   ```toml
+   aztec = { git = "...", tag = "aztec-packages-v0.87.4-devnet.0", ... }
+   ```
+3. **Match against version patterns** in `versions/versions.json`
+4. **Default to devnet** if no version detected
+
+### Supported Versions
+
+| Version | Tag Pattern | Status |
+|---------|-------------|--------|
+| devnet | `aztec-packages-v*-devnet*` or `v0.87+` | Default, active development |
+| testnet | `aztec-packages-v0.8[0-6]*` | Pre-release testing |
+| mainnet | `aztec-packages-v1.*` | Future stable release |
+
+### Version-Specific Syntax
+
+See `versions/<version>/syntax.md` for version-specific syntax reference. Key differences:
+- **Function attributes**: May vary between versions
+- **Storage patterns**: `Owned<>` wrapper requirements
+- **Note delivery**: `MessageDelivery` options
+
+When generating code, include a comment noting the target version:
+```rust
+// Target: Aztec devnet (aztec-packages-v0.87.x)
+```
+
 ## Technology Stack
 
 - **Noir**: Domain-specific language for writing Aztec smart contracts
@@ -265,10 +301,14 @@ name = "my_contract"
 type = "contract"
 
 [dependencies]
-aztec = { git = "https://github.com/AztecProtocol/aztec-packages/", tag = "aztec-packages-v0.XX.X", directory = "noir-projects/aztec-nr/aztec" }
-value_note = { git = "https://github.com/AztecProtocol/aztec-packages/", tag = "aztec-packages-v0.XX.X", directory = "noir-projects/aztec-nr/value-note" }
+# Use the same tag for all aztec-packages dependencies
+# Check https://github.com/AztecProtocol/aztec-packages/tags for latest
+aztec = { git = "https://github.com/AztecProtocol/aztec-packages/", tag = "aztec-packages-v0.87.4-devnet.0", directory = "noir-projects/aztec-nr/aztec" }
+value_note = { git = "https://github.com/AztecProtocol/aztec-packages/", tag = "aztec-packages-v0.87.4-devnet.0", directory = "noir-projects/aztec-nr/value-note" }
 ```
 
+**Important**: Match the tag to your target network version. See `versions/versions.json` for version patterns.
+
 ## Looking Up Latest Documentation
 
 This plugin includes the Context7 MCP server for fetching up-to-date Aztec documentation. Use it when:

diff --git a/NETWORK.md b/NETWORK.md
@@ -1,66 +1,91 @@
-# Network Versions
+# Version Support
 
-This plugin supports multiple Aztec network versions. Each network may have different syntax, APIs, and patterns.
+This plugin supports multiple Aztec versions within a single installation. No git branches or switching required.
 
-## Available Networks
+## Available Versions
 
-### mainnet
-- **Status**: Stable production release
-- **Aztec Version**: Latest stable
-- **Use when**: Deploying to production, building for mainnet users
+### devnet (Default)
+- **Status**: Active development
+- **Tag Pattern**: `aztec-packages-v*-devnet*` or `v0.87+`
+- **Use when**: New development, experimenting with latest features
+- **Syntax reference**: `versions/devnet/syntax.md`
 
 ### testnet
 - **Status**: Pre-release testing
-- **Aztec Version**: Release candidate
-- **Use when**: Testing before mainnet deployment, integration testing
+- **Tag Pattern**: `aztec-packages-v0.8[0-6]*`
+- **Use when**: Integration testing, pre-production validation
+- **Syntax reference**: `versions/testnet/syntax.md`
 
-### devnet
-- **Status**: Active development
-- **Aztec Version**: Latest development build
-- **Use when**: Experimenting with new features, contributing to Aztec
+### mainnet
+- **Status**: Future stable release
+- **Tag Pattern**: `aztec-packages-v1.*`
+- **Use when**: Production deployments (when available)
+- **Syntax reference**: `versions/mainnet/syntax.md`
 
-## Switching Networks
+## Version Detection
 
-```bash
-# Switch to testnet
-./setup.sh testnet
+The plugin auto-detects your project's version from `Nargo.toml`:
+
+```toml
+[dependencies]
+aztec = { git = "...", tag = "aztec-packages-v0.87.4-devnet.0", directory = "..." }
+```
 
-# Switch to devnet
-./setup.sh devnet
+### Manual Selection
 
-# Check current network
-./setup.sh status
+```bash
+./setup.sh devnet    # Use devnet syntax
+./setup.sh testnet   # Use testnet syntax
+./setup.sh mainnet   # Use mainnet syntax
+./setup.sh status    # Show current version
+./setup.sh detect    # Auto-detect from project
 ```
 
-## Version Differences
+### Using /aztec:detect-version
+
+Run the slash command to scan your project and report the detected version with syntax details.
 
-### Syntax Changes by Version
+## Syntax Differences by Version
 
-Each branch contains version-specific documentation in `CLAUDE.md` and the skills/commands directories. Key areas that may differ:
+| Feature | devnet | testnet | mainnet |
+|---------|--------|---------|---------|
+| Function attributes | `#[external("private")]` | `#[external("private")]` | TBD |
+| Storage wrapping | `Owned<PrivateSet<>>` | `Owned<PrivateSet<>>` | TBD |
+| Note delivery | `MessageDelivery::CONSTRAINED_ONCHAIN` | `MessageDelivery::CONSTRAINED_ONCHAIN` | TBD |
 
-| Feature | mainnet | testnet | devnet |
-|---------|---------|---------|--------|
-| Note delivery | `.deliver()` | `.deliver()` | `.deliver(MessageDelivery.*)` |
-| Storage patterns | `Map<>` | `Map<>` | `Owned<>` |
-| Function attributes | `#[aztec(private)]` | `#[external("private")]` | `#[external("private")]` |
+> **Note**: Mainnet syntax will be documented when mainnet launches. See `versions/<version>/syntax.md` for complete syntax references.
 
-> **Note**: This table is illustrative. Check the branch-specific `CLAUDE.md` for accurate syntax.
+## Version Files
 
-## Branch Management
+```
+versions/
+├── versions.json          # Version patterns and metadata
+├── devnet/
+│   └── syntax.md          # Complete devnet syntax reference
+├── testnet/
+│   └── syntax.md          # Complete testnet syntax reference
+└── mainnet/
+    └── syntax.md          # Mainnet syntax (placeholder)
+```
 
-When updating the plugin for a new Aztec release:
+## Configuration
+
+The active version is stored in `.aztec-version`:
+
+```json
+{
+  "version": "devnet",
+  "setAt": "2025-01-13T00:00:00Z",
+  "note": "Plugin configured for devnet syntax."
+}
+```
 
-1. Create/update the appropriate branch
-2. Update `CLAUDE.md` with new syntax
-3. Update skills and commands as needed
-4. Test with the target network
-5. Tag the release (e.g., `testnet-v0.87.0`)
+This file is created by `./setup.sh` and can be committed to your project to share version settings with your team.
 
-## Compatibility
+## Compatibility Notes
 
-The plugin attempts to use syntax compatible with:
-- **mainnet**: aztec-packages stable releases
-- **testnet**: aztec-packages release candidates
-- **devnet**: aztec-packages master branch
+- **Default behavior**: Uses devnet syntax if no version detected
+- **Version mismatch**: Claude will warn if multiple Nargo.toml files have different versions
+- **Unknown versions**: Falls back to devnet with a warning
 
 Always verify against the [official Aztec documentation](https://docs.aztec.network) for your target version.
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 A Claude Code plugin for Aztec smart contract and application development. This plugin provides specialized agents, skills, and commands to help you build privacy-preserving applications on the Aztec Network.
 
-⚠️ This plugin is currently set up to run on v3.0.0-devnet.20251212
+**Supports multiple Aztec versions** with auto-detection from your project's Nargo.toml.
 
 ## Installation
 
@@ -39,36 +39,48 @@ git pull
 
 Changes take effect on the next Claude Code session.
 
-## Network Versions
+## Version Support
 
-This plugin supports multiple Aztec network versions with potentially different syntax. Switch between them based on your target deployment:
+This plugin supports multiple Aztec versions. **Default: devnet** (latest development).
 
-```bash
-# Clone with a specific network version
-git clone https://github.com/critesjosh/aztec-claude-plugin
-cd aztec-plugin
-./setup.sh testnet  # or: mainnet, devnet
+### Auto-Detection
+
+The plugin automatically detects your project's Aztec version from `Nargo.toml`:
+
+```toml
+aztec = { git = "...", tag = "aztec-packages-v0.87.4-devnet.0", ... }
 ```
 
-### Available Networks
+### Available Versions
 
-| Network   | Description               | Use Case                        |
-| --------- | ------------------------- | ------------------------------- |
-| `mainnet` | Stable production release | Production deployments          |
-| `testnet` | Pre-release testing       | Integration testing             |
-| `devnet`  | Latest development        | Experimenting with new features |
+| Version   | Tag Pattern                    | Status                         |
+| --------- | ------------------------------ | ------------------------------ |
+| `devnet`  | `aztec-packages-v*-devnet*`    | Default, active development    |
+| `testnet` | `aztec-packages-v0.8[0-6]*`    | Pre-release testing            |
+| `mainnet` | `aztec-packages-v1.*`          | Future stable release          |
 
-### Switching Networks
+### Manual Version Selection
 
 ```bash
-# Switch to a different network
-./setup.sh devnet
+# Set version manually
+./setup.sh devnet     # Use devnet syntax (default)
+./setup.sh testnet    # Use testnet syntax
+./setup.sh mainnet    # Use mainnet syntax (when available)
+
+# Auto-detect from Nargo.toml
+./setup.sh detect
 
-# Check current network
+# Check current version
 ./setup.sh status
 ```
 
-See [NETWORK.md](./NETWORK.md) for detailed version differences.
+### Slash Command
+
+```
+/aztec:detect-version    # Scan project and report version
+```
+
+See [NETWORK.md](./NETWORK.md) for detailed version differences and syntax references.
 
 ## Features
 
@@ -191,8 +203,12 @@ aztec-plugin/
 ├── .claude-plugin/
 │   └── plugin.json          # Plugin manifest
 ├── .lsp.json                # Noir LSP configuration
-├── setup.sh                 # Network version switcher
-├── network.json             # Current network config (git-ignored)
+├── setup.sh                 # Version selector (no git required)
+├── versions/                # Version-specific syntax references
+│   ├── versions.json        # Version definitions and patterns
+│   ├── devnet/syntax.md     # Devnet syntax reference
+│   ├── testnet/syntax.md    # Testnet syntax reference
+│   └── mainnet/syntax.md    # Mainnet syntax reference
 ├── NETWORK.md               # Version differences documentation
 ├── agents/
 │   ├── contract-reviewer.md # Contract review agent

diff --git a/commands/detect-version.md b/commands/detect-version.md
@@ -0,0 +1,74 @@
+---
+description: Detect and display the Aztec version for the current project
+---
+
+# Detect Aztec Version
+
+Scan the current project to determine which Aztec version is being used and report the appropriate syntax variant.
+
+## Instructions
+
+1. **Search for Nargo.toml files** in the project:
+   - Check project root
+   - Check `contracts/` directory
+   - Check any subdirectories with `Nargo.toml`
+
+2. **Extract the version tag** from the `aztec` dependency:
+   ```toml
+   aztec = { git = "...", tag = "aztec-packages-vX.Y.Z", directory = "..." }
+   ```
+
+3. **Match against version patterns**:
+   - `aztec-packages-v*-devnet*` or `v0.87+` → **devnet**
+   - `aztec-packages-v0.8[0-6]*` → **testnet**
+   - `aztec-packages-v1.*` → **mainnet**
+
+4. **Report findings**:
+   - Detected version (devnet/testnet/mainnet)
+   - Tag found in Nargo.toml
+   - Syntax reference file path
+   - Any version mismatches between multiple Nargo.toml files
+
+## Output Format
+
+```
+Aztec Version Detection
+=======================
+
+Nargo.toml files found:
+- contracts/token/Nargo.toml
+  Tag: aztec-packages-v0.87.4-devnet.0
+
+Detected version: devnet
+Syntax reference: versions/devnet/syntax.md
+
+Key syntax for this version:
+- Function attributes: #[external("private")]
+- Storage: Owned<PrivateSet<T, Context>, Context>
+- Note delivery: .deliver(MessageDelivery::CONSTRAINED_ONCHAIN)
+```
+
+## Version Mismatch Warning
+
+If multiple Nargo.toml files have different version tags, warn the user:
+
+```
+WARNING: Version mismatch detected!
+- contracts/token/Nargo.toml: aztec-packages-v0.87.4-devnet.0
+- contracts/bridge/Nargo.toml: aztec-packages-v0.85.0
+
+Recommendation: Align all dependencies to the same version.
+```
+
+## No Version Found
+
+If no Nargo.toml or no aztec dependency:
+
+```
+No Aztec version detected.
+Using default: devnet
+
+To set a specific version:
+- Run ./setup.sh <version>
+- Or create .aztec-version file
+```