Enterprise workflow feedback: programmable Manager dispatch, external trigger API, and governance primitives

```markdown
## Background

We are participating in the GOAI Agent Infra track and used AgentTeams/HiClaw as the collaboration base for a real enterprise workflow: distributed PV proposal delivery from electricity bills and project constraints.

The workflow includes OCR/billing parsing, PV sizing, proposal writing, two independent reviewers, arbitration, evidence persistence, cost accounting, and Skill promotion. During integration we found AgentTeams useful as a visible multi-agent collaboration substrate, but we also had to build an external governance/orchestration layer to make the workflow production-style.

This issue is not meant as a criticism of the current product direction. It is a concrete enterprise integration feedback item, with suggestions that may help AgentTeams support production Agent Infra scenarios more directly.

## 1. Programmable Manager dispatch is hard to reach from external systems

### What we observed

In our integration, the Manager-centered collaboration model is conceptually the right entry point, but we could not find a stable programmable dispatch path where an external service can submit a structured task to the Manager and receive a traceable execution result.

We therefore implemented an external driver layer that dispatches work to workers and collects results outside the native Manager path.

### Why this matters

Enterprise systems usually need a service-facing interface:

- submit task from a portal, workflow engine, ticket, alert, or backend API;
- bind the submitted task to a trace/job id;
- dispatch to workers according to role and capability;
- collect outputs and retries;
- persist auditable execution evidence.

Without a documented programmable Manager dispatch path, downstream teams tend to rebuild this orchestration layer outside AgentTeams.

### Suggested improvement

Provide one of the following:

- a documented `Manager.register_tool(...)` / task-dispatch extension point;
- a supported Manager task API, for example `POST /tasks { skill, params } -> task_id / trace_id`;
- an official example showing external backend -> AgentTeams Manager -> Worker rooms -> result collection.

## 2. Console/UI APIs are not enough as production task triggers

### What we observed

The console is useful for visibility, but it is not a stable trigger interface for an external enterprise system. In practice, task dispatch still needs to go through Matrix rooms / DM style interaction, and the integration path is not obvious for backend systems.

### Why this matters

For enterprise workflows, the UI and the execution trigger are usually separated:

- UI/portal submits a task;
- backend validates permissions and parameters;
- AgentTeams executes the multi-agent workflow;
- result and evidence are retrieved by trace id.

If the only reliable trigger path is conversation-style messaging, integrations become fragile and harder to audit.

### Suggested improvement

Document or add a service-facing task trigger contract:

```http
POST /tasks
{
"team": "...",
"skill": "...",
"params": {...},
"metadata": {"external_job_id": "..."}
}
```

Expected outputs:

```json
{
"task_id": "...",
"trace_id": "...",
"status_url": "..."
}
```

This would make AgentTeams much easier to embed into enterprise systems.

## 3. Governance primitives would help AgentTeams move from demo to production

### What we had to add externally

For our GOAI workflow, we added several governance primitives outside AgentTeams:

- `PlanSpec`: a bounded DAG for role-based task execution;
- `PlanGuard`: schema, dependency, role, budget and safety checks before execution;
- `ContextBundle`: versioned context snapshots passed between agents;
- `Trace/Event log`: agent events and evidence persistence;
- `CostGateway`: model usage accounting and budget precheck;
- replay/evaluation gate before promoting a reusable Skill.

### Why this matters

Enterprise workflows need more than multiple agents chatting in a room. They need to answer:

- what plan was executed;
- which agent produced which output;
- which context version each agent used;
- why a plan changed;
- what evidence supports a decision;
- whether a high-risk action was blocked, revised, or approved;
- how much the execution cost;
- whether a Skill is safe to reuse.

### Suggested improvement

It would be valuable if AgentTeams provided lightweight specifications or extension points for:

- task graph / plan schema;
- context snapshot schema;
- lifecycle events / trace event conventions;
- evaluator / reviewer / arbiter roles;
- plan validation hooks;
- Skill contract template including inputs, outputs, trigger condition, dependencies, failure handling, safety boundary, evaluation and versioning.

These do not need to be a heavy built-in workflow engine. Even documented conventions would make ecosystem projects easier to compare, reproduce and integrate.

## Related use case

Our project is a GOAI Agent Infra demo built on top of AgentTeams/HiClaw. Public repository:

https://gitee.com/agent-hub-hu/agentteams-multi-agent-infra

Relevant files in that repository:

- `demo/scripts/plan_spec.py` -- PlanSpec / PlanGuard / dynamic replan / ContextBundle prototype;
- `demo/scripts/real_executor.py` -- production-style multi-agent execution chain;
- `demo/scripts/cost_gateway.py` -- usage events and cost accounting;
- `skills/experience-promote-protocol/` -- evidence-gated Skill promotion protocol;
- `docs/agent_identity.md` -- role and identity mapping;
- `docs/goai_track_mapping.md` -- task input, decomposition, context, tools, validation and evidence mapping.

## Expected outcome

We would love to know whether the AgentTeams maintainers consider these needs aligned with the roadmap. If yes, we are happy to follow up with a smaller PR, such as:

1. a Skill engineering contract template document; or
2. an external-system-driven AgentTeams example; or
3. a minimal trace/context schema proposal.

Thank you for building AgentTeams. The Matrix-room based visibility and human-in-the-loop collaboration model is a strong base; the above feedback comes from trying to push it into a production-like enterprise task workflow.