Architecture

Architecture

gsd-orchestrator is structured around a deterministic 9-state workflow engine that drives all GitHub operations through a stdio-spawned MCP server, with Claude handling all natural language tasks (analysis, editing, PR authoring, review comments).

State Machine

stateDiagram-v2
    direction LR
    [*] --> Idle
    Idle --> Analyzing
    Analyzing --> Branching
    Branching --> Editing
    Editing --> Validating
    Validating --> Committing
    Committing --> PrCreating
    PrCreating --> Reviewing
    Reviewing --> Documenting
    Documenting --> [*]

Loading

Per-State Behavior

• Idle — Calls get_repository and get_issue via MCP; populates IssueContext with the issue title, body, labels, and default branch name.
• Analyzing — Sends the issue body to Claude; retries up to 3 times on JSON parse failure; produces an AnalysisPlan containing the feature branch name, list of files to modify, and a change summary.
• Branching — Creates the feature branch from the default branch; idempotent — if the workflow was interrupted, resumes from the existing branch without re-creating it.
• Editing — Runs a ReAct loop per file (max 20 turns per file); reads the current file content via MCP, sends it to Claude with the issue context, then commits the result via create_or_update_file.
• Validating — Applies four safety gates: file safety blocklist (rejects changes to .pem, .key, or CI workflow files), merge conflict pre-flight, diff size guard, and test coverage intent check.
• Committing — Calls get_branch to confirm the final commit SHA is present in the branch; records the commit URL for the PR body.
• PrCreating — Checks for an existing PR from the same branch (idempotent on retry); generates the PR title and body via Claude; opens the pull request.
• Reviewing — Posts a bot review comment explaining what changed and why; requests reviewers from GSD_REVIEWERS if the variable is configured.
• Documenting — Updates docs/github-mcp-tools.md and CHANGELOG.md on the default branch; squash-merges the PR if GSD_AUTO_MERGE=true.
• Done / Failed — Terminal states. Done indicates the full workflow completed. Any state may transition to Failed on an unhandled exception.

Component Topology

flowchart LR
    subgraph Orchestrator["GSD Orchestrator (.NET 10)"]
        SM[GsdStateMachine]
        MCP[McpStdioClient]
        LLM[Anthropic.SDK]
        CP[FileCheckpointStore]
    end

    subgraph GitHub["GitHub"]
        MCPS[github-mcp-server.exe]
        GHAPI[GitHub API]
    end

    subgraph Anthropic["Anthropic"]
        CLAUDE[Claude API]
    end

    subgraph Storage["Local Storage"]
        CKPT[.gsd/state/]
    end

    SM --> MCP
    MCP -->|stdio| MCPS
    MCPS --> GHAPI
    SM --> LLM
    LLM --> CLAUDE
    SM --> CP
    CP --> CKPT

Loading

Data Flow

The Data Flow through gsd-orchestrator takes a GitHub Issue as input and produces a reviewed pull request (and optionally an auto-merged squash commit) as output. The transformation proceeds as follows:

Input: A GitHub issue body and its labels — free-form natural language describing a code change, bug fix, or feature request.

Transformation:

1. The Analyzing state extracts a structured change plan from the issue text: which files to touch and what to change in each.
2. The Branching state isolates the work on a dedicated feature branch.
3. The Editing state reads each target file and rewrites it through a Claude-powered ReAct loop, committing the result via MCP.
4. The Validating state applies safety gates to prevent accidental secret exposure or unsafe file modifications.
5. The PrCreating state opens a pull request with a Claude-generated description.
6. The Reviewing state posts a bot review comment summarising the changes.
7. The Documenting state records the MCP tools used and updates the changelog.

Output: A feature branch containing one or more commits, a pull request with a bot review comment, and optional auto-merge. If GSD_AUTO_MERGE=true, the PR is squash-merged after Documenting completes.