Two follow-ups from PR review on adobe/skills#91:
1. **Name vs ID disambiguation across `aio console` commands**
bootstrap.md mixed `--projectName`/`--workspaceName` (used by
create/add/list) with `--projectId`/`--workspaceId` (used by select)
without saying which goes where. Added an "Identifier convention"
section near the top of bootstrap.md, with a quick table
(create/add → names; select → IDs; `aio app use` → currently
selected) and a copy-pasteable `jq` recipe to resolve a name to an
ID via `aio console project list --json` /
`aio console workspace list --json`. Also added a recovery-table
row pointing back at the convention when a `select` step fails for
want of an ID.
2. **`--no-config-validation` escape hatch missing from bootstrap.md
recovery table; SKILL.md should enumerate which commands actually
validate**
- bootstrap.md: added a recovery-table row for "post-bootstrap
`aio app *` fails on schema validation" that names
`--no-config-validation` as the one-shot unblock and links to
the corresponding section in debugging.md.
- SKILL.md: expanded the validation troubleshooting bullet to
enumerate the specific commands that trigger validation —
`aio app init`, `aio app add (action|web-assets|extension|event|service)`,
`aio app delete …`, `aio app build`, `aio app deploy`,
`aio app undeploy`, `aio app run`, `aio app dev`, `aio app use`,
`aio app info` — so agents know exactly when the flag applies and
don't reach for it speculatively.
Validation: SKILL.md description still 995 chars (under 1024 limit);
`npx skills-ref validate` passes locally.
Asserting specific plugin floors (e.g. plugin-console >= 5.3.0,
plugin-app >= 14.2.0, lib-runtime >= 7.2.0, ims-oauth >= 6.1.0,
lib-templates >= 3.0.4) made the skill brittle for no real benefit:
- The agent had to grep `aio plugins --core` and parse versions before
doing anything useful.
- Every new release would mean re-tuning the floors.
- All the relevant fixes ship in the same `@adobe/aio-cli` bundle that
one `npm install -g` already pulls.
So replace the preflight with: install (or refresh) the latest CLI
bundle, then run the commands. If a documented subcommand or flag is
still unrecognised after that, the install itself failed (PATH,
permissions, registry mirror) — fix that, don't chase plugin versions.
Touches:
- SKILL.md: simplified `compatibility` frontmatter; rewrote the
bootstrap preflight; collapsed the version-specific troubleshooting
bullets; removed inline "(plugin >= X.Y.Z)" annotations from the
Console bootstrap and init-flag docs.
- references/bootstrap.md: replaced the "Why this exists" version
table with a short paragraph + "just install the latest CLI"
guidance; rewrote the preflight; collapsed the per-step recovery
table to use "CLI bundle is stale" as the single fix; updated the
recommended flow pseudo-code.
- references/debugging.md: merged the "console project create
unrecognised" / "console api list unrecognised" / "plugin-app too
old" entries into one "subcommand or flag is unrecognised → refresh
the bundle" entry; updated the proxy / Docker login / Windows
--no-open entries to point at `npm install -g @adobe/aio-cli` as
the fix instead of name-checking specific lib versions.
- references/templates.md: dropped the `aio-lib-runtime@7.2.0`
citation from the runtime-versions section and the ExC Shell
post-init guidance; the operational guidance ("Stage accepts
nodejs:24, prod stays on nodejs:22") is unchanged.
- README.md: simplified Prerequisites to "install the latest CLI
bundle"; collapsed the troubleshooting table accordingly.
- scripts/init.sh: usage text and header comments no longer reference
specific plugin versions; usage now points users at
`npm install -g @adobe/aio-cli` if a flag is unrecognised.
Validation: `npx skills-ref validate` still passes locally; SKILL.md
description stays at 995 chars (under the 1024 limit); script
`--help` renders cleanly and `bash -n` reports no syntax errors.
The validate workflow fails on this skill because its description is 1355
chars and the validator enforces a 1024-char ceiling. Tighten the wording
without dropping any of the trigger terms (Console project/workspace, APIs,
product profile, SPA / AEM / API Mesh / Asset Compute / MCP, init failure
modes, aio console errors). Now 995 chars; `npx skills-ref validate` passes
locally.
Also unblocks tessl-review, which was skipped because deterministic
validation failed first.
The first pass put the agentic project/workspace/API bootstrap behind
new bash subcommands (`project-create`, `workspace-create`,
`api-list`, `workspace-api-list`, `workspace-api-add`, and a chained
`bootstrap`). That hid the surface area that the
@adobe/aio-cli-plugin-console 5.2.0/5.3.0 releases were specifically
designed to expose, and forced fail-fast semantics where step-by-step
branching (already-exists, profile-required) is what an agent
actually needs.
This commit:
scripts/init.sh
- Removes all `aio console …` wrapper subcommands; the agent calls
those directly per references/bootstrap.md.
- Keeps the `aio app *` wrappers (init, init-bare, add-action,
add-web-assets) — they earn their keep with -y --no-login
--no-install plus mkdir/cwd glue.
- Teaches `init` to pass --org, --project, and --template-options
through to `aio app init` (un-hidden in @adobe/aio-cli-plugin-app
14.2.0), and accept --no-config-validation (added in 14.4.0) for
intentionally mid-edit scaffolds.
- Net: ~340 lines removed from the script.
SKILL.md
- "Bootstrap the Developer Console" rewritten as raw `aio` commands
the agent runs directly, with preflight (plugin version checks),
decision rule, recovery table, and post-bootstrap wiring (either
`init --org --project` or `aio app use --no-input`).
- Compatibility note now also pins plugin-app >= 14.2.0 and mentions
Node 24 stage support.
- Pattern Quick-Reference, Troubleshooting, and Initialize via
Script sections updated to match.
references/bootstrap.md
- Rewritten as an agent-facing playbook of `aio` commands rather
than a script-wrapper guide. Cross-references plugin-app 14.2.0
for the init-time wiring path.
references/debugging.md
- Replaced script-shaped failure tables with raw `aio console …`
failure modes.
- New entries for the additional release notes that affect this
skill: config validation defaults (plugin-app 14.4.0) and OpenWhisk
schema alignment (aio-cli-lib-app-config 4.2.0); proxy fix for
template listing during `aio app init` (aio-lib-templates 3.0.4 +
aio-cli-plugin-telemetry 2.0.3); Docker/CI login via
AIO_IMS_LOCAL_LOGIN_PORT (aio-lib-ims-oauth 6.1.0); and
`aio login --no-open` Windows fix (aio-lib-ims-oauth 6.0.5).
references/templates.md
- Added a Node.js 24-on-stage note backed by aio-lib-runtime 7.2.0,
and updated the excshell post-init guidance to mention nodejs:24
is now an option on stage.
README.md
- Reflects the slimmer script, the relocated bootstrap docs, the
expanded prereqs (plugin-console 5.3.0+, plugin-app 14.2.0+),
and the new troubleshooting entries.
Refactors `appbuilder-project-init` to leverage the non-interactive
commands shipped in `@adobe/aio-cli-plugin-console` 5.2.0 and 5.3.0
so an agent can stand up a Developer Console project, workspace, and
API subscriptions (including services that require a product profile)
without ever opening the Console UI or hitting an interactive prompt.
scripts/init.sh
- New subcommands: project-create, workspace-create, api-list,
workspace-api-list, workspace-api-add, and a chained `bootstrap`
that wraps all three create/add steps in one tool call.
- All new commands use --json and emit a single-line JSON contract
with `success`, plus a `step` field on bootstrap to flag the
failing stage. License-config / product-profile flags are wired
through both `bootstrap` (--api CODE=PROFILE) and `workspace-api-add`
(--license-config).
- Added a console plugin version guard (>= 5.3.0) so callers get a
clear JSON error pointing at `npm install -g @adobe/aio-cli`
instead of a confusing CLI failure on older installs.
SKILL.md / README.md
- New "Bootstrap the Developer Console" section + decision table.
- Updated description, triggers, prereqs, and Pattern Quick-Reference.
- Documented `aio app use --no-input` as the post-bootstrap wiring step.
references/
- Added bootstrap.md: full agentic bootstrap playbook (defaults,
per-step usage, idempotency, recovery).
- Updated debugging.md with bootstrap-specific failure modes
(plugin too old, project name collision, missing product profile,
workspace selection drift after `aio app use`).
Patrick Russell