Metadata-Version: 2.4
Name: salesforce-agent-optimizer
Version: 1.0.2
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

[English](README.md) | [Italiano](README.it.md) | [Espanol](README.es.md) | [Simplified Chinese](README.zh-CN.md)

Salesforce Agent Optimizer is an MIT-licensed Salesforce Agent Skill packaged as the
`sfao` command for Codex, Claude Code, and GitHub Copilot.

Current version: `1.0.2`

It installs agent instructions that enforce Salesforce-first solutioning,
configuration before custom code, minimal reversible changes, token-efficient
Knowledge, least-privilege planning, explicit org aliases, package.xml awareness,
and destructive-operation guardrails.

## 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 usually avoid PATH and dependency friction.

## Install

Recommended:

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

Alternative:

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

Install directly from GitHub before or outside PyPI publication:

```bash
uv tool install git+https://github.com/lucabenedettini/salesforce-ai-agent-optimizer.git
sfao install --project --platform all
sfao doctor
```

Plain `pip` is acceptable when you intentionally want the command in the active
Python environment:

```bash
pip install git+https://github.com/lucabenedettini/salesforce-ai-agent-optimizer.git
sfao install --project --platform all
sfao doctor
```

## Main `sfao` Commands

| Command | What it does |
| --- | --- |
| `sfao version` | Prints the installed Salesforce Agent Optimizer version. |
| `sfao install --project --platform all` | Installs Codex, Claude Code, and GitHub Copilot adapters in the current project. |
| `sfao install --project --platform codex` | Installs only the Codex project skill under `.agents/skills/`. |
| `sfao install --project --platform claude` | Installs only the Claude Code project skill under `.claude/skills/`. |
| `sfao install --project --platform copilot` | Installs only `AGENTS.md` and GitHub Copilot instruction files. |
| `sfao update --project --platform all` | Updates only files previously generated by `sfao`; user-edited files are skipped. |
| `sfao uninstall --project --platform all --yes` | Removes only generated adapter files; project folders and user-owned files are kept. |
| `sfao doctor` | Checks the local environment, installed adapters, Salesforce CLI availability, and common PATH issues. |
| `sfao doctor --verbose` | Prints full diagnostic details. |
| `sfao doctor --json` | Prints compact machine-readable diagnostics. |
| `sfao validate` | Validates installed files or the source tree, including frontmatter, YAML, TOML, JSON, Python, versions, and newline shape. |
| `sfao validate --verbose` | Prints validation details useful for troubleshooting. |
| `sfao validate --json` | Prints compact machine-readable validation results. |
| `sfao knowledge init --project-root .` | Creates `.salesforce-agent-knowledge/` for a Salesforce project. |
| `sfao knowledge refresh --project-root .` | Refreshes local Knowledge after metadata changes. |
| `sfao knowledge doctor --project-root .` | Checks whether local Knowledge exists and is usable. |
| `sfao knowledge refresh --project-root . --target-org <alias>` | Optionally enriches Knowledge from an org. The alias must be explicit. |
| `sfao version-context scaffold` | Creates local Salesforce release/API context files if missing. |
| `sfao version-context update` | Refreshes concise Salesforce release/API/package guidance from official Salesforce sources. |
| `sfao version-context validate` | Checks version-context files for required content. |

## What Gets Installed

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 this marker:

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

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

## Agent Workflow

After installation, the agent instructions require the same phase-gated workflow
for metadata information requests, bugfixes, new implementations, architecture
work, reviews, release work, and org inspection:

1. Review the request and restate scope, products/packages, org/environment, and acceptance criteria.
2. Plan from relevant references, local Knowledge, metadata dependencies, least privilege, and official Salesforce context when needed.
3. Ask for approval before file, metadata, org, deployable, or destructive changes.
4. Implement only approved minimal changes, or mark implementation as `not required` for information-only requests.
5. Generate `package.xml` when metadata is added or modified.
6. Validate before the final answer.
7. Return to planning after failed approval, tests, or validation; stop after three unsuccessful cycles.
8. Summarize evidence, changes or no-change result, validation, risks, and ask whether to push and to which branch when repository changes exist.

## Knowledge And Version Context

Create or refresh compact local Salesforce project Knowledge:

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

Refresh Salesforce release/API/package context:

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

Org access is never implicit. When a command needs Salesforce org metadata or
data, the agent must ask for an explicit alias. Production orgs are read-only
through the skill guardrails.

## 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
```

## 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
```

## 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.
- 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.

## 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 GitHub install command until the package is published on PyPI.

Salesforce CLI `sf` not found

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

Skill not visible in Codex, Claude Code, or GitHub Copilot

- Run the matching `sfao install --project --platform ...` command again.
- Restart the agent surface if it caches instructions.
- Run `sfao doctor` and `sfao validate`.

Stale generated files or version mismatch

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

## More Documentation

End-user and maintainer details live in the wiki source under `docs/wiki/`:

- `docs/wiki/Home.md`
- `docs/wiki/Installation.md`
- `docs/wiki/Packaging-And-Publishing.md`
- `docs/wiki/Principles.md`
- `docs/wiki/Testing-And-Manifests.md`
- `docs/wiki/Versioning.md`

Build, release, publishing, and package-maintenance details are intentionally kept
out of this README so the user-facing install path stays short.

## License

MIT. Anyone can use, copy, modify, distribute, and fork this repository under
the terms of `LICENSE`.
