Governance

Organizational intelligence for PAI, cherry-picked from Paperclip's zero-human-company model and adapted for CLI-first personal AI infrastructure.

Workflow Routing

Features

1. Budget Controls

Track and limit per-agent spending with cost estimates based on model pricing.

# Show spending report for current month
bun tools/BudgetReport.ts

# Compare against budget limits
bun tools/BudgetReport.ts --budget

# Filter by agent
bun tools/BudgetReport.ts --agent hiram --period week

Config: config/budgets.yml — per-agent monthly limits with alert thresholds.

2. Approval Gates

Human-in-the-loop governance for high-impact actions via Telegram.

# Check if action needs approval
bun tools/ApprovalGate.ts check deploy --agent hiram

# Request approval (sends Telegram, waits for response)
bun tools/ApprovalGate.ts request deploy --agent hiram --action "Push to carbene.ai production"

# List all gates
bun tools/ApprovalGate.ts list

Config: config/approvals.yml — gate definitions with Telegram integration.

3. Goal Ancestry

Every task traces back to a company goal. Provides "why" context for agent prompts.

# Show goal hierarchy
bun tools/GoalManager.ts list

# Trace project to goal
bun tools/GoalManager.ts trace P4

# Get injectable context block for agent prompts
bun tools/GoalManager.ts context P1

Config: goals/goals.yml — goal hierarchy with projects.

4. Org Chart Visualization

Auto-generated Mermaid diagram from agent configurations.

# Print Mermaid diagram
bun tools/OrgChart.ts

# Save as SVG (requires mmdc)
bun tools/OrgChart.ts --output svg --save org-chart.svg

5. Standing Orders (Heartbeat)

Recurring agent tasks executed on schedules — the PAI version of Paperclip's heartbeat engine.

# List all standing orders
bun tools/StandingOrders.ts list

# Enable/disable
bun tools/StandingOrders.ts enable daily-security-check

# Manually trigger
bun tools/StandingOrders.ts run friday-retro

# Sync to system cron
bun tools/StandingOrders.ts sync

Config: config/standing-orders.yml — agent schedules with goal links.

6. Config Export/Import

Portable, sanitized PAI configuration bundles for backup and sharing.

# Export (sanitized by default)
bun tools/ConfigExport.ts --output ~/exports/pai-config.tar.gz

# Import with dry run
bun tools/ConfigImport.ts pai-config.tar.gz --dry-run

# Import with merge (don't overwrite existing)
bun tools/ConfigImport.ts pai-config.tar.gz --merge

7. Multi-Workspace Isolation

Group agents, budgets, and goals by business domain.

Config: config/workspaces.yml — workspace definitions mapping agents to goals with budget pools.

8. Atomic Task Checkout

File-based locking prevents two agents from claiming the same task.

# Acquire lock
bun tools/TaskLock.ts acquire TASK-001 --agent hiram

# Release lock
bun tools/TaskLock.ts release TASK-001 --agent hiram

# Check status
bun tools/TaskLock.ts status TASK-001

# Clean stale locks (>30 min)
bun tools/TaskLock.ts cleanup --stale 30

Architecture

Governance/
├── SKILL.md                    # This file
├── tools/
│   ├── OrgChart.ts             # Mermaid org chart generator
│   ├── BudgetReport.ts         # Cost tracking and budget comparison
│   ├── GoalManager.ts          # Goal hierarchy management
│   ├── ApprovalGate.ts         # Telegram-based approval gates
│   ├── StandingOrders.ts       # Heartbeat/recurring agent tasks
│   ├── ConfigExport.ts         # Portable config export
│   ├── ConfigImport.ts         # Config import with merge
│   └── TaskLock.ts             # Atomic task checkout
├── config/
│   ├── budgets.yml             # Per-agent spend limits
│   ├── approvals.yml           # Approval gate definitions
│   ├── standing-orders.yml     # Recurring agent schedules
│   └── workspaces.yml          # Workspace isolation
└── reference/
    └── PaperclipInspiration.md # Design decisions and Paperclip comparison

Design Principles

1. CLI-first — Every feature is a TypeScript CLI tool (PAI Constitution Principle 8)
2. File-based state — No database required; YAML configs and file locks
3. Telegram-native governance — Approvals via existing Telegram bot infrastructure
4. Goal-aware — Every agent action can trace back to a company objective
5. Sanitize by default — Config exports strip secrets automatically
6. Composable — Each tool works independently; combine via shell pipelines

Examples

Example 1: Morning governance check

User: "How are we doing on budgets this month?"
→ Runs BudgetReport.ts --budget
→ Shows per-agent spend vs limits
→ Flags any agents approaching thresholds

Example 2: Pre-deploy approval

User: "Deploy carbene.ai changes"
→ ApprovalGate.ts check deploy --agent hiram
→ Gate triggered → sends Telegram approval request
→ Waits for the user's "approve" reply
→ Proceeds with deployment

Example 3: Why are we doing this?

User: "What goal does the trading system serve?"
→ GoalManager.ts trace P7
→ "P7 (Joseph Trading System) → G3 (Generate investment returns via automated trading)"
→ Provides full context for decision-making