Project Onboard

Project Onboarding Assistant

When to Use

• User clones a project repository and asks for help setting it up
• User asks "how do I get started" or "help me deploy" in a project directory
• User asks about prerequisites, environment setup, or first-time configuration
• A project directory contains an onboard.yml, onboard.json, or .onboard.yml manifest
• User says "onboard me" or "run onboard"
• User runs make setup and the Makefile delegates to this skill
• User asks to generate a setup script or bootstrap script for their project
• User asks about dev vs prod mode for a project setup

Do NOT use this skill for:

• Environments that are already deployed — use student-readiness to verify them
• Refactoring existing AgnosticD configs — use agnosticd-refactor
• Validating a running deployment — use agnosticd-deploy-test or vp-deploy-test
• Building a new skill — use the create-skill workflow

Instructions

This skill defines a six-phase onboarding process driven by a declarative manifest (onboard.yml) shipped by the consuming project. The manifest declares what needs to be installed, configured, and validated — this skill interprets the manifest and walks the user through each phase interactively.

The skill also generates runtime bootstrap.sh scripts that read onboard.yml at execution time, so humans without AI agents can run the same onboarding process from the command line (see Phase 7). The generated script uses python3 + PyYAML to parse the manifest — no values are baked into the bash code.

Key behaviors:

• Read the manifest first; do not improvise steps that are not declared in it
• Complete each phase before moving to the next; do not skip phases
• Always confirm with the user before running sudo commands or installing packages
• The process is idempotent — safe to re-run; skip prerequisites already installed
• If the user says "use all defaults" or asks for non-interactive mode, accept all default values from the manifest without prompting
• Always run validation (Phase 5) even if the user asks to skip other phases
• If quota_checks is defined, run quota checks (Phase 5b) after validation
• Always show the post-setup message (Phase 6)
• Substitute ${variable} references in commands, messages, and paths using the configuration values collected in Phase 4

Dev vs prod modes:

If the manifest defines a modes section, ask the user which mode they want at the start of Phase 0:

• dev — For repo maintainers and contributors. Installs dev-only extra prerequisites (linters, test frameworks, pre-commit hooks) in addition to the base prerequisites. Does not deploy.
• prod — For end users who want to deploy and use the project. Installs runtime prerequisites, configures deployment, runs validation, and optionally executes the deploy script after validation passes. This is the default if the user does not specify.

If the manifest has no modes section, run all phases without a deploy step (original behavior).

See references/manifest-spec.md for the complete onboard.yml schema.

Gotchas

• onboard.yml keys are case-sensitive — deployMethod is not the same as deploymethod
• The deploy script must be executable (chmod +x deploy.sh) or AgnosticD will silently skip it
• RHDP Keycloak naming: catalog item names must match exactly between onboard.yml and the RHDP catalog entry
• Non-interactive mode (--yes / ONBOARD_NONINTERACTIVE=true) skips ALL confirmation prompts — use with caution in production
• Platform-specific install commands vary (dnf vs brew vs apt) — the manifest's prerequisites list should use tool names, not install commands

Required Input

Before starting, confirm:

Phase 0 — Manifest Discovery

Search for the manifest in this order:

1. If the user provides an explicit path, use it
2. ./onboard.yml
3. ./onboard.json
4. ./agnosticd/onboard.yml
5. ./agnosticd/onboard.json
6. ./.onboard.yml
7. ./.onboard.json

Read and parse the manifest. Display the project name and description to the user:

=== <name>
<description>

Mode selection: If the manifest defines a modes section, ask the user:

• "Are you a maintainer/contributor (dev) or an end user looking to deploy (prod)?"
• Default to prod if the user does not specify
• In dev mode, include modes.dev.extra_prerequisites during Phase 2
• In prod mode, run modes.prod.post_validation_command after Phase 5

If no manifest is found: Explain what onboard.yml is and offer to help the user create one. Refer them to references/manifest-spec.md for the schema and references/example-manifest.yml for a working example.

Phase 1 — Platform Detection

Detect the user's operating system and map it to a manifest platform key.

On Linux, read /etc/os-release:

cat /etc/os-release

Map ID and VERSION_ID to platform keys:

On macOS, detect via:

uname -s

If the result is Darwin, use platform key macos.

Unknown platform: Use the fallback key from the manifest. If no fallback is defined for a prerequisite, print manual installation instructions and ask the user to install it themselves.

Display the detected platform:

Detected: <distro_name> <version> (<arch>)

Phase 2 — Prerequisites

For each entry in the manifest's prerequisites array, in order:

Step 1: Check if installed

Run the check_command. If it exits 0, the tool is present.

Step 2: Check version (if applicable)

If version_regex and min_version are defined in the manifest entry:

1. Capture the output of check_command
2. Extract the version using the version_regex pattern
3. Compare against min_version using dot-separated numeric comparison: split both versions on ., compare each segment as an integer left-to-right

