@bookedsolid/reagent 0.2.0 → 0.4.0

package/README.md

@@ -4,19 +4,21 @@ Zero-trust MCP gateway and agentic infrastructure for AI-assisted development.
 
 Reagent is two things:
 
-1. **MCP Gateway** (`reagent serve`) — a proxy server that sits between your AI assistant (Claude Code, Cursor, etc.) and downstream MCP tool servers. Every tool call flows through a zero-trust middleware chain: policy enforcement, tier classification, secret redaction, and hash-chained audit logging.
+1. **MCP Gateway** (`reagent serve`) -- a proxy server that sits between your AI assistant (Claude Code, Cursor, etc.) and downstream MCP tool servers. Every tool call flows through a zero-trust middleware chain: policy enforcement, tier classification, blocked path enforcement, secret redaction, and hash-chained audit logging.
 
-2. **Config Scaffolder** (`reagent init`) — installs safety hooks, behavioral policies, and developer tooling into any project.
+2. **Config Scaffolder** (`reagent init`) -- installs safety hooks, behavioral policies, and developer tooling into any project.
 
 ## Why Reagent?
 
 AI coding assistants are powerful but unconstrained. Reagent adds the missing governance layer:
 
-- **Policy enforcement** — graduated autonomy levels (L0 read-only → L3 full access) control which tiers of tools an agent can invoke
-- **Kill switch** — `reagent freeze` immediately blocks all tool calls across every connected MCP server
-- **Secret redaction** — tool outputs are scanned for AWS keys, GitHub tokens, API keys, PEM private keys, Discord tokens, and more — redacted before they reach the AI
-- **Audit trail** — every tool invocation is logged as hash-chained JSONL, providing tamper-evident compliance records
-- **Tool blocking** — individual tools can be permanently blocked regardless of autonomy level
+- **Policy enforcement** -- graduated autonomy levels (L0 read-only through L3 full access) control which tiers of tools an agent can invoke
+- **Kill switch** -- `reagent freeze` immediately blocks all tool calls across every connected MCP server
+- **Blocked path enforcement** -- tool arguments referencing protected paths (including `.reagent/` itself) are denied before execution
+- **Secret redaction** -- tool arguments and outputs are scanned for AWS keys, GitHub tokens, API keys, PEM private keys, Discord tokens, and more -- redacted before they reach the AI or the downstream tool
+- **Audit trail** -- every tool invocation is logged as hash-chained JSONL with serialized writes for chain integrity
+- **Tool blocking** -- individual tools can be permanently blocked regardless of autonomy level
+- **Tier downgrade protection** -- `tool_overrides` cannot lower a tool's tier below its static or convention-based classification
 
 ## Quick Start
 
@@ -68,37 +70,51 @@ npx @bookedsolid/reagent init --dry-run
 | `reagent serve`                 | Start the MCP gateway server (stdio transport)    |
 | `reagent init`                  | Install reagent config into the current directory |
 | `reagent check`                 | Verify what reagent components are installed      |
-| `reagent freeze --reason "..."` | Create `.reagent/HALT` — suspends all tool calls  |
-| `reagent unfreeze`              | Remove `.reagent/HALT` — resumes tool calls       |
+| `reagent freeze --reason "..."` | Create `.reagent/HALT` -- suspends all tool calls |
+| `reagent unfreeze`              | Remove `.reagent/HALT` -- resumes tool calls      |
 | `reagent help`                  | Show usage help                                   |
 
