acek-skills 1.0.2 → 1.0.3

package/README.md

@@ -3,7 +3,7 @@
 # acek-skills
 
 **Installable [Claude Code](https://claude.com/claude-code) skills for Salesforce work.**
-Admin • Development • Testing • DevOps • Security Review • Data Migration • Business Analysis • Ideation
+Admin • Development • Testing • DevOps • Security Review • Data Migration • Business Analysis • Ideation • Architecture
 
 [![npm version](https://img.shields.io/npm/v/acek-skills.svg)](https://www.npmjs.com/package/acek-skills)
 [![license](https://img.shields.io/npm/l/acek-skills.svg)](./LICENSE)
@@ -15,18 +15,20 @@ Admin • Development • Testing • DevOps • Security Review • Data Migrat
 
 ## Contents
 
-- [Why this exists](#why-this-exists)
-- [Quick start](#quick-start)
-- [How the wizard works](#how-the-wizard-works)
-- [Non-interactive install](#non-interactive-install)
-- [Org alias templating](#org-alias-templating)
-- [Install targets](#install-targets)
-- [Skills reference](#skills-reference)
-- [CLI reference](#cli-reference)
-- [Project structure](#project-structure)
-- [Adding a new skill](#adding-a-new-skill)
-- [FAQ](#faq)
-- [License](#license)
+- [acek-skills](#acek-skills)
+  - [Contents](#contents)
+  - [Why this exists](#why-this-exists)
+  - [Quick start](#quick-start)
+  - [How the wizard works](#how-the-wizard-works)
+  - [Non-interactive install](#non-interactive-install)
+  - [Org alias templating](#org-alias-templating)
+  - [Install targets](#install-targets)
+  - [Skills reference](#skills-reference)
+  - [CLI reference](#cli-reference)
+  - [Project structure](#project-structure)
+  - [Adding a new skill](#adding-a-new-skill)
+  - [FAQ](#faq)
+  - [License](#license)
 
 ---
 
@@ -38,7 +40,7 @@ nobody opens. **acek-skills** packages that knowledge as installable [Claude Cod
 skills](https://docs.claude.com/en/docs/claude-code/skills): Markdown files with trigger
 conditions that Claude reads automatically and applies only when the task actually calls for them.
 
-One package, eight roles, install only what you need, into whichever tool you actually use.
+One package, nine roles, install only what you need, into whichever tool you actually use.
 
 ## Quick start
 
@@ -56,6 +58,7 @@ Running `install` with no arguments walks you through three prompts:
 ? Select the skills to install
   - Space to select, Enter to confirm, a to toggle all
   ◉ sf-admin
+  ◉ sf-architect
   ◉ sf-ba
   ◉ sf-data-migration
   ◉ sf-dev
@@ -76,10 +79,13 @@ Running `install` with no arguments walks you through three prompts:
 ```
 
 1. **Skills** — all selected by default; deselect anything you don't need.
-2. **Targets** — pick one or more. Each selected skill is installed to *every* selected target,
+2. **Targets** — pick one or more. Each selected skill is installed to _every_ selected target,
    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
+   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.
 
 ## Non-interactive install
 
@@ -106,11 +112,11 @@ alias) instead of hardcoding one. Internally these are placeholders —
 `{{PROD_ORG_ALIAS}}` / `{{DEV_ORG_ALIAS}}` — resolved at install time so the package never ships
 with a real client or org name baked in.
 
-| How you install | What fills the placeholder |
-|---|---|
-| Interactive wizard | Whatever you type at the alias prompts |
-| `install --all` / `install <name>` | `ACEK_PROD_ORG_ALIAS` / `ACEK_DEV_ORG_ALIAS` env vars, if set |
-| Left blank / not set | Literal `<PROD_ORG_ALIAS>` / `<DEV_ORG_ALIAS>` — find-and-replace later |
+| How you install                    | What fills the placeholder                                              |
+| ---------------------------------- | ----------------------------------------------------------------------- |
+| Interactive wizard                 | Whatever you type at the alias prompts                                  |
+| `install --all` / `install <name>` | `ACEK_PROD_ORG_ALIAS` / `ACEK_DEV_ORG_ALIAS` env vars, if set           |
+| Left blank / not set               | Literal `<PROD_ORG_ALIAS>` / `<DEV_ORG_ALIAS>` — find-and-replace later |
 
 ```bash
 ACEK_PROD_ORG_ALIAS=Acme_Production ACEK_DEV_ORG_ALIAS=Acme_Dev npx acek-skills install --all
@@ -120,13 +126,13 @@ The CLI prints a reminder after install if any placeholder was left unresolved.
 
 ## Install targets
 
-| Target | Destination | Trigger behavior |
-|---|---|---|
-| **Claude Code** (project) | `./.claude/skills/<skill>/SKILL.md` | Auto-triggered — Claude reads the `description` frontmatter and invokes the skill only when the task matches |
-| **Claude Code** (global) | `~/.claude/skills/<skill>/SKILL.md` | Same as above, applies across every project on your machine |
-| **Cursor** | `./.cursor/rules/<skill>.mdc` | Project rule (`alwaysApply: false`) — Cursor decides relevance from the `description` field |
-| **Windsurf** | `./.windsurf/rules/<skill>.md` | Cascade rule (`trigger: model_decision`) — same idea, Windsurf's own matching |
-| **GitHub Copilot** | `./.github/instructions/<skill>.instructions.md` | Custom instructions (`applyTo: "**"`) — applied repo-wide, no per-task trigger |
+| Target                    | Destination                                      | Trigger behavior                                                                                             |
+| ------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| **Claude Code** (project) | `./.claude/skills/<skill>/SKILL.md`              | Auto-triggered — Claude reads the `description` frontmatter and invokes the skill only when the task matches |
+| **Claude Code** (global)  | `~/.claude/skills/<skill>/SKILL.md`              | Same as above, applies across every project on your machine                                                  |
+| **Cursor**                | `./.cursor/rules/<skill>.mdc`                    | Project rule (`alwaysApply: false`) — Cursor decides relevance from the `description` field                  |
+| **Windsurf**              | `./.windsurf/rules/<skill>.md`                   | Cascade rule (`trigger: model_decision`) — same idea, Windsurf's own matching                                |
+| **GitHub Copilot**        | `./.github/instructions/<skill>.instructions.md` | Custom instructions (`applyTo: "**"`) — applied repo-wide, no per-task trigger                               |
 
 Only Claude Code has a purpose-built skill system with dynamic, description-based triggering.
 Cursor and Windsurf approximate it with their own rule-matching; Copilot's custom instructions
@@ -135,6 +141,27 @@ matching behavior matters for your workflow.
 
 ## Skills reference
 
+<details>
+<summary><strong>sf-architect</strong> — technical architecture & plan mode</summary>
+
+Salesforce's plan mode. Gates all work behind an approved Architecture Plan before any code or
+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
+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.
+
+Comes with a companion **`/sf-init`** slash command (installed automatically alongside it, Claude
+Code targets only) that bootstraps `architecture.md` at the project root — a baseline of org
+aliases, tech stack, data model, integrations, and Permission Set inventory that `sf-architect`
+reads on every plan instead of re-scanning the whole project each time. Re-running `/sf-init`
+refreshes the baseline with a diff-and-confirm flow.
+
+</details>
+
 <details>
 <summary><strong>sf-admin</strong> — declarative configuration</summary>
 
@@ -142,6 +169,7 @@ Custom objects/fields, picklists, page layouts, record types, profiles, permissi
 sharing rules, validation rules, workflow rules, flows (Screen/Record-Triggered/Schedule),
 approval processes, reports, dashboards, email templates, org setup, security model (OWD), and
 data management (import/export/data loader) — anything declarative, no code involved.
+
 </details>
 
 <details>
@@ -150,6 +178,7 @@ 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.
+
 </details>
 
 <details>
@@ -158,19 +187,22 @@ intended to hand off to an admin or developer. Triggers on "write a PRD", "docum
 Import/export strategy, Data Loader automation, upsert with External IDs, bulk SOQL exports, data
 cleansing, bulk delete/mass update, and error handling for large-volume loads between orgs or from
 external systems.
+
 </details>
 
 <details>
 <summary><strong>sf-dev</strong> — custom development</summary>
 
 Apex classes, triggers, batch jobs, test classes, SOQL, LWC (HTML/JS/CSS), Aura components, and
-integration patterns. Covers governor limits, CRUD/FLS patterns, `@AuraEnabled` conventions, LWC
-brand tokens + version badges, and REST/SOAP callout patterns.
+integration patterns. Covers governor limits, CRUD/FLS patterns (including the API 67.0+
+user-mode-by-default security model), `@AuraEnabled` conventions, and REST/SOAP callout patterns.
+
+> **LWC styling:** uses SLDS 2 global hooks directly (`var(--slds-g-*, fallback)`) as the
+> baseline/standard approach — no custom brand token block. For a full design-system workflow
+> (token system, typography scale, signature elements, cross-component consistency scoring), use
+> [`shaiden`](https://www.npmjs.com/package/shaiden) instead. Both use the same SLDS 2 hook
+> vocabulary, so they no longer conflict — `shaiden` is just more thorough.
 
-> **Note:** its LWC section uses a custom `:host` brand-token block (`--brand`, `--r-sm`, etc.)
-> plus a mandatory version badge — a different, incompatible styling convention from
-> [`shaiden`](https://www.npmjs.com/package/shaiden) (SLDS 2 global hooks only). Don't install
-> both against the same component without reconciling the two first.
 </details>
 
 <details>
@@ -179,14 +211,18 @@ brand tokens + version badges, and REST/SOAP callout patterns.
 Code review checklists, scoped `package.xml` manifests, dry-run validation, Change Requests,
 deploy documentation, and the full sandbox-to-production pipeline via SF CLI. References your
 production/sandbox [org aliases](#org-alias-templating).
+
 </details>
 
 <details>
-<summary><strong>sf-ideation</strong> — enhancement brainstorming</summary>
+<summary><strong>sf-ideation</strong> — anchored enhancement brainstorming</summary>
+
+Generates enhancement ideas for one specific, named Apex class, LWC component, or closed/approved
+PRD — never in the abstract. Requires an anchor before doing anything: if the user doesn't name a
+file, it scans the project and asks the user to pick from what actually exists (never invents
+component names). Also used proactively when reviewing a specific component to spot improvement
+opportunities.
 
-Generates enhancement ideas for existing components/features or net-new concepts — for LWC,
-Apex, flows, or the platform generally. Also used proactively when reviewing a component to spot
-improvement opportunities.
 </details>
 
 <details>
@@ -194,7 +230,9 @@ improvement 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, and audit trail questions.
+encryption, audit trail, and a dedicated PII & Data Privacy section — field classification,
+sandbox data masking, and UU PDP-aware review practices.
+
 </details>
 
 <details>
@@ -203,6 +241,7 @@ encryption, and audit trail questions.
 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.
+
 </details>
 
 Each skill's full content — including code patterns, checklists, and exact trigger keywords —
@@ -214,14 +253,22 @@ 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
+acek-skills list                 List available skills and commands
 ```
 
+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`;
+`sf-architect` reads it on every plan afterward instead of re-scanning the whole project each
+time. Re-running `/sf-init` later refreshes the baseline with a diff-and-confirm flow rather than
+silently overwriting it.
+
 ## Project structure
 
 ```
 skills/
   sf-admin/SKILL.md
+  sf-architect/SKILL.md
   sf-ba/SKILL.md
   sf-data-migration/SKILL.md
   sf-dev/SKILL.md
@@ -229,6 +276,8 @@ skills/
   sf-ideation/SKILL.md
   sf-security-review/SKILL.md
   sf-testing/SKILL.md
+commands/
+  sf-init.md         /sf-init slash command — companion to sf-architect, Claude Code only
 bin/
   cli.js            install wizard / CLI entry point (acek-skills)
 ```
@@ -236,6 +285,7 @@ bin/
 ## Adding a new skill
 
 1. Create `skills/<name>/SKILL.md` with YAML frontmatter:
+
    ```markdown
    ---
    name: <name>
@@ -245,6 +295,7 @@ bin/
 
    # Skill content — rules, checklists, code patterns
    ```
+
 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.

package/bin/cli.js

@@ -9,6 +9,7 @@ const command = args[0];
 const target = args[1]; // optional: specific skill name, or "--all"
 
 const SKILLS_SRC = path.join(__dirname, '../skills');
+const COMMANDS_SRC = path.join(__dirname, '../commands');
 
 function printBanner() {
 	console.log(`\x1b[36m
@@ -26,12 +27,14 @@ const TARGETS = {
 	'claude-project': {
 		label: 'Claude Code — project (./.claude/skills)',
 		dir: (cwd) => path.join(cwd, '.claude/skills'),
+		commandsDir: (cwd) => path.join(cwd, '.claude/commands'),
 		format: 'claude',
 		selected: true,
 	},
 	'claude-global': {
 		label: 'Claude Code — global (~/.claude/skills)',
 		dir: () => path.join(os.homedir(), '.claude/skills'),
+		commandsDir: () => path.join(os.homedir(), '.claude/commands'),
 		format: 'claude',
 		selected: false,
 	},
@@ -95,6 +98,30 @@ function listSkills() {
 		.map((e) => e.name);
 }
 
+// Slash commands are a Claude-Code-specific concept (single .md file per
+// command under .claude/commands/) — unlike skills, they have no equivalent
+// in Cursor/Windsurf/Copilot, so they only ever install to 'claude' format
+// targets.
+function listCommands() {
+	if (!fs.existsSync(COMMANDS_SRC)) return [];
+	return fs
+		.readdirSync(COMMANDS_SRC, { withFileTypes: true })
+		.filter((e) => e.isFile() && e.name.endsWith('.md'))
+		.map((e) => e.name.replace(/\.md$/, ''));
+}
+
+function installCommandToTarget(commandName, targetKey, cwd, aliases = {}) {
+	const targetDef = TARGETS[targetKey];
+	if (targetDef.format !== 'claude' || !targetDef.commandsDir) return;
+	const destDir = targetDef.commandsDir(cwd);
+	fs.mkdirSync(destDir, { recursive: true });
+	const content = applyAliases(
+		fs.readFileSync(path.join(COMMANDS_SRC, `${commandName}.md`), 'utf8'),
+		aliases,
+	);
+	fs.writeFileSync(path.join(destDir, `${commandName}.md`), content);
+}
+
 // Pulls `name`/`description` out of the SKILL.md frontmatter (YAML folded
 // scalar style: "description: >") so non-Claude formats can reuse them.
 function parseSkill(skillName) {
@@ -258,12 +285,14 @@ async function runInteractiveInstall() {
 				{
 					type: 'text',
 					name: 'prod',
-					message: 'Production org alias (e.g. Acme_Production) — leave blank to fill in later',
+					message:
+						'Production org alias (e.g. Acme_Production) — leave blank to fill in later',
 				},
 				{
 					type: 'text',
 					name: 'dev',
-					message: 'Sandbox / dev org alias (e.g. Acme_Dev) — leave blank to fill in later',
+					message:
+						'Sandbox / dev org alias (e.g. Acme_Dev) — leave blank to fill in later',
 				},
 			],
 			{ onCancel },
@@ -275,9 +304,27 @@ async function runInteractiveInstall() {
 		for (const skillName of skills) {
 			installSkillToTarget(skillName, targetKey, cwd, aliases);
 		}
-		console.log(`✅ ${skills.length} skill(s) installed to ${TARGETS[targetKey].label}`);
+		console.log(
+			`✅ ${skills.length} skill(s) installed to ${TARGETS[targetKey].label}`,
+		);
+
+		if (skills.includes('sf-architect') && TARGETS[targetKey].commandsDir) {
+			installCommandToTarget('sf-init', targetKey, cwd, aliases);
+			console.log(
+				`✅ /sf-init command installed to ${TARGETS[targetKey].label}`,
+			);
+		}
 	}
 	warnIfAliasesUnresolved(skills, aliases);
+	if (
+		skills.includes('sf-architect') &&
+		targets.some((t) => TARGETS[t].commandsDir)
+	) {
+		console.log(
+			'\n💡 Run /sf-init in your project to bootstrap architecture.md — sf-architect reads it\n' +
+				'   on every plan afterward instead of re-scanning the whole project each time.',
+		);
+	}
 	console.log('\n🎉 Done!');
 }
 
@@ -293,6 +340,21 @@ async function main() {
 			console.log(
 				`✅ All ${available.length} skill(s) installed to ${TARGETS['claude-project'].label}`,
 			);
+			if (available.includes('sf-architect')) {
+				installCommandToTarget(
+					'sf-init',
+					'claude-project',
+					process.cwd(),
+					aliases,
+				);
+				console.log(
+					`✅ /sf-init command installed to ${TARGETS['claude-project'].label}`,
+				);
+				console.log(
+					'\n💡 Run /sf-init in your project to bootstrap architecture.md — sf-architect reads it\n' +
+						'   on every plan afterward instead of re-scanning the whole project each time.',
+				);
+			}
 			warnIfAliasesUnresolved(available, aliases);
 		} else if (target) {
 			printBanner();
@@ -305,7 +367,24 @@ async function main() {
 			}
 			const aliases = aliasesFromEnv();
 			installSkillToTarget(target, 'claude-project', process.cwd(), aliases);
-			console.log(`✅ Installed skill: ${target} → ${TARGETS['claude-project'].label}`);
+			console.log(
+				`✅ Installed skill: ${target} → ${TARGETS['claude-project'].label}`,
+			);
+			if (target === 'sf-architect') {
+				installCommandToTarget(
+					'sf-init',
+					'claude-project',
+					process.cwd(),
+					aliases,
+				);
+				console.log(
+					`✅ /sf-init command installed to ${TARGETS['claude-project'].label}`,
+				);
+				console.log(
+					'\n💡 Run /sf-init in your project to bootstrap architecture.md — sf-architect reads it\n' +
+						'   on every plan afterward instead of re-scanning the whole project each time.',
+				);
+			}
 			warnIfAliasesUnresolved([target], aliases);
 		} else {
 			await runInteractiveInstall();
@@ -313,6 +392,11 @@ async function main() {
 	} else if (command === 'list') {
 		console.log('📦 Available skills:');
 		listSkills().forEach((s) => console.log(`  - ${s}`));
+		const commands = listCommands();
+		if (commands.length > 0) {
+			console.log('\n⚡ Available commands:');
+			commands.forEach((c) => console.log(`  - /${c}`));
+		}
 	} else {
 		console.log(`
 Usage:
@@ -320,7 +404,11 @@ 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
+  acek-skills list                 List available skills and commands
+
+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
+to bootstrap architecture.md; sf-architect reads it on every plan afterward.
 
 Some skills reference your Salesforce org aliases. For non-interactive installs,
 set these env vars to fill them in automatically:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "acek-skills",
-	"version": "1.0.2",
+	"version": "1.0.3",
 	"description": "Installable Claude Code skills for Salesforce development (admin, dev, BA, testing, devops, security review, data migration, ideation)",
 	"bin": {
 		"acek-skills": "bin/cli.js"