appbuilder-project-init

---
name: appbuilder-project-init
description: Initialize an Adobe App Builder project end-to-end and prepare the machine to build one. Creates the Console project and workspace, subscribes APIs (including those needing a product profile), maps intent to the right template, runs non-interactive `aio app init`, and guides post-init customization. Use whenever the user mentions creating an App Builder app, scaffolding a project, `aio app init`, an Experience Cloud extension, adding actions or web assets, or creating a Console project/workspace — even without saying "App Builder". Also for SPA templates, AEM extensions, API Mesh, Asset Compute workers, and MCP servers. Also covers first-time machine/CLI setup (Node 20, aio CLI install, `aio login`, IMS org, stage vs prod) and debugging setup/init failures — `ERR_REQUIRE_ESM`, empty `aio console org list`, `451 accept developer terms`, template not found, init hangs, or Node/npm and post-init build errors.
metadata:
  category: project-initialization
license: Apache-2.0
compatibility: Requires aio CLI (Adobe I/O CLI) — install or refresh with `npm install -g @adobe/aio-cli` so the bundled plugins (`aio-cli-plugin-console`, `aio-cli-plugin-app`, etc.) are current. Node.js 18+ (Node 24 supported on Stage runtimes). Bash shell.
allowed-tools: Bash(aio:*) Bash(npm:*) Bash(node:*) Read Write Edit
---
# 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.

## Machine setup (first time)

Do this once per machine before initializing a project — plus a login per environment. If the CLI is already installed and you're logged in, skip to **Bootstrap** below.

### 1. Node 20

App Builder needs **Node 20** (npm ships with it). Check what's active: `node -v` → expect `v20.x`.

- **Have nvm?** `nvm install 20 && nvm use 20 && nvm alias default 20` so new shells keep it. If several Node versions are installed, the *active* one must be 20.
- **No Node / no nvm?** Install nvm, then Node 20:
  ```bash
  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
  # reopen the shell, then:
  nvm install 20 && nvm use 20 && nvm alias default 20
  ```
  (Alternatives: `brew install node@20`, or the official installer at nodejs.org.)

> Older Adobe docs say Node 18 — use **20**. A global `aio` belongs to whichever Node was active when you ran `npm i -g`; if you switch Node versions the old `aio` won't be on PATH. Symptom of a mismatch: `aio` dies with `SyntaxError: Unexpected token '??='` (a pre-20 Node parsing the Node-20 `aio`) — fix with `nvm use 20` and reinstall `aio` there.

### 2. Install the aio CLI + log in

```bash
npm install -g @adobe/aio-cli      # on Node 20
aio login                          # opens a browser; `aio login -f` forces a fresh prompt
aio where                          # confirm the correct IMS org/context
aio console org list               # list orgs and their IDs (then `aio console org select <id>` if needed)
```

Tokens are stored by the CLI automatically; a normal `aio login` lasts hours/days — one login per session, not per command. Confirm the **correct IMS org** — wrong-org is the most common setup mistake.

### 3. Stage vs prod

The default environment is **prod**. To target **stage**, set the env var and re-authenticate:

```bash
export AIO_CLI_ENV=stage
aio logout && aio login
```

Unset the variable (or open a new shell) to return to prod. The stage CLI talks to the stage Console (`developer-stage`).

### Logging in without a browser (CI / no human)

- **Import creds:** in the Developer Console open the workspace → **Download all** → `console.json`, then `aio app init <app> --import path/to/console.json` (fills `.env`/`.aio` — treat `console.json` as a secret, gitignore it).
- **CI / pipeline:** add an **OAuth Server-to-Server** credential to the workspace; `aio` and Runtime authenticate from the client id/secret with no human. Don't script SSO/MFA headlessly.

## 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 |
| Content Hub extension (asset details panel, card action, bulk action) | No generator — scaffold from sample app, see [`references/templates.md`](references/templates.md) |
| 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 commands are called directly — see the **Bootstrap** section above for the rationale.)

> **Note:** The path to this skill's scripts may be `skills/`, `.augment/skills/`, or `.github/skills/` depending on your platform and repository layout. Adjust the prefix in the commands below accordingly.

**With a template:**

```bash
skills/appbuilder-project-init/scripts/init.sh init "@adobe/generator-app-excshell" ./my-project
```

