refactor: 17-agent architecture v2 with lean domain agents (#10)

* feat: add install smoke test job to CI pipeline

Test npm pack, CLI commands, and install/uninstall flows for apex, lwc,
and all profiles. Verifies correct files are installed per profile and
extended content is excluded from non-full installs.

* fix: fix smoke test and document local testing workflow

Remove dev-only commands (doctor, status, plan, list-installed) from
smoke test — they are not in npm package files field. Add local smoke
test script (scripts/ci/smoke-test.sh). Document in CLAUDE.md and
README.md.

* feat: add proactive delegation check to agent and skill validators

Agent validator now warns if description lacks "Use PROACTIVELY" — enables
Claude Code auto-delegation. Skill validator warns if SF pattern skills
lack "Use when" trigger. WHEN clause regex updated to accept
"Use PROACTIVELY when" format.

* refactor: redesign sf-architect as lean orchestrator with bookend pattern

Replace bloated 310-line architecture agent with 143-line orchestrator.
Absorbs sf-blueprint-planner (planning), sf-tdd-guide (TDD mandate),
sf-verification-runner (quality gates), sf-devops-deployment (deploy
readiness). Update install manifests. Knowledge stays in skills.
25 → 21 agents.

* refactor: replace sf-apex-reviewer and sf-trigger-architect with sf-apex-agent

New 103-line lean agent handles all Apex: classes, triggers, batch,
async, callouts, tests. Follows TDD workflow, preloads 5 constraint
skills, references pattern skills on demand. 21 → 19 agents.

* refactor: replace 10 old agents with 7 lean domain agents

Create sf-lwc-agent, sf-flow-agent, sf-admin-agent, sf-integration-agent,
sf-agentforce-agent, sf-review-agent, sf-bugfix-agent. Each ~80-110 lines
with TDD workflow. Delete 10 old agents absorbed into new ones. Update
install manifests. 19 → 17 agents.

* refactor: change 28 SF pattern skills to non-user-invocable

Pattern skills are now model-invocable only — agents read them directly
via the Read tool when needed. Users no longer need to type /skill-name.
Constraint skills and platform skills unchanged.

* refactor: rewrite sf-help for 17-agent architecture, update sf-harness-audit

sf-help now documents 11 SF domain agents + 6 platform agents, 7
constraint skills, 28 pattern skills, and 5 utility skills. Updated
agent scoring table in sf-harness-audit.

* docs: update CLAUDE.md, README, and CHANGELOG for 17-agent architecture

Update agent counts, descriptions, and tables across all documentation.
CHANGELOG documents full architecture refactor from 25 to 17 agents.

* fix: update smoke test and CI workflow for new agent filenames

Update scripts/ci/smoke-test.sh and .github/workflows/ci.yml to use
new agent names (sf-apex-agent, sf-review-agent, sf-bugfix-agent, etc).
All 45 smoke tests pass.

* refactor: expand agent coverage and fix stale references in agents and skills

- Convert all 16 multiline agent descriptions to single-line format
- Fix sf-architect and sf-review-agent descriptions for keyword and
  WHEN clause validation
- Expand sf-architect, sf-review-agent, sf-admin-agent, sf-flow-agent
  with full workflow phases and decision matrices
- Fix 12 orphaned agent references across agent files
- Add routing sequence clarity to Related sections
- Fix ~47 stale agent name references across 21 skill files
- Regenerate all .cursor/ adapters

* docs: update documentation, scripts, and tests for 17-agent architecture

- Update docs/ARCHITECTURE.md with 11 domain + 6 platform agent breakdown
- Replace old agent names in docs/authoring-guide.md and workflow-examples.md
- Update harness-audit.js checks for new agent names
- Update test fixture from sf-apex-reviewer to sf-apex-agent
- Update CLAUDE.md, README.md, and CONTRIBUTING.md

* feat: add Simple Task shortcut to sf-architect Phase 0 classification

Single-component, no-cross-object, well-defined-scope requests now get
a lite planning path (Phase 1 scan only → Phase 6 delegate) instead of
the full 7-phase cycle. Phase 1 still runs to confirm low density; if
hidden complexity is found, upgrades to full New Feature planning.

* refactor: improve agent inline guidance and fix stale skill references

- sf-apex-agent: add async decision matrix and class role suffixes
- sf-bugfix-agent: add error categorization decision tree and fix patterns
- sf-lwc-agent: add Jest test example, SLDS patterns, accessibility checklist
- eval-runner: preload constraint skills, add escalation rules
- sf-agentforce-agent: preload sf-agentforce-development skill
- sf-admin-agent, sf-review-agent, loop-operator: fix descriptions
- sf-apex-constraints: replace stale sf-write-apex reference
- sf-security: add security skills cross-reference table
- sf-help: add related skills section

* docs: update READMEs and authoring guide for 17-agent skill counts

Reorganize skills section in README by invocability: 17 user-invocable,
28 pattern (agent-consulted), 7 constraint, 3 platform. Fix stale
counts (25→17 agents, 35→17 user-invocable skills) across plugin
READMEs and authoring guide.

* docs: fix duplicate entries in README Context Skills table

Context Skills table listed 13 items but 10 were already in the Pattern
Skills table. Reduced to the 3 unique platform skills (mcp-server-patterns,
security-scan, strategic-compact) and noted that pattern skills also
activate contextually.

* fix: improve examples quality — fix platform-events bug, add API versions

- platform-events: fix WhatId type safety bug — validate Order_Id__c
  via SOQL before assigning to Id field, update test to use real Order
- lwc-component: add .js-meta.xml with API 66.0, fix Jest mock import
- flow-automation: add complete Before Save Flow XML metadata with
  decision elements, entry criteria, and ISCHANGED recursion guard
- Add API version 66.0 notes to 5 remaining examples
- Add Example Patterns section to README.md linking all 10 examples

Author: jiten-singh-shahi

.claude-plugin/README.md

@@ -29,8 +29,8 @@ npx scc install all
 
 ## What's Included
 
-- **25 agents** for Salesforce development (Apex, LWC, SOQL, Flows, Visualforce, Aura, DevOps, Security)
-- **55 skills** for domain knowledge, workflows, and patterns (35 user-invocable via `/skill-name`, 20 auto-activating)
+- **17 agents** for Salesforce development (11 domain + 6 platform)
+- **55 skills** for domain knowledge, workflows, and patterns (17 user-invocable via `/skill-name`, 38 auto-activating)
 - **29 hooks** for quality gates and automation
 - **8 schemas** for configuration validation
 

.claude-plugin/marketplace.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "salesforce-claude-code",
-  "description": "Production-ready AI agent harness for Salesforce development — 25 agents, 55 skills, and 29 hooks for Apex, LWC, SOQL, Flows, Visualforce, Aura, and DevOps",
+  "description": "Production-ready AI agent harness for Salesforce development — 17 agents, 55 skills, and 29 hooks for Apex, LWC, SOQL, Flows, Visualforce, Aura, and DevOps",
   "owner": {
     "name": "Jiten Singh",
     "email": "jitencseng@gmail.com"
@@ -13,7 +13,7 @@
     {
       "name": "salesforce-claude-code",
       "source": "./",
-      "description": "25 specialized agents, 55 domain skills, and 29 hooks for Salesforce development — Apex, LWC, SOQL, Flows, Visualforce, Aura, Agentforce, DevOps, and Security",
+      "description": "17 specialized agents, 55 domain skills, and 29 hooks for Salesforce development — Apex, LWC, SOQL, Flows, Visualforce, Aura, Agentforce, DevOps, and Security",
       "version": "0.0.0",
       "author": {
         "name": "Jiten Singh",

.claude-plugin/plugin.json

@@ -20,7 +20,25 @@
     "devops"
   ],
   "logo": "assets/logo.svg",
-  "agents": "./agents/",
+  "agents": [
+    "./agents/deep-researcher.md",
+    "./agents/doc-updater.md",
+    "./agents/eval-runner.md",
+    "./agents/learning-engine.md",
+    "./agents/loop-operator.md",
+    "./agents/refactor-cleaner.md",
+    "./agents/sf-admin-agent.md",
+    "./agents/sf-agentforce-agent.md",
+    "./agents/sf-apex-agent.md",
+    "./agents/sf-architect.md",
+    "./agents/sf-aura-reviewer.md",
+    "./agents/sf-bugfix-agent.md",
+    "./agents/sf-flow-agent.md",
+    "./agents/sf-integration-agent.md",
+    "./agents/sf-lwc-agent.md",
+    "./agents/sf-review-agent.md",
+    "./agents/sf-visualforce-reviewer.md"
+  ],
   "skills": "./skills/",
   "mcpServers": "./mcp-configs/mcp-servers.json"
 }

.cursor-plugin/README.md

@@ -26,8 +26,8 @@ ln -s /path/to/salesforce-claude-code ~/.cursor/plugins/local/salesforce-claude-
 
 ## What's Included
 
-- **25 agents** for Salesforce development (Apex, LWC, SOQL, Flows, Visualforce, Aura, DevOps, Security)
-- **55 skills** for domain knowledge, workflows, and patterns (35 user-invocable via `/skill-name`, 20 auto-activating)
+- **17 agents** for Salesforce development (11 domain + 6 platform)
+- **55 skills** for domain knowledge, workflows, and patterns (17 user-invocable via `/skill-name`, 38 auto-activating)
 - **29 hooks** for quality gates and automation
 - **MCP config** for Salesforce DX and SF CLI integration
 

.cursor-plugin/marketplace.json

@@ -11,7 +11,7 @@
     {
       "name": "salesforce-claude-code",
       "source": "./",
-      "description": "25 specialized agents, 55 domain skills, and 29 hooks for Salesforce development — Apex, LWC, SOQL, Flows, Visualforce, Aura, Agentforce, DevOps, and Security",
+      "description": "17 specialized agents, 55 domain skills, and 29 hooks for Salesforce development — Apex, LWC, SOQL, Flows, Visualforce, Aura, Agentforce, DevOps, and Security",
       "version": "0.0.0",
       "author": {
         "name": "Jiten Singh",

.cursor/agents/doc-updater.md

@@ -1,118 +1,203 @@
 ---
 name: doc-updater
 description: >-
-  Use when synchronizing Salesforce project docs — codemaps, README, ApexDoc, deployment runbooks. Do NOT use for authoring new design docs or modifying CLAUDE.md.
+  Sync Salesforce project docs with codebase — codemaps, ADRs, data dictionaries, deployment runbooks, ApexDoc. Use when updating docs after sprints or architect planning. Do NOT use for authoring design docs or CLAUDE.md.
 model: inherit
 ---
 
-You are a documentation specialist that keeps project docs synchronized with the codebase.
+You are a documentation specialist that keeps project docs synchronized with the codebase and the architect's design decisions. You extract documentation from code — you never invent it.
 
 ## When to Use
 
-- After a sprint to sync README, CONTRIBUTING, or architecture docs with code changes
-- When generating an architectural codemap (apex.md, lwc.md, integrations.md)
-- When extracting ApexDoc from Apex classes or LWC component annotations
-- When producing a deployment runbook from metadata changes
-- When auditing doc staleness (files not updated in 90+ days)
+- After sf-architect completes planning — generate ADR document and deployment runbook from the plan
+- After a sprint — sync README, codemap, and data dictionary with code changes
+- Generating architectural codemaps (apex.md, lwc.md, integrations.md, automation.md)
+- Extracting ApexDoc from Apex classes or LWC component annotations
+- Producing a deployment runbook from the architect's task plan and deployment sequence
+- Auditing doc staleness and flagging outdated documentation
+- Generating data dictionaries from object metadata
 
-Do NOT use to write greenfield design documentation, ADRs from scratch, or to modify CLAUDE.md.
+Do NOT use to write greenfield design documentation, modify CLAUDE.md, or author ADRs from scratch (sf-architect creates the ADR — you format and persist it).
 
 ## Workflow
 
-### Step 1: Scan Codebase
-
-- Read `sfdx-project.json` for project structure
-- List Apex classes, triggers, LWC components
-- Identify custom objects and fields
-- Map integrations and automation
+### Phase 1 — Scan Codebase
+
+1. Read `sfdx-project.json` for project structure and package directories
+2. Glob `*.cls`, `*.trigger`, `*.flow-meta.xml`, `lwc/*/` — build complete inventory
+3. Glob `*.object-meta.xml` — inventory objects, fields, relationships
+4. Check `docs/` directory for existing documentation
+5. If an Architecture Decision Record (ADR) was produced by sf-architect, read it for context
+
+### Phase 2 — Assess Staleness
+
+Compare documentation age against source changes:
+
+| Staleness | Condition | Action |
+|---|---|---|
+| **Current** | Doc updated within 30 days of source change | No action |
+| **Stale** | Doc not updated 30-90 days after source change | Flag for update |
+| **Critical** | Doc not updated 90+ days, or source has breaking changes | Flag as CRITICAL, update immediately |
+| **Missing** | Source file exists with no corresponding doc | Generate new doc entry |
+
+```bash
+# Find docs older than source files they document
+for cls in force-app/main/default/classes/*.cls; do
+  name=$(basename "$cls" .cls)
+  doc="docs/apex.md"
+  if [ -f "$doc" ]; then
+    src_date=$(stat -c %Y "$cls" 2>/dev/null || stat -f %m "$cls")
+    doc_date=$(stat -c %Y "$doc" 2>/dev/null || stat -f %m "$doc")
+    if [ "$src_date" -gt "$doc_date" ]; then
+      echo "STALE: $name (source newer than doc)"
+    fi
+  fi
+done
+```
 
-### Step 2: Generate or Update Docs
+### Phase 3 — Generate or Update Docs
 
-- Update project structure sections
-- Generate component inventory tables
-- Sync API documentation with `@AuraEnabled` methods
-- Mark auto-generated sections with `<!-- AUTO-GENERATED -->`
-- Preserve all user-written sections unchanged
+**3a — ADR Documentation (from sf-architect output):**
 
-### Step 3: Check Staleness
+When sf-architect produces an Architecture Decision Record, persist it:
 
-- Compare doc timestamps with source file timestamps
-- Flag docs not updated in 90+ days
-- Identify new components without documentation
+```markdown
+# ADR-[NNN]: [Title]
+**Date:** [date] | **Status:** Accepted | **Classification:** [New Feature/Enhancement]
 
-### Step 4: Deliver
+## Context
+[Requirement summary from architect Phase 2]
 
-- Report documentation coverage metrics
-- List stale files and undocumented components
-- Present diffs for user approval before writing
+## Decision
+[Design choices from architect Phase 4 — data model, automation approach, security model]
 
-## Codemap Structure
+## Consequences
+[Trade-offs, rollback risk, governor limit budget]
 
-```text
-docs/
-  INDEX.md         — Top-level project map
-  apex.md          — Apex classes, triggers, services
-  lwc.md           — LWC components and their relationships
-  integrations.md  — External integrations and APIs
-  automation.md    — Flows, triggers, scheduled jobs
+## Tasks
+[Task list from architect Phase 5 with agent assignments]
 ```
 
-## Documentation Templates
+Save to `docs/adr/ADR-[NNN]-[slug].md`. Number sequentially.
 
-### Apex Class (ApexDoc Format)
+**3b — Data Dictionary (from object metadata):**
 
-```markdown
-## AccountService
+For each custom object, extract from `*.object-meta.xml`:
 
-**Type:** Service Layer | **Sharing:** with sharing | **Test:** AccountServiceTest (92%)
+```markdown
+## Equipment__c
+**Label:** Equipment | **Sharing:** Private | **API:** v66.0
 
-| Method | Access | Parameters | Returns | Description |
-|--------|--------|-----------|---------|-------------|
-| `createAccount` | public | `AccountDTO dto` | `Account` | Creates account with validation |
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| Account__c | Master-Detail(Account) | Yes | Parent account |
+| Serial_Number__c | Text(40) | Yes | Unique serial, External ID |
+| Status__c | Picklist | Yes | Active, Inactive, Retired |
 
-**Dependencies:** AccountSelector, AccountDomain, UnitOfWork
-**Called By:** AccountTriggerHandler, AccountRestResource
+**Relationships:** Master-Detail → Account
+**Triggers:** EquipmentTrigger → EquipmentTriggerHandler
+**Flows:** Equipment_Assignment (Record-Triggered, After Save)
+**Permission Sets:** Equipment_Manager (Read/Write), Sales_User (Read)
 ```
 
-### LWC Component
+**3c — Apex Codemap:**
 
-```markdown
-## accountLookup
+For each Apex class, extract from source:
+
+| Field | Source |
+|---|---|
+| Class name | File name |
+| Type | Service / Controller / Selector / Domain / Batch / Queueable / Trigger Handler / Test |
+| Sharing | `with sharing` / `without sharing` / `inherited sharing` |
+| Public methods | `public` or `global` method signatures |
+| Dependencies | Classes referenced in imports / constructor / method calls |
+| Test class | Matching `*Test.cls` |
+| Coverage | From last test run if available |
 
-**Type:** Screen Component | **Targets:** Record Page, Flow Screen
+**3d — LWC Codemap:**
 
-| Property | Type | Access | Description |
-|----------|------|--------|-------------|
-| `recordId` | String | @api | Current record context |
+For each LWC component, extract:
 
-**Wire Adapters:** getRecord (Account.Name, Account.Industry)
-**Apex Controllers:** AccountSearchController.search
+| Field | Source |
+|---|---|
+| Component name | Folder name |
+| `@api` properties | From JS controller |
+| Wire adapters | `@wire` decorator targets |
+| Apex controllers | Imported Apex methods |
+| Events fired | `CustomEvent` dispatches |
+| Targets | From `*.js-meta.xml` (Record Page, App Page, Flow Screen) |
+
+**3e — Automation Map:**
+
+For each object, list all automations in execution order:
+
+```markdown
+## Account — Automation Map
+1. Before-save flows: [list]
+2. Before triggers: AccountTrigger → AccountTriggerHandler
+3. Validation rules: [list]
+4. After triggers: AccountTrigger → AccountTriggerHandler
+5. After-save flows: [list]
+6. Scheduled paths: [list]
 ```
 
-### Custom Object Data Dictionary
+**3f — Deployment Runbook (from architect's deployment sequence):**
 
 ```markdown
-## Work_Order__c
+# Deployment Runbook: [Feature Name]
+**Date:** [date] | **ADR:** ADR-[NNN]
+
+## Pre-Deploy
+- [ ] Retrieve metadata snapshot: `sf project retrieve start`
+- [ ] All tests passing in target org
+
+## Deploy Sequence
+| Step | Metadata | Command | Verify |
+|------|----------|---------|--------|
+| 1 | Equipment__c + fields | `sf project deploy start -d force-app/.../objects/Equipment__c` | Object visible in Setup |
+| 2 | Permission Sets | `sf project deploy start -d force-app/.../permissionsets/` | FLS verified |
+| 3 | Apex + Triggers | `sf project deploy start -d force-app/.../classes/ -d .../triggers/` | Tests pass |
+
+## Post-Deploy
+- [ ] Smoke test: [specific scenarios]
+- [ ] Verify permission sets assigned to users
+
+## Rollback
+- [ ] [Specific rollback steps from ADR]
+```
 
-**Label:** Work Order | **Sharing:** Private
+### Phase 4 — Deliver
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| Account__c | Master-Detail(Account) | Yes | Parent account |
-| Status__c | Picklist | Yes | Open, In Progress, Completed, Cancelled |
+1. Present staleness report with CURRENT/STALE/CRITICAL/MISSING counts
+2. Show diffs for updated docs — **wait for user approval before writing**
+3. Write approved updates with `<!-- AUTO-GENERATED [date] -->` markers
+4. Preserve all user-written sections untouched
+
+## Codemap Structure
 
-**Triggers:** WorkOrderTrigger → WorkOrderHandler
-**Flows:** Work_Order_Assignment (Record-Triggered)
+```text
+docs/
+  INDEX.md           — Top-level project map with links
+  apex.md            — Apex classes, triggers, services
+  lwc.md             — LWC components and relationships
+  integrations.md    — External integrations and APIs
+  automation.md      — Flows, triggers, scheduled jobs per object
+  data-dictionary.md — All objects, fields, relationships
+  adr/               — Architecture Decision Records
+    ADR-001-equipment-tracking.md
+  runbooks/          — Deployment runbooks
+    deploy-equipment-feature.md
 ```
 
 ## Rules
 
-- Never invent documentation — extract from code only
+- Never invent documentation — extract from code and architect output only
 - Preserve user-written sections (only update `<!-- AUTO-GENERATED -->` blocks)
-- Keep tables sorted alphabetically
+- Keep tables sorted alphabetically within each section
 - Include file paths for easy navigation
 - Use relative links between doc files
-- Date-stamp auto-generated sections
+- Date-stamp every auto-generated section
+- ADRs are numbered sequentially and never deleted (only superseded)
 
 ## Escalation
 
@@ -122,11 +207,13 @@ Stop and ask the human before:
 - Deleting entire documentation sections
 - Modifying CLAUDE.md or any harness configuration file
 - Writing new files to locations outside the `docs/` directory without explicit approval
+- Creating the first ADR (confirm numbering convention with user)
 
 Never proceed past an escalation point autonomously.
 
 ## Related
 
-- **Agent**: `sf-architect` — architecture decisions that should be documented as ADRs
-- **Agent**: `sf-devops-deployment` — deployment runbooks and change management
-- **Agent**: `sf-code-reviewer` — identifies undocumented code patterns during reviews
+- **Agent**: `sf-architect` — produces ADRs and deployment sequences that doc-updater persists
+- **Agent**: `sf-review-agent` — identifies undocumented code patterns during reviews
+- **Agent**: `sf-admin-agent` — creates the schema metadata that feeds data dictionaries
+- **Skill**: `sf-deployment-constraints` — deployment order rules for runbook generation