9d24dc5c41
Session 4 step 18 — agent role/reports-to hierarchy with tree/validate/ add/remove/list commands, circular chain detection via python3. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
62 lines
1.8 KiB
Markdown
62 lines
1.8 KiB
Markdown
# 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.
|