**With a template, fully wired to a specific Console org/project (no post-init `aio app use` needed):**

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

`--org`, `--project`, `--template-options` (base64-encoded JSON), and `--no-config-validation` are passed straight through to `aio app init`. Use the latest `@adobe/aio-cli` so they're all recognised; `--no-config-validation` is the escape hatch for the rare case where a partial scaffold shouldn't yet have to pass schema validation.

**Bare project (no template):**

```bash
skills/appbuilder-project-init/scripts/init.sh init-bare ./my-project
```

Use `init-bare` only when the user explicitly wants to configure everything from scratch. In that case, "bare" means the generated project should stay minimal:

- `app.config.yaml` exists with an empty or minimal `application.runtimeManifest`
- `package.json` exists with only the basic project dependencies
- No pre-scaffolded `src/`, `web-src/`, or `actions/` directories

Why this matters: if the user asked for a bare project, pre-generated actions or web assets contradict that intent and remove the clean starting point they requested.

The script outputs JSON with `success`, `path`, and `output` fields. Check `success` before proceeding.

## Full Workflow (for ambiguous or complex requests)

### Step 1 — Gather intent

Ask the user (or infer from conversation context):

| Question | Examples |
| --- | --- |
| What type of app? | SPA shell, headless API, AEM extension, Asset Compute worker, API Mesh, remote server |
| Needs a UI? | Yes (React Spectrum in ExC Shell), No (actions only) |
| Extension point? | dx/excshell/1, aem/cf-console-admin/1, dx/asset-compute/worker/1, or N/A |
| Additional actions? | Names and purposes of custom actions beyond the default |
| Console state? | Existing project + workspace? Or do we need to create them and subscribe APIs first? |
| APIs needed? | e.g. Adobe I/O Management, Analytics, Target — including any that require a product profile |

If the user simply says "create an App Builder app" with no specifics, default to `@adobe/generator-app-excshell`.

If the Console state is "from scratch" or unknown, run the **Bootstrap the Developer Console** flow before continuing to template selection. See [references/bootstrap.md](references/bootstrap.md) for the full agentic bootstrap playbook.

### Step 2 — Select template

Consult the Template Decision Table above and [references/templates.md](references/templates.md) to map the user's intent to a template.

### Step 3 — Initialize, customize, validate

Follow the **Initialize via Script**, **Post-init customization**, and **Validate** sections below.

## Post-init Customization

Consult [references/templates.md](references/templates.md) for template-specific post-init guidance. Common tasks:

1. **Install dependencies** — Run `npm install` in the project directory. The init script uses `--no-install` to keep initialization fast, but dependencies are required before building or testing.
2. **For API Mesh projects, verify **`mesh.json`** is at the project root** — After `aio app init` with `@adobe/generator-app-api-mesh`, confirm `./mesh.json` exists before treating the scaffold as ready. If the file only exists at `node_modules/@adobe/generator-app-api-mesh/templates/mesh.json`, copy it into place with `cp node_modules/@adobe/generator-app-api-mesh/templates/mesh.json ./mesh.json`. The file under `node_modules/` is the generator's template source, not the project's active API Mesh configuration. Then customize the root `mesh.json` with the user's real source handlers; for multi-backend scenarios, configure at least two handlers.
3. **Clean up bare-project scaffolding if needed** — After `init-bare`, inspect the generated project. If the initializer created `actions/`, `src/`, or `web-src/`, remove those directories before continuing. A bare project should not keep auto-generated action code or web assets.
4. **Headless cleanup after template init** — If the user wants a headless project with **no frontend**, delete any generated UI directory after `aio app init`: `rm -rf web-src/` or the template-specific path such as `rm -rf src/<extension>/web-src/`. Then remove matching `web-src` config from `app.config.yaml` or `ext.config.yaml` if present, especially `web: web-src` and `operations.view` / `impl: index.html` entries. This avoids unnecessary frontend build artifacts and stale manifest wiring in a backend-only project.
5. **Add actions** — If the user later wants custom actions, run `cd ./my-project && skills/appbuilder-project-init/scripts/init.sh add-action "my-action"`.
6. **Add web assets** — Only if the user later decides the bare project needs a UI, run `skills/appbuilder-project-init/scripts/init.sh add-web-assets`.
7. **Edit ext.config.yaml directly** — Customize action definitions:

