How gellasangameshgupta/salesforce-compound-engineering-plugin works
1. What this repository is
This is a multi-platform plugin distribution repo for “SF Compound Engineering” workflows, not an application runtime. Its purpose is to package the same Salesforce-oriented skill system for multiple AI coding tools: Claude Code, Cursor, Codex, Copilot, Windsurf, Gemini, OpenCode, Kiro, Droid, Pi, OpenClaw, and Qwen.
2. Top-level architecture
The repo has three main layers:
- Plugin manifests for each host tool
- A Bun-based CLI installer/converter
- Reusable content assets: skills, personas, docs, and knowledge artifacts
3. Primary content model: skills-first
The real product surface is the skills/ tree. Each entry point like /sf-plan, /sf-review, or /sf-work is implemented as a skill file with frontmatter and supporting content. The skills own the workflow logic and reference specialist personas under skills/<skill>/references/personas/.
4. Agentless persona dispatch
The repo is explicitly agentless: there are no standalone agent definitions in a separate agents directory. Instead, “personas” are prompt assets embedded inside skill packages and dispatched by the workflow skills as parallel research/review roles. This is a major boundary: skills orchestrate; personas specialize.
5. Installer/conversion pipeline
The cli/ package is the mechanical heart of distribution. It reads the source plugin content and converts it into host-specific layouts. The pipeline is:
- detect target platform(s)
- parse plugin/markdown assets
- apply path/reference/frontmatter transforms
- emit platform-specific files and manifests
6. CLI internal structure
The CLI is organized around clear responsibilities:
- parser/ handles plugin metadata and markdown parsing
- transforms/ rewrites frontmatter, file paths, and cross-references
- converters/ contains per-platform emitters for the supported tools
- utils/ contains detection and helper logic
This is a classic read-transform-write pipeline.
7. Platform boundary: one source, many outputs
The same skills content is normalized into different host formats. The README shows outputs such as:
- .github/skills/ and .github/agents/*.agent.md for Copilot
- .cursor/skills/ symlinks and .cursor/mcp.json for Cursor
- skills/, commands/, agents/, or tool-specific config files for other platforms
These output differences are the main adapter boundary in the system.
8. Repository-owned plugin manifests
The root contains tool-specific manifests such as:
- .claude-plugin/plugin.json
- .cursor-plugin/plugin.json
- .codex-plugin/plugin.json
These are packaging descriptors for host ecosystems and are separate from the skill content itself.
9. Knowledge compounding loop
The repo includes durable learning artifacts under docs/:
- docs/plans/
- docs/brainstorms/
- docs/solutions/
These are treated as protected institutional knowledge. The workflow skills are designed to capture lessons back into these directories so later iterations start smarter.
10. Governance and schema boundaries
PRINCIPLES.md is the behavioral source of truth for the workflow system, while schema.yaml validates solution documents. Together they enforce consistency between authored knowledge and the automation that consumes it.
11. External integrations
The repo uses .mcp.json to configure Model Context Protocol connections:
- context7 for documentation lookup
- salesforce-dx for live org operations, code analysis, testing, metadata, and related Salesforce tooling
This is important because the skills rely on external tools for research and execution, not just local files.
12. Salesforce-specific domain focus
The skill set is deeply Salesforce-oriented: Apex, Flow, LWC, metadata, security, integration patterns, testing, and Agentforce. Many skills are domain generators or review frameworks, and the repository is structured to support Salesforce development workflows end-to-end.
13. Build/test boundary
The CLI has its own isolated test suite under cli/tests/, covering parser, transforms, and detection logic. That makes the install/conversion engine independently verifiable from the skill content it packages.
14. How to draw the architecture
A good diagram would show:
- Source assets: skills, personas, docs, plugin manifests
- Orchestration layer: workflow skills that route, research, review, and compound knowledge
- Conversion layer: Bun CLI reading source assets and emitting platform-specific plugin bundles
- External services: MCP servers for docs and Salesforce org operations
- Feedback loop: solutions/docs captured back into the repo and reused by later workflow runs
Main entry points: converters Converters · sf-plan/SKILL.md Plan workflow · sf-review/SKILL.md Review workflow · .mcp.json MCP config
Components 20
Source assets
Repository content that defines workflows, prompts, and packaged plugin entry points.
- Plugin manifests · Tool-specific plugin descriptors that package the same source content for different hosts.
- Skill index · Top-level index of the skills surface and entry points.
skills/index.md - Plan workflow · Research-and-planning skill that coordinates analysis and knowledge gathering.
skills/sf-plan/SKILL.md - Review workflow · Multi-lens review skill that orchestrates specialist checks across Salesforce code and metadata.
skills/sf-review/SKILL.md - Work workflow · Execution-oriented workflow that drives compound engineering tasks end to end.
skills/sf-work/SKILL.md - Persona bank · Specialist prompt assets embedded under skill packages and dispatched by workflows.
skills/sf-review/references/personas - Knowledge plans · Protected planning artifacts used to compound learning across iterations.
docs/plans - Principles · Behavioral source of truth for workflow behavior and repo standards.
PRINCIPLES.md - Schema · Validation schema for solution documents and authored knowledge.
schema.yaml
Conversion engine
Bun-based installer that parses, transforms, and emits host-specific bundles.
- CLI entry · Entry point for the distribution pipeline.
cli/src/index.ts - Parser · Reads plugin metadata and markdown skill assets into an internal model.
cli/src/parser - Transforms · Applies frontmatter, path, and reference rewrites for host-specific layouts.
cli/src/transforms - Converters · Per-platform output emitters for the supported host ecosystems.
cli/src/converters - Detect utils · Helpers for identifying target platforms and capabilities.
cli/src/utils/detect.ts - Copilot adapter · Representative converter for GitHub Copilot output layout.
cli/src/converters/copilot.ts - Cursor adapter · Representative converter for Cursor output layout.
cli/src/converters/cursor.ts - Codex adapter · Representative converter for Codex output layout.
cli/src/converters/codex.ts
External integrations
Model Context Protocol connections used by the workflows for documentation and Salesforce execution.
- MCP config · Model Context Protocol wiring for documentation lookup and Salesforce tooling.
.mcp.json - Context7 · External documentation lookup service used by skills.
- Salesforce DX · External Salesforce execution and analysis tooling used by skills.
Connections 24
- Plugin manifests → CLI entry: package entry · Plugin manifests point to the distribution engine that assembles host-specific bundles.
- Skill index → Plan workflow: route · The index exposes the workflow entry points.
- Skill index → Review workflow: route · The index exposes the workflow entry points.
- Skill index → Work workflow: route · The index exposes the workflow entry points.
- Plan workflow → Persona bank: dispatch · Planning workflows invoke embedded research personas.
- Review workflow → Persona bank: dispatch · Review workflows fan out to specialist personas.
- Work workflow → Persona bank: dispatch · Execution workflows reuse persona assets when needed.
- Plan workflow → Knowledge plans: capture · Planning work compounds into durable plan artifacts.
- Review workflow → Knowledge plans: learn · Review findings feed back into the knowledge base.
- Principles → Plan workflow: govern · Workflow behavior is constrained by the repo's principles.
- Principles → Review workflow: govern · Workflow behavior is constrained by the repo's principles.
- Schema → Knowledge plans: validate · Solution and plan documents are validated against the schema.
- MCP config → Context7: connect · MCP configuration wires documentation lookup access.
- MCP config → Salesforce DX: connect · MCP configuration wires Salesforce execution and analysis access.
- CLI entry → Parser: read · The CLI starts by parsing plugin metadata and markdown assets.
- Parser → Transforms: normalize · Parsed content is rewritten into host-neutral internal form.
- Transforms → Converters: emit prep · Rewritten assets are handed to platform-specific emitters.
- CLI entry → Detect utils: detect · The installer detects the intended target platform(s).
- Converters → Copilot adapter: emit · Representative host emitter for Copilot layouts.
- Converters → Cursor adapter: emit · Representative host emitter for Cursor layouts.
- Converters → Codex adapter: emit · Representative host emitter for Codex layouts.
- Detect utils → Converters: select · Platform detection selects the appropriate emitter path.
- MCP config → Plan workflow: support · Planning workflows rely on external MCP-backed research and execution.
- MCP config → Review workflow: support · Review workflows rely on external MCP-backed research and execution.