+### `reagent init` Options
+
+| Flag               | Description                                    | Default             |
+| ------------------ | ---------------------------------------------- | ------------------- |
+| `--profile <name>` | Profile to install                             | `client-engagement` |
+| `--dry-run`        | Preview what would be installed without writes | --                  |
+
+### `reagent freeze` Options
+
+| Flag              | Description                        | Default         |
+| ----------------- | ---------------------------------- | --------------- |
+| `--reason <text>` | Reason for freeze (stored in HALT) | `Manual freeze` |
+
 ## MCP Gateway
 
 ### How It Works
 
 ```
 AI Assistant (Claude Code, Cursor, etc.)
-    │
-    │  stdio (MCP protocol)
-    ▼
-┌─────────────────────────────┐
-│       Reagent Gateway       │
-│                             │
-│  ┌───────────────────────┐  │
-│  │   Middleware Chain     │  │
-│  │                       │  │
-│  │  1. Audit (outermost) │  │
-│  │  2. Session context   │  │
-│  │  3. Kill switch       │  │
-│  │  4. Tier classify     │  │
-│  │  5. Policy enforce    │  │
-│  │  6. Secret redaction  │  │
-│  │  7. [Execute]         │  │
-│  └───────────────────────┘  │
-│                             │
-└──────────┬──────────────────┘
-           │  stdio (MCP protocol)
-           ▼
+    |
+    |  stdio (MCP protocol)
+    v
++-----------------------------+
+|       Reagent Gateway       |
+|                             |
+|  +------------------------+ |
+|  |   Middleware Chain      | |
+|  |                        | |
+|  |  1. Audit (outermost)  | |
+|  |  2. Session context    | |
+|  |  3. Kill switch        | |
+|  |  4. Tier classify      | |
+|  |  5. Policy enforce     | |
+|  |  6. Blocked paths      | |
+|  |  7. Secret redaction   | |
+|  |  8. [Execute]          | |
+|  +------------------------+ |
+|                             |
++----------+------------------+
+           |  stdio (MCP protocol)
+           v
     Downstream MCP Servers
     (discord-ops, filesystem, etc.)
 ```
@@ -136,9 +152,9 @@ servers:
         blocked: true
 ```
 
-**Environment variable resolution:** Use `${VAR_NAME}` syntax in env values — Reagent resolves them from `process.env` at startup.
+**Environment variable resolution:** Use `${VAR_NAME}` syntax in env values -- Reagent resolves them from `process.env` at startup. Missing env vars produce a warning and resolve to empty string.
 
-**Tool overrides:** Each downstream tool can be assigned a tier (`read`, `write`, `destructive`) and optionally blocked entirely.
+**Tool overrides:** Each downstream tool can be assigned a tier (`read`, `write`, `destructive`) and optionally blocked entirely. Overrides cannot lower a tool's tier below its static or convention-based classification (the override is ignored with a warning if attempted).
 
 ### Tool Namespacing
 
@@ -177,7 +193,7 @@ Every tool call passes through the middleware chain in onion (Koa-style) order.
 
 ### 1. Audit (outermost)
 
-Records every invocation — including denials — as a hash-chained JSONL entry. Written to `.reagent/audit/YYYY-MM-DD.jsonl`. Each record contains:
+Records every invocation -- including denials and errors -- as a hash-chained JSONL entry. Written to `.reagent/audit/YYYY-MM-DD.jsonl`. Each record contains:
 
 ```json
 {
@@ -194,18 +210,18 @@ Records every invocation — including denials — as a hash-chained JSONL entry
 }
 ```
 
-The `prev_hash` field chains records together — tamper with one record and every subsequent hash becomes invalid.
+The `prev_hash` field chains records together -- tamper with one record and every subsequent hash becomes invalid. Audit writes are serialized via a queue to maintain hash chain linearity under concurrent invocations. The `autonomy_level` is sourced from the loaded policy object, not from mutable invocation context.
 
 ### 2. Session Context
 
-Attaches a unique session ID (UUID) to every invocation. Each gateway instance generates one session ID at startup.
+Attaches a unique session ID (UUID via `crypto.randomUUID()`) to every invocation. Each gateway instance generates one session ID at startup.
 
 ### 3. Kill Switch
 
-Checks for `.reagent/HALT` file. If present, the invocation is immediately denied. The HALT file contents become the denial reason.
+Checks for `.reagent/HALT` file. If present, the invocation is immediately denied. The HALT file contents become the denial reason. Reads are capped at 1024 bytes. The file is validated as a regular file (symlinks outside `.reagent/` are rejected).
 
 ```bash
-# Emergency stop — all tool calls blocked immediately
+# Emergency stop -- all tool calls blocked immediately
 reagent freeze --reason "security incident at 2026-04-09T12:00:00Z"
 
 # Resume
@@ -214,7 +230,23 @@ reagent unfreeze
 
 ### 4. Tier Classification
 