- Set `runtime: nodejs:22` for production. Stage workspaces also accept `runtime: nodejs:24`.
- Add `inputs:` for environment variables the action needs
- Set `annotations.require-adobe-auth: true` if the action needs IMS tokens
- Set `web: 'yes'` or `web: 'raw'` depending on HTTP access needs

8. **Edit app.config.yaml** — For multi-extension projects, add `$include` entries.
9. **Apply action boilerplate** — Use the `appbuilder-action-scaffolder` skill's boilerplate pattern for production-ready action code with logging, input validation, and error handling.

## Validate

Verify the project structure by checking these items directly:

1. `app.config.yaml`** exists** and contains valid YAML
2. **All **`$include`** paths resolve** to real files
3. `ext.config.yaml` (if present) has `runtimeManifest.packages` with at least one action
4. **Action JS files exist** at all declared `function:` paths
5. `package.json`** exists** with `name`, `version`, and an Adobe SDK dependency (`@adobe/aio-sdk` or `@adobe/aio-lib-core-logging`)
6. **No root-level **`runtimeManifest` in `app.config.yaml` (see Manifest guardrail below)

Read the relevant files and verify each check. Fix any issues before proceeding.

## Build, Test, Deploy (optional)

If the user wants to go beyond scaffolding:

```bash
aio app build       # Build
aio app test        # Run tests
aio app deploy      # Deploy to Adobe I/O Runtime
aio app dev         # Run locally for development (use `aio app run` instead if actions use State SDK, Files SDK, or sequences)
```

## Manifest guardrail

**Extension projects:** Actions are defined under `runtimeManifest` in `ext.config.yaml`, referenced via `$include` from `app.config.yaml`.

**Standalone apps:** Actions go under `application.runtimeManifest` in `app.config.yaml`.

Do not place a root-level `runtimeManifest` directly in `app.config.yaml`: the CLI ignores those actions, so they will not deploy. If you see this shape, move it under `application.runtimeManifest` or into `ext.config.yaml`.

## Troubleshooting & Edge Cases

