Recipe · Add a new SDK

Goal: scaffold a new publishable @engineering11/* SDK — backend or frontend flavor — ready to be developed, built, and published.

Time: ~5 minutes interactive · Owner: E11 Bootstrapper · Workflows: e11-bootstrap-wizard → e11-scaffold-sdk-backend or e11-scaffold-sdk-frontend

Prerequisites

• Foundry installed in a control project.
• @engineering11/alloy installed in the same control project.
• A name for the new SDK (kebab-case, will become @engineering11/<name>).

When to scaffold an SDK vs an in-repo microservice

Scaffold an SDK ([NS]) when…	Scaffold an in-repo microservice ([NM]) when…
The capability is reusable across multiple E11 projects	The capability is specific to one platform deployment
You'd publish it to GitHub Packages	It should never be published
Other teams will depend on it	Only this backend depends on it
It maps to a platform concept (auth, files, etc.)	It's domain logic for this product

If you're not sure, prefer [NM] first — it's lighter-weight. You can promote a microservice into an SDK later if it generalises.

Walkthrough — backend SDK

You: @e11-bootstrapper NS

Bootstrapper: Starting bootstrap wizard, scaffold_type=sdk.

  Which flavor? [backend | frontend]

You: backend

Bootstrapper: Step 1 — SDK identity
  Package name (will be @engineering11/<name>)?

You: reconciliation

Bootstrapper: Output root? (default: ../reconciliation)

You: [accept default]

Bootstrapper: Step 2 — Packages to scaffold
  Backend SDKs typically have: api, rest, tasks, functions, client, jobs.
  Toggle which to include (api is recommended; others optional based on usage):
    [x] api     [ ] rest     [ ] tasks    [ ] functions
    [ ] client  [ ] jobs

You: api, rest, tasks

Bootstrapper: Step 3 — Peer SDKs (informational)
  Querying matrix:unit for related SDKs you may depend on:
    auth, user, access, datastores, configuration, logging, errors

  These will NOT be installed automatically — your SDK is a peer.
  You'll add specific deps in package.json as you build out the SDK.

  Step 4 — Summary
    output_root: /Users/you/work/reconciliation
    scaffold_type: sdk (backend)
    packages: api, rest, tasks
    Workflow: e11-scaffold-sdk-backend

  Confirm? [C]

You: C

Bootstrapper: Handing off to e11-scaffold-sdk-backend workflow.
  [generates SDK monorepo]
  [runs npm install]
  [runs npm run build]
  ✓ Scaffold complete at /Users/you/work/reconciliation

Walkthrough — frontend SDK

The frontend flavor is similar but produces a different shape (one package per surface — no rest / tasks split):

@e11-bootstrapper NS

Bootstrapper: Which flavor? [backend | frontend]

You: frontend

Bootstrapper: Package name (will be @engineering11/<name>-client)?

You: reconciliation

Bootstrapper: [proceeds through frontend-specific prompts]
  Workflow: e11-scaffold-sdk-frontend
  ✓ Scaffold complete.

What you get (backend SDK)

@engineering11/reconciliation/
├── packages/
│   ├── api/                    # types + interfaces (always)
│   │   ├── src/
│   │   ├── package.json        # @engineering11/reconciliation-api
│   │   └── tsconfig.json
│   ├── rest/                   # REST handlers (when selected)
│   ├── tasks/                  # task handlers (when selected)
│   └── ...
├── package.json                # @engineering11/reconciliation (workspace root)
├── tsconfig.base.json
├── README.md
└── STANDARDS.md                # link to alloy://shared/conventions/code-standards-backend.md

After scaffolding — developing the SDK

Once the scaffold exists, the actual SDK development follows the gen-sdk skill (resolved via skill:e11-knowledge pattern:gen-sdk). The skill walks you through:

• Defining the API contract in packages/api
• Implementing rest / tasks / functions handlers
• Wiring up tests
• Updating the README + STANDARDS

For complex SDK work you'll usually pair this recipe with:

• [CA] Create Architecture (if the SDK's design is non-trivial)
• [QK] Query Knowledge for pattern:gen-sdk, convention:code-standards-backend, and related SDK docs

Publishing

Once your SDK builds and has tests, publish it:

cd /Users/you/work/reconciliation
npm version minor                    # or major/patch
npm publish                          # publishes to GitHub Packages

GitHub Packages auth needs the same read:packages token (or a write:packages token for publishing). See installation.

Gotchas

• -client suffix for frontend SDKs. The convention is @engineering11/<name>-client for frontend-flavored SDKs. The wizard adds it for you when flavor=frontend.
• api is always recommended. It defines the types both consumers and the SDK implementation share. Without it, you'll regenerate types twice.
• gen-sdk isn't in alloy yet. The full SDK-generation guide is at sdks-nodejs-skill://gen-sdk.md, resolved via the four reserved upstream-skill keys. The Bootstrapper just sets up the scaffolding; the development guide lives upstream.
• Choose flavor up front. You can't easily convert a backend SDK to frontend (or vice versa) after the fact. Pick correctly.
• The first commit is yours. The scaffold doesn't git init. Initialize the repo and commit the generated tree as your first commit before any local edits.

Source

Agent: e11-bootstrapper/SKILL.md · workflows: e11-scaffold-sdk-backend/SKILL.md, e11-scaffold-sdk-frontend/SKILL.md · generation skill: sdks-nodejs-skill://gen-sdk.md

See also: Phase 5 — Scaffold · Knowledge layer (for the upstream-skill keys).