# strands-agents/agent-sop architecture

> Architecture diagram of the GitHub repository strands-agents/agent-sop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/strands-agents/agent-sop
- Repository: https://github.com/strands-agents/agent-sop

## Overview

1. **Repository purpose**
   - This repo is a packaging and distribution system for “Agent SOPs”: markdown-based workflow definitions that can be delivered to AI tools in multiple formats.
   - The core architectural idea is **single source SOP content** converted into several target surfaces: MCP prompts, Cursor commands, Agent Skills, and a reusable format rule.

2. **Canonical content layer**
   - The authoritative workflow content appears to live in the **`agent-sops/`** directory, plus supporting documentation under **`spec/`** and **`rules/`**.
   - These markdown files define the SOPs themselves, the SOP format specification, and the authoring/validation rule, which are then transformed into runtime artifacts.

3. **Python package as the transformation engine**
   - The **`python/strands_agents_sops/`** package is the main executable subsystem.
   - It likely contains one module per output channel:
     - **`mcp.py`** for exposing SOPs as MCP prompts
     - **`cursor.py`** for generating Cursor command files
     - **`skills.py`** for generating Agent Skills
     - **`rules.py`** for emitting the SOP format rule
     - **`utils.py`** for shared file/path/markdown handling
     - **`__main__.py`** and **`main.py`-style entry handling in the package** for the CLI

4. **CLI as the primary control plane**
   - The package is used as a command-line tool (`strands-agents-sops`) with subcommands such as `mcp`, `commands`, `skills`, and `rule`.
   - The CLI is the orchestration boundary: it loads built-in SOPs, optionally loads external SOPs from user-supplied paths, applies precedence rules, and emits the chosen target format.

5. **External SOP loading is a first-class extension point**
   - The README and tests indicate a key architectural feature: users can supply additional SOP directories via `--sop-paths`.
   - These external SOPs are discovered by filename suffix (`.sop.md`), normalized for paths like `~` and relative paths, and merged with built-ins using override precedence.
   - This makes SOP content extensible without changing the package code.

6. **Multiple output adapters**
   - The repo is not a single-product app; it is a **multi-adapter content distribution system**.
   - Each adapter targets a different ecosystem boundary:
     - **MCP server**: exposes prompts to clients like Kiro or Claude Code
     - **Cursor commands**: generates command files consumable inside Cursor
     - **Skills**: generates `SKILL.md` bundles for Claude/Skills-compatible tooling
     - **Rule output**: prints or exports the SOP authoring format rule for other agent platforms

7. **Generated artifact boundaries**
   - Generated outputs are intentionally separated from source SOPs:
     - **`.cursor/commands/`** for Cursor
     - **`skills/<name>/SKILL.md`** for Agent Skills
     - likely a rule file destination when exported into another tool’s conventions
   - This separation is important for diagramming: source content enters the package, transformed artifacts exit into tool-specific directories.

8. **Built-in workflows shipped with the package**
   - The README identifies several built-in SOPs: `codebase-summary`, `pdd`, `code-task-generator`, `code-assist`, and `eval`.
   - The presence of `skills/agent-sop-author/` and `rules/agent-sop-format.md` suggests the repo also ships its own authoring workflow and formatting guidance, not just end-user operational SOPs.

9. **Validation and correctness layer**
   - Tests under **`python/tests/`** cover cursor generation, SOP loading, rules, skills, main entry behavior, and utility functions.
   - This indicates the architecture relies on deterministic transformation and discovery behavior, especially around malformed input and precedence handling.
   - The **`skills/agent-sop-author/validate-sop.sh`** script adds a shell-based validation step for authored SOPs.

10. **Distribution and packaging**
   - The Python project is isolated under **`python/`** with its own `pyproject.toml`, so the repo is structured as a package distribution rather than a monolithic application.
   - Top-level `.claude-plugin/` metadata and GitHub workflows indicate the repo also publishes itself as a plugin/skill distribution artifact.

11. **GitHub Actions and release pipeline**
   - The `.github/workflows/` directory shows separate automation lanes:
     - PR/push validation
     - lint/test
     - PyPI publishing on release
     - skills publishing
   - This means build/test/release is a significant architectural boundary: source SOP changes flow through CI into packaged Python releases and generated skill distributions.

12. **How the pieces flow together**
   - A practical data flow is:
     1. SOP markdown is authored in repo content locations
     2. the Python CLI discovers built-in and external SOPs
     3. the selected adapter renders them into a target format
     4. the output is consumed by an AI tool, MCP client, or plugin/skills system
   - The repo therefore functions as a **content compiler for agent workflows**.

13. **Diagramming takeaway**
   - If you draw this architecture, the main nodes are:
     - **SOP source content**
     - **Python CLI / transformer layer**
     - **Adapter outputs** for MCP, Cursor, Skills, and Rules
     - **External consumer tools** such as Kiro, Claude Code, and Claude Skills-compatible systems
   - The important boundary is not “backend vs frontend,” but **canonical markdown workflows vs generated tool-specific integrations**.

