*How we adopted Spec-Driven Development and built SuzieQ, Batfish, gNMI, Azure Networking, and Canvas visualizations in a single session.*
—
## Part 1: The Shift to Spec-Driven Development
NetClaw has always been ambitious. A CCIE-level AI network engineering coworker with 97 skills and 43 MCP integrations doesn’t get built by accident. But as the project grew, we hit a familiar problem: every new MCP server, every new skill, every new integration had a growing list of touchpoints that needed to stay in sync. The README. The install script. The SOUL.md identity file. The Three.js HUD. The .env.example. The TOOLS.md reference. The openclaw.json config. The SKILL.md documentation.
Miss one and you have a capability that exists in code but is invisible to the agent, or documented but not installable, or installable but not wired into the gateway.
So we adopted **Spec-Driven Development (SDD)** using [Speckit](https://github.com/nicholasgriffintn/speckit) and wrote a **project constitution** before writing a single line of new code.
### The NetClaw Constitution
The constitution is a living document with 16 non-negotiable principles. Two are marked **NON-NEGOTIABLE** in the strongest terms:
**Principle I: Safety-First Operations** — Every device interaction begins with observation. No destructive commands without explicit human approval. Device state is never assumed or guessed.
**Principle XI: Full-Stack Artifact Coherence** — When adding ANY new capability, ALL of the following must be updated before the feature is considered complete:
– `README.md`
– `scripts/install.sh`
– `ui/netclaw-visual/` (Three.js HUD)
– `SOUL.md` (agent identity and skills)
– `workspace/skills/<name>/SKILL.md`
– `.env.example`
– `TOOLS.md`
– `config/openclaw.json`
A pull request that adds a capability without updating all required artifacts **must not be merged**.
The remaining 14 principles cover everything from ITSM-gated changes (ServiceNow CR required for production) to immutable GAIT audit trails, MCP-native integration, multi-vendor neutrality, credential safety, and the SDD workflow itself.
### The SDD Workflow
Every new capability now follows a rigorous pipeline:
1. **Specify** — Define the feature with user stories, acceptance scenarios (Given/When/Then), functional requirements, and measurable success criteria
2. **Clarify** — Identify ambiguities and resolve them with structured questions
3. **Plan** — Research technical approaches, define data models, design MCP tool contracts
4. **Tasks** — Generate dependency-ordered, parallelizable task lists
5. **Implement** — Execute tasks in phase order with checkpoints
6. **Coherence** — Run the artifact coherence checklist
7. **Review** — PR review against the constitution
This isn’t bureaucracy for the sake of it. When you’re building an agent that can peer BGP, push configs to production routers, and create ServiceNow tickets, you need guardrails that are as rigorous as the CCIE lab itself.
—
## Part 2: The Five New Capabilities
We didn’t just adopt SDD as a theoretical exercise. We immediately put it to work by identifying the five highest-impact capabilities missing from NetClaw and building all of them in a single development session. Here’s what landed.
### 1. SuzieQ MCP Server: Network Observability with Time Travel
**What it is:** A new MCP server that wraps the [SuzieQ](https://www.stardustsystems.net/suzieq/) network observability platform, giving NetClaw the ability to query network state across every device in your environment — including what the network looked like at any point in the past.
**Why it matters:** Before SuzieQ, NetClaw could query individual devices via pyATS. That’s powerful, but it’s like reading one page of a book at a time. SuzieQ gives NetClaw the entire library — every device, every protocol, every table, with a time machine built in.
**The 5 tools:**
| Tool | What It Does |
|——|————-|
| `suzieq_show` | Query any network table (BGP, OSPF, routes, interfaces, MAC, ARP, LLDP, VLANs, MLAG, EVPN, and more) across all devices. Supports time-travel: “show me BGP peers as they were on March 20th at 9am.” Supports filtering by device, namespace, hostname, columns, and custom expressions. |
| `suzieq_summarize` | Aggregated views: total routes per device, interface state distribution, BGP peer counts by state. The 30,000-foot view of your network health without scrolling through thousands of rows. |
| `suzieq_assert` | Validation engine: “Assert all BGP peers are established.” Returns pass/fail per device with failure details. This transforms passive monitoring into active compliance checking. |
| `suzieq_unique` | Distribution analysis: “What are the unique VRFs in use?” “How many interfaces are in each state?” Quick categorical insight across the fleet. |
| `suzieq_path` | Forwarding path trace: “Trace the path from 10.0.1.1 to 10.0.2.1.” Returns hop-by-hop forwarding decisions with ingress/egress interfaces. |
**The time-travel capability is the real differentiator.** When an incident happens at 2am and you’re investigating at 9am, you can ask NetClaw “show me the OSPF neighbors at 2:15am” and see exactly what the network looked like during the event. No more guessing, no more “I think it was probably…”
**Environment variables:**
“`bash
SUZIEQ_API_URL=http://suzieq-host:8000
SUZIEQ_API_KEY=your_suzieq_api_key
SUZIEQ_VERIFY_SSL=true
SUZIEQ_TIMEOUT=30
“`
—
### 2. Batfish MCP Server: The First-Ever Batfish MCP
**What it is:** The world’s first MCP server for [Batfish](https://www.batfish.org/), the open-source network configuration analysis tool from Intentionet. This gives NetClaw the ability to validate network configurations *before they touch a live device*.
**Why it matters:** This is arguably the most important safety feature we’ve ever added to NetClaw. The constitution says “safety first” and “verify after every change.” Batfish lets us verify *before* the change. Upload your proposed config, ask Batfish to analyze it, and know whether it will break reachability, violate compliance policies, or create unintended ACL consequences — all without touching a single router.
**The 8 tools:**
| Tool | What It Does |
|——|————-|
| `batfish_upload_snapshot` | Upload device configurations to Batfish for analysis. Accepts inline config dicts or directory paths. Auto-discovers devices and vendors. |
| `batfish_validate_config` | Parse and validate configs with per-device pass/fail status, vendor detection, and detailed parse warnings. Catches syntax errors, unknown commands, and structural issues before they cause outages. |
| `batfish_test_reachability` | The killer feature: “Can 10.1.1.1 reach 10.2.2.2 on port 443?” Returns PERMITTED, DENIED, or NO_ROUTE with the complete hop-by-hop forwarding path and every ACL decision along the way. |
| `batfish_trace_acl` | Deep packet trace through a specific ACL or firewall rule set. Returns the matching rule number, action (permit/deny), and step-by-step trace events. |
| `batfish_diff_configs` | Compare two configuration snapshots: route additions/removals, next-hop changes, and — critically — differential reachability. “Traffic from A to B was PERMITTED in the old config but is DENIED in the new one.” |
| `batfish_check_compliance` | Validate configs against 6 built-in policy types: interface descriptions required, no default routes, NTP configured, no shutdown interfaces, BGP sessions established, OSPF adjacencies up. |
| `batfish_list_snapshots` | List all analysis snapshots in a network. |
| `batfish_delete_snapshot` | Clean up old snapshots. |
**The compound effect is enormous.** Imagine this workflow:
1. NetClaw receives a change request via ServiceNow
2. It pulls the current config via pyATS (baseline)
3. It generates the proposed config change
4. It uploads both to Batfish and runs `batfish_diff_configs`
5. It runs `batfish_test_reachability` for critical traffic flows
6. It runs `batfish_check_compliance` against organizational policies
7. Only if ALL checks pass does it proceed to apply the change
8. After applying, it verifies via pyATS and SuzieQ
That’s a fully autonomous, safety-gated change management pipeline. No other network automation agent can do this.
**Environment variables:**
“`bash
BATFISH_HOST=localhost
BATFISH_PORT=9997
BATFISH_NETWORK=netclaw
“`
**Prerequisite:** Batfish runs as a Docker container. The install script auto-pulls it:
“`bash
docker pull batfish/batfish
docker run -d -p 9997:9997 batfish/batfish
“`
—
### 3. gNMI Streaming Telemetry MCP Server: The Network Talks to NetClaw
**What it is:** A new MCP server implementing gNMI (gRPC Network Management Interface) for model-driven streaming telemetry. This is the shift from NetClaw *asking* devices for their state to devices *telling* NetClaw their state in real time.
**Why it matters:** Until now, NetClaw’s monitoring was poll-based. Run a `show` command, parse the output, repeat. That works, but it’s like checking your email every 5 minutes instead of getting push notifications. gNMI streaming telemetry is the push notification. Interface goes down? NetClaw knows in under 2 seconds, not whenever it next polls. BGP peer flaps? The telemetry subscription fires immediately.
This is the single biggest modernization of NetClaw’s monitoring capability.
**The 10 tools:**
| Tool | What It Does |
|——|————-|
| `gnmi_get` | Retrieve device state or config using YANG model paths. Structured, typed, vendor-normalized data instead of parsing CLI text output. |
| `gnmi_set` | Apply configuration changes via gNMI Set. **ITSM-gated**: requires a valid ServiceNow Change Request number (CHG format). Follows read-before-write with automatic verify-after-write. |
| `gnmi_subscribe` | Create real-time telemetry subscriptions. SAMPLE mode polls at intervals (configurable, minimum 1 second). ON_CHANGE mode fires only when state changes. Up to 50 concurrent subscriptions. |
| `gnmi_unsubscribe` | Cancel a telemetry subscription and clean up resources. |
| `gnmi_get_subscriptions` | List all active subscriptions with status, target device, YANG paths, creation time, and last update time. |
| `gnmi_get_subscription_updates` | Retrieve the latest N updates from a subscription. Ring buffer stores 1,000 most recent updates per subscription. |
| `gnmi_capabilities` | Discover what YANG models a device supports. Classifies models as OpenConfig vs. vendor-native with counts and version info. |
| `gnmi_browse_yang_paths` | Explore available YANG paths on a device with configurable tree depth. Like `ls` for your device’s data model. |
| `gnmi_compare_with_cli` | Compare gNMI-retrieved state with CLI-retrieved state (via pyATS). Field-level matching with timing-sensitive variance detection. Validates that the gNMI data matches reality. |
| `gnmi_list_targets` | List all configured gNMI targets with real-time connectivity status. |
**Four vendor dialects built in:**
| Vendor | Default Port | Encoding | ON_CHANGE |
|——–|————-|———-|———–|
| Cisco IOS-XR | 57400 | JSON_IETF | Yes |
| Juniper JunOS | 32767 | JSON_IETF | Yes |
| Arista EOS | 6030 | JSON | Yes |
| Nokia SR OS | 57400 | JSON_IETF | Yes |
**ITSM Gating for gNMI Set:**
The `gnmi_set` tool is the only write operation in the entire gNMI MCP server, and it’s locked behind a ServiceNow gate:
1. Validates the CR number matches format `CHG` followed by digits
2. In production mode, queries ServiceNow to verify the CR is in “Implement” state
3. Captures a gNMI Get baseline before any changes
4. Applies the Set operation
5. Runs a gNMI Get to verify the change took effect
6. Logs everything to GAIT
Lab mode (`NETCLAW_LAB_MODE=true`) bypasses ServiceNow but still requires a CR number for audit trail purposes.
**Environment variables:**
“`bash
GNMI_TARGETS='[{“name”:”router1″,”host”:”10.1.1.1″,”port”:57400,”username”:”admin”,”password”:”changeme”,”vendor”:”cisco-iosxr”}]’
GNMI_TLS_CA_CERT=/path/to/ca.pem
GNMI_TLS_CLIENT_CERT=/path/to/client.pem # Optional, for mTLS
GNMI_TLS_CLIENT_KEY=/path/to/client.key # Optional, for mTLS
GNMI_TLS_SKIP_VERIFY=false # Lab only
GNMI_DEFAULT_PORT=6030
GNMI_MAX_RESPONSE_SIZE=1048576 # 1MB truncation threshold
GNMI_MAX_SUBSCRIPTIONS=50
“`
—
### 4. Azure Networking MCP Server: Multi-Cloud Complete
**What it is:** A comprehensive MCP server for Microsoft Azure networking services. NetClaw already had AWS (5 skills, 27 tools) and GCP (3 skills, 28 tools). Azure was the missing piece. Now the multi-cloud networking story is complete.
**Why it matters:** Enterprise networks don’t live in one cloud. They span AWS VPCs, GCP VPCs, Azure VNets, and on-premise data centers connected by ExpressRoute, Direct Connect, and Cloud Interconnect. NetClaw can now observe, audit, and troubleshoot the entire picture.
**The 19 tools, organized by Azure service:**
**Virtual Networking:**
– `azure_list_subscriptions` — List all accessible Azure subscriptions
– `azure_list_vnets` — List Virtual Networks
– `azure_get_vnet_details` — Detailed VNet config (subnets, address space, DNS, flow logs)
– `azure_get_vnet_peerings` — Peering relationships and status
**Network Security:**
– `azure_list_nsgs` — List Network Security Groups
– `azure_get_nsg_rules` — Inbound/outbound rules with source/dest/port details
– `azure_get_effective_security_rules` — Computed effective rules after all NSG applications
– `azure_audit_nsg_compliance` — CIS Azure Foundations Benchmark audit
**Hybrid Connectivity:**
– `azure_get_expressroute_status` — Circuit status, peering details, QoS metrics
– `azure_get_expressroute_routes` — Advertised and learned route tables
– `azure_get_vpn_gateway_status` — VPN gateway health, connection status, routing info
**Firewalls & Security Appliances:**
– `azure_list_firewalls` — List Azure Firewalls
– `azure_get_firewall_policy` — Firewall policy rules and rule collections
**Load Balancing:**
– `azure_list_load_balancers` — List Load Balancers
– `azure_get_lb_backend_health` — Backend pool health probe results
– `azure_get_app_gateway_health` — Application Gateway and Front Door backend health
**Infrastructure:**
– `azure_get_route_tables` — User-defined routes
– `azure_get_network_watcher_status` — Network Watcher capabilities
– `azure_get_private_endpoints` — Private Link connections
– `azure_get_dns_zones` — DNS zones and records
**CIS Azure Foundations Benchmark compliance is built in:**
| Rule | Severity | What It Checks |
|——|———-|—————|
| 6.1 | Critical | RDP (port 3389) exposed to internet — recommends Azure Bastion |
| 6.2 | Critical | SSH (port 22) exposed to internet |
| 6.3 | High | Unrestricted UDP from internet (DDoS amplification risk) |
| 6.4 | Medium | NSG flow logs enabled with 90-day retention |
**Environment variables:**
“`bash
AZURE_TENANT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AZURE_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AZURE_CLIENT_SECRET=your-client-secret-value
AZURE_SUBSCRIPTION_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
“`
—
### 5. Canvas/A2UI Network Visualization: See Your Network Inline
**What it is:** A new skill that leverages OpenClaw’s Canvas and A2UI (Agent-to-UI) framework to render rich network visualizations directly in the chat interface. No separate browser tab, no Three.js HUD required (though that still works too). Seven visualization types, all rendered inline.
**Why it matters:** NetClaw has always been able to tell you about your network. Now it can show you. When you ask “show me the network topology,” you don’t get a wall of text — you get an interactive SVG map with devices color-coded by health status. When you ask about a change request, you see a visual timeline tracking through Assess, Authorize, Implement, and Review stages.
**The 7 visualization types:**
| Type | What You See |
|——|————-|
| **Topology Map** | Interactive SVG network diagram generated from CDP/LLDP discovery data. Devices color-coded by health (green/amber/red). Links show interface names. Auto-clusters by site when topology exceeds 200 nodes. |
| **Dashboard Panel** | Real-time gauges and counters: CPU utilization, memory usage, interface status, BGP peer counts, OSPF adjacency state. Supports gauge, counter, status-list, bar chart, and sparkline widgets. |
| **Alert Card** | Severity-colored alert cards from Grafana, Prometheus, and device syslog. Critical (red), warning (amber), info (blue). Filterable by severity, device, and time range. Shows “all clear” when no active alerts. |
| **Change Timeline** | Visual progress tracker for ServiceNow Change Requests. Horizontal stage progression: New, Assess, Authorize, Scheduled, Implement, Review, Closed. Highlights current stage. Shows rejection and rollback indicators. |
| **Diff View** | Side-by-side config diffs with syntax coloring: green for additions, red for removals, gray for context. Works for configurations, routing tables, and ACL rules. |
| **Path Trace** | Hop-by-hop forwarding path diagram with ingress/egress interfaces at each node. Highlights ECMP paths and black holes. Data sourced from pyATS and SuzieQ. |
| **Health Scorecard** | Weighted health score per device or per site. CPU (20%), memory (20%), interfaces (25%), BGP (20%), OSPF (15%). Drill-down from site to device to individual metrics. Missing data redistributes weight rather than failing. |
**All visualizations use WCAG 2.1 AA accessible colors** and degrade gracefully when data sources are unavailable (partial render with warnings, not blank screens).
**No new environment variables needed** — Canvas visualizations pull data from existing MCP servers (pyATS, Grafana, Prometheus, ServiceNow, SuzieQ).
—
## Part 3: The Compound Effect — Why These Five Together Are More Than the Sum
Each of these capabilities is powerful on its own. But the real magic is what happens when NetClaw combines them.
### Streaming Telemetry + SuzieQ: Real-Time Meets Historical
gNMI subscriptions fire when state changes. SuzieQ records everything over time. Together, NetClaw can:
– Detect a BGP peer flap via gNMI ON_CHANGE subscription (real-time)
– Query SuzieQ for “how many times has this peer flapped in the last 7 days?” (historical)
– Cross-reference with SuzieQ’s time-travel to see what else changed during each flap (correlation)
– Display the analysis as a Canvas dashboard panel with a sparkline of flap frequency (visualization)
That’s four new capabilities working together in a single troubleshooting workflow.
### Batfish + gNMI Set: Pre-Validated, ITSM-Gated Changes
The most powerful safety pipeline in network automation:
1. **Proposed change** arrives via ServiceNow
2. **Batfish validates** the proposed config (reachability, compliance, ACL impact)
3. **gNMI Set** applies the change (only if Batfish passes AND ServiceNow CR is approved)
4. **gNMI Get** verifies the change took effect
5. **SuzieQ assert** confirms the network is in the expected state
6. **Canvas timeline** shows the CR progressing through each stage
If any step fails, automatic rollback. If rollback fails, halt and alert. Every step GAIT-logged.
### Azure + AWS + GCP: True Multi-Cloud Visibility
NetClaw can now answer questions that span clouds:
– “Compare the security posture of our AWS VPCs, GCP VPCs, and Azure VNets”
– “Show me all internet-facing firewall rules across all three clouds”
– “Is our ExpressRoute circuit healthy? What about our Direct Connect and Cloud Interconnect?”
– “Run CIS compliance across Azure NSGs, AWS Security Groups, and GCP Firewall Rules”
And render the results as Canvas health scorecards with per-cloud drill-down.
### Canvas + Everything: The Visual Agent
Every MCP tool NetClaw has — all 46 integrations — can now feed data into Canvas visualizations:
– pyATS health checks become topology maps and dashboards
– Grafana alerts become alert cards
– ServiceNow CRs become change timelines
– SuzieQ path traces become forwarding diagrams
– Config diffs become side-by-side diff views
The agent doesn’t just tell you what’s happening. It shows you.
—
## Part 4: Getting These Features
### New Installation (install.sh)
If you’re installing NetClaw fresh, `scripts/install.sh` now includes all five new capabilities automatically. The install script has been updated from 47 steps to 53 steps:
– **SuzieQ MCP** — pip install from `mcp-servers/suzieq-mcp/requirements.txt`
– **Batfish MCP** — pip install from `mcp-servers/batfish-mcp/requirements.txt` + `docker pull batfish/batfish`
– **gNMI MCP** — pip install fastmcp, grpcio, pygnmi, protobuf, cryptography, pydantic
– **Azure Network MCP** — pip install from `mcp-servers/azure-network-mcp/requirements.txt` (azure-identity, azure-mgmt-network, azure-mgmt-resource, azure-mgmt-dns, azure-mgmt-frontdoor)
– **Canvas/A2UI** — No additional dependencies (deployed as a skill via bulk copy)
### Existing NetClaw Installation (git pull)
If you already have NetClaw running, here’s how to add all five capabilities:
**Step 1: Pull the latest code**
“`bash
cd netclaw
git pull origin main
“`
**Step 2: Install SuzieQ MCP dependencies**
“`bash
pip3 install -r mcp-servers/suzieq-mcp/requirements.txt
“`
**Step 3: Install Batfish MCP dependencies**
“`bash
pip3 install -r mcp-servers/batfish-mcp/requirements.txt
docker pull batfish/batfish
docker run -d -p 9997:9997 -p 9996:9996 batfish/batfish
“`
**Step 4: Install gNMI MCP dependencies**
“`bash
pip3 install -r mcp-servers/gnmi-mcp/requirements.txt
“`
**Step 5: Install Azure Network MCP dependencies**
“`bash
pip3 install -r mcp-servers/azure-network-mcp/requirements.txt
“`
**Step 6: Update your .env file**
Add the following to your `.env` file (copy from `.env.example` for reference):
“`bash
# ── SuzieQ Network Observability ──
SUZIEQ_API_URL=http://your-suzieq-host:8000
SUZIEQ_API_KEY=your_suzieq_api_key
SUZIEQ_VERIFY_SSL=true
SUZIEQ_TIMEOUT=30
# ── Batfish Configuration Analysis ──
BATFISH_HOST=localhost
BATFISH_PORT=9997
BATFISH_NETWORK=netclaw
# ── gNMI Streaming Telemetry ──
GNMI_TARGETS='[{“name”:”router1″,”host”:”10.1.1.1″,”port”:57400,”username”:”admin”,”password”:”changeme”,”vendor”:”cisco-iosxr”}]’
GNMI_TLS_CA_CERT=/path/to/ca.pem
GNMI_TLS_CLIENT_CERT=/path/to/client.pem
GNMI_TLS_CLIENT_KEY=/path/to/client.key
GNMI_TLS_SKIP_VERIFY=false
GNMI_DEFAULT_PORT=6030
GNMI_MAX_RESPONSE_SIZE=1048576
GNMI_MAX_SUBSCRIPTIONS=50
# ── Azure Networking ──
AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret
AZURE_SUBSCRIPTION_ID=your-subscription-id
“`
Canvas/A2UI requires no additional environment variables — it uses existing MCP server connections.
**Step 7: Restart OpenClaw gateway**
“`bash
openclaw gateway
“`
The new MCP servers are already registered in `config/openclaw.json` and will be discovered automatically on restart.
—
## The Numbers
| Metric | Before | After |
|——–|——–|——-|
| Skills | 97 | 101 |
| MCP Integrations | 43 | 46 |
| MCP Tools | ~400 | ~442 |
| Cloud Providers | 2 (AWS, GCP) | 3 (AWS, GCP, Azure) |
| Telemetry Model | Poll-based (CLI) | Poll + Stream (CLI + gNMI) |
| Pre-Change Validation | Manual | Automated (Batfish) |
| Network Observability | Per-device | Fleet-wide with time travel (SuzieQ) |
| Visualization | Separate 3D HUD | Inline Canvas + 3D HUD |
| CIS Compliance | Cisco only | Cisco + Azure |
| Development Process | Ad-hoc | Spec-Driven (16 principles) |
**160 new files. 23,028 lines of new code. 225 SDD tasks executed. One session.**
NetClaw isn’t just getting more capable. It’s getting more disciplined. The constitution and SDD workflow ensure that every future capability — whether it’s SNMP monitoring, Terraform integration, or RPKI validation — will go through the same rigorous specify-plan-task-implement pipeline, with full artifact coherence guaranteed.
The network deserves an engineer that never cuts corners. That’s NetClaw.
