Skip to content

feat(agents): Move agent-template intelligence from the card prompt into the build-an-agent skill - #5188

Merged
mmabrouk merged 3 commits into
big-agentsfrom
docs/agent-templates-plan
Jul 10, 2026
Merged

feat(agents): Move agent-template intelligence from the card prompt into the build-an-agent skill#5188
mmabrouk merged 3 commits into
big-agentsfrom
docs/agent-templates-plan

Conversation

@mmabrouk

@mmabrouk mmabrouk commented Jul 9, 2026

Copy link
Copy Markdown
Member

Context

The agent home page shows a strip of template cards. Clicking one opens a builder agent
seeded with a single outcome sentence, like "Create an agent that turns merged pull requests
into clean release notes and publishes them to our docs page." That sentence describes the
result but never says how to reach it. The builder (a Sonnet-class model running the
build-an-agent skill) had no playbook for a changelog writer, so it guessed: it asked the
user questions they could not answer, wired read tools but never the write tool that does the
real work, or started committing on wrong priors. The prompt was the wrong place for the
per-use-case intelligence.

This PR moves that intelligence into the skill. The card prompt shrinks to a pointer, and the
depth lives in a playbook the builder reads in full once it recognizes the use case.

Changes

Four parts move together.

Skill routing + playbook package. BUILD_AN_AGENT_SKILL
(sdks/python/agenta/sdk/agents/adapters/agenta_builtins.py) gained a three-line routing
paragraph: before the generic build loop, the builder checks
references/agent-templates/index.md for a playbook matching the ask, and follows it when one
matches. The 28 playbooks plus a generated index.md come from a new package,
agent_templates/, one module per category (TemplateEntry(key, name, match, category, body)). The package validates its entries at import time (unique keys, no | or newline in
table cells) and generates the index from the entries, so the router table can never drift
from the files that exist.