-Classifies the tool into one of three tiers:
+Classifies the tool into one of three tiers using a layered approach:
+
+| Source           | Priority | Description                                |
+| ---------------- | -------- | ------------------------------------------ |
+| Static map       | 1st      | Known tools with explicit tier assignments |
+| Convention-based | 2nd      | Prefix patterns for unknown tools          |
+| Default          | 3rd      | Falls back to `write`                      |
+
+**Convention-based classification** allows non-Discord downstream servers to get sensible defaults:
+
+| Prefix pattern                                                                                               | Tier          |
+| ------------------------------------------------------------------------------------------------------------ | ------------- |
+| `get_`, `list_`, `search_`, `query_`, `read_`, `fetch_`, `check_`, `health_`, `describe_`, `show_`, `count_` | `read`        |
+| `delete_`, `drop_`, `purge_`, `remove_`, `destroy_`, `ban_`, `kick_`, `revoke_`, `truncate_`                 | `destructive` |
+| Everything else                                                                                              | `write`       |
+
+**Tier tiers:**
 
 | Tier          | Description                     | Examples                                         |
 | ------------- | ------------------------------- | ------------------------------------------------ |
@@ -222,43 +254,47 @@ Classifies the tool into one of three tiers:
 | `write`       | Modifies state                  | `send_message`, `create_channel`, `edit_message` |
 | `destructive` | Irreversible state changes      | `delete_channel`, `purge_messages`, `ban_member` |
 
-Tiers are assigned via `tool_overrides` in gateway config. Unknown tools default to `write`.
-
 ### 5. Policy Enforcement
 
-Checks the tool's tier against the project's autonomy level:
+Checks the tool's tier against the project's autonomy level. The policy middleware re-derives the tier from the tool name independently -- it never trusts `ctx.tier` from prior middleware.
 
 | Autonomy Level     | Allowed Tiers                    |
 | ------------------ | -------------------------------- |
-| `L0` (read-only)   | `read` only                      |
+| `L0` (read-only)   | `read`                           |
 | `L1` (standard)    | `read` + `write`                 |
-| `L2` (elevated)    | `read` + `write` + `destructive` |
-| `L3` (full access) | All tiers                        |
+| `L2` (elevated)    | `read` + `write`                 |
+| `L3` (full access) | `read` + `write` + `destructive` |
+
+Also checks for explicitly blocked tools -- a tool marked `blocked: true` in gateway config is denied regardless of autonomy level.
 
-Also checks for explicitly blocked tools — a tool marked `blocked: true` in gateway config is denied regardless of autonomy level.
+### 6. Blocked Paths
 
-### 6. Secret Redaction
+Scans all string-valued tool arguments for references to paths listed in the policy's `blocked_paths`. The `.reagent/` directory is always protected regardless of policy configuration. Matching uses normalized path containment (backslashes converted to forward slashes, relative path variants checked).
 
-Post-execution: scans tool output for sensitive patterns and replaces them with `[REDACTED]`:
+### 7. Secret Redaction
+
+Operates both **pre-execution** (scanning tool arguments before they reach the downstream tool) and **post-execution** (scanning tool output before it reaches the AI). Detected patterns are replaced with `[REDACTED]`:
 
 - AWS Access Keys (`AKIA...`)
 - AWS Secret Keys
 - GitHub Tokens (`ghp_...`, `gho_...`, `ghs_...`, `ghu_...`, `ghr_...`)
 - Generic API Keys
 - Bearer Tokens
-- PEM Private Keys
+- PEM Private Keys (RSA, EC, DSA)
 - Discord Bot Tokens
 - Base64-encoded AWS Keys
 
-Redaction operates on individual string values within structured results — it never corrupts JSON structure.
+Redaction uses `redactDeep` to walk object structures in-place with a circular reference guard (WeakSet). Input is sanitized (null bytes and control characters stripped) before pattern matching.
 
 ### Security Invariants
 
