docs: global architecture context for Dynamic Team Mode (RFC-0055)

[Million-mo]

docs: global architecture context for Dynamic Team Mode (RFC-0055)

Purpose

This PR does not change any code. It adds global architecture documentation so that the design intent behind Dynamic Team Mode (RFC-0055) and the surrounding AgentPool architecture can be reviewed as a coherent whole, not just through scattered code PRs and discussion comments.

Related:

• GitHub Discussion Team Agent 架构设计: Lead-Worker + Peer 通信 + 共享 Blackboard #160 (Team Agent 架构设计)
• RFC-0055: Dynamic Team Mode
• Issue Session 管理技术债：存储双路径、状态机断裂、创建/关闭路径碎片化 #170 (session-management technical debt)

What is added

Document	What it covers
docs/architecture/README.md	How to read this documentation branch
docs/architecture/01-vision-and-philosophy.md	Harness vs. Framework, scope, long-term vision
docs/architecture/02-system-overview.md	Global architecture diagram and component map
docs/architecture/03-problem-space.md	Problems Dynamic Team Mode solves and evidence
docs/architecture/04-constraints-and-principles.md	Hard constraints and design principles
docs/architecture/05-framework-comparison.md	Qwen Code, OMO, Hermes, OpenCode, Zed, CrewAI, AutoGen comparison
docs/architecture/06-rfc-roadmap.md	Existing RFCs, dependencies, and phase plan
docs/architecture/06-decisions/DDR-001-why-dynamic-team-mode.md	Decision record: why we chose this approach
docs/rfcs/draft/RFC-0055-dynamic-team-mode.md	Synced from feat/dynamic-team-mode
docs/team-mode/RFC-0055-design-notes.md	Links RFC-0055 to local code and issue #170

Why this matters

The current RFC and implementation are spread across feat/dynamic-team-mode and discussion comments. This branch consolidates the reasoning so that reviewers can challenge the architecture before more implementation PRs are merged.

Review focus

• Is the problem statement in 03-problem-space.md accurate?
• Are the constraints in 04-constraints-and-principles.md acceptable?
• Does the framework comparison in 05-framework-comparison.md fairly represent each option?
• Are the RFC dependencies in 06-rfc-roadmap.md correct?
• Is issue Session 管理技术债：存储双路径、状态机断裂、创建/关闭路径碎片化 #170 correctly identified as a prerequisite in RFC-0055-design-notes.md?

Status

Draft. Ready for architectural review and discussion.

[gemini-code-assist]

Code Review

This pull request introduces comprehensive global architecture documentation for AgentPool, including its design philosophy, system overview, problem space, and a detailed draft for RFC-0055 (Dynamic Team Mode). The review feedback correctly identifies two critical issues in the RFC-0055 draft code: a missing ctx parameter in the get_tools method signature causing a NameError, and incorrect API usage of SessionPool.create_session regarding its parameters and return type. Both comments provide highly actionable code suggestions to resolve these issues.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The get_tools method uses ctx (e.g., ctx.host.session_pool and ctx.session.metadata), but ctx is not defined in the method's signature or scope. This will result in a NameError at runtime. To fix this, ctx: AgentContext should be added as a parameter to the get_tools method.

Suggested change

	async def get_tools(self) -> Sequence[Tool]:
	# Tools access ctx via PydanticAI's RunContext[AgentContext] at
	# execution time. The toolset is constructed at capability init time
	# with the config; team_id and base_dir are resolved per-operation
	# from ctx.session.metadata and ctx.team_mode_config.
	session_pool = ctx.host.session_pool
	if session_pool is None:
	return [] # standalone mode — no team tools
	team_id = ctx.session.metadata.get("team_id")
	if team_id is None:
	return []
	async def get_tools(self, ctx: AgentContext) -> Sequence[Tool]:
	# Tools access ctx via PydanticAI's RunContext[AgentContext] at
	# execution time. The toolset is constructed at capability init time
	# with the config; team_id and base_dir are resolved per-operation
	# from ctx.session.metadata and ctx.team_mode_config.
	session_pool = ctx.host.session_pool
	if session_pool is None:
	return [] # standalone mode — no team tools
	team_id = ctx.session.metadata.get("team_id")
	if team_id is None:
	return []

[gemini-code-assist]

There are two correctness issues in this block:

1. SessionPool.create_session requires session_id as its first parameter, but it is omitted here. This will raise a TypeError at runtime.
2. create_session returns a SessionState object, not a string ID. Assigning it to child_session_id and passing it directly to send_message and register_member will cause type mismatches.

To fix these, we should generate a unique session_id (e.g., child_sid), pass it to create_session, and then use child_session.session_id for subsequent calls.

Suggested change

	child_session_id = await session_pool.create_session(
	agent_name=agent_name,
	parent_session_id=parent_session_id,
	team_id=team_id,
	team_role="member",
	team_member_name=member_name,
	)
	# Render the protocol template for this member
	protocol_prompt = config.protocol_template.format(
	team_name=name,
	role="member",
	member_name=member_name,
	)
	# protocol_prompt is the rendered protocol_template with variables
	# (team_name, role, member_name) substituted.
	# Start agent with protocol prompt via send_message (RFC-0054 API)
	await session_pool.send_message(child_session_id, protocol_prompt, mode=DeliveryMode.QUEUE)
	state.register_member(member_name, child_session_id)
	child_sid = str(uuid4())
	child_session = await session_pool.create_session(
	session_id=child_sid,
	agent_name=agent_name,
	parent_session_id=parent_session_id,
	team_id=team_id,
	team_role="member",
	team_member_name=member_name,
	)
	# Render the protocol template for this member
	protocol_prompt = config.protocol_template.format(
	team_name=name,
	role="member",
	member_name=member_name,
	)
	# protocol_prompt is the rendered protocol_template with variables
	# (team_name, role, member_name) substituted.
	# Start agent with protocol prompt via send_message (RFC-0054 API)
	await session_pool.send_message(child_session.session_id, protocol_prompt, mode=DeliveryMode.QUEUE)
	state.register_member(member_name, child_session.session_id)