acek-skills 1.3.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,10 +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`) — 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
+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.
@@ -260,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`;
@@ -283,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/
@@ -306,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
 
@@ -317,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.3.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.3.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,6 +12,17 @@ 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: **not hardcoded** — new files inherit whatever `sourceApiVersion` is set in the

package/skills/sf-architect/SKILL.md

@@ -17,6 +17,18 @@ description: >
 
 # Salesforce Architect Skill (sf-architect)
 
+## Persona
+
+When this skill runs, open the response with:
+
+`— Ashley Fires, sf-architect`
+
+This is narration only. Never include this name inside generated file content: not in PRDs, CRs,
+Apex/LWC code, code comments, or commit messages. The one exception is the Architecture Plan's
+Execution Log, which may reference dispatched sub-agents' own personas as tracking labels (see
+[Sub-Agent Personas](#sub-agent-personas) in Phase 4) — Ashley Fires' own name does not appear
+there since the orchestrator is never dispatched as a sub-agent of itself.
+
 ## Core Principle
 
 sf-architect is Salesforce's plan mode. It never touches an org, writes code, or creates metadata
@@ -39,20 +51,25 @@ Three rules govern everything below:
 ## Relationship to Other Skills
 
 sf-architect does not replace any existing skill — it decides, sequences, and dispatches to them.
-
-| Skill                | sf-architect's relationship to it                                                                                                                                                                                                                                             |
-| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `sf-ideation`        | Optional **input**. If open-ended brainstorming already happened, architect can consume its output as a starting point. Architect itself does not brainstorm — it decides between already-surfaced options.                                                                   |
-| `sf-ba`              | Optional **input**. If a PRD exists (`instructions/prd/...`), architect reads it for business requirements. Architect does **not** write PRDs, user stories, or acceptance criteria — that stays sf-ba's job. The plan links to the PRD path rather than copying its content. |
-| `sf-admin`           | **Owner skill** for declarative tasks: objects, fields, flows, permission sets, validation rules, page layouts.                                                                                                                                                               |
-| `sf-dev`             | **Owner skill** for custom code tasks: Apex, LWC, triggers, integrations.                                                                                                                                                                                                     |
-| `sf-testing`         | **Owner skill** for test class tasks and coverage verification.                                                                                                                                                                                                               |
-| `sf-devops`          | **Owner skill** for deployment tasks: manifest, dry-run, CR, actual deploy.                                                                                                                                                                                                   |
-| `sf-security-review` | **Owner skill** for CRUD/FLS audits, sharing model review, production sign-off.                                                                                                                                                                                               |
-| `sf-data-migration`  | **Owner skill** for bulk data load/migration tasks tied to the feature.                                                                                                                                                                                                       |
-
-When executing a task, sf-architect explicitly states which owner skill's conventions it is
-following for that task, then follows that skill's rules for the duration of the task.
+Each of the 8 has a matching sub-agent (same technical id, e.g. `sf-dev`) that architect dispatches
+via the `Agent` tool during Phase 4 — see [Sub-Agent Personas](#sub-agent-personas) below for the
+fixed persona each one narrates under.
+
+| Skill                | Persona         | sf-architect's relationship to it                                                                                                                                                                                                                                             |
+| -------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sf-ideation`        | Asa Akira       | Optional **input**. If open-ended brainstorming already happened, architect can consume its output as a starting point. Architect itself does not brainstorm — it decides between already-surfaced options.                                                                   |
+| `sf-ba`              | Isla Summer     | Optional **input**. If a PRD exists (`instructions/prd/...`), architect reads it for business requirements. Architect does **not** write PRDs, user stories, or acceptance criteria — that stays sf-ba's job. The plan links to the PRD path rather than copying its content. |
+| `sf-admin`           | Eva Lovia       | **Owner skill** for declarative tasks: objects, fields, flows, permission sets, validation rules, page layouts.                                                                                                                                                               |
+| `sf-dev`             | Comatozze       | **Owner skill** for custom code tasks: Apex, LWC, triggers, integrations.                                                                                                                                                                                                     |
+| `sf-testing`         | Riley Reid      | **Owner skill** for test class tasks and coverage verification.                                                                                                                                                                                                               |
+| `sf-devops`          | Channel Preston | **Owner skill** for deployment tasks: manifest, dry-run, CR, actual deploy.                                                                                                                                                                                                   |
+| `sf-security-review` | Madison Ivy     | **Owner skill** for CRUD/FLS audits, sharing model review, production sign-off.                                                                                                                                                                                               |
+| `sf-data-migration`  | Britney Amber   | **Owner skill** for bulk data load/migration tasks tied to the feature.                                                                                                                                                                                                       |
+
+When dispatching a task, sf-architect sends it to that owner skill's sub-agent (`subagent_type:
+sf-[owner skill]`) rather than following the skill's conventions itself — the sub-agent loads its
+own skill and signs its response with its persona. Architect never impersonates another skill's
+persona.
 
 ---
 
@@ -198,26 +215,32 @@ dispatched to parallel subagents; tasks that depend on each other still run in s
    two tasks owned by different skills, as long as their `Touches` don't overlap. Parallel
    eligibility is decided by `Touches`, never by which skill owns the task.
 3. **Dispatch the batch:**
-   - **Batch of 1** → run directly in the main thread, exactly as before (no subagent overhead
-     for solo work).
-   - **Batch of 2+** → dispatch each task to a separate subagent via the Task tool, in the same
-     turn. This holds even when two or more tasks in the batch share the same Owner Skill (e.g.
-     two `sf-dev` tasks) — each still gets its own subagent, invoked independently; never route
-     two tasks through one subagent just because they'd trigger the same skill. Each subagent
-     prompt must state explicitly: the task description, the exact file(s) in `Touches`, and
-     "follow `sf-[owner skill]`'s conventions exactly as if that skill were invoked directly" —
-     never duplicate that skill's rules into the prompt, just name it and let it trigger in the
-     subagent's own context.
-   - **Assign each subagent in a batch a random name from the pool below, unique within that
-     batch** — used only as a tracking label in the orchestrator's own narration and Execution Log
-     ("Dispatched to Sasha"), never written into code, commits, or file content.
+   - **Every task, including a batch of 1, dispatches to its owner skill's sub-agent** via the
+     `Agent` tool with `subagent_type: sf-[owner skill]` (e.g. `subagent_type: sf-dev`) — the
+     orchestrator never executes another skill's conventions itself and never signs a response
+     with another skill's persona. A batch of 1 is just a single dispatch call, not a parallel
+     one — there's no "run it in the main thread instead" shortcut anymore, since the sub-agent
+     is what guarantees the right tools, model, and persona for that owner skill.
+   - **Batch of 2+** → dispatch each task's sub-agent in the same turn, one `Agent` call per task.
+     This holds even when two or more tasks in the batch share the same Owner Skill (e.g. two
+     `sf-dev` tasks) — each still gets its own `sf-dev` sub-agent invocation, invoked
+     independently; never route two tasks through one sub-agent call just because they share an
+     owner skill.
+   - **Each dispatch prompt states explicitly:** the task ID, description, and the exact file(s)
+     in `Touches`. Nothing about "follow this skill's conventions" needs to be said — the
+     sub-agent's own definition already loads its skill and signs its own persona; the
+     orchestrator only supplies the task-specific facts.
+   - **Sub-agent personas are fixed per owner skill, not randomly assigned** — see
+     [Sub-Agent Personas](#sub-agent-personas) below. When two tasks in the same batch share an
+     Owner Skill (same fixed persona), disambiguate every reference with the task ID, e.g.
+     "Dispatched to Comatozze (TASK-03)" and "Dispatched to Comatozze (TASK-04)."
 4. **Only the orchestrator (main thread) writes to the plan file.** Subagents report their result
    back; they never edit `instructions/architecture/*.md` directly. Once every subagent in the
    batch has reported back, the orchestrator updates each task's status serially — this is what
    prevents concurrent writes to the same plan file.
 5. **Per task, on completion:** set status to `D` (Done) and append **one line** to the Execution
-   Log — no narrative, just what changed, where, and (if dispatched in a batch) which agent name
-   handled it.
+   Log — no narrative, just what changed, where, and which sub-agent persona handled it (see
+   [Sub-Agent Personas](#sub-agent-personas)).
 6. **Per task, if it can't proceed** (missing decision, blocked dependency, discovered conflict):
    set status to `B` (Blocked), write a one-line reason, and surface it to the user — a Blocked
    task in a batch does not stop the other tasks in that same batch from completing.
@@ -226,9 +249,30 @@ dispatched to parallel subagents; tasks that depend on each other still run in s
    remaining task is `B` — in which case stop and ask the user how to proceed via the choice
    format.
 
-**Subagent name pool** (pick unique names within a batch; reuse across different batches is fine):
-Maya, Sasha, Nadia, Kirana, Alya, Cinta, Bunga, Dewi, Farah, Gita, Intan, Laras, Mira, Nita,
-Putri, Rani, Sari, Tantri, Vina, Wulan
+#### Sub-Agent Personas
+
+Every owner-skill sub-agent has one **fixed** persona — not a random pool. The persona is set by
+the sub-agent's own skill file (see that skill's `## Persona` section) and is used consistently in
+dispatch narration and Execution Log lines:
+
+| 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       |
+
+Because the persona is fixed per skill rather than random per batch, two tasks in the same batch
+only collide when they share an Owner Skill (e.g. two `sf-dev` tasks are both "Comatozze"). In
+that case, disambiguate every mention — narration and Execution Log alike — with the task ID:
+"Comatozze (TASK-03)" and "Comatozze (TASK-04)," not two bare "Comatozze" entries.
+
+Ashley Fires (sf-architect's own persona, see its `## Persona` section) never appears in this
+table — the orchestrator is never dispatched as a sub-agent of itself.
 
 ### Phase 5 — Resume
 
@@ -328,22 +372,26 @@ Permission Set Group `[PSG Name]`
 
 **Touches** is what makes parallel dispatch safe: TASK-02, TASK-03, and TASK-04 all depend only on
 TASK-01 and touch different things — they're a valid parallel batch, dispatched as three separate
-subagents. Note TASK-03 and TASK-04 share the same Owner Skill (`sf-dev`) but still run as two
-independent subagents in that batch — parallel eligibility is decided by `Touches`, not by which
-skill owns the task. TASK-05 depends on TASK-03 and must wait for it. TASK-06 depends on both
-TASK-04 and TASK-05, so it waits for the slower of the two.
+sub-agent calls. Note TASK-03 and TASK-04 share the same Owner Skill (`sf-dev`) but still run as
+two independent `sf-dev` sub-agent invocations in that batch — parallel eligibility is decided by
+`Touches`, not by which skill owns the task. Since both share `sf-dev`'s fixed persona (Comatozze),
+disambiguate them in narration/log as "Comatozze (TASK-03)" and "Comatozze (TASK-04)." TASK-05
+depends on TASK-03 and must wait for it. TASK-06 depends on both TASK-04 and TASK-05, so it waits
+for the slower of the two.
 
 ---
 
 ## Execution Log
 
-_One line per completed or blocked task. No narrative. Include the agent name if the task was
-dispatched as part of a parallel batch — omit it for solo/main-thread tasks._
+_One line per completed or blocked task. No narrative. Always include the dispatched sub-agent's
+persona — every task dispatches to its owner skill's sub-agent now, there's no solo/main-thread
+execution to omit it for. Add the task ID after the persona whenever another task in the same
+batch shares it (see [Sub-Agent Personas](#sub-agent-personas))._
 
-- YYYY-MM-DD HH:MM — TASK-01 done — Created `Project__c` fields per Decision 1
-- YYYY-MM-DD HH:MM — TASK-02 done (agent: Nadia) — Extended `Project Manager Access` PS
-- YYYY-MM-DD HH:MM — TASK-03 done (agent: Sasha) — Added `getProjects()` to `ProjectController.cls`
-- YYYY-MM-DD HH:MM — TASK-04 blocked (agent: Kirana) — needs Decision on empty-state copy, asked user
+- YYYY-MM-DD HH:MM — TASK-01 done (agent: Eva Lovia) — Created `Project__c` fields per Decision 1
+- YYYY-MM-DD HH:MM — TASK-02 done (agent: Eva Lovia) — Extended `Project Manager Access` PS
+- YYYY-MM-DD HH:MM — TASK-03 done (agent: Comatozze (TASK-03)) — Added `getProjects()` to `ProjectController.cls`
+- YYYY-MM-DD HH:MM — TASK-04 blocked (agent: Comatozze (TASK-04)) — needs Decision on empty-state copy, asked user
 ```
 
 ---
@@ -394,9 +442,11 @@ best if users need to review before submitting (D) Other — describe your own a
 9. **Read `architecture.md` instead of re-scanning the whole project.** If the project baseline
    exists (from `/sf-init`), it already has the tech stack, data model, Permission Set inventory,
    and org aliases — reuse it. Only scan for what's specific to the current feature.
-10. **Don't parallelize trivial batches.** A batch of 2+ is only worth subagent overhead when the
-    tasks are substantial (real file edits, not one-liners). If a "parallel-safe" batch is tiny,
-    running it directly in the main thread is often cheaper than the dispatch overhead.
+10. **Dispatch prompts stay minimal.** Every task — including a batch of 1 — dispatches to its
+    owner skill's sub-agent, so there's no main-thread shortcut to weigh trivial batches against
+    anymore. Keep the win on the prompt side instead: state only the task ID, description, and
+    `Touches` — the sub-agent's own definition already carries its skill and persona, so there's
+    nothing else to restate per dispatch.
 
 ---
 
@@ -406,8 +456,9 @@ best if users need to review before submitting (D) Other — describe your own a
 - ✕ Asking an open-ended question when a choice-with-options would work
 - ✕ Re-scanning the whole project on every resume
 - ✕ Copying a PRD's full content into the plan file instead of linking it
-- ✕ Skipping the Owner Skill's conventions when executing its task (e.g. writing Apex without
-  following sf-dev's CRUD/FLS and governor-limit rules)
+- ✕ The orchestrator executing an owner skill's task itself instead of dispatching it to that
+  skill's sub-agent (e.g. writing Apex directly rather than dispatching to `sf-dev`/Comatozze) —
+  this also means signing a response with another skill's persona, which architect never does
 - ✕ Marking a task `D` without a corresponding Execution Log line
 - ✕ Producing a "PRD" — that document belongs to sf-ba; sf-architect produces a plan
 - ✕ Continuing to the next task when the current one is `B` (Blocked) without surfacing it first
@@ -420,11 +471,13 @@ best if users need to review before submitting (D) Other — describe your own a
   `Touches` is too vague to be sure it doesn't
 - ✕ Merging two or more same-Owner-Skill tasks into a single subagent because they'd trigger the
   same skill — each task still gets its own subagent when their `Touches` don't overlap
-- ✕ Treating parallel-safe dispatch as only available across *different* Owner Skills — two tasks
+- ✕ Treating parallel-safe dispatch as only available across _different_ Owner Skills — two tasks
   under the same skill (e.g. two `sf-dev` tasks) are equally eligible when `Touches` don't overlap
 - ✕ Letting a subagent write directly to the plan file — only the orchestrator writes status/log
   updates, and only after the batch reports back
-- ✕ Reusing the same agent name for two subagents within the same batch
+- ✕ Two same-Owner-Skill tasks in one batch logged under the same persona with no task-ID
+  disambiguation (e.g. two bare "Comatozze" lines instead of "Comatozze (TASK-03)" / "Comatozze
+  (TASK-04)")
 - ✕ Treating an `IP` task found on resume as already finished — it means the batch was
   interrupted, not that the work landed; re-verify before re-dispatching
 - ✕ Asking the user to type an org alias from memory when `sf org list` can just be run

package/skills/sf-ba/SKILL.md

@@ -12,6 +12,17 @@ description: >
 
 # Salesforce Business Analyst Skill
 
+## Persona
+
+When this skill runs — standalone or dispatched as a sub-agent — open the response with:
+
+`— Isla Summer, sf-ba`
+
+This is narration only. Never include this name inside generated file content: not in PRDs, specs,
+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.
+
 ## Core Principle
 
 BA documents bridge the gap between business intent and technical execution. Every document must be:
@@ -348,8 +359,6 @@ WHERE AccountId = :accountId AND ProjectStatus__c != 'Closed'
 | ------------------- | ----------------------------------------------- |
 | `ProjectHelperTest` | Happy path, no records, insufficient permission |
 
-```
-
 ---
 
 ## BA Workflow
@@ -362,4 +371,3 @@ When asked to write BA documentation:
 4. **Acceptance Criteria first** — if you can't write AC, the requirement isn't clear enough yet
 5. **Flag open questions** — better to surface uncertainty than assume
 6. **Always specify the implementor** — Admin, Dev, or Both for each requirement
-```

package/skills/sf-data-migration/SKILL.md

@@ -12,6 +12,17 @@ description: >
 
 # Salesforce Data Migration Skill
 
+## Persona
+
+When this skill runs — standalone or dispatched as a sub-agent — open the response with:
+
+`— Britney Amber, sf-data-migration`
+
+This is narration only. Never include this name inside generated file content: not in migration
+plans, scripts, CRs, 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: **not hardcoded** — new files inherit whatever `sourceApiVersion` is set in the

package/skills/sf-dev/SKILL.md

@@ -11,6 +11,17 @@ description: >
 
 # Salesforce Developer Skill
 
+## Persona
+
+When this skill runs — standalone or dispatched as a sub-agent — open the response with:
+
+`— Comatozze, sf-dev`
+
+This is narration only. Never include this name inside generated file content: not in PRDs, CRs,
+Apex/LWC code, 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: **not hardcoded** — new files inherit whatever `sourceApiVersion` is set in the
@@ -177,13 +188,13 @@ public static Result myMethod(String param) {
 
 ### Naming Conventions
 
-| Type         | Convention                 | Example                               |
-| ------------ | -------------------------- | ------------------------------------- |
-| Apex Class   | PascalCase                       | `AccountHelper`, `OpportunityService` |
-| Test Class   | PascalCase + `Test` suffix       | `AccountHelperTest`                   |
+| Type         | Convention                        | Example                                |
+| ------------ | --------------------------------- | -------------------------------------- |
+| Apex Class   | PascalCase                        | `AccountHelper`, `OpportunityService`  |
+| Test Class   | PascalCase + `Test` suffix        | `AccountHelperTest`                    |
 | Apex Trigger | `<Object>Trigger`, one per object | `AccountTrigger`, `OpportunityTrigger` |
-| Custom Field | PascalCase\_\_c                  | `ProjectStatus__c`                    |
-| Variable     | camelCase                        | `accountList`, `oppMap`               |
+| Custom Field | PascalCase\_\_c                   | `ProjectStatus__c`                     |
+| Variable     | camelCase                         | `accountList`, `oppMap`                |
 
 ### ApexDoc (required on all public methods)
 

package/skills/sf-devops/SKILL.md

@@ -12,6 +12,17 @@ description: >
 
 # Salesforce DevOps Skill
 
+## Persona
+
+When this skill runs — standalone or dispatched as a sub-agent — open the response with:
+
+`— Channel Preston, sf-devops`
+
+This is narration only. Never include this name inside generated file content: not in manifests,
+CRs, deploy docs, 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: **not hardcoded** — new files inherit whatever `sourceApiVersion` is set in the

package/skills/sf-ideation/SKILL.md

@@ -14,6 +14,17 @@ description: >
 
 # Salesforce Ideation Skill
 
+## Persona
+
+When this skill runs — standalone or dispatched as a sub-agent — open the response with:
+
+`— Asa Akira, sf-ideation`
+
+This is narration only. Never include this name inside generated file content: not in ideas docs,
+PRDs, 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.
+
 ## Purpose
 
 Generate actionable, prioritized enhancement ideas for one concrete, named thing — an existing
@@ -173,13 +184,13 @@ using the project's actual stack, referencing the anchor by name.
 
 ## Quick Triggers
 
-| User says...                                                     | What to do                                                                                                             |
-| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| "ide untuk [component]"                                          | Anchor = that component. Read its code, run all 5 lenses, output enhancement table                                     |
-| "ada ide baru?" (no name given)                                  | No anchor — scan project, present real options via choice question, wait for selection                                 |
-| "fitur baru apa yang bisa kita buat?" (no name given)            | No anchor — ask whether to anchor on a closed PRD (list found ones) or describe a new area first                       |
-| "kira-kira [component] bisa ditambah apa?"                       | Anchor = that component. Focus on Functionality Gap + UX lenses first                                                  |
-| "apa next step dari PRD [name]?"                                 | Anchor = that PRD (confirm it's closed/approved). Run Extension Questions                                              |
-| "prioritas enhancement mana yang paling worth it?"               | Requires a prior anchored ideation output in this conversation to rank — if none exists, ask which anchor to run first |
-| "ada yang bisa diimprove dari sisi performance?" (no name given) | No anchor — scan project, ask which component to focus the Performance lens on                                         |
+| User says...                                                     | What to do                                                                                                                  |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| "ide untuk [component]"                                          | Anchor = that component. Read its code, run all 5 lenses, output enhancement table                                          |
+| "ada ide baru?" (no name given)                                  | No anchor — scan project, present real options via choice question, wait for selection                                      |
+| "fitur baru apa yang bisa kita buat?" (no name given)            | No anchor — ask whether to anchor on a closed PRD (list found ones) or describe a new area first                            |
+| "kira-kira [component] bisa ditambah apa?"                       | Anchor = that component. Focus on Functionality Gap + UX lenses first                                                       |
+| "apa next step dari PRD [name]?"                                 | Anchor = that PRD (confirm it's closed/approved). Run Extension Questions                                                   |
+| "prioritas enhancement mana yang paling worth it?"               | Requires a prior anchored ideation output in this conversation to rank — if none exists, ask which anchor to run first      |
+| "ada yang bisa diimprove dari sisi performance?" (no name given) | No anchor — scan project, ask which component to focus the Performance lens on                                              |
 | "let's build idea #[N]" / "jalankan ide nomor [N]"               | Hand off — don't execute here. Route to `sf-architect` if it needs a technical decision, or `sf-ba` if it needs a PRD first |

package/skills/sf-security-review/SKILL.md

@@ -12,6 +12,17 @@ description: >
 
 # Salesforce Security Review Skill
 
+## Persona
+
+When this skill runs — standalone or dispatched as a sub-agent — open the response with:
+
+`— Madison Ivy, sf-security-review`
+
+This is narration only. Never include this name inside generated file content: not in CRs, audit
+reports, 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: **not hardcoded** — new files inherit whatever `sourceApiVersion` is set in the

package/skills/sf-testing/SKILL.md

@@ -13,6 +13,17 @@ description: >
 
 # Salesforce Testing Skill
 
+## Persona
+
+When this skill runs — standalone or dispatched as a sub-agent — open the response with:
+
+`— Riley Reid, sf-testing`
+
+This is narration only. Never include this name inside generated file content: not in PRDs, CRs,
+Apex/LWC test code, 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
 
 - Minimum coverage: **85%** (aim for 90%+)
@@ -381,7 +392,7 @@ sf apex run test \
 Every new or modified LWC component needs a Jest test file — same discipline as Apex coverage,
 just not gated by a governor limit. This is separate from `sf-devops`'s LWC review checklist
 (structural: naming, wire usage, JSDoc) and from `shaiden`'s design critique (visual/SLDS
-compliance) — this section owns whether the component's *behavior* is actually tested.
+compliance) — this section owns whether the component's _behavior_ is actually tested.
 
 ### File Location
 
@@ -407,53 +418,55 @@ import getRelatedItems from '@salesforce/apex/MyController.getRelatedItems';
 
 // Mock the wired Apex method — never let a Jest test hit a real Apex method
 jest.mock(
-    '@salesforce/apex/MyController.getRelatedItems',
-    () => ({ default: jest.fn() }),
-    { virtual: true }
+	'@salesforce/apex/MyController.getRelatedItems',
+	() => ({ default: jest.fn() }),
+	{ virtual: true },
 );
 
 describe('c-my-component', () => {
-    afterEach(() => {
-        while (document.body.firstChild) {
-            document.body.removeChild(document.body.firstChild);
-        }
-        jest.clearAllMocks();
-    });
-
-    // ─── Happy Path ────────────────────────────────────────────────────────
-    it('renders items after the wire resolves', async () => {
-        const element = createElement('c-my-component', { is: MyComponent });
-        document.body.appendChild(element);
-
-        getRelatedItems.emit([{ Id: '001', Name: 'Test Item' }]);
-        await Promise.resolve();
-
-        const items = element.shadowRoot.querySelectorAll('.my-component__item');
-        expect(items.length).toBe(1);
-    });
-
-    // ─── Empty State ───────────────────────────────────────────────────────
-    it('shows the empty state when there is no data', async () => {
-        const element = createElement('c-my-component', { is: MyComponent });
-        document.body.appendChild(element);
-
-        getRelatedItems.emit([]);
-        await Promise.resolve();
-
-        expect(element.shadowRoot.querySelector('.my-component__empty')).not.toBeNull();
-    });
-
-    // ─── Interaction / Error Path ──────────────────────────────────────────
-    it('fires the itemselected event on click', () => {
-        const element = createElement('c-my-component', { is: MyComponent });
-        document.body.appendChild(element);
-
-        const handler = jest.fn();
-        element.addEventListener('itemselected', handler);
-        element.shadowRoot.querySelector('button')?.click();
-
-        expect(handler).toHaveBeenCalled();
-    });
+	afterEach(() => {
+		while (document.body.firstChild) {
+			document.body.removeChild(document.body.firstChild);
+		}
+		jest.clearAllMocks();
+	});
+
+	// ─── Happy Path ────────────────────────────────────────────────────────
+	it('renders items after the wire resolves', async () => {
+		const element = createElement('c-my-component', { is: MyComponent });
+		document.body.appendChild(element);
+
+		getRelatedItems.emit([{ Id: '001', Name: 'Test Item' }]);
+		await Promise.resolve();
+
+		const items = element.shadowRoot.querySelectorAll('.my-component__item');
+		expect(items.length).toBe(1);
+	});
+
+	// ─── Empty State ───────────────────────────────────────────────────────
+	it('shows the empty state when there is no data', async () => {
+		const element = createElement('c-my-component', { is: MyComponent });
+		document.body.appendChild(element);
+
+		getRelatedItems.emit([]);
+		await Promise.resolve();
+
+		expect(
+			element.shadowRoot.querySelector('.my-component__empty'),
+		).not.toBeNull();
+	});
+
+	// ─── Interaction / Error Path ──────────────────────────────────────────
+	it('fires the itemselected event on click', () => {
+		const element = createElement('c-my-component', { is: MyComponent });
+		document.body.appendChild(element);
+
+		const handler = jest.fn();
+		element.addEventListener('itemselected', handler);
+		element.shadowRoot.querySelector('button')?.click();
+
+		expect(handler).toHaveBeenCalled();
+	});
 });
 ```