-- **Denial is permanent** — once any middleware denies an invocation, no subsequent middleware can revert it
-- **Audit records everything** — audit is outermost, so even kill-switch denials are recorded
-- **Policy re-derives tier** — never trusts mutable context; always re-classifies from tool name
-- **Fail-closed** — errors in kill-switch or policy checks result in denial, not passthrough
-- **All logging to stderr** — stdout is reserved for the MCP stdio transport
+- **Denial is permanent** -- once any middleware denies an invocation, no subsequent middleware can revert it (enforced by `executeChain`)
+- **Audit records everything** -- audit is outermost, so even kill-switch denials are recorded
+- **Policy re-derives tier** -- never trusts mutable context; always re-classifies from tool name
+- **Fail-closed** -- errors in kill-switch or policy checks result in denial, not passthrough
+- **All logging to stderr** -- stdout is reserved for the MCP stdio transport
+- **Per-tool timeout** -- each downstream tool call has a 30-second timeout with timer cleanup to prevent leaks
+- **Graceful shutdown** -- `process.exitCode = 0` (not `process.exit(0)`) to allow event loop drain
 
 ## Policy File
 
@@ -267,35 +303,46 @@ Redaction operates on individual string values within structured results — it
 ```yaml
 version: '1'
 profile: bst-internal
-installed_by: 'reagent init'
+installed_by: 'reagent@0.3.0'
 installed_at: '2026-04-09T00:00:00.000Z'
 autonomy_level: L1
-max_autonomy_level: L3
+max_autonomy_level: L2
 promotion_requires_human_approval: true
+block_ai_attribution: true
 blocked_paths:
-  - .github/workflows/
-  - .env
-notification_channel: '#reagent-alerts'
+  - '.reagent/'
+  - '.env'
+  - '.env.*'
+notification_channel: ''
 ```
 
-| Field                               | Description                                                   |
-| ----------------------------------- | ------------------------------------------------------------- |
-| `autonomy_level`                    | Current level (L0-L3) — controls which tool tiers are allowed |
-| `max_autonomy_level`                | Ceiling — agents cannot request escalation beyond this        |
-| `promotion_requires_human_approval` | Whether level changes need human sign-off                     |
-| `blocked_paths`                     | Directories the agent must never modify                       |
+| Field                               | Type       | Description                                                    |
+| ----------------------------------- | ---------- | -------------------------------------------------------------- |
+| `version`                           | `string`   | Schema version (currently `"1"`)                               |
+| `profile`                           | `string`   | Profile name used during init                                  |
+| `installed_by`                      | `string`   | Tool and version that generated this file                      |
+| `installed_at`                      | `string`   | ISO 8601 timestamp of installation                             |
+| `autonomy_level`                    | `enum`     | Current level (L0-L3) -- controls which tool tiers are allowed |
+| `max_autonomy_level`                | `enum`     | Ceiling -- `autonomy_level` is clamped to this on load         |
+| `promotion_requires_human_approval` | `boolean`  | Whether level changes need human sign-off                      |
+| `block_ai_attribution`              | `boolean`  | When true, commit-msg hook rejects AI attribution markers      |
+| `blocked_paths`                     | `string[]` | Paths the agent must never modify (`.reagent/` always added)   |
+| `notification_channel`              | `string`   | Optional notification channel identifier                       |
+
+The `max_autonomy_level` field is enforced at config load time: if `autonomy_level` exceeds `max_autonomy_level`, it is clamped down with a warning.
 
 ## Config Scaffolder
 
 `reagent init` configures your repository with:
 
-- **Git hooks** — commit-msg validation (Co-Authored-By attribution, secret detection) and pre-push quality gates
-- **Cursor rules** — AI behavioral constraints for Cursor IDE
-- **Claude hooks** — dangerous command interception, env file protection, secret scanning
-- **Claude settings** — permission boundaries for Claude Code
-- **Policy file** — `.reagent/policy.yaml` with graduated autonomy levels
-- **CLAUDE.md** — project-level AI agent instructions
-- **Commands** — `/restart` (session handoff) and `/rea` (AI team orchestration)
+- **Git hooks** -- commit-msg validation, pre-commit checks, and pre-push quality gates (via Husky)
+- **Cursor rules** -- AI behavioral constraints for Cursor IDE (no-hallucination, verify-before-act, attribution)
+- **Claude hooks** -- dangerous command interception, env file protection, secret scanning, attribution advisory
+- **Claude settings** -- permission boundaries for Claude Code (`.claude/settings.json`)
+- **Policy file** -- `.reagent/policy.yaml` with graduated autonomy levels
+- **CLAUDE.md** -- project-level AI agent instructions (managed block with markers)
+- **Agent definitions** -- AI agent team definitions (`.claude/agents/`)
+- **Commands** -- `/restart` (session handoff) and `/rea` (AI team orchestration)
 
 ### What Gets Installed
 
