Skip to main content

Claude GitHub Actions Plugin Architecture

System Overview​

This isn't a running service - it's a Claude Code plugin: a marketplace manifest pointing at one plugin, which bundles five markdown "command" files. When installed, Claude Code loads each command file's instructions and exposes it as a slash command; invoking the command makes Claude follow that file's steps using its own git/gh tool access in the current project.

Architecture Diagram​

graph TB
    subgraph Repo["claude-github-actions"]
      Marketplace[".claude-plugin/marketplace.json<br/>defines the fleet-studio marketplace"]
      PluginManifest["plugins/fleet-git-workflow/.claude-plugin/plugin.json"]
      Commands["plugins/fleet-git-workflow/commands/*.md<br/>new-branch, feature-branch, commit, stage-pr, prod-pr"]
    end
    ClaudeCode["Claude Code session<br/>(installed per-project)"]
    GitHub["Local git + GitHub<br/>(via gh, git CLI)"]

    Marketplace --> PluginManifest
    PluginManifest --> Commands
    ClaudeCode -->|"/plugin marketplace add + /plugin install"| Marketplace
    ClaudeCode -->|"user runs /commit, /stage-pr, etc."| Commands
    Commands -->|"instructs Claude to run"| GitHub

How to read this diagram​

Arrows mean flow / dependency / "talks to", not button clicks. There's no server here - "runtime" is a Claude Code session interpreting a markdown file's instructions.

Core Components​

.claude-plugin/marketplace.json​

Declares the fleet-studio marketplace and lists fleet-git-workflow as its one plugin, pointing at ./plugins/fleet-git-workflow.

plugins/fleet-git-workflow/.claude-plugin/plugin.json​

Plugin manifest (name, description, author) required for Claude Code to recognize the directory as an installable plugin.

plugins/fleet-git-workflow/commands/*.md​

Each file is a natural-language spec for one slash command - trigger phrases, step-by-step instructions, example usage, and explicit rules (e.g. "never force-push," "confirm the parent branch first"). Claude Code executes these as instructions, not as code.

Command Flow (example: /stage-pr)​

sequenceDiagram
    participant Dev
    participant Claude
    participant Git as git/gh CLI
    participant GitHub

    Dev->>Claude: /stage-pr
    Claude->>Git: git status / diff
    Claude->>Git: commit staged changes
    Claude->>Git: push branch
    Claude->>Git: check for conflicts vs dev
    Claude->>GitHub: gh pr create (branch -> dev)
    GitHub-->>Claude: PR URL
    Claude-->>Dev: report PR URL + conflict status

Design Decisions​

Markdown instructions, not executable scripts​

Context: The team wanted consistent git workflows across everyone's Claude Code sessions without maintaining a separate CLI tool.

Decision: Ship the workflow as plugin command files (natural-language instructions Claude follows using its own tools) rather than a standalone script - install once per project via the plugin system, no extra binary to keep updated.

Auto-detect parent branch by convention​

Context: Different repos use dev, develop, or development as their integration branch.

Decision: /new-branch and /feature-branch check for each in that order rather than requiring the user to specify it every time, while still confirming with the user before branching.

Technology Stack​

LayerTechnology
FormatClaude Code plugin (marketplace + plugin manifest + markdown commands)
Dependenciesgit, gh CLI (used by Claude Code at invocation time)
Default branchmain

Next Steps​