docs(design): build kit as the reserved static workflow __ag__build_kit

[mmabrouk]

Context

Agents created through the new template-builder and playground-native flows show no build kit and run without its tools, even after commit. The server content was proven healthy; the root cause is delivery: the frontend fetched the kit exclusively as a rider on GET /simple/applications/{id}, keyed by a workflow_id that ephemeral drafts don't have and that onboarding's in-place swap doesn't re-resolve.

The decision (Mahmoud, 2026-07-07)

The build kit becomes a reserved static workflow, __ag__build_kit, in the existing StaticWorkflowCatalog — the same home as __ag__build_an_agent and __ag__request_connection. Two refinements from review: it is just an agent configuration (parameters.agent with tools/skills/sandbox — no new schema flavor; "overlay" is how the playground uses it, not a type), and nothing relocates (the entry goes where the catalog lives; the ops list stays put; overlay.py is absorbed as the kit's content builder).

Delivery: the frontend resolves the slug through the existing workflow-retrieve path, fetches once per project, and merges it onto anything agent-typed (flags.is_agent — drafts and committed agents alike). The per-application rider retires after the FE migrates. Options A (dedicated route — provisionally built, parked unmerged on feat/build-kit-overlay-impl-draft, to be discarded) and B (template-response rider) are superseded; the analysis stays in context.md.

Verified, not assumed

• Nested embeds resolve: reserved slugs return the synthetic catalog revision directly on retrieve, and the full resolver routes workflow refs back through the catalog, so the kit's internal embeds (request-connection, build-an-agent) work on both paths.
• Content equivalence: 16 tools + skill embed + sandbox permissions, byte-comparable to today's overlay output; a unit test pins it.
• Two implementation guards (the only sharp edges): the kit must be excluded from its own reserved-tool-embed iteration (or it embeds itself), and its revision must be built lazily (the builder can't read the catalog mid-construction).
• Merge semantics unchanged: the client merge target is literally parameters.agent — the concrete evidence for the "it's just an agent config" framing.

Why this matters now

This gates flipping NEXT_PUBLIC_AGENT_TEMPLATE_BUILDER to default-on (the last piece of the zero-config new experience; the other two flags shipped in #5121).

https://claude.ai/code/session_01N2djTMgXnpk84EqtugHDJB

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jul 7, 2026 4:13pm

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c7aa2f6d-d355-4584-8d80-11214ce2b0fe

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/build-kit-overlay-delivery

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}