docs(adrs): draft ADR — agent template store

[tomkis]

Summary

Drafts an ADR proposing an Agent Template Store — an external, configurable catalog of installable agent manifests, fetched by api-server from a Helm-configured URL (default: a public GitHub Pages catalog).

Captures the Slack thread consensus that the platform repo shouldn't keep accumulating demo agents, and that an "agent" is better modeled as a composition (image + repo + skills + connectors + env + schedules + init script) than as a Docker image alone.

• New humr.ai/type=template-source ConfigMap, sister to ADR-030's skill-source.
• Manifest schema with per-field required flags; only image is platform-mandatory, every other field is optional and individually markable as required by the manifest author.
• UI install wizard walks the user through required connectors, env, skills, and schedules before creating the agent.
• Repo-clone-on-first-boot layered on top of ADR-001's image-baked workspace seeding — the dominant authoring pattern becomes humr-base + a repo, image rebuilds reserved for cases that genuinely need them.
• Linked to ADR-030 (skills marketplace), ADR-024 (connector envs), ADR-023 (harness-agnostic base), ADR-001 (workspace seeding), ADR-006 (ConfigMap symmetry), and to issue feature: Per-instance GitHub repo: clone on create, refresh/push/diff from the UI #335 (per-agent repo evolution / push-back) as the lifecycle complement to install.

Status: Proposed — open for review and questions before promotion.

Test plan

• Reviewers confirm the design covers the Slack-thread shape (image / repo / skills / connectors / init script / configs).
• Confirm naming choice (template-source vs other) and v0 scope (single admin-set source, mirroring ADR-030's progression).
• Confirm relationship to feature: Per-instance GitHub repo: clone on create, refresh/push/diff from the UI #335 — the manifest's repo field is the install-time anchor; feature: Per-instance GitHub repo: clone on create, refresh/push/diff from the UI #335 owns the evolve-time mechanics.
• Decide whether to migrate the four chart-shipped templates into the default store now or in a follow-up.

[xjacka]

🛡️ Humr — Code Review

PR #348: docs(adrs): draft ADR — agent template store

Author: tomkis | Branch: docs/adr-agent-store → main | Changes: +208 −0 (2 files)

Summary

Adds a DRAFT ADR proposing an external Agent Template Store — a configurable catalog of agent manifests (image, repo, skills, connectors, env, schedules) that users can browse and install via a wizard-driven UI. The ADR is a sister concept to ADR-030's skill-source, introducing humr.ai/type=template-source ConfigMaps, a manifest schema, install wizard, and Helm chart migration away from hardcoded chart templates.

Findings

• 🟡 Warning — Security: The v0 trust model relies solely on the install wizard as the trust gate, but the document doesn't specify whether admin approval is required for individual template installs or only for adding template-sources. Any user who can reach a configured store URL could install a template that clones arbitrary code into the agent's PVC and requests high-privilege connectors. The document acknowledges signing is deferred but doesn't articulate a minimum privilege model for "who can install from the store." (docs/adrs/DRAFT-agent-store.md §Phase 0 / Consequences)
• 🟡 Warning — Architecture: image.ref is declared the only platform-mandatory field, yet the recommended authoring path is "humr-base-derived + repo." Omitting an explicit image.ref fails manifest validation — a sensible default (e.g., humr-base) could be inferred and would reduce friction for the common case, better aligning with the stated goal of "no Dockerfile, no image build." (docs/adrs/DRAFT-agent-store.md §3 Field rules)
• 🟡 Warning — Architecture: Phase 0 references humr.kagenti.io/templates/index.json as the default store, but the Non-goals explicitly state "no Humr-hosted marketplace service." It's unclear whether humr.kagenti.io is a GitHub Pages domain or a newly hosted service — if the latter, it contradicts the stated non-goal and introduces new operational responsibility. (docs/adrs/DRAFT-agent-store.md §Phase 0 — Default store seed)
• 🟢 Suggestion — Architecture: The init resolution order is defined ("repo file beats manifest field") but recovery behavior when repo cloning fails before the init step is unspecified. RepoCloneFailed is mentioned as a status but the restart policy, partial state cleanup, and user-visible recovery path are left open — worth closing for a PVC-touching first-boot operation. (docs/adrs/DRAFT-agent-store.md §3 init / §Phase 0 Agent-runtime)
• 🟢 Suggestion — Maintainability: Both modified files are missing a trailing newline (\ No newline at end of file in the diff). POSIX-compliant text files require this; most linters and editors will flag it. (docs/adrs/DRAFT-agent-store.md:207, docs/adrs/index.md:48)
• ✅ Looks good: ADR structure is thorough — context, decision, alternatives, consequences, phases, and non-goals are clearly articulated and consistent with the platform's ConfigMap-centric resource model (ADR-006, ADR-023, ADR-024, ADR-030).
• ✅ Looks good: Keeping template-source as a sister type to skill-source (rather than overloading one type) is architecturally sound and avoids semantic confusion in the controller layer.
• ✅ Looks good: Per-field required flags in the manifest schema are a clean design that enables the install wizard to distinguish blockers from optional configuration without ad-hoc UI logic.

Verdict

COMMENT — The ADR is well-reasoned and comprehensively covers the design space, but has notable gaps: the v0 security trust model needs a minimum privilege model for who can install templates, image.ref should consider a default to reduce friction, and the humr.kagenti.io reference needs clarification against the non-hosted-service non-goal.

---

Review by Humr · automated code guardian