agent-builder/scripts/templates/org-chart/README.md

Org Chart

File-based agent hierarchy using Paperclip's simple reportsTo pattern.

Design decisions

• Simple reportsTo FK, not recursive: Each agent has a single Reports To field referencing its parent by name. No recursive traversal at runtime.
• Board = human operator: Top-level agents use (board) to indicate they report directly to the human. The human always has override authority.
• Markdown table: Human-editable, version-controlled, no service dependency.

Delegation flow

(board) [human]
  └─ orchestrator-agent (manager)
       ├─ research-agent (worker)
       └─ writer-agent (worker)

Task assignment flows down the tree. Escalation flows up. Cross-team requests are routed through the nearest common ancestor.

Human override authority

The human operator ("board") has unconditional override authority:

• Any agent can be paused, redirected, or terminated at any time
• No agent can block a human instruction
• Governance gates apply to agents, not to the human operator

Usage

# Show org tree
./org-manager.sh

# Validate chart (check agent files exist, no circular chains)
./org-manager.sh validate

# Add an agent
./org-manager.sh add writer-agent "Content Writer" orchestrator-agent

# Remove an agent (direct reports reassigned to parent)
./org-manager.sh remove writer-agent

# List all agents
./org-manager.sh list

Validation checks

• All agent names must have a corresponding .claude/agents/<name>.md file
• All Reports To values must be valid agent names or (board)
• No circular reporting chains

Paperclip comparison

Paperclip stores the org chart in a agents database table with a reportsTo foreign key. This implementation uses a markdown table — equivalent structure, no database required, suitable for file-based agent systems running on a single machine.