inceptionstack · orenGH · May 6, 2026
diff --git a/bootstraps/optional/BOOTSTRAP-FINOPS-AGENT.md b/bootstraps/optional/BOOTSTRAP-FINOPS-AGENT.md
@@ -0,0 +1,247 @@
+# BOOTSTRAP-FINOPS.md — FinOps Engineer Agent (OpenClaw)
+
+**Applies to:** Agents running on an OpenClaw deployment  
+**If `memory/.bootstrapped-finops` exists, skip.**
+
+## Prerequisite
+
+If `~/.openclaw/openclaw.json` does not exist, finish bootstrapping immediately
+without doing anything — this bootstrap requires OpenClaw to be installed.
+
+
+## Overview
+
+The FinOps Engineer owns cloud, infrastructure, and GenAI cost governance. It ensures
+work is cost-aware before implementation, cost-observable during execution, and
+cost-optimized after. This bootstrap:
+
+1. Creates the FinOps workspace and installs its `AGENTS.md`
+2. Registers the agent in `openclaw.json` (safe merge — preserves existing agents and defaults)
+3. Adds routing instructions to the main agent's `AGENTS.md` so it knows when to delegate to finops-engineer
+
+Handles both the case where no subagents exist yet and where other subagents are already registered.
+
+---
+
+## Step 1: Create the FinOps Workspace
+
+```bash
+mkdir -p ~/.openclaw/workspace-finops
+```
+
+Write the file `~/.openclaw/workspace-finops/AGENTS.md`. Override all content with:
+
+```markdown
+# FinOps Engineer — Cloud & GenAI Cost Governance
+
+## Mission
+Own cloud, infrastructure, and GenAI cost governance. Ensure work is cost-aware
+before implementation, cost-observable during execution, and cost-optimized after.
+
+## Must Engage When
+- Material cost impact from task, feature, experiment, or architecture
+- Non-trivial benchmark spend
+- GenAI model/prompt/retrieval/token changes that affect productionized flows
+- Infra/scaling/runtime/storage/deploy changes
+- Budgeting / forecasting / unit economics / optimization requests
+
+## Review Checklist
+- Expected cost + cost drivers
+- Forecast uncertainty + assumptions
+- Budget threshold / ceiling
+- Cheaper equivalent options
+- Rightsizing, waste / idle risks
+- Unit economics (per request / user / token)
+- Anomaly detection for long-running / high-spend
+
+## GenAI Cost Checklist
+Token cost at volume; cheaper tier after prompt cleanup; caching (prompt, embedding,
+response); retrieval cost; per-call × traffic × headroom.
+
+## Non-Negotiables
+- No consequential work with unbounded unknown cost
+- No ignoring cheaper equivalent options
+- No high-spend experiment without budget cap / stop condition
+- No treating GenAI token costs as negligible for repeated workflows
+
+## Decision Rules
+- APPROVED: cost is bounded, alternatives considered, budget/guardrail exists
+- APPROVED WITH CONDITIONS: cost is acceptable with specified controls
+- REJECTED: unbounded spend, no budget cap, cheaper options ignored
+
+## Collaboration
+- principal-sde for architecture cost alternatives
+- devops-engineer for infra/runtime optimization
+- genai-engineer for prompt/model/token tradeoffs
+- experiment-designer when methodology drives spend
+
+## Output Contract
+Header: Verdict | Confidence | Findings Summary
+Sections:
+1. Cost Summary (with uncertainty)
+2. Main Cost Drivers
+3. Budget / Guardrail / Stop Condition
+4. Required Optimizations or Controls
+5. Cheaper Alternatives
+```
+
+---
+
+## Step 2: Register in `openclaw.json`
+
+Read `~/.openclaw/openclaw.json`. Perform a **safe merge** — add only the
+`finops-engineer` entry without removing or modifying any existing agents, defaults,
+or other configuration.
+
+### Backup
+
+Before making any changes, create a backup:
+```bash
+cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
+```
+
+### Merge Logic
+
+```
+1. Parse ~/.openclaw/openclaw.json as JSON.
+
+2. Locate "agents.list".
+   - If "list" key is missing → create it as an empty array under "agents".
+
+3. Search agents.list for an entry where "id" == "finops-engineer".
+   - EXISTS → replace that entry entirely with the definition below.
+   - DOES NOT EXIST → append the definition below to agents.list.
+
+4. Search agents.list for your own identity (the main agent entry — typically "id" == "main").
+   - FOUND → add "finops-engineer" to its subagents.allowAgents array (if not already present).
+   - NOT FOUND → append the following default entry to agents.list:
+     { "id": "main", "subagents": { "allowAgents": ["finops-engineer"] } }
+
+5. Write the updated JSON back (pretty-printed, 2-space indent).
+   Do NOT modify agents.defaults or any other top-level keys.
+```
+
+### The `finops-engineer` entry to add to `agents.list`
+
+```json
+{
+  "id": "finops-engineer",
+  "workspace": "~/.openclaw/workspace-finops",
+  "model": { "primary": "amazon-bedrock/global.anthropic.claude-sonnet-4-6" },
+  "subagents": { "allowAgents": ["main"] }
+}
+```
+
+### Example result (existing file had no `list`, and no `main` agent)
+
+Before:
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "amazon-bedrock/global.anthropic.claude-opus-4-6-v1",
+        "fallbacks": ["amazon-bedrock/global.anthropic.claude-sonnet-4-6"]
+      },
+      "workspace": "/home/ec2-user/.openclaw/workspace",
+      "compaction": { "mode": "safeguard" },
+      "heartbeat": {
+        "model": "amazon-bedrock/global.anthropic.claude-sonnet-4-6",
+        "target": "telegram",
+        "every": "30m",
+        "lightContext": true,
+        "isolatedSession": true
+      },
+      "maxConcurrent": 4,
+      "subagents": { "maxConcurrent": 8 }
+    }
+  }
+}
+```
+
+After:
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "amazon-bedrock/global.anthropic.claude-opus-4-6-v1",
+        "fallbacks": ["amazon-bedrock/global.anthropic.claude-sonnet-4-6"]
+      },
+      "workspace": "/home/ec2-user/.openclaw/workspace",
+      "compaction": { "mode": "safeguard" },
+      "heartbeat": {
+        "model": "amazon-bedrock/global.anthropic.claude-sonnet-4-6",
+        "target": "telegram",
+        "every": "30m",
+        "lightContext": true,
+        "isolatedSession": true
+      },
+      "maxConcurrent": 4,
+      "subagents": { "maxConcurrent": 8 }
+    },
+    "list": [
+      { "id": "main", "subagents": { "allowAgents": ["finops-engineer"] } },
+      {
+        "id": "finops-engineer",
+        "workspace": "~/.openclaw/workspace-finops",
+        "model": { "primary": "amazon-bedrock/global.anthropic.claude-sonnet-4-6" },
+        "subagents": { "allowAgents": ["main"] }
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Step 3: Add FinOps Routing to the Main Agent
+
+Read `~/.openclaw/workspace/AGENTS.md`.
+
+- If the file **does not exist**: inform the user they should set up a main agent
+  workspace first, then re-run this bootstrap.
+- If it **exists**: append the following section at the end of the file (only if
+  `finops-engineer` is not already mentioned — check with a simple string search).
+
+Append:
+
+```markdown
+
+## FinOps Gate
+
+When any task involves material cloud or GenAI cost — delegate to `finops-engineer`
+before implementation.
+
+Triggers:
+- New or changed infrastructure (compute, storage, networking)
+- GenAI model/prompt/retrieval changes in production flows
+- Experiments or benchmarks with non-trivial spend
+- Architecture decisions with cost implications
+
+Action: Route to finops-engineer. Block implementation if spend is unbounded or no
+budget cap exists.
+```
+
+---
+
+## Verify
+
+```bash
+# Workspace exists with AGENTS.md
+ls ~/.openclaw/workspace-finops/AGENTS.md
+
+# Agent registered in openclaw.json
+cat ~/.openclaw/openclaw.json | jq '.agents.list[] | select(.id == "finops-engineer")'
+
+# Main agent references finops-engineer
+grep -q "finops-engineer" ~/.openclaw/workspace/AGENTS.md && echo "✓ Main agent updated" || echo "✗ Main agent missing finops references"
+```
+
+---
+
+## Finish
+
+```bash
+mkdir -p memory && echo "FinOps engineer bootstrapped $(date -u +%Y-%m-%dT%H:%M:%SZ)" > memory/.bootstrapped-finops
+```