Activity

1. johnnyhuy

   self-assigned this

   on Apr 21, 2026
2. johnnyhuy commented on Aug 17, 2026

   

   johnnyhuy

   on Aug 17, 2026

   ContributorAuthor

   More actions

   PRD #88 — Reusable Software Templates (incl. AI Hub / Answer Engine)

   Problem Statement

   The showcase currently ships four software templates (examples/templates/):

   • github-blank-repo — bare GitHub repo bootstrap with a catalog-info.yaml.
   • github-pull-request-docs — TechDocs site published via PR into an existing repo.
   • gitlab-blank-repo — bare GitLab repo bootstrap.
   • gitlab-merge-request — TechDocs site published via MR into an existing repo.

   These cover only the GitHub/GitLab repo-creation slice of "what would I scaffold here?". They are:

   1. Duplicative. Two near-identical pairs (GitHub vs GitLab) where the structure is the same; only the publish action differs.
   2. Narrow. No patterns for: AI-native services, agent/answer-engine workers, RAG indexers, MCP servers, observability backends, or event-driven services. The April 2026 meeting notes flag recurring demand for these.
   3. Disconnected from the demo. Templates don't reference the rest of the portal (TechDocs entity, scorecard, pulse-check) so a user scaffolding a new repo doesn't see the full loop.
   4. Hidden behind scaffolder UX. ScaffolderPage lists them with the Recommended group filter; the homepage "Popular Templates" panel reads from kind: template entities. No editorial curation.

   The result: someone evaluating the showcase for "what would I build here?" sees four trivial repo bootstraps and concludes the platform doesn't know about modern AI-native repo patterns.

   Solution

   Curate a template inventory organised around three families, ship the missing templates, and surface the curated set both on the homepage and the scaffolder page. The three families:

   1. Repo bootstrap (existing) — keep github-blank-repo + gitlab-blank-repo; add a single canonical cross-provider version driven by the publisher action.
   2. Docs site (existing) — keep github-pull-request-docs + gitlab-merge-request; consolidate into one template per provider.
   3. AI-native service (new) — add a starter set of templates that codify the "AI Hub / answer engine" patterns referenced in the April 2026 meeting notes. Until those notes are pasted into context, this PRD proposes a placeholder structure with named template slots; concrete steps require user input on what "AI Hub" and "answer engine" mean here.

   Template inventory (proposed):

   Slot	Template name	Purpose	Source / pattern
   1	github-blank-repo (existing)	Bare GitHub repo + catalog-info	keep
   2	gitlab-blank-repo (existing)	Bare GitLab repo + catalog-info	keep
   3	ai-hub-service (new)	Skeleton for an AI Hub service	TBD — fill from meeting notes
   4	answer-engine-worker (new)	Worker that backs the answer engine	TBD — fill from meeting notes
   5	mcp-server (new)	Model Context Protocol server skeleton	derive from existing github-blank-repo shape
   6	techdocs-site (refactor of existing two)	TechDocs site published via PR/MR	consolidate

   Exact slots 3–5 are placeholder names pending the April 2026 meeting notes. If those notes clarify that "AI Hub" and "answer engine" are the only two AI-native patterns needed, drop mcp-server and keep the inventory at 5.

   User Stories

   1. As a developer evaluating the showcase, I want to see a curated list of templates grouped by purpose (Repo, Docs, AI-native), so that I can quickly tell what the portal is good at scaffolding.
   2. As a developer, I want a "Recommended" filter group on the scaffolder page that highlights templates tagged recommended, so that I can find good starting points without scrolling.
   3. As a developer building an AI-native service, I want a template that scaffolds an "AI Hub"-style service, so that I don't start from a blank repo.
   4. As a developer building an answer engine, I want a template that scaffolds an answer-engine worker (queue consumer + indexer + API), so that the canonical pattern is reusable.
   5. As a developer, I want every template to register itself in the catalog, so that the new service shows up immediately in the homepage "Catalog Highlights" panel.
   6. As a developer, I want every template to ship with a TechDocs site (mkdocs.yml + index.md), so that documentation is opt-out, not opt-in.
   7. As a developer, I want templates to use a consistent parameter schema (owner, repoUrl, name), so that I don't have to re-learn the form for each one.
   8. As a portal admin, I want to add/remove templates by adding/removing a folder under examples/templates/ and registering a Template entity in examples/all.yaml, so that template curation doesn't require code changes to the frontend.
   9. As a portal admin, I want to retire the duplicate GitLab docs-site template by routing its name to the consolidated one, so that the scaffolder UI isn't cluttered.
   10. As a developer, I want a "template catalogue" page on the portal that lists templates grouped by family with descriptions, so that I can browse before committing.
   11. As a developer, I want the homepage "Popular Templates" panel to show only recommended-tagged templates, so that I see the curated set, not every template.
   12. As a portal admin, I want each template to have a unique icon and color in the scaffolder and homepage cards, so that the catalogue is visually scannable.

   Implementation Decisions

   • Templates live as files under examples/templates/<template-name>/{template.yaml,template/}. The scaffolder backend reads them via the local-filesystem location configured in app-config.yaml (already configured for examples/). No change to scaffolder wiring.
   • Template entity registration: each template must have a corresponding kind: Template entry registered in the catalog. Either as a file under examples/templates/<template-name>/catalog-info.yaml, or as an inline entry in examples/all.yaml. Verify the existing wiring before deciding which.
   • Tagging convention: every template gets tags: [recommended] for the homepage "Popular Templates" panel, plus family tags: family:repo, family:docs, family:ai-native, provider:github, provider:gitlab. The homepage filter reads family + recommended.
   • AI-native templates (slots 3–5): build one at a time as vertical slices. Each template = template.yaml + template/ skeleton + a docs/ site. Skeleton content (Dockerfile, package.json, README, mkdocs.yml, basic service code) needs user input from the April 2026 notes.
   • Consolidation of docs-site templates: keep the GitHub and GitLab versions but rename to techdocs-site-github and techdocs-site-gitlab (or similar) so the scaffolder UI groups them. Old names are deprecated but kept as aliases for one release.
   • Homepage "Popular Templates" panel: extend the existing panel to read the family tag and render a small family chip on each card. Also surface a "See all templates" link that goes to /self-service?filters[tags]=recommended (verify the scaffolder URL filter syntax).
   • New "Template catalogue" page: optional for this PRD; can be deferred to a follow-up. The Scaffolder page (/self-service) already groups templates by tags, so the catalogue page is a quality-of-life add, not a blocker.
   • No new scaffolder actions required — fetch:template, publish:github, publish:gitlab, publish:github:pull-request, publish:gitlab:merge-request, catalog:register already exist and are wired in the backend.
   • Permissions: every template respects the existing developer group RBAC (per permission-backend-module-default). No template-restriction changes.
   • No new frontend dependencies beyond what's already imported in the homepage + scaffolder pages.

   Testing Decisions

   • What makes a good test: assert the scaffolder page renders the new templates, the homepage "Popular Templates" panel filters to recommended+family, and the catalogue YAMLs are valid (apiVersion, kind, metadata.name, metadata.tags all present).
   • Modules to test:
     • Template YAML validity — a smoke test that examples/templates/*/template.yaml parses and has the required fields.
     • Homepage filter — unit/integration test on the homepage's filter logic.
     • Scaffolder registration — manual smoke (scaffold a test template via the UI).
   • Prior art: examples/templates/github-blank-repo/template.yaml is the canonical shape; new templates must match. Use it as the reference for parameter schema, step shape, and output.links/output.text.
   • Manual QA:
     • Run yarn workspace backend start and visit /self-service — all templates listed, grouped by tag.
     • Visit / — "Popular Templates" shows 4 recommended templates.
     • Scaffold github-blank-repo end-to-end — repo appears in GitHub, entity appears in catalog.
     • For each new AI-native template, confirm the template/ skeleton is a working starting point (lint clean, builds).

   Out of Scope

   • Building the AI Hub / answer engine service code itself — templates scaffold the skeleton only.
   • MCP server runtime implementation (template only).
   • Hosting/infra provisioning beyond what publish:github / publish:gitlab already do.
   • Localisation of template descriptions.
   • Authoring tools for non-developers to create templates.
   • Replacing or upgrading @backstage/plugin-scaffolder — already on latest in the codebase (verify).

   Further Notes

   • Hard blocker on AI-native templates: slots 3–5 cannot be specified until the April 2026 meeting notes are pasted into context (Meetings/2026-04-20 - Leong Chiew build manifest rollout, Velo priorities, and AI native repo patterns.md, Notes/2026-04-17 - GBP Infra Working Session - ECR Baseline and AI Enablement.md). The PRD structure assumes a single canonical "AI Hub service" pattern + a single "answer engine worker" pattern; if the notes say otherwise, revise.
   • Related open issue: Curate plugin showcase for templates GitHub and answer engine #86 (Curate plugin showcase for templates GitHub and answer engine) appears adjacent. Verify whether Curate plugin showcase for templates GitHub and answer engine #86 is meant to be merged into Package reusable software templates and starter structures #88 or kept separate before implementing.
   • The four existing templates share enough DNA that a future refactor (out of scope here) could collapse them to one template per (publisher × skeleton) matrix. For now, leave them as-is to avoid scope creep.
   • Land after PR fix: GitHub theme and catalog view padding gaps #91 (theme/padding fix) so the homepage and scaffolder pages inherit the fixed Grid spacing and the GitHub theme component overrides.
3. johnnyhuy

   added

   enhancementNew feature or requestNew feature or request

   on Aug 17, 2026
4. johnnyhuy

   added 2 commits that reference this issue on Aug 18, 2026

   feat: homepage onboarding flow and AI-native software templates

   ...

   8e0ecab

   feat: homepage onboarding flow and AI-native software templates (#96)

   ...

   5321b9b
5. johnnyhuy

   closed this as completedin #96on Aug 24, 2026