Metadata-Version: 2.4
Name: salesforce-agent-optimizer
Version: 1.0.0
Summary: Frictionless Salesforce Agent Skill for Codex, Claude Code, and GitHub Copilot.
Author: Luca Benedettini
License: MIT
Project-URL: Homepage, https://github.com/lucabenedettini/salesforce-ai-agent-optimizer
Project-URL: Repository, https://github.com/lucabenedettini/salesforce-ai-agent-optimizer
Project-URL: Issues, https://github.com/lucabenedettini/salesforce-ai-agent-optimizer/issues
Project-URL: Changelog, https://github.com/lucabenedettini/salesforce-ai-agent-optimizer/blob/main/CHANGELOG.md
Keywords: salesforce,agent-skills,codex,claude-code,github-copilot,ai-agents
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pyyaml; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# Salesforce Agent Optimizer

Salesforce Agent Optimizer is a public, autonomous Salesforce Agent Skill packaged as the `sfao` Python CLI for Codex, Claude Code, and GitHub Copilot.

Current version: `1.0.0`

It optimizes Salesforce delivery for AI agents through Salesforce-first solutioning, configuration-first planning, minimal reversible changes, compact local Knowledge, safe Salesforce CLI usage, least-privilege planning, destructive-operation guardrails, package.xml awareness, and token-efficient progressive disclosure.

## Quick Start

```bash
uv tool install salesforce-agent-optimizer
sfao install --project --platform all
sfao knowledge init --project-root .
sfao doctor
```

Use `uv tool install` or `pipx install` for CLI isolation. Plain `pip install` works, but isolated tool installers reduce PATH and dependency friction.

## Install From PyPI

```bash
uv tool install salesforce-agent-optimizer
sfao install --project --platform all
sfao knowledge init --project-root .
sfao doctor
```

Alternative:

```bash
pipx install salesforce-agent-optimizer
sfao install --project --platform all
sfao doctor
```

## Install From Git Before PyPI

```bash
uv tool install git+https://github.com/<owner>/<repository>.git
sfao version
sfao install --project --platform all
sfao doctor
```

Alternative:

```bash
pip install git+https://github.com/<owner>/<repository>.git
sfao install --project --platform all
sfao doctor
```

## Local Development Install

```bash
git clone https://github.com/lucabenedettini/salesforce-ai-agent-optimizer.git
cd salesforce-ai-agent-optimizer
python -m pip install -e ".[dev]"
sfao version
sfao validate
sfao doctor
```

## What `sfao` Installs

For Codex:

```text
.agents/skills/salesforce-agent-optimizer/SKILL.md
.agents/skills/salesforce-agent-optimizer/references/
.agents/skills/salesforce-agent-optimizer/scripts/
.agents/skills/salesforce-agent-optimizer/agents/openai.yaml
```

For Claude Code:

```text
.claude/skills/salesforce-agent-optimizer/SKILL.md
.claude/skills/salesforce-agent-optimizer/references/
.claude/skills/salesforce-agent-optimizer/scripts/
```

For GitHub Copilot:

```text
AGENTS.md
.github/copilot-instructions.md
.github/instructions/salesforce-agent-optimizer.instructions.md
```

Generated files contain:

```md
<!-- Generated by salesforce-agent-optimizer. Managed by sfao. -->
```

`sfao` never overwrites or removes user-owned files silently.

## Install

All agents:

```bash
sfao install --project --platform all
```

Only Codex:

```bash
sfao install --project --platform codex
```

Only Claude Code:

```bash
sfao install --project --platform claude
```

Only GitHub Copilot:

```bash
sfao install --project --platform copilot
```

## Update

```bash
uv tool upgrade salesforce-agent-optimizer
sfao update --project --platform all
sfao doctor
```

Alternative:

```bash
pipx upgrade salesforce-agent-optimizer
sfao update --project --platform all
sfao doctor
```

`sfao update` updates only files generated by `sfao`. If a generated file was manually edited, it is skipped and reported.

## Uninstall

```bash
sfao uninstall --project --platform all --yes
uv tool uninstall salesforce-agent-optimizer
```

Alternative:

```bash
sfao uninstall --project --platform all --yes
pipx uninstall salesforce-agent-optimizer
```

`sfao uninstall` removes only generated files. It keeps user-owned files and project folders such as `.github`, `.agents`, `.claude`, and `.salesforce-agent-knowledge`.

## Knowledge Generation

Create or refresh compact local Salesforce project Knowledge:

```bash
sfao knowledge init --project-root .
sfao knowledge refresh --project-root .
sfao knowledge doctor --project-root .
```