If the installed version is less than min_version, treat it as needing install/upgrade.

Step 3: Install if missing or outdated

1. Look up the install command for the detected platform key
2. If no command exists for this platform, try fallback
3. Show the user what will be run and ask for confirmation before executing
4. Run the install command
5. Re-run check_command to verify the installation succeeded

Reporting

Print status for each prerequisite:

--- Phase 2: Prerequisites ---

  [OK]      python3 3.12.4 (>= 3.12)
  [INSTALL] podman not found
            → Running: sudo dnf install -y podman
  [OK]      podman 5.2.1 (>= 5.0)
  [OK]      aws 2.17.0
  [INSTALL] sshpass not found
            → Running: sudo dnf install -y sshpass
  [OK]      sshpass installed

Dev mode extras: If running in dev mode and the manifest defines modes.dev.extra_prerequisites, process those after the base prerequisites using the same check/install pattern. These are tools only maintainers need (e.g., shellcheck, pre-commit, test frameworks).

Gate: All prerequisites must be installed before continuing. If any install fails, stop and help the user troubleshoot before proceeding.

Phase 3 — Setup Steps

For each entry in the manifest's setup_steps array, in order:

Step 1: Collect variables

If the step defines prompt_var, prompt, and default, ask the user for the value. Store it for variable substitution in this and later phases.

Step 2: Check if already done

Substitute variables in the check command and run it. If it exits 0, skip this step (print [SKIP] with the step name).

Step 3: Execute the action

Substitute variables in the action command and run it. Verify it succeeds.

Reporting

--- Phase 3: Setup Steps ---

  [SKIP]  Clone AgnosticD v2 (already exists)
  [RUN]   Run agd setup
  [RUN]   Scaffold secrets file

Gate: All setup steps must complete before continuing.

Phase 4 — Configuration

Read the config.prompts array from the manifest. For each prompt:

1. Display the prompt text with the default value in brackets
2. If choices is defined, show the valid options and reject invalid input
3. If required is true, reject empty input (keep asking)
4. If the user accepts the default (empty input), use the default value
5. Store the answer keyed by key

After all prompts are answered, write the configuration file:

Write the config file

Write to the path specified in config.output_file, relative to the project root.

Format: flat YAML, one key: value per line, with a header comment:

# Generated by project-onboard -- re-run to reconfigure
# DO NOT commit this file (contains environment-specific values)
account: mylab
aws_region: us-west-2
num_students: 2

Ensure .gitignore coverage

If config.gitignore is true in the manifest:

1. Check if the config file path is already in .gitignore
2. If not, append it (create .gitignore if it does not exist)
3. Inform the user

Reporting

--- Phase 4: Configuration ---

  Account name (matches secrets filename) [sandbox3008]: mylab
  AWS region [us-east-2]: us-west-2
  Number of student clusters [1]: 2
  ...

  Config saved to: agnosticd/config.yml (local-only, git-ignored)

Phase 5 — Validation

For each entry in the manifest's validation array:

1. Substitute ${variable} references in the command using values from Phase 4
2. Run the command
3. Determine the result:
   • Exit 0 → PASS
   • Exit non-zero and required: true → FAIL
   • Exit non-zero and required: false → WARN
4. On failure, display the fail_message (with variable substitution)

Reporting

--- Phase 5: Validation ---

  [PASS] AWS credentials valid (arn:aws:iam::123456789:user/jdoe)
  [PASS] Pull secret exists and is valid JSON
  [PASS] AgnosticD agd binary found
  [PASS] Secrets file exists
  [WARN] Route53 hosted zone not verified

  4/4 required checks passed, 1 warning. Ready to deploy!

Readiness Gate

After all checks run, report the readiness score:

  Readiness: X/Y required checks passed (N warning(s))

• All required checks pass → Proceed to Phase 6 (and deployment in prod mode)
• Any required check fails → Report the score and stop. Do not proceed to deployment. The user must fix all required failures before deploying. Still show the post-setup message (Phase 6), since it often contains remediation instructions.
• Warnings are informational and do not block deployment

Phase 5b — Quota Checks

If the manifest defines a quota_checks array, run cloud resource quota checks after validation. Quota checks query both the limit and current usage for each resource and block deployment when needs exceed available capacity.

For each entry in quota_checks:

1. Substitute ${variable} references in limit_command and usage_command
2. Run limit_command — capture the numeric output as limit
3. Run usage_command — capture the numeric output as usage
4. Compute available = limit - usage
5. Compare: if available < needed, the check fails

Reporting

--- Quota Check ---

  [PASS] EC2 vCPUs: need 32, available 96 (limit: 128, used: 32)
  [FAIL] Elastic IPs: need 5, available 2 (limit: 5, used: 3)

  Quota: 1/2 checks passed
  BLOCKED: Insufficient quota. Fix the issues above before deploying.

Quota Gate

