# gellasangameshgupta/salesforce-compound-engineering-plugin architecture

> Architecture diagram of the GitHub repository gellasangameshgupta/salesforce-compound-engineering-plugin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gellasangameshgupta/salesforce-compound-engineering-plugin
- Repository: https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin

## Overview

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: [`cli/src/converters`](https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/tree/main/cli/src/converters) (Converters), [`skills/sf-plan/SKILL.md`](https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/skills/sf-plan/SKILL.md) (Plan workflow), [`skills/sf-review/SKILL.md`](https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/skills/sf-review/SKILL.md) (Review workflow), [`.mcp.json`](https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/.mcp.json) (MCP config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_source["Source assets"]
  node_manifests["Plugin manifests<br/>host packaging"]
  node_skills_index["Skill index<br/>entry map<br/>[index.md]"]
  node_sf_plan["Plan workflow<br/>workflow skill<br/>[SKILL.md]"]
  node_sf_review["Review workflow<br/>workflow skill<br/>[SKILL.md]"]
  node_sf_work["Work workflow<br/>workflow skill<br/>[SKILL.md]"]
  node_skill_personas["Persona bank<br/>embedded personas"]
  node_docs_plans["Knowledge plans<br/>durable knowledge"]
  node_principles["Principles<br/>governance spec<br/>[PRINCIPLES.md]"]
  node_schema["Schema<br/>[schema.yaml]"]
end

subgraph group_cli["Conversion engine"]
  node_cli_entry["CLI entry<br/>bun installer<br/>[index.ts]"]
  node_parser["Parser<br/>input parsing"]
  node_transforms["Transforms<br/>rewrite layer"]
  node_converters["Converters<br/>emitters"]
  node_detect["Detect utils<br/>platform detection<br/>[detect.ts]"]
  node_copilot_conv["Copilot adapter<br/>platform emitter<br/>[copilot.ts]"]
  node_cursor_conv["Cursor adapter<br/>platform emitter<br/>[cursor.ts]"]
  node_codex_conv["Codex adapter<br/>platform emitter<br/>[codex.ts]"]
end

subgraph group_integrations["External integrations"]
  node_mcp_config["MCP config<br/>integration config<br/>[.mcp.json]"]
  node_context7(("Context7<br/>docs service"))
  node_salesforce_dx(("Salesforce DX<br/>org tooling"))
end

node_manifests -->|"package entry"| node_cli_entry
node_skills_index -->|"route"| node_sf_plan
node_skills_index -->|"route"| node_sf_review
node_skills_index -->|"route"| node_sf_work
node_sf_plan -->|"dispatch"| node_skill_personas
node_sf_review -->|"dispatch"| node_skill_personas
node_sf_work -->|"dispatch"| node_skill_personas
node_sf_plan -->|"capture"| node_docs_plans
node_sf_review -->|"learn"| node_docs_plans
node_principles -->|"govern"| node_sf_plan
node_principles -->|"govern"| node_sf_review
node_schema -->|"validate"| node_docs_plans
node_mcp_config -->|"connect"| node_context7
node_mcp_config -->|"connect"| node_salesforce_dx
node_cli_entry -->|"read"| node_parser
node_parser -->|"normalize"| node_transforms
node_transforms -->|"emit prep"| node_converters
node_cli_entry -->|"detect"| node_detect
node_converters -->|"emit"| node_copilot_conv
node_converters -->|"emit"| node_cursor_conv
node_converters -->|"emit"| node_codex_conv
node_detect -->|"select"| node_converters
node_mcp_config -->|"support"| node_sf_plan
node_mcp_config -->|"support"| node_sf_review

click node_skills_index "https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/skills/index.md"
click node_sf_plan "https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/skills/sf-plan/SKILL.md"
click node_sf_review "https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/skills/sf-review/SKILL.md"
click node_sf_work "https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/skills/sf-work/SKILL.md"
click node_skill_personas "https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/tree/main/skills/sf-review/references/personas"
click node_docs_plans "https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/tree/main/docs/plans"
click node_principles "https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/PRINCIPLES.md"
click node_schema "https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/schema.yaml"
click node_mcp_config "https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/.mcp.json"
click node_cli_entry "https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/cli/src/index.ts"
click node_parser "https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/tree/main/cli/src/parser"
click node_transforms "https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/tree/main/cli/src/transforms"
click node_converters "https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/tree/main/cli/src/converters"
click node_detect "https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/cli/src/utils/detect.ts"
click node_copilot_conv "https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/cli/src/converters/copilot.ts"
click node_cursor_conv "https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/cli/src/converters/cursor.ts"
click node_codex_conv "https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/cli/src/converters/codex.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_manifests,node_skills_index,node_sf_plan,node_sf_review,node_sf_work,node_skill_personas,node_docs_plans,node_principles,node_schema toneBlue
class node_cli_entry,node_parser,node_transforms,node_converters,node_detect,node_copilot_conv,node_cursor_conv,node_codex_conv toneAmber
class node_mcp_config,node_context7,node_salesforce_dx toneMint
```

## Components

### Source assets

Repository content that defines workflows, prompts, and packaged plugin entry points.

- **Plugin manifests**: host packaging · Tool-specific plugin descriptors that package the same source content for different hosts.
- [Skill index](https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/skills/index.md): entry map · Top-level index of the skills surface and entry points. · `skills/index.md`
- [Plan workflow](https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/skills/sf-plan/SKILL.md): workflow skill · Research-and-planning skill that coordinates analysis and knowledge gathering. · `skills/sf-plan/SKILL.md`
- [Review workflow](https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/skills/sf-review/SKILL.md): workflow skill · Multi-lens review skill that orchestrates specialist checks across Salesforce code and metadata. · `skills/sf-review/SKILL.md`
- [Work workflow](https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/skills/sf-work/SKILL.md): workflow skill · Execution-oriented workflow that drives compound engineering tasks end to end. · `skills/sf-work/SKILL.md`
- [Persona bank](https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/tree/main/skills/sf-review/references/personas): embedded personas · Specialist prompt assets embedded under skill packages and dispatched by workflows. · `skills/sf-review/references/personas`
- [Knowledge plans](https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/tree/main/docs/plans): durable knowledge · Protected planning artifacts used to compound learning across iterations. · `docs/plans`
- [Principles](https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/PRINCIPLES.md): governance spec · Behavioral source of truth for workflow behavior and repo standards. · `PRINCIPLES.md`
- [Schema](https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/schema.yaml): validation 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](https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/cli/src/index.ts): bun installer · Entry point for the distribution pipeline. · `cli/src/index.ts`
- [Parser](https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/tree/main/cli/src/parser): input parsing · Reads plugin metadata and markdown skill assets into an internal model. · `cli/src/parser`
- [Transforms](https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/tree/main/cli/src/transforms): rewrite layer · Applies frontmatter, path, and reference rewrites for host-specific layouts. · `cli/src/transforms`
- [Converters](https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/tree/main/cli/src/converters): emitters · Per-platform output emitters for the supported host ecosystems. · `cli/src/converters`
- [Detect utils](https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/cli/src/utils/detect.ts): platform detection · Helpers for identifying target platforms and capabilities. · `cli/src/utils/detect.ts`
- [Copilot adapter](https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/cli/src/converters/copilot.ts): platform emitter · Representative converter for GitHub Copilot output layout. · `cli/src/converters/copilot.ts`
- [Cursor adapter](https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/cli/src/converters/cursor.ts): platform emitter · Representative converter for Cursor output layout. · `cli/src/converters/cursor.ts`
- [Codex adapter](https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/cli/src/converters/codex.ts): platform emitter · 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](https://github.com/gellasangameshgupta/salesforce-compound-engineering-plugin/blob/main/.mcp.json): integration config · Model Context Protocol wiring for documentation lookup and Salesforce tooling. · `.mcp.json`
- **Context7**: docs service · External documentation lookup service used by skills.
- **Salesforce DX**: org tooling · External Salesforce execution and analysis tooling used by skills.

## Connections

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