Add AgentScript doctor and common-pitfall guidance

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "agentforce-adlc",
       "source": "./",
-      "description": "Author, discover, scaffold, deploy, test, secure, and optimize Agentforce .agent files",
+      "description": "Author, doctor, deploy, test, secure, and optimize Agentforce .agent files",
       "version": "0.11.0"
     }
   ]

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agentforce-adlc",
   "version": "0.11.0",
-  "description": "Agentforce Agent Development Life Cycle — author, discover, scaffold, deploy, test, secure, and optimize .agent files",
+  "description": "Agentforce Agent Development Life Cycle — author, doctor, deploy, test, secure, and optimize .agent files",
   "author": {
     "name": "SalesforceAIResearch"
   },

CHANGELOG.md

@@ -32,6 +32,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   without naming AgentScript instruction surfaces.
 
 ### Added
+- **`/agentforce-doctor` for actionable AgentScript health checks.** The new
+  skill reconstructs explicit and inferred use cases, audits the complete
+  instruction/action/state/runtime path, applies minimal evidence-backed
+  repairs, and compares the unchanged baseline with the candidate using the
+  same cases and evaluator. Its diagnostic catalog covers instruction
+  overrides, prompt indentation that impersonates executable scope,
+  reachability, action contracts, raw outputs, stale state, lifecycle resets,
+  turn-ending setters, transitions, authority, side-effect ownership,
+  architecture, capability honesty, and evaluation integrity. It does not
+  deploy, publish, activate, or treat simulated actions as proof of a live
+  effect. The installer, routing registry, agent manifests, and user
+  documentation now expose the fourth skill. ([#46](https://github.com/SalesforceAIResearch/agentforce-adlc/pull/46))
+- **Common AgentScript control-flow pitfalls are now explicit authoring
+  guidance.** The core skill and references distinguish structural
+  indentation from model-facing indentation inside `|` text, explain that
+  step labels and words such as `Call`, `Set`, and `STOP` do not create runtime
+  sequencing, and require independent action gating and evidence-backed state.
+  ([#46](https://github.com/SalesforceAIResearch/agentforce-adlc/pull/46))
 - "Manage MCP Servers" task domain in `/agentforce-generate` for registering and managing MCP (Model Context Protocol) servers via the Salesforce CLI `sf agent mcp` commands. Includes:
   - Interactive tool whitelisting with full metadata review (input/output schemas, annotations)
   - Server lifecycle management (create, list, get, update, delete)

CLAUDE.md

@@ -12,9 +12,9 @@ agentforce-adlc/
 ├── agents/           # Claude Code agent definitions (.md)
 ├── skills/           # Claude Code skills (SKILL.md-driven)
 │   ├── agentforce-generate/   # Author + discover + scaffold + deploy + optimize + safety + feedback + MCP server management
+│   ├── agentforce-doctor/     # Use-case audit + minimal repair + regression evaluation
 │   ├── agentforce-test/        # Preview testing + batch testing + action execution
-│   ├── agentforce-observe/     # STDM trace analysis + fix loop
-│   └── agentforce-secure/      # OWASP LLM Top 10 security assessment
+│   └── agentforce-observe/     # STDM trace analysis + fix loop
 ├── hooks/            # Plugin hook definitions
 │   └── hooks.json        # PreToolUse/PostToolUse hook config
 ├── shared/           # Cross-skill shared code
@@ -33,6 +33,7 @@ agentforce-adlc/
 | Skill | Trigger | Description |
 |---|---|---|
 | `/agentforce-generate` | "build agent", "create agent", "write .agent", "new agent", "agentforce agent", "service agent", "employee agent", "voice agent", "phone agent", "build me an agent", "FAQ agent", "discover", "check org", "scaffold", "generate stubs", "deploy", "publish", "activate", "safety review", "security check", "feedback", "optimize agent", "improve agent", "clean up agent", "refactor agent", "register MCP", "create MCP server", "whitelist tools", "approve tools", "list MCP servers", "update MCP server", "delete MCP server", "fetch MCP assets", "MCP authentication" | **Primary skill** — author .agent files (text + voice), discover targets, scaffold stubs, deploy, optimize, safety review, feedback, manage MCP servers |
+| `/agentforce-doctor` | "doctor agent", "agent health check", "audit agent", "audit .agent", "common pitfalls", "what is wrong with this agent", "repair agent", "diagnose and fix agent", "evaluate fixes" | Reconstruct intended use cases, report actionable defects, make minimal repairs, and compare the same cases before and after |
 | `/agentforce-test` | "test agent", "preview", "smoke test", "batch test", "run action", "execute", "test action", "security test", "OWASP", "red team", "pen test", "security scan", "security grade", "vulnerability assessment", "prompt injection test" | Agent preview + batch testing + individual action execution + OWASP LLM Top 10 security testing (Mode C) |
 | `/agentforce-observe` | "optimize", "analyze sessions", "STDM", "session traces" | Session trace analysis + improvement loop (trace/data-driven optimization; static `.agent` file optimization → `/agentforce-generate`) |
 
@@ -65,6 +66,12 @@ agentforce-adlc/
 
 When a user wants to **create, build, or write an Agentforce agent**, ALWAYS use `/agentforce-generate`. This skill generates `.agent` files directly using the Agent Script DSL — the correct approach for this project. This includes phrases like "build me a service agent", "create an employee agent", "build a FAQ bot", or any request involving Agentforce agents.
 
+When a user wants a **comprehensive audit, health check, common-pitfall scan,
+repair loop, or before/after evaluation** of an existing AgentScript agent, use
+`/agentforce-doctor`. A single already-specified edit remains an
+`/agentforce-generate` task; production session or trace diagnosis remains an
+`/agentforce-observe` task.
+
 **Detection heuristic:** If the project has `sfdx-project.json`, `aiAuthoringBundles/`, or `.agent` files, treat ALL agent-related requests as ADLC requests — even if the user doesn't explicitly say "Agentforce."
 
 Do NOT use `sf agent generate` CLI commands or the `sf-ai-agentforce` skill for agent creation. Those tools work with Setup UI metadata XML, not Agent Script. The `/agentforce-generate` skill is the primary tool for all agent authoring in this project.
@@ -131,7 +138,11 @@ claude plugin marketplace add /path/to/agentforce-adlc
 claude plugin install agentforce-adlc@agentforce-adlc
 ```
 
-When installed as a plugin, skills are namespaced: `/agentforce-adlc:agentforce-generate`, `/agentforce-adlc:agentforce-test`, `/agentforce-adlc:agentforce-observe`.
+When installed as a plugin, skills are namespaced:
+`/agentforce-adlc:agentforce-generate`,
+`/agentforce-adlc:agentforce-doctor`,
+`/agentforce-adlc:agentforce-test`, and
+`/agentforce-adlc:agentforce-observe`.
 
 ### File-copy install (Cursor or legacy)
 

README.md

@@ -1,7 +1,7 @@
 # agentforce-adlc
 
-**Agent Development Life Cycle** — Build, deploy, test, and optimize Agentforce agents
-using Claude Code skills and Agent Script DSL.
+**Agent Development Life Cycle** — Build, audit, repair, deploy, test, and
+optimize Agentforce agents using Claude Code skills and Agent Script DSL.
 
 ## What is this?
 
@@ -10,11 +10,13 @@ using Claude Code skills and Agent Script DSL.
 ### Key differentiators
 
 - **Direct authoring** — Claude generates `.agent` files natively, not via markdown-to-agent conversion
-- **Full lifecycle** — Author, discover, scaffold, deploy, test, and optimize in one toolchain
+- **Full lifecycle** — Author, audit, repair, discover, scaffold, deploy, test,
+  and optimize in one toolchain
 - **Safety built-in** — LLM-driven safety review across the entire lifecycle (authoring, deploy, test, optimize)
 - **Deterministic agents** — Agent Script DSL enforces code-level guarantees (conditionals, guards, transitions)
 - **Session trace analysis** — Extract STDM data from Data Cloud for data-driven optimization
-- **4 consolidated skills** — Development, testing, observability, and security, following the [agentskills.io](https://agentskills.io) standard
+- **4 focused skills** — Development, doctoring, testing, and observability,
+  following the [agentskills.io](https://agentskills.io) standard
 
 ## Pipeline
 
@@ -25,6 +27,12 @@ User prompt
 +--------------------------+
 | Safety Review (Phase 0)  |<-- LLM-driven, 7 categories
 | .agent file generated    |
++--------+-----------------+
+         |  /agentforce-doctor
+         v
++--------------------------+
+| Use cases -> Audit       |<-- Evidence-backed findings
+| -> Repair -> Re-evaluate |
 +--------+-----------------+
          |  /agentforce-generate (discover)
          v
@@ -51,7 +59,10 @@ User prompt
 +--------------------------+
 ```
 
-Each skill can be invoked independently. Run `/agentforce-test` on an existing agent without touching the development steps. Run `/agentforce-observe` on production session data without redeploying.
+Each skill can be invoked independently. Run `/agentforce-doctor` to audit,
+repair, and regression-check an existing agent without publishing it. Run
+`/agentforce-test` on an existing agent without touching the development steps.
+Run `/agentforce-observe` on production session data without redeploying.
 
 ## Installation
 
@@ -69,7 +80,11 @@ claude plugin marketplace add SalesforceAIResearch/agentforce-adlc
 claude plugin install agentforce-adlc@agentforce-adlc
 ```
 
-When installed as a plugin, skills are namespaced: `/agentforce-adlc:agentforce-generate`, `/agentforce-adlc:agentforce-test`, `/agentforce-adlc:agentforce-observe`.
+When installed as a plugin, skills are namespaced:
+`/agentforce-adlc:agentforce-generate`,
+`/agentforce-adlc:agentforce-doctor`,
+`/agentforce-adlc:agentforce-test`, and
+`/agentforce-adlc:agentforce-observe`.
 
 ### File-copy install (Cursor or legacy Claude Code)
 
@@ -138,7 +153,20 @@ The skill will:
 
 Each phase can also be triggered individually (e.g., "just discover targets for OrderService.agent").
 
-### 2. Test the agent (`/agentforce-test`)
+### 2. Doctor an existing agent (`/agentforce-doctor`)
+
+```
+/agentforce-doctor
+
+Audit OrderService.agent for common AgentScript pitfalls. Recover its intended
+use cases, make minimal fixes, and compare the same cases before and after.
+```
+
+Builds a use-case matrix, reports only evidence-backed findings, applies the
+smallest repairs, and checks the candidate against the unchanged baseline. It
+does not deploy, publish, activate, or run live consequential actions.
+
+### 3. Test the agent (`/agentforce-test`)
 
 ```
 /agentforce-test
@@ -151,7 +179,7 @@ Smoke test OrderService against my-org with these utterances:
 
 Runs preview sessions, analyzes traces, and reports topic routing accuracy and action success rates. Also supports batch testing via Testing Center and individual action execution.
 
-### 3. Optimize from production data (`/agentforce-observe`)
+### 4. Optimize from production data (`/agentforce-observe`)
 
 ```
 /agentforce-observe
@@ -164,11 +192,12 @@ Extracts STDM session traces from Data Cloud, identifies patterns (wrong topic,
 
 ## Skills reference
 
-### 4 consolidated skills (v0.2.0+)
+### 4 focused skills
 
 | Skill | Description | Covers |
 |-------|-------------|--------|
 | `/agentforce-generate` | Build, review, discover, scaffold, deploy, and ensure safety of Agentforce agents | Author, discover, scaffold, deploy, safety review, feedback |
+| `/agentforce-doctor` | Audit and minimally repair an existing AgentScript agent against its intended use cases | Static diagnosis, common pitfalls, repair, baseline/candidate evaluation |
 | `/agentforce-test` | Test Agentforce agents via preview, batch testing, action execution, and OWASP LLM Top 10 security testing (Mode C — cases authored from the agent's own script and business domain) | Preview, batch test, action execution, security suite + A–F grade |
 | `/agentforce-observe` | Analyze session traces from Data Cloud, reproduce issues, and improve the .agent file | STDM analysis, reproduce, fix loop |
 
@@ -251,8 +280,9 @@ agentforce-adlc/
 │   ├── adlc-author.md         # Agent Script authoring specialist
 │   ├── adlc-engineer.md       # Platform engineer (discover/scaffold/deploy)
 │   └── adlc-qa.md             # Testing and optimization specialist
-├── skills/              # Claude Code skills (3 consolidated, agentskills.io standard)
+├── skills/              # Claude Code skills (agentskills.io standard)
 │   ├── agentforce-generate/   # Author + discover + scaffold + deploy + safety + feedback
+│   ├── agentforce-doctor/     # Audit + repair + baseline/candidate evaluation
 │   ├── agentforce-test/       # Preview + batch testing + action execution + OWASP security testing
 │   └── agentforce-observe/    # STDM trace analysis + fix loop
 ├── hooks/               # Plugin hook definitions

agents/adlc-orchestrator.md

@@ -2,7 +2,7 @@
 name: adlc-orchestrator
 description: Plan-mode orchestrator for the Agent Development Life Cycle
 tools: Read, Grep, Glob, Bash, Task(adlc-author, adlc-engineer, adlc-qa)
-skills: agentforce-generate, agentforce-test, agentforce-observe
+skills: agentforce-generate, agentforce-doctor, agentforce-test, agentforce-observe
 ---
 
 # ADLC Orchestrator Agent
@@ -26,28 +26,34 @@ You gather requirements, create execution plans, and delegate implementation to
 - Author creates .agent file from requirements
 - Validate Agent Script syntax and structure
 
-### 3. Discovery (Delegate to adlc-engineer)
+### 3. Agent Doctor (Delegate to adlc-qa for existing or substantially changed agents)
+- Use `/agentforce-doctor` to reconstruct intended use cases
+- Audit syntax, instructions, routing, actions, state, and lifecycle behavior
+- Apply minimal evidence-backed repairs
+- Compare the same use cases before and after
+
+### 4. Discovery (Delegate to adlc-engineer)
 - Engineer discovers missing Flow/Apex targets
 - Identifies required metadata components
 - Generates scaffolding plan
 
-### 4. Scaffolding (Delegate to adlc-engineer)
+### 5. Scaffolding (Delegate to adlc-engineer)
 - Engineer creates Flow/Apex stubs
 - Generates supporting metadata
 - Prepares deployment bundle
 
-### 5. Deployment (Delegate to adlc-engineer)
+### 6. Deployment (Delegate to adlc-engineer)
 - Engineer deploys metadata to target org
 - Publishes agent authoring bundle
 - Activates agent
 
-### 6. Testing & Optimization (Delegate to adlc-qa)
+### 7. Testing & Optimization (Delegate to adlc-qa)
 - QA runs smoke tests via preview
 - Analyzes session traces
 - Identifies and fixes issues
 - Optimizes agent performance
 
-### 7. Security Assessment (Delegate to adlc-qa)
+### 8. Security Assessment (Delegate to adlc-qa)
 - Uses `/agentforce-test` **Mode C** (OWASP LLM Top 10) — security testing is part of the test flow, not a separate skill
 - **Confirm with the user before generating security test cases** (the coding agent must ask first)
 - **Mode C1** — generate a deployable Testing Center security suite for persistent regression coverage
@@ -80,6 +86,9 @@ Task(adlc-engineer, "Deploy and publish agent: [agent_name]")
 
 # To QA for testing:
 Task(adlc-qa, "Test agent and optimize: [agent_name]")
+
+# To QA for a comprehensive static audit and repair:
+Task(adlc-qa, "Use agentforce-doctor on: [agent_name]")
 ```
 
 ## Success Criteria
@@ -104,4 +113,4 @@ Task(adlc-qa, "Test agent and optimize: [agent_name]")
 - Provide clear phase status updates
 - Summarize specialist agent outputs
 - Highlight any blocking issues
-- Confirm before moving to next phase
+- Confirm before moving to next phase

agents/adlc-qa.md

@@ -2,7 +2,7 @@
 name: adlc-qa
 description: Tests Agentforce agents and optimizes based on session trace analysis
 tools: Read, Edit, Write, Bash, Grep, Glob
-skills: agentforce-test, agentforce-observe
+skills: agentforce-doctor, agentforce-test, agentforce-observe
 ---
 
 # ADLC QA Agent
@@ -12,6 +12,7 @@ You are the **ADLC QA Agent**, responsible for testing Agentforce agents and opt
 ## Your Expertise
 
 ### Testing Capabilities
+- Use-case-driven static audit and repair with `/agentforce-doctor`
 - Smoke testing via sf agent preview
 - Batch testing with test suites
 - Session trace analysis
@@ -242,4 +243,4 @@ Use `/agentforce-test` **Mode C** (OWASP LLM Top 10 security testing) — it is
 3. Issues identified and fixed
 4. Performance metrics
 5. Optimization recommendations
-6. Security assessment grade and findings
+6. Security assessment grade and findings

shared/hooks/scripts/session-init.py

@@ -105,8 +105,10 @@ def detect_adlc_project() -> tuple[bool, str]:
     if indicators:
         hint = (
             f"ADLC project detected ({', '.join(indicators)}). "
-            "Use /adlc-author to build agents, /adlc-test to test, "
-            "/adlc-deploy to deploy. All agent requests should use ADLC skills."
+            "Use /agentforce-generate to build or change agents, "
+            "/agentforce-doctor to audit and repair them, /agentforce-test to "
+            "test, and /agentforce-generate to deploy. All agent requests "
+            "should use ADLC skills."
         )
         return True, hint
     return False, ""

shared/hooks/skills-registry.json

@@ -1,12 +1,18 @@
 {
-  "version": "0.5.0",
+  "version": "0.6.0",
   "skills": {
     "agentforce-generate": {
       "path": "skills/agentforce-generate",
       "triggers": ["build agent", "create agent", "write .agent", "author agent", "discover", "check org", "what targets exist", "find targets", "scaffold", "generate stubs", "create flow", "create apex", "deploy", "publish", "activate", "safety review", "security check", "is this agent safe", "feedback", "submit feedback"],
       "description": "Build, review, discover, scaffold, deploy, and ensure safety of Agentforce agents",
       "aliases": ["developing-agentforce", "adlc-author", "adlc-discover", "adlc-scaffold", "adlc-deploy", "adlc-safety", "adlc-feedback", "agentforce-development"]
     },
+    "agentforce-doctor": {
+      "path": "skills/agentforce-doctor",
+      "triggers": ["doctor agent", "agent health check", "audit agent", "audit .agent", "common pitfalls", "what is wrong with this agent", "repair agent", "diagnose and fix agent", "evaluate fixes"],
+      "description": "Audit, minimally repair, and regression-evaluate an existing AgentScript agent",
+      "aliases": ["adlc-doctor", "agentforce-health-check"]
+    },
     "agentforce-test": {
       "path": "skills/agentforce-test",
       "triggers": ["test agent", "preview", "smoke test", "batch test", "run action", "execute", "test action", "invoke", "security test", "OWASP", "red team", "pen test", "security scan", "security grade", "vulnerability assessment", "prompt injection test", "security posture", "harden agent", "security assessment"],