# 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

```bash
# 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.