sf-builder

A Cowork plugin that helps non-technical Salesforce admins and analysts start and build features for a 2nd Generation Managed Package (2GP) — without wrestling with the command line.

Describe what you want in plain English. The plugin gets your machine ready (project folder, git, GitHub, and a safe Salesforce org), then builds the feature — Lightning Web Components first — and follows your project's own conventions to commit and open a GitHub pull request for the dev team to review.

---

Install

In Claude Code, add the marketplace and install the plugin:

/plugin marketplace add https://github.com/laserburst/sf-builder.git
/plugin install sf-builder@sf-builder

Use the full https://... URL shown above, not the laserburst/sf-builder shorthand — the shorthand can make Claude Code clone over SSH, which fails on machines without GitHub SSH keys configured.

/plugin not available? The /plugin slash command only works in the interactive claude terminal. In the desktop/Cowork app, use the claude plugin … CLI commands below from your shell instead.

Manage the plugin (CLI)

Run these in a terminal. They work whether you installed from git or a local path.

# --- Install from git (end users) ---
claude plugin marketplace add https://github.com/laserburst/sf-builder.git
claude plugin install sf-builder@sf-builder

# --- Install from a local checkout (development / testing a branch) ---
claude plugin marketplace add /path/to/sf-builder      # reads your current branch's files
claude plugin install sf-builder@sf-builder

# --- Update after changes ---
claude plugin marketplace update sf-builder             # re-sync the catalog/files
claude plugin update sf-builder@sf-builder              # pull a new plugin version

# --- Inspect ---
claude plugin list

# --- Remove ---
claude plugin uninstall sf-builder@sf-builder          # remove the plugin
claude plugin marketplace remove sf-builder            # remove the marketplace entry

Restart Claude Code (or start a new session) after install/update so changes load.

---

The dev-start skill

The plugin centers on one skill, dev-start, which takes you from "I just installed this" to "I'm building". It does as much as possible for you, talking in plain English and only stopping when it needs a decision (which project, which org) or a piece of information.

Trigger it by saying things like "get me started", "set up my project", "I just installed this", "start a new feature", or "I want to build / add / change something in Salesforce". Even if you jump straight to "add a field", it runs setup first.

What it does, in order:

1. Fewer approval pop-ups (optional). Offers, once, to add a one-time setting so you aren't asked to approve every routine command. Saving your work and opening a pull request still check with you first.
2. Project folder. Keeps every project under one parent folder (default ~/salesforce-projects/), with one subfolder per feature.
3. Checks your tools. git, GitHub (gh), and the Salesforce CLI (sf) — installed and signed in. Anything missing is fixed for you, or shown on a status card with clear, clickable next steps.
4. Picks the project. Lists the GitHub repos you can access and clones the one you choose.
5. Makes a feature branch off develop (or main / master).
6. Connects a safe org. Lists your Salesforce orgs and lets you pick a scratch org or sandbox — never production or a Dev Hub (see Safety below). If you don't have one, ask your dev team for access and the plugin connects it for you.
7. Builds the feature, defaulting to Lightning Web Components, then follows your project's own skills and conventions for the rest (commit, validate, open the PR).

Every check shows a visual status card — green when it passed, red with concrete fix-it steps when it didn't.

---

Commands: saving your work and opening a PR

Saving work and opening a pull request are outward, hard-to-undo actions, so they're not done automatically — they're slash commands you run yourself. The assistant can suggest them, but only you can invoke them:

Command	What it does
/sf-builder:dev-commit	Stages, commits, and pushes your changes to your feature branch on GitHub. Optionally takes a message: /dev-commit added the contact table.
/sf-builder:dev-complete	Saves your work and opens a pull request for your dev team to review — creating it only if one doesn't exist yet.

Both talk in plain English and show a status card with the result (and the PR link for dev-complete). They run git push / gh pr create only because you invoked them.

---

Why LWC-first

With AI, a non-developer can produce a lot of code quickly — and a human developer has to review all of it. Lightning Web Components are safer to hand over than Apex: LWC works through the platform's data layer, which respects the running user's permissions (sharing and field-level security) automatically, whereas Apex runs in system mode and can bypass them if not written carefully.

So the plugin:

• reads data, including complex queries, with the GraphQL wire adapter;
• creates and updates records with Lightning Data Service;
• writes Apex only when something genuinely can't be done in LWC — and flags it clearly for review.

---

Safety: development orgs only

The plugin will only build against a scratch org or a sandbox. Production orgs and Dev Hubs are never valid build targets — when a connected org is ambiguous, it confirms by asking the org itself (SELECT IsSandbox FROM Organization). If you connect a production org, the plugin won't refuse the connection, but it will refuse to use it as a target and ask for a sandbox or scratch org instead.

---

Prerequisites

dev-start checks for these and fixes or guides anything missing:

Tool	Install
Salesforce CLI (sf)	https://developer.salesforce.com/tools/salesforcecli
GitHub CLI (gh)	https://cli.github.com

If the cloned project already ships a graphify knowledge graph (a graphify-out/graph.json or a committed .claude/skills/graphify/), the plugin will query it to find existing components and avoid duplicates. It will not install or build a graph for you — that's a heavy operation best left to the dev team. Without a graph, the plugin simply reads the force-app/ source directly.

---

PLUGIN_CONTEXT.md — project conventions file

If your SFDX repo has a PLUGIN_CONTEXT.md at its root, the plugin reads it during the build phase and treats it as the source of truth for naming conventions, approved patterns, and team notes — alongside any skills the project ships in its own .claude/skills/.

Format:

# Project Context

## Package
- Namespace: myns
- Package name: My Managed Package
- Base branch: develop

## Conventions
- Custom object names: PascalCase, no abbreviations
- Field names: Snake_Case_With_Capitals
- Permission sets: <Feature>_Access (e.g. Renewal_Access)
- Off-limits: do not add fields to the Account object without team approval

## Notes
- All features must have an associated permission set
- Scratch org definition: config/project-scratch-def.json

---

Repo structure expected

The plugin assumes a standard Salesforce DX (SFDX) project layout:

your-sfdx-repo/
├── sfdx-project.json          # Package config (namespace, packageDirectories)
├── force-app/
│   └── main/
│       └── default/
│           ├── lwc/
│           ├── objects/
│           ├── permissionsets/
│           └── ...
├── config/
│   └── project-scratch-def.json
└── PLUGIN_CONTEXT.md          # Optional — team conventions

---

For contributors: card templates

Each skill is fully self-contained — no symlinks, no shared files, nothing to enable on any platform (Windows included).

• dev-start owns the full, canonical card spec at skills/dev-start/references/status-card.md — all card types (success / info / error), choice cards, the one-time-code box, and the rules for when to use each.
• dev-commit and dev-complete only ever render a success or error card, so each inlines a small copy of that template at the bottom of its own SKILL.md.

dev-start also ships build-phase reference docs:

• references/2gp-rules.md — the 2GP package constraints it always enforces (implicit namespace, no hardcoded IDs, permission-sets-not-Profiles, field type/existence permanent after release, correct SFDX paths).
• references/lwc-guidance.md and references/apex-guidance.md — default LWC/Apex patterns it consults only where the cloned project's own conventions are silent (the project always wins). These are adapted from the MIT-licensed david-sfdev/claude-sf-skills; see CREDITS.md.

If you change the card look, update the canonical status-card.md and glance at the two inline snippets to keep them visually consistent. (They're intentionally minimal, so they rarely need to change.)

---

Future integrations (not in this version)

• Jira — create/link stories on PR open
• Slack — post PR notification to team channel