appbuilder-project-init

What this skill does

# App Builder Project Initialization

Maps user intent to the right Adobe App Builder template and runs non-interactive `aio app init`. Default: `@adobe/generator-app-excshell` (SPA + actions). For headless/bare projects, use `init-bare`.

When a Developer Console project / workspace / API subscription does not yet exist, this skill walks the agent through creating them non-interactively by calling `aio console …` directly — see the **Bootstrap** section and [references/bootstrap.md](references/bootstrap.md). The latest `@adobe/aio-cli` bundle exposes non-interactive `aio console project create` / `workspace create` / `api list` / `workspace api add` (with `--license-config` for services that require a product profile), and non-interactive `aio app init --org/--project/--template-options`. Together they remove every blocking "open the Developer Console UI and click" step from the agentic setup path. Just install the latest CLI (`npm install -g @adobe/aio-cli`) and use them.

## Bootstrap the Developer Console (project, workspace, APIs)

If the user is starting from zero — no Developer Console project yet, or an existing project that is missing a workspace or API subscription — bootstrap that state **before** `aio app init`. Otherwise `aio app init` / `aio app use` / `aio app deploy` have nothing to wire the local app to.

The full bootstrap is just `aio` commands; **call them directly**, not through a wrapper script. They are already non-interactive in the recent plugin releases, and per-step calls let you react to "already exists" or "needs a product profile" responses without baking those decisions into bash.

### Preflight

Make sure the CLI is current — that's what brings in the non-interactive Console + app init commands:

```bash
npm install -g @adobe/aio-cli
aio --version
```

Don't try to assert specific plugin versions; just take the latest. If a `console` or `app` subcommand below is rejected as "command not found" or "unknown flag" after this, the CLI install genuinely failed (PATH issue, permissions, registry mirror) — fix the install rather than working around it.

Confirm an org is selected (or pass `--orgId` on every command below):

```bash
aio console org list --json   # if needed, then:
aio console org select <orgId>
```

### Decision rule

| User state | Next action |
| --- | --- |
| "Create a project + workspace + add APIs from scratch" | Run the bootstrap chain (project → workspace → APIs), then `aio app init`. |
| Project exists, workspace missing | Skip project-create. Run `aio console workspace create`, then optionally `aio console workspace api add`. |
| Project + workspace exist, only need to add an API | Run `aio console api list` to discover service codes, then `aio console workspace api add`. |
| Everything already wired | Skip bootstrap. Go straight to **Initialize via Script**. |

Always check what already exists with `aio console project list --json` and `aio console workspace api list --projectName <p> --workspaceName <w> --json` before creating — these commands fail loudly on "already exists" and there is no built-in idempotency.

### The bootstrap chain (raw commands)

Step 1 — create the Console project:

```bash
aio console project create -n my-project --json
# optional: -t "Title" -d "Description" -o <orgId>
```

Step 2 — create a workspace inside it (`Stage` is the conventional first non-Production workspace; pick a more descriptive name in long-lived shared projects):

```bash
aio console workspace create \
  --projectName my-project \
  --name Stage \
  --json
# optional: --orgId <orgId> --title "Stage workspace"
```

Step 3 — discover and subscribe the APIs the app needs:

```bash
aio console api list --json   # see all service codes available to the org
                              # entries flagged for whether they need a product profile

# Free-tier service:
aio console workspace api add \
  --projectName my-project \
  --workspaceName Stage \
  --service-code AdobeIOManagementAPISDK \
  --json

# Service that requires a product profile:
aio console workspace api add \
  --projectName my-project \
  --workspaceName Stage \
  --service-code AdobeAnalyticsSDK \
  --license-config AdobeAnalyticsSDK=AnalyticsProductionProfile \
  --json
```

`--service-code` accepts a comma-separated list to subscribe several free-tier services in one call. `--license-config` is repeatable when several profile-bound services are added together.

### Recover from per-step failures

| Failure | What to do |
| --- | --- |
| `project create` fails with "already exists" | Read `aio console project list --json`, reuse the existing project's name, and continue at step 2. |
| `workspace create` fails with "already exists" | List workspaces with `aio console workspace list --projectName <p> --json` and continue at step 3. |
| `workspace api add` returns "product profile required" | The service code requires `--license-config`. Ask the user (or the org admin) for the profile name and retry with `--license-config CODE=PROFILE`. |
| Any step returns an org-selection error | Pass `--orgId <id>` explicitly, or `aio console org select <id>` once before retrying. |

### Wire the local app to the bootstrapped state

Two equivalent ways to point a fresh `aio app init` at the project/workspace you just created:

1. **Pass them as flags to `init` itself** (cleanest):

   ```bash
   skills/appbuilder-project-init/scripts/init.sh init \
     "@adobe/generator-app-excshell" ./my-project \
     --org <orgId> --project my-project
   ```

   The wrapper passes `--org` / `--project` / `--template-options` straight through to `aio app init`, on top of the existing `-y --no-login --no-install` flags.

2. **Run `aio app use` after init** (works on any plugin version):

   ```bash
   cd ./my-project
   aio app use --no-input   # adopts the currently selected project/workspace, no prompts
   ```

Either route ends with the local `.aio` and `.env` pointing at the workspace you just bootstrapped, so `aio app deploy` publishes to the right namespace.

## Fast Path (for clear requests)

When the user's intent maps unambiguously to a single template — for example, they name a template directly or describe an app that clearly matches exactly one entry below — skip straight to **Initialize via Script** below. Use the matched template and any project name the user provided (or a sensible default).

Examples of fast-path triggers:

- "Create an App Builder app using `@adobe/generator-app-excshell`" → use that template, run init
- "Set up an Asset Compute worker" → maps unambiguously to `@adobe/generator-app-asset-compute`, run init
- "Create a new App Builder app" (no specifics) → defaults to `@adobe/generator-app-excshell`, run init
- "Initialize a bare project" → use `init-bare`, run init

If there is any ambiguity — multiple templates could fit, or the user's constraints are unclear — use the full template decision table and workflow below.

## Template Decision Table

Pick the template that matches the user's intent. When unclear, default to `@adobe/generator-app-excshell`.

| User wants | Template |
| --- | --- |
| SPA with actions + React UI | @adobe/generator-app-excshell |
| AEM Content Fragment Console extension | @adobe/aem-cf-admin-ui-ext-tpl |
| AEM React SPA (WKND-based) | @adobe/generator-app-aem-react |
| Adobe API Mesh (GraphQL) | @adobe/generator-app-api-mesh |
| Asset Compute custom worker | @adobe/generator-app-asset-compute |
| Remote server on App Builder | @adobe/generator-app-remote-mcp-server-generic |
| Bare / from-scratch project (no pre-scaffolded actions or UI) | init.sh init-bare |

For a headless/backend-only request, prefer `init-bare` when possible. If the user still needs a template that generates UI files, plan a post-init cleanup so the final project has no `web-src` frontend directory or web manifest wiring.

## Initialize via Script

The `aio app *` wrappers go through a single script: `scripts/init.sh`. (Console bootstrap comm