compact-agent 1.10.0 → 1.11.0

package/resources/ecc/skills/agent-payment-x402/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: agent-payment-x402
+description: Add x402 payment execution to AI agents with per-task budgets, spending controls, and non-custodial wallets. Supports Base through agentwallet-sdk and X Layer through OKX Payments / OKX Agent Payments Protocol.
+origin: community
+---
+
+# Agent Payment Execution (x402)
+
+Enable AI agents to make policy-gated payments with built-in spending controls. Uses the x402 HTTP payment protocol and MCP tools so agents can pay for external services, APIs, or other agents without custodial risk.
+
+## When to Use
+
+Use when: your agent needs to pay for an API call, purchase a service, settle with another agent, enforce per-task spending limits, or manage a non-custodial wallet. Pairs naturally with cost-aware-llm-pipeline and security-review skills.
+
+## Decision Tree
+
+Choose the integration path based on whether your agent is buying access to a paid API or charging others for one:
+
+| Need | Recommended path |
+|------|------------------|
+| Agent pays a 402-gated API on Base or another agentwallet-supported chain | Use `agentwallet-sdk` as an MCP payment server with strict spending policy |
+| Agent pays a 402-gated API on X Layer | Use OKX Agent Payments Protocol from `okx/onchainos-skills`; `okx-x402-payment` is a deprecated legacy alias |
+| TypeScript API charges agents | Use OKX Payments TypeScript seller SDK docs for Express, Hono, Fastify, or Next.js |
+| Go API charges agents | Use OKX Payments Go seller SDK docs for Gin, Echo, or `net/http` |
+| Rust API charges agents | Use OKX Payments Rust seller SDK docs for Axum |
+| Java API charges agents | Use OKX Payments Java seller SDK docs for Spring Boot 2/3, Java EE, or Jakarta |
+| Python API charges agents | Check the current OKX Payments repository before implementation; a Python seller guide may not be available |
+
+## Supported Networks
+
+- `agentwallet-sdk`: use the package docs to confirm current network coverage before production. Base Sepolia is the safest development default; Base mainnet is the production path called out by the original skill.
+- OKX Payments / X Layer: current seller docs target X Layer (`eip155:196`) and USDT0 settlement. Fetch current SDK docs before generating production code because payment packages and facilitator behavior can change quickly.
+
+## How It Works
+
+### x402 Protocol
+x402 extends HTTP 402 (Payment Required) into a machine-negotiable flow. When a server returns `402`, the agent's payment tool negotiates price, checks budget, signs a transaction, and retries only inside the policy and confirmation boundary set by the orchestrator.
+
+### Spending Controls
+Every payment tool call enforces a `SpendingPolicy`:
+- **Per-task budget** — max spend for a single agent action
+- **Per-session budget** — cumulative limit across an entire session
+- **Allowlisted recipients** — restrict which addresses/services the agent can pay
+- **Rate limits** — max transactions per minute/hour
+
+### Non-Custodial Wallets
+Agents hold their own keys via ERC-4337 smart accounts. The orchestrator sets policy before delegation; the agent can only spend within bounds. No pooled funds, no custodial risk.
+
+## MCP Integration
+
+The payment layer exposes standard MCP tools that slot into any Claude Code or agent harness setup.
+
+> **Security note**: Always pin the package version. This tool manages private keys — unpinned `npx` installs introduce supply-chain risk.
+
+### Option A: agentwallet-sdk (Base / multi-chain)
+
+```json
+{
+  "mcpServers": {
+    "agentpay": {
+      "command": "npx",
+      "args": ["agentwallet-sdk@6.0.0"]
+    }
+  }
+}
+```
+
+### Available Tools (agent-callable)
+
+| Tool | Purpose |
+|------|---------|
+| `get_balance` | Check agent wallet balance |
+| `send_payment` | Send payment to address or ENS |
+| `check_spending` | Query remaining budget |
+| `list_transactions` | Audit trail of all payments |
+
+> **Note**: Spending policy is set by the **orchestrator** before delegating to the agent — not by the agent itself. This prevents agents from escalating their own spending limits. Configure policy via `set_policy` in your orchestration layer or pre-task hook, never as an agent-callable tool.
+
+### Option B: OKX Agent Payments Protocol (X Layer)
+
+Use this path for X Layer x402, Multi-Party Payment (MPP), session payment, charge, and A2A charge flows.
+
+For buyer-side agent flows:
+
+1. Install or reference the current `okx/onchainos-skills` repository.
+2. Use `skills/okx-agent-payments-protocol/SKILL.md` as the dispatcher.
+3. Treat `skills/okx-x402-payment/SKILL.md` as a deprecated compatibility alias, not as the canonical skill.
+4. Require explicit user confirmation before wallet status checks or payment actions. Do not hide payment execution behind a generic tool call.
+
+For seller-side API flows, fetch the latest language-specific guide before generating code:
+
+| Runtime | Current guide |
+|---------|---------------|
+| TypeScript | `https://raw.githubusercontent.com/okx/payments/main/typescript/SELLER.md` |
+| Go | `https://raw.githubusercontent.com/okx/payments/main/go/x402/SELLER.md` |
+| Rust | `https://raw.githubusercontent.com/okx/payments/main/rust/x402/SELLER.md` |
+| Java | `https://raw.githubusercontent.com/okx/payments/main/java/SELLER.md` |
+
+Do not copy examples from older docs without checking the current OKX repository. Current OKX guidance uses `okx-agent-payments-protocol` as the dispatcher, and Java seller docs are now available.
+
+## Examples
+
+### Budget enforcement in an MCP client
+
+When building an orchestrator that calls the agentpay MCP server, enforce budgets before dispatching paid tool calls.
+
+> **Prerequisites**: Install the package before adding the MCP config — `npx` without `-y` will prompt for confirmation in non-interactive environments, causing the server to hang: `npm install -g agentwallet-sdk@6.0.0`
+
+```typescript
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+async function main() {
+  // 1. Validate credentials before constructing the transport.
+  //    A missing key must fail immediately — never let the subprocess start without auth.
+  const walletKey = process.env.WALLET_PRIVATE_KEY;
+  if (!walletKey) {
+    throw new Error("WALLET_PRIVATE_KEY is not set — refusing to start payment server");
+  }
+
+  // Connect to the agentpay MCP server via stdio transport.
+  // Whitelist only the env vars the server needs — never forward all of process.env
+  // to a third-party subprocess that manages private keys.
+  const transport = new StdioClientTransport({
+    command: "npx",
+    args: ["agentwallet-sdk@6.0.0"],
+    env: {
+      PATH: process.env.PATH ?? "",
+      NODE_ENV: process.env.NODE_ENV ?? "production",
+      WALLET_PRIVATE_KEY: walletKey,
+    },
+  });
+  const agentpay = new Client({ name: "orchestrator", version: "1.0.0" });
+  await agentpay.connect(transport);
+
+  // 2. Set spending policy before delegating to the agent.
+  //    Always verify success — a silent failure means no controls are active.
+  const policyResult = await agentpay.callTool({
+    name: "set_policy",
+    arguments: {
+      per_task_budget: 0.50,
+      per_session_budget: 5.00,
+      allowlisted_recipients: ["api.example.com"],
+    },
+  });
+  if (policyResult.isError) {
+    throw new Error(
+      `Failed to set spending policy — do not delegate: ${JSON.stringify(policyResult.content)}`
+    );
+  }
+
+  // 3. Use preToolCheck before any paid action
+  await preToolCheck(agentpay, 0.01);
+}
+
+// Pre-tool hook: fail-closed budget enforcement with four distinct error paths.
+async function preToolCheck(agentpay: Client, apiCost: number): Promise<void> {
+  // Path 1: Reject invalid input (NaN/Infinity bypass the < comparison)
+  if (!Number.isFinite(apiCost) || apiCost < 0) {
+    throw new Error(`Invalid apiCost: ${apiCost} — action blocked`);
+  }
+
+  // Path 2: Transport/connectivity failure
+  let result;
+  try {
+    result = await agentpay.callTool({ name: "check_spending" });
+  } catch (err) {
+    throw new Error(`Payment service unreachable — action blocked: ${err}`);
+  }
+
+  // Path 3: Tool returned an error (e.g., auth failure, wallet not initialised)
+  if (result.isError) {
+    throw new Error(
+      `check_spending failed — action blocked: ${JSON.stringify(result.content)}`
+    );
+  }
+
+  // Path 4: Parse and validate the response shape
+  let remaining: number;
+  try {
+    const parsed = JSON.parse(
+      (result.content as Array<{ text: string }>)[0].text
+    );
+    if (!Number.isFinite(parsed?.remaining)) {
+      throw new TypeError("missing or non-finite 'remaining' field");
+    }
+    remaining = parsed.remaining;
+  } catch (err) {
+    throw new Error(
+      `check_spending returned unexpected format — action blocked: ${err}`
+    );
+  }
+
+  // Path 5: Budget exceeded
+  if (remaining < apiCost) {
+    throw new Error(
+      `Budget exceeded: need $${apiCost} but only $${remaining} remaining`
+    );
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exitCode = 1;
+});
+```
+
+## Best Practices
+
+- **Set budgets before delegation**: When spawning sub-agents, attach a SpendingPolicy via your orchestration layer. Never give an agent unlimited spend.
+- **Pin your dependencies**: Always specify an exact version in your MCP config (e.g., `agentwallet-sdk@6.0.0`). Verify package integrity before deploying to production.
+- **Audit trails**: Use `list_transactions` in post-task hooks to log what was spent and why.
+- **Fail closed**: If the payment tool is unreachable, block the paid action — don't fall back to unmetered access.
+- **Pair with security-review**: Payment tools are high-privilege. Apply the same scrutiny as shell access.
+- **Test with testnets first**: Use Base Sepolia for development; switch to Base mainnet for production.
+
+## Production Reference
+
+- **npm**: [`agentwallet-sdk`](https://www.npmjs.com/package/agentwallet-sdk)
+- **Merged into NVIDIA NeMo Agent Toolkit**: [PR #17](https://github.com/NVIDIA/NeMo-Agent-Toolkit-Examples/pull/17) — x402 payment tool for NVIDIA's agent examples
+- **Protocol spec**: [x402.org](https://x402.org)
+- **OKX Payments SDKs**: [`okx/payments`](https://github.com/okx/payments) — TypeScript, Go, Rust, and Java seller integrations for X Layer x402
+- **OKX Agent Payments Protocol skill**: [`okx/onchainos-skills`](https://github.com/okx/onchainos-skills/tree/main/skills/okx-agent-payments-protocol)
+- **OKX Payments overview**: [web3.okx.com/onchainos/dev-docs/payments/overview](https://web3.okx.com/onchainos/dev-docs/payments/overview)

package/resources/ecc/skills/agent-sort/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: agent-sort
 description: Build an evidence-backed ECC install plan for a specific repo by sorting skills, commands, rules, hooks, and extras into DAILY vs LIBRARY buckets using parallel repo-aware review passes. Use when ECC should be trimmed to what a project actually needs instead of loading the full bundle.
+origin: ECC
 ---
 
 # Agent Sort

package/resources/ecc/skills/agentic-engineering/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: agentic-engineering
+description: Operate as an agentic engineer using eval-first execution, decomposition, and cost-aware model routing.
+origin: ECC
+---
+
+# Agentic Engineering
+
+Use this skill for engineering workflows where AI agents perform most implementation work and humans enforce quality and risk controls.
+
+## Operating Principles
+
+1. Define completion criteria before execution.
+2. Decompose work into agent-sized units.
+3. Route model tiers by task complexity.
+4. Measure with evals and regression checks.
+
+## Eval-First Loop
+
+1. Define capability eval and regression eval.
+2. Run baseline and capture failure signatures.
+3. Execute implementation.
+4. Re-run evals and compare deltas.
+
+## Task Decomposition
+
+Apply the 15-minute unit rule:
+- each unit should be independently verifiable
+- each unit should have a single dominant risk
+- each unit should expose a clear done condition
+
+## Model Routing
+
+- Haiku: classification, boilerplate transforms, narrow edits
+- Sonnet: implementation and refactors
+- Opus: architecture, root-cause analysis, multi-file invariants
+
+## Session Strategy
+
+- Continue session for closely-coupled units.
+- Start fresh session after major phase transitions.
+- Compact after milestone completion, not during active debugging.
+
+## Review Focus for AI-Generated Code
+
+Prioritize:
+- invariants and edge cases
+- error boundaries
+- security and auth assumptions
+- hidden coupling and rollout risk
+
+Do not waste review cycles on style-only disagreements when automated format/lint already enforce style.
+
+## Cost Discipline
+
+Track per task:
+- model
+- token estimate
+- retries
+- wall-clock time
+- success/failure
+
+Escalate model tier only when lower tier fails with a clear reasoning gap.

package/resources/ecc/skills/agentic-os/SKILL.md

@@ -0,0 +1,387 @@
+---
+name: agentic-os
+description: Build persistent multi-agent operating systems on Claude Code. Covers kernel architecture, specialist agents, slash commands, file-based memory, scheduled automation, and state management without external databases.
+origin: ECC
+---
+
+# Agentic OS
+
+Treat Claude Code as a persistent runtime / operating system rather than a chat session. This skill codifies the architecture used by production agentic setups: a kernel config that routes tasks to specialist agents, persistent file-based memory, scheduled automation, and a JSON/markdown data layer.
+
+## When to Activate
+
+- Building a multi-agent workflow inside Claude Code
+- Setting up persistent Claude Code automation that survives session restarts
+- Creating a "personal OS" or "agentic OS" for recurring tasks
+- User says "agentic OS", "personal OS", "multi-agent", "agent coordinator", "persistent agent"
+- Structuring long-running projects where context must survive across sessions
+
+## Architecture Overview
+
+The Agentic OS has four layers. Each layer is a directory in your project root.
+
+```
+project-root/
+├── CLAUDE.md          # Kernel: identity, routing rules, agent registry
+├── agents/            # Specialist agent definitions (markdown prompts)
+├── .claude/commands/  # Slash commands: user-facing CLI
+├── scripts/           # Daemon scripts: scheduled or event-driven tasks
+└── data/              # State: JSON/markdown filesystem, no external DB
+```
+
+### Layer Responsibilities
+
+| Layer | Purpose | Persistence |
+|---|---|---|
+| Kernel (`CLAUDE.md`) | Identity, routing, model policies, agent registry | Git-tracked |
+| Agents (`agents/`) | Specialist identities with scoped tools and memory | Git-tracked |
+| Commands (`.claude/commands/`) | User-facing slash commands (`/daily-sync`, `/outreach`) | Git-tracked |
+| Scripts (`scripts/`) | Python/JS daemons triggered by cron or webhooks | Git-tracked |
+| State (`data/`) | Append-only logs, project state, decision records | Git-ignored or tracked |
+
+## The Kernel
+
+`CLAUDE.md` is the kernel. It acts as the COO / orchestrator. Claude reads it at session start and uses it to route work.
+
+### Kernel Structure
+
+```markdown
+# CLAUDE.md - Agentic OS Kernel
+
+## Identity
+You are the COO of [project-name]. You route tasks to specialist agents.
+You never write code directly. You delegate to the right agent and synthesize results.
+
+## Agent Registry
+
+| Agent | Role | Trigger |
+|---|---|---|
+| @dev | Code, architecture, debugging | User says "build", "fix", "refactor" |
+| @writer | Documentation, content, emails | User says "write", "draft", "blog" |
+| @researcher | Research, analysis, fact-checking | User says "research", "analyze", "compare" |
+| @ops | DevOps, deployment, infrastructure | User says "deploy", "CI", "server" |
+
+## Routing Rules
+1. Parse the user request for intent keywords
+2. Match to the Agent Registry trigger column
+3. Load the corresponding agent file from `agents/<name>.md`
+4. Hand off execution with full context
+5. Synthesize and present the result back to the user
+
+## Model Policies
+- Default model: use the repository or harness default.
+- @dev tasks: prefer a higher-reasoning model for complex architecture.
+- @researcher tasks: use the configured research-capable model and approved search tools.
+- Cost ceiling: warn before exceeding the project's configured spend threshold.
+```
+
+### Key Principle
+
+The kernel should be **small and declarative**. Routing logic lives in plain markdown tables, not code. This makes the system inspectable and editable without debugging.
+
+## Specialist Agents
+
+Each agent is a standalone markdown file in `agents/`. Claude loads the relevant agent file when routing a task.
+
+### Agent Definition Format
+
+```markdown
+# @dev - Software Engineer
+
+## Identity
+You are a senior software engineer. You write clean, tested, production-grade code.
+You prefer simple solutions. You ask clarifying questions when requirements are ambiguous.
+
+## Memory Scope
+- Read `data/projects/<current-project>.md` for context
+- Read `data/decisions/` for architectural decisions
+- Append execution logs to `data/logs/<date>-@dev.md`
+
+## Tool Access
+- Full filesystem access within project root
+- Git operations (status, diff, commit, branch)
+- Test runner access
+- MCP servers as configured in `.claude/mcp.json`
+
+## Constraints
+- Always write tests for new features
+- Never commit directly to `main`; use feature branches
+- Prefer editing existing files over creating new ones
+- Keep functions under 50 lines when possible
+```
+
+### Multi-Agent Collaboration Pattern
+
+When a task spans multiple agents, the kernel runs them sequentially or in parallel:
+
+```
+User: "Build a landing page and write the launch blog post"
+
+Kernel routing:
+1. @dev - "Build a landing page with [requirements]"
+2. @writer - "Write a launch blog post for [product] using the landing page copy"
+3. Kernel synthesizes both outputs into a unified response
+```
+
+For parallel execution, use Claude Code's background task capability or shell scripts that invoke Claude Code with specific agent contexts.
+
+## Commands and Daily Workflows
+
+Slash commands are markdown files in `.claude/commands/`. They define reusable workflows.
+
+### Command Structure
+
+```markdown
+# /daily-sync
+
+Run the morning briefing:
+
+1. Read `data/logs/last-sync.md` for context
+2. Check project status: `git status`, pending PRs, CI health
+3. Review `data/inbox/` for new tasks or decisions needed
+4. Generate a summary of blockers, priorities, and next actions
+5. Append the briefing to `data/logs/daily/<date>.md`
+```
+
+### Standard Command Set
+
+| Command | Purpose |
+|---|---|
+| `/daily-sync` | Morning briefing: status, blockers, priorities |
+| `/outreach` | Run outreach workflow (email, LinkedIn, etc.) |
+| `/research <topic>` | Deep research with citation tracking |
+| `/apply-jobs` | Tailor resume + cover letter for a target role |
+| `/analytics` | Pull metrics from Stripe, GitHub, or custom sources |
+| `/interview-prep` | Generate flashcards or mock interview questions |
+| `/decision <topic>` | Log a decision with pros/cons and chosen path |
+
+### Activating Commands
+
+Place command files in `.claude/commands/<command-name>.md`. Claude Code auto-discovers them. Users invoke them with `/<command-name>`.
+
+## Persistent Memory
+
+Memory is file-based. No vector DB, no Redis, no PostgreSQL. JSON and markdown files in `data/` are the database.
+
+### Memory Directory Structure
+
+```
+data/
+├── daily-logs/         # Append-only daily activity logs
+├── projects/           # Per-project context files
+├── decisions/          # Architectural and business decisions (ADR format)
+├── inbox/              # New tasks or ideas awaiting triage
+├── contacts/           # People, companies, relationship notes
+└── templates/          # Reusable prompts and formats
+```
+
+### Daily Log Format
+
+```markdown
+# 2026-04-22 - Daily Log
+
+## Sessions
+- 09:00 - Session 1: Refactored auth module (@dev)
+- 11:30 - Session 2: Drafted investor update (@writer)
+
+## Decisions
+- Switched from JWT to session cookies (see `data/decisions/2026-04-22-auth.md`)
+
+## Blockers
+- Waiting on API key from vendor (follow up 2026-04-24)
+
+## Next Actions
+- [ ] Merge auth refactor PR
+- [ ] Send investor update for review
+```
+
+### Auto-Reflection Pattern
+
+At the end of each session, the kernel appends a reflection:
+
+```markdown
+## Reflection - Session 3
+- What worked: Parallel agent execution saved 20 minutes
+- What didn't: @researcher hit a paywalled source, need better source ranking
+- What to change: Add `source-tier` field to research notes (A/B/C credibility)
+```
+
+This creates a feedback loop that improves the system over time without code changes.
+
+## Scheduled Automation
+
+Agentic OS tasks run on a schedule using external cron, not Claude Code's built-in cron (which dies when the session ends).
+
+### macOS: LaunchAgent
+
+```xml
+<!-- ~/Library/LaunchAgents/com.agentic.daily-sync.plist -->
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" ...>
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.agentic.daily-sync</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/claude</string>
+        <string>--cwd</string>
+        <string>/path/to/project</string>
+        <string>--command</string>
+        <string>/daily-sync</string>
+    </array>
+    <key>StartCalendarInterval</key>
+    <dict>
+        <key>Hour</key>
+        <integer>8</integer>
+        <key>Minute</key>
+        <integer>0</integer>
+    </dict>
+    <key>StandardOutPath</key>
+    <string>/tmp/agentic-daily-sync.log</string>
+</dict>
+</plist>
+```
+
+### Linux: systemd Timer
+
+```ini
+# ~/.config/systemd/user/agentic-daily-sync.service
+[Unit]
+Description=Agentic OS Daily Sync
+
+[Service]
+Type=oneshot
+ExecStart=/usr/local/bin/claude --cwd /path/to/project --command /daily-sync
+```
+
+```ini
+# ~/.config/systemd/user/agentic-daily-sync.timer
+[Unit]
+Description=Run daily sync every morning
+
+[Timer]
+OnCalendar=*-*-* 8:00:00
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+```
+
+### Cross-Platform: pm2
+
+```bash
+# ecosystem.config.js
+module.exports = {
+  apps: [{
+    name: 'agentic-daily-sync',
+    script: 'claude',
+    args: '--cwd /path/to/project --command /daily-sync',
+    cron_restart: '0 8 * * *',
+    autorestart: false
+  }]
+};
+```
+
+## Data Layer
+
+The data layer is your filesystem. Use JSON for structured data and markdown for narrative content.
+
+### JSON for Structured State
+
+```json
+// data/projects/website-v2.json
+{
+  "name": "Website v2",
+  "status": "in-progress",
+  "milestone": "beta-launch",
+  "agents_involved": ["@dev", "@writer"],
+  "files": {
+    "spec": "docs/website-v2-spec.md",
+    "design": "designs/website-v2.fig"
+  },
+  "metrics": {
+    "commits": 47,
+    "last_session": "2026-04-22T11:30:00Z"
+  }
+}
+```
+
+### Markdown for Narrative
+
+Use markdown for anything a human reads: decisions, logs, research notes, contact records.
+
+### Schema Evolution
+
+Never rename existing fields. Add new fields and mark old ones deprecated:
+
+```json
+{
+  "name": "Website v2",
+  "status": "in-progress",
+  "milestone": "beta-launch",
+  "_deprecated_priority": "high",
+  "priority_v2": { "level": "high", "rationale": "Blocks investor demo" }
+}
+```
+
+This keeps historical data readable without migration scripts.
+
+## Anti-Patterns
+
+### Monolithic Single Agent
+
+```markdown
+# BAD - One agent does everything
+You are a full-stack developer, writer, researcher, and DevOps engineer.
+```
+
+Split into specialist agents. The kernel handles routing.
+
+### Stateless Sessions
+
+```markdown
+# BAD - No memory between sessions
+Starting fresh every time Claude Code opens.
+```
+
+Always read `data/` at session start and write back at session end.
+
+### Hardcoded Credentials
+
+```markdown
+# BAD - API keys in agent files or CLAUDE.md
+Your OpenAI API key is sk-xxxxxxxx
+```
+
+Use environment variables or a `.env` file loaded by scripts. Agents reference `process.env.API_KEY`.
+
+### External Database for Simple State
+
+```markdown
+# BAD - PostgreSQL for a solo user's agentic OS
+```
+
+Use JSON/markdown files until you have multiple concurrent users or GBs of data.
+
+### Over-Engineered Routing
+
+```markdown
+# BAD - Routing logic in code instead of markdown tables
+if (intent.includes('deploy')) { agent = opsAgent; }
+```
+
+Keep routing declarative in `CLAUDE.md` markdown tables. It is inspectable, editable, and debuggable.
+
+## Best Practices
+
+- [ ] `CLAUDE.md` is under 200 lines and fits in context window
+- [ ] Each agent file is under 100 lines and focused on one domain
+- [ ] `data/` is git-ignored for sensitive logs, git-tracked for decisions and specs
+- [ ] Commands use imperative names: `/daily-sync`, not `/run-daily-sync`
+- [ ] Logs are append-only; never edit past daily logs
+- [ ] Every agent has a `Memory Scope` section defining what files it reads
+- [ ] Reflections are written at the end of every session
+- [ ] Scheduled tasks use external cron (LaunchAgent, systemd, pm2), not Claude Code's session cron
+- [ ] Cost tracking: log API spend per session in `data/logs/<date>-costs.json`
+- [ ] One project = one Agentic OS. Do not share a single `CLAUDE.md` across unrelated projects.