Knowledge is written to `.salesforce-agent-knowledge/` and stores summaries, indexes, hashes, source paths, wiki pages, and history. Source metadata remains the source of truth.

Optional org enrichment must use an explicit alias:

```bash
sfao knowledge refresh --project-root . --target-org my-sandbox
```

No org access is required by default.

## Salesforce Version-Context Update

Create and validate version-context resources:

```bash
sfao version-context scaffold
sfao version-context validate
```

Refresh official-source context:

```bash
sfao version-context update
sfao version-context validate
```

The command uses official Salesforce source links only and stores concise summaries, source links, API version context, SOAP login guardrails, LWC notes, and package-version cautions.

## Token Optimization And Context Compaction

The skill is designed for low-token agent work:

- Start from `SKILL.md`.
- Read `references/routing.md`.
- Load only task-relevant references.
- Consult `.salesforce-agent-knowledge/` before repeated metadata reads.
- Prefer compact JSON, summaries, path lists, diffs, and focused excerpts.
- Do not paste full metadata files unless strictly necessary.
- Use `--json`, `--summary`, `--compact`, `--max-items`, and `--verbose` intentionally.
- After meaningful steps, compact task state into goal, current state, files changed, commands executed, validation status, risks, and next action.

Token optimization never removes destructive-operation warnings, validation errors, permission impacts, package.xml scope, or deployment risks.

## Doctor And Validation

```bash
sfao doctor
sfao doctor --verbose
sfao doctor --json
sfao validate
sfao validate --verbose
sfao validate --json
```

Default output is concise: status first, then warnings and errors. Full diagnostics are opt-in with `--verbose`.

## Release And Publishing

Build locally:

```bash
python -m pip install -e ".[dev]"
sfao validate
python -m build
python -m twine check dist/*
```

Tag release:

```bash
git tag v1.0.0
git push origin v1.0.0
```

The release workflow builds wheel, sdist, a versioned skill ZIP, SHA256 checksums, and `release-manifest.json`.

PyPI publishing uses Trusted Publishing and runs only when repository variable `PUBLISH_TO_PYPI=true` is set.

See `docs/publishing.md`.

## Troubleshooting

`sfao: command not found`

- Run `uv tool update-shell`, open a new terminal, or add the tool bin directory to PATH.
- On Windows, check the user Scripts directory printed by `pip`.

`uv: command not found`

- Install `uv`, or use `pipx install salesforce-agent-optimizer`.

PyPI package not found

- Use the Git install command before PyPI publication.

Salesforce CLI `sf` not found

- Install the official Salesforce CLI and verify `sf --version`.

Skill not visible in Codex or Claude Code

- Run `sfao install --project --platform codex` or `sfao install --project --platform claude`.
- Restart the agent surface if it caches skills.

Copilot instructions not loading

- Confirm `.github/copilot-instructions.md` and `.github/instructions/salesforce-agent-optimizer.instructions.md` exist.
- Confirm the instructions file has `applyTo` frontmatter.

Version mismatch or stale generated files

- Run `sfao update --project --platform all`.
- Run `sfao validate`.

Invalid YAML, TOML, or frontmatter

- Run `sfao validate --verbose`.
- Ensure generated files were not collapsed into one line and have final LF newlines.

## Windows And PowerShell Notes

- Prefer `uv tool install` or `pipx install` for a stable `sfao` command.
- If PowerShell cannot find `sfao`, reopen the terminal after PATH changes.
- If script execution policy blocks local scripts, use Python module commands such as `python -m build` and `python scripts/validate_skill.py`.

## Privacy And Safety

- Do not commit Salesforce credentials, `.sf/`, `.sfdx/`, auth files, tokens, private keys, or local secrets.
- Least privilege is required during planning: inspect current access before granting permissions and grant only the minimum access needed.
- The safe Salesforce CLI facade requires explicit org aliases before org operations.
- Production org operations default to read-only inspection through the skill guardrails.
- Destructive data or metadata operations require explicit approval for the exact scope.
- Destructive CLI operations require the exact approval phrase `I explicitly approve this deletion`.
- Knowledge stores compact summaries and hashes, not raw secrets.

## Backward Compatibility

The canonical CLI is `sfao`. Existing slash-command guidance remains as wrappers:

- `/sf-init-project-skill` maps to `sfao knowledge init --project-root .`.
- `/sf-version-update-skill` maps to `sfao version-context scaffold` and `sfao version-context update`.

## Contributing

Before opening a pull request:

```bash
python -m pip install -e ".[dev]"
sfao validate
sfao doctor
python scripts/sync_agent_instructions.py --check --json
python scripts/validate_skill.py --json
python scripts/self_test.py --json
python -m pytest
python -m ruff check .
python -m build
python -m twine check dist/*
```
