Agenta-AI · mmabrouk · Jun 19, 2026
diff --git a/docs/design/agent-workflows/README.md b/docs/design/agent-workflows/README.md
@@ -1,53 +1,64 @@
-# Agent workflows
-
-This folder documents a proof of concept: running a coding agent as an Agenta workflow.
-
-Agenta runs prompt workflows today (completion, chat, the LLM judge). Each calls a model
-once and returns one answer. An agent is different. It runs a loop, calls tools across many
-turns, and returns a final answer. This PoC adds the agent as a new workflow type behind the
-same `/invoke` contract, traced into the same spans, configured from the same playground.
-
-It proves one specific claim: that the **agent** and the **place it runs** are both config,
-not code. You change a dropdown to swap Pi for Claude Code, or local for a Daytona cloud
-sandbox, and nothing above the seam changes.
-
-## Read in this order
-
-1. **[Architecture](architecture.md)**. How a request flows from the playground to the model
-   and back: the relay of programs, the two containers, and the vocabulary. Start here.
-2. **[Ports and adapters](ports-and-adapters.md)**. The ports that keep the relay swappable:
-   the backend, environment, and harness layers, where they live in the SDK, the wire
-   contract, and how the service picks a backend.
-3. **[Sessions](sessions.md)**. How a multi-turn conversation holds together today (cold
-   replay), and the two paths open to us tomorrow.
-4. **[The Pi adapter](adapters/pi.md)**. The default harness, which traces itself and takes
-   tools natively through a Pi extension.
-5. **[The Claude Code adapter](adapters/claude-code.md)**. The second harness, which proves
-   the swap and is the template for any MCP-capable agent.
-6. **[The Agenta harness](adapters/agenta.md)**. Pi with an opinion: forced skills, forced
-   tools, and a base AGENTS.md preamble the author's instructions are appended to.
-
-## What this PoC includes and defers
-
-It includes the agent workflow behind `/invoke`, two harnesses (Pi and Claude Code), two
-sandboxes (local and Daytona), backend-resolved tools that keep credentials server-side, and
-tracing that nests the agent's run under the caller's span.
-
-It defers the things a production rollout will need: a warm daemon and server-owned session
-storage (see [Sessions](sessions.md)), live streaming to the client over the HTTP edge, the
-multi-tenant filesystem jail for a shared daemon, and registering the agent as a first-class
-backend workflow type with its own builtin URI. Each is called out where it belongs.
-
-The first two of those, streaming and server-owned sessions, have a proposed design:
-[Streaming and sessions](streaming-and-sessions.md) for the rationale and trade-offs, and
-the [Agent protocol RFC](agent-protocol-rfc.md) for the normative spec of the endpoints and
-the wire format. They add a new `POST /messages` endpoint (Vercel-AI-format SSE stream, an
-optional `session_id`, and `UIMessage` inputs) plus a `load-session` endpoint, sitting next
-to the existing `/invoke`, which is unchanged.
-
-## The `scratch/` folder
-
-`scratch/` holds the raw working material from the build: the original work-package folders
-(WP-1 through WP-8), the port redesign notes, the research write-ups, and the proof-of-concept
-spikes. The pages above supersede it. It stays for history and for the running POC code, and
-it is not meant to be read as the design.
+# Agent Workflows
+
+This workspace documents the current agent workflow implementation and the work still
+needed to make it production-ready.
+
+The source of truth is the code listed in [Ground Truth](ground-truth.md). Design pages at
+this level describe the current implementation unless they explicitly say "planned",
+"blocked", or "not implemented". Historical work-package notes and old RFCs live in
+[trash/](trash/).
+
+## Read In This Order
+
+1. [Ground Truth](ground-truth.md): what the current code does, what is wired, and what is
+   still missing.
+2. [Status](status.md): current cleanup state, decisions, blockers, and next steps.
+3. [Meeting Alignment](meeting-alignment.md): where the current work matches the June 18
+   design discussion, where it diverges, and what still needs to be done.
+4. [Architecture](architecture.md): the service, agent runner sidecar, harnesses, and
+   sandboxes.
+5. [Protocol](protocol.md): `/invoke`, `/messages`, `/load-session`, and the runner `/run`
+   wire contract.
+6. [Ports and Adapters](ports-and-adapters.md): the SDK runtime ports, backend adapters,
+   harness adapters, and browser protocol adapter.
+7. [Agent Template](agent-template.md): the intended split between generic agent identity,
+   harness-specific config, and runtime infrastructure.
+8. [Sessions](sessions.md): cold replay, streaming, session ids, and the missing session
+   store.
+9. [Triggers](triggers.md): planned trigger/event integration and the missing Compose.io
+   POC.
+10. [Pi Adapter](adapters/pi.md): Pi-specific tool delivery, prompt layers, tracing, and
+   usage writeback.
+11. [Claude Code Adapter](adapters/claude-code.md): Claude over ACP, MCP tool delivery,
+   permissions, tracing, and usage.
+12. [Agenta Harness](adapters/agenta.md): the experimental Agenta-flavored Pi harness.
+13. [SDK Local Tools](sdk-local-tools/): planned and partly implemented work for standalone
+   SDK tool resolution. This remains blocked by `LocalBackend`.
+14. [PR Stack](pr-stack.md): functional breakpoints for reviewable stacked PRs.
+15. [Implementation Review](implementation-review.md): high-level cleanup risks and PR
+    slicing notes.
+16. [Open Issues](open-issues.md): deferred decisions that need ownership.
+
+## Current State
+
+The agent workflow runs a coding harness as an Agenta workflow. It supports:
+
+- A batch `/invoke` path that returns the final assistant message.
+- An agent-only `/messages` path that accepts Vercel `UIMessage` input and can stream a
+  Vercel UI Message Stream over SSE.
+- A `/load-session` route with the right contract but no durable storage by default.
+- Pi and Claude harnesses through the rivet runner.
+- Pi and the experimental `agenta` harness through the in-process Pi backend.
+- Server-resolved tool specs, code tool execution, callback tools, and MCP plumbing behind
+  a feature flag.
+
+The main missing pieces are durable server-owned sessions, future session snapshot
+interfaces, the agent template/config split, trigger integration, a working standalone
+`LocalBackend`, production Agenta harness content, first-class built-in workflow
+registration, and the final cleanup of historical work-package names in comments and docs.
+
+## Trash
+
+[trash/](trash/) holds old work-package notes, research spikes, and superseded RFCs. It is
+kept for archaeology only. Do not treat it as design truth unless a current page links to a
+specific note as background.
diff --git a/docs/design/agent-workflows/adapters/claude-code.md b/docs/design/agent-workflows/adapters/claude-code.md
@@ -31,7 +31,7 @@ something in particular.
 
 The mechanism is a small stdio MCP server (`tools/mcp-server.ts`) that the daemon launches
 and attaches to the session. Its tool bodies POST back to Agenta's `/tools/call` with the