Main entry points: [`python/strands_agents_sops/__main__.py`](https://github.com/strands-agents/agent-sop/blob/main/python/strands_agents_sops/__main__.py) (CLI), [`python/strands_agents_sops/rules.py`](https://github.com/strands-agents/agent-sop/blob/main/python/strands_agents_sops/rules.py) (Rules Adapter), [`python/strands_agents_sops/skills.py`](https://github.com/strands-agents/agent-sop/blob/main/python/strands_agents_sops/skills.py) (Skills Adapter), [`.github/workflows`](https://github.com/strands-agents/agent-sop/blob/main/.github/workflows) (CI Workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_source["Source SOPs"]
  node_agent_sops["Agent SOPs<br/>sop source"]
  node_spec_doc["SOP Spec<br/>format spec"]
  node_format_rule["Format Rule<br/>authoring rule"]
end

subgraph group_engine["Python Engine"]
  node_cli["CLI<br/>entrypoint<br/>[__main__.py]"]
  node_mcp_adapter["MCP Adapter<br/>renderer<br/>[mcp.py]"]
  node_cursor_adapter["Cursor Adapter<br/>renderer<br/>[cursor.py]"]
  node_skills_adapter["Skills Adapter<br/>renderer<br/>[skills.py]"]
  node_rules_adapter["Rules Adapter<br/>renderer<br/>[rules.py]"]
  node_utils["Utilities<br/>shared helpers<br/>[utils.py]"]
  node_external_sops["External SOPs<br/>extension input"]
end

subgraph group_outputs["Generated Surfaces"]
  node_mcp_prompts["MCP Prompts<br/>published artifact"]
  node_cursor_commands["Cursor Commands<br/>published artifact"]
  node_skill_bundle["Skill Bundle<br/>published artifact<br/>[SKILL.md]"]
  node_rule_output["Rule Output<br/>published artifact"]
end

subgraph group_delivery["Packaging & CI"]
  node_pyproject["Py Project<br/>package config<br/>[pyproject.toml]"]
  node_plugin_meta["Plugin Meta<br/>distribution metadata<br/>[plugin.json]"]
  node_workflows["CI Workflows<br/>automation<br/>[workflows]"]
end

node_agent_sops -->|"load built-ins"| node_cli
node_external_sops -->|"override input"| node_cli
node_spec_doc -->|"defines shape"| node_rules_adapter
node_format_rule -->|"source rule"| node_rules_adapter
node_cli -->|"mcp"| node_mcp_adapter
node_cli -->|"commands"| node_cursor_adapter
node_cli -->|"skills"| node_skills_adapter
node_cli -->|"rule"| node_rules_adapter
node_cli -->|"uses"| node_utils
node_mcp_adapter -->|"renders"| node_mcp_prompts
node_cursor_adapter -->|"renders"| node_cursor_commands
node_skills_adapter -->|"renders"| node_skill_bundle
node_rules_adapter -->|"renders"| node_rule_output
node_skills_adapter -->|"includes"| node_external_sops
node_pyproject -->|"packages"| node_cli
node_plugin_meta -->|"publishes"| node_workflows
node_workflows -->|"builds"| node_pyproject
node_workflows -->|"releases"| node_skill_bundle

click node_agent_sops "https://github.com/strands-agents/agent-sop/tree/main/agent-sops"
click node_spec_doc "https://github.com/strands-agents/agent-sop/blob/main/spec/agent-sops-specification.md"
click node_format_rule "https://github.com/strands-agents/agent-sop/blob/main/rules/agent-sop-format.md"
click node_cli "https://github.com/strands-agents/agent-sop/blob/main/python/strands_agents_sops/__main__.py"
click node_mcp_adapter "https://github.com/strands-agents/agent-sop/blob/main/python/strands_agents_sops/mcp.py"
click node_cursor_adapter "https://github.com/strands-agents/agent-sop/blob/main/python/strands_agents_sops/cursor.py"
click node_skills_adapter "https://github.com/strands-agents/agent-sop/blob/main/python/strands_agents_sops/skills.py"
click node_rules_adapter "https://github.com/strands-agents/agent-sop/blob/main/python/strands_agents_sops/rules.py"
click node_utils "https://github.com/strands-agents/agent-sop/blob/main/python/strands_agents_sops/utils.py"
click node_skill_bundle "https://github.com/strands-agents/agent-sop/blob/main/skills/agent-sop-author/SKILL.md"
click node_pyproject "https://github.com/strands-agents/agent-sop/blob/main/python/pyproject.toml"
click node_plugin_meta "https://github.com/strands-agents/agent-sop/blob/main/.claude-plugin/plugin.json"
click node_workflows "https://github.com/strands-agents/agent-sop/blob/main/.github/workflows"

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_agent_sops,node_spec_doc,node_format_rule toneBlue
class node_cli,node_mcp_adapter,node_cursor_adapter,node_skills_adapter,node_rules_adapter,node_utils,node_external_sops toneAmber
class node_mcp_prompts,node_cursor_commands,node_skill_bundle,node_rule_output toneMint
class node_pyproject,node_plugin_meta,node_workflows toneRose
```

## Components

### Source SOPs

Canonical markdown workflows and their authoring rules.

- [Agent SOPs](https://github.com/strands-agents/agent-sop/tree/main/agent-sops): sop source · Built-in workflow content shipped as markdown SOPs. · `agent-sops`
- [SOP Spec](https://github.com/strands-agents/agent-sop/blob/main/spec/agent-sops-specification.md): format spec · Defines the repository's SOP format and structure. · `spec/agent-sops-specification.md`
- [Format Rule](https://github.com/strands-agents/agent-sop/blob/main/rules/agent-sop-format.md): authoring rule · Markdown rule used to validate and guide SOP authoring. · `rules/agent-sop-format.md`

### Python Engine

CLI and transformation modules that discover and render SOPs.

- [CLI](https://github.com/strands-agents/agent-sop/blob/main/python/strands_agents_sops/__main__.py): entrypoint · Command-line control plane for loading SOPs and selecting output adapters. · `python/strands_agents_sops/__main__.py`
- [MCP Adapter](https://github.com/strands-agents/agent-sop/blob/main/python/strands_agents_sops/mcp.py): renderer · Exposes SOPs as MCP prompts for compatible clients. · `python/strands_agents_sops/mcp.py`
- [Cursor Adapter](https://github.com/strands-agents/agent-sop/blob/main/python/strands_agents_sops/cursor.py): renderer · Generates Cursor command files from SOP content. · `python/strands_agents_sops/cursor.py`
- [Skills Adapter](https://github.com/strands-agents/agent-sop/blob/main/python/strands_agents_sops/skills.py): renderer · Builds Agent Skills bundles such as SKILL.md outputs. · `python/strands_agents_sops/skills.py`
- [Rules Adapter](https://github.com/strands-agents/agent-sop/blob/main/python/strands_agents_sops/rules.py): renderer · Emits the SOP format rule for other tools or exports. · `python/strands_agents_sops/rules.py`
- [Utilities](https://github.com/strands-agents/agent-sop/blob/main/python/strands_agents_sops/utils.py): shared helpers · Shared path, discovery, and markdown handling used by adapters. · `python/strands_agents_sops/utils.py`
- **External SOPs**: extension input · User-supplied SOP directories loaded through override precedence.

### Generated Surfaces

Tool-specific artifacts and bundle formats produced from SOP content.

- **MCP Prompts**: published artifact · Prompt surface consumed by MCP clients such as Claude Code or Kiro.
- **Cursor Commands**: published artifact · Command files generated into Cursor's commands directory.
- [Skill Bundle](https://github.com/strands-agents/agent-sop/blob/main/skills/agent-sop-author/SKILL.md): published artifact · Distributed skills package rooted at SKILL.md. · `skills/agent-sop-author/SKILL.md`
- **Rule Output**: published artifact · Rendered format rule consumed by other agent platforms.

### Packaging & CI

Distribution metadata and automation for publishing and validation.

- [Py Project](https://github.com/strands-agents/agent-sop/blob/main/python/pyproject.toml): package config · Python package definition and distribution metadata. · `python/pyproject.toml`
- [Plugin Meta](https://github.com/strands-agents/agent-sop/blob/main/.claude-plugin/plugin.json): distribution metadata · Claude plugin metadata used for packaging and marketplace distribution. · `.claude-plugin/plugin.json`
- [CI Workflows](https://github.com/strands-agents/agent-sop/blob/main/.github/workflows): automation · GitHub Actions lanes for validation, testing, publishing, and skills release. · `.github/workflows`

## Connections

- Agent SOPs → CLI: load built-ins · Canonical SOP markdown is discovered and fed into the CLI.
- External SOPs → CLI: override input · User-supplied SOP directories are merged with built-ins using precedence rules.
- SOP Spec → Rules Adapter: defines shape · The SOP specification informs the emitted format rule.
- Format Rule → Rules Adapter: source rule · The authoring rule is used as the basis for rule output.
- CLI → MCP Adapter: mcp · CLI dispatches to the MCP rendering path.
- CLI → Cursor Adapter: commands · CLI dispatches to Cursor command generation.
- CLI → Skills Adapter: skills · CLI dispatches to skill bundle generation.
- CLI → Rules Adapter: rule · CLI dispatches to rule emission.
- CLI → Utilities: uses · CLI relies on shared discovery and path helpers.
- MCP Adapter → MCP Prompts: renders · Adapter converts SOPs into MCP prompt surfaces.
- Cursor Adapter → Cursor Commands: renders · Adapter writes Cursor-compatible command files.
- Skills Adapter → Skill Bundle: renders · Adapter builds skill bundles for downstream tooling.
- Rules Adapter → Rule Output: renders · Adapter emits a portable format rule artifact.
- Skills Adapter → External SOPs: includes · Skill generation can incorporate external SOP content.
- Py Project → CLI: packages · Python packaging exposes the CLI entrypoint and modules.
- Plugin Meta → CI Workflows: publishes · Plugin metadata is delivered through repository automation.
- CI Workflows → Py Project: builds · CI validates and publishes the Python package on release.
- CI Workflows → Skill Bundle: releases · GitHub Actions publishes skill artifacts.
