project-structure

name	project-structure
metadata	{"author":"rhoai3-demo","version":"1.2.0","platform-family":"rhoai","platform-baseline":"repo","ocp-baseline":"repo","skill-group":"Project Structure"}
description	Evolve the rhoai3-demo repository structure, GitOps stage layout, documentation standards, skill taxonomy, Red Hat narrative alignment, and official-doc evidence model. Use when the user asks to reorganize demo stages, create or refactor skills, update repository guidance, align READMEs with European enterprise messaging, add component documentation standards, or decide where project knowledge belongs. Do NOT use for live deployment, live cluster troubleshooting, or resource shutdown/recovery; use the Demo Environment skills for those. Do NOT use as the source of truth for specific RHOAI CR fields; use RHOAI Platform skills and official Red Hat docs.

Project Structure

Use this skill to evolve the demo project itself: repository layout, GitOps stage conventions, documentation structure, shared skill groups, and Red Hat-aligned narrative standards.

Source Hierarchy

When changing project structure or documentation, use this evidence model:

1. Official Red Hat product docs for the active docs/PLATFORM_BASELINE.md versions are the source of truth for supported product configuration.
2. Red Hat articles, blogs, product pages, datasheets, and /Users/adrina/Sandbox/rh-brain/Red Hat Brain ground README concept framing, European enterprise value, and example implementation patterns.
3. Existing repo implementation, scripts, and READMEs show current demo behavior but are not product authority.
4. Live cluster schema checks are verification only, using oc explain or oc get crd; never invent CR fields or API versions.

Official docs remain the source of truth for supported configuration. Treat rh-brain as supporting evidence, not product authority. The active product version target lives in docs/PLATFORM_BASELINE.md; skills should reference that baseline instead of repeating exact versions in every frontmatter block.

Skill Groups

Keep canonical skill folders flat under .agents/skills/ for discovery, review, and reuse. Do not maintain tool-specific skill copies; add a minimal bridge only for a proven tool-only gap.

Group	Prefix	Purpose	Current skills
Project Structure	project-*	Repo architecture, demo stage lifecycle, GitOps stage layout, docs, Red Hat narrative grounding, skill governance, Red Hat docs-to-skill generation, Red Hat Operator GitOps deployment patterns, manifest review, Red Hat source alignment	project-structure, project-agent-guidance, project-red-hat-doc-skill-authoring, project-rhoai-doc-chapter-skill-authoring, project-red-hat-operator-gitops, project-demo-stage-authoring, project-architecture-diagrams, project-gitops-authoring, project-documentation-authoring, project-manifest-review, project-red-hat-doc-alignment-review
Demo Environment	env-*	Live AWS/OpenShift demo lifecycle: bootstrap, deploy, validate, troubleshoot, shutdown/recovery, redeploy	env-deploy-and-evaluate, env-troubleshoot, env-manage-resources, env-validate-demo-flow
RHOAI Platform	rhoai-*	Official-doc-backed component guidance for installing, configuring, and using active RHOAI baseline capabilities	rhoai-architecture-overview, rhoai-release-and-support-posture, rhoai-platform-planning, rhoai-api-tiers, rhoai-update-channels, rhoai-self-managed-installation, rhoai-dsci-dsc-configuration, rhoai-distributed-workloads, rhoai-kueue-workload-management, rhoai-distributed-workload-operations, rhoai-distributed-workload-workflows, rhoai-kubeflow-spark-operator, rhoai-nvidia-gpu-accelerators, rhoai-hardware-profiles, rhoai-certificate-management, rhoai-observability, rhoai-logs-and-audit-records, rhoai-installation-troubleshooting, rhoai-uninstallation, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ; component skills planned

Use project-red-hat-doc-skill-authoring for new rhoai-*, ocp-*, and odf-* product skills generated from official Red Hat documentation. Use project-rhoai-doc-chapter-skill-authoring and references/rhoai-component-skill-roadmap.md for existing RHOAI-only component planning, and use references/ocp-component-skill-roadmap.md for OpenShift Platform component planning. Use references/odf-component-skill-roadmap.md for OpenShift Data Foundation component planning. Use .agents/references/red-hat-doc-map.yaml as the product/category/book/topic routing layer; keep skill folders flat under .agents/skills/.

Project Change Workflow

1. Identify the group and owner skill for the work.
2. For a new demo stage, start with project-demo-stage-authoring to define intent, sources, skill routing, plan, GitOps ownership, scripts, validation, and review gates.
3. Read the relevant .agents/rules/*.md files before editing GitOps, README, labels, secrets, or generated architecture diagrams.
4. Keep code and docs aligned: manifest changes require README updates, and README capability claims require implemented manifests or a clear deferred label.
5. Keep operational details in docs/OPERATIONS.md and recovery details in docs/TROUBLESHOOTING.md; keep deferred capabilities and future work in docs/BACKLOG.md; stage READMEs should stay focused on concise Why/What content, technology mapping, and architecture delta.
6. For README concepts, cite Red Hat narrative sources from rh-brain; for RHOAI component configuration, cite official active-baseline docs. Use project-red-hat-doc-alignment-review to check both.
7. Update AGENTS.md, .agents/rules/*.md, and the relevant project skills when skill groups, inventory, or source hierarchy change.

Naming Guidance

Prefer stable names that describe responsibility:

• project-* for repository structure, docs, GitOps conventions, and narrative.
• env-* for live demo environment operations.
• rhoai-* for official-doc-backed RHOAI component knowledge.
• ocp-* for official-doc-backed OpenShift Container Platform knowledge.
• odf-* for official-doc-backed OpenShift Data Foundation knowledge.
• assets-* for visual, deck, diagram, or generated media workflows.

Renames should be incremental. Keep compatibility by updating negative triggers and cross-references before deleting old skill folders.