feat: agent hierarchy — templates, org chart, role@project naming

[aterrylu]

Summary

• Agent templates — reusable blueprints at ~/.autonomos/templates/*.json for defining agent roles (system prompt, capabilities, model). Created via create_template MCP tool or by dropping a JSON file. Marketplace-ready individual file model.
• Org chart — hierarchy metadata (template, manager, project) stored on persisted sessions. set_manager and get_org_chart MCP tools let agents or humans configure relationships at runtime. Tree derived from manager references.
• Base context rewrite — every spawned agent gets identity, communication, environment, and lifecycle context. Tool list interpolated from shared MCP_INSTRUCTIONS (single source of truth).

Architecture decisions

graph TD
    T[~/.autonomos/templates/*.json] -->|blueprint| S[create_agent]
    S -->|spawns| P[sessions.json]
    P -->|metadata| O[get_org_chart]
    M[set_manager] -->|updates| P
    
    style T fill:#2d5a27
    style P fill:#1a3a5c
    style O fill:#5a2d27

Loading

• No per-agent config folders — sessions ARE agents. Hierarchy is metadata on persisted sessions, not a separate registry. Validated by industry research (no coding agent platform uses persistent agent registries).
• Templates define types, not instances — matches Overstory/Citadel pattern. Individual files for marketplace distribution.
• Hierarchy emerges organically — no deploy_org tool. CEO agent or human uses set_manager after spawning.
• Vertical feature ownership — agents own feature slices (Dashboard@autonomOS, Agentic@autonomOS), not horizontal layers (Frontend, Backend).

New MCP tools

Tool	Description
create_template	Create a reusable agent template on disk
list_templates	List available templates
set_manager	Set an agent's manager in the org chart
get_org_chart	View the organization hierarchy tree

New REST endpoints

Endpoint	Method	Description
/api/templates	GET	List all templates
/api/templates	POST	Create a template
/api/org	GET	Get org chart tree
/api/org/manager	PUT	Set agent's manager

Files changed

Area	Files	Changes
Core types	agent.ts, provider.ts, index.ts	AgentTemplate type, SpawnOptions hierarchy fields
Templates	templates.ts (new)	Template loader with path traversal protection
Org chart	orgChart.ts (new), hierarchy.ts (new)	Shared org chart builder, REST routes
MCP	tools.ts, mcp.ts	4 new tool definitions + handlers
Sessions	persisted.ts, sessions.ts, routes/sessions.ts	Hierarchy fields on PersistedSession, BASE_CONTEXT rewrite
Channel server	index.ts, dist.mjs	New tool handlers via HTTP API, serverFetch helper
Tests	mcp-tools.test.ts	Updated for 8 tools
Docs	CLAUDE.md, RESEARCH.md	Templates, hierarchy, base context documentation
Research	singleton-agent-pattern.md, persistent-agent-identity.md	Industry research on agent persistence models

Test plan

• All 10 MCP tool tests pass
• Biome lint clean (43 files)
• Server startup test passes
• Deployed to forge and tested end-to-end:
  • list_agents() — shows all active agents
  • get_org_chart() — shows hierarchy tree with manager relationships
  • list_templates() — empty initially, populated after create
  • create_template() — creates template file on disk
  • set_manager() — updates hierarchy, reflected in org chart
  • send() — inter-agent messaging works with hierarchy
  • TeamLead confirmed org chart visible from subordinate agent

🤖 Generated with Claude Code

[nox-0x]

🟡 Warning

Problem: ${MCP_INSTRUCTIONS} in the BASE_CONTEXT template literal coerces the array to a string via .toString(), which joins elements with commas — not newlines.

Why it matters: Every spawned agent gets a system prompt where the tool list reads as one run-on comma-separated line: "You are running inside autonomOS — an agent orchestration platform.,,Available tools:,- send(to, message): Send messages via URI...,". The tool documentation is still technically present, but it is much harder for the model to parse as structured instructions.

Suggested fix:

// Join with newlines before interpolating
${MCP_INSTRUCTIONS.join("\n")}

Or define the constant as a pre-joined string:

// In mcp/tools.ts
export const MCP_INSTRUCTIONS_TEXT = MCP_INSTRUCTIONS.join("\n");

// In sessions.ts
${MCP_INSTRUCTIONS_TEXT}