diff --git a/.github/scripts/validate-checkpoint.sh b/.github/scripts/validate-checkpoint.sh index c50a786..be40791 100755 --- a/.github/scripts/validate-checkpoint.sh +++ b/.github/scripts/validate-checkpoint.sh @@ -22,7 +22,7 @@ Run the checkpoint: python3 core/flow/pipeline-checkpoint.py --skill-name ${skill_name} --qs-name {qs-name} \`\`\` Print the dashboard link to the user: -"Pipeline dashboard updated — track progress at [dashboard.md](.rhoai-qs/{qs-name}/flow/dashboard.md)" +"Pipeline dashboard updated — track progress at [dashboard.md](.rhoai-qs/{qs-name}/.qs-factory/flow/dashboard.md)" EOF } diff --git a/.gitignore b/.gitignore index 46aac84..851837f 100644 --- a/.gitignore +++ b/.gitignore @@ -32,19 +32,27 @@ __pycache__/ # Generated output (legacy convention, largely superseded by .rhoai-qs/ below) data/ -# Everything for every quickstart lives here: pipeline state, specs, PRDs, -# designs, blog drafts, reports, AND each quickstart's own code repo (each -# quickstart is its own separate git repo/remote, e.g. rh-ai-quickstart/, -# set up directly inside .rhoai-qs// by rh-qs-scaffold via git init, not -# git clone, since the folder already has pipeline/prds/designs/ in it before -# scaffold runs). One single rule covers all of it — no per-slug maintenance -# needed here. Note: the quickstart's own repo intentionally does NOT gitignore -# pipeline/, prds/, designs/, reports/ — they stay tracked and pushed during -# development for team collaboration (reviewing the PRD/design together, etc.), -# and only get removed as a final cleanup step in rh-qs-ship, right before the -# quickstart ships — see docs/foundation/pipeline-convention.md. +# Quickstarts only — every direct child of .rhoai-qs/ is one quickstart's own +# git repo root (or a symlink to one elsewhere on disk). rh-qs-discovery seeds +# it from rh-ai-quickstart/ai-quickstart-template as soon as the slug is minted; +# the user pushes it to rh-ai-quickstart/ after approving the PRD. All +# factory bookkeeping for that quickstart — PRD, design, pipeline specs, +# dashboard, reports — lives in exactly one folder inside it, .qs-factory/. +# One single rule covers all of it; no per-slug maintenance needed here. +# +# Note: the quickstart's own repo intentionally does NOT gitignore .qs-factory/ +# — it stays tracked and pushed during development for team collaboration +# (reviewing the PRD/design together, etc.), and is removed wholesale as a final +# cleanup step in rh-qs-ship, right before the quickstart ships. +# See docs/foundation/pipeline-convention.md. .rhoai-qs/ +# Factory-side working material, deliberately outside .rhoai-qs/ so that the +# "every child of .rhoai-qs/ is a quickstart" invariant holds, and so that +# nothing here can leak into a published quickstart repo. +.blog-drafts/ +.reports/ + # Temporary files .tmp/ brain.ai diff --git a/core/flow/pipeline-checkpoint.py b/core/flow/pipeline-checkpoint.py index dc79247..996c643 100644 --- a/core/flow/pipeline-checkpoint.py +++ b/core/flow/pipeline-checkpoint.py @@ -13,6 +13,7 @@ import glob import logging import os +import re import time _import_error = None @@ -25,10 +26,19 @@ from pathlib import Path SCRIPT_DIR = Path(__file__).resolve().parent +# Skills run from several working directories — the factory root before scaffold, +# and inside .rhoai-qs// after it. Anchor every path off the factory root so +# the checkpoint writes to the same place regardless of where it was invoked. +FACTORY_ROOT = SCRIPT_DIR.parent.parent REGISTRY_PATH = SCRIPT_DIR / "pipeline-registry.yaml" FRESHNESS_WINDOW = 6000 # seconds — outputs must be younger than this -LOG_DIR = Path(".tmp") +BANNER_URL = ( + "https://raw.githubusercontent.com/rh-ai-quickstart/quickstart-factory" + "/main/core/assets/dashboard-banner.svg" +) + +LOG_DIR = FACTORY_ROOT / ".tmp" LOG_DIR.mkdir(parents=True, exist_ok=True) logging.basicConfig( filename=str(LOG_DIR / "pipeline-checkpoint.log"), @@ -42,12 +52,21 @@ # Error reporting (stdlib-only so it works even when external imports fail) # --------------------------------------------------------------------------- +def dashboard_dir_for(qs_name: str) -> Path: + """Directory holding the quickstart's dashboard. Always factory-root-anchored.""" + return FACTORY_ROOT / f".rhoai-qs/{qs_name}/.qs-factory/flow" + + +def lock_dir_for(qs_name: str) -> Path: + return FACTORY_ROOT / f".tmp/{qs_name}" + + def _append_error_to_dashboard(qs_name: str, skill_name: str, error: Exception): """Append a red error banner to the dashboard markdown.""" try: - dashboard_path = Path(f".rhoai-qs/{qs_name}/flow/dashboard.md") + dashboard_path = dashboard_dir_for(qs_name) / "dashboard.md" dashboard_path.parent.mkdir(parents=True, exist_ok=True) - lock_dir = Path(f".tmp/{qs_name}") + lock_dir = lock_dir_for(qs_name) lock_dir.mkdir(parents=True, exist_ok=True) lock_path = lock_dir / "dashboard.lock" timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S") @@ -97,6 +116,34 @@ def resolve_qs_path(template, qs_name: str) -> str: return template.replace("{qs-name}", qs_name) +# --------------------------------------------------------------------------- +# Link rewriting +# +# Registry paths are stored factory-root-relative. The dashboard lives at an +# arbitrary depth below the factory root — and may be reached through a symlink +# that leaves the factory tree altogether — so links are made relative to the +# dashboard's own directory rather than carrying a hardcoded `../../../` prefix. +# --------------------------------------------------------------------------- + +MD_LINK_RE = re.compile(r"\[([^\]]*)\]\(([^)\s]+)\)") +# URL schemes, protocol-relative URLs, anchors, and already-absolute paths +NON_RELATIVE_RE = re.compile(r"^(?:[a-z][a-z0-9+.\-]*:|//|#|/)", re.IGNORECASE) + + +def link_to(target: str, dashboard_dir: Path) -> str: + """Rewrite a factory-root-relative path to be relative to `dashboard_dir`.""" + if NON_RELATIVE_RE.match(target): + return target + return os.path.relpath(FACTORY_ROOT / target, dashboard_dir) + + +def rewrite_links(text: str, dashboard_dir: Path) -> str: + """Rewrite every relative markdown link target in `text`.""" + return MD_LINK_RE.sub( + lambda m: f"[{m.group(1)}]({link_to(m.group(2), dashboard_dir)})", text + ) + + # --------------------------------------------------------------------------- # Dashboard markdown renderer # --------------------------------------------------------------------------- @@ -104,6 +151,7 @@ def resolve_qs_path(template, qs_name: str) -> str: def render_dashboard(qs_name: str, skills: list[dict], state: dict) -> str: """Render the full dashboard markdown from state + registry.""" now_str = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S") + dashboard_dir = dashboard_dir_for(qs_name) total = len(skills) done_count = sum( 1 for s in skills if state.get(s["id"], {}).get("status") == "done" @@ -138,7 +186,7 @@ def render_dashboard(qs_name: str, skills: list[dict], state: dict) -> str: if outputs: first_out = outputs[0] out_path = resolve_qs_path(first_out, qs_name) - out_link = f"[{os.path.basename(out_path)}](../../../{out_path})" + out_link = f"[{os.path.basename(out_path)}]({link_to(out_path, dashboard_dir)})" else: out_link = "—" if verified is False: @@ -165,8 +213,8 @@ def render_dashboard(qs_name: str, skills: list[dict], state: dict) -> str: if last_done_skill: guidance = last_done_skill.get("review_guidance", "").strip() if guidance: - guidance = resolve_qs_path(guidance, qs_name) - review_section = f"\n---\n\n## ⚠️ Review Before Continuing — {last_done_skill['id']}\n\n{guidance}\n" + guidance = rewrite_links(resolve_qs_path(guidance, qs_name), dashboard_dir) + review_section =f"\n---\n\n## ⚠️ Review Before Continuing — {last_done_skill['id']}\n\n{guidance}\n" # Next step next_section = "" @@ -219,7 +267,7 @@ def render_dashboard(qs_name: str, skills: list[dict], state: dict) -> str: ) body = f"""\ -Quickstart Factory — Red Hat OpenShift AI +Quickstart Factory — Red Hat OpenShift AI # Pipeline Dashboard — {qs_name} @@ -252,7 +300,8 @@ def validate_outputs(skill: dict, qs_name: str) -> bool: return True now = time.time() for out in outputs: - pattern = resolve_qs_path(out, qs_name) + # Registry paths are factory-root-relative; absolute paths pass through. + pattern = str(FACTORY_ROOT / resolve_qs_path(out, qs_name)) matches = glob.glob(pattern) if not matches: return False @@ -267,9 +316,9 @@ def validate_outputs(skill: dict, qs_name: str) -> bool: def update_dashboard(qs_name: str, skill_id: str, skills: list[dict], outputs_verified: bool): """Update (or create) the dashboard under file lock.""" - dashboard_dir = Path(f".rhoai-qs/{qs_name}/flow") + dashboard_dir = dashboard_dir_for(qs_name) dashboard_path = dashboard_dir / "dashboard.md" - lock_dir = Path(f".tmp/{qs_name}") + lock_dir = lock_dir_for(qs_name) lock_path = lock_dir / "dashboard.lock" lock_dir.mkdir(parents=True, exist_ok=True) diff --git a/core/flow/pipeline-registry.yaml b/core/flow/pipeline-registry.yaml index b8a762e..bb1bb0a 100644 --- a/core/flow/pipeline-registry.yaml +++ b/core/flow/pipeline-registry.yaml @@ -10,6 +10,12 @@ # skills[].review_guidance: # - Keep to 4 lines max — only the most important checks the user must note # - Always end with a peer review recommendation +# - Write any path you want the user to open as a markdown link with a +# factory-root-relative target. pipeline-checkpoint.py rewrites it relative +# to the dashboard at render time — never hardcode a ../../../ prefix. +# +# All paths in this file (expected_outputs, review_guidance links) are relative +# to the quickstart-factory repo root, regardless of the skill's working dir. # pipeline: name: greenfield @@ -33,10 +39,12 @@ skills: description: "Full backlog output from gh-backlog-reader (issue numbers, titles, bodies, labels, assignees)" required: false expected_outputs: - - path: ".rhoai-qs/{qs-name}/prds/prd.md" + - path: ".rhoai-qs/{qs-name}/.qs-factory/prds/prd.md" description: "Structured PRD ready for rh-qs-architect" + - path: ".rhoai-qs/{qs-name}/chart/Chart.yaml" + description: "Proof the repo was seeded from ai-quickstart-template in Phase 4a — without this the checkpoint shows discovery green even if seeding never ran" review_guidance: | - - PRD exists at [.rhoai-qs/{qs-name}/prds/prd.md](../../../.rhoai-qs/{qs-name}/prds/prd.md) with all sections filled in + - PRD exists at [.rhoai-qs/{qs-name}/.qs-factory/prds/prd.md](.rhoai-qs/{qs-name}/.qs-factory/prds/prd.md) with all sections filled in - Review PRD content for completeness: problem statement, target persona, success metrics, scope boundaries, and technology constraints - Recommend getting a peer engineer review on the PRD before continuing next_skill: rh-qs-architect @@ -48,14 +56,14 @@ skills: - name: qs-name description: "Quickstart slug" expected_outputs: - - path: ".rhoai-qs/{qs-name}/designs/architecture-spec.yaml" + - path: ".rhoai-qs/{qs-name}/.qs-factory/designs/architecture-spec.yaml" description: "Structured YAML handoff spec with technology stack, component BOM, integration_patterns (protocols, data flows, security boundaries), testing strategy, and upstream dependencies" - - path: ".rhoai-qs/{qs-name}/designs/architecture-diagram.mmd" + - path: ".rhoai-qs/{qs-name}/.qs-factory/designs/architecture-diagram.mmd" description: "Mermaid architecture diagram referenced by architecture-spec.yaml" review_guidance: | - - architecture-spec.yaml exists at [.rhoai-qs/{qs-name}/designs/architecture-spec.yaml](../../../.rhoai-qs/{qs-name}/designs/architecture-spec.yaml) with all required sections filled in + - architecture-spec.yaml exists at [.rhoai-qs/{qs-name}/.qs-factory/designs/architecture-spec.yaml](.rhoai-qs/{qs-name}/.qs-factory/designs/architecture-spec.yaml) with all required sections filled in - Review content: technology_stack complete, component BOM matches PRD, integration_patterns cover non-obvious protocols/flows/security boundaries, chart versions pinned, testing_strategy defined, dependencies include content_hash - - architecture-diagram.mmd exists at [.rhoai-qs/{qs-name}/designs/architecture-diagram.mmd](../../../.rhoai-qs/{qs-name}/designs/architecture-diagram.mmd) and matches components + - architecture-diagram.mmd exists at [.rhoai-qs/{qs-name}/.qs-factory/designs/architecture-diagram.mmd](.rhoai-qs/{qs-name}/.qs-factory/designs/architecture-diagram.mmd) and matches components - Recommend getting a peer engineer review on the architecture spec before continuing next_skill: rh-qs-scaffold @@ -66,10 +74,10 @@ skills: - name: qs-name description: "Quickstart slug" expected_outputs: - - path: ".rhoai-qs/{qs-name}/pipeline/scaffold-manifest.yaml" + - path: ".rhoai-qs/{qs-name}/.qs-factory/pipeline/scaffold-manifest.yaml" description: "Handoff manifest listing created files, packages, CI jobs, and linting config" review_guidance: | - - scaffold-manifest.yaml exists in [.rhoai-qs/{qs-name}/pipeline/scaffold-manifest.yaml](../../../.rhoai-qs/{qs-name}/pipeline/scaffold-manifest.yaml) + - scaffold-manifest.yaml exists in [.rhoai-qs/{qs-name}/.qs-factory/pipeline/scaffold-manifest.yaml](.rhoai-qs/{qs-name}/.qs-factory/pipeline/scaffold-manifest.yaml) - make lint passes, no placeholder strings remain in scaffolded files - Review content: repo accessible, Makefile has all standard targets, CI workflows valid - Recommend getting a peer engineer review on the scaffold before continuing @@ -82,10 +90,10 @@ skills: - name: qs-name description: "Quickstart slug" expected_outputs: - - path: ".rhoai-qs/{qs-name}/pipeline/implementation-manifest.yaml" + - path: ".rhoai-qs/{qs-name}/.qs-factory/pipeline/implementation-manifest.yaml" description: "Handoff manifest documenting endpoints, DB models, services, env vars, and test coverage" review_guidance: | - - implementation-manifest.yaml exists in [.rhoai-qs/{qs-name}/pipeline/implementation-manifest.yaml](../../../.rhoai-qs/{qs-name}/pipeline/implementation-manifest.yaml) + - implementation-manifest.yaml exists in [.rhoai-qs/{qs-name}/.qs-factory/pipeline/implementation-manifest.yaml](.rhoai-qs/{qs-name}/.qs-factory/pipeline/implementation-manifest.yaml) - make lint && make test pass with zero failures - Review content: all endpoints implemented, no placeholders, no hardcoded secrets - Recommend getting a peer engineer review on the implementation before continuing @@ -98,10 +106,10 @@ skills: - name: qs-name description: "Quickstart slug" expected_outputs: - - path: ".rhoai-qs/{qs-name}/pipeline/deploy-manifest.yaml" + - path: ".rhoai-qs/{qs-name}/.qs-factory/pipeline/deploy-manifest.yaml" description: "Handoff manifest recording Helm deps, compose services, Containerfiles, routes, and env vars" review_guidance: | - - deploy-manifest.yaml exists in [.rhoai-qs/{qs-name}/pipeline/deploy-manifest.yaml](../../../.rhoai-qs/{qs-name}/pipeline/deploy-manifest.yaml) + - deploy-manifest.yaml exists in [.rhoai-qs/{qs-name}/.qs-factory/pipeline/deploy-manifest.yaml](.rhoai-qs/{qs-name}/.qs-factory/pipeline/deploy-manifest.yaml) - make helm-lint passes and make dev brings up the local stack - Review content: no raw oc/kubectl usage, no committed secrets, Containerfiles use UBI9 - Recommend getting a peer engineer review on the deploy config before continuing @@ -127,12 +135,12 @@ skills: description: "Target OpenShift namespace — derived as opg-- if omitted" required: false expected_outputs: - - path: ".rhoai-qs/{qs-name}/pipeline/deploy-state.yaml" + - path: ".rhoai-qs/{qs-name}/.qs-factory/pipeline/deploy-state.yaml" description: "Final cluster health snapshot per resource — handoff to rh-qs-document" review_guidance: | - - deploy-state.yaml exists in [.rhoai-qs/{qs-name}/pipeline/deploy-state.yaml](../../../.rhoai-qs/{qs-name}/pipeline/deploy-state.yaml) with overall_status healthy + - deploy-state.yaml exists in [.rhoai-qs/{qs-name}/.qs-factory/pipeline/deploy-state.yaml](.rhoai-qs/{qs-name}/.qs-factory/pipeline/deploy-state.yaml) with overall_status healthy - Review content: unhealthy_resources empty, all E2E tests passed, no resource skipped after 3 failed attempts - - Read .tmp/{qs-name}/debug/deploy-report.md (local run log, not committed) for root causes and fixes — confirm those fixes went into the quickstart's source, not just onto the cluster + - Read [deploy-report.md](.tmp/{qs-name}/debug/deploy-report.md) (local run log, not committed) for root causes and fixes — confirm those fixes went into the quickstart's source, not just onto the cluster - Recommend getting a peer engineer review on the applied fixes before continuing next_skill: rh-qs-document @@ -143,27 +151,43 @@ skills: - name: qs-name description: "Quickstart slug" expected_outputs: - - path: ".rhoai-qs/{qs-name}/pipeline/doc-manifest.yaml" + - path: ".rhoai-qs/{qs-name}/.qs-factory/pipeline/doc-manifest.yaml" description: "Documentation handoff manifest with README section status and validation results" review_guidance: | - - doc-manifest.yaml exists in [.rhoai-qs/{qs-name}/pipeline/doc-manifest.yaml](../../../.rhoai-qs/{qs-name}/pipeline/doc-manifest.yaml) and all validation booleans are true + - doc-manifest.yaml exists in [.rhoai-qs/{qs-name}/.qs-factory/pipeline/doc-manifest.yaml](.rhoai-qs/{qs-name}/.qs-factory/pipeline/doc-manifest.yaml) and all validation booleans are true - README deploy commands match Makefile targets, no placeholder content remains - Review content: catalog metadata compliant, architecture diagram matches spec - Recommend getting a peer engineer review on the docs before continuing - next_skill: rh-qs-ship - - - id: rh-qs-ship - order: 8 - description: "Ship the quickstart — create PR with structured summary, generate blog post draft, and update backlog status" - expected_inputs: - - name: qs-name - description: "Quickstart slug" - expected_outputs: - - path: ".rhoai-qs/{qs-name}/blog-drafts/{qs-name}-*.md" - description: "Blog post draft following the template (Hook, What It Does, How It Works, Get Started, What's Next)" - review_guidance: | - - PR created with accurate summary, CI checks pass, no secrets in diff - - Blog draft follows template from assets/blog-template.md with required links - - Backlog issue commented on or status updated - - Recommend getting a peer engineer review on the PR before merging + # rh-qs-document is the last checkpointed step — see the rh-qs-ship note below. + # Pointing next_skill at a skill the parser cannot see would dangle: + # pipeline-checkpoint.py resolves it with next(..., None) and silently falls + # through to its "first skill not done" scan. rh-qs-document's own closing + # text tells the user to run rh-qs-ship. next_skill: null + + # rh-qs-ship is intentionally commented out — it is the final step and its + # cleanup deletes .qs-factory/, including the dashboard, so there is nothing + # left to checkpoint. Kept here for reference only: commented entries are + # invisible to the YAML parser, so pipeline-checkpoint.py and + # validate-checkpoint.sh both skip it. + # + # Do not resurrect the expected_outputs below as written — the glob + # blog-drafts/{qs-name}-*.md never matched the skill's actual output, so ship + # was always outputs_verified: false. Blog drafts have since moved out of the + # quickstart entirely, to .blog-drafts/-.md at the factory root. + # + # - id: rh-qs-ship + # order: 8 + # description: "Ship the quickstart — create PR with structured summary, generate blog post draft, and update backlog status" + # expected_inputs: + # - name: qs-name + # description: "Quickstart slug" + # expected_outputs: + # - path: ".rhoai-qs/{qs-name}/blog-drafts/{qs-name}-*.md" + # description: "Blog post draft following the template (Hook, What It Does, How It Works, Get Started, What's Next)" + # review_guidance: | + # - PR created with accurate summary, CI checks pass, no secrets in diff + # - Blog draft follows template from assets/blog-template.md with required links + # - Backlog issue commented on or status updated + # - Recommend getting a peer engineer review on the PR before merging + # next_skill: null diff --git a/core/flow/test_pipeline_checkpoint.py b/core/flow/test_pipeline_checkpoint.py index c0c2284..f3fee14 100644 --- a/core/flow/test_pipeline_checkpoint.py +++ b/core/flow/test_pipeline_checkpoint.py @@ -1,6 +1,7 @@ """Tests for pipeline-checkpoint.py.""" import os +import re import sys import time from pathlib import Path @@ -45,6 +46,7 @@ def mod(tmp_path, monkeypatch): spec.loader.exec_module(m) m.LOG_DIR = log_dir + m.FACTORY_ROOT = tmp_path return m @@ -56,7 +58,7 @@ def mod(tmp_path, monkeypatch): "expected_inputs": [ {"name": "qs-name", "description": "Quickstart slug"}, ], - "expected_outputs": [{"path": ".rhoai-qs/{qs-name}/flow/output-1.md"}], + "expected_outputs": [{"path": ".rhoai-qs/{qs-name}/.qs-factory/flow/output-1.md"}], "review_guidance": "Check output-1.", }, { @@ -66,7 +68,7 @@ def mod(tmp_path, monkeypatch): "expected_inputs": [ {"name": "qs-name", "description": "Quickstart slug"}, ], - "expected_outputs": [{"path": ".rhoai-qs/{qs-name}/flow/output-2.md"}], + "expected_outputs": [{"path": ".rhoai-qs/{qs-name}/.qs-factory/flow/output-2.md"}], "review_guidance": "Check output-2.", }, { @@ -77,7 +79,7 @@ def mod(tmp_path, monkeypatch): {"name": "qs-name", "description": "Quickstart slug"}, {"name": "file-name", "description": "File name to create"}, ], - "expected_outputs": [{"path": ".rhoai-qs/{qs-name}/flow/output-3.md"}], + "expected_outputs": [{"path": ".rhoai-qs/{qs-name}/.qs-factory/flow/output-3.md"}], "review_guidance": "", }, ] @@ -137,11 +139,11 @@ def test_stale_file_fails(self, mod, tmp_path): assert mod.validate_outputs(skill, "demo") is False def test_qs_name_substitution(self, mod, tmp_path): - out_dir = tmp_path / ".rhoai-qs" / "demo" / "flow" + out_dir = tmp_path / ".rhoai-qs" / "demo" / ".qs-factory" / "flow" out_dir.mkdir(parents=True) out_file = out_dir / "output-1.md" out_file.write_text("content") - pattern = str(tmp_path / ".rhoai-qs/{qs-name}/flow/output-1.md") + pattern = str(tmp_path / ".rhoai-qs/{qs-name}/.qs-factory/flow/output-1.md") skill = {"id": "x", "expected_outputs": [{"path": pattern}]} assert mod.validate_outputs(skill, "demo") is True @@ -240,6 +242,72 @@ def test_progress_bar_partial(self, mod): assert "67%" in md +# ── emitted link targets ───────────────────────────────────────────────── + + +class TestEmittedLinksResolve: + """Every relative link the dashboard emits must resolve from the dashboard's + own directory. This pins the invariant that makes the dashboard's depth below + the factory root irrelevant — move it and these links must still land.""" + + LINKED_SKILL = { + "id": "skill-1", + "order": 1, + "description": "First step", + "expected_inputs": [{"name": "qs-name", "description": "Quickstart slug"}], + "expected_outputs": [{"path": ".rhoai-qs/{qs-name}/.qs-factory/prds/prd.md"}], + # A sibling of the dashboard inside the quickstart, plus a target that + # lives outside it entirely — a fixed prefix cannot serve both. + "review_guidance": ( + "- PRD at [prd.md](.rhoai-qs/{qs-name}/.qs-factory/prds/prd.md)\n" + "- Run log at [deploy-report.md](.tmp/{qs-name}/debug/deploy-report.md)\n" + ), + } + + TARGETS = (".rhoai-qs/demo/.qs-factory/prds/prd.md", ".tmp/demo/debug/deploy-report.md") + + def _render(self, mod, tmp_path): + # The dashboard dir must exist for `..` segments in a link to resolve. + mod.dashboard_dir_for("demo").mkdir(parents=True, exist_ok=True) + for rel in self.TARGETS: + p = tmp_path / rel + p.parent.mkdir(parents=True, exist_ok=True) + p.write_text("content") + state = { + "skill-1": { + "status": "done", + "completed_at": "2026-01-01", + "outputs_verified": True, + } + } + return mod.render_dashboard("demo", [self.LINKED_SKILL], state) + + def test_every_relative_link_resolves(self, mod, tmp_path): + md = self._render(mod, tmp_path) + dashboard_dir = mod.dashboard_dir_for("demo") + + targets = [t for _, t in re.findall(r"\[([^\]]*)\]\(([^)\s]+)\)", md)] + relative = [t for t in targets if not re.match(r"^(?:\w+:|//|#|/)", t)] + assert len(relative) == 3, f"expected 3 relative links, got {relative}" + + for target in relative: + assert (dashboard_dir / target).exists(), ( + f"link {target!r} does not resolve from {dashboard_dir}" + ) + + def test_links_are_not_factory_root_relative(self, mod, tmp_path): + """The raw registry form must never reach the rendered dashboard.""" + md = self._render(mod, tmp_path) + assert "](.rhoai-qs/" not in md + assert "](.tmp/" not in md + + def test_banner_is_an_absolute_url(self, mod, tmp_path): + """The banner is depth-independent, so moving the dashboard cannot break it.""" + md = self._render(mod, tmp_path) + assert f'/blog-drafts/` (or the top-level `.rhoai-qs/blog-drafts/` if the quickstart's own slug folder doesn't exist, e.g. for older quickstarts predating this convention). Drafts require review before publication. +Generate blog post drafts for completed AI Quickstarts. Outputs to `.blog-drafts/` in the quickstart-factory root. Drafts require review before publication. ## Workflow @@ -34,10 +34,9 @@ Include in every blog post: ## Output -- **If the quickstart's slug folder exists:** `.rhoai-qs//blog-drafts/YYYY-MM-DD.md` — no slug in the filename, the folder already disambiguates (e.g. `.rhoai-qs/vllm-cpu/blog-drafts/2025-03-11.md`) -- **Fallback (no slug folder, e.g. an older quickstart predating this convention):** `.rhoai-qs/blog-drafts/{quickstart-slug}-YYYY-MM-DD.md` — the slug **is** needed here since this top-level folder mixes drafts for every quickstart lacking its own slug folder (e.g. `vllm-cpu-2025-03-11.md`) +`.blog-drafts/-YYYY-MM-DD.md` in the quickstart-factory root — e.g. `.blog-drafts/vllm-cpu-2025-03-11.md`. -> **Note:** it isn't yet certain how often this fallback path will actually be used in practice — most quickstarts going forward should have their own slug folder from the start. See [pipeline-convention.md](../../../docs/foundation/pipeline-convention.md#cross-cutting-locations). +One rule, no conditionals: the path works whether or not the quickstart has a slug folder under `.rhoai-qs/`, which matters because blog-writer is often run against an older quickstart that never went through the factory pipeline. Drafts are factory-side working material — review-before-publication artifacts with no business in a published quickstart repo — so they live outside `.rhoai-qs/` and are gitignored. See [pipeline-convention.md](../../../docs/foundation/pipeline-convention.md#factory-side-locations). ## References diff --git a/core/skills/pipeline-grooming/SKILL.md b/core/skills/pipeline-grooming/SKILL.md index 9538f03..a4fd623 100644 --- a/core/skills/pipeline-grooming/SKILL.md +++ b/core/skills/pipeline-grooming/SKILL.md @@ -31,7 +31,7 @@ Use this checklist per quickstart item: ## Report Template -Grooming spans the whole backlog, not one quickstart, so save the report to the top-level `.rhoai-qs/reports/grooming-report-.md` (see [pipeline-convention.md](../../../docs/foundation/pipeline-convention.md)) — never under a single quickstart's slug folder. +Grooming spans the whole backlog, not one quickstart, so save the report to the factory-root `.reports/grooming-report-.md` (see [pipeline-convention.md](../../../docs/foundation/pipeline-convention.md#factory-side-locations)) — not under a quickstart's slug folder, and not under `.rhoai-qs/` at all: every direct child there is a quickstart, which is what makes slug resolution a plain `ls`. When producing a grooming report: diff --git a/core/skills/quickstart-identifier/SKILL.md b/core/skills/quickstart-identifier/SKILL.md index 11863a1..b62162f 100644 --- a/core/skills/quickstart-identifier/SKILL.md +++ b/core/skills/quickstart-identifier/SKILL.md @@ -33,7 +33,7 @@ Identify potential new AI Quickstarts by: ## Output -Coverage analysis spans the whole backlog, not one quickstart, so save any report to the top-level `.rhoai-qs/reports/` (see [pipeline-convention.md](../../../docs/foundation/pipeline-convention.md)) — never under a single quickstart's slug folder. If the user decides to pursue one of the proposed ideas, hand off to `rh-qs-discovery`, which will create the actual slug folder. +Coverage analysis spans the whole backlog, not one quickstart, so save any report to the factory-root `.reports/` (see [pipeline-convention.md](../../../docs/foundation/pipeline-convention.md#factory-side-locations)) — not under a quickstart's slug folder, and not under `.rhoai-qs/` at all: every direct child there is a quickstart, which is what makes slug resolution a plain `ls`. If the user decides to pursue one of the proposed ideas, hand off to `rh-qs-discovery`, which will create the actual slug folder. ## References diff --git a/core/skills/rh-qs-architect/SKILL.md b/core/skills/rh-qs-architect/SKILL.md index 8012539..bec468e 100644 --- a/core/skills/rh-qs-architect/SKILL.md +++ b/core/skills/rh-qs-architect/SKILL.md @@ -1,6 +1,6 @@ --- name: rh-qs-architect -description: Architecture phase for AI Quickstarts. Reads the PRD, maps requirements to OpenShift AI and ai-architecture-charts, presents a bill of materials, generates a Mermaid diagram, and produces an architecture spec. Use when a PRD exists under .rhoai-qs//prds/. +description: Architecture phase for AI Quickstarts. Reads the PRD, maps requirements to OpenShift AI and ai-architecture-charts, presents a bill of materials, generates a Mermaid diagram, and produces an architecture spec. Use when a PRD exists under .rhoai-qs//.qs-factory/prds/. --- # rh-qs-architect @@ -9,7 +9,7 @@ description: Architecture phase for AI Quickstarts. Reads the PRD, maps requirem ## Trigger -PRD exists from `rh-qs-discovery` at `.rhoai-qs//prds/prd.md` +PRD exists from `rh-qs-discovery` at `.rhoai-qs//.qs-factory/prds/prd.md` ## What it does @@ -30,7 +30,7 @@ PRD exists from `rh-qs-discovery` at `.rhoai-qs//prds/prd.md` ### Phase 0: Resolve Quickstart Context -Before reading any files, resolve which quickstart this session is for. Run `ls .rhoai-qs/ 2>/dev/null` (excluding `reports` and `blog-drafts`) and spawn the **validation-skill subagent**: +Before reading any files, resolve which quickstart this session is for. Run `ls -1 .rhoai-qs/ 2>/dev/null` (every entry is a quickstart — no filtering) and spawn the **validation-skill subagent**: ```python Agent( @@ -52,7 +52,7 @@ Handle the result per [validation-skill-template.md](../../../docs/foundation/va ### Remaining phases ``` -- [ ] 1. Read PRD from .rhoai-qs//prds/prd.md +- [ ] 1. Read PRD from .rhoai-qs//.qs-factory/prds/prd.md - [ ] 2. Extract features from PRD (prd-feature-extractor subagent) - [ ] 3. If decision_points exist → present to user, refine input_features if needed - [ ] 4. Apply technology defaults @@ -68,7 +68,7 @@ Handle the result per [validation-skill-template.md](../../../docs/foundation/va #### Step 1: Read PRD -Read the PRD at `.rhoai-qs//prds/prd.md`. Use it as the source of truth for later steps; do not modify it. +Read the PRD at `.rhoai-qs//.qs-factory/prds/prd.md`. Use it as the source of truth for later steps; do not modify it. #### Step 2: Extract PRD features @@ -86,11 +86,11 @@ slug: {slug} ) ``` -The subagent writes `input_features`, `deployment_questions`, and `decision_points` to `.rhoai-qs/{slug}/pipeline/prd-features.yaml` and returns the same data as JSON. +The subagent writes `input_features`, `deployment_questions`, and `decision_points` to `.rhoai-qs/{slug}/.qs-factory/pipeline/prd-features.yaml` and returns the same data as JSON. #### Step 3: Resolve decision points -If `decision_points` is non-empty, present each to the user. Update `.rhoai-qs/{slug}/pipeline/prd-features.yaml` with any refined `input_features` (and related fields) before proceeding. If empty, continue. +If `decision_points` is non-empty, present each to the user. Update `.rhoai-qs/{slug}/.qs-factory/pipeline/prd-features.yaml` with any refined `input_features` (and related fields) before proceeding. If empty, continue. #### Step 4: Apply technology defaults @@ -162,7 +162,7 @@ Do not continue until the user approves (or requests changes). Keep the approved **Substep 8a: Enrich tech_stack** -Read `.rhoai-qs/{slug}/pipeline/prd-features.yaml`. For each technology identified in Step 5 (chart selections) and Step 6 (RHOAI mappings) that is NOT already in `input_features.tech_stack`, add it. +Read `.rhoai-qs/{slug}/.qs-factory/pipeline/prd-features.yaml`. For each technology identified in Step 5 (chart selections) and Step 6 (RHOAI mappings) that is NOT already in `input_features.tech_stack`, add it. From Step 5 charts — add the underlying technology, for example: @@ -207,7 +207,7 @@ deployment_questions: {deployment_questions} **Substep 8c: Verify** -Check `.rhoai-qs/{slug}/pipeline/kb-scores.yaml` exists. If it does not, stop and report the error to the user. +Check `.rhoai-qs/{slug}/.qs-factory/pipeline/kb-scores.yaml` exists. If it does not, stop and report the error to the user. #### Step 9: Define integration patterns and data flow @@ -252,7 +252,7 @@ integration_patterns: {integration_patterns} ) ``` -The subagent writes `.rhoai-qs/{slug}/designs/architecture-diagram.mmd` and returns a short status JSON. If `status` is not `success`, report `message` and stop. Use that file in Step 12. +The subagent writes `.rhoai-qs/{slug}/.qs-factory/designs/architecture-diagram.mmd` and returns a short status JSON. If `status` is not `success`, report `message` and stop. Use that file in Step 12. #### Step 11: Define testing strategy @@ -268,14 +268,14 @@ Define the testing strategy per component. Note which `rh-qs-test-suite` profile #### Step 12: Write architecture spec -Write `.rhoai-qs//designs/architecture-spec.yaml` following the template in [references/architecture-spec-template.yaml](./references/architecture-spec-template.yaml). +Write `.rhoai-qs//.qs-factory/designs/architecture-spec.yaml` following the template in [references/architecture-spec-template.yaml](./references/architecture-spec-template.yaml). Include: - **Header:** spec_version, quickstart_name, slug, skill, created_at - **Technology Stack:** Full stack listing (frontend, backend, database, vector_db, model_serving, etc.) - **Components:** Approved BOM with nested details per component (type, role, technology, delivery, chart config, rhoai_features, constraints, kb_sources with match_reason, dependencies) - **Integration & Data Flow:** Pull from `{integration_patterns}` (protocols, data_flows, security_boundaries) returned by Step 9 -- **Architecture Diagram:** Reference to `.rhoai-qs/{slug}/designs/architecture-diagram.mmd` +- **Architecture Diagram:** Reference to `.rhoai-qs/{slug}/.qs-factory/designs/architecture-diagram.mmd` - **Testing Strategy:** Levels and scope - **Dependencies:** Reference to prd.md, prd-features.yaml, and kb-scores.yaml with content_hash @@ -301,4 +301,4 @@ Run the checkpoint: python3 core/flow/pipeline-checkpoint.py --skill-name rh-qs-architect --qs-name {qs-name} ``` Print the dashboard link to the user: -"Pipeline dashboard updated — track progress at [dashboard.md](.rhoai-qs/{qs-name}/flow/dashboard.md)" +"Pipeline dashboard updated — track progress at [dashboard.md](.rhoai-qs/{qs-name}/.qs-factory/flow/dashboard.md)" diff --git a/core/skills/rh-qs-architect/references/architecture-spec-template.yaml b/core/skills/rh-qs-architect/references/architecture-spec-template.yaml index f008a6a..abaf5fe 100644 --- a/core/skills/rh-qs-architect/references/architecture-spec-template.yaml +++ b/core/skills/rh-qs-architect/references/architecture-spec-template.yaml @@ -69,7 +69,7 @@ integration_patterns: mechanism: "" # ─── Architecture Diagram ───────────────────────────────────── -architecture_diagram_path: .rhoai-qs//designs/architecture-diagram.mmd +architecture_diagram_path: .rhoai-qs//.qs-factory/designs/architecture-diagram.mmd # ─── Testing Strategy ───────────────────────────────────────── testing_strategy: @@ -97,12 +97,12 @@ testing_strategy: # ─── Dependencies ───────────────────────────────────────────── dependencies: - - spec: .rhoai-qs//prds/prd.md + - spec: .rhoai-qs//.qs-factory/prds/prd.md fields_used: [problem_statement, target_persona, technology_constraints] content_hash: "sha256:..." - - spec: .rhoai-qs//pipeline/prd-features.yaml + - spec: .rhoai-qs//.qs-factory/pipeline/prd-features.yaml fields_used: [input_features, deployment_questions, decision_points] content_hash: "sha256:..." - - spec: .rhoai-qs//pipeline/kb-scores.yaml + - spec: .rhoai-qs//.qs-factory/pipeline/kb-scores.yaml fields_used: [results] content_hash: "sha256:..." diff --git a/core/skills/rh-qs-architect/references/prd-features-schema.md b/core/skills/rh-qs-architect/references/prd-features-schema.md index eaa7fdf..b406a46 100644 --- a/core/skills/rh-qs-architect/references/prd-features-schema.md +++ b/core/skills/rh-qs-architect/references/prd-features-schema.md @@ -1,6 +1,6 @@ # PRD Features Schema -Defines the structure for `.rhoai-qs/{slug}/pipeline/prd-features.yaml`, the intermediate file that bridges PRD extraction and architecture design. +Defines the structure for `.rhoai-qs/{slug}/.qs-factory/pipeline/prd-features.yaml`, the intermediate file that bridges PRD extraction and architecture design. ## Example diff --git a/core/skills/rh-qs-architect/subagents/README.md b/core/skills/rh-qs-architect/subagents/README.md index f1d3b83..71c3a36 100644 --- a/core/skills/rh-qs-architect/subagents/README.md +++ b/core/skills/rh-qs-architect/subagents/README.md @@ -10,7 +10,7 @@ This directory contains the subagents used by `rh-qs-architect` ([../SKILL.md](. |-------|-------------| | **Name** | `validation-skill-prompt.md` | | **Purpose** | Resolve which quickstart (by slug) this session applies to | -| **Input** | User's raw message, list of existing slugs under `.rhoai-qs/` (excluding `reports` and `blog-drafts`), `is_entry_point: false`, calling skill name | +| **Input** | User's raw message, list of existing slugs under `.rhoai-qs/` (every entry is a quickstart), `is_entry_point: false`, calling skill name | | **Output** | Resolution status as JSON — resolved/needs_user_input/error, with slug and confidence | | **When used** | Phase 0 — before reading the PRD or writing the design doc | | **Why subagent** | Mechanical slug matching against a list, self-contained — see [validation-skill-template.md](../../../../docs/foundation/validation-skill-template.md) for the full spec | @@ -34,7 +34,7 @@ This directory contains the subagents used by `rh-qs-architect` ([../SKILL.md](. |-------|-------------| | **Name** | `prd-feature-extractor-prompt.md` | | **Purpose** | Extract structured `input_features` from a PRD for chart selection and architecture mapping | -| **Input** | `slug` — the quickstart slug (PRD path derived as `.rhoai-qs/{slug}/prds/prd.md`) | +| **Input** | `slug` — the quickstart slug (PRD path derived as `.rhoai-qs/{slug}/.qs-factory/prds/prd.md`) | | **Output** | JSON with `input_features` (5-key schema), `deployment_questions`, and `decision_points` | | **When used** | Step 2 — after slug resolution, before chart selection | | **Why subagent** | Pure extraction/classification task, self-contained — keeps the main agent's context free for orchestration and design decisions | @@ -55,7 +55,7 @@ This directory contains the subagents used by `rh-qs-architect` ([../SKILL.md](. } ``` -The subagent also writes this data to `.rhoai-qs/{slug}/pipeline/prd-features.yaml`. If the main agent refines `input_features` after resolving decision points with the user, it updates that file directly. +The subagent also writes this data to `.rhoai-qs/{slug}/.qs-factory/pipeline/prd-features.yaml`. If the main agent refines `input_features` after resolving decision points with the user, it updates that file directly. ### 3. chart-selector-prompt.md @@ -111,8 +111,8 @@ The subagent also writes this data to `.rhoai-qs/{slug}/pipeline/prd-features.ya |-------|-------------| | **Name** | `diagram-generator-prompt.md` | | **Purpose** | Generate a Mermaid architecture diagram from the approved bill of materials | -| **Input** | `slug` (PRD path derived as `.rhoai-qs/{slug}/prds/prd.md`), `bom` (list of `{role, technology, delivery}`), `charts` (selected chart names only) | -| **Output** | Writes `.rhoai-qs/{slug}/designs/architecture-diagram.mmd`; returns JSON with `status`, `path`, and a short `message` | +| **Input** | `slug` (PRD path derived as `.rhoai-qs/{slug}/.qs-factory/prds/prd.md`), `bom` (list of `{role, technology, delivery}`), `charts` (selected chart names only) | +| **Output** | Writes `.rhoai-qs/{slug}/.qs-factory/designs/architecture-diagram.mmd`; returns JSON with `status`, `path`, and a short `message` | | **When used** | Step 10 — after integration analysis, before the architecture spec | | **Why subagent** | Isolated diagram task — nodes from the BOM, edges from roles and PRD user flows, so the main agent stays on orchestration | @@ -121,7 +121,7 @@ The subagent also writes this data to `.rhoai-qs/{slug}/pipeline/prd-features.ya ```json { "status": "success", - "path": ".rhoai-qs/mortgage-processor/designs/architecture-diagram.mmd", + "path": ".rhoai-qs/mortgage-processor/.qs-factory/designs/architecture-diagram.mmd", "message": "Wrote architecture diagram." } ``` diff --git a/core/skills/rh-qs-architect/subagents/chart-selector-prompt.md b/core/skills/rh-qs-architect/subagents/chart-selector-prompt.md index 4a78099..37a4370 100644 --- a/core/skills/rh-qs-architect/subagents/chart-selector-prompt.md +++ b/core/skills/rh-qs-architect/subagents/chart-selector-prompt.md @@ -15,7 +15,7 @@ This is a **capability-matching task**. For each chart, understand what it provi **Input Parameters:** - `{input_features}`: the 5-key feature object (`components`, `tech_stack`, `ai_pattern`, `platform`, `data_layer`) - `{deployment_questions}`: list of how-to deployment questions from the extractor -- `{slug}`: the quickstart slug — the PRD lives at `.rhoai-qs/{slug}/prds/prd.md` (fallback if features don't provide enough context) +- `{slug}`: the quickstart slug — the PRD lives at `.rhoai-qs/{slug}/.qs-factory/prds/prd.md` (fallback if features don't provide enough context) - `{charts_reference_path}`: path to `references/ai-architecture-charts.md` ### Step 1: Read the charts reference @@ -35,7 +35,7 @@ When two charts cover the same primary role, follow the reference's guidance on ### Step 3: Resolve ambiguous matches -If capability fit is borderline, read the PRD at `.rhoai-qs/{slug}/prds/prd.md` for additional context. Only read the PRD when the features and deployment questions do not provide enough signal. +If capability fit is borderline, read the PRD at `.rhoai-qs/{slug}/.qs-factory/prds/prd.md` for additional context. Only read the PRD when the features and deployment questions do not provide enough signal. ### Step 4: Return selected charts diff --git a/core/skills/rh-qs-architect/subagents/diagram-generator-prompt.md b/core/skills/rh-qs-architect/subagents/diagram-generator-prompt.md index 45faf30..b5f7f90 100644 --- a/core/skills/rh-qs-architect/subagents/diagram-generator-prompt.md +++ b/core/skills/rh-qs-architect/subagents/diagram-generator-prompt.md @@ -11,7 +11,7 @@ You draw the architecture diagram for this quickstart from the **approved bill o ## Instructions **Input Parameters:** -- `{slug}`: the quickstart slug — the PRD lives at `.rhoai-qs/{slug}/prds/prd.md` +- `{slug}`: the quickstart slug — the PRD lives at `.rhoai-qs/{slug}/.qs-factory/prds/prd.md` - `{bom}`: approved bill of materials — a list of `{role, technology, delivery}` objects - `{charts}`: selected ai-architecture-charts names only (e.g. `["ogx-ai", "llm-service", "pgvector"]`) - `{integration_patterns}`: output from integration-analyzer subagent — `protocols`, `data_flows`, and `security_boundaries` @@ -26,7 +26,7 @@ Use `role` for what the node is, `technology` for the label when it helps, and ` Draw edges from each component's `role` and from interaction patterns. **Prefer `protocols` from `{integration_patterns}`** for non-obvious communication (gRPC, message queues, custom protocols). For standard patterns (REST, SQL, HTTP), infer from BOM roles and PRD sections. -Read `.rhoai-qs/{slug}/prds/prd.md` when you need fallback context — component relationships, user flow, or data movement. Start with **User flows**; use **Data model** or **AI touchpoints** if the path is still unclear. Do not reread the PRD for requirements extraction. +Read `.rhoai-qs/{slug}/.qs-factory/prds/prd.md` when you need fallback context — component relationships, user flow, or data movement. Start with **User flows**; use **Data model** or **AI touchpoints** if the path is still unclear. Do not reread the PRD for requirements extraction. The PRD follows a standard 7-section template: @@ -45,7 +45,7 @@ Label edges with: ### Step 3: Write the diagram -Write Mermaid source (no markdown fence) to `.rhoai-qs/{slug}/designs/architecture-diagram.mmd`. +Write Mermaid source (no markdown fence) to `.rhoai-qs/{slug}/.qs-factory/designs/architecture-diagram.mmd`. - Use `flowchart TB` or `flowchart LR`, whichever fits the graph - Keep every node in the same graph. Mark ready subchart nodes (names in `{charts}`) with hexagon shape `id{{label}}`; use rectangles for everything else (application code, OpenShift Route, RHOAI-only features) @@ -84,7 +84,7 @@ After the file is written, return **only JSON** matching the schema below. ```json { "status": "success", - "path": ".rhoai-qs/mortgage-processor/designs/architecture-diagram.mmd", + "path": ".rhoai-qs/mortgage-processor/.qs-factory/designs/architecture-diagram.mmd", "message": "Wrote architecture diagram." } ``` diff --git a/core/skills/rh-qs-architect/subagents/integration-analyzer-prompt.md b/core/skills/rh-qs-architect/subagents/integration-analyzer-prompt.md index 011cc0e..5712556 100644 --- a/core/skills/rh-qs-architect/subagents/integration-analyzer-prompt.md +++ b/core/skills/rh-qs-architect/subagents/integration-analyzer-prompt.md @@ -19,7 +19,7 @@ You analyze how approved BOM components communicate, map data flows, and define List all KB names and descriptions to identify relevant architectural patterns: ```bash -yq -o json . .rhoai-qs/{slug}/pipeline/kb-scores.yaml | jq '.results | to_entries | map({type: .key, items: (.value | map({name, description}))})' +yq -o json . .rhoai-qs/{slug}/.qs-factory/pipeline/kb-scores.yaml | jq '.results | to_entries | map({type: .key, items: (.value | map({name, description}))})' ``` Scan the output for architecture/component/deployment patterns relevant to the BOM. Note which types (archetypes, architectures, components, deployment) have patterns you might reference. @@ -54,7 +54,7 @@ If a BOM component or integration looks complex or you spotted a KB pattern in S 1. Extract the pattern's summary: ```bash - yq -o json . .rhoai-qs/{slug}/pipeline/kb-scores.yaml | jq '.results.[] | select(.name == "") | {name, summary, path}' + yq -o json . .rhoai-qs/{slug}/.qs-factory/pipeline/kb-scores.yaml | jq '.results.[] | select(.name == "") | {name, summary, path}' ``` Example: `.results.architectures[] | select(.name == "agent-orchestration")` diff --git a/core/skills/rh-qs-architect/subagents/prd-feature-extractor-prompt.md b/core/skills/rh-qs-architect/subagents/prd-feature-extractor-prompt.md index 9eadd77..1a3729f 100644 --- a/core/skills/rh-qs-architect/subagents/prd-feature-extractor-prompt.md +++ b/core/skills/rh-qs-architect/subagents/prd-feature-extractor-prompt.md @@ -11,11 +11,11 @@ You analyze a PRD and produce a structured feature profile that drives architect ## Instructions **Input Parameters:** -- `{slug}`: the quickstart slug — the PRD lives at `.rhoai-qs/{slug}/prds/prd.md` +- `{slug}`: the quickstart slug — the PRD lives at `.rhoai-qs/{slug}/.qs-factory/prds/prd.md` ### Step 1: Read the PRD -Read the PRD at `.rhoai-qs/{slug}/prds/prd.md`. The PRD follows a standard 7-section template: +Read the PRD at `.rhoai-qs/{slug}/.qs-factory/prds/prd.md`. The PRD follows a standard 7-section template: 1. Use case summary 2. User flows @@ -66,7 +66,7 @@ These are just examples — flag **any** ambiguity you find where the architect ### Step 6: Write the output file -Write the extracted features to `.rhoai-qs/{slug}/pipeline/prd-features.yaml` in YAML format with three top-level keys: `input_features`, `deployment_questions`, `decision_points`. See [references/prd-features-schema.md](../references/prd-features-schema.md) for field definitions. +Write the extracted features to `.rhoai-qs/{slug}/.qs-factory/pipeline/prd-features.yaml` in YAML format with three top-level keys: `input_features`, `deployment_questions`, `decision_points`. See [references/prd-features-schema.md](../references/prd-features-schema.md) for field definitions. ## Output diff --git a/core/skills/rh-qs-architect/subagents/validation-skill-prompt.md b/core/skills/rh-qs-architect/subagents/validation-skill-prompt.md index 9ab2e00..4b1b7c2 100644 --- a/core/skills/rh-qs-architect/subagents/validation-skill-prompt.md +++ b/core/skills/rh-qs-architect/subagents/validation-skill-prompt.md @@ -14,7 +14,7 @@ You determine which quickstart, by slug, the current `rh-qs-architect` session a **Input Parameters:** - `{user_message}`: the user's raw request for this session -- `{existing_slugs}`: list of slugs found under `.rhoai-qs/` (excluding `reports` and `blog-drafts`), gathered by the main agent via `ls .rhoai-qs/ 2>/dev/null` +- `{existing_slugs}`: list of slugs found under `.rhoai-qs/`, gathered by the main agent via `ls -1 .rhoai-qs/ 2>/dev/null` — every entry is a quickstart, nothing is filtered out - `{is_entry_point}`: always `false` for `rh-qs-architect` - `{calling_skill}`: `rh-qs-architect` diff --git a/core/skills/rh-qs-bump-versions/SKILL.md b/core/skills/rh-qs-bump-versions/SKILL.md index c709f62..e9e9bbc 100644 --- a/core/skills/rh-qs-bump-versions/SKILL.md +++ b/core/skills/rh-qs-bump-versions/SKILL.md @@ -43,7 +43,7 @@ description: | |----------|---------------| | Python packages | `packages/*/pyproject.toml`, root `uv.lock` | | Node packages | `packages/*/package.json`, `pnpm-lock.yaml` | -| Helm app chart | `deploy/helm//Chart.yaml` (`version`, `appVersion`) | +| Helm app chart | `chart/Chart.yaml` (`version`, `appVersion`) | | Helm subcharts | `dependencies[]` in `Chart.yaml` — pin from [ai-architecture-charts](https://github.com/rh-ai-quickstart/ai-architecture-charts) | | Container bases | `Containerfile` `FROM` lines | | CI tool pins | `.github/workflows/*.yml` `env:` (`UV_VERSION`, Helm installer version) | @@ -66,7 +66,7 @@ uv lock --upgrade-package pnpm update --filter # Helm subchart -helm dependency update deploy/helm// +helm dependency update chart/ # Verify make lint test helm-lint helm-template diff --git a/core/skills/rh-qs-debug-and-deploy/SKILL.md b/core/skills/rh-qs-debug-and-deploy/SKILL.md index f131aed..9fb9d8a 100644 --- a/core/skills/rh-qs-debug-and-deploy/SKILL.md +++ b/core/skills/rh-qs-debug-and-deploy/SKILL.md @@ -42,7 +42,7 @@ User provides: ### Phase 0: Resolve Quickstart Context -Before touching any files, resolve which quickstart this session is for. Run `ls .rhoai-qs/ 2>/dev/null` (excluding `reports` and `blog-drafts`) and spawn the **validation-skill subagent**: +Before touching any files, resolve which quickstart this session is for. Run `ls -1 .rhoai-qs/ 2>/dev/null` (every entry is a quickstart — no filtering) and spawn the **validation-skill subagent**: ```python Agent( @@ -94,7 +94,7 @@ if [ -d ".tmp/{slug}/debug" ]; then mv ".tmp/{slug}/debug" ".tmp/{slug}/debug.old.$(date +%Y%m%d-%H%M%S)" fi mkdir -p ".tmp/{slug}/debug" -mkdir -p ".rhoai-qs/{slug}/pipeline" +mkdir -p ".rhoai-qs/{slug}/.qs-factory/pipeline" ``` Rotation only ever touches `{state_dir}` — the persistent files under `{project_path}/pipeline/` (`deploy-state.yaml`, `test-plan.md`) survive every run. @@ -385,4 +385,4 @@ Run the checkpoint: python3 core/flow/pipeline-checkpoint.py --skill-name rh-qs-debug-and-deploy --qs-name {qs-name} ``` Print the dashboard link to the user: -"Pipeline dashboard updated — track progress at [dashboard.md](.rhoai-qs/{qs-name}/flow/dashboard.md)" +"Pipeline dashboard updated — track progress at [dashboard.md](.rhoai-qs/{qs-name}/.qs-factory/flow/dashboard.md)" diff --git a/core/skills/rh-qs-debug-and-deploy/output-templates/debug-report-template.md b/core/skills/rh-qs-debug-and-deploy/output-templates/debug-report-template.md index 9f3d626..a841b11 100644 --- a/core/skills/rh-qs-debug-and-deploy/output-templates/debug-report-template.md +++ b/core/skills/rh-qs-debug-and-deploy/output-templates/debug-report-template.md @@ -30,7 +30,7 @@ health_attempt_1: description: "Add emptyDir volume mount at /app/data so container gets writable directory under restricted-v2 SCC" fix_category: config | source-code files_to_change: - - path: deploy/helm/templates/app-server.yaml + - path: chart/templates/app-server.yaml what_to_change: "Add volumes section with emptyDir{} and volumeMounts for /app/data" redeploy_needed: true @@ -56,7 +56,7 @@ health_attempt_2: description: "Change POSTGRES_HOST from 'postgresql' to 'postgresql-svc'" fix_category: config files_to_change: - - path: deploy/helm/templates/app-server.yaml + - path: chart/templates/app-server.yaml what_to_change: "Update env POSTGRES_HOST value" redeploy_needed: true diff --git a/core/skills/rh-qs-debug-and-deploy/output-templates/deploy-analysis-template.md b/core/skills/rh-qs-debug-and-deploy/output-templates/deploy-analysis-template.md index e005a08..cf4e537 100644 --- a/core/skills/rh-qs-debug-and-deploy/output-templates/deploy-analysis-template.md +++ b/core/skills/rh-qs-debug-and-deploy/output-templates/deploy-analysis-template.md @@ -18,7 +18,7 @@ deployment_options: rationale: "Documented as the primary path in README section 'Quickstart'" deploy_commands: - description: "Install with in-cluster model serving" - command: "helm install my-quickstart ./deploy/helm -n -f values-openshift.yaml" + command: "helm install my-quickstart ./chart -n -f values-openshift.yaml" - id: external-endpoint label: "External inference endpoint" description: "Skips llm-service; the app points at an existing OpenAI-compatible endpoint" @@ -27,7 +27,7 @@ deployment_options: rationale: "README section 'Bring your own model'" deploy_commands: - description: "Install with external endpoint" - command: "helm install my-quickstart ./deploy/helm -n -f values-external-llm.yaml" + command: "helm install my-quickstart ./chart -n -f values-external-llm.yaml" # Which deployment_options entry was chosen. Written by the main agent in Phase 1d. # null when deployment_options is absent (single deployment path). @@ -40,7 +40,7 @@ selected_option_id: local-model # Every phase after 1d reads deploy commands from here and nowhere else. deploy_commands: - description: "Install Helm chart with OpenShift mode" - command: "helm install my-quickstart ./deploy/helm -n --set openshiftMode=true -f values-openshift.yaml" + command: "helm install my-quickstart ./chart -n --set openshiftMode=true -f values-openshift.yaml" - description: "Apply post-install config" command: "oc apply -f ./deploy/post-install/ -n " @@ -49,7 +49,7 @@ deploy_instructions_source: "README.md section 'RHOAI Deployment'" # Helm-specific (if deployment_method is helm) helm: - chart_path: ./deploy/helm + chart_path: ./chart release_name: my-quickstart values_files: [values.yaml, values-openshift.yaml] diff --git a/core/skills/rh-qs-debug-and-deploy/output-templates/final-report-template.md b/core/skills/rh-qs-debug-and-deploy/output-templates/final-report-template.md index 538d997..425c88d 100644 --- a/core/skills/rh-qs-debug-and-deploy/output-templates/final-report-template.md +++ b/core/skills/rh-qs-debug-and-deploy/output-templates/final-report-template.md @@ -54,8 +54,8 @@ The saved copy is a local run log for whoever ran the factory — it is not comm {/if} ## Files Modified During Debug -- `deploy/helm/templates/app-server.yaml` — added emptyDir volume, fixed env var -- `deploy/helm/values.yaml` — updated storage class name +- `chart/templates/app-server.yaml` — added emptyDir volume, fixed env var +- `chart/values.yaml` — updated storage class name ## Artifacts - Cluster state (handoff to `rh-qs-document`): `{project_path}/pipeline/deploy-state.yaml` diff --git a/core/skills/rh-qs-debug-and-deploy/output-templates/fix-report-template.md b/core/skills/rh-qs-debug-and-deploy/output-templates/fix-report-template.md index 5ecdbe4..8cb38c9 100644 --- a/core/skills/rh-qs-debug-and-deploy/output-templates/fix-report-template.md +++ b/core/skills/rh-qs-debug-and-deploy/output-templates/fix-report-template.md @@ -23,9 +23,9 @@ health_attempt_1: fix_applied: "Added emptyDir volume mount at /app/data, set securityContext runAsNonRoot" fix_category: config files_modified: - - path: deploy/helm/templates/app-server.yaml + - path: chart/templates/app-server.yaml change: "Added volumes section with emptyDir{}, volumeMounts for /app/data" - redeploy_command: "helm upgrade my-quickstart ./deploy/helm -n myns --set openshiftMode=true" + redeploy_command: "helm upgrade my-quickstart ./chart -n myns --set openshiftMode=true" result: failed post_fix_status: "Still CrashLoopBackOff - different error: connection refused to postgresql:5432" user_approval_required: false @@ -43,9 +43,9 @@ health_attempt_2: fix_applied: "Updated POSTGRES_HOST env var in deployment template from 'postgresql' to 'postgresql-svc'" fix_category: config files_modified: - - path: deploy/helm/templates/app-server.yaml + - path: chart/templates/app-server.yaml change: "Changed env POSTGRES_HOST value from 'postgresql' to 'postgresql-svc'" - redeploy_command: "helm upgrade my-quickstart ./deploy/helm -n myns --set openshiftMode=true" + redeploy_command: "helm upgrade my-quickstart ./chart -n myns --set openshiftMode=true" result: success post_fix_status: "Running, 1/1 ready" user_approval_required: false diff --git a/core/skills/rh-qs-debug-and-deploy/subagents/validation-skill-prompt.md b/core/skills/rh-qs-debug-and-deploy/subagents/validation-skill-prompt.md index f1819a1..ca12c2b 100644 --- a/core/skills/rh-qs-debug-and-deploy/subagents/validation-skill-prompt.md +++ b/core/skills/rh-qs-debug-and-deploy/subagents/validation-skill-prompt.md @@ -14,7 +14,7 @@ You determine which quickstart, by slug, the current `rh-qs-debug-and-deploy` se **Input Parameters:** - `{user_message}`: the user's raw request for this session -- `{existing_slugs}`: list of slugs found under `.rhoai-qs/` (excluding `reports` and `blog-drafts`), gathered by the main agent via `ls .rhoai-qs/ 2>/dev/null` +- `{existing_slugs}`: list of slugs found under `.rhoai-qs/`, gathered by the main agent via `ls -1 .rhoai-qs/ 2>/dev/null` — every entry is a quickstart, nothing is filtered out - `{is_entry_point}`: always `false` for `rh-qs-debug-and-deploy` - `{calling_skill}`: `rh-qs-debug-and-deploy` diff --git a/core/skills/rh-qs-deploy/SKILL.md b/core/skills/rh-qs-deploy/SKILL.md index 9a30551..c7b2765 100644 --- a/core/skills/rh-qs-deploy/SKILL.md +++ b/core/skills/rh-qs-deploy/SKILL.md @@ -13,7 +13,7 @@ Local verification passed from **`rh-qs-verify-build`** (`make dev`, `make test` ## Where This Runs -This skill works inside `.rhoai-qs//` — the scaffolded quickstart's own repo, since that's where Helm charts and Containerfiles live. Pipeline files and the architecture spec sit right alongside the code in this same folder — reference them as plain relative paths (`designs/architecture-spec.yaml`, `pipeline/...`), no `../` needed. See [pipeline-convention.md](../../../docs/foundation/pipeline-convention.md#where-skills-run-and-why-it-matters-for-paths). +This skill works inside `.rhoai-qs//` — the scaffolded quickstart's own repo, since that's where Helm charts and Containerfiles live. All factory bookkeeping sits in `.qs-factory/` inside this same folder — reference it with that prefix and no `../` (`.qs-factory/designs/architecture-spec.yaml`, `.qs-factory/pipeline/...`). See [pipeline-convention.md](../../../docs/foundation/pipeline-convention.md#where-skills-run-and-why-it-matters-for-paths). ## Agent guardrails @@ -37,7 +37,7 @@ This skill works inside `.rhoai-qs//` — the scaffolded quickstart's own ### Phase 0: Resolve Quickstart Context -Before doing anything, resolve which quickstart this session is for. Run `ls ../ 2>/dev/null` (excluding `reports` and `blog-drafts`) and spawn the **validation-skill subagent**: +Before doing anything, resolve which quickstart this session is for. Run `ls -1 ../ 2>/dev/null` (every entry is a quickstart — no filtering) and spawn the **validation-skill subagent**: ```python Agent( @@ -107,7 +107,7 @@ Do **not** document or use raw `oc`/`kubectl` for install. Verification and docs ```bash make helm-lint -helm template deploy/helm// -f deploy/helm//values.yaml +helm template chart/ -f chart/values.yaml make dev && curl -f http://localhost:/health ``` @@ -124,7 +124,7 @@ When deploy configs render locally → **`rh-qs-test-suite`** (if design include - [Helm: Llama Stack guide](./references/helm-llamastack.md) - [Helm: MinIO guide](./references/helm-minio.md) - [ai-architecture-charts](https://github.com/rh-ai-quickstart/ai-architecture-charts) -- Architecture spec: `designs/architecture-spec.yaml` +- Architecture spec: `.qs-factory/designs/architecture-spec.yaml` - [subagents/validation-skill-prompt.md](./subagents/validation-skill-prompt.md) — pass by file path only, do NOT read directly ## Pipeline checkpoint @@ -135,4 +135,4 @@ Run the checkpoint: python3 core/flow/pipeline-checkpoint.py --skill-name rh-qs-deploy --qs-name {qs-name} ``` Print the dashboard link to the user: -"Pipeline dashboard updated — track progress at [dashboard.md](.rhoai-qs/{qs-name}/flow/dashboard.md)" +"Pipeline dashboard updated — track progress at [dashboard.md](.rhoai-qs/{qs-name}/.qs-factory/flow/dashboard.md)" diff --git a/core/skills/rh-qs-deploy/references/helm-llamastack.md b/core/skills/rh-qs-deploy/references/helm-llamastack.md index ed1f654..4b7e1a7 100644 --- a/core/skills/rh-qs-deploy/references/helm-llamastack.md +++ b/core/skills/rh-qs-deploy/references/helm-llamastack.md @@ -11,7 +11,7 @@ Add [Llama Stack](https://github.com/meta-llama/llama-stack) to a quickstart usi ## When to use -- The quickstart already has (or is getting) a Helm chart under `deploy/helm//` or `helm/` +- The quickstart already has (or is getting) a Helm chart under `chart/` - The functional design calls for Llama Stack (agents, RAG, tools) on OpenShift / OpenShift AI - You need to enable a specific Hugging Face model, a remote OpenAI-compatible endpoint, or bundled pgvector @@ -63,7 +63,7 @@ Include only what the design needs: Then refresh vendored charts: ```bash -cd deploy/helm/ # or helm/ +cd chart helm dependency update ``` @@ -210,8 +210,8 @@ Add only if the design requires them: ### 6. Verify ```bash -helm template deploy/helm/ -f deploy/helm//values.yaml | grep -E 'llamastack|llm-service|pgvector' -helm lint deploy/helm/ +helm template chart -f chart/values.yaml | grep -E 'llamastack|llm-service|pgvector' +helm lint chart ``` After install on OpenShift, run **`make verify-deploy NAMESPACE=`** (defined in the quickstart Makefile during `rh-qs-deploy`). Do not use raw `oc`/`kubectl` in agent workflows. diff --git a/core/skills/rh-qs-deploy/references/helm-minio.md b/core/skills/rh-qs-deploy/references/helm-minio.md index 5f88b82..5700fe4 100644 --- a/core/skills/rh-qs-deploy/references/helm-minio.md +++ b/core/skills/rh-qs-deploy/references/helm-minio.md @@ -11,7 +11,7 @@ Add [MinIO](https://min.io/) object storage to a quickstart using the shared [mi ## When to use -- The quickstart already has (or is getting) a Helm chart under `deploy/helm//` or `helm/` +- The quickstart already has (or is getting) a Helm chart under `chart/` - The design needs S3-compatible storage (documents, pipeline artifacts, model binaries, sample datasets) - OpenShift Data Science Pipelines or ingestion notebooks need an object store backend @@ -66,7 +66,7 @@ MinIO is a dependency of `configure-pipeline`, gated by `pipelineStorage.deployM Refresh vendored charts: ```bash -cd deploy/helm/ # or helm/ +cd chart helm dependency update ``` @@ -219,8 +219,8 @@ minio: ### 7. Verify ```bash -helm template deploy/helm/ -f deploy/helm//values.yaml | grep -E 'minio|minio-api' -helm lint deploy/helm/ +helm template chart -f chart/values.yaml | grep -E 'minio|minio-api' +helm lint chart ``` After install on OpenShift, run **`make verify-deploy NAMESPACE=`**. Embed MinIO health checks inside that Makefile target — agents do not run `oc`/`kubectl` directly. diff --git a/core/skills/rh-qs-deploy/subagents/README.md b/core/skills/rh-qs-deploy/subagents/README.md index a9da22f..4dcd1ff 100644 --- a/core/skills/rh-qs-deploy/subagents/README.md +++ b/core/skills/rh-qs-deploy/subagents/README.md @@ -10,7 +10,7 @@ This directory contains the `validation-skill` subagent used by `rh-qs-deploy` ( |-------|-------------| | **Name** | `validation-skill-prompt.md` | | **Purpose** | Resolve which quickstart (by slug) this session applies to | -| **Input** | User's raw message, list of existing slugs under `../` (excluding `reports` and `blog-drafts`), `is_entry_point: false`, calling skill name | +| **Input** | User's raw message, list of existing slugs under `../` (every entry is a quickstart), `is_entry_point: false`, calling skill name | | **Output** | Resolution status as JSON — resolved/needs_user_input/error, with slug and confidence | | **When used** | Phase 0 — before reading the design doc or wiring Helm charts | | **Why subagent** | Mechanical slug matching against a list, self-contained — see [validation-skill-template.md](../../../../docs/foundation/validation-skill-template.md) for the full spec | diff --git a/core/skills/rh-qs-deploy/subagents/validation-skill-prompt.md b/core/skills/rh-qs-deploy/subagents/validation-skill-prompt.md index 6059f98..8edac0e 100644 --- a/core/skills/rh-qs-deploy/subagents/validation-skill-prompt.md +++ b/core/skills/rh-qs-deploy/subagents/validation-skill-prompt.md @@ -14,7 +14,7 @@ You determine which quickstart, by slug, the current `rh-qs-deploy` session appl **Input Parameters:** - `{user_message}`: the user's raw request for this session -- `{existing_slugs}`: list of slugs found under `.rhoai-qs/` (excluding `reports` and `blog-drafts`), gathered by the main agent via `ls ../ 2>/dev/null` (this skill runs inside `.rhoai-qs//`, so `../` is `.rhoai-qs/` itself) +- `{existing_slugs}`: list of slugs found under `.rhoai-qs/`, gathered by the main agent via `ls -1 ../ 2>/dev/null` (this skill runs inside `.rhoai-qs//`, so `../` is `.rhoai-qs/` itself) — every entry is a quickstart, nothing is filtered out - `{is_entry_point}`: always `false` for `rh-qs-deploy` - `{calling_skill}`: `rh-qs-deploy` diff --git a/core/skills/rh-qs-discovery/SKILL.md b/core/skills/rh-qs-discovery/SKILL.md index fdeb58e..cde21e7 100644 --- a/core/skills/rh-qs-discovery/SKILL.md +++ b/core/skills/rh-qs-discovery/SKILL.md @@ -14,7 +14,7 @@ allowed-tools: Bash, Read, Write, Edit, Agent ## Goal -Produce a validated Product Requirements Document (PRD) at `.rhoai-qs//prds/prd.md` that is ready for handoff to `rh-qs-architect`. The PRD captures the user's quickstart idea with enough detail for architectural design without pre-deciding implementation choices. +Produce a validated Product Requirements Document (PRD) at `.rhoai-qs//.qs-factory/prds/prd.md` that is ready for handoff to `rh-qs-architect`. The PRD captures the user's quickstart idea with enough detail for architectural design without pre-deciding implementation choices. ## Input @@ -69,7 +69,7 @@ Calling skill: rh-qs-discovery ) ``` -Where `existing_slugs` comes from `ls .rhoai-qs/ 2>/dev/null` (excluding `reports` and `blog-drafts`), run by the main agent — never by the subagent. +Where `existing_slugs` comes from `ls -1 .rhoai-qs/ 2>/dev/null` (every entry is a quickstart — no filtering), run by the main agent — never by the subagent. Handle the result per [validation-skill-template.md](../../../docs/foundation/validation-skill-template.md#main-agent-handling). If `resolution: new_quickstart`, treat this as a brand-new idea and proceed to Phase 1 normally. @@ -129,7 +129,9 @@ Record the chosen destination. The issue URL will be added to the PRD header whe For a brand-new idea, mint the slug now: lowercase, hyphenated, derived from the quickstart's working title (e.g., `mortgage-application-processor`). This is the slug every subsequent phase — and every downstream skill — will use to namespace files under `.rhoai-qs//`. -Read [spec-template.md](./spec-template.md). Based on the input type, initial analysis, and backlog check results, generate `.rhoai-qs//pipeline/discovery-spec.yaml` with: +**Seed the repo before writing anything else** — see Phase 4a. `discovery-spec.yaml` is the first bookkeeping file written, so the repo has to exist first. + +Read [spec-template.md](./spec-template.md). Based on the input type, initial analysis, and backlog check results, generate `.rhoai-qs//.qs-factory/pipeline/discovery-spec.yaml` with: - Completed sections (what we already know from the user's input) - Remaining interview questions (what we still need to ask) - Gap questions relevant to this idea @@ -137,6 +139,59 @@ Read [spec-template.md](./spec-template.md). Based on the input type, initial an Present the spec to the user for approval before proceeding to the interview. +### Phase 4a: Seed the Quickstart Repo + +Runs **between minting the slug and writing `discovery-spec.yaml`**. Creates the quickstart's repo **locally only** — nothing is pushed here (see Phase 8). + +Every quickstart starts life as a copy of the org template, [`rh-ai-quickstart/ai-quickstart-template`](https://github.com/rh-ai-quickstart/ai-quickstart-template), so it carries the standard Helm chart layout (`chart/`) and the catalog README skeleton — including the `## Tags` block redhat.com publication requires — from day one rather than drifting from the org standard and reconstructing those fields later. + +```bash +SLUG="" +DIR=".rhoai-qs/$SLUG" + +# Idempotent / resumable — discovery may be re-run on the same idea. +if [ -d "$DIR/.git" ]; then echo "repo already seeded — skipping"; exit 0; fi +if [ -d "$DIR" ] && [ -n "$(ls -A "$DIR" 2>/dev/null)" ]; then + echo "ERROR: $DIR is non-empty but has no .git — stop and ask the user"; exit 1 +fi + +TMP=$(mktemp -d) +git clone --depth 1 --single-branch --branch main \ + https://github.com/rh-ai-quickstart/ai-quickstart-template.git "$TMP" +mkdir -p "$DIR" +git -C "$TMP" archive --format=tar HEAD | tar -x -C "$DIR" # includes dotfiles +rm -rf "$TMP" + +# .gitkeep is required — git does not track empty directories, so without these +# the five subdirs are absent from the commit and vanish on the first clone. +for d in prds designs pipeline flow reports; do + mkdir -p "$DIR/.qs-factory/$d" && touch "$DIR/.qs-factory/$d/.gitkeep" +done + +cd "$DIR" + +# Substitute the template placeholders BEFORE the first commit, so the repo +# never has a commit carrying them and the tree is clean afterwards. +MAINTAINER="$(git config user.name)" +sed -i.bak "s|^name: my-quickstart$|name: $SLUG|" chart/Chart.yaml +sed -i.bak "s|CONTRIBUTOR_NAME|$MAINTAINER|" chart/Chart.yaml +rm -f chart/Chart.yaml.bak + +git init -b main +git add -A +git commit -m "chore: scaffold from ai-quickstart-template" +``` + +Use `git archive | tar -x`, **not** `cp -r "$TMP"/*` — the shell glob silently drops dotfiles. The template has no top-level dotfiles today, so that bug would lie dormant until someone adds `.github/workflows/`. + +`chart/Chart.yaml` ships `name: my-quickstart` and `maintainers: - name: CONTRIBUTOR_NAME`. Left alone they sit in the repo across five pipeline stages and trip the factory's own "no placeholder strings remain" gates, so they are rewritten here, in the same phase — and before the commit, so `git status` is clean when the phase ends. + +There is deliberately **no** `blog-drafts/` subdir. Drafts are factory-side working material and live at `.blog-drafts/-.md` in the factory root — see [pipeline-convention.md](../../../docs/foundation/pipeline-convention.md#factory-side-locations). + +The README's `> **CONTRIBUTOR TODO:` blockquotes stay as they are — `rh-qs-document` fills them in later, in place. + +Afterwards the repo should be exactly: one commit, a clean `git status`, `chart/`, `docs/images/`, `LICENSE`, `README.md`, and the five empty `.qs-factory/` subdirs. + ### Phase 5: Structured Interview / PRD Structuring **If the user uploaded documents:** Spawn the **prd-structurer subagent** to extract structured PRD sections: @@ -268,7 +323,7 @@ For each refinement round: ### Phase 8: Write PRD -Read [output-templates.md](./output-templates.md). Write the final PRD to `.rhoai-qs//prds/prd.md` using the template format. Include the PRD header with: +Read [output-templates.md](./output-templates.md). Write the final PRD to `.rhoai-qs//.qs-factory/prds/prd.md` using the template format. Include the PRD header with: - Issue destination and URL (if created) - Slug - Date @@ -277,6 +332,18 @@ Slug convention: lowercase, hyphenated (e.g., `mortgage-application-processor`). Confirm with the user before handing off to `rh-qs-architect`. +**Once the user approves the PRD, print these push instructions — do not run them.** Creating the GitHub repo is the user's call, not the agent's: + +```bash +cd .rhoai-qs/ +gh repo create rh-ai-quickstart/ --public --source=. --remote=origin --push \ + --description "" +``` + +Never use `gh repo create --clone`: it takes no destination argument (it always creates `./` in the cwd), and on failure `cloneWithRetry` treats exit 128 as retryable — it retries three times over ~9 s, then fails **after the repo already exists on GitHub**, so a re-run hits "name already taken". + +`rh-qs-scaffold` will not proceed until this remote is set. + ## Gap Analysis Mode When the user asks to identify gaps (absorbs rh-qs-quickstart-identifier), **skip Phase 0** — this mode surveys the whole backlog and doesn't apply to one specific quickstart: @@ -289,7 +356,7 @@ When the user asks to identify gaps (absorbs rh-qs-quickstart-identifier), **ski 2. Read [references/industry-trends.md](./references/industry-trends.md) (if available) 3. Compare coverage by industry, technology, and use case 4. Propose 3-5 new quickstart ideas with rationale -5. Save report to `.rhoai-qs/reports/gap-analysis-.md` using the template from [references/gap-analysis-template.md](./references/gap-analysis-template.md) +5. Save report to `.reports/gap-analysis-.md` using the template from [references/gap-analysis-template.md](./references/gap-analysis-template.md) If the user wants to pursue one of the proposed ideas, transition into the standard discovery flow (Phase 1 onward, as a brand-new idea) with the gap analysis context as initial input. @@ -327,5 +394,5 @@ Run the checkpoint: python3 core/flow/pipeline-checkpoint.py --skill-name rh-qs-discovery --qs-name {qs-name} ``` Print the dashboard link to the user: -"Pipeline dashboard updated — track progress at [dashboard.md](.rhoai-qs/{qs-name}/flow/dashboard.md)" +"Pipeline dashboard updated — track progress at [dashboard.md](.rhoai-qs/{qs-name}/.qs-factory/flow/dashboard.md)" diff --git a/core/skills/rh-qs-discovery/output-templates.md b/core/skills/rh-qs-discovery/output-templates.md index 990734c..92ed773 100644 --- a/core/skills/rh-qs-discovery/output-templates.md +++ b/core/skills/rh-qs-discovery/output-templates.md @@ -10,7 +10,7 @@ For the gap analysis report format, see [references/gap-analysis-template.md](./ ## PRD Template -**Location:** `.rhoai-qs//prds/prd.md` +**Location:** `.rhoai-qs//.qs-factory/prds/prd.md` **Slug convention:** lowercase, hyphenated (e.g., `mortgage-application-processor`, `supply-chain-anomaly-detector`). diff --git a/core/skills/rh-qs-discovery/reasoning-guardrails.md b/core/skills/rh-qs-discovery/reasoning-guardrails.md index afd3b07..c55bc1a 100644 --- a/core/skills/rh-qs-discovery/reasoning-guardrails.md +++ b/core/skills/rh-qs-discovery/reasoning-guardrails.md @@ -184,7 +184,7 @@ Once you've reasoned about all applicable concerns: ## Self-Check Before Generating PRD -Before writing the final PRD to `.rhoai-qs//prds/prd.md`, quickly verify: +Before writing the final PRD to `.rhoai-qs//.qs-factory/prds/prd.md`, quickly verify: - [ ] All relevant guardrails considered - [ ] PRD content traces to user input (not invented) - [ ] Ambiguities listed as open questions, not silently resolved diff --git a/core/skills/rh-qs-discovery/references/gap-analysis-template.md b/core/skills/rh-qs-discovery/references/gap-analysis-template.md index 647e2a1..e861528 100644 --- a/core/skills/rh-qs-discovery/references/gap-analysis-template.md +++ b/core/skills/rh-qs-discovery/references/gap-analysis-template.md @@ -4,7 +4,7 @@ This template is used by the main agent in **gap analysis mode** only (when the Gap analysis surveys the whole backlog — it runs before any specific quickstart slug exists, so this report is **not** namespaced under `.rhoai-qs//`. It's a cross-cutting artifact, like a grooming report. -**Location:** `.rhoai-qs/reports/gap-analysis-.md` +**Location:** `.reports/gap-analysis-.md` ```markdown # Quickstart Gap Analysis — diff --git a/core/skills/rh-qs-discovery/spec-template.md b/core/skills/rh-qs-discovery/spec-template.md index f085eae..e142b93 100644 --- a/core/skills/rh-qs-discovery/spec-template.md +++ b/core/skills/rh-qs-discovery/spec-template.md @@ -4,14 +4,14 @@ description: Template for discovery specification YAML file structure # Discovery Specification Template -This template defines the structure of `.rhoai-qs//pipeline/discovery-spec.yaml` — the interview plan and PRD tracking document that serves as the contract between initial input analysis and PRD generation. +This template defines the structure of `.rhoai-qs//.qs-factory/pipeline/discovery-spec.yaml` — the interview plan and PRD tracking document that serves as the contract between initial input analysis and PRD generation. Discovery is the first skill in the pipeline, so this spec has no upstream dependencies. It tracks what information has been gathered, what questions remain, and whether the idea is unique in the backlog. ## File Location ``` -.rhoai-qs//pipeline/discovery-spec.yaml +.rhoai-qs//.qs-factory/pipeline/discovery-spec.yaml ``` See [pipeline-convention.md](../../../docs/foundation/pipeline-convention.md) for directory scoping rules. @@ -116,7 +116,7 @@ validation_rules: dependencies: [] # Discovery is the first pipeline skill — no upstream spec dependencies. # Downstream skills (rh-qs-architect) will reference the PRD at -# .rhoai-qs//prds/prd.md, not this spec file. +# .rhoai-qs//.qs-factory/prds/prd.md, not this spec file. ``` ## Field Descriptions @@ -283,7 +283,7 @@ dependencies: [] ### For Main Agent (Phase 4) -Read this template, then generate `.rhoai-qs//pipeline/discovery-spec.yaml` based on the user's initial input and the backlog check results. The spec serves as the interview plan — it tracks which sections are covered and which questions remain. For a brand-new idea, the slug is minted here (from `quickstart_name`); for a continuing session, it was already resolved by `validation-skill` in Phase 0 — see [validation-skill-template.md](../../../docs/foundation/validation-skill-template.md). +Read this template, then generate `.rhoai-qs//.qs-factory/pipeline/discovery-spec.yaml` based on the user's initial input and the backlog check results. The spec serves as the interview plan — it tracks which sections are covered and which questions remain. For a brand-new idea, the slug is minted here (from `quickstart_name`); for a continuing session, it was already resolved by `validation-skill` in Phase 0 — see [validation-skill-template.md](../../../docs/foundation/validation-skill-template.md). Update the spec as the interview progresses: move items from `remaining_questions` to `completed_sections` as answers come in. @@ -293,4 +293,4 @@ Before presenting the PRD to the user, check each `validation_rules` entry again ### Downstream Consumer -`rh-qs-architect` reads the PRD at `.rhoai-qs//prds/prd.md`, not this spec. This spec is an internal working document for the discovery process. The PRD is the handoff artifact. +`rh-qs-architect` reads the PRD at `.rhoai-qs//.qs-factory/prds/prd.md`, not this spec. This spec is an internal working document for the discovery process. The PRD is the handoff artifact. diff --git a/core/skills/rh-qs-discovery/subagents/README.md b/core/skills/rh-qs-discovery/subagents/README.md index b09d1dc..4725408 100644 --- a/core/skills/rh-qs-discovery/subagents/README.md +++ b/core/skills/rh-qs-discovery/subagents/README.md @@ -26,7 +26,7 @@ This directory contains specialized subagent prompts that handle focused tasks d |-------|-------------| | **Name** | `validation-skill-prompt.md` | | **Purpose** | Resolve which quickstart (by slug) this session applies to, when continuing or refining an existing idea | -| **Input** | User's raw message, list of existing slugs under `.rhoai-qs/` (excluding `reports` and `blog-drafts`), `is_entry_point: true`, calling skill name | +| **Input** | User's raw message, list of existing slugs under `.rhoai-qs/` (every entry is a quickstart), `is_entry_point: true`, calling skill name | | **Output** | Resolution status as JSON — resolved/needs_user_input/new_quickstart/error, with slug and confidence | | **When used** | Phase 0 — only when continuing/refining an existing idea; skipped for brand-new ideas (no slug exists yet) | | **Why subagent** | Mechanical slug matching against a list, no reasoning about the PRD itself, self-contained — see [validation-skill-template.md](../../../../docs/foundation/validation-skill-template.md) for the full spec | diff --git a/core/skills/rh-qs-discovery/subagents/validation-skill-prompt.md b/core/skills/rh-qs-discovery/subagents/validation-skill-prompt.md index 0f4e756..6f3a64c 100644 --- a/core/skills/rh-qs-discovery/subagents/validation-skill-prompt.md +++ b/core/skills/rh-qs-discovery/subagents/validation-skill-prompt.md @@ -16,7 +16,7 @@ Your output tells the main agent exactly what to do next: proceed with a resolve **Input Parameters:** - `{user_message}`: the user's raw request for this session -- `{existing_slugs}`: list of slugs found under `.rhoai-qs/` (excluding `reports` and `blog-drafts`), gathered by the main agent via `ls .rhoai-qs/ 2>/dev/null` +- `{existing_slugs}`: list of slugs found under `.rhoai-qs/`, gathered by the main agent via `ls -1 .rhoai-qs/ 2>/dev/null` — every entry is a quickstart, nothing is filtered out - `{is_entry_point}`: always `true` for `rh-qs-discovery` - `{calling_skill}`: `rh-qs-discovery` diff --git a/core/skills/rh-qs-document/SKILL.md b/core/skills/rh-qs-document/SKILL.md index 8976498..481cc04 100644 --- a/core/skills/rh-qs-document/SKILL.md +++ b/core/skills/rh-qs-document/SKILL.md @@ -9,7 +9,7 @@ description: Generate README and catalog documentation for AI Quickstarts from v ## Trigger -**`rh-qs-verify-deploy`** report is green (`reports/verify-deploy-*.md`); CI workflows from `rh-qs-test-suite` are in place when the design requires them +**`rh-qs-verify-deploy`** report is green (`.qs-factory/reports/verify-deploy-*.md`); CI workflows from `rh-qs-test-suite` are in place when the design requires them Documentation runs **after** verification — not before. Every deploy command in the README must match what verify-deploy actually ran. @@ -19,18 +19,36 @@ This skill works inside `.rhoai-qs//` — the scaffolded quickstart's own ## What it does -1. Generates **README.md** from the implementation using standard quickstart catalog structure -2. Includes: title, description, requirements (hardware/software), deploy steps, delete/cleanup steps +1. **Fills in the existing `README.md` in place** — never regenerates it (see below) +2. Replaces each `> **CONTRIBUTOR TODO:` blockquote with real content: title, description, requirements (hardware/software), deploy steps, delete/cleanup steps 3. References the **Mermaid architecture diagram** from the architect phase (saved in `docs/images/`) -4. Adds **catalog metadata/tags** for Red Hat documentation discovery +4. Fills the `## Tags` block with catalog metadata for Red Hat documentation discovery 5. Documents all **environment variables** and their purpose 6. Optionally generates a **demo script outline** for video/presentation +## Fill in the README — do not regenerate it + +`README.md` already exists. `rh-qs-discovery` seeded the repo from [ai-quickstart-template](https://github.com/rh-ai-quickstart/ai-quickstart-template), so the file is the full catalog skeleton: `Overview`, `Detailed description`, `Architecture diagrams`, `Requirements`, `Deploy` (`Prerequisites` / `Installation` / `Validating the deployment` / `Delete`), `Repository structure`, `References`, `Technical details`, `Tags`. + +**Edit it, section by section.** Writing a fresh README over the top drops the sections and tag fields catalog publication requires, and those are exactly the fields nobody notices missing until the submission bounces. + +Find the work with: + +```bash +grep -n 'CONTRIBUTOR TODO' README.md +``` + +Each hit is a blockquote describing what belongs there, usually with an example. Replace the whole blockquote with real content drawn from the verify-deploy report, architecture spec, and the code. When every hit is gone, the README is done. Keep the heading structure as-is — the catalog tooling reads it. + +**Substitute Makefile targets for the template's raw `oc`.** The skeleton's examples use `oc new-project`, `oc get pods`, `helm uninstall`, and `oc delete project`. Those are placeholder guidance, not the commands to ship — they contradict `rh-qs-secure`, which forbids documenting raw `oc`/`kubectl`. Write `make deploy`, `make verify-deploy`, and `make undeploy` instead, matching what verify-deploy actually ran. Do not copy the examples verbatim. + +Two of the template's placeholder strings also need replacing wherever they appear: `YOUR_QUICKSTART_NAME` and `my-quickstart`. + ## Workflow ### Phase 0: Resolve Quickstart Context -Before doing anything, resolve which quickstart this session is for. Run `ls ../ 2>/dev/null` (excluding `reports` and `blog-drafts`) and spawn the **validation-skill subagent**: +Before doing anything, resolve which quickstart this session is for. Run `ls -1 ../ 2>/dev/null` (every entry is a quickstart — no filtering) and spawn the **validation-skill subagent**: ```python Agent( @@ -56,23 +74,38 @@ Handle the result per [validation-skill-template.md](../../../docs/foundation/va - [ ] 2. Explore repository (code, Helm, Makefile, compose, docs/images/) - [ ] 3. Read architecture spec for architecture diagram and component list - [ ] 4. Gather user-facing facts (hardware, RHOAI version, permissions) -- [ ] 5. Draft or update README.md using ReadmeStructure +- [ ] 5. Fill in every CONTRIBUTOR TODO block in README.md, in place - [ ] 6. Validate every documented command exists in Makefile or Helm (no undocumented oc/kubectl) - [ ] 7. Cross-check README deploy steps against verify-deploy evidence -- [ ] 8. Optional: write docs/demo-script.md +- [ ] 8. Complete the ## Tags block — publication blocks without it +- [ ] 9. Optional: write docs/demo-script.md ``` -### README sections +### What each section needs -Use [references/ReadmeStructure.md](./references/ReadmeStructure.md): - -- Title and short description (catalog character limits) +- Title and short description — the catalog's character limits are enforced in the Tags check below - Workload-focused detailed description - Requirements: specific GPU, tested OpenShift AI version, permissions -- Deploy and Delete steps (copy-pasteable; use `make deploy` / `make undeploy` and podman terminology — not raw `oc`) +- Deploy and Delete steps (copy-pasteable; `make deploy` / `make undeploy` and podman terminology — not raw `oc`) - Architecture section with diagram from `docs/images/` or architecture spec - Environment variables table -- Tags/metadata for catalog +- Repository structure tree, updated to the real layout + +### `## Tags` — required for publication + +redhat.com catalog publication rejects a quickstart with an incomplete `## Tags` block, so check it explicitly rather than trusting the TODO sweep: + +| Field | Constraint | +|-------|-----------| +| Title | Must match the H1 heading exactly; ≤ 64 chars | +| Description | Must match the short description exactly; ≤ 160 chars | +| Industry | Exactly one, from the catalog's list (e.g. Healthcare, Retail, Financial Services) | +| Product | Primary Red Hat product (e.g. OpenShift AI, OpenShift, RHEL) | +| Use case | Short descriptor (e.g. security, automation, productivity) | +| Partner | Partner names, or `N/A` — the field must be present either way | +| Contributor org | The contributing organization. The template's own TODO block does not list this one; add the line. | + +Record the result in `doc-manifest.yaml` under `validation.tags_complete` (see [pipeline-contracts.md](../../../docs/foundation/pipeline-contracts.md#7-doc-manifestyaml)) and do not hand off to `rh-qs-ship` while it is false. ### Demo script (optional) @@ -88,6 +121,7 @@ Save to `docs/demo-script.md`: - Line-by-line code walkthroughs - Generic placeholders when repo pins specific versions - Commands not present in Makefile or Helm +- A regenerated README — fill in the template's, in place ## Audience @@ -95,7 +129,8 @@ Readers may have **limited OpenShift AI experience**. Use plain language, explic ## Output -- `README.md` (create or replace) +- `README.md` (edited in place — every CONTRIBUTOR TODO block replaced) +- `.qs-factory/pipeline/doc-manifest.yaml` - Optional `docs/demo-script.md` - Updated `docs/images/` if diagram exported @@ -105,8 +140,8 @@ When README is complete → **`rh-qs-ship`** ## References -- [README structure](./references/ReadmeStructure.md) -- Architecture spec: `designs/architecture-spec.yaml` +- [ai-quickstart-template README](https://github.com/rh-ai-quickstart/ai-quickstart-template/blob/main/README.md) — the upstream skeleton; the repo's own `README.md` is the copy to edit +- Architecture spec: `.qs-factory/designs/architecture-spec.yaml` - [subagents/validation-skill-prompt.md](./subagents/validation-skill-prompt.md) — pass by file path only, do NOT read directly ## Pipeline checkpoint @@ -117,4 +152,4 @@ Run the checkpoint: python3 core/flow/pipeline-checkpoint.py --skill-name rh-qs-document --qs-name {qs-name} ``` Print the dashboard link to the user: -"Pipeline dashboard updated — track progress at [dashboard.md](.rhoai-qs/{qs-name}/flow/dashboard.md)" +"Pipeline dashboard updated — track progress at [dashboard.md](.rhoai-qs/{qs-name}/.qs-factory/flow/dashboard.md)" diff --git a/core/skills/rh-qs-document/references/ReadmeStructure.md b/core/skills/rh-qs-document/references/ReadmeStructure.md deleted file mode 100644 index f255d8a..0000000 --- a/core/skills/rh-qs-document/references/ReadmeStructure.md +++ /dev/null @@ -1,165 +0,0 @@ -# [INSERT quickstart title here] - - - - -## Table of contents - - - -## Detailed description - - - - -### See it in action - - - -### Architecture diagrams - - - - -## Requirements - - -### Minimum hardware requirements - - - -### Minimum software requirements - - - -### Required user permissions - - - - -## Deploy - - - -### Delete - - - -## References - - - -## Technical details - - - -## Tags - - diff --git a/core/skills/rh-qs-document/subagents/README.md b/core/skills/rh-qs-document/subagents/README.md index fce9470..7332d1e 100644 --- a/core/skills/rh-qs-document/subagents/README.md +++ b/core/skills/rh-qs-document/subagents/README.md @@ -10,7 +10,7 @@ This directory contains the `validation-skill` subagent used by `rh-qs-document` |-------|-------------| | **Name** | `validation-skill-prompt.md` | | **Purpose** | Resolve which quickstart (by slug) this session applies to | -| **Input** | User's raw message, list of existing slugs under `../` (excluding `reports` and `blog-drafts`), `is_entry_point: false`, calling skill name | +| **Input** | User's raw message, list of existing slugs under `../` (every entry is a quickstart), `is_entry_point: false`, calling skill name | | **Output** | Resolution status as JSON — resolved/needs_user_input/error, with slug and confidence | | **When used** | Phase 0 — before reading the verify-deploy report or design doc | | **Why subagent** | Mechanical slug matching against a list, self-contained — see [validation-skill-template.md](../../../../docs/foundation/validation-skill-template.md) for the full spec | diff --git a/core/skills/rh-qs-document/subagents/validation-skill-prompt.md b/core/skills/rh-qs-document/subagents/validation-skill-prompt.md index d44ae9a..5343c87 100644 --- a/core/skills/rh-qs-document/subagents/validation-skill-prompt.md +++ b/core/skills/rh-qs-document/subagents/validation-skill-prompt.md @@ -14,7 +14,7 @@ You determine which quickstart, by slug, the current `rh-qs-document` session ap **Input Parameters:** - `{user_message}`: the user's raw request for this session -- `{existing_slugs}`: list of slugs found under `.rhoai-qs/` (excluding `reports` and `blog-drafts`), gathered by the main agent via `ls ../ 2>/dev/null` (this skill runs inside `.rhoai-qs//`, so `../` is `.rhoai-qs/` itself) +- `{existing_slugs}`: list of slugs found under `.rhoai-qs/`, gathered by the main agent via `ls -1 ../ 2>/dev/null` (this skill runs inside `.rhoai-qs//`, so `../` is `.rhoai-qs/` itself) — every entry is a quickstart, nothing is filtered out - `{is_entry_point}`: always `false` for `rh-qs-document` - `{calling_skill}`: `rh-qs-document` diff --git a/core/skills/rh-qs-implement/SKILL.md b/core/skills/rh-qs-implement/SKILL.md index a0dd4ca..5e020be 100644 --- a/core/skills/rh-qs-implement/SKILL.md +++ b/core/skills/rh-qs-implement/SKILL.md @@ -13,7 +13,7 @@ Scaffold exists from `rh-qs-scaffold` ## Where This Runs -This skill works inside `.rhoai-qs//` — the scaffolded quickstart's own repo, since that's where the application code lives. The PRD, architecture spec, and pipeline specs/manifests sit right alongside the code in this same folder — reference them as plain relative paths (`prds/prd.md`, `designs/architecture-spec.yaml`, `pipeline/...`), no `../` needed. See [pipeline-convention.md](../../../docs/foundation/pipeline-convention.md#where-skills-run-and-why-it-matters-for-paths). +This skill works inside `.rhoai-qs//` — the scaffolded quickstart's own repo, since that's where the application code lives. The PRD, architecture spec, and pipeline specs/manifests all sit in `.qs-factory/` inside this same folder — reference them with that prefix and no `../` (`.qs-factory/prds/prd.md`, `.qs-factory/designs/architecture-spec.yaml`, `.qs-factory/pipeline/...`). See [pipeline-convention.md](../../../docs/foundation/pipeline-convention.md#where-skills-run-and-why-it-matters-for-paths). ## What it does @@ -33,7 +33,7 @@ Builds the **minimal vertical slice** that proves the use case end-to-end: ### Phase 0: Resolve Quickstart Context -Before reading any files, resolve which quickstart this session is for. Run `ls ../ 2>/dev/null` (excluding `reports` and `blog-drafts`) and spawn the **validation-skill subagent**: +Before reading any files, resolve which quickstart this session is for. Run `ls -1 ../ 2>/dev/null` (every entry is a quickstart — no filtering) and spawn the **validation-skill subagent**: ```python Agent( @@ -133,8 +133,8 @@ When vertical slice works locally → **`rh-qs-verify-build`** - [Monorepo layout](./references/template-layout.md) - [Design checklist](./references/design-checklist.md) -- PRD: `prds/prd.md` -- Architecture spec: `designs/architecture-spec.yaml` +- PRD: `.qs-factory/prds/prd.md` +- Architecture spec: `.qs-factory/designs/architecture-spec.yaml` - [subagents/validation-skill-prompt.md](./subagents/validation-skill-prompt.md) — pass by file path only, do NOT read directly ## Pipeline checkpoint @@ -145,4 +145,4 @@ Run the checkpoint: python3 core/flow/pipeline-checkpoint.py --skill-name rh-qs-implement --qs-name {qs-name} ``` Print the dashboard link to the user: -"Pipeline dashboard updated — track progress at [dashboard.md](.rhoai-qs/{qs-name}/flow/dashboard.md)" +"Pipeline dashboard updated — track progress at [dashboard.md](.rhoai-qs/{qs-name}/.qs-factory/flow/dashboard.md)" diff --git a/core/skills/rh-qs-implement/references/template-layout.md b/core/skills/rh-qs-implement/references/template-layout.md index 8524ec3..c53ff86 100644 --- a/core/skills/rh-qs-implement/references/template-layout.md +++ b/core/skills/rh-qs-implement/references/template-layout.md @@ -25,7 +25,7 @@ Canonical structure from the validated `ai-quickstart-template` monorepo (see co │ │ └── alembic/versions/ │ ├── ingestion/ # Optional: RAG ingest jobs/scripts │ └── configs/ # Shared eslint, prettier, ruff -├── deploy/helm// # App chart (api, ui, db, routes, migration job) +├── chart/ # App chart (api, ui, db, routes, migration job) ├── compose.yml # Local Postgres (podman-compose) ├── Makefile # setup, dev, test, deploy, db-* ├── turbo.json diff --git a/core/skills/rh-qs-implement/subagents/README.md b/core/skills/rh-qs-implement/subagents/README.md index 1d2c520..c645cfa 100644 --- a/core/skills/rh-qs-implement/subagents/README.md +++ b/core/skills/rh-qs-implement/subagents/README.md @@ -10,7 +10,7 @@ This directory contains the `validation-skill` subagent used by `rh-qs-implement |-------|-------------| | **Name** | `validation-skill-prompt.md` | | **Purpose** | Resolve which quickstart (by slug) this session applies to | -| **Input** | User's raw message, list of existing slugs under `../` (excluding `reports` and `blog-drafts`), `is_entry_point: false`, calling skill name | +| **Input** | User's raw message, list of existing slugs under `../` (every entry is a quickstart), `is_entry_point: false`, calling skill name | | **Output** | Resolution status as JSON — resolved/needs_user_input/error, with slug and confidence | | **When used** | Phase 0 — before reading the PRD/design doc | | **Why subagent** | Mechanical slug matching against a list, self-contained — see [validation-skill-template.md](../../../../docs/foundation/validation-skill-template.md) for the full spec | diff --git a/core/skills/rh-qs-implement/subagents/validation-skill-prompt.md b/core/skills/rh-qs-implement/subagents/validation-skill-prompt.md index ea3602a..e0a21e9 100644 --- a/core/skills/rh-qs-implement/subagents/validation-skill-prompt.md +++ b/core/skills/rh-qs-implement/subagents/validation-skill-prompt.md @@ -14,7 +14,7 @@ You determine which quickstart, by slug, the current `rh-qs-implement` session a **Input Parameters:** - `{user_message}`: the user's raw request for this session -- `{existing_slugs}`: list of slugs found under `.rhoai-qs/` (excluding `reports` and `blog-drafts`), gathered by the main agent via `ls ../ 2>/dev/null` (this skill runs inside `.rhoai-qs//`, so `../` is `.rhoai-qs/` itself) +- `{existing_slugs}`: list of slugs found under `.rhoai-qs/`, gathered by the main agent via `ls -1 ../ 2>/dev/null` (this skill runs inside `.rhoai-qs//`, so `../` is `.rhoai-qs/` itself) — every entry is a quickstart, nothing is filtered out - `{is_entry_point}`: always `false` for `rh-qs-implement` - `{calling_skill}`: `rh-qs-implement` diff --git a/core/skills/rh-qs-minio-conversion/SKILL.md b/core/skills/rh-qs-minio-conversion/SKILL.md index 284de2f..0314ffc 100644 --- a/core/skills/rh-qs-minio-conversion/SKILL.md +++ b/core/skills/rh-qs-minio-conversion/SKILL.md @@ -251,7 +251,7 @@ Commit **Chart.lock** and the packaged chart under `charts/` (e.g. `aws-compatib ### Phase 0: Resolve quickstart -Resolve which quickstart this session is for before any edits. If the user provides a git URL, clone it under `.rhoai-qs/` (slug = repo name). Otherwise, list sibling slugs under `.rhoai-qs/` (exclude `reports` and `blog-drafts`) and confirm when more than one exists. See [validation-skill-template.md](../../../docs/foundation/validation-skill-template.md). +Resolve which quickstart this session is for before any edits. If the user provides a git URL, clone it under `.rhoai-qs/` (slug = repo name). Otherwise, list sibling slugs under `.rhoai-qs/` (every entry is a quickstart) and confirm when more than one exists. See [validation-skill-template.md](../../../docs/foundation/validation-skill-template.md). ### Phase 1: Inventory MinIO surface area diff --git a/core/skills/rh-qs-scaffold/SKILL.md b/core/skills/rh-qs-scaffold/SKILL.md index 27a958f..4a6e046 100644 --- a/core/skills/rh-qs-scaffold/SKILL.md +++ b/core/skills/rh-qs-scaffold/SKILL.md @@ -10,11 +10,11 @@ description: Scaffold a new AI Quickstart GitHub repository with CI/CD, linting, ## Trigger -Architecture spec approved from `rh-qs-architect` at `.rhoai-qs//designs/architecture-spec.yaml` +Architecture spec approved from `rh-qs-architect` at `.rhoai-qs//.qs-factory/designs/architecture-spec.yaml` ## What it does -1. Creates a local GitHub repository under git users name. +1. Verifies the quickstart repo already exists and is pushed to `rh-ai-quickstart/` 2. Configures branch protection: require CI passing, require 1 review, no direct push to main 3. Creates directory structure based on the design 4. Sets up GitHub Actions: minimal CI (lint + unit tests on PR); full Kind/E2E/evals → **`rh-qs-test-suite`** after deploy @@ -29,7 +29,7 @@ Architecture spec approved from `rh-qs-architect` at `.rhoai-qs//designs/a ### Phase 0: Resolve Quickstart Context -Before doing anything, resolve which quickstart this session is for. Run `ls .rhoai-qs/ 2>/dev/null` (excluding `reports` and `blog-drafts`) and spawn the **validation-skill subagent**: +Before doing anything, resolve which quickstart this session is for. Run `ls -1 .rhoai-qs/ 2>/dev/null` (every entry is a quickstart — no filtering) and spawn the **validation-skill subagent**: ```python Agent( @@ -51,7 +51,7 @@ Handle the result per [validation-skill-template.md](../../../docs/foundation/va ### Remaining phases ``` -- [ ] 1. Create GitHub repo +- [ ] 1. Verify the repo precondition - [ ] 2. Configure branch protection - [ ] 3. Scaffold directory structure - [ ] 4. Add GitHub Actions workflows @@ -61,39 +61,27 @@ Handle the result per [validation-skill-template.md](../../../docs/foundation/va - [ ] 8. Push initial commit and verify CI ``` -### Create repository +### Repo precondition -**Important:** `.rhoai-qs//` already exists and already contains `pipeline/`, `prds/`, `designs/` from earlier phases — it is **not empty**. `git clone` (and `gh repo create ... --clone`) refuses to clone into a non-empty directory, so **do not use `--clone`**. Instead, create the GitHub repo separately, then `git init` the existing folder and connect it to the new remote: +Scaffold does **not** create the repo. `rh-qs-discovery` already seeded `.rhoai-qs//` from [ai-quickstart-template](https://github.com/rh-ai-quickstart/ai-quickstart-template) and committed it locally, and the user already pushed it to `rh-ai-quickstart/`. Verify both before touching anything: ```bash -# 1. Ensure we're at the quickstart-factory root -cd "$(git rev-parse --show-toplevel)" - -# 2. Create the GitHub repo WITHOUT cloning (no --clone flag) -gh repo create rh-ai-quickstart/ --public --description "" - -# 3. Move into the existing folder (already has pipeline/, prds/, designs/) -# and turn it into a git repo pointed at the new remote -cd .rhoai-qs// -git init -git remote add origin "https://github.com/rh-ai-quickstart/.git" -git branch -M main +DIR=".rhoai-qs/" +[ -d "$DIR/.git" ] || { echo "ERROR: $DIR is not a git repo"; exit 1; } +git -C "$DIR" remote get-url origin || { echo "ERROR: no origin remote"; exit 1; } ``` -If starting from [ai-quickstart-template](https://github.com/rh-ai-quickstart/ai-quickstart-template), create the repo with `--template rh-ai-quickstart/ai-quickstart-template` (still no `--clone`), then pull the template's content into the existing folder without disturbing `pipeline/`, `prds/`, `designs/`: +If either check fails, **stop** and tell the user to push the repo first with the command `rh-qs-discovery` printed at the end of its run: ```bash -gh repo create rh-ai-quickstart/ --public --template rh-ai-quickstart/ai-quickstart-template --description "" -cd .rhoai-qs// -git init -git remote add origin "https://github.com/rh-ai-quickstart/.git" -git fetch origin -git checkout -t origin/main -f +cd .rhoai-qs/ +gh repo create rh-ai-quickstart/ --public --source=. --remote=origin --push \ + --description "" ``` -`git checkout -f` only touches files that exist in the template's tree — since the template has no `pipeline/`, `prds/`, or `designs/` folders, the existing bookkeeping content is left untouched. Remove packages not in the design matrix afterward. +Do not work around a missing remote by creating the repo yourself — branch protection and CI both target `rh-ai-quickstart/`, and who creates it under that org is the user's call. -**Do NOT gitignore `pipeline/`, `prds/`, `designs/`, `blog-drafts/`, `reports/` in this repo.** These folders stay tracked and get pushed to the quickstart's own GitHub remote throughout development — this is intentional, so the team can collaborate on the PRD, design doc, and pipeline state via normal pull requests (e.g., reviewing a design doc together), not just on one engineer's local machine. They only get removed as a final cleanup step in `rh-qs-ship`, right before the quickstart is considered done. See [pipeline-convention.md](../../../docs/foundation/pipeline-convention.md#nested-quickstart-repos) for the full rationale. +**Do NOT gitignore `.qs-factory/` in this repo.** It stays tracked and gets pushed to the quickstart's own GitHub remote throughout development — this is intentional, so the team can collaborate on the PRD, design doc, and pipeline state via normal pull requests (e.g., reviewing a design doc together), not just on one engineer's local machine. It is removed wholesale as a final cleanup step in `rh-qs-ship`, right before the quickstart is considered done. See [pipeline-convention.md](../../../docs/foundation/pipeline-convention.md#nested-quickstart-repos) for the full rationale. ### Branch protection @@ -105,15 +93,16 @@ git checkout -t origin/main -f ## Repository structure -This lives at `.rhoai-qs//`. The top five entries (`pipeline/`, `prds/`, `designs/`, `blog-drafts/`, `reports/`) are factory bookkeeping from earlier phases — tracked and pushed like everything else during development so the team can collaborate on the PRD, design, etc., then removed as a final cleanup step in `rh-qs-ship` (see Create repository above): +This lives at `.rhoai-qs//`. Entries marked **(template)** already exist — discovery seeded them from `ai-quickstart-template` and scaffold must not recreate or overwrite them. `.qs-factory/` is factory bookkeeping from earlier phases, tracked and pushed like everything else during development so the team can collaborate on the PRD, design, etc., then removed wholesale as a final cleanup step in `rh-qs-ship` (see Repo precondition above). Everything else is what scaffold adds: ``` .rhoai-qs// # = this repo's root -├── pipeline/ # ─┐ -├── prds/ # │ factory bookkeeping — tracked during -├── designs/ # │ development, removed by rh-qs-ship -├── blog-drafts/ # │ right before the quickstart is done -├── reports/ # ─┘ +├── .qs-factory/ # ─┐ factory bookkeeping — tracked during +│ ├── prds/ # │ development, removed by rh-qs-ship +│ ├── designs/ # │ right before the quickstart is done +│ ├── pipeline/ # │ +│ ├── flow/ # │ +│ └── reports/ # ─┘ │ ├── .github/ │ ├── workflows/ @@ -144,26 +133,29 @@ This lives at `.rhoai-qs//`. The top five entries (`pipeline/`, `prds/`, ` │ ├── src/ │ ├── tests/ │ └── pyproject.toml -├── deploy/ -│ └── helm// -│ ├── Chart.yaml -│ ├── values.yaml -│ └── templates/ +├── chart/ # (template) Helm chart — fill in, do not move +│ ├── Chart.yaml # name + maintainer already substituted +│ ├── values.yaml +│ └── templates/ ├── tests/ │ ├── integration/ │ └── e2e/ │ └── playwright.config.ts ├── docs/ -│ └── images/ # Architecture diagrams +│ └── images/ # (template) architecture diagrams ├── compose.yml ├── Makefile ├── turbo.json ├── .env.example ├── .pre-commit-config.yaml ├── .gitignore -└── README.md +├── LICENSE # (template) +└── README.md # (template) catalog skeleton — rh-qs-document + # fills its CONTRIBUTOR TODO blocks in place ``` +The chart lives at `chart/` — the org template's layout, and what the catalog tooling expects. Do not introduce a `deploy/helm//` path. + ## GitHub Actions CI (ci.yaml) **Trigger:** Pull request to main @@ -175,7 +167,7 @@ This lives at `.rhoai-qs//`. The top five entries (`pipeline/`, `prds/`, ` | type-check | pyright/mypy + `tsc` | | unit-tests-api | `pytest packages/api/` | | unit-tests-ui | `vitest packages/ui/` | -| helm-lint | `helm lint deploy/helm//` | +| helm-lint | `helm lint chart/` | All jobs must pass before PR can merge. @@ -213,7 +205,7 @@ A GitHub repository with CI/CD configured, project structure created, and lintin ```bash make lint -helm lint deploy/helm// +helm lint chart/ ``` ## Next skill @@ -224,7 +216,7 @@ When scaffold is pushed and CI is green → **`rh-qs-implement`** - [ai-quickstart-template](https://github.com/rh-ai-quickstart/ai-quickstart-template) - [it-self-service-agent CI patterns](../rh-qs-test-suite/SKILL.md) — production workflow split (post-deploy) -- Architecture spec: `.rhoai-qs//designs/architecture-spec.yaml` +- Architecture spec: `.rhoai-qs//.qs-factory/designs/architecture-spec.yaml` - [subagents/validation-skill-prompt.md](./subagents/validation-skill-prompt.md) — pass by file path only, do NOT read directly ## Pipeline checkpoint @@ -235,4 +227,4 @@ Run the checkpoint: python3 core/flow/pipeline-checkpoint.py --skill-name rh-qs-scaffold --qs-name {qs-name} ``` Print the dashboard link to the user: -"Pipeline dashboard updated — track progress at [dashboard.md](.rhoai-qs/{qs-name}/flow/dashboard.md)" +"Pipeline dashboard updated — track progress at [dashboard.md](.rhoai-qs/{qs-name}/.qs-factory/flow/dashboard.md)" diff --git a/core/skills/rh-qs-scaffold/subagents/README.md b/core/skills/rh-qs-scaffold/subagents/README.md index 36111a5..3e16bf1 100644 --- a/core/skills/rh-qs-scaffold/subagents/README.md +++ b/core/skills/rh-qs-scaffold/subagents/README.md @@ -10,7 +10,7 @@ This directory contains the `validation-skill` subagent used by `rh-qs-scaffold` |-------|-------------| | **Name** | `validation-skill-prompt.md` | | **Purpose** | Resolve which quickstart (by slug) this session applies to | -| **Input** | User's raw message, list of existing slugs under `.rhoai-qs/` (excluding `reports` and `blog-drafts`), `is_entry_point: false`, calling skill name | +| **Input** | User's raw message, list of existing slugs under `.rhoai-qs/` (every entry is a quickstart), `is_entry_point: false`, calling skill name | | **Output** | Resolution status as JSON — resolved/needs_user_input/error, with slug and confidence | | **When used** | Phase 0 — before reading the design doc or creating the GitHub repo | | **Why subagent** | Mechanical slug matching against a list, self-contained — see [validation-skill-template.md](../../../../docs/foundation/validation-skill-template.md) for the full spec | diff --git a/core/skills/rh-qs-scaffold/subagents/validation-skill-prompt.md b/core/skills/rh-qs-scaffold/subagents/validation-skill-prompt.md index e4c3e0f..20ac2a7 100644 --- a/core/skills/rh-qs-scaffold/subagents/validation-skill-prompt.md +++ b/core/skills/rh-qs-scaffold/subagents/validation-skill-prompt.md @@ -14,7 +14,7 @@ You determine which quickstart, by slug, the current `rh-qs-scaffold` session ap **Input Parameters:** - `{user_message}`: the user's raw request for this session -- `{existing_slugs}`: list of slugs found under `.rhoai-qs/` (excluding `reports` and `blog-drafts`), gathered by the main agent via `ls .rhoai-qs/ 2>/dev/null` +- `{existing_slugs}`: list of slugs found under `.rhoai-qs/`, gathered by the main agent via `ls -1 .rhoai-qs/ 2>/dev/null` — every entry is a quickstart, nothing is filtered out - `{is_entry_point}`: always `false` for `rh-qs-scaffold` - `{calling_skill}`: `rh-qs-scaffold` diff --git a/core/skills/rh-qs-secure/SKILL.md b/core/skills/rh-qs-secure/SKILL.md index 6ab3c8f..efbcf0c 100644 --- a/core/skills/rh-qs-secure/SKILL.md +++ b/core/skills/rh-qs-secure/SKILL.md @@ -91,4 +91,4 @@ Security review is **embedded** in the pipeline — not a terminal stage. After - [Agent permissions and MCP guardrails](./references/agent-permissions.md) - [Application security checklist](./references/application-security.md) - [Llama Stack safety](https://llama-stack.readthedocs.io/) — when orchestration is enabled -- Architecture spec: `.rhoai-qs//designs/architecture-spec.yaml` when invoked from the factory root (e.g. during `rh-qs-architect`), or plain `designs/architecture-spec.yaml` when invoked from inside the scaffolded quickstart repo itself (e.g. during `rh-qs-deploy`, which already runs from `.rhoai-qs//`) +- Architecture spec: `.rhoai-qs//.qs-factory/designs/architecture-spec.yaml` when invoked from the factory root (e.g. during `rh-qs-architect`), or plain `designs/architecture-spec.yaml` when invoked from inside the scaffolded quickstart repo itself (e.g. during `rh-qs-deploy`, which already runs from `.rhoai-qs//`) diff --git a/core/skills/rh-qs-secure/references/agent-permissions.md b/core/skills/rh-qs-secure/references/agent-permissions.md index ef55477..2efaa5f 100644 --- a/core/skills/rh-qs-secure/references/agent-permissions.md +++ b/core/skills/rh-qs-secure/references/agent-permissions.md @@ -38,7 +38,7 @@ For live cluster deployment, **spawn a sub-agent** (Task) with a narrow mandate: ``` Task: Deploy to namespace Allowed: make deploy, make verify-deploy, make helm-lint, make helm-template -Forbidden: oc, kubectl, editing resources outside deploy/helm/ +Forbidden: oc, kubectl, editing resources outside chart/ Output: verify-deploy log + any values overrides needed for shared services ``` diff --git a/core/skills/rh-qs-session-start/SKILL.md b/core/skills/rh-qs-session-start/SKILL.md index acebe48..6d6b649 100644 --- a/core/skills/rh-qs-session-start/SKILL.md +++ b/core/skills/rh-qs-session-start/SKILL.md @@ -25,7 +25,7 @@ When the user says **"hello"** or **"hi"**: - By assignee: [summary from --summary output] ## In-Progress Quickstarts -[list slugs found under `ls .rhoai-qs/ 2>/dev/null`, excluding `reports` and `blog-drafts`, or "None yet" if empty] +[list slugs found under `ls -1 .rhoai-qs/ 2>/dev/null` — every entry is a quickstart — or "None yet" if empty] ## What would you like to do? @@ -115,7 +115,7 @@ Conversational. Read `core/skills/pipeline-grooming/SKILL.md` and `references/gr Conversational. Read `core/skills/blog-writer/SKILL.md`, `assets/blog-template.md`, and `references/messaging-guidelines.md`, then: - Fetch the issue with `gh-backlog-reader --issue ` to get comments and linked repos - If a linked implementation repo exists, browse its README to understand architecture and usage -- Generate a draft in `.rhoai-qs/{slug}/blog-drafts/{date}.md` (or the top-level `.rhoai-qs/blog-drafts/{slug}-{date}.md` if no slug folder exists for this quickstart yet — the slug is needed there since that folder mixes drafts for every quickstart lacking its own slug folder) +- Generate a draft in `.blog-drafts/{slug}-{date}.md` at the factory root ### quickstart-identifier Conversational. Read `core/skills/quickstart-identifier/SKILL.md` and `references/industry-trends.md`, then: @@ -139,22 +139,25 @@ Conversational. Read `core/skills/quickstart-identifier/SKILL.md` and `reference ## Output Directory -All generated artifacts (blog drafts, grooming reports, coverage analyses, PRDs, designs, code, etc.) go under `.rhoai-qs/`, namespaced by quickstart slug: +Anything tied to one quickstart — PRD, design, pipeline state, code — goes under `.rhoai-qs//`. Anything that isn't stays at the factory root: ``` +.blog-drafts/ ← -YYYY-MM-DD.md, every blog draft +.reports/ ← Cross-cutting reports (grooming, gap analysis) .rhoai-qs/ - / - pipeline/ ← Specs and manifests for that quickstart - prds/ ← PRD from rh-qs-discovery - designs/ ← Design doc from rh-qs-architect - blog-drafts/ ← Blog post drafts for that quickstart - reports/ ← Per-quickstart reports (verify-deploy, etc.) - packages/, deploy/ ← The quickstart's own application code (separate git repo) - reports/ ← Cross-cutting reports not tied to one quickstart (grooming, gap analysis) - blog-drafts/ ← Fallback for quickstarts predating this convention + / ← the quickstart's own git repo + .qs-factory/ ← all factory bookkeeping, removed by rh-qs-ship + prds/ ← PRD from rh-qs-discovery + designs/ ← Design doc from rh-qs-architect + pipeline/ ← Handoff specs and manifests + flow/ ← Pipeline dashboard + reports/ ← Per-quickstart reports (verify-deploy, etc.) + chart/, packages/, ... ← The quickstart's own application code ``` -This directory is gitignored by the factory repo — nothing under `.rhoai-qs/` gets pushed to `quickstart-factory`'s own history. (The quickstart's own code still gets committed and pushed — just to its own separate GitHub repo.) See [pipeline-convention.md](../../../docs/foundation/pipeline-convention.md) for the full convention. +**Every direct child of `.rhoai-qs/` is a quickstart** — that is what makes slug resolution a plain `ls -1 .rhoai-qs/` with no filtering, so nothing else may be put there. + +All three directories are gitignored by the factory repo — nothing in them gets pushed to `quickstart-factory`'s own history. (The quickstart's own code still gets committed and pushed — just to its own separate GitHub repo.) See [pipeline-convention.md](../../../docs/foundation/pipeline-convention.md) for the full convention. ## Governance diff --git a/core/skills/rh-qs-ship/SKILL.md b/core/skills/rh-qs-ship/SKILL.md index 774175d..503d501 100644 --- a/core/skills/rh-qs-ship/SKILL.md +++ b/core/skills/rh-qs-ship/SKILL.md @@ -14,9 +14,9 @@ Documentation is complete from `rh-qs-document` ## Where This Runs -This skill works inside `.rhoai-qs//` — the scaffolded quickstart's own repo, since it creates a PR against that repo. `rh-qs-ship` is also where the factory bookkeeping folders (`pipeline/`, `prds/`, `designs/`, `reports/`) get **removed** — they were tracked and pushed throughout development so the team could collaborate on the PRD, design, etc., but the finished, published quickstart shouldn't carry them. See [pipeline-convention.md](../../../docs/foundation/pipeline-convention.md#nested-quickstart-repos). +This skill works inside `.rhoai-qs//` — the scaffolded quickstart's own repo, since it creates a PR against that repo. `rh-qs-ship` is also where `.qs-factory/` gets **removed** — the PRD, design, pipeline state, and dashboard were tracked and pushed throughout development so the team could collaborate on them, but the finished, published quickstart shouldn't carry internal factory bookkeeping. See [pipeline-convention.md](../../../docs/foundation/pipeline-convention.md#nested-quickstart-repos). -`blog-drafts/` is handled separately: the draft is generated by *this same skill*, needs human review before publication, and isn't itself a development-collaboration artifact the way the PRD/design are — so it's excluded from the automatic cleanup below and left for the user to remove once the post is actually published. +`.qs-factory/` has no exceptions — everything inside it goes, so the cleanup is one `git rm -r` with no pathspec to maintain. The blog draft is the reason that used to be untrue, and it now lives in the factory repo at `.blog-drafts/-.md`, outside the quickstart entirely. ## What it does @@ -29,7 +29,7 @@ This skill works inside `.rhoai-qs//` — the scaffolded quickstart's own ### Phase 0: Resolve Quickstart Context -Before doing anything, resolve which quickstart this session is for. Run `ls ../ 2>/dev/null` (excluding `reports` and `blog-drafts`) and spawn the **validation-skill subagent**: +Before doing anything, resolve which quickstart this session is for. Run `ls -1 ../ 2>/dev/null` (every entry is a quickstart — no filtering) and spawn the **validation-skill subagent**: ```python Agent( @@ -52,8 +52,8 @@ Handle the result per [validation-skill-template.md](../../../docs/foundation/va ``` - [ ] 1. Verify git state (no secrets committed) -- [ ] 2. Draft blog post (writes blog-drafts/.md — needed for step 4) -- [ ] 3. Clean up factory bookkeeping (remove pipeline/, prds/, designs/, reports/ — NOT blog-drafts/) +- [ ] 2. Draft blog post (writes .blog-drafts/-.md in the factory repo) +- [ ] 3. Clean up factory bookkeeping (remove .qs-factory/ — all of it) - [ ] 4. Create pull request (includes the bookkeeping removal as part of the diff) - [ ] 5. Update backlog issue - [ ] 6. Return PR URL and review checklist @@ -71,20 +71,20 @@ Handle the result per [validation-skill-template.md](../../../docs/foundation/va - Implementation repo URL - Contrib: https://github.com/rh-ai-quickstart/ai-quickstart-contrib -Save to **`blog-drafts/YYYY-MM-DD.md`**. Drafts require human review before publication. Do this **before** the cleanup step below, since `blog-drafts/` is intentionally left out of that cleanup. +Save to **`.blog-drafts/-YYYY-MM-DD.md`** in the quickstart-factory repo — from inside the quickstart that is `../../.blog-drafts/-$(date +%F).md`. It is gitignored there, so the draft is never part of any commit, in this repo or the quickstart's. Drafts require human review before publication; leave it for the user to remove once the post is actually published. ### Clean up factory bookkeeping Now that the PRD, design, and pipeline state have served their purpose — collaborative development via normal PRs — remove them so the finished, published quickstart doesn't carry internal factory bookkeeping: ```bash -git rm -r --ignore-unmatch pipeline/ prds/ designs/ reports/ +git rm -r --ignore-unmatch .qs-factory git commit -m "chore: remove factory pipeline bookkeeping before shipping" ``` -`--ignore-unmatch` avoids a hard failure if one of these folders happens to be empty or missing (e.g., an unusual pipeline path) — in the normal flow all four exist by the time `rh-qs-ship` runs. +One pathspec, no exceptions: everything under `.qs-factory/` goes, including `flow/dashboard.md`. `--ignore-unmatch` only guards the case where the folder is already gone (e.g. ship re-run after a partial cleanup). -**Do NOT remove `blog-drafts/`** — the draft just written above still needs human review before publication; leave it for the user to clean up once the post is actually published. +No `.gitignore` entry is needed afterwards — `git rm -r` removes the files from the working tree as well as the index, and nothing re-creates them. ### Create pull request @@ -142,7 +142,7 @@ Comment on or close the related contrib issue. Mark in-progress during review, c | Artifact | Path | |----------|------| | Pull request | GitHub URL | -| Blog draft | `blog-drafts/.md` | +| Blog draft | `.blog-drafts/-.md` (quickstart-factory repo, gitignored) | ## References @@ -150,12 +150,8 @@ Comment on or close the related contrib issue. Mark in-progress during review, c - [Messaging guidelines](./references/messaging-guidelines.md) - [subagents/validation-skill-prompt.md](./subagents/validation-skill-prompt.md) — pass by file path only, do NOT read directly -## Pipeline checkpoint +## Closing message -Run the checkpoint: +`rh-qs-ship` runs **no pipeline checkpoint** — it just deleted the dashboard, so there is nothing left to update. Close with a plain message instead: -```bash -python3 core/flow/pipeline-checkpoint.py --skill-name rh-qs-ship --qs-name {qs-name} -``` -Print the dashboard link to the user: -"Pipeline dashboard updated — track progress at [dashboard.md](.rhoai-qs/{qs-name}/flow/dashboard.md)" +> "Factory bookkeeping removed — `.qs-factory/` (including the pipeline dashboard) is staged for deletion in this PR. The blog draft is at `.blog-drafts/-.md` in the factory repo." diff --git a/core/skills/rh-qs-ship/subagents/README.md b/core/skills/rh-qs-ship/subagents/README.md index 398f94f..3a5e253 100644 --- a/core/skills/rh-qs-ship/subagents/README.md +++ b/core/skills/rh-qs-ship/subagents/README.md @@ -10,7 +10,7 @@ This directory contains the `validation-skill` subagent used by `rh-qs-ship` ([. |-------|-------------| | **Name** | `validation-skill-prompt.md` | | **Purpose** | Resolve which quickstart (by slug) this session applies to | -| **Input** | User's raw message, list of existing slugs under `../` (excluding `reports` and `blog-drafts`), `is_entry_point: false`, calling skill name | +| **Input** | User's raw message, list of existing slugs under `../` (every entry is a quickstart), `is_entry_point: false`, calling skill name | | **Output** | Resolution status as JSON — resolved/needs_user_input/error, with slug and confidence | | **When used** | Phase 0 — before creating the PR or drafting the blog post | | **Why subagent** | Mechanical slug matching against a list, self-contained — see [validation-skill-template.md](../../../../docs/foundation/validation-skill-template.md) for the full spec | diff --git a/core/skills/rh-qs-ship/subagents/validation-skill-prompt.md b/core/skills/rh-qs-ship/subagents/validation-skill-prompt.md index ed626f0..b6c2840 100644 --- a/core/skills/rh-qs-ship/subagents/validation-skill-prompt.md +++ b/core/skills/rh-qs-ship/subagents/validation-skill-prompt.md @@ -14,7 +14,7 @@ You determine which quickstart, by slug, the current `rh-qs-ship` session applie **Input Parameters:** - `{user_message}`: the user's raw request for this session -- `{existing_slugs}`: list of slugs found under `.rhoai-qs/` (excluding `reports` and `blog-drafts`), gathered by the main agent via `ls ../ 2>/dev/null` (this skill runs inside `.rhoai-qs//`, so `../` is `.rhoai-qs/` itself) +- `{existing_slugs}`: list of slugs found under `.rhoai-qs/`, gathered by the main agent via `ls -1 ../ 2>/dev/null` (this skill runs inside `.rhoai-qs//`, so `../` is `.rhoai-qs/` itself) — every entry is a quickstart, nothing is filtered out - `{is_entry_point}`: always `false` for `rh-qs-ship` - `{calling_skill}`: `rh-qs-ship` diff --git a/core/skills/rh-qs-test-suite/SKILL.md b/core/skills/rh-qs-test-suite/SKILL.md index 8f08c9c..e29d982 100644 --- a/core/skills/rh-qs-test-suite/SKILL.md +++ b/core/skills/rh-qs-test-suite/SKILL.md @@ -14,7 +14,7 @@ description: | ## Trigger - Helm chart and Makefile deploy targets exist from **`rh-qs-deploy`** if not create it. -- Architecture spec **`designs/architecture-spec.yaml`** defines testing strategy (unit / integration / E2E / evals) — this skill runs inside `.rhoai-qs//` itself (the scaffolded quickstart repo), so the architecture spec sits right alongside the code, no `../` needed +- Architecture spec **`.qs-factory/designs/architecture-spec.yaml`** defines testing strategy (unit / integration / E2E / evals) — this skill runs inside `.rhoai-qs//` itself (the scaffolded quickstart repo), so the architecture spec is in `.qs-factory/` right there, no `../` needed - Optional: replace or extend minimal workflows from **`rh-qs-scaffold`** ## Nightly-only fast path @@ -158,7 +158,7 @@ For repos using **dev → main**: require `Validate PR comes from dev branch` on | **Agent + evals** | Standard + `pr-evaluation-check.yml` + eval artifact upload | | **Release train** | Full + `pr-branch-check.yml` + `build-and-push.yaml` + `create-dev-to-main-pr.yaml` + nightlies | -Match profile to the **Testing strategy** section in `designs/architecture-spec.yaml`. +Match profile to the **Testing strategy** section in `.qs-factory/designs/architecture-spec.yaml`. ## Verification diff --git a/core/skills/rh-qs-test-suite/references/makefile-ci-contract.md b/core/skills/rh-qs-test-suite/references/makefile-ci-contract.md index df8df2c..2c2d502 100644 --- a/core/skills/rh-qs-test-suite/references/makefile-ci-contract.md +++ b/core/skills/rh-qs-test-suite/references/makefile-ci-contract.md @@ -65,7 +65,7 @@ Examples from it-self-service-agent—replace with design-specific targets: ## Nightly contract (canonical names) -`subagents/nightly-tests-prompt.md` expects the canonical names `rh-qs-deploy`/`rh-qs-scaffold` already establish: `deploy` (install), `test`, `undeploy` (uninstall), `verify-deploy` (smoke test). Any quickstart that went through `rh-qs-deploy` should already have all three. For older quickstarts missing one, the subagent searches for an equivalent existing target (e.g. `install-full`, `helm-install-prod`, `e2e-ui`, `helm-uninstall`) rather than renaming anything — it uses whatever real name it finds and records the mapping in `pipeline/nightly-tests-manifest.yaml`. +`subagents/nightly-tests-prompt.md` expects the canonical names `rh-qs-deploy`/`rh-qs-scaffold` already establish: `deploy` (install), `test`, `undeploy` (uninstall), `verify-deploy` (smoke test). Any quickstart that went through `rh-qs-deploy` should already have all three. For older quickstarts missing one, the subagent searches for an equivalent existing target (e.g. `install-full`, `helm-install-prod`, `e2e-ui`, `helm-uninstall`) rather than renaming anything — it uses whatever real name it finds and records the mapping in `.qs-factory/pipeline/nightly-tests-manifest.yaml`. ## Environment variables workflows pass diff --git a/core/skills/rh-qs-test-suite/subagents/README.md b/core/skills/rh-qs-test-suite/subagents/README.md index 4f54f7f..dbc3179 100644 --- a/core/skills/rh-qs-test-suite/subagents/README.md +++ b/core/skills/rh-qs-test-suite/subagents/README.md @@ -2,4 +2,4 @@ | Name | Purpose | Input | Output | When used | Why subagent | |------|---------|-------|--------|-----------|---------------| -| `nightly-tests-prompt.md` | Generate a reusable `workflow_call` test workflow plus scheduled `nightly-main`/`nightly-` callers, copying shared composite actions from `quickstart-ci-testing`, a namespace/ServiceAccount provisioning script, and reports on required secrets/variables and toolchain setup | `slug`, `repo_root`, `invocation_mode` (`standalone` or `full-pipeline`) | `pipeline/nightly-tests-manifest.yaml` + a report (toolchain steps used, secrets/variables needed, cluster-admin warning if any, next steps) | Step 8 of the main `rh-qs-test-suite` workflow, or directly via the nightly-only fast path in `SKILL.md` when a quickstart already has CI and just needs nightly testing added or refreshed | Nightly generation is self-contained detection + file-generation logic (Makefile contract resolution, toolchain detection, secret discovery, cluster-admin scan, action copying) that the orchestrator shouldn't have to hold in its own context, and that also needs to be independently invokable without running the rest of the CI build-out | +| `nightly-tests-prompt.md` | Generate a reusable `workflow_call` test workflow plus scheduled `nightly-main`/`nightly-` callers, copying shared composite actions from `quickstart-ci-testing`, a namespace/ServiceAccount provisioning script, and reports on required secrets/variables and toolchain setup | `slug`, `repo_root`, `invocation_mode` (`standalone` or `full-pipeline`) | `.qs-factory/pipeline/nightly-tests-manifest.yaml` + a report (toolchain steps used, secrets/variables needed, cluster-admin warning if any, next steps) | Step 8 of the main `rh-qs-test-suite` workflow, or directly via the nightly-only fast path in `SKILL.md` when a quickstart already has CI and just needs nightly testing added or refreshed | Nightly generation is self-contained detection + file-generation logic (Makefile contract resolution, toolchain detection, secret discovery, cluster-admin scan, action copying) that the orchestrator shouldn't have to hold in its own context, and that also needs to be independently invokable without running the rest of the CI build-out | diff --git a/core/skills/rh-qs-test-suite/subagents/nightly-tests-prompt.md b/core/skills/rh-qs-test-suite/subagents/nightly-tests-prompt.md index 5b03130..4ee22ac 100644 --- a/core/skills/rh-qs-test-suite/subagents/nightly-tests-prompt.md +++ b/core/skills/rh-qs-test-suite/subagents/nightly-tests-prompt.md @@ -124,7 +124,7 @@ Write `.github/workflows/nightly-main.yml` and, only if Step 5 found a dev branc ### Step 10: Write the manifest -Write `pipeline/nightly-tests-manifest.yaml`: +Write `.qs-factory/pipeline/nightly-tests-manifest.yaml`: ```yaml slug: @@ -174,4 +174,4 @@ Summarize what was created/updated/skipped, then always include: ## Output -`pipeline/nightly-tests-manifest.yaml` (schema above) plus the report described in Step 11, returned as your final message to the orchestrator. +`.qs-factory/pipeline/nightly-tests-manifest.yaml` (schema above) plus the report described in Step 11, returned as your final message to the orchestrator. diff --git a/core/skills/rh-qs-verify-deploy/SKILL.md b/core/skills/rh-qs-verify-deploy/SKILL.md index 0a877b6..5009220 100644 --- a/core/skills/rh-qs-verify-deploy/SKILL.md +++ b/core/skills/rh-qs-verify-deploy/SKILL.md @@ -37,14 +37,14 @@ Closes the **biggest pipeline gap**: validating that the quickstart actually wor 3. Runs optional **`helm test`** hooks if the chart defines them 4. Validates **security smoke checks** from **`rh-qs-secure`** (no plaintext secrets in running config) 5. Exercises the **primary user journey** at minimum (API call or UI smoke — as defined in PRD) -6. Writes **`reports/verify-deploy-.md`** with pass/fail evidence +6. Writes **`.qs-factory/reports/verify-deploy-.md`** with pass/fail evidence 7. Only when verification passes → hand off to **`rh-qs-document`** ## Workflow ### Phase 0: Resolve Quickstart Context -Before doing anything, resolve which quickstart this session is for. Run `ls ../ 2>/dev/null` (excluding `reports` and `blog-drafts`) and spawn the **validation-skill subagent**: +Before doing anything, resolve which quickstart this session is for. Run `ls -1 ../ 2>/dev/null` (every entry is a quickstart — no filtering) and spawn the **validation-skill subagent**: ```python Agent( @@ -82,7 +82,7 @@ Add to the quickstart repo during **`rh-qs-deploy`**: ```makefile RELEASE ?= -CHART_DIR ?= deploy/helm/$(RELEASE) +CHART_DIR ?= chart NAMESPACE ?= -demo deploy: ## helm upgrade --install (only cluster entry point) @@ -92,6 +92,11 @@ helm-lint: helm-template: ``` +`CHART_DIR` is the single source of truth for the chart path — every target and +every doc that needs it reads `$(CHART_DIR)`, never a literal path. The chart sits +at `chart/` because that is where `ai-quickstart-template` puts it and what the +catalog tooling expects. + `verify-deploy` should: - Wait for Deployment rollout (via `helm status` / chart hooks / scripted health URL) @@ -101,7 +106,7 @@ helm-template: ## Verification report template -Save to **`reports/verify-deploy-YYYY-MM-DD.md`**: +Save to **`.qs-factory/reports/verify-deploy-YYYY-MM-DD.md`**: ```markdown # Verify deploy — @@ -153,5 +158,5 @@ When verification report is green → **`rh-qs-document`** (docs must match veri - [Agent permissions](../rh-qs-secure/references/agent-permissions.md) - [Application security](../rh-qs-secure/references/application-security.md) - [Makefile CI contract](../rh-qs-test-suite/references/makefile-ci-contract.md) -- Architecture spec: `designs/architecture-spec.yaml` +- Architecture spec: `.qs-factory/designs/architecture-spec.yaml` - [subagents/validation-skill-prompt.md](./subagents/validation-skill-prompt.md) — pass by file path only, do NOT read directly diff --git a/core/skills/rh-qs-verify-deploy/subagents/README.md b/core/skills/rh-qs-verify-deploy/subagents/README.md index d9accc3..46ab739 100644 --- a/core/skills/rh-qs-verify-deploy/subagents/README.md +++ b/core/skills/rh-qs-verify-deploy/subagents/README.md @@ -10,7 +10,7 @@ This directory contains the `validation-skill` subagent used by `rh-qs-verify-de |-------|-------------| | **Name** | `validation-skill-prompt.md` | | **Purpose** | Resolve which quickstart (by slug) this session applies to | -| **Input** | User's raw message, list of existing slugs under `../` (excluding `reports` and `blog-drafts`), `is_entry_point: false`, calling skill name | +| **Input** | User's raw message, list of existing slugs under `../` (every entry is a quickstart), `is_entry_point: false`, calling skill name | | **Output** | Resolution status as JSON — resolved/needs_user_input/error, with slug and confidence | | **When used** | Phase 0 — before reading the design doc or writing the verification report | | **Why subagent** | Mechanical slug matching against a list, self-contained — see [validation-skill-template.md](../../../../docs/foundation/validation-skill-template.md) for the full spec | diff --git a/core/skills/rh-qs-verify-deploy/subagents/validation-skill-prompt.md b/core/skills/rh-qs-verify-deploy/subagents/validation-skill-prompt.md index 3d80d7d..5bc22b8 100644 --- a/core/skills/rh-qs-verify-deploy/subagents/validation-skill-prompt.md +++ b/core/skills/rh-qs-verify-deploy/subagents/validation-skill-prompt.md @@ -14,7 +14,7 @@ You determine which quickstart, by slug, the current `rh-qs-verify-deploy` sessi **Input Parameters:** - `{user_message}`: the user's raw request for this session -- `{existing_slugs}`: list of slugs found under `.rhoai-qs/` (excluding `reports` and `blog-drafts`), gathered by the main agent via `ls ../ 2>/dev/null` (this skill runs inside `.rhoai-qs/<slug>/`, so `../` is `.rhoai-qs/` itself) +- `{existing_slugs}`: list of slugs found under `.rhoai-qs/`, gathered by the main agent via `ls -1 ../ 2>/dev/null` (this skill runs inside `.rhoai-qs/<slug>/`, so `../` is `.rhoai-qs/` itself) — every entry is a quickstart, nothing is filtered out - `{is_entry_point}`: always `false` for `rh-qs-verify-deploy` - `{calling_skill}`: `rh-qs-verify-deploy` diff --git a/core/subagents/kb-retrieval/kb-retrieval-pipeline-prompt.md b/core/subagents/kb-retrieval/kb-retrieval-pipeline-prompt.md index 802a0be..45c06b5 100644 --- a/core/subagents/kb-retrieval/kb-retrieval-pipeline-prompt.md +++ b/core/subagents/kb-retrieval/kb-retrieval-pipeline-prompt.md @@ -195,10 +195,10 @@ Read the top-N results from `.tmp/{slug}/kb-indexes/top-kb-entries.yaml`. Create the output directory and file: ```bash -mkdir -p ".rhoai-qs/{slug}/pipeline" +mkdir -p ".rhoai-qs/{slug}/.qs-factory/pipeline" ``` -Write the file `.rhoai-qs/{slug}/pipeline/kb-scores.yaml` with this structure: +Write the file `.rhoai-qs/{slug}/.qs-factory/pipeline/kb-scores.yaml` with this structure: ```yaml knowledge_base_root: core/skills/qs-extract-knowledge/knowledge-base diff --git a/docs/ADR-001 Implementation Tasks.md b/docs/ADR-001 Implementation Tasks.md index b403ece..1404693 100644 --- a/docs/ADR-001 Implementation Tasks.md +++ b/docs/ADR-001 Implementation Tasks.md @@ -5,6 +5,13 @@ Date: 2026-06-28 Authors: Matan Talvi, Yossi Elias ``` +> **Partially superseded — file layout only.** Every `.rhoai-qs/<slug>/pipeline/`, +> `prds/`, `designs/`, and `reports/` path in this document has since moved under +> `.rhoai-qs/<slug>/.qs-factory/`, and the Helm chart from `deploy/helm/<slug>/` to +> `chart/`. This record is kept as written — it documents the tasks as planned, not +> the current layout. For the layout in force, see +> [foundation/pipeline-convention.md](foundation/pipeline-convention.md). + ## Dependency Graph diff --git a/docs/ADR.md b/docs/ADR.md index 2a54159..b5a1029 100644 --- a/docs/ADR.md +++ b/docs/ADR.md @@ -6,6 +6,13 @@ Date: 2026-06-24 Authors: Matan Talvi, Yossi Elias ``` +> **Partially superseded — file layout only.** Every `.rhoai-qs/<slug>/pipeline/`, +> `prds/`, `designs/`, `reports/`, and `deploy/helm/<slug>/` path in this document +> has since moved: factory bookkeeping now lives under `.rhoai-qs/<slug>/.qs-factory/` +> and the Helm chart at `chart/`. This record is kept as written — it documents the +> decision as taken, not the current layout. For the layout in force, see +> [foundation/pipeline-convention.md](foundation/pipeline-convention.md). + ## Context The Quickstart Factory currently operates a 7-stage pipeline with 10 skills (7 pipeline + 3 utility). Each skill is a flat `SKILL.md` that the agent reads and follows directly — no subagent orchestration, no feedback loops, no validation beyond `make lint && make test`, no hooks, and no knowledge base. @@ -105,6 +112,11 @@ Every skill that produces artifacts validates its output and iterates on failure ### Pattern 4: Persistent-File Handoff +> **Superseded by [foundation/pipeline-convention.md](foundation/pipeline-convention.md).** +> The handoff mechanism stands; the paths below do not. All bookkeeping has since +> been consolidated under `.rhoai-qs/<slug>/.qs-factory/` — so e.g. the Discovery → +> Architect handoff is now `.rhoai-qs/<slug>/.qs-factory/prds/prd.md`. + Skills pass structured artifacts to each other via files in `.rhoai-qs/`, not conversation context — this matters because each skill typically runs in its own separate chat session. **Namespace scoping:** All pipeline files are scoped to a quickstart-specific directory: `.rhoai-qs/<slug>/pipeline/` (e.g., `.rhoai-qs/spending-transaction-monitor/pipeline/`), inside the `quickstart-factory` repo itself. This prevents name clashes between different quickstarts and preserves context from previous runs when resuming. Every skill resolves `<slug>` via the `validation-skill` subagent (Phase 0) before touching any of these files — see [pipeline-convention.md](foundation/pipeline-convention.md) and [validation-skill-template.md](foundation/validation-skill-template.md). diff --git a/docs/NEW_QUICKSTART_SKILLS.md b/docs/NEW_QUICKSTART_SKILLS.md index b071269..b1e8029 100644 --- a/docs/NEW_QUICKSTART_SKILLS.md +++ b/docs/NEW_QUICKSTART_SKILLS.md @@ -22,9 +22,9 @@ flowchart TB Sh["7. rh-qs-ship<br/>Docs → PR → announce"] Input --> D - D -->|"PRD<br/>.rhoai-qs/<slug>/prds/prd.md"| A + D -->|"PRD<br/>.rhoai-qs/<slug>/.qs-factory/prds/prd.md"| A A --> Sec - Sec -->|"Architecture spec + security<br/>.rhoai-qs/<slug>/designs/architecture-spec.yaml"| S + Sec -->|"Architecture spec + security<br/>.rhoai-qs/<slug>/.qs-factory/designs/architecture-spec.yaml"| S S -->|"GitHub repo + CI/CD"| I I -->|"Working app"| VB VB --> Dep @@ -38,15 +38,15 @@ flowchart TB | Stage | Skill | Output | Location | |-------|-------|--------|----------| -| 1 | rh-qs-discovery | `.rhoai-qs/<slug>/prds/prd.md` | `core/skills/rh-qs-discovery/` | -| 2 | rh-qs-architect | `.rhoai-qs/<slug>/designs/architecture-spec.yaml` | `core/skills/rh-qs-architect/` | +| 1 | rh-qs-discovery | `.rhoai-qs/<slug>/.qs-factory/prds/prd.md` | `core/skills/rh-qs-discovery/` | +| 2 | rh-qs-architect | `.rhoai-qs/<slug>/.qs-factory/designs/architecture-spec.yaml` | `core/skills/rh-qs-architect/` | | 2b | rh-qs-secure | Security guidance during architecture | `core/skills/rh-qs-secure/` | | 3 | rh-qs-scaffold | GitHub repo + CI/CD | `core/skills/rh-qs-scaffold/` | | 4 | rh-qs-implement | Working application code | `core/skills/rh-qs-implement/` | | 4b | rh-qs-verify-build | Local build verified | `core/skills/rh-qs-verify-build/` | | 5 | rh-qs-deploy | Helm chart + compose.yml | `core/skills/rh-qs-deploy/` | | 5b | rh-qs-test-suite | GitHub Actions (PR/E2E/nightly) | `core/skills/rh-qs-test-suite/` | -| 5c | rh-qs-verify-deploy | `.rhoai-qs/<slug>/reports/verify-deploy-*.md` | `core/skills/rh-qs-verify-deploy/` | +| 5c | rh-qs-verify-deploy | `.rhoai-qs/<slug>/.qs-factory/reports/verify-deploy-*.md` | `core/skills/rh-qs-verify-deploy/` | | 6 | rh-qs-document | README.md + docs/ | `core/skills/rh-qs-document/` | | 7 | rh-qs-ship | PR URL + blog draft | `core/skills/rh-qs-ship/` | diff --git a/docs/foundation/acceptance-criteria.md b/docs/foundation/acceptance-criteria.md index d5fed83..94db1ae 100644 --- a/docs/foundation/acceptance-criteria.md +++ b/docs/foundation/acceptance-criteria.md @@ -234,6 +234,6 @@ Note: all criteria for `rh-qs-implement` are `requires_user_approval: false` bec ## Relationship to Other Foundation Docs - **[spec-as-contract.md](spec-as-contract.md)** — defines the `acceptance_criteria` and `validation_rules` fields within the spec format, and the post-implementation validation flow -- **[pipeline-convention.md](pipeline-convention.md)** — specs containing acceptance criteria live in `.rhoai-qs/<slug>/pipeline/` +- **[pipeline-convention.md](pipeline-convention.md)** — specs containing acceptance criteria live in `.rhoai-qs/<slug>/.qs-factory/pipeline/` - **[pipeline-contracts.md](pipeline-contracts.md)** — handoff manifests may reference acceptance criteria results from upstream skills - **[reasoning-guardrails-template.md](reasoning-guardrails-template.md)** — guardrails are concern areas the agent reasons about organically; acceptance criteria are concrete, verifiable pass/fail checks diff --git a/docs/foundation/pipeline-contracts.md b/docs/foundation/pipeline-contracts.md index 5f4d7ad..4f08c2b 100644 --- a/docs/foundation/pipeline-contracts.md +++ b/docs/foundation/pipeline-contracts.md @@ -2,7 +2,7 @@ This document defines the YAML schema for each inter-skill handoff file. These contracts specify exactly what each file contains, which skill produces it, and which skill consumes it — enabling skills to be developed and validated independently. -Every handoff file follows the common header defined in [spec-as-contract.md](spec-as-contract.md) and lives in the quickstart's `.rhoai-qs/<slug>/pipeline/` directory as defined in [pipeline-convention.md](pipeline-convention.md). +Every handoff file follows the common header defined in [spec-as-contract.md](spec-as-contract.md) and lives in the quickstart's `.rhoai-qs/<slug>/.qs-factory/pipeline/` directory as defined in [pipeline-convention.md](pipeline-convention.md). ## Common Header @@ -24,15 +24,15 @@ The pipeline passes structured artifacts through these files, in order: | # | File | Producer | Consumer | Category | Location | |---|------|----------|----------|----------|----------| -| 1 | `architecture-spec.yaml` | rh-qs-architect | rh-qs-scaffold | Spec | `.rhoai-qs/<slug>/designs/` | -| 2 | `scaffold-manifest.yaml` | rh-qs-scaffold | rh-qs-implement | Manifest | `.rhoai-qs/<slug>/pipeline/` | -| 3 | `implementation-manifest.yaml` | rh-qs-implement | rh-qs-deploy | Manifest | `.rhoai-qs/<slug>/pipeline/` | -| 4 | `deploy-manifest.yaml` | rh-qs-deploy | rh-qs-security | Manifest | `.rhoai-qs/<slug>/pipeline/` | -| 5 | `security-report.yaml` | rh-qs-security | rh-qs-debug-and-deploy | Report | `.rhoai-qs/<slug>/pipeline/` | -| 6 | `deploy-state.yaml` | rh-qs-debug-and-deploy | rh-qs-document | State | `.rhoai-qs/<slug>/pipeline/` | -| 7 | `doc-manifest.yaml` | rh-qs-document | rh-qs-ship | Manifest | `.rhoai-qs/<slug>/pipeline/` | +| 1 | `architecture-spec.yaml` | rh-qs-architect | rh-qs-scaffold | Spec | `.rhoai-qs/<slug>/.qs-factory/designs/` | +| 2 | `scaffold-manifest.yaml` | rh-qs-scaffold | rh-qs-implement | Manifest | `.rhoai-qs/<slug>/.qs-factory/pipeline/` | +| 3 | `implementation-manifest.yaml` | rh-qs-implement | rh-qs-deploy | Manifest | `.rhoai-qs/<slug>/.qs-factory/pipeline/` | +| 4 | `deploy-manifest.yaml` | rh-qs-deploy | rh-qs-security | Manifest | `.rhoai-qs/<slug>/.qs-factory/pipeline/` | +| 5 | `security-report.yaml` | rh-qs-security | rh-qs-debug-and-deploy | Report | `.rhoai-qs/<slug>/.qs-factory/pipeline/` | +| 6 | `deploy-state.yaml` | rh-qs-debug-and-deploy | rh-qs-document | State | `.rhoai-qs/<slug>/.qs-factory/pipeline/` | +| 7 | `doc-manifest.yaml` | rh-qs-document | rh-qs-ship | Manifest | `.rhoai-qs/<slug>/.qs-factory/pipeline/` | -Additionally, the PRD (`.rhoai-qs/<slug>/prds/prd.md`) produced by rh-qs-discovery is a Markdown file, not YAML, and its format is defined by the PRD template — not this document. +Additionally, the PRD (`.rhoai-qs/<slug>/.qs-factory/prds/prd.md`) produced by rh-qs-discovery is a Markdown file, not YAML, and its format is defined by the PRD template — not this document. --- @@ -41,7 +41,7 @@ Additionally, the PRD (`.rhoai-qs/<slug>/prds/prd.md`) produced by rh-qs-discove **Producer:** rh-qs-architect **Consumer:** rh-qs-scaffold **Category:** Spec -**Location:** `.rhoai-qs/<slug>/designs/architecture-spec.yaml` +**Location:** `.rhoai-qs/<slug>/.qs-factory/designs/architecture-spec.yaml` Documents the architecture decisions, component bill of materials, technology stack, and testing strategy for a quickstart. @@ -105,7 +105,7 @@ integration_patterns: - point: "Secrets" mechanism: "OpenShift secrets for DB credentials and model API keys" -architecture_diagram_path: .rhoai-qs/spending-transaction-monitor/designs/architecture-diagram.mmd +architecture_diagram_path: .rhoai-qs/spending-transaction-monitor/.qs-factory/designs/architecture-diagram.mmd testing_strategy: profile: standard @@ -127,13 +127,13 @@ testing_strategy: runs_on: "Every PR" dependencies: - - spec: .rhoai-qs/spending-transaction-monitor/prds/prd.md + - spec: .rhoai-qs/spending-transaction-monitor/.qs-factory/prds/prd.md fields_used: [problem_statement, target_persona, technology_constraints] content_hash: "sha256:..." - - spec: .rhoai-qs/spending-transaction-monitor/pipeline/prd-features.yaml + - spec: .rhoai-qs/spending-transaction-monitor/.qs-factory/pipeline/prd-features.yaml fields_used: [input_features, deployment_questions, decision_points] content_hash: "sha256:..." - - spec: .rhoai-qs/spending-transaction-monitor/pipeline/kb-scores.yaml + - spec: .rhoai-qs/spending-transaction-monitor/.qs-factory/pipeline/kb-scores.yaml fields_used: [results] content_hash: "sha256:..." ``` @@ -163,7 +163,7 @@ dependencies: | `integration_patterns.security_boundaries` | list | yes | Security considerations at component boundaries | | `integration_patterns.security_boundaries[].point` | string | yes | Boundary or security checkpoint name | | `integration_patterns.security_boundaries[].mechanism` | string | yes | Security approach (auth, secrets, policy, isolation, etc.) | -| `architecture_diagram_path` | string | yes | Path to Mermaid diagram file (e.g., `.rhoai-qs/<slug>/designs/architecture-diagram.mmd`) | +| `architecture_diagram_path` | string | yes | Path to Mermaid diagram file (e.g., `.rhoai-qs/<slug>/.qs-factory/designs/architecture-diagram.mmd`) | | `testing_strategy` | map | yes | Testing levels and scope (no tool commands) | | `dependencies` | list | yes | Upstream specs with content_hash | @@ -381,16 +381,16 @@ skill: rh-qs-deploy created_at: "2026-07-01T16:00:00Z" helm: - chart_path: deploy/helm + chart_path: chart dependencies: - name: llm-service chart: ai-architecture-charts/llm-service version: "0.3.0" - values_file: deploy/helm/values-llm.yaml + values_file: chart/values-llm.yaml - name: pgvector chart: ai-architecture-charts/pgvector version: "0.2.1" - values_file: deploy/helm/values-pgvector.yaml + values_file: chart/values-pgvector.yaml validation: helm_lint: pass helm_template: pass @@ -488,16 +488,16 @@ overall_status: PASS | PASS_WITH_WARNINGS | BLOCKED scanners: code: status: PASS | FAIL - source_file: .rhoai-qs/spending-transaction-monitor/pipeline/qs-security-code.yaml + source_file: .rhoai-qs/spending-transaction-monitor/.qs-factory/pipeline/qs-security-code.yaml containers: status: PASS | FAIL - source_file: .rhoai-qs/spending-transaction-monitor/pipeline/qs-security-containers.yaml + source_file: .rhoai-qs/spending-transaction-monitor/.qs-factory/pipeline/qs-security-containers.yaml helm: status: PASS | FAIL - source_file: .rhoai-qs/spending-transaction-monitor/pipeline/qs-security-helm.yaml + source_file: .rhoai-qs/spending-transaction-monitor/.qs-factory/pipeline/qs-security-helm.yaml dependencies: status: PASS | FAIL - source_file: .rhoai-qs/spending-transaction-monitor/pipeline/qs-security-deps.yaml + source_file: .rhoai-qs/spending-transaction-monitor/.qs-factory/pipeline/qs-security-deps.yaml findings: - id: sec-1 @@ -606,7 +606,7 @@ debug_history: root_cause_category: config fix_applied: "Added env var from Kubernetes Secret" fix_files: - - deploy/helm/values-api.yaml + - chart/values-api.yaml resolved: true - resource: llm-service attempts: 0 @@ -674,7 +674,7 @@ Lists all documentation files produced and their validation status. ### Schema ```yaml -spec_version: 1 +spec_version: 2 quickstart_name: "Spending Transaction Monitor" slug: spending-transaction-monitor skill: rh-qs-document @@ -700,6 +700,17 @@ documentation: source: implementation-manifest.yaml - name: Deployment status: complete + - name: Tags + status: complete + + tags: + title: "Spending Transaction Monitor" # matches H1, <= 64 chars + description: "Flag anomalous card transactions in real time with an on-cluster LLM" # matches short description, <= 160 chars + industry: "Financial Services" # exactly one + product: "OpenShift AI" + use_case: "fraud detection, anomaly detection" + partner: "N/A" # present even when empty + contributor_org: "Red Hat" additional_files: - path: TEST-PLAN.md @@ -713,6 +724,8 @@ validation: all_make_targets_exist: true all_urls_well_formed: true diagram_matches_components: true + no_contributor_todo_remaining: true + tags_complete: true user_approved: true dependencies: @@ -739,13 +752,27 @@ dependencies: | `documentation.readme.sections[].name` | string | yes | Section name | | `documentation.readme.sections[].status` | enum | yes | `complete`, `draft`, or `missing` | | `documentation.additional_files` | list | no | Other docs produced (TEST-PLAN.md, CONTRIBUTING.md, etc.) | +| `documentation.tags` | map | yes | The README's `## Tags` block, mirrored for machine checking | +| `documentation.tags.title` | string | yes | Matches the README H1; ≤ 64 chars | +| `documentation.tags.description` | string | yes | Matches the short description; ≤ 160 chars | +| `documentation.tags.industry` | string | yes | Exactly one industry from the catalog's list | +| `documentation.tags.product` | string | yes | Primary Red Hat product | +| `documentation.tags.use_case` | string | yes | Short use-case descriptor | +| `documentation.tags.partner` | string | yes | Partner names, or `N/A` — the key must be present | +| `documentation.tags.contributor_org` | string | yes | Contributing organization | | `validation` | map | yes | Documentation validation checks | | `validation.all_make_targets_exist` | boolean | yes | Every `make` target in README exists in Makefile | | `validation.all_urls_well_formed` | boolean | yes | All URLs are syntactically valid | | `validation.diagram_matches_components` | boolean | yes | Architecture diagram matches component list | +| `validation.no_contributor_todo_remaining` | boolean | yes | `grep -c 'CONTRIBUTOR TODO' README.md` is 0 | +| `validation.tags_complete` | boolean | yes | Every `documentation.tags` field present and within its limit | | `validation.user_approved` | boolean | yes | User reviewed and approved the documentation | | `dependencies` | list | yes | Upstream specs/manifests with `content_hash` | +### Changes in spec_version 2 + +Added `documentation.tags` and the `validation.tags_complete` / `validation.no_contributor_todo_remaining` booleans. `rh-qs-document` now fills in the template's `README.md` in place rather than generating one, so the `## Tags` block redhat.com publication requires is present from the start — these fields make "present" machine-checkable instead of a thing someone notices at submission time. + --- ## Schema Evolution @@ -761,7 +788,7 @@ Consuming skills must check `spec_version` on read and fail with a clear error i ## Relationship to Other Foundation Docs - **[spec-as-contract.md](spec-as-contract.md)** — defines the common spec format; `architecture-spec.yaml` (file #1) uses a simplified architect-specific schema documented in section 1 above and in `core/skills/rh-qs-architect/references/architecture-spec-template.yaml` -- **[pipeline-convention.md](pipeline-convention.md)** — defines the `.rhoai-qs/<slug>/pipeline/` directory where all these files live +- **[pipeline-convention.md](pipeline-convention.md)** — defines the `.rhoai-qs/<slug>/.qs-factory/pipeline/` directory where all these files live - **[skill-directory-structure.md](skill-directory-structure.md)** — each skill's `spec-template.md` defines skill-specific fields within these schemas - **[acceptance-criteria.md](acceptance-criteria.md)** — defines how `acceptance_criteria` sections in specs are validated - **[validation-skill-template.md](validation-skill-template.md)** — how `<slug>` is resolved before any of these files are read or written diff --git a/docs/foundation/pipeline-convention.md b/docs/foundation/pipeline-convention.md index d043bb1..5d5556d 100644 --- a/docs/foundation/pipeline-convention.md +++ b/docs/foundation/pipeline-convention.md @@ -1,104 +1,115 @@ # Pipeline File Convention -This document defines how factory skills store and pass structured artifacts between pipeline stages, and where each quickstart's actual code lives. Everything for a given quickstart — pipeline specs, PRD, architecture spec, blog drafts, reports, **and its application code** — lives together in one place inside the **`quickstart-factory`** repo, namespaced by quickstart slug. This ensures a full audit trail that survives reboots and is deleted only when the user chooses. +This document defines how factory skills store and pass structured artifacts between pipeline stages, and where each quickstart's actual code lives. Everything for a given quickstart — pipeline specs, PRD, architecture spec, reports, **and its application code** — lives together in one place inside the **`quickstart-factory`** repo, namespaced by quickstart slug. This ensures a full audit trail that survives reboots and is deleted only when the user chooses. ## Why Everything Lives Under `.rhoai-qs/<slug>/` -Every skill's bookkeeping — specs, manifests, PRDs, designs, blog drafts, reports — and the quickstart's scaffolded application code (created by `rh-qs-scaffold`) live together under one folder: `quickstart-factory/.rhoai-qs/<slug>/`. One canonical location per quickstart means every skill can always find everything it needs without hopping between repos or guessing where things are on disk. +Every skill's bookkeeping — specs, manifests, PRDs, designs, reports — and the quickstart's own application code live together under one folder: `quickstart-factory/.rhoai-qs/<slug>/`. One canonical location per quickstart means every skill can always find everything it needs without hopping between repos or guessing where things are on disk. -Because `.rhoai-qs/` now holds data for **every** quickstart ever worked on, every skill must first determine *which* quickstart the current session applies to. See [Resolving the Quickstart Slug](#resolving-the-quickstart-slug). +Because `.rhoai-qs/` holds data for **every** quickstart ever worked on, every skill must first determine *which* quickstart the current session applies to. See [Resolving the Quickstart Slug](#resolving-the-quickstart-slug). -## Directory Structure +## The Two Invariants -All quickstart-scoped files — bookkeeping and code alike — live under: +Everything else in this document follows from these two rules: -``` -quickstart-factory/.rhoai-qs/<slug>/ -``` +1. **Every direct child of `.rhoai-qs/` is a quickstart.** Nothing else lives there — no cross-cutting reports, no shared drafts, no scratch folders. Slug resolution is therefore a plain directory listing, with no allowlist, denylist, or filter step. +2. **All factory bookkeeping lives in exactly one folder per quickstart: `.qs-factory/`.** It has no exceptions — nothing inside it survives `rh-qs-ship`, so a single rule can track it, ignore it, or delete it. -**Example:** `quickstart-factory/.rhoai-qs/mortgage-processor/` +## Directory Structure -Two things that are **not** about any single quickstart live directly under `.rhoai-qs/` itself, as siblings of the slug folders — see [Cross-Cutting Locations](#cross-cutting-locations): +`quickstart-factory/.rhoai-qs/<slug>/` **is the quickstart's git repo root.** It is one of two things: -``` -quickstart-factory/.rhoai-qs/reports/ -quickstart-factory/.rhoai-qs/blog-drafts/ -``` +- a **real directory**, seeded by `rh-qs-discovery` from the org template (the normal case), or +- a **symlink** to a repo living elsewhere on disk, for a quickstart you already had checked out before adopting this convention. + +Both shapes behave identically for every skill: `ls`, `cd`, and relative paths all work through a symlink, and the checkpoint's dashboard links are computed relative to the dashboard itself, so they stay correct either way. + +**Example:** `quickstart-factory/.rhoai-qs/mortgage-processor/` The `.rhoai-qs/` directory is gitignored by the factory repo, so none of this ever ends up in the factory's own commits. (The quickstart's own code, however, is committed to its own separate repo — see [Nested Quickstart Repos](#nested-quickstart-repos).) ### Full Layout ``` -quickstart-factory/.rhoai-qs/ -├── mortgage-processor/ -│ ├── pipeline/ -│ │ ├── discovery-spec.yaml -│ │ ├── scaffold-spec.yaml -│ │ ├── scaffold-manifest.yaml # Handoff to implement -│ │ ├── implementation-spec.yaml -│ │ ├── implementation-manifest.yaml # Handoff to deploy -│ │ ├── deploy-spec.yaml -│ │ ├── deploy-manifest.yaml # Handoff to security -│ │ ├── security-report.yaml # Handoff to debug-and-deploy -│ │ ├── deploy-state.yaml # Handoff to document -│ │ └── doc-manifest.yaml # Handoff to ship -│ ├── prds/ -│ │ └── prd.md -│ ├── designs/ -│ │ ├── architecture-spec.yaml # Also the handoff to scaffold -│ │ └── architecture-diagram.mmd -│ ├── blog-drafts/ -│ │ └── 2026-07-29.md -│ ├── reports/ -│ │ └── verify-deploy-2026-07-29.md -│ │ -│ ├── packages/api/ # ─┐ -│ ├── packages/ui/ # │ the quickstart's own -│ ├── deploy/helm/ # │ application code — -│ ├── .github/workflows/ # │ a separate git repo, -│ ├── .git/ # │ set up here by -│ ├── Makefile # │ rh-qs-scaffold -│ └── README.md # ─┘ +quickstart-factory/ +├── .blog-drafts/ ← gitignored; factory-side, slug-prefixed +│ └── mortgage-processor-2026-03-11.md +├── .reports/ ← gitignored; cross-cutting reports +│ └── grooming-report-2026-03-11.md │ -├── spending-transaction-monitor/ -│ └── ... (same shape — pipeline + prd + design + code, all together) -│ -├── reports/ ← cross-cutting, not tied to one quickstart -│ ├── gap-analysis-2026-07-29.md -│ └── grooming-report-2026-07-29.md -│ -└── blog-drafts/ ← fallback for quickstarts predating this convention - └── vllm-cpu-2025-03-11.md +└── .rhoai-qs/ ← gitignored; QUICKSTARTS ONLY, nothing else + └── mortgage-processor/ ← the quickstart's own git repo root + ├── .git/ ← (or a symlink to a repo elsewhere) + │ + ├── .qs-factory/ ◄══ ALL factory bookkeeping, one folder + │ ├── prds/ + │ │ └── prd.md + │ ├── designs/ + │ │ ├── architecture-spec.yaml # Also the handoff to scaffold + │ │ └── architecture-diagram.mmd + │ ├── pipeline/ + │ │ ├── discovery-spec.yaml + │ │ ├── scaffold-spec.yaml + │ │ ├── scaffold-manifest.yaml # Handoff to implement + │ │ ├── implementation-spec.yaml + │ │ ├── implementation-manifest.yaml # Handoff to deploy + │ │ ├── deploy-spec.yaml + │ │ ├── deploy-manifest.yaml # Handoff to security + │ │ ├── security-report.yaml # Handoff to debug-and-deploy + │ │ ├── deploy-state.yaml # Handoff to document + │ │ └── doc-manifest.yaml # Handoff to ship + │ ├── flow/ + │ │ └── dashboard.md # pipeline-checkpoint.py + │ └── reports/ + │ └── verify-deploy-2026-07-29.md + │ + ├── chart/ ─┐ + │ ├── Chart.yaml │ seeded from + │ ├── values.yaml │ rh-ai-quickstart/ + │ └── templates/ │ ai-quickstart-template + ├── docs/images/ │ by rh-qs-discovery + ├── LICENSE │ + └── README.md ─┘ (catalog skeleton, incl. ## Tags) + + ── added later by scaffold / implement / deploy ── + packages/{api,ui,db}/ · .github/workflows/ · tests/ + Makefile · compose.yml · turbo.json · .env.example ``` -There is no separate sibling folder for the code anymore — `.rhoai-qs/<slug>/` **is** the quickstart's repo root, with the factory's bookkeeping folders (`pipeline/`, `prds/`, `designs/`, `blog-drafts/`, `reports/`) sitting alongside the application code (`packages/`, `deploy/`, etc.) inside it. +Note what is **not** there: no `blog-drafts/` inside the quickstart (drafts are factory-side working material — see [Factory-Side Locations](#factory-side-locations)), and no sibling folders under `.rhoai-qs/` itself. ## Nested Quickstart Repos -`rh-qs-scaffold` creates each quickstart as its own GitHub repository (`rh-ai-quickstart/<slug>`) and turns `quickstart-factory/.rhoai-qs/<slug>/` into that repo's working directory. This folder has its own `.git/`, its own remote, its own commit history and CI, independent of the factory repo. +`rh-qs-discovery` seeds `quickstart-factory/.rhoai-qs/<slug>/` from the org template as a **local** git repo as soon as the slug is minted. The **user** pushes it to `rh-ai-quickstart/<slug>` after approving the PRD. From then on this folder has its own `.git/`, its own remote, its own commit history and CI, independent of the factory repo. -**Important:** this folder already contains `pipeline/`, `prds/`, `designs/` from earlier phases by the time scaffold runs, so it is never empty — `git clone` (and `gh repo create ... --clone`) would refuse to clone into it. `rh-qs-scaffold` instead creates the GitHub repo separately, then runs `git init` + `git remote add` directly inside the existing folder (see `rh-qs-scaffold/SKILL.md` for the exact steps, including the template-repo variant). +`rh-qs-scaffold` does not create the repo — it verifies the remote is set and adds the application scaffolding on top of the template. -### The bookkeeping folders are tracked, not gitignored +### `.qs-factory/` is tracked, not gitignored -`pipeline/`, `prds/`, `designs/`, `blog-drafts/`, `reports/` live inside this same repo and are **committed and pushed like everything else** throughout development — they are deliberately **not** added to the quickstart's own `.gitignore`. This is intentional: it lets the team collaborate on the PRD, design doc, and pipeline state through normal pull requests (reviewing a design doc together, discussing an open question in the PRD, etc.), not just on whichever engineer's machine happened to run the factory pipeline. +`.qs-factory/` lives inside the quickstart's own repo and is **committed and pushed like everything else** throughout development — it is deliberately **not** added to the quickstart's `.gitignore`. This is intentional: it lets the team collaborate on the PRD, design doc, and pipeline state through normal pull requests (reviewing a design doc together, discussing an open question in the PRD, etc.), not just on whichever engineer's machine happened to run the factory pipeline. -`pipeline/`, `prds/`, `designs/`, and `reports/` get removed as a **final cleanup step in `rh-qs-ship`**, right before the quickstart is considered done — so the finished, published repo doesn't carry this internal bookkeeping, but the team had full visibility into it while the work was in progress. `blog-drafts/` is deliberately excluded from that same cleanup pass, since the draft is generated by `rh-qs-ship` itself and still needs human review before publication — it's left for the user to remove once the post actually goes out. See `rh-qs-ship/SKILL.md` for the exact steps. +It is removed **wholesale** as a final cleanup step in `rh-qs-ship`, right before the quickstart is considered done: -This is a **separate concern** from the factory's own `.gitignore`, which simply ignores `.rhoai-qs/` as one blanket rule (see the factory's `.gitignore`) — git never looks inside an ignored directory, so it never notices there's another repo nested inside it, and the two repos' git histories don't interact. +```bash +git rm -r --ignore-unmatch .qs-factory +``` + +There are no exceptions to that command — nothing inside `.qs-factory/` belongs in a published quickstart. So the finished repo carries none of this internal bookkeeping, but the team had full visibility into it while the work was in progress. See `rh-qs-ship/SKILL.md` for the exact steps. -See `rh-qs-scaffold/SKILL.md` for the exact repo-creation steps. +This is a **separate concern** from the factory's own `.gitignore`, which simply ignores `.rhoai-qs/` as one blanket rule (see the factory's `.gitignore`) — git never looks inside an ignored directory, so it never notices there's another repo nested inside it, and the two repos' git histories don't interact. ## Where Skills Run (and Why It Matters for Paths) -Skills fall into two groups, based on whether the quickstart's code repo exists yet: +Skills fall into two groups, based on whether they run inside the quickstart's repo: + +**At the `quickstart-factory` root** (`rh-qs-discovery`, `rh-qs-architect`, `rh-qs-scaffold`, plus factory-level skills like `pipeline-grooming`, `blog-writer`): paths are written in full, `.rhoai-qs/<slug>/.qs-factory/prds/prd.md`. + +**Inside `.rhoai-qs/<slug>/`** (`rh-qs-implement`, `rh-qs-deploy`, `rh-qs-verify-deploy`, `rh-qs-document`, `rh-qs-test-suite`, `rh-qs-ship`): that's where the application code lives and where `make`/`helm`/etc. need to run. From there: -**Before scaffolding** (`rh-qs-discovery`, `rh-qs-architect`, `rh-qs-scaffold` itself, plus factory-level skills like `pipeline-grooming`, `blog-writer`): run with their working directory at the **`quickstart-factory` root**. Paths are written in full: `.rhoai-qs/<slug>/prds/prd.md`. +- Reading/writing bookkeeping files uses the `.qs-factory/` prefix: `.qs-factory/prds/prd.md`, `.qs-factory/designs/architecture-spec.yaml`, `.qs-factory/pipeline/deploy-spec.yaml`, `.qs-factory/reports/...` +- Listing other quickstarts (for slug resolution) means going up one level: `ls -1 ../`. -**After scaffolding** (`rh-qs-implement`, `rh-qs-deploy`, `rh-qs-verify-deploy`, `rh-qs-document`, `rh-qs-test-suite`, `rh-qs-ship`): run with their working directory **inside** `.rhoai-qs/<slug>/` itself, since that's where the application code lives and where `make`/`helm`/etc. need to run. From there: -- Reading/writing the quickstart's own bookkeeping files uses **plain relative paths, no prefix**: `prds/prd.md`, `designs/architecture-spec.yaml`, `pipeline/deploy-spec.yaml`, `reports/...` -- Listing *other* quickstarts (for slug resolution) requires going up one level: `ls ../` lists every slug folder plus the two cross-cutting folders (`reports/`, `blog-drafts/`) as siblings. +`pipeline-checkpoint.py` is the exception that needs no care here — it anchors every path off the factory root itself, so it writes to the same place from either working directory. ## Resolving the Quickstart Slug @@ -109,7 +120,7 @@ See [validation-skill-template.md](validation-skill-template.md) for the full re In short: 1. If the user named the quickstart in their message → use it. -2. Otherwise, list existing slugs under `.rhoai-qs/` (excluding the two cross-cutting folders, `reports/` and `blog-drafts/`): +2. Otherwise, list existing slugs — every direct child of `.rhoai-qs/` is one, so this is a plain `ls` with no filtering: - Exactly one → confirm with the user, then proceed. - Multiple → ask the user which one. - None → only valid if this is `rh-qs-discovery` starting a brand-new idea; otherwise, stop and report the error. @@ -118,7 +129,7 @@ In short: ## File Categories -Four categories of pipeline files exist within `.rhoai-qs/<slug>/pipeline/`: +Four categories of pipeline files exist within `.rhoai-qs/<slug>/.qs-factory/pipeline/`: ### 1. Spec files @@ -142,7 +153,7 @@ After validation, a refined variant is written: ### 2. Handoff manifests -Output artifacts that the next pipeline stage consumes. These are the inter-skill contracts. +Output artifacts that the next pipeline stage consumes. These are the inter-skill contracts. All locations are relative to `.qs-factory/`. | File | Producer | Consumer | Location | |------|----------|----------|----------| @@ -156,7 +167,7 @@ Output artifacts that the next pipeline stage consumes. These are the inter-skil See [pipeline-contracts.md](pipeline-contracts.md) for the YAML schema of each handoff file. -Note: `designs/architecture-spec.yaml` serves double duty — it is both the architect's spec file and the handoff manifest to scaffold. It has no `-refined` variant; user approval happens on the spec itself. +Note: `.qs-factory/designs/architecture-spec.yaml` serves double duty — it is both the architect's spec file and the handoff manifest to scaffold. It has no `-refined` variant; user approval happens on the spec itself. ### 3. Internal working files @@ -195,75 +206,34 @@ Per-resource debug artifacts that accumulate during the debug loop. Debug and fix files append `attempt_N` keys — they never overwrite previous attempts. This lets the debugger review what was already tried before proposing a new fix. -## Non-Pipeline Categories (also namespaced by slug) +## Non-Pipeline Categories (also under `.qs-factory/`) -Two more categories live under `.rhoai-qs/<slug>/`, alongside `pipeline/` and the application code, but are human-readable deliverables rather than skill-to-skill contracts: +Three more categories sit alongside `pipeline/` inside `.qs-factory/`, but are human-readable deliverables or generated views rather than skill-to-skill contracts: | Directory | File | Producing Skill | Purpose | |-----------|------|------------------|---------| | `prds/` | `prd.md` | rh-qs-discovery | The PRD — the actual handoff artifact to rh-qs-architect | | `designs/` | `architecture-spec.yaml`, `architecture-diagram.mmd` | rh-qs-architect | Architecture spec and Mermaid diagram — handoff artifacts to rh-qs-scaffold | -| `blog-drafts/` | `<date>.md` | rh-qs-ship / blog-writer | Draft announcement, requires human review | +| `flow/` | `dashboard.md` | pipeline-checkpoint.py | Live pipeline progress view | | `reports/` | `verify-deploy-<date>.md`, etc. | rh-qs-verify-deploy | Per-quickstart reports | -The slug isn't repeated in these filenames — the parent `.rhoai-qs/<slug>/` folder already disambiguates which quickstart a file belongs to. Filenames only need to name the *type* of artifact (`prd`, `architecture-spec`) or add a date when multiple versions can exist over time (`blog-drafts/`, `reports/`). +The slug isn't repeated in these filenames — the parent `.rhoai-qs/<slug>/` folder already disambiguates which quickstart a file belongs to. Filenames only need to name the *type* of artifact (`prd`, `architecture-spec`) or add a date when multiple versions can exist over time (`reports/`). -## Cross-Cutting Locations +## Factory-Side Locations -Two folders sit directly under `.rhoai-qs/`, as siblings of the slug folders — not inside any of them, since they're not about one specific quickstart: +Two gitignored folders sit at the **factory root**, not under `.rhoai-qs/` — keeping them out preserves the "every direct child of `.rhoai-qs/` is a quickstart" invariant, and keeping them out of the quickstart repo means ship's cleanup needs no exceptions. ``` -.rhoai-qs/ -├── mortgage-processor/ ← a slug folder -├── spending-transaction-monitor/ ← another slug folder -├── reports/ ← cross-cutting reports -└── blog-drafts/ ← fallback blog drafts +quickstart-factory/ +├── .blog-drafts/ ← <slug>-YYYY-MM-DD.md +└── .reports/ ← cross-cutting reports, not tied to one quickstart ``` -**`.rhoai-qs/reports/`** — reports that survey the whole backlog, not one quickstart: -- `gap-analysis-<date>.md` from `rh-qs-discovery`'s gap analysis mode — this runs *before* any slug exists (it's proposing new quickstart ideas), so there's no slug folder to put it in. -- `grooming-report-<date>.md` from `pipeline-grooming` — scores and prioritizes every backlog issue at once. +**`.blog-drafts/<slug>-YYYY-MM-DD.md`** — draft announcements from `rh-qs-ship` and `blog-writer`. These are review-before-publication working material with no business in a published quickstart repo. The filename is always slug-prefixed, so one naming rule covers every quickstart whether or not it has a slug folder. -Neither filename includes a slug, since there isn't one to include. +**`.reports/<name>-YYYY-MM-DD.md`** — reports that survey the whole backlog rather than one quickstart: `gap-analysis-<date>.md` from `rh-qs-discovery`'s gap-analysis mode (which runs *before* any slug exists), `grooming-report-<date>.md` from `pipeline-grooming`, and coverage analyses from `quickstart-identifier`. Created on demand. -**`.rhoai-qs/blog-drafts/`** — a fallback for `blog-writer` when asked to draft a post for a quickstart that predates this whole convention (no `.rhoai-qs/<slug>/` folder exists for it, because it was built before the factory adopted this pipeline). This case genuinely **is** about one specific quickstart — the file just can't live in a slug folder that was never created. Its filename **does** include the slug (`vllm-cpu-2025-03-11.md`) to disambiguate itself, since this folder mixes fallback drafts from multiple old quickstarts together. - -> **Open question, not yet resolved:** it isn't certain how often either of these two paths will actually see use in practice — gap analysis and grooming reports may end up being requested rarely, and most quickstarts going forward should have their own slug folder from the start (making the `blog-drafts/` fallback increasingly rare too). Revisit whether this dedicated structure is still earning its complexity once real usage data exists. - -## Directory Layout Example - -A fully populated designs directory and pipeline directory mid-pipeline, for a single quickstart, looks like: - -``` -.rhoai-qs/mortgage-processor/designs/ -├── architecture-spec.yaml # Handoff to scaffold -└── architecture-diagram.mmd - -.rhoai-qs/mortgage-processor/pipeline/ -├── discovery-spec.yaml -├── scaffold-spec.yaml -├── scaffold-manifest.yaml # Handoff to implement -├── implementation-spec.yaml -├── implementation-spec-refined.yaml -├── test-spec.yaml # Internal: test inventory -├── test-results.yaml # Internal: test outcomes -├── implementation-manifest.yaml # Handoff to deploy -├── deploy-spec.yaml -├── deploy-validation.yaml # Internal: reviewer results -├── deploy-manifest.yaml # Handoff to security -├── qs-security-code.yaml # Internal: scanner output -├── qs-security-containers.yaml -├── qs-security-helm.yaml -├── qs-security-deps.yaml -├── security-report.yaml # Handoff to debug-and-deploy -├── qs-deploy-analysis.yaml # Internal: deploy analysis -├── deploy-state.yaml # Handoff to document -├── qs-debug-redis.yaml # Internal: per-resource debug -├── qs-fix-redis.yaml -├── qs-e2e-results.yaml # Internal: E2E results -├── doc-manifest.yaml # Handoff to ship -└── qs-kb-extraction-report.yaml # Internal: KB extraction -``` +Per-quickstart reports are a different thing entirely and stay in `.qs-factory/reports/`. ## Cleanup Policy @@ -273,21 +243,21 @@ Skills do NOT clean up pipeline files during execution. Files accumulate through ### User-controlled cleanup -Pipeline files persist until the user explicitly deletes them. To reset a single quickstart's pipeline state without touching its code: +Pipeline files persist until the user explicitly deletes them. To reset a single quickstart's factory bookkeeping without touching its code: ```bash -rm -rf .rhoai-qs/mortgage-processor/pipeline/ +rm -rf .rhoai-qs/mortgage-processor/.qs-factory/ ``` -To remove everything for that quickstart, **including its cloned code repo**: +To remove everything for that quickstart, **including its code repo**: ```bash rm -rf .rhoai-qs/mortgage-processor/ ``` -This is safe — it only removes that one quickstart's folder, not other quickstarts' data or the cross-cutting `reports/`/`blog-drafts/` folders. The user decides when cleanup happens — after shipping, after review, or never. Note the code itself still exists on GitHub (`rh-ai-quickstart/<slug>`) even after deleting the local clone. +This is safe — it only removes that one quickstart's folder, not other quickstarts' data. The user decides when cleanup happens — after shipping, after review, or never. Note the code itself still exists on GitHub (`rh-ai-quickstart/<slug>`) even after deleting the local copy. -This is a different, complementary concern from the **ship-time cleanup** in `rh-qs-ship` (see [Nested Quickstart Repos](#nested-quickstart-repos)): that one removes the bookkeeping folders from the quickstart's own git history as a standard, non-optional step before shipping, so the published repo doesn't carry them. This section is about the *local* `.rhoai-qs/<slug>/` folder in the factory — always user-controlled, never automatic. +This is a different, complementary concern from the **ship-time cleanup** in `rh-qs-ship` (see [`.qs-factory/` is tracked, not gitignored](#qs-factory-is-tracked-not-gitignored)): that one removes `.qs-factory/` from the quickstart's own git history as a standard, non-optional step before shipping, so the published repo doesn't carry it. This section is about the *local* `.rhoai-qs/<slug>/` folder in the factory — always user-controlled, never automatic. ## Concurrency @@ -297,23 +267,23 @@ Different quickstarts share the same `quickstart-factory` repo, but each has its ### Same quickstart -Running the same quickstart concurrently (e.g., two agents both running `rh-qs-deploy` for `mortgage-processor` at the same time) is NOT safe. Both would write to the same `.rhoai-qs/mortgage-processor/pipeline/deploy-spec.yaml`, causing race conditions. +Running the same quickstart concurrently (e.g., two agents both running `rh-qs-deploy` for `mortgage-processor` at the same time) is NOT safe. Both would write to the same `.rhoai-qs/mortgage-processor/.qs-factory/pipeline/deploy-spec.yaml`, causing race conditions. This is a known constraint. The factory is designed for one pipeline execution per quickstart at a time. ## Resumability -Since pipeline files are persistent, resumability works naturally. When a skill starts, after resolving its slug via `validation-skill`, it checks whether `.rhoai-qs/<slug>/pipeline/` already contains artifacts from a previous run: +Since pipeline files are persistent, resumability works naturally. When a skill starts, after resolving its slug via `validation-skill`, it checks whether `.qs-factory/pipeline/` already contains artifacts from a previous run: ``` 1. Resolve the slug (validation-skill) -2. Check if .rhoai-qs/<slug>/pipeline/ exists +2. Check if .rhoai-qs/<slug>/.qs-factory/pipeline/ exists 3. If it exists, check for artifacts from this skill and upstream skills 4. If upstream handoff manifests exist: → Check content_hash against the current upstream file (see below) → If hashes match: offer to resume from current stage → If hashes differ: warn that upstream has changed, offer to re-run - → Or start fresh (rm -rf .rhoai-qs/<slug>/pipeline/) + → Or start fresh (rm -rf .rhoai-qs/<slug>/.qs-factory/pipeline/) 5. If this skill's own spec exists: → Offer to reuse the existing spec → Or regenerate diff --git a/docs/foundation/skill-directory-structure.md b/docs/foundation/skill-directory-structure.md index 563833b..337593a 100644 --- a/docs/foundation/skill-directory-structure.md +++ b/docs/foundation/skill-directory-structure.md @@ -198,7 +198,7 @@ core/skills/implementation/rh-qs-implement/ │ # error handling, async consistency, security basics │ ├── spec-template.md -│ # Defines .rhoai-qs/<slug>/pipeline/implementation-spec.yaml: +│ # Defines .rhoai-qs/<slug>/.qs-factory/pipeline/implementation-spec.yaml: │ # endpoints, schemas, services, DB models, UI routes │ ├── output-templates.md @@ -238,13 +238,13 @@ core/skills/implementation/rh-qs-implement/ ``` Phase 0: Resolve quickstart slug (validation-skill) -Phase 1: Read scaffold-manifest.yaml from .rhoai-qs/<slug>/pipeline/ and architecture-spec.yaml from .rhoai-qs/<slug>/designs/ +Phase 1: Read scaffold-manifest.yaml from .rhoai-qs/<slug>/.qs-factory/pipeline/ and architecture-spec.yaml from .rhoai-qs/<slug>/.qs-factory/designs/ Phase 2: Generate implementation-spec.yaml → user approval Phase 3: Spawn db-schema subagent (dependency) Phase 4: Spawn backend-implementer + frontend-implementer in parallel Phase 5: Spawn test-writer → generates tests Phase 6: Run `make test` → route failures → fix loop (max 3) -Phase 7: Write implementation-manifest.yaml to .rhoai-qs/<slug>/pipeline/ +Phase 7: Write implementation-manifest.yaml to .rhoai-qs/<slug>/.qs-factory/pipeline/ ``` ## Minimal Example: rh-qs-discovery @@ -288,7 +288,7 @@ Current skills are flat `SKILL.md` files with optional `references/` and `script 1. Keep `SKILL.md` but rewrite it as an orchestrator 2. Add `reasoning-guardrails.md` with skill-specific concern areas -3. Add `spec-template.md` defining the skill's spec YAML, using `.rhoai-qs/<slug>/pipeline/` paths per [pipeline-convention.md](pipeline-convention.md) +3. Add `spec-template.md` defining the skill's spec YAML, using `.rhoai-qs/<slug>/.qs-factory/pipeline/` paths per [pipeline-convention.md](pipeline-convention.md) 4. Add `output-templates.md` defining output formats 5. Create `subagents/` with `README.md`, `validation-skill-prompt.md` (Phase 0 slug resolution, see [validation-skill-template.md](validation-skill-template.md)), and one `<role>-prompt.md` per delegated task 6. Move heavy logic from `SKILL.md` into subagent prompts diff --git a/docs/foundation/spec-as-contract.md b/docs/foundation/spec-as-contract.md index 5a62cc0..8765a14 100644 --- a/docs/foundation/spec-as-contract.md +++ b/docs/foundation/spec-as-contract.md @@ -15,7 +15,7 @@ Analyze → Generate Spec → User Approval → Validate Spec (parallel) → Ref | Phase | Actor | Description | |-------|-------|-------------| | **Analyze** | Main agent | Read inputs (PRD, prior manifests, KB files), reason about the problem | -| **Generate Spec** | Main agent | Write the spec YAML to `.rhoai-qs/<slug>/pipeline/<skill>-spec.yaml` | +| **Generate Spec** | Main agent | Write the spec YAML to `.rhoai-qs/<slug>/.qs-factory/pipeline/<skill>-spec.yaml` | | **User Approval** | User | Review the spec, approve or request changes (see [acceptance-criteria.md](acceptance-criteria.md)) | | **Validate Spec** | Validator subagent(s) | Check spec correctness in parallel (e.g., chart versions exist, schemas are valid) | | **Refine** | Main agent | Incorporate validation feedback, write `<skill>-spec-refined.yaml` | @@ -26,7 +26,7 @@ Analyze → Generate Spec → User Approval → Validate Spec (parallel) → Ref - **Separates reasoning from file edits** — the agent reasons about *what* to do in the spec phase, then a focused subagent applies changes without re-reasoning. - **Catches errors before implementation** — parallel validators check the spec for consistency, missing fields, and invalid references before any code is written. -- **Creates an audit trail** — the spec YAML in `.rhoai-qs/<slug>/pipeline/` documents every decision made during analysis. +- **Creates an audit trail** — the spec YAML in `.rhoai-qs/<slug>/.qs-factory/pipeline/` documents every decision made during analysis. - **Enables user control** — the user reviews and approves the plan before implementation begins. ## Spec File Location @@ -34,11 +34,11 @@ Analyze → Generate Spec → User Approval → Validate Spec (parallel) → Ref Most specs are written to the quickstart's namespaced pipeline directory, once the skill has resolved the slug via `validation-skill` (see [pipeline-convention.md](pipeline-convention.md#resolving-the-quickstart-slug)): ``` -.rhoai-qs/<slug>/pipeline/<skill>-spec.yaml # Initial spec -.rhoai-qs/<slug>/pipeline/<skill>-spec-refined.yaml # After validation feedback +.rhoai-qs/<slug>/.qs-factory/pipeline/<skill>-spec.yaml # Initial spec +.rhoai-qs/<slug>/.qs-factory/pipeline/<skill>-spec-refined.yaml # After validation feedback ``` -**Exception:** `rh-qs-architect` writes its spec to `.rhoai-qs/<slug>/designs/architecture-spec.yaml` (no `-refined` variant) because it serves as both a spec and the primary design document for the quickstart. +**Exception:** `rh-qs-architect` writes its spec to `.rhoai-qs/<slug>/.qs-factory/designs/architecture-spec.yaml` (no `-refined` variant) because it serves as both a spec and the primary design document for the quickstart. See [pipeline-convention.md](pipeline-convention.md) for the full scoping rules. @@ -57,7 +57,7 @@ created_at: "2026-07-01T12:00:00Z" # ─── Inputs ────────────────────────────────────────────── inputs: prior_manifests: # Pipeline files from previous skills - - path: .rhoai-qs/spending-transaction-monitor/pipeline/scaffold-manifest.yaml + - path: .rhoai-qs/spending-transaction-monitor/.qs-factory/pipeline/scaffold-manifest.yaml skill: rh-qs-scaffold user_inputs: [] # Any direct user-provided data @@ -169,7 +169,7 @@ After the spec is generated, one or more validator subagents check it in paralle ``` ┌──────────────────────────────────────────────────────────┐ -│ Main agent writes .rhoai-qs/<slug>/pipeline/<skill>-spec.yaml│ +│ Main agent writes .rhoai-qs/<slug>/.qs-factory/pipeline/<skill>-spec.yaml│ │ │ │ Spawn validator subagents in parallel: │ │ ┌─────────────────┐ ┌─────────────────┐ │ @@ -217,7 +217,7 @@ When validators find blockers, the main agent: 1. Reads validation results 2. Fixes the spec (not code — nothing has been implemented yet) -3. Writes `.rhoai-qs/<slug>/pipeline/<skill>-spec-refined.yaml` +3. Writes `.rhoai-qs/<slug>/.qs-factory/pipeline/<skill>-spec-refined.yaml` 4. Re-runs validators on the refined spec 5. Max 2 refinement iterations per skill (configurable in `spec-template.md`) @@ -260,7 +260,7 @@ If any criterion fails, the skill enters its feedback loop (see ADR-001 Pattern This example shows a fully populated spec for the Architect skill (`rh-qs-architect`), converting a PRD into a component bill of materials. -**Exception:** The architect spec lives at `.rhoai-qs/<slug>/designs/architecture-spec.yaml` (not under `pipeline/`) and uses a simplified schema — it omits `inputs`, `acceptance_criteria`, and `validation_rules`, and has no `-refined` variant. User approval happens on the spec itself. See [pipeline-contracts.md](pipeline-contracts.md#1-architecture-specyaml) and `core/skills/rh-qs-architect/references/architecture-spec-template.yaml` for the canonical schema. +**Exception:** The architect spec lives at `.rhoai-qs/<slug>/.qs-factory/designs/architecture-spec.yaml` (not under `pipeline/`) and uses a simplified schema — it omits `inputs`, `acceptance_criteria`, and `validation_rules`, and has no `-refined` variant. User approval happens on the spec itself. See [pipeline-contracts.md](pipeline-contracts.md#1-architecture-specyaml) and `core/skills/rh-qs-architect/references/architecture-spec-template.yaml` for the canonical schema. ```yaml spec_version: 1 @@ -349,7 +349,7 @@ integration_patterns: - point: "Frontend → Backend" mechanism: "OAuth2 with RHOAI authentication" -architecture_diagram_path: .rhoai-qs/spending-transaction-monitor/designs/architecture-diagram.mmd +architecture_diagram_path: .rhoai-qs/spending-transaction-monitor/.qs-factory/designs/architecture-diagram.mmd testing_strategy: profile: standard @@ -371,13 +371,13 @@ testing_strategy: runs_on: "Every PR" dependencies: - - spec: .rhoai-qs/spending-transaction-monitor/prds/prd.md + - spec: .rhoai-qs/spending-transaction-monitor/.qs-factory/prds/prd.md fields_used: [problem_statement, target_persona, technology_constraints] content_hash: "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" - - spec: .rhoai-qs/spending-transaction-monitor/pipeline/prd-features.yaml + - spec: .rhoai-qs/spending-transaction-monitor/.qs-factory/pipeline/prd-features.yaml fields_used: [input_features, deployment_questions, decision_points] content_hash: "sha256:..." - - spec: .rhoai-qs/spending-transaction-monitor/pipeline/kb-scores.yaml + - spec: .rhoai-qs/spending-transaction-monitor/.qs-factory/pipeline/kb-scores.yaml fields_used: [results] content_hash: "sha256:..." ``` @@ -389,7 +389,7 @@ Each skill's `spec-template.md` extends the common fields above with skill-speci | Skill | Spec File | Key Component Fields | |-------|-----------|---------------------| | rh-qs-discovery | `discovery-spec.yaml` | Interview plan, PRD section targets | -| rh-qs-architect | `designs/architecture-spec.yaml` | Technology stack, component BOM (`role`, `technology`, `delivery`), `integration_patterns`, diagram path, testing strategy | +| rh-qs-architect | `.qs-factory/designs/architecture-spec.yaml` | Technology stack, component BOM (`role`, `technology`, `delivery`), `integration_patterns`, diagram path, testing strategy | | rh-qs-scaffold | `scaffold-spec.yaml` | Repo name, packages, CI jobs, linting config | | rh-qs-implement | `implementation-spec.yaml` | Endpoints, schemas, services, DB models, UI routes | | rh-qs-deploy | `deploy-spec.yaml` | Chart dependencies, values overrides, compose services, Containerfile specs | @@ -400,6 +400,6 @@ Each skill's `spec-template.md` extends the common fields above with skill-speci - **[skill-directory-structure.md](skill-directory-structure.md)** — each skill's `spec-template.md` file defines the skill-specific fields - **[acceptance-criteria.md](acceptance-criteria.md)** — details when user approval is required and how criteria are validated -- **[pipeline-convention.md](pipeline-convention.md)** — defines the `.rhoai-qs/<slug>/pipeline/` directory where most specs and manifests are written (`architecture-spec.yaml` is the exception — it lives under `designs/`) +- **[pipeline-convention.md](pipeline-convention.md)** — defines the `.rhoai-qs/<slug>/.qs-factory/pipeline/` directory where most specs and manifests are written (`architecture-spec.yaml` is the exception — it lives under `designs/`) - **[validation-skill-template.md](validation-skill-template.md)** — how the slug is resolved before any spec is written - **[pipeline-contracts.md](pipeline-contracts.md)** — defines the output manifests that consuming skills expect (downstream of specs) diff --git a/docs/foundation/validation-skill-template.md b/docs/foundation/validation-skill-template.md index 159a088..f24ffba 100644 --- a/docs/foundation/validation-skill-template.md +++ b/docs/foundation/validation-skill-template.md @@ -27,13 +27,24 @@ Self-contained, following the standard subagent structure from [skill-directory- | Input | Description | |-------|-------------| | `user_message` | The user's raw request for this session (e.g., "deploy mortgage-processor", "continue the fraud idea", "run rh-qs-deploy") | -| `existing_slugs` | List of quickstart slug folders, **excluding** the two cross-cutting folders `reports/` and `blog-drafts/` (see [pipeline-convention.md](pipeline-convention.md#cross-cutting-locations)) | +| `existing_slugs` | List of the directories under `.rhoai-qs/`. Every one of them is a quickstart — there is nothing to filter out (see [pipeline-convention.md](pipeline-convention.md#the-two-invariants)) | | `is_entry_point` | `true` only for `rh-qs-discovery`; changes how a zero-match result is handled | | `calling_skill` | Name of the skill invoking this subagent (for logging/messaging only) | The main agent runs the listing command itself — the subagent never has filesystem access, it only reasons over the list it's given. The exact command depends on where the calling skill runs (see [pipeline-convention.md](pipeline-convention.md#where-skills-run-and-why-it-matters-for-paths)): -- Skills running at the `quickstart-factory` root (discovery, architect, scaffold): `ls .rhoai-qs/ 2>/dev/null`, then filter out `reports` and `blog-drafts`. -- Skills running inside `.rhoai-qs/<slug>/` itself (implement, deploy, verify-deploy, document, test-suite, ship): `ls ../ 2>/dev/null`, then filter out `reports` and `blog-drafts`. + +```bash +# Skills running at the quickstart-factory root (discovery, architect, scaffold): +ls -1 .rhoai-qs/ 2>/dev/null + +# Skills running inside .rhoai-qs/<slug>/ itself +# (implement, deploy, verify-deploy, document, test-suite, ship): +ls -1 ../ 2>/dev/null +``` + +The output **is** the slug list, verbatim — no filtering. Every direct child of `.rhoai-qs/` is a quickstart, so there is nothing to exclude. + +Use plain `ls`, not `find`: `find -printf` is GNU-only and breaks on macOS, and `ls` lists a symlinked quickstart like any other entry, which `find -type d` would not. ## Resolution Logic @@ -108,15 +119,15 @@ Every subsequent phase constructs paths using the resolved `slug`, in whichever ``` # From the quickstart-factory root (discovery, architect, scaffold): -.rhoai-qs/<slug>/pipeline/<skill>-spec.yaml -.rhoai-qs/<slug>/prds/prd.md -.rhoai-qs/<slug>/designs/architecture-spec.yaml +.rhoai-qs/<slug>/.qs-factory/pipeline/<skill>-spec.yaml +.rhoai-qs/<slug>/.qs-factory/prds/prd.md +.rhoai-qs/<slug>/.qs-factory/designs/architecture-spec.yaml # From inside .rhoai-qs/<slug>/ itself (implement, deploy, verify-deploy, # document, test-suite, ship): -pipeline/<skill>-spec.yaml -prds/prd.md -designs/architecture-spec.yaml +.qs-factory/pipeline/<skill>-spec.yaml +.qs-factory/prds/prd.md +.qs-factory/designs/architecture-spec.yaml ``` ## Relationship to Other Foundation Docs diff --git a/docs/skill-testing-guide.md b/docs/skill-testing-guide.md index f79b1d4..d11a592 100644 --- a/docs/skill-testing-guide.md +++ b/docs/skill-testing-guide.md @@ -35,7 +35,7 @@ This is the repeatable checklist for testing one skill, one time: ```mermaid flowchart TD Hash["Record factory commit: git rev-parse --short HEAD"] --> Run["Run the skill against the test QS slug"] - Run --> Check["Check outputs: pipeline-registry.yaml review_guidance + .rhoai-qs/slug/flow/dashboard.md"] + Run --> Check["Check outputs: pipeline-registry.yaml review_guidance + .rhoai-qs/slug/.qs-factory/flow/dashboard.md"] Check --> Export["Export conversation (client-specific)"] Export --> Tokens["Record token usage (client-specific)"] Tokens --> Commit["Commit: test(skill) template"] @@ -45,7 +45,7 @@ flowchart TD 1. **Record the factory commit.** In `quickstart-factory`, run `git rev-parse --short HEAD`. This is the `Factory:` value in the commit message (§4). 2. **Run the skill** against the test quickstart's slug, in whichever client we're using (Cursor or Claude Code). -3. **Check the outputs — reuse, don't reinvent.** Every pipeline skill already has an `expected_outputs` list and a `review_guidance` block in [core/flow/pipeline-registry.yaml](../core/flow/pipeline-registry.yaml), and skills already call [core/flow/pipeline-checkpoint.py](../core/flow/pipeline-checkpoint.py) to update `.rhoai-qs/<slug>/flow/dashboard.md` after they run. Look there first: +3. **Check the outputs — reuse, don't reinvent.** Every pipeline skill already has an `expected_outputs` list and a `review_guidance` block in [core/flow/pipeline-registry.yaml](../core/flow/pipeline-registry.yaml), and skills already call [core/flow/pipeline-checkpoint.py](../core/flow/pipeline-checkpoint.py) to update `.rhoai-qs/<slug>/.qs-factory/flow/dashboard.md` after they run. Look there first: - Did the dashboard mark the skill `done` with `outputs_verified: true`? - Does the skill's `review_guidance` in `pipeline-registry.yaml` hold up (file exists, `make lint`/`make test` pass, no placeholders, etc.)? - Only write a manual note in the commit if something looks off — don't invent a second, parallel definition of "done." This mirrors the same reuse-first pattern the factory already uses for [acceptance-criteria.md](foundation/acceptance-criteria.md).