[Feature] First-class agent taxonomy on Agent/AgentBuilder; colocate plan, orchestrator, and prompt factories under agent/agent #478

Summary

Define a first-class taxonomy of agents (core, research, communication, automation, planner/orchestrator, etc.) that all build on the existing Agent / AgentBuilder types in src/openhuman/agent/agent/types.rs. Planning, orchestration, and system-prompt construction for these agents should live alongside that type under src/openhuman/agent/agent/ (with clear submodules), instead of spreading orchestration-only logic across unrelated trees.

User-visible outcome: predictable agent roles, easier testing, and a single place for contributors to see how each agent is built and which prompts it uses.

Problem

Today the runtime Agent struct is well-factored (types, builder, turn, runtime per agent/mod.rs), but multi-agent behavior (archetypes, orchestrator DAG, sub-agent runs) largely lives under src/openhuman/agent/harness/, while prompt assembly is split across prompt.rs (e.g. SystemPromptBuilder, archetype sections) and markdown under agent/prompts/.

That split makes it hard to answer:

• “What agents exist, and how do they differ?”
• “Where is the orchestrator’s plan defined relative to the main Agent?”
• “How do we create prompts per agent kind in one coherent pipeline?”

New roles (e.g. planner-only, evaluator, handoff targets) risk ad hoc wiring instead of extending the same Agent/AgentBuilder foundation.

Solution (optional)

1. Agent kinds / registry — Introduce an enum or registry (e.g. AgentKind) that maps each product role to:

   • AgentBuilder defaults (tools subset, temperature caps, iteration limits where applicable)
   • Prompt recipe (which SystemPromptBuilder sections / archetype markdown files)
   • Optional orchestration profile (participant in DAG vs single-turn primary)

2. Colocate under agent/agent/ — Add focused modules, for example:

   • agent/agent/plan.rs — planning steps / structured plan output types consumed by orchestration
   • agent/agent/orchestrator.rs — topology and handoff rules (migrate or thin-wrap today’s harness/executor + config)
   • agent/agent/prompts.rs (or prompt_factory.rs) — factory that builds SystemPromptBuilder (or equivalent) per AgentKind, reusing existing prompt.rs primitives

   Keep types.rs as the single structural definition of Agent / AgentBuilder; behavior stays in sibling files per existing pattern.

3. Inheritance / composition — Prefer composition: specialized agents are Agent instances built via shared AgentBuilder helpers, not parallel structs, unless a trait boundary is needed for testing (e.g. trait RunnableAgent implemented only by Agent).

4. Migration — Incrementally move orchestrator entrypoints and archetype resolution so openhuman::agent::agent is the public conceptual home; harness can become a thin compatibility layer or be merged.

5. Docs — Update agent/mod.rs file-layout table and docs/ or AGENTS.md to describe agent kinds and prompt wiring.

Acceptance criteria

• Types — All specialized agents remain instances of (or thin wrappers around) Agent / AgentBuilder defined in types.rs; no duplicate “second agent struct” without justification.
• Registry — Documented list of agent kinds with stable names, mapped to prompt sources and tool/memory policies.
• Colocation — Plan and orchestrator logic (or facades) live under src/openhuman/agent/agent/ with module-level docs explaining call graph from turn / RPC entrypoints.
• Prompt creation — A single documented path for “build system prompt for agent kind X” (factory or builder extension), aligned with packaged + optional overlay prompts.
• Tests — Unit or integration tests that at least one secondary kind builds, runs a minimal turn (or dry-run), and loads the expected prompt sections.
• No silent behavior drift — Orchestrator enablement and defaults remain explicit in config; migration notes if RPC or CLI surface changes.

Related

• src/openhuman/agent/agent/types.rs — Agent, AgentBuilder
• src/openhuman/agent/agent/mod.rs — module layout
• src/openhuman/agent/harness/ — current orchestrator / archetypes / subagent runner
• Prompt markdown: src/openhuman/agent/prompts/, SystemPromptBuilder in prompt.rs
• Optional overlap: multi-agent / self-reflection issues if planner agents are added later