Commerce Compass

An Adobe App Builder SPA that installs the Claude Code AI toolkit into your Adobe Commerce or App Builder project — step by step, running entirely on your local machine.

How it works

Commerce Compass is a two-part system:

| Part | What it does | |------|-------------| | App Builder SPA (aio app dev) | Wizard UI — collects platform, role, starter kit, and project path | | Local bridge (npm run bridge) | Background server on localhost:3131 — executes setup.sh and streams output back to the SPA |

The SPA cannot write to your filesystem directly (App Builder SPAs run in the browser). The bridge server handles that, streaming live terminal output back so you can see exactly what's happening.

Prerequisites

| Tool | Version | Check | |------|---------|-------| | Node.js | ≥ 18 | node --version | | AIO CLI | latest | npm install -g @adobe/aio-cli | | git | any | git --version | | Claude Code | latest | claude.ai/code |

Quick start

Two terminals, both from the commerce-compass directory:

# Terminal 1 — bridge (runs setup.sh on your machine)
npm run bridge

# Terminal 2 — SPA dev server
npm start

Open the URL printed by npm start (typically https://localhost:9080), complete the wizard, and click Run Setup on this machine.

Wizard steps

1. Platform

| Option | Toolkit installed | |--------|-----------------| | Adobe Commerce | adobe-commerce-ai-toolkit | | App Builder | adobe-appbuilder-ai-toolkit |

2. Starter Kit (App Builder only)

| Option | What gets cloned | |--------|-----------------| | Integration | adobe/commerce-integration-starter-kit (contents merged into your project root) | | Checkout | adobe/commerce-checkout-starter-kit (contents merged into your project root) | | Not applicable | Skip — for existing or standalone apps |

3. Role

| Role | Access | |------|--------| | Developer | Phase 3 (implement) + Phase 4 (validate) | | Lead | Phase 2 (structure) + Phase 3 + Phase 4 | | Architect | All phases 1–4 |

4. Project path

Absolute path to your existing project directory (must start with /).

5. Preview & run

Summarises your config. If the bridge is running, click Run Setup on this machine to install. Live terminal output streams directly in the browser.

What gets installed

Adobe Commerce

Into your project directory (.claude/):

• CLAUDE.md — full domain knowledge and SDLC procedures
• .claude/commands/ — phase commands (/phase1 → /phase4, /dev-feature, /upgrade, /review, /deploy-check, …)
• .claude/hooks/ — quality and audit hooks
• .claude/settings.json — pre-authorised tool permissions
• .commerce-compass — config file (platform, role)
• requirements/REQUIREMENTS.md — project info template

App Builder

Into your project directory (.claude/):

• CLAUDE.md — App Builder domain knowledge and workflow
• .claude/commands/ — App Builder phase commands
• .claude/hooks/ — quality hooks
• .claude/settings.json — pre-authorised tool permissions
• .commerce-compass — config file (platform, role, starter kit)

After setup

1. Open your project in Claude Code
2. Run /commerce-init (Commerce) or /appbuilder-init (App Builder) to verify the setup
3. Start with the command matching your role:
   • Architect: /phase1
   • Lead: /phase2
   • Developer: /phase3

npm scripts

| Script | What it does | |--------|-------------| | npm start | Start SPA dev server (aio app dev) | | npm run bridge | Start local bridge server on port 3131 | | npm run bridge:stop | Kill the bridge server | | npm run build | Build SPA for deployment | | npm run deploy | Deploy SPA to Adobe App Builder Stage | | npm run undeploy | Remove deployed SPA |

Troubleshooting

"Local bridge not running" in the SPA

Start the bridge in a separate terminal:

npm run bridge

Then click Retry in the SPA.

Port already in use

npm run bridge:stop   # kill port 3131
# or for the SPA dev server:
lsof -ti :35729 :9080 | xargs kill -9

Setup fails mid-run

Check the terminal output streamed in the SPA. The most common causes:

• Toolkit repo not accessible (check your network / GitHub access)
• Project path does not exist on disk
• Node.js version below 18

Click Retry after fixing the issue.

aio app dev binds to wrong org

aio config:clear
aio logout
aio login
aio console org select
aio console project select
aio console workspace select
aio app use

Architecture

browser (App Builder SPA)
  │  wizard: platform → [starter-kit] → role → project-path → preview
  │
  │  GET  localhost:3131/api/health   — bridge check on mount
  │  POST localhost:3131/run          — streams setup.sh output via SSE
  ▼
setup-server.js (localhost:3131)
  │
  └─ spawn bash setup.sh --non-interactive --platform … --project … --role … [--starter-kit …]
       │
       ├─ ensure toolkit cached at ~/.commerce-compass/packages/
       │    └─ sparse clone from GitHub on first run, git pull on subsequent runs
       │
       ├─ node <toolkit>/scripts/setup-project.mjs --project … --role …
       │    └─ copies .claude/ commands, hooks, settings, CLAUDE.md into project
       │
       ├─ [App Builder only] git clone starter kit as sibling to project
       │
       └─ write .commerce-compass config into project root

License

Apache-2.0