|
1 | | -# Guide: onboard-product — bring a new Ganemo product into AWaC |
| 1 | +# Guide: onboard-product — bring a NEW product into AWaC end-to-end (public OSS edition) |
2 | 2 |
|
3 | | -The path: |
| 3 | +> Run `awac guide onboard-product` and feed the output to your agent. The agent reads the 9-step plan, asks you the 5 inputs upfront, runs `awac scaffold-stack`, creates the 3 Cat A repos, registers the product in the core registry, scaffolds project_management, sets up the devvault catalog, audits the result, and bootstraps a first workspace — all in one continuous flow. Wall-clock: 15-30 min. |
4 | 4 |
|
5 | | -- A "product" in Ganemo is a vertical (Acme, Widget, Atlas, ...) with its own GitHub org and an `<org>/agent-stack` repo that publishes the product's deploy/devvault/template metadata. |
6 | | -- Onboarding creates the org's agent-stack from governance, registers it in `getGanemo/agent-stack-core-oss/awac.yml` (shortcut + template entries), and audits the result. |
7 | | -- The full workflow is multi-step and may include creating Cat A repos before scaffold-stack runs. |
8 | | -- After onboarding you can `wsp init <name> --template <product>-feature --yes` to create workspaces against the new product. |
| 5 | +--- |
9 | 6 |
|
10 | | -Relevant `wsp` commands: |
| 7 | +You are an AI coding agent helping me onboard a NEW product into AWaC. |
11 | 8 |
|
12 | | -- `wsp scaffold-stack <org>` — introspect the org and create `<org>/agent-stack` from governance. Uses `--push-direct` during onboarding. |
13 | | -- `wsp scaffold-repo <org>/<repo> --category <A|B|C|D|E>` — create or audit a Cat A/B/C/D/E repo's README to governance convention. |
14 | | -- `wsp audit <product>` — verify the product is fully aligned with governance + AWaC convention (Cat A repos exist with the right descriptions, agent-stack carries `awac.yml`/`devvault.yml`/`deploy.yml`/templates, registry has shortcut + template). |
15 | | -- `wsp governance check` — verify the governance↔awac.yml mirror. |
| 9 | +This is the path "I have the GitHub org + the AWS account + the domain |
| 10 | +ready; bring this product into AWaC". It's NOT the path "I have an |
| 11 | +existing product, compose a workspace from a feature template" (that's |
| 12 | +`awac guide quickstart` for an existing-product workspace). |
16 | 13 |
|
17 | | -Full canonical workflow: `getGanemo/agent-stack-core-oss/workflows/onboard_new_product.md`. |
| 14 | +The canonical workflow lives at: |
| 15 | + https://raw.githubusercontent.com/getGanemo/agent-stack-core/main/workflows/onboard_new_product.md |
| 16 | + |
| 17 | +That workflow has 9 steps. This guide gives you everything you need to |
| 18 | +run them without reading the canonical file (in case `gh` raw fetch is |
| 19 | +unavailable). |
| 20 | + |
| 21 | +--- |
| 22 | + |
| 23 | +## Step 0 — Collect the 5 inputs upfront. Do NOT improvise |
| 24 | + |
| 25 | +Ask the user for these 5 values BEFORE doing anything. Show them as a |
| 26 | +list and confirm all at once. Do not invent placeholders for missing |
| 27 | +values; if any is missing, stop and ask. |
| 28 | + |
| 29 | +| Input | Example | Notes | |
| 30 | +|---|---|---| |
| 31 | +| Display name | `Secrevo` | Capitalized as the user wants it shown. | |
| 32 | +| Slug | `secrevo` | lowercase, no spaces, no `get` prefix. | |
| 33 | +| GitHub org | `getsecrevo` | Convention: if the slug is taken on GitHub, prefix `get`. The CLI strips `get` to derive the slug. | |
| 34 | +| Domain | `secrevo.com` | The product's primary domain. Used in the `infrastructure` Cat A repo's description. | |
| 35 | +| AWS account ID | `123456789012` | 12 digits. Used in the `infrastructure` description. If pending, ask the user to create the AWS account first — do NOT use a placeholder. | |
| 36 | +| Workspace local path | `~/dev/secrevo-bootstrap/` | Empty directory where the first workspace will live. | |
| 37 | + |
| 38 | +Once confirmed, do not ask again unless the user changes one explicitly. |
| 39 | + |
| 40 | +--- |
| 41 | + |
| 42 | +## Step 1 — Verify CLI + auth + org visibility |
| 43 | + |
| 44 | +```bash |
| 45 | +awac --version 2>&1 || echo "WSP_MISSING" # need 1.5.0+ |
| 46 | +gh auth status >/dev/null 2>&1 || echo "GH_AUTH_MISSING" |
| 47 | +gh api orgs/<ORG> >/dev/null 2>&1 || echo "ORG_NOT_VISIBLE" |
| 48 | +``` |
| 49 | + |
| 50 | +- `wsp` not installed or below 1.5.0 → `pipx install --force <wheel>` from |
| 51 | + the latest `getGanemo/workspace-cli-oss` release. (Private repo. `gh` must |
| 52 | + be authenticated against the GitHub account that owns the org first.) |
| 53 | +- `gh` not authenticated → `gh auth login --web --hostname github.com`. |
| 54 | +- Org not visible → user has to create it on GitHub OR add permissions to |
| 55 | + the PAT / GitHub App. Stop and tell the user. |
| 56 | +- All OK → proceed. |
| 57 | + |
| 58 | +--- |
| 59 | + |
| 60 | +## Step 2 — Show the plan, get explicit user confirmation, THEN scaffold-stack |
| 61 | + |
| 62 | +Before any GitHub-mutating call, print the plan and wait for an explicit |
| 63 | +"OK ejecutá" (or equivalent) from the user. Do NOT proceed with `--yes` |
| 64 | +flags on your own. |
| 65 | + |
| 66 | +The plan to show: |
| 67 | + |
| 68 | +``` |
| 69 | +About to onboard product '<slug>' into AWaC. This will: |
| 70 | +
|
| 71 | +1. Run `awac scaffold-stack <ORG>` which: |
| 72 | + - Introspects the org (currently has 0 repos). |
| 73 | + - Creates <ORG>/agent-stack (private repo) with seed awac.yml. |
| 74 | + - Auto-registers `<slug>: <ORG>/agent-stack` and template |
| 75 | + `<slug>-feature` in getGanemo/agent-stack-core/awac.yml. |
| 76 | +
|
| 77 | +2. Create 3 Cat A repos (private) with governance-compliant READMEs: |
| 78 | + - <ORG>/project_management |
| 79 | + - <ORG>/infrastructure (description includes AWS account + domain) |
| 80 | + - <ORG>/agent-stack (already created in step 1) |
| 81 | +
|
| 82 | +3. Refresh <ORG>/agent-stack to declare the 3 Cat A repos. |
| 83 | +
|
| 84 | +4. Initialize project_management with a first progreso.md |
| 85 | + following manage_project_state convention. |
| 86 | +
|
| 87 | +5. Add devvault.yml catalog to <ORG>/agent-stack with a minimum set of |
| 88 | + secrets (aws, cloudflare). Suggest others based on convention. |
| 89 | +
|
| 90 | +6. Add an audit entry in getGanemo/docs-company governance. |
| 91 | +
|
| 92 | +7. Run `awac audit <slug>` and report 11/11 PASS or list what's missing. |
| 93 | +
|
| 94 | +8. Bootstrap a first workspace in <local-path> using template |
| 95 | + `<slug>-feature`. |
| 96 | +
|
| 97 | +9. Run `awac secrets check <slug>` and report which secrets need to be |
| 98 | + populated in ~/.devvault/<slug>/. |
| 99 | +``` |
| 100 | + |
| 101 | +Wait for the user's literal confirmation in this turn before continuing. |
| 102 | + |
| 103 | +--- |
| 104 | + |
| 105 | +## Step 3 — Execute Step 2 of the canonical workflow: scaffold-stack |
| 106 | + |
| 107 | +```bash |
| 108 | +awac scaffold-stack <ORG> |
| 109 | +``` |
| 110 | + |
| 111 | +Verify the output contains: |
| 112 | +- `pushed: yes (main)` |
| 113 | +- `registry: ok — <slug> registered in getGanemo/agent-stack-core` |
| 114 | + |
| 115 | +If `registry: skipped/no-op` → the auto-register flag was off. Re-run |
| 116 | +with default (no flags) to register. |
| 117 | + |
| 118 | +--- |
| 119 | + |
| 120 | +## Step 4 — Create the 3 Cat A repos |
| 121 | + |
| 122 | +```bash |
| 123 | +awac scaffold-repo <ORG>/project_management --category A |
| 124 | +awac scaffold-repo <ORG>/infrastructure --category A \ |
| 125 | + --aws-account <AWS_ID> --domain <DOMAIN> |
| 126 | +# agent-stack already exists from Step 3, no scaffold-repo needed. |
| 127 | +``` |
| 128 | + |
| 129 | +The seed READMEs are governance-compliant. Each repo is created PRIVATE |
| 130 | +by default. Do not push public. |
| 131 | + |
| 132 | +--- |
| 133 | + |
| 134 | +## Step 5 — Refresh agent-stack to declare the 3 Cat A repos |
| 135 | + |
| 136 | +```bash |
| 137 | +awac scaffold-stack <ORG> --update --push-direct |
| 138 | +``` |
| 139 | + |
| 140 | +`--push-direct` skips the PR review (the user is the org owner; the |
| 141 | +change is additive). Verifies the awac.yml#repos block now lists |
| 142 | +project_management + infrastructure + agent-stack. |
| 143 | + |
| 144 | +--- |
| 145 | + |
| 146 | +## Step 6 — Initialize project_management/progreso.md |
| 147 | + |
| 148 | +Clone the just-created project_management locally, add a first |
| 149 | +`progreso.md` per the `manage_project_state` skill convention: |
| 150 | + |
| 151 | +``` |
| 152 | +# Progreso — <ProductDisplayName> |
| 153 | +
|
| 154 | +## Estado actual (YYYY-MM-DD) |
| 155 | +- Producto onboardeado en AWaC. |
| 156 | +- agent-stack registrado en getGanemo/agent-stack-core. |
| 157 | +- 3 repos Cat A creados. |
| 158 | +
|
| 159 | +## Pendiente |
| 160 | +- Scaffold Cat C/D repos del producto cuando exista código. |
| 161 | +- Crear primer workspace de feature con `awac init`. |
| 162 | +``` |
| 163 | + |
| 164 | +Push to main of `<ORG>/project_management`. |
| 165 | + |
| 166 | +--- |
| 167 | + |
| 168 | +## Step 7 — Author devvault.yml catalog in agent-stack |
| 169 | + |
| 170 | +Edit `<ORG>/agent-stack/devvault.yml` to declare the minimum secrets: |
| 171 | + |
| 172 | +```yaml |
| 173 | +schema: devvault/1 |
| 174 | +product: <slug> |
| 175 | +description: > |
| 176 | + Secrets needed to operate <ProductDisplayName>. |
| 177 | + Resolves against ~/.devvault/<vault_path>/ on the developer's machine. |
| 178 | +secrets: |
| 179 | + aws_account: aws/account.yml |
| 180 | + aws: aws/<slug>.yml |
| 181 | + cloudflare: providers/cloudflare.yml |
| 182 | +``` |
| 183 | +
|
| 184 | +Suggest additions based on the product's nature (e.g. stripe if SaaS |
| 185 | +billing, openai if LLM, smtp if email product). Ask the user before |
| 186 | +adding any. |
| 187 | +
|
| 188 | +Push to main. |
| 189 | +
|
| 190 | +--- |
| 191 | +
|
| 192 | +## Step 8 — Add audit entry in your governance repo |
| 193 | +
|
| 194 | +If your organization keeps a governance doc (the URL set via |
| 195 | +`WSP_GOVERNANCE_DOC`), append a row for the new product there. The path |
| 196 | +is up to your conventions — typical layout is `governance/products.md` |
| 197 | +with a table per product. |
| 198 | + |
| 199 | +Skip this step if your org doesn't track products in a governance doc |
| 200 | +yet — `awac audit` does NOT require it. |
| 201 | + |
| 202 | +Then verify: |
| 203 | + |
| 204 | +```bash |
| 205 | +awac governance check |
| 206 | +``` |
| 207 | + |
| 208 | +Should report aligned. If divergence, re-read both sides and reconcile. |
| 209 | + |
| 210 | +--- |
| 211 | + |
| 212 | +## Step 9 — Audit, bootstrap workspace, validate secrets |
| 213 | + |
| 214 | +```bash |
| 215 | +awac audit <slug> # must report 11/11 PASS |
| 216 | +cd <local-workspace-path> |
| 217 | +awac init <slug>-feature --template <slug>-feature --yes |
| 218 | +cd <slug>-feature |
| 219 | +awac bootstrap |
| 220 | +awac secrets check <slug> # report which secrets need population |
| 221 | +``` |
| 222 | + |
| 223 | +The `--yes` here is justified: the user explicitly confirmed onboarding |
| 224 | +in Step 2 of this guide. If the user did not confirm, stop here and ask. |
| 225 | + |
| 226 | +Report at the end: |
| 227 | +- Audit result (must be PASS). |
| 228 | +- Bootstrap result (file count, .agents/ tree, .stack/<slug>/ contents, |
| 229 | + cloned repos). |
| 230 | +- Missing secrets the user needs to populate from password manager |
| 231 | + (1Password, Bitwarden, etc.). |
| 232 | + |
| 233 | +--- |
| 234 | + |
| 235 | +## Anti-patterns (do NOT do these) |
| 236 | + |
| 237 | +- **Auto-pass `--yes` without explicit user confirmation in this turn**. |
| 238 | + The Step 2 plan exists exactly to catch this. The CLI gates also fire |
| 239 | + (WSP_020) but the discipline is yours. |
| 240 | +- **Invent an AWS account ID or domain because the user didn't say**. |
| 241 | + Stop and ask. A wrong account ID gets baked into the `infrastructure` |
| 242 | + Cat A description and is a chore to fix later. |
| 243 | +- **Skip `awac audit` at the end**. The audit is the canonical "did |
| 244 | + onboarding succeed" check. Don't trust your own narrative; trust |
| 245 | + `audit <slug>` returning 11/11. |
| 246 | +- **Push public the new Cat A repos**. They start private by default; |
| 247 | + promotion to public is a deliberate later decision. |
| 248 | +- **Edit your registry's `awac.yml` manually instead of via |
| 249 | + scaffold-stack auto-register**. The CLI does it idempotently. Set |
| 250 | + `WSP_REGISTRY_REPO` if your registry isn't the default. |
| 251 | +- **Edit `.stack/<slug>/{devvault,deploy}.yml` in the workspace** to |
| 252 | + silence a missing-secret error. Edit canonical in `<ORG>/agent-stack` |
| 253 | + + `awac sync` instead. |
| 254 | + |
| 255 | +--- |
| 256 | + |
| 257 | +## Recovery: a Step failed mid-workflow |
| 258 | + |
| 259 | +- `scaffold-stack` failed → most likely `gh` auth issue or org not |
| 260 | + visible. Re-run after fixing. |
| 261 | +- `scaffold-repo` failed for one Cat A repo → re-run only that one; |
| 262 | + others are independent. |
| 263 | +- `audit` reports failures → read each FAIL entry; the remediation |
| 264 | + field tells you what's missing. Most common: forgot the registry |
| 265 | + auto-register, or didn't add devvault.yml. |
| 266 | +- Wrong AWS account in `infrastructure` description → run `awac |
| 267 | + scaffold-repo <ORG>/infrastructure --category A --update |
| 268 | + --aws-account <CORRECT_ID> --domain <DOMAIN>` to open a PR fixing it. |
| 269 | + |
| 270 | +--- |
| 271 | + |
| 272 | +## Cross-references |
| 273 | + |
| 274 | +- Canonical workflow (in your registry): `<your-registry>/workflows/onboard_new_product.md` |
| 275 | +- Skill: `manage_project_state` (used in Step 6 for progreso.md format). |
| 276 | +- Rule: `aws_resource_safety` (cross-product safety while you have AWS open). |
| 277 | +- Site: https://awac.ganemo.com |
0 commit comments