Frontend registry. web/oss/src/components/pages/agent-home/assets/templates.ts grew from
6 to 28 templates. TEMPLATE_CATEGORY_ORDER is now
[Engineering, Support, Sales, Knowledge, Ops] (Monitoring folds into Engineering per decision
#1). A new display-only logoSlugs field carries the brand marks a card shows;
requiredIntegrations stays the separate functional connect/tools list. PROVIDERS grew from
6 to 22 entries. seedMessage === builderMessage short seeds ("Build a that ...").
OnboardingConfigPanel caps at 6 cards, TemplateCategoryChips is deleted, and a new
registry-invariant test guards the shape.

Authoring skill. A new repo skill, .agents/skills/write-template-playbooks/ (SKILL.md +
prompting-checklist + a worked example), teaches how to write one playbook file so the catalog
can grow consistently.

Tests. An SDK drift + FE-parity test file and a frontend registry-invariant test (details
below).

Fixes found by live verification. Three bugs surfaced while verifying against the running
stack, two of them pre-existing but fatal to this feature's smoke path:

  • The FE zod schema rejected the static catalog's version: "v1"
    (web/packages/agenta-entities/src/workflow/core/schema.ts), so every __ag__* static
    workflow retrieve was silently discarded and the build kit never loaded through the primary
    path. The schema now parses vN strings to numbers (5 new unit tests).
  • The agent-home create flow auto-sent the first turn before the build-kit overlay fetch
    resolved, so turn 1 always ran without the kit even when the fetch worked. The auto-send now
    waits on a derived overlay-ready atom, with a 10-second escape hatch that sends anyway and
    logs a warning.
  • The newrelic Composio logo slug returned the grey fallback placeholder; the working slug is
    new_relic.

Concrete before/after for the changelog-writer card:

Before, the card's builder message was the only thing the builder received.

Create an agent that turns merged pull requests into clean release notes and publishes them
to our docs page.

After, the seed is a short pointer, and the builder reads the playbook for the depth.

seedMessage:    "Build a changelog writer that turns merged pull requests into release notes and publishes them."
builderMessage: "Build a changelog writer that turns merged pull requests into release notes and publishes them."

On that seed the builder now reads references/agent-templates/index.md, matches the
changelog-writer row, opens references/agent-templates/changelog-writer.md, and follows a
real playbook: discover the GitHub read tools, test_run them through a delta, then ask the
user one request_input form for the repo and where to publish, before it commits.

Scope / risk

No wire or protocol change. The playbook files ride the existing SkillFile mechanism, and
the playground still embeds the build-an-agent skill by slug exactly as before. The agent
config schema is unchanged.

Docs-only surfaces are frozen. The full flag-off surface delete is deferred (decision #4), so
the old card-prompt gallery path stays behind the flag rather than being removed here. The
CHECK integration marks are display-only: logoSlugs renders brand marks and never gates
Create; requiredIntegrations is the only functional connect gate. Analytics vocabulary
changed per decision #6.

Tests / notes

  • SDK drift + FE-parity file
    sdks/python/oss/tests/pytest/unit/agents/test_agenta_builtins_reference_files.py: 16
    passed. It pins the routing paragraph, the generated index, per-playbook file existence, and
    parity between the SDK template keys and the frontend registry.
  • Frontend registry invariants
    web/oss/src/components/pages/agent-home/assets/templates.test.ts via vitest: 17 passed.
  • Live-stack verification (WP4), against the running dev stack: the API serves all 31 skill
    files for __ag__build_an_agent with no restart (dev hot-reload picked up the SDK change);
    the strip renders all 28 cards with exact tab counts (All 28, Engineering 10, Support 4,
    Sales 5, Knowledge 5, Ops 4) and real brand logos; picking a card seeds the composer and
    shows the provenance chip. Unit sweep: 606 passed / 2 pre-existing failures unrelated to this
    change (test_unknown_harness_is_permissive,
    test_run_selection_unknown_permission_falls_back_to_allow_reads — stale against a recent
    capabilities/dtos change, flagged to that lane).
  • End-to-end builder smoke: PASS (after the dev-box FUSE mount was repaired). Clicking the
    Changelog writer card: the auto-sent turn 1 carried the full build kit (17 tools plus the
    build-an-agent skill embed, proving the zod fix and the overlay wait live); the agent read
    SKILL.md, then references/agent-templates/index.md, then changelog-writer.md; its
    first reply was a request_input form (repository, where to publish, how releases work)
    with "Figure it out" / "Use your best judgment" as leading enum options, no free-form
    questioning. One environment caveat: the test project's OpenAI and Anthropic keys are out
    of credit, so the passing run used the subscription (self-managed) credential path; the
    default card experience needs a funded key in the project vault.

Review rounds folded in

  • Codex (gpt-5.5, xhigh) staff review: verdict "direction is right", two blockers, both
    fixed in the follow-up commit. (1) Version round-trip: the FE parses the static catalog's
    "v1" to 1, so a later reference round-trip could send a version the backend's exact
    string compare refuses; the static catalog and the static-ref consistency check now compare
    versions tolerantly ("v1" == "1" == 1) with a parametrized test. (2)
    requiredIntegrations under-declared what playbooks actually need; every card now lists
    exactly the connections its playbook hard-requires (13 rows became two-integration) and the
    rule is documented on the field. Mediums also applied: the first-turn overlay wait resets on
    entity/seed change and arms only when the send is blocked solely on the overlay; the
    FE-parity test bracket-scans the array and fails loudly on a missing marker; template keys
    must be kebab slugs. Deferred with notes in the workspace status: allOf/oneOf requirement
    groups, TemplateEntry/overlayReady renames.
  • CodeRabbit round 1 (8 comments on the plan docs): all replied to and resolved; the two
    that leaked into shipped content are fixed ("press Enter to accept" field descriptions
    replaced with "Recommended: X" / "Leave empty to use X" across all playbooks and the
    authoring skill; support-reply-drafter's card matches its playbook, zendesk). Inventory
    persona and CHECK counts corrected by recount (F=27, J=13, R=14; 7 CHECK / 21 SOLID).
  • Internal review waves: a WP0/WP1 structural review (uniqueness guard, category field,
    parity test, table-injection guard, all applied) and a 27-playbook quality sweep (two medium
    content fixes: a no-match fabrication clause in three knowledge bots, and crm-updater's
    cross-run approval reframed to a single-run approval-gated flow).

How to QA

Prerequisites: the local dev stack (load-env for your edition, then
bash ./hosting/docker-compose/run.sh <flags> --build). No extra setup.

Steps:

  1. Open the agent home page.
  2. Confirm the category strip shows 5 tabs (Engineering, Support, Sales, Knowledge, Ops) and
    28 cards across them.
  3. Pick the "Changelog writer" card.
  4. Confirm the composer is seeded with "Build a changelog writer that turns merged pull
    requests into release notes and publishes them." and a template chip appears.
  5. Send the message.
  6. Watch the builder: it should read references/agent-templates/index.md, then open
    references/agent-templates/changelog-writer.md, then reply with a request_input form
    asking for the repo and where to publish.

Expected result: the builder follows the changelog-writer playbook instead of guessing. It
asks one grounded request_input form and proposes GitHub read tools plus the publish tool,
not a blind commit.

Automated tests:

cd sdks/python && uv run --no-sync python -m pytest oss/tests/pytest/unit/agents/test_agenta_builtins_reference_files.py
cd web/oss && pnpm vitest run src/components/pages/agent-home/assets/templates.test.ts

Edge cases:

  • An old bookmarked flag-off gallery URL still resolves. The flag-off path is frozen, not
    deleted, so that surface renders as before.
  • A template that lists CHECK logos (logoSlugs) shows those brand marks without demanding
    the user connect them. Only requiredIntegrations gates Create.

Design docs: docs/design/agent-workflows/projects/agent-templates/ (see open-questions.md for the six decisions).

https://claude.ai/code/session_016MYos6VaKu8AjhcLFkaMUk

@vercel

vercel Bot commented Jul 9, 2026

Copy link
Copy Markdown

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

Project Deployment Actions Updated (UTC)
agenta-documentation Ready Ready Preview, Comment Jul 10, 2026 12:15am

Request Review

@coderabbitai

coderabbitai Bot commented Jul 9, 2026

Copy link
Copy Markdown

Review Change Stack

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: 368939da-b40c-4131-ace9-4bf0595cbba6

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
📝 Walkthrough

Walkthrough

This PR defines and implements an agent-template playbook system, including authoring guidance, 28 generated playbooks, build-an-agent routing, frontend catalog expansion, overlay-aware onboarding, registry validation, and workflow-version normalization.

Changes

Agent template playbook delivery

Layer / File(s) Summary
Research and playbook contract
docs/design/agent-workflows/projects/agent-templates/*, .agents/skills/write-template-playbooks/*
Documents runtime constraints, canonical playbook structure, prompting rules, worked examples, and authoring guidance.
Template catalog and decisions
docs/design/agent-workflows/projects/agent-templates/template-inventory.md, open-questions.md, plan.md, status.md
Defines 28 templates, category and integration metadata, resolved design choices, work packages, and implementation status.
Generated playbooks and build-an-agent wiring
sdks/python/agenta/sdk/agents/adapters/agent_templates/*, agenta_builtins.py
Adds category playbooks, validates template entries, generates an index and bundled files, and routes matching requests through playbooks before the generic build loop.
Frontend registry and onboarding
web/oss/src/components/pages/agent-home/assets/templates.ts, AgentChatPanel.tsx, OnboardingConfigPanel.tsx
Expands template metadata and provider mappings, separates display logos from required integrations, caps onboarding entries, and gates seed submission on overlay readiness.
Validation and workflow state
web/oss/src/components/pages/agent-home/assets/templates.test.ts, sdks/python/oss/tests/pytest/unit/agents/test_agenta_builtins_reference_files.py, web/packages/agenta-entities/src/workflow/*
Adds registry, SDK/frontend parity, bundled-file, overlay-readiness, and workflow-version normalization tests and logic.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related PRs

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 27.78% which is insufficient. The required threshold is 60.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed It clearly states the main change: moving agent-template logic from card prompts into the build-an-agent skill.
Description check ✅ Passed It accurately describes the PR's scope and changes, including skill routing, template expansion, and related fixes.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/agent-templates-plan

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

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

Home-page template cards seed prompts the builder agent cannot execute. This
workspace plans the fix: per-use-case playbooks shipped as build-an-agent skill
references, short card seeds, a 28-template inventory for the beachhead
personas, a playbook-writing repo skill, and Sonnet verification. Six open
questions gate the frontend and scope decisions.

Claude-Session: https://claude.ai/code/session_016MYos6VaKu8AjhcLFkaMUk
@mmabrouk

mmabrouk commented Jul 9, 2026

Copy link
Copy Markdown
Member Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jul 9, 2026

Copy link
Copy Markdown
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 8


ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: aae5ffc9-831b-4ac0-866c-72b329e3cf34

📥 Commits

Reviewing files that changed from the base of the PR and between ead0700 and 7aa13cc.

📒 Files selected for processing (9)
  • docs/design/agent-workflows/projects/agent-templates/README.md
  • docs/design/agent-workflows/projects/agent-templates/context.md
  • docs/design/agent-workflows/projects/agent-templates/exemplar.md
  • docs/design/agent-workflows/projects/agent-templates/open-questions.md
  • docs/design/agent-workflows/projects/agent-templates/plan.md
  • docs/design/agent-workflows/projects/agent-templates/playbook-spec.md
  • docs/design/agent-workflows/projects/agent-templates/research.md
  • docs/design/agent-workflows/projects/agent-templates/status.md
  • docs/design/agent-workflows/projects/agent-templates/template-inventory.md

Comment thread docs/design/agent-workflows/projects/agent-templates/exemplar.md
Comment thread docs/design/agent-workflows/projects/agent-templates/plan.md
Comment thread docs/design/agent-workflows/projects/agent-templates/plan.md
Comment thread docs/design/agent-workflows/projects/agent-templates/research.md
Comment thread docs/design/agent-workflows/projects/agent-templates/template-inventory.md Outdated
Comment thread docs/design/agent-workflows/projects/agent-templates/template-inventory.md Outdated
- **Measure first.** Ship with five categories, watch which tabs users click, split to six
later. Lowest risk, slowest to the full grouping.

**Recommendation.** Measure first: ship five categories by folding Monitoring into Engineering

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

mmabrouk added a commit that referenced this pull request Jul 9, 2026
…d home catalog

Template cards seeded one-line prompts the builder agent could not execute: it
had no playbook for the use case, so it asked the wrong questions, wired the
wrong tools, and stalled.

- build-an-agent now routes through references/agent-templates/index.md; 28
  per-use-case playbooks ship as generated SkillFiles from the new
  agent_templates package (one module per category, import-time validation,
  drift + FE-parity tests).
- Home registry grows 6 -> 28 templates across 5 categories with short
  'Build a <X> that ...' seeds, a display-only logoSlugs field, PROVIDERS
  6 -> 22, and a registry-invariant test.
- New write-template-playbooks repo skill encodes the playbook format and the
  prompting checklist (unignored via scoped .gitignore negations).
- Fixes found by live verification: static workflow version 'v1' was rejected
  by the FE zod schema (killing every __ag__* retrieve), the first builder
  turn auto-sent before the build-kit overlay resolved, and the newrelic logo
  slug hit the CDN fallback.

Decisions from the PR #5188 review are recorded in the workspace
(open-questions.md); the elicitation default field is tracked in #5190.

Claude-Session: https://claude.ai/code/session_016MYos6VaKu8AjhcLFkaMUk
@mmabrouk mmabrouk changed the title docs(design): plan the agent-templates revamp (skill playbooks + 28-card catalog) feat(agents): Move agent-template intelligence from the card prompt into the build-an-agent skill Jul 9, 2026

@mmabrouk mmabrouk left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Inline review guide from the implementation session: one comment per load-bearing spot (router, package design, exemplar fidelity, display/required split, categories, the two pre-existing FE bugs fixed, gitignore scoping, drift guard). The PR body carries the verification results and the one pending QA cell (builder smoke, blocked on the dev-box FUSE mount another session is fixing).

fewest calls and the least time. A simple no-tool ask is two actions: write better
`instructions.agents_md`, then call `commit_revision`.

Before anything else, check `references/agent-templates/index.md` for a playbook matching the

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review guide: the router. This is the whole change to the skill body: 3 lines inserted after the role statement. It sends the builder to the index before the generic loop and explicitly keeps approval stops. Everything else in the body is untouched; the 29 new reference files are appended to BUILD_AN_AGENT_SKILL.files via build_agent_template_skill_files() further down.

from ...skills import SkillFile


class TemplateEntry(NamedTuple):

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review guide: the package design. One module per category so parallel authors never conflict. The index table is GENERATED from these entries (it cannot drift from the files that exist) and _validate_entries raises at import on duplicate keys or table-breaking characters (reviewer findings H1/L4). Playbook markdown lives in the category modules as string constants, the same pattern as the existing reference constants in agenta_builtins.py.

# The hand-written seed playbook. Body sourced from the workspace exemplar; it layers the
# changelog use case onto the generic build loop and never repeats the loop or the config
# schema. Keep it 1-2 KB: a bigger playbook hides what is relevant from a Sonnet-class model.
_CHANGELOG_WRITER_BODY = """\

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review guide: the exemplar. This changelog-writer body is your hand-written playbook from the plan (exemplar.md), verbatim except the three factual corrections recorded there: test_run explores uncommitted tools via its delta (no commit-and-stop needed), the trigger test is Lightning "Test event" / Play "Run" (not a flask), and request_input has no default field so proposed values ride the field descriptions with an enum-first "figure it out" option (real defaults tracked in #5190). The other 27 playbooks were authored against this exemplar plus the write-template-playbooks skill, then quality-swept (2 medium fixes: a no-match fabrication clause in 3 knowledge bots, and crm-updater's cross-run approval reframed to a single-run approval-gated flow).

* Every integration the use case might touch, shown as card/chip logos. Display-only — it
* never gates Create. `requiredIntegrations` is the separate, functional connect/tools list.
*/
logoSlugs?: string[]

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review guide: the display/required split (decision #5). logoSlugs is display-only brand marks; requiredIntegrations stays the functional connect gate + drawer tools list, narrowed to one SOLID integration per template. CHECK-confidence integrations (datadog, pagerduty, confluence, intercom, gitlab...) appear only in logoSlugs per decision #3, so no card demands an unverified connection. Cards render via templateProviderSlugs(), which prefers logoSlugs and falls back to requiredIntegrations.

export const TEMPLATE_CATEGORY_ORDER = ["Engineering", "Support", "Ops", "Docs"] as const
/** Canonical chip order; only categories present in the templates render. Five visible categories
* (Monitoring folds into Engineering) — see open-questions.md #1; revisit once there's click data. */
export const TEMPLATE_CATEGORY_ORDER = [

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review guide: categories (decision #1). Five visible tabs; Monitoring templates carry category Engineering but sit together under a section comment, so a later six-tab split is a reorder. The SDK keeps Monitoring as its own module. Analytics categories rename freely per decision #6.

// the static catalog serves reserved __ag__* workflows as "vN" (e.g. "v1"). Strip the
// "v" prefix before coercing so both shapes parse to a number instead of NaN.
version: z
.preprocess(

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review guide: pre-existing bug fixed on the FE read path. The static catalog stamps reserved ag* revisions with version "v1"; z.coerce.number() rejected it, the whole response failed validation, and retrieveWorkflowRevision returned null, so EVERY static workflow retrieve (including the build kit) was silently dropped. This preprocess strips the v prefix; output stays number|null|undefined and downstream consumers were checked. 5 new unit tests, including the real static response envelope.

// pending, wait at most 10s for the overlay, then send anyway (kit-less) with a warning.
const [overlayWaitElapsed, setOverlayWaitElapsed] = useState(false)
useEffect(() => {
if (!firstRunPrompt || overlayReady) return

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review guide: the turn-1 race fix. Before: the seed auto-send fired as soon as the model unblocked, while the build-kit overlay fetch was still in flight, so the FIRST builder turn of every card flow ran kit-less (verified live: turn 1 carried tools: [] and no skill). Now the send waits on a derived overlay-ready atom mirroring the overlay atom's own resolution, with a 10s escape hatch that sends anyway and console.warns, so a broken overlay endpoint cannot wedge the send forever.

Comment thread .gitignore
.agents/*
!.agents/skills/
.agents/skills/*
!.agents/skills/write-template-playbooks/

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review guide. The repo ignores all dotdirs (.* above); the three existing repo skills were force-added long ago. These scoped negations re-include only the new write-template-playbooks skill (a dir-by-dir re-include chain, because git cannot re-include inside an excluded dir); everything else under .agents/ and .claude/ stays ignored exactly as before.

_validate_entries([entry])


def test_frontend_and_sdk_template_keys_match():

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review guide: the cross-repo drift guard. Parses the AGENT_TEMPLATES keys out of templates.ts by regex and asserts 1:1 parity with the SDK entries, so a card without a playbook (or a playbook without a card) fails the SDK suite. Skips with a clear message when the web tree is absent (SDK-only distribution).

@mmabrouk

mmabrouk commented Jul 9, 2026

Copy link
Copy Markdown
Member Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jul 9, 2026

Copy link
Copy Markdown
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (2)
web/oss/src/components/pages/agent-home/assets/templates.ts (1)

141-1179: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Suggest extending the registry test to catch toolsSummary/integration-label drift.

templates.test.ts currently only asserts that logoSlugs/requiredIntegrations slugs exist in PROVIDERS, which is why the HubSpot/Gmail mismatch above wasn't caught. A cheap addition — asserting toolsSummary mentions the label of template.requiredIntegrations[0].slug — would guard against future drift as more templates are added.

sdks/python/agenta/sdk/agents/adapters/agent_templates/__init__.py (1)

52-67: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add category to the table-breaking character validation.

_validate_entries checks name and match for | and \n because they render in the index Markdown table, but category also renders in the table at line 95 and is not validated. A future contributor adding a category name containing | or a newline would silently break the generated index.md table. The key field (line 96) has the same exposure, though it's also used as a filename so the risk is doubly relevant.

♻️ Proposed fix
-        for field_name in ("name", "match"):
+        for field_name in ("name", "category", "match"):

If key should also be guarded (it renders in the table and doubles as a filename), add it too:

-        for field_name in ("name", "match"):
+        for field_name in ("key", "name", "category", "match"):

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 6f947c9e-8553-461c-a859-a00f3792bb34

📥 Commits

Reviewing files that changed from the base of the PR and between 7aa13cc and 729bba5.

📒 Files selected for processing (29)
  • .agents/skills/write-template-playbooks/SKILL.md
  • .agents/skills/write-template-playbooks/references/prompting-checklist.md
  • .agents/skills/write-template-playbooks/references/worked-example.md
  • .claude/skills/write-template-playbooks
  • .gitignore
  • docs/design/agent-workflows/documentation/tools.md
  • docs/design/agent-workflows/projects/agent-templates/open-questions.md
  • docs/design/agent-workflows/projects/agent-templates/plan.md
  • docs/design/agent-workflows/projects/agent-templates/playbook-spec.md
  • docs/design/agent-workflows/projects/agent-templates/status.md
  • sdks/python/agenta/sdk/agents/adapters/agent_templates/__init__.py
  • sdks/python/agenta/sdk/agents/adapters/agent_templates/engineering.py
  • sdks/python/agenta/sdk/agents/adapters/agent_templates/knowledge.py
  • sdks/python/agenta/sdk/agents/adapters/agent_templates/monitoring.py
  • sdks/python/agenta/sdk/agents/adapters/agent_templates/ops.py
  • sdks/python/agenta/sdk/agents/adapters/agent_templates/sales.py
  • sdks/python/agenta/sdk/agents/adapters/agent_templates/support.py
  • sdks/python/agenta/sdk/agents/adapters/agenta_builtins.py
  • sdks/python/oss/tests/pytest/unit/agents/test_agenta_builtins_reference_files.py
  • web/oss/src/components/AgentChatSlice/AgentChatPanel.tsx
  • web/oss/src/components/pages/agent-home/PlaygroundOnboarding/OnboardingConfigPanel.tsx
  • web/oss/src/components/pages/agent-home/assets/templates.test.ts
  • web/oss/src/components/pages/agent-home/assets/templates.ts
  • web/oss/src/components/pages/agent-home/components/TemplatesSection/TemplateCategoryChips.tsx
  • web/packages/agenta-entities/src/workflow/core/schema.ts
  • web/packages/agenta-entities/src/workflow/index.ts
  • web/packages/agenta-entities/src/workflow/state/index.ts
  • web/packages/agenta-entities/src/workflow/state/store.ts
  • web/packages/agenta-entities/tests/unit/workflowVersionSchema.test.ts
💤 Files with no reviewable changes (1)
  • web/oss/src/components/pages/agent-home/components/TemplatesSection/TemplateCategoryChips.tsx
✅ Files skipped from review due to trivial changes (5)
  • .claude/skills/write-template-playbooks
  • .agents/skills/write-template-playbooks/SKILL.md
  • docs/design/agent-workflows/projects/agent-templates/playbook-spec.md
  • docs/design/agent-workflows/projects/agent-templates/open-questions.md
  • docs/design/agent-workflows/projects/agent-templates/plan.md
🚧 Files skipped from review as they are similar to previous changes (1)
  • docs/design/agent-workflows/projects/agent-templates/status.md

Comment thread web/oss/src/components/pages/agent-home/assets/templates.ts
mmabrouk added a commit that referenced this pull request Jul 10, 2026
…d home catalog

Template cards seeded one-line prompts the builder agent could not execute: it
had no playbook for the use case, so it asked the wrong questions, wired the
wrong tools, and stalled.

- build-an-agent now routes through references/agent-templates/index.md; 28
  per-use-case playbooks ship as generated SkillFiles from the new
  agent_templates package (one module per category, import-time validation,
  drift + FE-parity tests).
- Home registry grows 6 -> 28 templates across 5 categories with short
  'Build a <X> that ...' seeds, a display-only logoSlugs field, PROVIDERS
  6 -> 22, and a registry-invariant test.
- New write-template-playbooks repo skill encodes the playbook format and the
  prompting checklist (unignored via scoped .gitignore negations).
- Fixes found by live verification: static workflow version 'v1' was rejected
  by the FE zod schema (killing every __ag__* retrieve), the first builder
  turn auto-sent before the build-kit overlay resolved, and the newrelic logo
  slug hit the CDN fallback.

Decisions from the PR #5188 review are recorded in the workspace
(open-questions.md); the elicitation default field is tracked in #5190.

Claude-Session: https://claude.ai/code/session_016MYos6VaKu8AjhcLFkaMUk
@mmabrouk
mmabrouk force-pushed the docs/agent-templates-plan branch from 4627d7b to a4c6dfd Compare July 10, 2026 00:10
mmabrouk added 2 commits July 10, 2026 02:13
…d home catalog

Template cards seeded one-line prompts the builder agent could not execute: it
had no playbook for the use case, so it asked the wrong questions, wired the
wrong tools, and stalled.

- build-an-agent now routes through references/agent-templates/index.md; 28
  per-use-case playbooks ship as generated SkillFiles from the new
  agent_templates package (one module per category, import-time validation,
  drift + FE-parity tests).
- Home registry grows 6 -> 28 templates across 5 categories with short
  'Build a <X> that ...' seeds, a display-only logoSlugs field, PROVIDERS
  6 -> 22, and a registry-invariant test.
- New write-template-playbooks repo skill encodes the playbook format and the
  prompting checklist (unignored via scoped .gitignore negations).
- Fixes found by live verification: static workflow version 'v1' was rejected
  by the FE zod schema (killing every __ag__* retrieve), the first builder
  turn auto-sent before the build-kit overlay resolved, and the newrelic logo
  slug hit the CDN fallback.

Decisions from the PR #5188 review are recorded in the workspace
(open-questions.md); the elicitation default field is tracked in #5190.

Claude-Session: https://claude.ai/code/session_016MYos6VaKu8AjhcLFkaMUk
…ate feature

Codex blockers: static workflow versions now compare tolerantly (v1 == 1 == 1)
in the static catalog and the static-ref consistency check, with a round-trip
test, so an FE that parses 'v1' to 1 can never send back a version the backend
refuses; every card's requiredIntegrations now lists exactly the connections
its playbook hard-requires (13 rows became two-integration), with the rule
documented on the field.

Codex mediums: the first-turn overlay wait resets on entity/seed change and
arms only when the send is blocked solely on the overlay; the FE-parity test
bracket-scans the array body and fails loudly on a missing marker; template
keys must be kebab slugs.

CodeRabbit round: replaced every 'press Enter to accept' field description
(request_input has no prefill) with 'Recommended: X' / 'Leave empty to use X'
across all playbooks and the authoring skill; support-reply-drafter's card
required integration matches its playbook (zendesk); inventory persona and
CHECK counts corrected by recount (F=27 J=13 R=14; 7 CHECK / 21 SOLID).

Claude-Session: https://claude.ai/code/session_016MYos6VaKu8AjhcLFkaMUk
@mmabrouk
mmabrouk force-pushed the docs/agent-templates-plan branch from a4c6dfd to c188226 Compare July 10, 2026 00:13
@mmabrouk
mmabrouk marked this pull request as ready for review July 10, 2026 00:14
@dosubot dosubot Bot added size:XXL This PR changes 1000+ lines, ignoring generated files. Backend documentation Improvements or additions to documentation labels Jul 10, 2026

@mmabrouk mmabrouk left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@mmabrouk
mmabrouk merged commit 41eacd0 into big-agents Jul 10, 2026
17 checks passed
@mmabrouk mmabrouk mentioned this pull request Jul 10, 2026
12 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Backend documentation Improvements or additions to documentation feature Frontend size:XXL This PR changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant