CLAUDE.md

1# Agentforce ADLC — Agent Development Life Cycle
2 
3Generate Agentforce Agent Script `.agent` files **directly** via Claude Code skills. No intermediate markdown conversion step.
4 
5## Project Structure
6 
7```
8agentforce-adlc/
9├── .claude-plugin/   # Claude Code plugin manifest
10│   ├── plugin.json       # Plugin definition (name: "agentforce-adlc")
11│   └── marketplace.json  # Self-hosted marketplace
12├── agents/           # Claude Code agent definitions (.md)
13├── skills/           # Claude Code skills (SKILL.md-driven)
14│   ├── agentforce-generate/   # Author + discover + scaffold + deploy + optimize + safety + feedback + MCP server management
15│   ├── agentforce-test/        # Preview testing + batch testing + action execution
16│   ├── agentforce-observe/     # STDM trace analysis + fix loop
17│   └── agentforce-secure/      # OWASP LLM Top 10 security assessment
18├── hooks/            # Plugin hook definitions
19│   └── hooks.json        # PreToolUse/PostToolUse hook config
20├── shared/           # Cross-skill shared code
21│   ├── hooks/scripts/    # Hook scripts (guardrails.py, agent-validator.py)
22│   └── sf-cli/           # SF CLI subprocess wrapper
23├── scripts/          # Python helper scripts (standalone)
24│   └── generators/   # Flow XML, Apex, PermSet generators
25├── tools/            # Installer (file-copy for Cursor)
26├── settings.json     # Plugin default settings (agent)
27├── tests/            # pytest test suite
28└── force-app/        # Example Salesforce DX output
29```
30 
31## Skills
32 
33| Skill | Trigger | Description |
34|---|---|---|
35| `/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 |
36| `/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) |
37| `/agentforce-observe` | "optimize", "analyze sessions", "STDM", "session traces" | Session trace analysis + improvement loop (trace/data-driven optimization; static `.agent` file optimization → `/agentforce-generate`) |
38 
39### Backward Compatibility Aliases
40 
41| Old Command | New Command |
42|---|---|
43| `/developing-agentforce` | `/agentforce-generate` |
44| `/testing-agentforce` | `/agentforce-test` |
45| `/observing-agentforce` | `/agentforce-observe` |
46| `/securing-agentforce` | `/agentforce-test` (Mode C) |
47| `/agentforce-secure` | `/agentforce-test` (Mode C) |
48| `/adlc-author` | `/agentforce-generate` |
49| `/adlc-discover` | `/agentforce-generate` (Section 16) |
50| `/adlc-scaffold` | `/agentforce-generate` (Section 17) |
51| `/adlc-deploy` | `/agentforce-generate` (Section 18) |
52| `/adlc-safety` | `/agentforce-generate` (Section 15) |
53| `/adlc-feedback` | `/agentforce-generate` (Section 19) |
54| `/adlc-test` | `/agentforce-test` |
55| `/adlc-run` | `/agentforce-test` (Action Execution section) |
56| `/adlc-optimize` | `/agentforce-observe` |
57| `/agentforce-development` | `/agentforce-generate` |
58| `/agentforce-testing` | `/agentforce-test` |
59| `/agentforce-observability` | `/agentforce-observe` |
60| `/adlc-security` | `/agentforce-test` (Mode C) |
61| `/agentforce-security` | `/agentforce-test` (Mode C) |
62| `/owasp-scan` | `/agentforce-test` (Mode C) |
63 
64## Important: Agent Creation Routing
65 
66When 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.
67 
68**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."
69 
70Do 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.
71 
72## Key Conventions
73 
74- **Indentation**: Generate with 4 spaces per level. Do not mix structural tabs and spaces; tabs are non-portable across AgentScript implementations.
75- **Booleans**: `True` / `False` (capitalized — Python-style)
76- **Variables**: `mutable` (read-write) or `linked` (bound to external source)
77- **Actions**: Two-level system — `definitions` (in topic) and `invocations` (in reasoning)
78- **Naming**: `developer_name` must match the folder name under `aiAuthoringBundles/`
79 
80## Running Commands
81 
82```bash
83# Discover missing targets
84python3 scripts/discover.py --agent-file path/to/Agent.agent -o OrgAlias
85 
86# Scaffold stubs for missing targets
87python3 scripts/scaffold.py --agent-file path/to/Agent.agent -o OrgAlias --output-dir force-app/main/default
88 
89# Describe SObject fields (for smart scaffold)
90python3 scripts/org_describe.py --sobject Account -o OrgAlias
91```
92 
93## Development
94 
95```bash
96# Install Python dev dependencies
97pip install -e ".[dev]"
98 
99# Run the default test suite
100pytest tests/ -v
101 
102# Validate shipped assets with the supported public AgentScript SDK
103npx --yes --package=@sf-agentscript/agentforce@2.9.27 -- \
104  node tests/validate_agent_assets.mjs \
105  skills/agentforce-generate/assets
106 
107# If the package is unavailable or stale, build the pinned source and validate
108node tests/validate_agent_assets_from_source.mjs \
109  skills/agentforce-generate/assets
110```
111 
112The SDK-backed validator rejects versions older than the minimum declared in
113`tests/agentscript-toolchain.json`. It uses the public
114`@sf-agentscript/agentforce` package without adding it to the repository or the
115installed skills. When that package is unavailable or stale, use the source
116command to clone and build the pinned
117[`salesforce/agentscript`](https://github.com/salesforce/agentscript) revision.
118Update the pin and declared minimum together as AgentScript advances. CI uses
119the pin for pull requests and checks `main` separately on a schedule.
120 
121## Installation
122 
123### As a Claude Code plugin (recommended)
124 
125```bash
126# Load directly from the repo (development)
127claude --plugin-dir /path/to/agentforce-adlc
128 
129# Or install via marketplace
130claude plugin marketplace add /path/to/agentforce-adlc
131claude plugin install agentforce-adlc@agentforce-adlc
132```
133 
134When installed as a plugin, skills are namespaced: `/agentforce-adlc:agentforce-generate`, `/agentforce-adlc:agentforce-test`, `/agentforce-adlc:agentforce-observe`.
135 
136### File-copy install (Cursor or legacy)
137 
138```bash
139# Install skills, agents, and hooks to ~/.claude/ or ~/.cursor/
140python3 tools/install.py
141```
142 
143## Versioning & Changelog
144 
145This plugin follows [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`) and records changes in [`CHANGELOG.md`](CHANGELOG.md) using the [Keep a Changelog](https://keepachangelog.com/) format.
146 
147### Version source of truth
148 
149The version lives in **two** files and they must stay in sync:
150 
151- `.claude-plugin/plugin.json` — `version`
152- `.claude-plugin/marketplace.json` — `plugins[0].version`
153 
154### When to bump
155 
156| Change                                                            | Bump                   |
157| ----------------------------------------------------------------- | ---------------------- |
158| Breaking change to plugin slug, skill namespace, or hook contract | MAJOR (pre-1.0: MINOR) |
159| New skill, agent, hook, or user-visible capability                | MINOR                  |
160| Bug fix, doc-only change, internal refactor                       | PATCH                  |
161 
162Pre-1.0 convention: treat breaking changes as MINOR bumps (e.g., `0.5.0` → `0.6.0` for the slug rename).
163 
164### Changelog workflow
165 
1661. **Every user-visible PR** adds an entry under `## [Unreleased]` in `CHANGELOG.md` using the Keep a Changelog sections: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`. Include a PR link.
1672. **When cutting a release**:
168   - Rename `## [Unreleased]` to `## [X.Y.Z] — YYYY-MM-DD` and start a fresh empty `## [Unreleased]` block above it.
169   - Bump `version` in both `plugin.json` and `marketplace.json`.
170   - Update the link references at the bottom of `CHANGELOG.md`.
171   - Tag the release commit: `git tag vX.Y.Z && git push --tags`.
1723. **Breaking changes** get a `### Migration` subsection with the exact commands users must run.
173 
174## Safety & Guardrails
175 
176ADLC enforces safety across the full lifecycle via two layers:
177 
1781. **LLM-driven safety** (Section 15 of `/agentforce-generate`) — 7-category review (Identity, User Safety, Data Handling, Content Safety, Fairness, Deception, Scope). Integrated into authoring (Phase 0 + Phase 5), deploy (pre-publish check), test (safety probes + verdict), and optimize (post-fix verification).
179 
1802. **Operational hooks** — `agent-validator.py` (PostToolUse) runs lightweight local preflight checks and warns on common authoring mistakes. It is not a parser or compiler; use the AgentScript SDK or Salesforce CLI for language validity. `guardrails.py` (PreToolUse) warns on production org deployments and destructive operations.
181 
182Key safety behaviors:
183 
184- `/agentforce-generate` blocks unsafe requests at Phase 0 and adds AI disclosure, scope boundaries, and escalation paths to all agents
185- `/agentforce-test` runs adversarial safety probes and produces a SAFE/UNSAFE/NEEDS_REVIEW verdict
186- `/agentforce-test` (Mode C — OWASP LLM Top 10 security testing) is part of the test flow, not a separate skill: it generates deployable Testing Center security test cases (C1) and/or runs live adversarial probing with an A–F grade (C2). Generating security test cases requires **explicit user confirmation**. Cases are authored **by the agent from the customer's own `.agent` script** — its actions, `available when` gates, injection sinks, and business domain — following `skills/agentforce-test/references/security-test-design.md`; there is no generator script. Always locate and read the `.agent` file first; a run based only on the neutral technique catalog covers materially less and must say so in the report.
187- `/agentforce-test` (Action Execution) checks org type (sandbox vs production) and validates inputs before execution
188- `/agentforce-generate` (Section 18 — Deploy) requires explicit user acknowledgment for warnings before proceeding
189 
190## Windows Compatibility
191 
192ADLC works on Windows with these considerations:
193 
194- **Python command**: Use `python` instead of `python3` on Windows
195- **Temp files**: Skill examples use `/tmp/` — substitute `%TEMP%\` (cmd) or `$env:TEMP\` (PowerShell)
196- **Shell examples**: SKILL.md bash examples work in Git Bash or WSL; PowerShell equivalents are noted where applicable
197- **Path resolution**: All Python scripts use `pathlib.Path` and are cross-platform
198- **Installer**: `python tools/install.py` works on all platforms (the bash `install.sh` wrapper is macOS/Linux only)
199- **Hook scripts**: Already handle `sys.platform == "win32"` for stdin reading
200