Summary

Define a workspace capability discovery convention so agents can discover local, durable capabilities before concluding that a task is impossible.

Problem to solve

OpenClaw already has several primitives that can support this behavior, including bootstrap hooks, before_prompt_build, taskflow, ACP runtimes, skills, and tool policy. However, workspace-specific capabilities are currently documented ad hoc in files such as AGENTS.md, TOOLS.md, or local notes.

That makes capability use inconsistent across sessions. An agent may incorrectly report that it cannot perform a task because it does not know that the workspace has an approved bridge, queue, taskflow, ACP runtime, or documented fallback path.

The goal is not to add a gateway wrapper, proxy, separate daemon, or parallel session/router layer. Gateway should remain the source of truth for sessions, routing, auth, and tool policy.

Proposed solution

Add a documented workspace convention for capability descriptors, for example:

• capabilities/*.md for durable workspace capabilities.
• Optional capabilities/index.md as a short registry.
• Clear guidance that bootstrap or prompt-context mechanisms may surface these descriptors to agents.

Each capability descriptor should include:

• Purpose.
• Supported requests.
• Required tools, commands, queues, or runtimes.
• Safety and approval boundaries.
• Verification steps.
• Fallback behavior.
• A rule for what to inspect before responding "not possible".

This should initially be documentation and convention-level work. A follow-up can evaluate whether bootstrap-extra-files, boot-md, or another existing hook should natively discover capabilities/*.md.

Alternatives considered

• Put all capability details in AGENTS.md: simple, but it grows too large and mixes role policy with operational integration details.
• Put all capability details in TOOLS.md: better than AGENTS.md, but still becomes a large manual index without per-capability structure.
• Add a new gateway-like wrapper/orchestrator: rejected for now because it risks duplicating gateway responsibilities and creating split-brain behavior around sessions, routing, auth, and tool policy.
• Use only plugins: useful for some capabilities, but not every workspace integration needs to become a plugin before agents can discover it.

Impact

Affected:

• Users with local workspace integrations, bridge queues, ACP delegation paths, or taskflow-based automation.
• Agents that need to discover available capabilities at session startup or before declaring a task unsupported.

Severity:

• Medium. It does not block core OpenClaw runtime behavior, but it causes avoidable false negatives and manual re-explanation.

Frequency:

• Recurring for workspaces with custom integrations or multi-agent workflows.

Consequence:

• Extra manual context transfer.
• Agents may miss valid execution paths.
• Durable capabilities are harder to reuse across sessions.

Evidence/examples

Existing OpenClaw primitives that appear relevant:

• bootstrap-extra-files can inject extra workspace bootstrap files during agent bootstrap.
• before_prompt_build hooks can inject dynamic context before model calls.
• Taskflow/task registry can coordinate durable multi-step work.
• ACP runtimes and agent harnesses provide delegation substrates.
• Tool policy and plugin prompt-injection controls already define important safety boundaries.

The requested change is to define a small convention that uses these existing primitives rather than creating a new gateway-adjacent service.

Additional information

Non-goals:

• No separate listener.
• No parallel session store.
• No independent auth layer.
• No shadow tool router.
• No wrapper that mimics gateway behavior.

Potential follow-ups:

• Document how bootstrap-extra-files can include capabilities/*.md.
• Add a small test fixture showing capability descriptors included in startup context.
• Consider a native capability registry only after the convention is validated in real workspaces.