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. 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:

  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

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:

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:

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):

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

Decision rule

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:

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):

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:

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

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):

   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):

   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.

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:

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):

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):

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):

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 for the full agentic bootstrap playbook.

Step 2 — Select template

Consult the Template Decision Table above and 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 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:

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

References

• 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 — Template catalog with intent mapping and per-template post-init guidance
• references/debugging.md — Troubleshooting guide for init failures, Node/npm issues, login problems, and first-run errors