All quota checks must pass for deployment to proceed. Unlike validation checks, there is no required flag — every quota check is mandatory. If any check fails, display the fail_message with remediation instructions and stop. Do not proceed to deployment.

If quota_checks is not defined or is empty, skip this phase silently.

Phase 6 — Post-Setup

Display the post_setup.message from the manifest with all ${variable} references substituted. Also show the deploy_script path if defined:

--- Next Steps ---

  <post_setup.message with variables substituted>

Prod mode deploy: If running in prod mode and the manifest defines modes.prod.post_validation_command, ask the user if they want to deploy now. If yes, run the command. If validation had required failures, warn before deploying.

Phase 7 — Generate Bootstrap Script

When the user asks to generate a setup script, create a bootstrap.sh that reads onboard.yml at runtime. This gives the project a standalone onboarding experience for humans who do not have Claude Code or Cursor.

When to generate

• User asks "generate a bootstrap script" or "create a setup script"
• User asks "how can someone set this up without AI?"
• After completing Phases 0-6, offer to generate the script

How to generate

1. Read references/bootstrap-template.md for the complete runtime script
2. Copy the script into the project root as bootstrap.sh
3. Run chmod +x bootstrap.sh
4. Read references/agents-template.md for the AGENTS.md template
5. If the project already has an AGENTS.md, append the onboard section under a new ## Onboarding heading. Otherwise create AGENTS.md with the template content.
6. Suggest the project add it to their Makefile: setup: ./bootstrap.sh
7. Remind the user to commit onboard.yml, bootstrap.sh, and AGENTS.md

Key principles

• The generated script reads onboard.yml at runtime via python3 + PyYAML — no manifest values are baked into the bash code
• Single source of truth: changing onboard.yml changes bootstrap behavior immediately; the script itself only needs updating if a new version of the template adds structural improvements
• python3 + PyYAML required: the script exits with clear install instructions if either is missing. python3 ships on every RHEL system; PyYAML ships as python3-pyyaml on RHEL/Fedora
• Strict readiness gate: deployment is blocked unless all required validation checks pass. The script prints a readiness score and exits non-zero on failure.
• The script is idempotent — safe to re-run
• Default mode is prod (most users are consumers, not maintainers)
• CI-friendly: ./bootstrap.sh --non-interactive --check-only works in pipelines

Re-run Behavior

The project-onboard process is designed to be re-run safely:

• Prerequisites: Already-installed tools are detected and skipped
• Setup steps: The check command skips completed steps
• Configuration: Previous values can be re-entered or changed
• Validation: Always runs fresh

If the user asks to re-run only part of the process:

• "Reconfigure" → Skip to Phase 4 (config prompts), then run Phases 5-6
• "Check only" → Skip to Phase 5 (validation), then Phase 6
• "Install prerequisites only" → Run Phases 1-2 only

Creating an onboard.yml for a New Project

When a user asks to create a manifest for their project:

1. Read references/manifest-spec.md for the schema
2. Read references/example-manifest.yml for a complete working example
3. Examine the project's existing setup documentation (README, DEPLOYMENT.md, etc.)
4. Extract prerequisites, configuration options, and validation steps
5. Generate the manifest, filling in platform-specific install commands
6. For deploy.sh hardening, refer to references/deploy-hardening.md

RHDP Pre-Provisioned Cluster Workshops

When the target cluster is ordered from the RHDP catalog (agd-v2.ocp-cluster-aws.prod) rather than provisioned via agd, use the rhdp-workload scaffold type (./install.sh scaffold --type rhdp-workload). Key differences for the manifest:

• No AgnosticD prerequisites — remove agd binary checks, AGD_ROOT, and secrets file validation
• No cloud credentials — replace AWS/GCP/Azure credential checks with oc whoami (must be logged in to the RHDP cluster)
• Add Keycloak validation — verify keycloak namespace exists, RHBK operator is Succeeded, and KeycloakRealmImport CR named sso is present
• User format — RHDP pre-creates users as user1, user2, user3 (no dash separator, not user-1); each user has a unique password in the KeycloakRealmImport CR
• User count auto-detection — query the Keycloak sso realm to count pre-created users rather than requiring a hardcoded count
• Identity provider — RHDP already configures OpenID via RHBK; manifests must NOT create htpasswd or conflicting IdPs
• Deploy mode — support ocp_workloads, rhel_vms, or both modes for workload deployment flexibility

Platform-Specific Install Command Reference

Common install commands for use when helping users author manifests:

Escalation

• Prerequisites fail on unsupported platform → Show the fallback message from the manifest; suggest the user install manually
• Validation finds cluster or cloud issues → Activate the student-readiness skill for deployed environment checks
• deploy.sh has cross-platform bugs → Refer to references/deploy-hardening.md for sed, SSH, and error-handling patterns
• AgnosticD config needs improvement → Activate the agnosticd-refactor skill
• User wants to create a manifest for a new project → Use the schema in references/manifest-spec.md and the example in references/example-manifest.yml