Adobe App Builder AI Toolkit (Claude Code)

Phase-gated SDLC for Adobe App Builder development — greenfield apps and Commerce → App Builder migrations — powered by Claude Code.

Extracted from commerce-compass as a standalone tool, so App Builder workflows can be installed, versioned, and developed independently of general Commerce module-development tooling.

Quick Reference

| Task | Command | |---|---| | Start session / switch requirement | /appbuilder-init | | Create a new requirement | /new-requirement <name> | | Check phase status (all requirements) | /appbuilder-status | | New feature (full workflow) | /dev-action <description> | | Scaffold a runtime action | /action-create <name> <type> | | Scaffold a UI extension | /ui-extension-create <extension-point> <label> | | Scaffold API Mesh | /mesh-create <description> | | Commerce → App Builder migration plan | /appbuilder-migrate | | Migration effort estimate | /appbuilder-estimate | | Live Adobe docs lookup | /appbuilder-docs <topic> | | Validate structure | /appbuilder-validate-quick | | Pre-commit check | /review-before-commit | | Full PR review | /review | | Pre-deploy validation | /deploy-check [Stage\|Production] | | Configure workspace | /workspace-setup [Stage\|Production] | | Project health & tech debt | /tech-debt-triage |

Phase Commands (role-gated)

| Command | Role | Purpose | |---|---|---| | /phase1 | Architect, Lead | Requirements & architecture | | /phase2 | Architect, Lead | Scaffold project structure | | /phase3 | Developer, Lead | Implement actions & extensions | | /phase4 | Developer, Lead | Test, validate, deploy to Stage |

How It Works

The toolkit enforces a phase-gated SDLC. Each phase has clear ownership, gates, and deliverables. No phase skipping. No code before requirements are signed off.

Phase 0 — Environment      /appbuilder-init
Phase 1 — Requirements     /phase1   (Architect/Lead)
Phase 2 — Scaffold         /phase2   (Architect/Lead)
Phase 3 — Implement        /phase3   (Developer)
Phase 4 — Deploy to Stage  /phase4   (Developer)

Each requirement (e.g. loyalty-app, order-sync) lives in its own directory with a REQUIREMENTS.md and per-requirement .phase-state.json. A single App Builder project can track multiple requirements independently.

project-root/
├── loyalty-app/REQUIREMENTS.md   ← requirement spec + phase markers
├── order-sync/REQUIREMENTS.md
├── .claude/active-requirement    ← which requirement is being worked on
├── app.config.yaml               ← shared App Builder config
└── actions/                      ← shared runtime actions

Phase state is persisted in <req-dir>/.phase-state.json.

Project Types

Greenfield (APPBUILDER_PROJECT_TYPE=greenfield) Building a new App Builder app from scratch. Follows Phase 0 → 4.

Migration (APPBUILDER_PROJECT_TYPE=migration) Moving existing Commerce custom modules to App Builder. Adds:

• /migration-approach — choose full ACCS/SaaS migration vs a lighter PaaS + App Builder extension
• /appbuilder-migrate — analyse Commerce modules, produce MIGRATION_PLAN.md
• /appbuilder-estimate — effort estimation report with complexity tiers and risk multipliers
• /accs-workstream-hop-plan — break the workstream plan into 5 trackable hops
• /accs-workstream-hop-execute <hop> — execute one hop with gated, per-component tracking

Setup

Prerequisites

node >= 18
npm install -g @adobe/aio-cli
aio login

Install into your App Builder project

aio plugins:install @adobe-thillai/aio-cli-plugin-ccma
cd /path/to/your/app-builder-project
aio ccma:setup

This copies .claude/commands, .claude/agents, .claude/skills, .claude/guardrails, .claude/prompts, .claude/context, .claude/hooks, and CLAUDE.md into the target project, then installs and wires up the CodeGraph and FluffyJaws MCP servers.

aio ccma:setup --project /path/to/your/app-builder-project --role full --type greenfield

Roles:

• full — all commands and agents (Architect)
• lead — Phase 2/3/4 commands (Lead Developer)
• developer — Phase 3/4 + daily workflow commands (Developer)

Types:

• greenfield — building a new App Builder app from scratch
• migration — moving existing Commerce custom modules to App Builder

Wire (or re-verify) just the commerce-extensibility-tools MCP server:

aio ccma:mcp:setup --project /path/to/your/app-builder-project

Environment Variables

Create .env in your App Builder project root:

AIO_runtime_namespace=<your-namespace>
AIO_runtime_auth=<your-auth-key>
SERVICE_API_KEY=<oauth-s2s-client-id>
SERVICE_API_SECRET=<oauth-s2s-client-secret>
COMMERCE_BASE_URL=https://your-commerce-store.example.com
COMMERCE_ACCESS_TOKEN=<integration-token>
COMMERCE_WEBHOOKS_PRIVATE_KEY=<hmac-key-if-using-webhooks>
LOG_LEVEL=info