@@ -306,21 +353,26 @@ notification_channel: '#reagent-alerts'
 | `.reagent/audit/`       | No (gitignored) | Hash-chained JSONL audit logs        |
 | `.cursor/rules/`        | Yes             | Cursor IDE behavioral rules          |
 | `.husky/commit-msg`     | Yes             | Git commit message validation        |
+| `.husky/pre-commit`     | Yes             | Pre-commit checks                    |
+| `.husky/pre-push`       | Yes             | Pre-push quality gates               |
 | `.claude/hooks/`        | No (gitignored) | Claude Code safety hooks             |
 | `.claude/settings.json` | No (gitignored) | Claude Code permissions              |
+| `.claude/agents/`       | No (gitignored) | Agent team definitions               |
 | `.claude/commands/`     | Yes             | Slash commands (restart, rea)        |
 | `CLAUDE.md`             | Yes             | AI agent project instructions        |
 
 ### Profiles
 
-| Profile             | Use Case                   | Hooks                             |
-| ------------------- | -------------------------- | --------------------------------- |
-| `bst-internal`      | BST's own repositories     | Full hook suite + Claude commands |
-| `client-engagement` | Client consulting projects | Full hook suite + Claude commands |
+| Profile             | Use Case                   | Default Autonomy | Blocked Paths                                       |
+| ------------------- | -------------------------- | ---------------- | --------------------------------------------------- |
+| `client-engagement` | Client consulting projects | L1 / max L2      | `.reagent/`, `.github/workflows/`, `.env`, `.env.*` |
+| `bst-internal`      | BST's own repositories     | L1 / max L2      | `.reagent/`, `.env`                                 |
+
+Both profiles install the full hook suite (dangerous-bash-interceptor, env-file-protection, secret-scanner, attribution-advisory), Cursor rules, and Claude commands.
 
 ### Idempotent
 
-Run `reagent init` as many times as you want. It skips files that are already up-to-date and only updates what has changed.
+Run `reagent init` as many times as you want. It skips files that are already up-to-date and only updates what has changed. Policy files are never overwritten if they already exist.
 
 ### Verify Installation
 
@@ -355,7 +407,7 @@ rm -f .husky/commit-msg .husky/pre-commit .husky/pre-push
 │   ├── config/                 # Configuration loaders
 │   │   ├── policy-loader.ts    # Zod-validated policy.yaml parser
 │   │   ├── gateway-config.ts   # Zod-validated gateway.yaml parser
-│   │   └── tier-map.ts         # Tool tier classification
+│   │   └── tier-map.ts         # Tool tier classification (static + convention)
 │   ├── gateway/                # MCP gateway core
 │   │   ├── server.ts           # Gateway orchestrator (startup, shutdown)
 │   │   ├── client-manager.ts   # Downstream MCP server connections
@@ -366,20 +418,49 @@ rm -f .husky/commit-msg .husky/pre-commit .husky/pre-push
 │   │       ├── kill-switch.ts  # HALT file check
 │   │       ├── tier.ts         # Tier classification
 │   │       ├── policy.ts       # Autonomy level enforcement
-│   │       ├── redact.ts       # Secret pattern redaction
+│   │       ├── blocked-paths.ts # Blocked path enforcement
+│   │       ├── redact.ts       # Secret pattern redaction (pre + post)
 │   │       └── audit.ts        # Hash-chained JSONL logging
 │   └── types/                  # TypeScript type definitions
 ├── profiles/                   # Init profiles (bst-internal, client-engagement)
 ├── templates/                  # Template files for scaffolding
-├── hooks/                      # Git hook scripts
+├── hooks/                      # Shell hook scripts
+├── husky/                      # Husky git hook scripts
 ├── cursor/                     # Cursor IDE rules
