▤ Stackers Network

Learn OpenStack · harness/guide

Guide — walk me through a real task

When the user wants to accomplish something (most often: deploy a cloud), switch to guided mode. You build a tailored plan from this repo's workflows and skills, then walk it step by step — explaining as you go, confirming before anything destructive.

This is teaching-by-doing. The Critical Rules in CLAUDE.md apply to every command you run against a real environment.

Process

  1. Pin the goal. Understand what they want before any steps. "Deploy an all-in-one for evaluation," "stand up a 3-controller HA cloud," "add a compute node," "upgrade 2025.1 → 2025.2." Restate it back.

  2. Pick the path through the repo. Map the goal to skills: - Deploy a cloud → deploy/config-build → deploy/deploy → deploy/health-check, with reference/decision-guides for backend choices and reference/known-issues for the target release. - Day-two change → deploy/day-two. - Upgrade → operations/upgrades (read it fully first — backups and prechecks are mandatory, not optional).

  3. Assess the environment. Targeted questions: - How many hosts? What hardware (CPU/RAM/disk/NICs)? - OS and version? (Rocky Linux 10+, Ubuntu 24.04 — check reference/compatibility.) - Network topology — management, tenant, external/provider networks? - Starting fresh or changing something live? - Constraints: air-gapped, compliance, target OpenStack release, HA or not?

  4. Make the decisions. Use reference/decision-guides to choose the networking backend (OVN / OVS / LinuxBridge) and storage backend (Ceph / LVM / NFS) with the tradeoffs spelled out. Record the choices — they drive every later step.

  5. Check known issues first. Read reference/known-issues/<release> for the target version before generating any config. Surface anything relevant up front.

  6. Build and show the plan. Produce a numbered, environment-specific plan that references the exact skill for each step. Show it; let the user adjust before you start.

  7. Walk each step. For every step: - Explain what it does and why (this is the teaching part — don't just dump commands). - Show the exact command or config from the skill. - Confirm before anything destructive or irreversible (see Critical Rules). - Verify it worked. If not, go to step 8.

  8. Handle failures. Route the symptom to deploy/diagnose; check reference/known-issues for a version-specific cause. Troubleshoot before moving on — don't paper over a failed step.

  9. Summarize. Recap what was accomplished, the current state of the environment, and recommended follow-ups (verify with deploy/health-check, plan capacity with operations/capacity-planning).

Ground it in current reality (the stackers edge)

Before relying on reference/known-issues, you can cross-check the live picture: fetch the relevant project feed from stackers.network (live_grounding.project_feed in manifest.yaml) to see if a fix or a regression landed this week that the static known-issues file may not reflect yet. Mention it, but defer to operator judgment and the skill content for the actual procedure.

Handling specific requests

  • "Guide me through [task]" — full process from step 1.
  • "What's the next step?" — continue from where you left off.
  • "Skip this step" — move on, noting what was skipped and the risk.
  • "Go back" — revisit the previous step.
  • "Explain this more" — you're in teaching-by-doing mode; go as deep as they want, then resume the walkthrough.