Skip to content

Refactor/restructure factory and quickstart repos - #47

Merged
YosiElias merged 9 commits into
rh-ai-quickstart:mainfrom
YosiElias:refactor/restructure-factory-and-quickstart-repos
Oct 18, 2026
Merged

YosiElias merged 9 commits into
rh-ai-quickstart:mainfrom
YosiElias:refactor/restructure-factory-and-quickstart-repos

Conversation

@YosiElias

@YosiElias YosiElias commented Oct 14, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Restructure the Quickstart Factory and the repositories it produces around a consistent file layout. Each new quickstart starts from the organization template, giving contributors the standard chart/ structure and catalog README skeleton from the start. Predictable paths make factory workflow files easier to find and manage, and reduce the risk of factory artifacts ending up in published quickstarts.

Technical changes

  • Store each quickstart’s factory artifacts under .rhoai-qs/<slug>/.qs-factory/; move shared reports and blog drafts to .reports/ and .blog-drafts/ at the factory root.
  • Keep .rhoai-qs/ dedicated to quickstarts, simplifying slug discovery.
  • Seed new repositories from the organization template during discovery, replace chart placeholders before the initial commit, and have scaffold verify the repository and its origin.
  • Standardize Helm charts under chart/ and update pipeline paths, documentation, and publishing cleanup to match

…dashboard

The checkpoint resolved .tmp/ and .rhoai-qs/<slug>/flow/ against the current
working directory, but skills run from two different places — the factory root
before scaffold, and inside .rhoai-qs/<slug>/ after it. Running it from the
latter produced a nested .rhoai-qs/<slug>/.../.rhoai-qs/<slug>/flow/dashboard.md.
Everything now hangs off FACTORY_ROOT (SCRIPT_DIR.parent.parent).

Emitted links carried a hardcoded ../../../ prefix, which assumed a fixed
dashboard depth and walked out of the tree entirely for a symlinked quickstart.
They are now os.path.relpath'd against the dashboard's own directory, so depth
stops mattering; registry review_guidance drops the prefix and stores
factory-root-relative targets. The banner is an absolute raw.githubusercontent
URL for the same reason.

Behavior-preserving: the dashboard still lands at .rhoai-qs/<slug>/flow/.

Signed-off-by: Yossi Elias <yelias@redhat.com>
…folders

Factory bookkeeping was scattered across five sibling folders at the quickstart
repo root, intermixed with the quickstart's own application code. It now lives
in exactly one folder, .rhoai-qs/<slug>/.qs-factory/, that a single rule can
track, ignore, or delete.

Two invariants come out of this and the rest of the plan leans on them:

  1. Every direct child of .rhoai-qs/ is a quickstart. The cross-cutting
     .rhoai-qs/reports/ and .rhoai-qs/blog-drafts/ folders were documented but
     never created on disk, and pipeline-convention.md already flagged them as
     an unresolved open question. They are gone; factory-side material moves to
     .blog-drafts/ and .reports/ at the factory root. Slug resolution is now a
     plain `ls -1` with no filter step — which also unbreaks
     agent-mesh-for-sw-modernization, a real cloned quickstart with no
     bookkeeping folders at all.
  2. .qs-factory/ has no exceptions — nothing inside it survives ship.

pipeline-convention.md also now states the symlink case explicitly: a slug
folder may be a symlink to a repo elsewhere on disk, which the telco quickstart
already does and the doc previously denied.

ADR.md and ADR-001 Implementation Tasks.md are historical records and keep
their original paths; they get a "superseded, layout only" note instead.

Docs and slug resolution only — the code move lands next.

Signed-off-by: Yossi Elias <yelias@redhat.com>
Applies the convention from the previous commit to the code: the dashboard,
registry output paths, every skill's spec/manifest/PRD/design/report path, and
the in-slug relative forms all gain the .qs-factory/ prefix.

These have to land together. validate-checkpoint.sh compares the last non-empty
lines of every pipeline SKILL.md byte-for-byte against build_expected, which
embeds the dashboard path — so build_expected and the SKILL.md footers must move
in the same commit or the skill-gate job fails on either one alone.