-same WP-7 envelope the Pi path uses. The resolved specs and the callback endpoint reach the
+same callback-tool envelope the Pi path uses. The resolved specs and the callback endpoint reach the
 MCP server through its environment, so nothing tool-specific is written to a file the agent
 can read. The safety property is identical to Pi's: the provider key and the connection auth
 stay server-side, and the agent only ever asks Agenta to run a named tool.

diff --git a/docs/design/agent-workflows/adapters/pi.md b/docs/design/agent-workflows/adapters/pi.md
@@ -38,7 +38,7 @@ extension reads the resolved tool specs from `AGENTA_TOOL_SPECS` and registers e
 Pi directly through `pi.registerTool`. Pi then sees them as native tools and runs the loop.
 
 Each registered tool's body does one thing: it POSTs the call back to Agenta's `/tools/call`
-with the tool's `callRef` (the WP-7 envelope). The model picks the tool and supplies the
+with the tool's `callRef` (the callback-tool envelope). The model picks the tool and supplies the
 arguments; Agenta runs the actual tool server-side. This is the key safety property: the
 Composio key and the connection auth never enter the sandbox. The agent only ever asks
 Agenta to run a named tool.

diff --git a/docs/design/agent-workflows/agent-template.md b/docs/design/agent-workflows/agent-template.md
@@ -0,0 +1,59 @@
+# Agent Template
+
+The agent template is the portable description of what the agent is. It should not silently
+mix product identity, harness runtime options, and deployment infrastructure.
+
+## Intended Shape
+
+The baseline template is:
+
+- `AGENTS.md` content: the main instructions.
+- Skills: a folder-shaped set of skill files, serialized into a JSON-safe representation.
+- Tools: managed builtin tools, inline code tools, and future MCP tool references.
+- Metadata: name, description, and other product identity fields when the UI needs them.
+
+This mirrors the file-based agent convention used by local coding agents while keeping the
+wire shape JSON-friendly. File bytes can be base64 encoded when plain text is not safe.
+
+## Configuration Layers
+
+| Layer | Examples | Status |
+| --- | --- | --- |
+| Generic agent identity | `AGENTS.md`, skills, tool references, template metadata | Intended long-term template surface. Partly represented today by `agents_md` and tool config. |
+| Harness-specific config | Harness id, model, harness option bags, permission policy | Present today. Permissions are not generic yet. |
+| Runtime infrastructure | Local versus Daytona, runner sidecar URL, filesystem isolation, secret channels | Present as a POC selection in `RunSelection`, but should not become durable agent identity by default. |
+
+The current code still accepts `sandbox` in request config. That is useful for the POC and
+tests, but the long-term template should not require users to encode where the platform is
+deployed.
+
+## Current Implementation
+
+Today the request surface includes:
+
+- `parameters.agent.agents_md`
+- `parameters.agent.model`
+- `parameters.agent.tools`
+- `parameters.agent.mcp_servers`
+- `parameters.agent.harness`
+- `parameters.agent.sandbox`
+- `parameters.agent.permission_policy`
+- harness-specific options such as Pi prompt overrides
+
+The runtime also has forced Agenta policy in `AgentaHarness`, but that content is
+experimental and not a general template system.
+
+## Missing Work
+
+- A first-class persisted template DTO that separates identity from run selection.
+- Skills folder serialization and loading outside forced Agenta harness content.
+- A stable tool contract based on URI, schema, and execution body or delivery reference.
+- Clear UI grouping for generic template fields, harness-specific fields, and runtime
+  infrastructure.
+- Import/export behavior for `AGENTS.md` and skills folders.
+
+## Deferred Work
+
+Hooks, assets, extra code snippets, and a generic permissions overlay are deferred. The POC
+should leave space for them without pretending they are supported.
+