feat(templates): add org-chart template (Paperclip pattern)

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>
This commit is contained in:
Kjell Tore Guttormsen 2026-04-12 06:55:33 +02:00
commit 9d24dc5c41
3 changed files with 369 additions and 0 deletions

View file

@ -0,0 +1,62 @@
# 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.