rh-qs-ship is commented out of the registry rather than deleted, following the
rh-qs-security precedent: it is the final step and its cleanup deletes
.qs-factory/ including the dashboard, so it has nothing to checkpoint. Keeping
it commented also exempts it from the CI gate for free — validate-checkpoint.sh
builds its skill list with `yq '.skills[].id'`, which cannot see commented
entries. The gate now reports 7 pipeline skills, not 8.

rh-qs-document.next_skill becomes null. Pointing it at a skill the parser cannot
see dangles: pipeline-checkpoint.py resolves it with next(..., None) and falls
through to its "first skill not done" scan. It degraded gracefully, but it was a
lie in the data.

Not touched: qs-extract-knowledge/knowledge-base/** and the rh-qs-test-suite
input fixtures record how other, existing repos are actually laid out —
rewriting them would falsify the knowledge base.

Signed-off-by: Yossi Elias <yelias@redhat.com>
Every quickstart now starts as a copy of rh-ai-quickstart/ai-quickstart-template,
created locally in rh-qs-discovery Phase 4a as soon as the slug is minted. It
carries the standard chart/ layout and the catalog README skeleton (including the
from the org standard and reconstructing those fields at document time.

Seeding uses `git archive | tar -x` rather than `cp -r "$TMP"/*`, which silently
drops dotfiles — latent today since the template has no top-level dotfiles, fatal
the day someone adds .github/workflows/. The five .qs-factory/ subdirs get
.gitkeep files; git does not track empty directories, so without them they vanish
on the first clone. Chart.yaml's `my-quickstart` / `CONTRIBUTOR_NAME` placeholders
are substituted in the same phase — left alone they survive five pipeline stages
and trip the factory's own "no placeholder strings remain" gates.

Pushing stays the user's call: discovery prints the `gh repo create --source=.`
command and does not run it. Never --clone — it takes no destination argument and
its cloneWithRetry treats exit 128 as retryable, so it fails after the repo
already exists on GitHub and a re-run hits "name already taken".

rh-qs-scaffold therefore stops creating the repo. It now verifies .git and an
origin remote as a precondition, which also resolves the old contradiction
between "creates a repo under the git user's name" and the rh-ai-quickstart/<slug>
remote the same file configured branch protection on. Its structure tree marks
what the template already provides and drops deploy/helm/<slug>/ for chart/.

chart/Chart.yaml is added to discovery's expected_outputs so the checkpoint
actually verifies seeding ran — otherwise discovery reports green either way.

Signed-off-by: Yossi Elias <yelias@redhat.com>
The factory had a latent three-way split: some files said `deploy/helm/<slug>/`,
others `deploy/helm/`, and the org template `ai-quickstart-template` — which
quickstarts are now seeded from — puts the chart at `chart/`. Adopt the template's
location everywhere so a freshly seeded repo and the docs describing it agree.

`CHART_DIR ?= chart` in rh-qs-verify-deploy's Makefile block is the single source
of truth; targets and docs read `$(CHART_DIR)` rather than repeating a literal path.

Deliberately untouched:
- qs-extract-knowledge/knowledge-base/** and the rh-qs-test-suite input-repo
  fixtures — both record how other, existing repos are actually laid out.
- rh-qs-minio-conversion — it converts pre-existing quickstarts whose charts live
  wherever they live (the skill's own table shows `deploy/helm/fraud-detection`
  next to `helm/billing-workloads`); rewriting those would falsify the record.
- docs/ADR.md's historical diagram — the superseded-by note at the top covers it.

Signed-off-by: Yossi Elias <yelias@redhat.com>
…holesale

Blog drafts are factory-side working material — review-before-publication
artifacts with no business in a published quickstart repo. They were the only
thing keeping rh-qs-ship's cleanup from being a single pathspec, and that
exception had already cost something: the cleanup listed pipeline/ prds/
designs/ reports/ but not flow/, so dashboard.md shipped in published repos.

Drafts now live at .blog-drafts/<slug>-YYYY-MM-DD.md in the factory root,
gitignored. The flat slug-prefixed name also collapses blog-writer's two-path
fallback — "slug folder exists" vs "doesn't" — into one rule, which matters
because blog-writer is often pointed at an older quickstart that never went
through the pipeline at all.

With nothing left to except, ship's cleanup is `git rm -r --ignore-unmatch
.qs-factory`, and --ignore-unmatch now only guards a re-run after a partial
cleanup rather than papering over a missing folder in the normal flow.

Ship also stops running the pipeline checkpoint: it just deleted the dashboard,
so there is nothing to update. It closes with a plain message instead. The
lockstep CI gate derives its skill list from the registry, where rh-qs-ship is
commented out, so dropping the block does not trip it — verified.

rh-qs-session-start's output-directory tree was stale on every line; it now
shows .blog-drafts/, .reports/, and .qs-factory/, and states the invariant that
every direct child of .rhoai-qs/ is a quickstart.

Signed-off-by: Yossi Elias <yelias@redhat.com>
references/ReadmeStructure.md was a 3.3 KB fork of what is now a 14.3 KB
upstream README — missing the Partner tag and the Overview, Prerequisites,
Installation, Validating the deployment, and Repository structure sections.
Paired with "README.md (create or replace)" in the Output section, rh-qs-document
would have replaced the seeded template README with the older skeleton, dropping
exactly the fields redhat.com catalog publication checks. Delete the fork and
point at the real template.

The skill now edits README.md in place: `grep -n 'CONTRIBUTOR TODO' README.md`
enumerates the work, each blockquote gets replaced with real content, and the
heading structure the catalog tooling reads stays intact.

Called out explicitly: the template's examples use `oc new-project`, `oc get
pods`, and `oc delete project`. Those are placeholder guidance that contradicts
rh-qs-secure, and the Installation ones are plain numbered steps rather than
blockquote text, so a sweep that only replaces TODO blocks would leave them
behind. Substitute make deploy / verify-deploy / undeploy.

doc-manifest.yaml goes to spec_version 2 with a documentation.tags map and
tags_complete / no_contributor_todo_remaining booleans, so "the Tags block is
complete" is machine-checkable at handoff rather than at submission. Note that
contributor_org is not in the template's own TODO list — the skill says to add
the line.

Signed-off-by: Yossi Elias <yelias@redhat.com>
…ports/

Grooming reports and gap analyses span the whole backlog, so they were already
kept out of any one slug folder — but at `.rhoai-qs/reports/`, a sibling of the
quickstarts. That one entry is what forced slug resolution to filter instead of
just listing, and a filter is a rule every skill has to remember.

They move to `.reports/` at the factory root, symmetric with `.blog-drafts/` and
gitignored the same way. `.rhoai-qs/` now contains quickstarts and nothing else,
so `ls -1 .rhoai-qs/` is the slug list verbatim.

Signed-off-by: Yossi Elias <yelias@redhat.com>
…ommit

Running Phase 4a end to end against a scratch slug showed the sed block sitting
after `git commit`: the seed commit carried `my-quickstart` and CONTRIBUTOR_NAME,
and the phase ended with a dirty working tree. A later `git add -A` would have
swept the substitution into whatever commit came next.

Move it ahead of `git init`. Re-verified: one commit, clean `git status`, zero
placeholders, and a fresh clone carries all five .qs-factory/ subdirs plus the
14 KB catalog README with its ## Tags block.

Signed-off-by: Yossi Elias <yelias@redhat.com>
@github-actions

Copy link
Copy Markdown

🔍 Skill Validation (Advisory — does not block merge)

❌ Errors

  • internal link escapes skill directory: ../../../docs/foundation/pipeline-convention.md
  • https://docs.redhat.com/en/learn/ai-quickstarts (HTTP 503)
  • internal link escapes skill directory: ../../../docs/foundation/pipeline-convention.md
  • internal link escapes skill directory: ../../../docs/foundation/pipeline-convention.md
  • internal link escapes skill directory: ../../../docs/foundation/validation-skill-template.md
  • internal link escapes skill directory: ../rh-qs-test-suite/references/workflow-catalog.md
  • internal link escapes skill directory: ../rh-qs-test-suite/references/makefile-ci-contract.md
  • internal link escapes skill directory: ../../../docs/foundation/validation-skill-template.md
  • broken internal link: ./subagents/.md (file not found)
  • internal link escapes skill directory: ../../../docs/foundation/pipeline-convention.md
  • internal link escapes skill directory: ../rh-qs-secure/references/agent-permissions.md
  • internal link escapes skill directory: ../../../docs/foundation/validation-skill-template.md
  • https://rh-ai-quickstart.github.io/ai-architecture-charts (HTTP 404)
  • internal link escapes skill directory: ../../../docs/foundation/validation-skill-template.md
  • internal link escapes skill directory: ../../../docs/foundation/pipeline-convention.md
  • broken internal link: ./references/industry-trends.md (file not found)
  • internal link escapes skill directory: ../../../docs/foundation/pipeline-convention.md
  • internal link escapes skill directory: ../../../docs/foundation/validation-skill-template.md
  • internal link escapes skill directory: ../../../docs/foundation/validation-skill-template.md
  • internal link escapes skill directory: ../rh-qs-deploy/references/helm-minio.md
  • internal link escapes skill directory: ../../../docs/foundation/validation-skill-template.md
  • internal link escapes skill directory: ../../../docs/foundation/pipeline-convention.md
  • internal link escapes skill directory: ../rh-qs-test-suite/SKILL.md
  • https://llama-stack.readthedocs.io/ (HTTP 404)
  • internal link escapes skill directory: ../../../docs/foundation/pipeline-convention.md
  • https://docs.redhat.com/en/learn/ai-quickstarts (HTTP 503)
  • internal link escapes skill directory: ../../../docs/foundation/pipeline-convention.md
  • internal link escapes skill directory: ../../../docs/foundation/validation-skill-template.md
  • https://docs.redhat.com/en/learn/ai-quickstarts (HTTP 503)
  • internal link escapes skill directory: ../../../docs/foundation/pipeline-convention.md
  • internal link escapes skill directory: ../../../docs/foundation/validation-skill-template.md
  • internal link escapes skill directory: ../rh-qs-secure/references/agent-permissions.md
  • internal link escapes skill directory: ../rh-qs-secure/references/application-security.md
  • internal link escapes skill directory: ../rh-qs-test-suite/references/makefile-ci-contract.md

⚠️ Warnings

  • unknown directory: subagents/ (contains 6 files) — agents using the standard skill structure won't discover these files; should this be assets/?
  • unknown directory: output-templates/ (contains 6 files) — agents using the standard skill structure won't discover these files; should this be references/ or assets/?
  • unknown directory: subagents/ (contains 8 files) — agents using the standard skill structure won't discover these files; should this be references/ or assets/?
  • unrecognized field: "argument-hint"
  • unknown directory: subagents/ (contains 2 files) — agents using the standard skill structure won't discover these files; should this be assets/?
  • unexpected file at root: output-templates.md — if agents need this file, move it into references/ or assets/ as appropriate; otherwise remove it to avoid unnecessary context window usage
  • unexpected file at root: reasoning-guardrails.md — if agents need this file, move it into references/ or assets/ as appropriate; otherwise remove it to avoid unnecessary context window usage
  • unexpected file at root: spec-template.md — if agents need this file, move it into references/ or assets/ as appropriate; otherwise remove it to avoid unnecessary context window usage
  • unknown directory: subagents/ (contains 6 files) — agents using the standard skill structure won't discover these files; should this be assets/?
  • unrecognized field: "argument-hint"
  • unknown directory: subagents/ (contains 2 files) — agents using the standard skill structure won't discover these files; should this be references/ or assets/?
  • unknown directory: subagents/ (contains 2 files) — agents using the standard skill structure won't discover these files; should this be assets/?
  • SKILL.md body is 6875 tokens (spec recommends < 5000)
  • unknown directory: subagents/ (contains 2 files) — agents using the standard skill structure won't discover these files; should this be references/ or assets/?
  • unknown directory: subagents/ (contains 2 files) — agents using the standard skill structure won't discover these files
  • unknown directory: subagents/ (contains 2 files) — agents using the standard skill structure won't discover these files; should this be assets/?
  • unknown directory: subagents/ (contains 2 files) — agents using the standard skill structure won't discover these files; should this be references/ or assets/?

📋 Full report

@YosiElias
YosiElias merged commit 35ddad6 into rh-ai-quickstart:main Oct 18, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant