acek-skills 1.2.0 → 1.4.0

package/README.md

@@ -23,6 +23,7 @@ Admin • Development • Testing • DevOps • Security Review • Data Migrat
   - [Non-interactive install](#non-interactive-install)
   - [Org alias templating](#org-alias-templating)
   - [Install targets](#install-targets)
+  - [Sub-agents](#sub-agents)
   - [Skills reference](#skills-reference)
   - [CLI reference](#cli-reference)
   - [Project structure](#project-structure)
@@ -83,7 +84,11 @@ Running `install` with no arguments walks you through three prompts:
    converted into that tool's native rule format.
 3. **Org aliases** — only asked if one of the selected skills references them (currently
    `sf-devops` and `sf-data-migration`). Leave blank to fill in later by hand.
-4. **Commands** — if `sf-architect` is selected and at least one Claude Code target is chosen, its
+4. **Sub-agents** — any selected skill that has a matching sub-agent (same technical id, e.g.
+   `sf-dev`) installs it automatically to `.claude/agents/` on Claude Code targets — no separate
+   prompt. See [Sub-agents](#sub-agents). Not installed for Cursor/Windsurf/Copilot targets, which
+   have no subagent concept.
+5. **Commands** — if `sf-architect` is selected and at least one Claude Code target is chosen, its
    companion `/sf-init` slash command installs automatically to `.claude/commands/` — no separate
    prompt. Not installed for Cursor/Windsurf/Copilot targets, which have no slash-command concept.
 
@@ -139,6 +144,36 @@ Cursor and Windsurf approximate it with their own rule-matching; Copilot's custo
 apply more broadly since it has no equivalent trigger mechanism. Check each tool's docs if the
 matching behavior matters for your workflow.
 
+## Sub-agents
+
+`sf-architect` acts as Salesforce's plan-mode orchestrator: once a plan is approved, it dispatches
+each task to the owner skill's own sub-agent (Claude Code's native `Agent` tool, `subagent_type:
+sf-[owner skill]`) instead of following that skill's conventions itself. Every owner skill has a
+matching sub-agent under `agents/`, same technical id as its skill folder, each with a **fixed**
+narrated persona:
+
+| Owner skill (`subagent_type`) | Persona         |
+| ------------------------------ | --------------- |
+| `sf-admin`                     | Eva Lovia       |
+| `sf-dev`                       | Comatozze       |
+| `sf-testing`                   | Riley Reid      |
+| `sf-devops`                    | Channel Preston |
+| `sf-security-review`           | Madison Ivy     |
+| `sf-data-migration`            | Britney Amber   |
+| `sf-ba`                        | Isla Summer     |
+| `sf-ideation`                  | Asa Akira       |
+
+`sf-architect` itself narrates as **Ashley Fires** and is never dispatched as a sub-agent of
+itself — it only ever assigns work out. Personas are narration only (a response signature line);
+they never appear inside generated file content (PRDs, code, commit messages) except as a tracking
+label in the Architecture Plan's Execution Log.
+
+Installing a skill that has a matching sub-agent installs both automatically, to
+`.claude/agents/<name>.md` — Claude Code targets only, since Cursor/Windsurf/Copilot have no
+subagent equivalent (same rule as `/sf-init`, see [Install targets](#install-targets)). A skill's
+sub-agent works standalone too — dispatch it directly with the `Agent` tool — but it's designed to
+be driven by `sf-architect`'s plan-mode flow.
+
 ## Skills reference
 
 <details>
@@ -148,8 +183,10 @@ Salesforce's plan mode. Gates all work behind an approved Architecture Plan befo
 metadata is touched: runs Discovery (project scan + choice-based clarifying questions, never open
 text), proposes Decisions with trade-offs for data model / automation layer / integration pattern
 / security model / Permission Set strategy, then breaks approved work into tasks dispatched to the
-right skill (`sf-admin`, `sf-dev`, `sf-testing`, `sf-devops`, `sf-security-review`,
-`sf-data-migration`). Plans are saved to `instructions/architecture/` and are resumable across
+right owner skill's **sub-agent** (`sf-admin`, `sf-dev`, `sf-testing`, `sf-devops`,
+`sf-security-review`, `sf-data-migration` — see [Sub-agents](#sub-agents)) — always including a
+`sf-security-review` task when the plan touches a PII-bearing object/field, an integration, or a
+sharing/OWD change. Plans are saved to `instructions/architecture/` and are resumable across
 sessions without re-scanning the project or re-reading chat history. Complements — does not
 replace — `sf-ba` (PRDs) and `sf-ideation` (open-ended brainstorming), and can consume either as
 input.
@@ -177,7 +214,10 @@ data management (import/export/data loader) — anything declarative, no code in
 
 Writes PRDs, user stories, feature specs, and functional requirements — structured Markdown docs
 intended to hand off to an admin or developer. Triggers on "write a PRD", "document requirements",
-"write user stories", or when a business problem needs to become executable documentation.
+"write user stories", or when a business problem needs to become executable documentation. Its
+Admin Spec / Dev Spec templates are for work that will **not** go through `sf-architect`; for
+open-ended brainstorming on a specific existing component instead of net-new requirements, it
+hands off to `sf-ideation`.
 
 </details>
 
@@ -230,8 +270,9 @@ opportunities.
 
 CRUD/FLS checks, sharing model review, `with sharing` enforcement, SOQL injection, XSS in LWC,
 hardcoded credential detection, and a production sign-off checklist. Also covers Shield,
-encryption, audit trail, and a dedicated PII & Data Privacy section — field classification,
-sandbox data masking, and UU PDP-aware review practices.
+encryption, audit trail, a dedicated PII & Data Privacy section — field classification, sandbox
+data masking, and UU PDP-aware review practices — plus Guest User/Experience Cloud access review
+and Connected App/External Client App (OAuth) review checklists.
 
 </details>
 
@@ -239,8 +280,9 @@ sandbox data masking, and UU PDP-aware review practices.
 <summary><strong>sf-testing</strong> — Apex test strategy</summary>
 
 Test classes, `TestDataFactory` patterns, mocking HTTP callouts and platform events, test
-assertions, coverage reports, and debugging org-only test failures. Enforces the 85% coverage
-floor and `AuraHandledException` assertion conventions.
+assertions, coverage reports, debugging org-only test failures, and LWC Jest unit tests
+(`@salesforce/sfdx-lwc-jest`). Enforces the 85% Apex coverage floor, `AuraHandledException`
+assertion conventions, and a 3-scenario minimum (happy/empty/interaction) for every LWC component.
 
 </details>
 
@@ -253,9 +295,13 @@ lives in its `SKILL.md`.
 acek-skills install              Interactive: pick skills, target IDE(s)/tool(s), and org aliases
 acek-skills install --all        Install all skills to Claude Code (project), no prompts
 acek-skills install <name>       Install a single skill to Claude Code (project), no prompts
-acek-skills list                 List available skills and commands
+acek-skills list                 List available skills, commands, and sub-agents
 ```
 
+Any installed skill with a matching **sub-agent** (`.claude/agents/<name>.md`) installs it
+automatically alongside it — Claude Code targets only, since Cursor/Windsurf/Copilot have no
+subagent equivalent. See [Sub-agents](#sub-agents).
+
 Installing `sf-architect` also installs its companion **`/sf-init`** slash command — Claude Code
 targets only (`.claude/commands/`), since Cursor/Windsurf/Copilot have no slash-command
 equivalent. Run `/sf-init` once per project after installing to bootstrap `architecture.md`;
@@ -276,6 +322,15 @@ skills/
   sf-ideation/SKILL.md
   sf-security-review/SKILL.md
   sf-testing/SKILL.md
+agents/
+  sf-admin.md         sub-agent dispatched by sf-architect (subagent_type: sf-admin) — Claude Code only
+  sf-ba.md
+  sf-data-migration.md
+  sf-dev.md
+  sf-devops.md
+  sf-ideation.md
+  sf-security-review.md
+  sf-testing.md
 commands/
   sf-init.md         /sf-init slash command — companion to sf-architect, Claude Code only
 bin/
@@ -299,6 +354,10 @@ bin/
 2. No CLI changes needed — `list` and `install` pick up any folder under `skills/` automatically.
 3. If the skill needs org-specific values, use the `{{PROD_ORG_ALIAS}}` / `{{DEV_ORG_ALIAS}}`
    placeholders (see [Org alias templating](#org-alias-templating)) rather than hardcoding one.
+4. Optional: to make the skill dispatchable as one of `sf-architect`'s sub-agents, add
+   `agents/<name>.md` with the same technical id as the skill folder — see [Sub-agents](#sub-agents)
+   for the frontmatter shape and persona convention. Also no CLI changes needed; `install` matches
+   agent files to skill names by filename.
 
 ## FAQ
 
@@ -310,9 +369,15 @@ responds, and doesn't touch any org, sandbox, or production data on its own.
 Yes — deselect any skill in the interactive wizard, or use `install <name>` for a single one.
 
 **Can I re-run install to update after a new version is published?**
-Yes, `npx` always resolves the latest version unless you pin one (`npx acek-skills@1.2.0 install`).
+Yes, `npx` always resolves the latest version unless you pin one (`npx acek-skills@1.4.0 install`).
 Re-running overwrites previously installed files for the skills/targets you select.
 
+**What are the sub-agents in `.claude/agents/`?**
+Dispatch targets for `sf-architect`'s plan-mode execution — one per owner skill, invoked via
+Claude Code's `Agent` tool (`subagent_type: sf-[owner skill]`) instead of `sf-architect` following
+that skill's conventions itself. See [Sub-agents](#sub-agents). Only installed for Claude Code
+targets; Cursor/Windsurf/Copilot have no subagent concept.
+
 **Why do only Claude Code skills auto-trigger?**
 Claude Code has a native skill system that matches tasks against each skill's `description`
 frontmatter. Cursor, Windsurf, and Copilot don't expose the same mechanism, so their versions are

package/agents/sf-admin.md

@@ -0,0 +1,18 @@
+---
+name: sf-admin
+description: >
+  Salesforce administrator sub-agent — dispatched by sf-architect for tasks whose Owner Skill is
+  `sf-admin`. Handles declarative configuration: custom objects/fields, page layouts, record
+  types, profiles, permission sets, sharing rules, validation rules, and flows.
+tools: Read, Write, Edit, Grep, Glob, Bash
+model: inherit
+---
+
+Open your response with the persona signature line defined in `sf-admin`'s Persona section, then
+load and strictly follow the `sf-admin` skill for every convention, checklist, and pattern in
+this task — do not improvise anything that skill already defines.
+
+The dispatch prompt supplies task-specific details (task ID, description, exact files in
+`Touches`, and any relevant Architecture Plan decisions). Report back a concise summary of what
+changed and where. Do not write to the plan file — only the orchestrator writes status/log
+updates.

package/agents/sf-ba.md

@@ -0,0 +1,16 @@
+---
+name: sf-ba
+description: >
+  Salesforce business analyst sub-agent — dispatched by sf-architect for tasks whose Owner Skill
+  is `sf-ba`. Handles PRDs, user stories, feature specs, and functional requirement documents.
+tools: Read, Write, Edit, Grep, Glob
+model: inherit
+---
+
+Open your response with the persona signature line defined in `sf-ba`'s Persona section, then
+load and strictly follow the `sf-ba` skill for every convention and document structure it
+defines — do not improvise anything that skill already defines.
+
+The dispatch prompt supplies task-specific details (task ID, description, and any relevant
+Architecture Plan context). Report back a concise summary of what document was written and
+where. Do not write to the plan file — only the orchestrator writes status/log updates.

package/agents/sf-data-migration.md

@@ -0,0 +1,18 @@
+---
+name: sf-data-migration
+description: >
+  Salesforce data migration sub-agent — dispatched by sf-architect for tasks whose Owner Skill is
+  `sf-data-migration`. Handles bulk import/export strategy, upsert scripts with External IDs, and
+  data cleansing.
+tools: Read, Write, Edit, Grep, Glob, Bash
+model: inherit
+---
+
+Open your response with the persona signature line defined in `sf-data-migration`'s Persona
+section, then load and strictly follow the `sf-data-migration` skill for every convention,
+checklist, and pattern in this task — do not improvise anything that skill already defines.
+
+The dispatch prompt supplies task-specific details (task ID, description, exact files in
+`Touches`, and any relevant Architecture Plan decisions, including resolved org aliases). Report
+back a concise summary of what changed and where. Do not write to the plan file — only the
+orchestrator writes status/log updates.

package/agents/sf-dev.md

@@ -0,0 +1,18 @@
+---
+name: sf-dev
+description: >
+  Salesforce developer sub-agent — dispatched by sf-architect for tasks whose Owner Skill is
+  `sf-dev`. Handles custom development: Apex classes/triggers/batch jobs, LWC/Aura components,
+  SOQL, and integration/callout code.
+tools: Read, Write, Edit, Grep, Glob, Bash
+model: inherit
+---
+
+Open your response with the persona signature line defined in `sf-dev`'s Persona section, then
+load and strictly follow the `sf-dev` skill for every convention, checklist, and pattern in this
+task — do not improvise anything that skill already defines.
+
+The dispatch prompt supplies task-specific details (task ID, description, exact files in
+`Touches`, and any relevant Architecture Plan decisions). Report back a concise summary of what
+changed and where. Do not write to the plan file — only the orchestrator writes status/log
+updates.

package/agents/sf-devops.md

@@ -0,0 +1,18 @@
+---
+name: sf-devops
+description: >
+  Salesforce DevOps sub-agent — dispatched by sf-architect for tasks whose Owner Skill is
+  `sf-devops`. Handles deployment manifests, dry-run validation, Change Requests, and
+  sandbox-to-production deploys via SF CLI.
+tools: Read, Write, Grep, Glob, Bash
+model: inherit
+---
+
+Open your response with the persona signature line defined in `sf-devops`'s Persona section, then
+load and strictly follow the `sf-devops` skill for every convention, checklist, and pattern in
+this task — do not improvise anything that skill already defines.
+
+The dispatch prompt supplies task-specific details (task ID, description, exact files in
+`Touches`, and any relevant Architecture Plan decisions, including resolved org aliases). Report
+back a concise summary of what changed and where. Do not write to the plan file — only the
+orchestrator writes status/log updates.

package/agents/sf-ideation.md

@@ -0,0 +1,18 @@
+---
+name: sf-ideation
+description: >
+  Salesforce ideation sub-agent — dispatched by sf-architect for tasks whose Owner Skill is
+  `sf-ideation`. Generates anchored enhancement ideas for an existing Apex class, LWC component,
+  or closed/approved PRD.
+tools: Read, Grep, Glob, Write
+model: inherit
+---
+
+Open your response with the persona signature line defined in `sf-ideation`'s Persona section,
+then load and strictly follow the `sf-ideation` skill's anchor requirement and idea-generation
+pattern — do not improvise anything that skill already defines.
+
+The dispatch prompt supplies task-specific details (task ID, description, and the anchor
+file/component/PRD to ground ideas in). Report back a concise summary of the ideas produced and
+where they were written. Do not write to the plan file — only the orchestrator writes status/log
+updates.

package/agents/sf-security-review.md

@@ -0,0 +1,19 @@
+---
+name: sf-security-review
+description: >
+  Salesforce security review sub-agent — dispatched by sf-architect for tasks whose Owner Skill
+  is `sf-security-review`. Handles CRUD/FLS audits, sharing model review, PII/data-privacy
+  checks, and production sign-off.
+tools: Read, Grep, Glob
+model: inherit
+---
+
+Open your response with the persona signature line defined in `sf-security-review`'s Persona
+section, then load and strictly follow the `sf-security-review` skill for every convention,
+checklist, and pattern in this task — do not improvise anything that skill already defines.
+
+This agent is read-only by design — it audits and reports, it never edits code or metadata
+itself. The dispatch prompt supplies task-specific details (task ID, description, exact
+files/components to review, and any relevant Architecture Plan decisions). Report back findings
+and a sign-off status. Do not write to the plan file — only the orchestrator writes status/log
+updates.

package/agents/sf-testing.md

@@ -0,0 +1,18 @@
+---
+name: sf-testing
+description: >
+  Salesforce testing sub-agent — dispatched by sf-architect for tasks whose Owner Skill is
+  `sf-testing`. Handles Apex test classes, TestDataFactory, callout/platform-event mocking, and
+  LWC Jest unit tests.
+tools: Read, Write, Edit, Grep, Glob, Bash
+model: inherit
+---
+
+Open your response with the persona signature line defined in `sf-testing`'s Persona section,
+then load and strictly follow the `sf-testing` skill for every convention, checklist, and pattern
+in this task — do not improvise anything that skill already defines.
+
+The dispatch prompt supplies task-specific details (task ID, description, exact files in
+`Touches`, and any relevant Architecture Plan decisions). Report back a concise summary of what
+changed and where. Do not write to the plan file — only the orchestrator writes status/log
+updates.

package/bin/cli.js

@@ -10,6 +10,7 @@ const target = args[1]; // optional: specific skill name, or "--all"
 
 const SKILLS_SRC = path.join(__dirname, '../skills');
 const COMMANDS_SRC = path.join(__dirname, '../commands');
+const AGENTS_SRC = path.join(__dirname, '../agents');
 
 function printBanner() {
 	console.log(`\x1b[36m
@@ -28,6 +29,7 @@ const TARGETS = {
 		label: 'Claude Code — project (./.claude/skills)',
 		dir: (cwd) => path.join(cwd, '.claude/skills'),
 		commandsDir: (cwd) => path.join(cwd, '.claude/commands'),
+		agentDir: (cwd) => path.join(cwd, '.claude/agents'),
 		format: 'claude',
 		selected: true,
 	},
@@ -35,6 +37,7 @@ const TARGETS = {
 		label: 'Claude Code — global (~/.claude/skills)',
 		dir: () => path.join(os.homedir(), '.claude/skills'),
 		commandsDir: () => path.join(os.homedir(), '.claude/commands'),
+		agentDir: () => path.join(os.homedir(), '.claude/agents'),
 		format: 'claude',
 		selected: false,
 	},
@@ -122,6 +125,30 @@ function installCommandToTarget(commandName, targetKey, cwd, aliases = {}) {
 	fs.writeFileSync(path.join(destDir, `${commandName}.md`), content);
 }
 
+// Sub-agents (.claude/agents/*.md) are dispatched by sf-architect via the
+// Agent tool (subagent_type: sf-<skill>) — one per owner skill, same
+// technical id as the matching skill folder. Like commands, they're a
+// Claude-Code-only concept: Cursor/Windsurf/Copilot have no subagent
+// equivalent, so they only ever install to 'claude' format targets.
+function listAgents() {
+	if (!fs.existsSync(AGENTS_SRC)) return [];
+	return fs
+		.readdirSync(AGENTS_SRC, { withFileTypes: true })
+		.filter((e) => e.isFile() && e.name.endsWith('.md'))
+		.map((e) => e.name.replace(/\.md$/, ''));
+}
+
+function installAgentToTarget(agentName, targetKey, cwd) {
+	const targetDef = TARGETS[targetKey];
+	if (targetDef.format !== 'claude' || !targetDef.agentDir) return;
+	const destDir = targetDef.agentDir(cwd);
+	fs.mkdirSync(destDir, { recursive: true });
+	fs.copyFileSync(
+		path.join(AGENTS_SRC, `${agentName}.md`),
+		path.join(destDir, `${agentName}.md`),
+	);
+}
+
 // Pulls `name`/`description` out of the SKILL.md frontmatter (YAML folded
 // scalar style: "description: >") so non-Claude formats can reuse them.
 function parseSkill(skillName) {
@@ -299,6 +326,7 @@ async function runInteractiveInstall() {
 		);
 	}
 
+	const availableAgents = listAgents();
 	const cwd = process.cwd();
 	for (const targetKey of targets) {
 		for (const skillName of skills) {
@@ -308,6 +336,16 @@ async function runInteractiveInstall() {
 			`✅ ${skills.length} skill(s) installed to ${TARGETS[targetKey].label}`,
 		);
 
+		const agentsToInstall = skills.filter((s) => availableAgents.includes(s));
+		if (agentsToInstall.length > 0 && TARGETS[targetKey].agentDir) {
+			for (const agentName of agentsToInstall) {
+				installAgentToTarget(agentName, targetKey, cwd);
+			}
+			console.log(
+				`✅ ${agentsToInstall.length} sub-agent(s) installed to ${TARGETS[targetKey].label}`,
+			);
+		}
+
 		if (skills.includes('sf-architect') && TARGETS[targetKey].commandsDir) {
 			installCommandToTarget('sf-init', targetKey, cwd, aliases);
 			console.log(
@@ -340,6 +378,17 @@ async function main() {
 			console.log(
 				`✅ All ${available.length} skill(s) installed to ${TARGETS['claude-project'].label}`,
 			);
+			const agentsToInstall = listAgents().filter((a) =>
+				available.includes(a),
+			);
+			for (const agentName of agentsToInstall) {
+				installAgentToTarget(agentName, 'claude-project', process.cwd());
+			}
+			if (agentsToInstall.length > 0) {
+				console.log(
+					`✅ ${agentsToInstall.length} sub-agent(s) installed to ${TARGETS['claude-project'].label}`,
+				);
+			}
 			if (available.includes('sf-architect')) {
 				installCommandToTarget(
 					'sf-init',
@@ -370,6 +419,12 @@ async function main() {
 			console.log(
 				`✅ Installed skill: ${target} → ${TARGETS['claude-project'].label}`,
 			);
+			if (listAgents().includes(target)) {
+				installAgentToTarget(target, 'claude-project', process.cwd());
+				console.log(
+					`✅ Installed sub-agent: ${target} → ${TARGETS['claude-project'].label}`,
+				);
+			}
 			if (target === 'sf-architect') {
 				installCommandToTarget(
 					'sf-init',
@@ -397,6 +452,11 @@ async function main() {
 			console.log('\n⚡ Available commands:');
 			commands.forEach((c) => console.log(`  - /${c}`));
 		}
+		const agents = listAgents();
+		if (agents.length > 0) {
+			console.log('\n🤖 Available sub-agents (dispatched by sf-architect):');
+			agents.forEach((a) => console.log(`  - ${a}`));
+		}
 	} else {
 		console.log(`
 Usage:
@@ -404,7 +464,12 @@ Usage:
   acek-skills install --all        Install all skills to Claude Code (project), no prompts
   acek-skills install <name>       Install a single skill to Claude Code (project), no prompts
 
-  acek-skills list                 List available skills and commands
+  acek-skills list                 List available skills, commands, and sub-agents
+
+Each installed skill that has a matching sub-agent (same technical id, e.g. sf-dev) also installs
+that sub-agent to .claude/agents/ (Claude Code targets only — Cursor/Windsurf/Copilot have no
+subagent equivalent). sf-architect dispatches these during Phase 4 execution instead of following
+their conventions itself.
 
 Installing sf-architect also installs its companion /sf-init slash command (Claude Code targets
 only — Cursor/Windsurf/Copilot have no slash-command equivalent). Run /sf-init once per project

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "acek-skills",
-	"version": "1.2.0",
+	"version": "1.4.0",
 	"description": "Installable Claude Code skills for Salesforce development (admin, dev, BA, testing, devops, security review, data migration, ideation)",
 	"bin": {
 		"acek-skills": "bin/cli.js"
@@ -8,7 +8,8 @@
 	"files": [
 		"bin/",
 		"skills/",
-		"commands"
+		"commands",
+		"agents"
 	],
 	"keywords": [
 		"claude",

package/skills/sf-admin/SKILL.md

@@ -12,9 +12,23 @@ description: >
 
 # Salesforce Administrator Skill
 
+## Persona
+
+When this skill runs — standalone or dispatched as a sub-agent — open the response with:
+
+`— Eva Lovia, sf-admin`
+
+This is narration only. Never include this name inside generated file content: not in PRDs, CRs,
+metadata, code comments, or commit messages. The one existing exception is the Architecture Plan's
+Execution Log (owned by `sf-architect`), which may reference it as a tracking label when this
+skill is dispatched as a sub-agent task.
+
 ## Environment Context
 
-- API Version: **67.0** (Summer '26)
+- API Version: **not hardcoded** — new files inherit whatever `sourceApiVersion` is set in the
+  project's `sfdx-project.json` when scaffolded via SF CLI. When touching an **existing**
+  class/component/metadata item, check its `apiVersion`: below **62.0** → bump to **67.0** as part
+  of the change; 62.0+ → leave as-is unless the task needs 67.0+ behavior specifically.
 - Org Type: Enterprise (single org: sandbox + production)
 - Tooling: **SF CLI** for metadata retrieval; most admin tasks done declaratively in Setup UI
 - Any metadata changes intended for production must go through the DevOps deployment process