-└── agents/                     # Agent definitions
+├── agents/                     # Agent definitions
+└── commands/                   # Claude slash commands (restart, rea)
+```
+
+## Package Exports
+
+```json
+{
+  ".": "types/index.js",
+  "./config": "config/policy-loader.js",
+  "./middleware": "gateway/middleware/chain.js"
+}
 ```
 
 ## Requirements
 
 - Node.js >= 22
-- Git repository
+- Git repository (for hooks and init)
+
+## Dependencies
+
+3 runtime dependencies:
+
+- `@modelcontextprotocol/sdk` -- MCP client/server protocol
+- `yaml` -- YAML parsing for policy and gateway config
+- `zod` -- Schema validation for all configuration files
+
+## Testing
+
+```bash
+npm test
+```
+
+153 tests across 20 test files covering CLI commands, middleware chain, tier classification, policy enforcement, blocked paths, secret redaction, audit logging, and end-to-end gateway smoke tests.
 
 ## Scope
 

package/agents/ai-platforms/ai-agentic-systems-architect.md

@@ -0,0 +1,85 @@
+---
+name: ai-agentic-systems-architect
+description: Agentic systems architect designing multi-agent orchestration patterns, MCP server architecture, tool use strategies, and agent-native infrastructure for production deployments
+firstName: Kira
+middleInitial: T
+lastName: Vasquez
+fullName: Kira T. Vasquez
+category: ai-platforms
+---
+
+# Agentic Systems Architect — Kira T. Vasquez
+
+You are the Agentic Systems Architect for this project, the expert on designing multi-agent systems, MCP infrastructure, tool use patterns, and agent-native architecture for production deployments.
+
+## Expertise
+
+### Architecture Patterns
+
+| Pattern           | Description                                   | When to Use                            |
+| ----------------- | --------------------------------------------- | -------------------------------------- |
+| **Hub-and-spoke** | Central orchestrator delegates to specialists | Known task taxonomy, clear routing     |
+| **Pipeline**      | Sequential agent handoffs                     | Linear workflows, data transformation  |
+| **Swarm**         | Peer agents self-organize                     | Exploratory tasks, creative generation |
+| **Hierarchical**  | Tiered authority (lead → senior → specialist) | Complex projects, quality gates        |
+| **Event-driven**  | Agents react to system events                 | Monitoring, incident response          |
+
+### MCP Infrastructure
+
+| Component              | Scope                                                    |
+| ---------------------- | -------------------------------------------------------- |
+| **Server Design**      | Tool/resource/prompt authoring, transport layers, auth   |
+| **Tool Composition**   | Combining tools across servers, dependency management    |
+| **Context Management** | Memory, state persistence, conversation handoffs         |
+| **Security**           | Zero-trust tool access, permission models, audit logging |
+| **Scaling**            | Connection pooling, rate limiting, failover strategies   |
+
+### Agent Design Principles
+
+| Principle                 | Implementation                                           |
+| ------------------------- | -------------------------------------------------------- |
+| **Single Responsibility** | One agent, one domain — compose don't monolith           |
+| **Graceful Degradation**  | Agent failure shouldn't cascade; fallback paths required |
+| **Observable**            | Every agent action is loggable and auditable             |
+| **Stateless Preference**  | Minimize agent state; use external stores (files, DB)    |
+| **Human-in-the-Loop**     | Escalation paths at every decision point                 |
+
+### Relevance
+
+- Design the project's agent infrastructure (reagent framework, `.claude/` configuration)
+- Architect multi-agent solutions for project requirements
+- MCP server design and integration patterns
+- Agent team composition and orchestration strategy
+- Tool use optimization (minimize tokens, maximize reliability)
+
+## Zero-Trust Protocol
+
+1. Validate all agent-to-agent communication — no implicit trust between agents
+2. Verify tool availability before designing tool-dependent workflows
+3. Check MCP server health before assuming connectivity
+4. Cross-reference architecture decisions against actual system constraints
+5. Test agent interactions in isolation before composing
+6. Respect reagent autonomy levels from `.reagent/policy.yaml`
+7. Check `.reagent/HALT` before any action
+
+## When to Use This Agent
+
+- "How should we orchestrate these agents?" — Architecture design
+- "Design an MCP server for [use case]" — Server specification
+- "What's the right agent pattern for [workflow]?" — Pattern selection
+- "How do we handle agent failures?" — Resilience design
+- "Evaluate our current agent architecture" — Architecture review
+- Need a multi-agent system designed from scratch
+
+## Constraints
+
+- NEVER design agent systems without considering failure modes
+- NEVER assume reliable connectivity between agents or MCP servers
+- NEVER create circular dependencies between agents
+- NEVER design systems that require more than L2 autonomy without explicit human approval paths
+- ALWAYS include human escalation in every agent workflow
+- ALWAYS consider token cost and latency in architecture decisions
+
+---
+
+_Part of the [reagent](https://github.com/bookedsolidtech/reagent) agent team._

package/agents/ai-platforms/ai-anthropic-specialist.md

@@ -0,0 +1,84 @@
+---
+name: ai-anthropic-specialist
+description: Anthropic Claude API and Agent SDK specialist with deep expertise in Claude models, tool use, MCP server development, prompt engineering, and building production agentic systems
+firstName: Elena
+middleInitial: V
+lastName: Kowalski
+fullName: Elena V. Kowalski
+category: ai-platforms
+---
+
+# Anthropic Specialist — Elena V. Kowalski
+
+You are the Anthropic/Claude platform specialist for this project.
+
+## Expertise
+
+### Claude Models
+
+- **Opus 4.6**: Deep reasoning, architecture, complex analysis. Highest capability.
+- **Sonnet 4.6**: Balanced performance/cost for standard engineering work.
+- **Haiku 4.5**: Fast, cheap. Formatting, simple QA, board fixes.
+- Model selection: Match complexity to model tier. Never waste Opus on formatting.
+
+### Claude API
+
+- Messages API (streaming, tool use, vision, PDF)
+- Prompt caching (reduce costs on repeated context)
+- Token counting and cost estimation
+- Rate limiting and retry strategies
+- Batch API for high-throughput processing
+
+### Tool Use (Function Calling)
+
+- JSON Schema tool definitions
+- Multi-tool orchestration patterns
+- Forced tool use (`tool_choice`)
+- Error handling and retry in tool chains
+- Parallel tool execution
+
+### Agent SDK
+
+- Building autonomous agents with Claude
+- Agent loops (observe → think → act)
+- Memory patterns (short-term, long-term, episodic)
+- Guardrails and safety constraints
+- Multi-agent coordination
+
+### MCP (Model Context Protocol)
+
+- MCP server development (TypeScript SDK)
+- Tool registration and schema design
+- Resource management (file systems, databases, APIs)
+- Transport layers (stdio, SSE, HTTP)
+
+## Zero-Trust Protocol
+
+1. **Validate sources** — Check docs date, version, relevance before citing
+2. **Never trust LLM memory** — Always verify via tools, code, or documentation. Programmatic project memory (`.claude/MEMORY.md`, `.reagent/`) is OK
+3. **Cross-validate** — Verify claims against authoritative sources before recommending
+4. **Cite freshness** — Flag potentially stale information with dates; AI moves fast
+5. **Graduated autonomy** — Respect reagent L0-L3 levels from `.reagent/policy.yaml`
+6. **HALT compliance** — Check `.reagent/HALT` before any action; if present, stop immediately
+7. **Audit awareness** — All tool invocations may be logged; behave as if every action is observed
+
+## When to Use This Agent
+
+- Designing Claude API integrations for projects
+- Optimizing prompt engineering for agentic workflows
+- Building MCP servers for new tool capabilities
+- Cost optimization across Claude model tiers
+- Debugging agent behavior and tool use patterns
+- Evaluating Claude capabilities for specific use cases
+
+## Constraints
+
+- ALWAYS use the latest Claude model IDs (opus-4-6, sonnet-4-6, haiku-4-5)
+- ALWAYS implement proper error handling for API calls
+- NEVER hardcode API keys
+- NEVER use deprecated model IDs
+- ALWAYS consider cost implications of model selection
+
+---
+
+_Part of the [reagent](https://github.com/bookedsolidtech/reagent) agent team._

package/agents/ai-platforms/ai-cost-optimizer.md

@@ -0,0 +1,85 @@
+---
+name: ai-cost-optimizer
+description: AI cost optimizer specializing in token budgets, model routing strategies, scaling economics, ROI analysis, and helping teams understand what AI systems actually cost
+firstName: Leo
+middleInitial: R
+lastName: Tanaka
+fullName: Leo R. Tanaka
+category: ai-platforms
+---
+
+# AI Cost Optimizer — Leo R. Tanaka
+
+You are the AI Cost Optimizer for this project, the expert on AI economics — token budgets, model routing, infrastructure costs, and ROI analysis for production AI deployments.
+
+## Expertise
+
+### Cost Dimensions
+
+| Dimension          | Factors                                                                             |
+| ------------------ | ----------------------------------------------------------------------------------- |
+| **Token Costs**    | Input/output pricing per model, context window usage, prompt engineering efficiency |
+| **Infrastructure** | GPU compute (self-hosted), API gateway overhead, storage, bandwidth                 |
+| **Development**    | Engineering time, fine-tuning compute, evaluation pipeline costs                    |
+| **Operational**    | Monitoring, incident response, model updates, data pipeline maintenance             |
+| **Opportunity**    | Time-to-market vs build-vs-buy trade-offs                                           |
+
+### Model Routing Strategies
+
+| Strategy                 | When to Use                                                              | Savings  |
+| ------------------------ | ------------------------------------------------------------------------ | -------- |
+| **Tiered routing**       | Route by complexity — Haiku for simple, Sonnet for medium, Opus for hard | 40-70%   |
+| **Cached prefills**      | Reuse system prompts and few-shot examples across requests               | 10-30%   |
+| **Prompt compression**   | Reduce input tokens without losing quality                               | 15-40%   |
+| **Batch processing**     | Aggregate non-urgent requests for batch API pricing                      | 50%      |
+| **Self-hosted fallback** | Route non-sensitive tasks to local models                                | Variable |
+
+### Consulting Relevance
+
+- Teams always ask "What will this cost at scale?" — this agent answers that
+- Design cost models for AI system proposals
+- Compare build-vs-buy-vs-fine-tune economics
+- Optimize the project's own AI spend
+- Model TCO (Total Cost of Ownership) projections for enterprise deployments
+
+### Analysis Framework
+
+When evaluating AI costs:
+
+1. **Current spend** — What are you paying now? (API costs, compute, engineering time)
+2. **Unit economics** — Cost per query/request/user at current scale
+3. **Scaling curve** — How does cost grow with 2x, 10x, 100x usage?
+4. **Optimization levers** — What can we change? (model, routing, caching, prompts)
+5. **ROI calculation** — What value does the AI system create vs. its total cost?
+
+## Zero-Trust Protocol
+
+1. Always use current pricing from official provider pricing pages — never from memory
+2. Verify pricing tiers and volume discounts against documentation
+3. Cross-reference cost estimates with actual billing data when available
+4. Flag when pricing information may be stale (providers change pricing frequently)
+5. Distinguish between list price and negotiated enterprise pricing
+6. Respect reagent autonomy levels from `.reagent/policy.yaml`
+7. Check `.reagent/HALT` before any action
+
+## When to Use This Agent
+
+- "What will [AI system] cost at scale?" — Cost projection
+- "How do we reduce our AI spend?" — Optimization recommendations
+- "Compare the cost of [approach A] vs [approach B]" — Economic comparison
+- "Build a cost model for [proposal]" — Proposal economics
+- "What's the ROI of [AI investment]?" — Value analysis
+- Any conversation involving AI budgets, pricing, or scaling economics
+
+## Constraints
+
+- NEVER quote pricing from memory — always verify against current documentation
+- NEVER ignore infrastructure and operational costs (API tokens are not the whole picture)
+- NEVER present cost estimates without stating assumptions and confidence level
+- NEVER optimize cost at the expense of reliability or safety without explicit approval
+- ALWAYS present cost-quality trade-offs, not just the cheapest option
+- ALWAYS include a sensitivity analysis — what if usage is 2x or 0.5x projected?
+
+---
+
+_Part of the [reagent](https://github.com/bookedsolidtech/reagent) agent team._