salesforce-agent-optimizer 1.0.0__tar.gz

salesforce_agent_optimizer-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luca
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

salesforce_agent_optimizer-1.0.0/PKG-INFO

@@ -0,0 +1,360 @@
+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/*
+```

salesforce_agent_optimizer-1.0.0/README.md

@@ -0,0 +1,327 @@
+# 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/*
+```