- `aio`** CLI not installed:** If `aio --version` returns `command not found` or fails, stop before initialization. Ask the user to install Adobe I/O CLI, complete `aio auth login`, and retry only after the CLI is available.
- `npm install`** fails after init:** The scaffold can still be created because init runs with `--no-install`, but builds/tests will fail until dependencies install cleanly. Capture the first package error, confirm the Node/npm version is compatible, rerun `npm install` from the project root, and only continue once it succeeds.
- **Template choice is ambiguous:** If the request could map to multiple templates, ask one clarifying question about UI vs headless, extension point, or target Adobe product. If the user has no preference, default to `@adobe/generator-app-excshell` and state that assumption explicitly.
- **Project directory already exists or is not empty:** Do not overwrite it silently. Ask whether to use a different directory, clear the existing folder, or initialize into a new path.
- `aio console …`** subcommand or flag not recognised:** Almost always means the CLI bundle is stale. Run `npm install -g @adobe/aio-cli` and retry — that's the supported way to refresh every plugin (console, app, runtime, ims-oauth, telemetry). Only dig deeper if the same command still fails after a clean reinstall.
- **Workspace API add fails with "product profile required":** The service code needs a product profile. Re-run `aio console api list --json` to confirm, ask the user (or org admin) for the profile name, and retry with `--license-config CODE=PROFILE`.
- **No org selected:** Console bootstrap commands will fail with an org-selection error. Run `aio console org list` then `aio console org select <orgId>` (or pass `--orgId` to every command) before retrying.
- **Validation errors from a freshly scaffolded but partially edited project:** Recent `aio app *` versions validate `app.config.yaml` by default against an OpenWhisk-aligned schema. The validation runs on every `aio app *` command that reads or writes the manifest — concretely: `aio app init`, `aio app add (action|web-assets|extension|event|service)`, `aio app delete (action|web-assets|extension|event|service)`, `aio app build`, `aio app deploy`, `aio app undeploy`, `aio app run`, `aio app dev`, `aio app use`, and `aio app info`. The escape hatch flag is the same on all of them: `--no-config-validation`. Use it on the single command you need to unblock (e.g. `aio app build --no-config-validation` while you're still mid-refactor), then drop it as soon as the manifest is whole. Don't bake it into scripts — silent drift between local config and the deployed shape is exactly what the validator was added to catch.
- **Template listing hangs behind a corporate proxy:** Older CLI bundles didn't honour `HTTP_PROXY` / `HTTPS_PROXY` during the template registry SSL handshake. Run `npm install -g @adobe/aio-cli` to pick up the proxy fix, confirm `HTTPS_PROXY` is exported in the same shell, and retry.
- `aio`** commands die instantly with `ERR_REQUIRE_ESM` (exit 127):** A clean install can resolve `@adobe/aio-cli-plugin-certificate` to `2.2.0` (shipped as ESM), which the bundled CommonJS console lib cannot `require()` — every `aio where` / `login` / `console` command exits 127 with `[ERR_REQUIRE_ESM]` (though `aio -v` still prints a version, which is misleading). Pin the plugin to the last CommonJS 2.x *inside the global package*: `cd "$(npm root -g)/@adobe/aio-cli" && npm install @adobe/aio-cli-plugin-certificate@2.1.0`. Re-check after any `aio update`.
- `aio console org list`** returns nothing / `[]`:** Login succeeded but the org list is empty — almost always the **wrong environment** (internal Adobe/App Builder dev lives on **stage**, but the CLI defaults to **prod**). Switch: `export AIO_CLI_ENV=stage && aio logout && aio login`. If stage is *also* empty, it's an entitlement problem, not an environment one (needs an App Builder license and the user added under **Admin Console → Users → Developers**).
- `aio console project list`** → `451 … accept developer terms`:** The org's **Adobe Developer Terms of Use** haven't been accepted — a one-time, per-org acceptance the CLI can't do for you. Open the Developer Console (Stage `https://developer-stage.adobe.com/console`, Prod `https://developer.adobe.com/console`), confirm the correct org (top-right), accept the prompt, then re-run the command.

## Chaining with other skills

After initialization, hand off to:

- `appbuilder-action-scaffolder` — For scaffolding actions with playbook, checklist, boilerplate templates, and manifest validation
- `appbuilder-ui-scaffolder` — Build React Spectrum UI for ExC Shell SPAs and AEM extensions

## Pattern Quick-Reference

| Task | Reference | Command |
| --- | --- | --- |
| Bootstrap Console project + workspace + APIs | [references/bootstrap.md](references/bootstrap.md) | `aio console project create` → `aio console workspace create` → `aio console workspace api add` |
| Discover org's available APIs | [references/bootstrap.md](references/bootstrap.md) | `aio console api list --json` |
| Subscribe an existing workspace to an API | [references/bootstrap.md](references/bootstrap.md) | `aio console workspace api add --service-code … [--license-config …]` |
| Initialize an App Builder project from a template | [references/templates.md](references/templates.md) | `scripts/init.sh init` |
| Wire local app to a Console workspace post-init | [references/bootstrap.md](references/bootstrap.md) | `scripts/init.sh init … --org … --project …` *or* `aio app use --no-input` |
| Debug project init issues | [references/debugging.md](references/debugging.md) | — |

## References

- [references/bootstrap.md](references/bootstrap.md) — Agentic Developer Console bootstrap (project, workspace, API subscriptions) via raw `aio console …` commands from the latest `@adobe/aio-cli`
- [references/templates.md](references/templates.md) — Template catalog with intent mapping and per-template post-init guidance (includes the Content Hub extension)
- [references/debugging.md](references/debugging.md) — Troubleshooting guide for init failures, Node/npm issues, login problems, and first-run errors

From adobe/skills at 940b879, shown as plain text under its license: Apache-2.0 (permissive). The license text is in plugins/app-builder/skills/appbuilder-project-init/SKILL.md.

• SKILL.md26 KB · ff5429ec7adc
• README.md8.6 KB · dd5c0974d4ba
• evals/
• evals.json9.0 KB · f5fb17a90cec
• references/
• bootstrap.md10 KB · 41084f1b2681
• debugging.md9.5 KB · 976aa38d057b
• templates.md17 KB · 190235794f80
• scripts/
• init.sh7.7 KB · 772bac62e594

7 files, 88 KB in total. Each file has a sha256 in the pin's manifest; the first 12 characters are shown.