Never commit .env to git. It is automatically added to .gitignore by the setup script.

Slash Commands

Core Workflow

• /appbuilder-init — Session start. Detects environment, displays phase dashboard.
• /appbuilder-status — Current phase and next action.
• /appbuilder-docs <topic> — Live Adobe docs lookup (WebSearch).

Development

• /dev-action <description> — Orchestrator: architect design → implementation → security review → tests.
• /action-create <name> [type] — Scaffold one runtime action. Types: webhook, event-handler, api-proxy, scheduled.
• /ui-extension-create <point> <label> — Scaffold Admin UI SDK extension.
• /mesh-create <description> — Create API Mesh configuration.

Migration

• /migration-approach — Choose full ACCS/SaaS migration vs a lighter PaaS + App Builder extension.
• /appbuilder-migrate — Analyse Commerce modules → produce MIGRATION_PLAN.md.
• /appbuilder-estimate — Effort estimation report (ESTIMATION_REPORT.md).
• /accs-workstream-hop-plan — Break the workstream plan into 5 trackable hops (accs-hop-state.md).
• /accs-workstream-hop-execute <hop> — Execute one hop: gated pre-check, per-component dispatch, validation.

Quality & Review

• /review-before-commit — Pre-commit: validate structure, check credentials, review staged changes.
• /review [files] — Full PR review with parallel agent checks (architect, security, QA).
• /appbuilder-validate-quick — Fast structure + pre-deploy check.

Deployment

• /deploy-check [Stage|Production] — Go/no-go: automated checks + parallel agent review + smoke test checklist.
• /workspace-setup [Stage|Production] — Verify aio auth, workspace binding, env vars, services.

Maintenance

• /tech-debt-triage — Full project health check: oversized actions, missing tests, security gaps, dependency audit.

Specialist Agents

Invoked automatically by workflow commands — not called directly.

| Agent | Role | |---|---| | appbuilder-architect | Design, action type selection, migration planning, storage strategy | | appbuilder-developer | Implementation, action code, event handlers, UI extensions | | appbuilder-security-reviewer | IMS auth, HMAC verification, credential safety, PII | | appbuilder-qa-engineer | jest tests, coverage analysis, smoke test checklists | | appbuilder-devops-engineer | CI/CD pipelines, workspace config, deployment procedures |

Guardrails (Always Active)

| Guardrail | Rule | |---|---| | credential-security | No hardcoded secrets. .env only. Workspace secrets for Production. | | locked-core-principle | Never touch Commerce PHP. Extend via APIs, Events, Webhooks. | | pii-protection | No PII in logs. IDs only. TTL on customer data in state. | | deployment-safety | Confirm workspace before deploy. Never auto-deploy to Production. |

Directory Layout (installed into target project)

<your-project>/
├── CLAUDE.md                    # Loaded on every session — all instructions
├── REQUIREMENTS.md              # Requirements + phase markers (created by /phase1)
├── MIGRATION_PLAN.md            # Migration plan (created by /appbuilder-migrate)
├── app.config.yaml              # App Builder runtime manifest
├── .env                         # Local credentials (gitignored)
└── .claude/
    ├── settings.json            # Permissions + hooks + env vars
    ├── agents/                  # 5 specialist agents
    ├── commands/                # 19 slash commands
    ├── guardrails/              # 4 safety rules (always loaded by agents)
    ├── skills/                  # 7 reference knowledge files
    ├── prompts/                 # 4 review templates
    ├── context/                 # 5 runtime state files (fill in per project)
    └── hooks/                   # Harness hooks (quality log, phase gate)

Prerequisites for Commerce Integration

Before the App Builder app can receive Commerce events or webhooks:

1. Install adobe/commerce-eventing (Composer) in Commerce
2. Configure IMS in Commerce Admin → Stores → Configuration → Adobe Services → Adobe I/O
3. Connect the App Builder project in Developer Console → your project → Event Provider
4. For webhooks: install magento/module-webhook and configure in Commerce Admin → System → Webhooks

References

• App Builder docs: https://developer.adobe.com/app-builder/docs/
• Admin UI SDK: https://developer.adobe.com/commerce/extensibility/admin-ui-sdk/
• Commerce Events: https://developer.adobe.com/commerce/extensibility/events/
• Commerce Webhooks: https://developer.adobe.com/commerce/extensibility/webhooks/
• API Mesh: https://developer.adobe.com/graphql-mesh-gateway/
• aio CLI: https://developer.adobe.com/runtime/docs/guides/tools/cli_install/