Agent System Unification - Design and Implementation Plans

[ULookup]

Summary

This PR contains the design spec and implementation plans for unifying Merak's agent system, following Codex's subagent architecture as the primary reference. No code changes yet - this is a planning PR for review and alignment before execution.

Background

The prior analysis (2026-07-13-pipeline-vs-agent-conflict-analysis.md, included in this PR) identified 5 parallel agent invocation paths (3 broken), NullRunControl used in 3 places, phase_allowed_tools declared but not enforced, auto_advance removing Agent judgment, AgentKind enum hardcoded with a 70-line switch-case, and merak_core.md describing wrong (programming) agents. The core conflict: Pipeline is a declarative state machine; Agent is autonomous. They cannot coexist cleanly.

Decision: Delete Pipeline entirely. Make Agent capability the core. Follow Codex's spawn_agent / wait_agent / send_input / close_agent API.

What's in This PR

1. Design Spec

docs/superpowers/specs/2026-07-13-agent-system-unification-design.md

9 design decisions (MD+YAML format, three-layer API, fully dynamic taxonomy, config-driven can_spawn, real RunControl, ephemeral spawn + persistent state, selective context inheritance, phased hard cutover). Includes full god.md and writer.md examples with English prompts following four-block structure (Identity / Capabilities / Constraints / Format).

2. Phase 1 Plan - Foundation (7 tasks)

docs/superpowers/plans/2026-07-13-agent-system-unification-phase1.md

New libs/agent_spawner/ library: AgentRegistry (MD+YAML loader), EventBus, real Control (replaces NullRunControl), AgentSpawner (spawn/wait/send/close + depth guard + permission check), 9 agent definition MD files, integration tests. Old system untouched.

3. Phase 2 Plan - Switch (8 tasks)

docs/superpowers/plans/2026-07-13-agent-system-unification-phase2.md

Wire new system into the real stack: per-instance ToolRegistry builder, real AgentLoop integration, 5 LLM-callable tools (spawn_agent / wait_agent / send_input / close_agent / list_agents), 8 HTTP endpoints under /sessions/:sid/agents/*, merak_core.md rewrite for worldbuilding agents, RuntimeService migration, WebUI (AgentTree + SSE + ApprovalDialog), integration tests. Old code remains but is not called.

4. Phase 3 Plan - Cleanup (10 tasks)

docs/superpowers/plans/2026-07-13-agent-system-unification-phase3.md

Delete all legacy code: PipelineManager + pipeline.cpp + config, AgentKind enum + to_string, worldbuilding_tools.cpp switch-case + DelegateToWriterTool, AgentTool, SubAgentRunner, NullRunControl class, pipeline injection in runtime_service.cpp / compositor.cpp / HTTP layer, obsolete tests, WebUI phase display. Full regression with dual-compiler build + grep verification (zero references to PipelineManager / AgentKind / NullRunControl / SubAgentRunner / phase_allowed_tools / auto_advance).

Key Design Decisions

#	Decision	Choice
1	MCP scope	Keep MCP, not in this refactoring
2	Agent definition format	MD + YAML frontmatter (better for long-form Chinese literary prompts than TOML)
3	API architecture	Three-layer: C++ core / LLM tools / HTTP endpoints
4	Agent taxonomy	Fully dynamic, no enum (add agent = add MD file, zero code changes)
5	Spawn hierarchy	Config-driven can_spawn, max_depth=3 (God > Writer > Individual)
6	RunControl transparency	Parent sees result only; WebUI sees all events via SSE
7	Agent lifecycle	Ephemeral spawn + persistent state (diary, CharacterCard, VoiceFingerprint in DB)
8	Context inheritance	Selective: world + KG + session, not parent history/tools
9	Transition strategy	Phased hard cutover (3 phases), end state has zero legacy code

Agent Prompt Guidelines

Agent system prompts (config/agents/*.md body) are written in English (frontier LLMs perform better with English instruction-following), following four-block structure: Identity -> Capabilities -> Constraints -> Format. Agents are instructed to respond in Chinese (the project's target language is Chinese novels). This is documented in the spec's "Prompt Best Practices Applied" section.

What's NOT in This PR

• No C++ code changes
• No WebUI code changes
• No config file changes (beyond the new config/agents/*.md definitions, which are Phase 1)
• No test changes

Execution happens in 3 subsequent PRs (one per phase), each independently deliverable and testable.

Review Checklist

• Design spec: Are the 9 design decisions sound?
• Phase 1: Is the AgentSpawner API correct? Are the 9 agent definitions appropriate?
• Phase 2: Is the migration path safe? Are the HTTP endpoints well-scoped?
• Phase 3: Is the deletion checklist complete? Any missed references?
• Prompt quality: Do the god.md / writer.md examples follow best practices?

Next Steps

After review and approval, execution can proceed via:

1. Subagent-Driven (recommended) - fresh subagent per task, review between tasks
2. Inline Execution - batch execution with checkpoints

Each phase produces a separate PR. Phase 2 PR depends on Phase 1 PR merging. Phase 3 PR depends on Phase 2 PR merging.