# Installation

Specwright can be installed in four ways: as a GitHub App, a Claude Code plugin, an MCP server, or self-hosted on Kubernetes.

## GitHub App

The GitHub App provides automated PR analysis, spec tracking, ticket sync, and doc maintenance.

### 1. Install the App

Visit the [Specwright GitHub App](https://github.com/apps/specwright) page and click **Install**. Select your organization and choose which repositories to enable.

### 2. Add SPECWRIGHT.yaml

Create a `SPECWRIGHT.yaml` file in your repository root:

```yaml
version: "1"

specs:
  doc_paths:
    - "docs/specs/*.md"

agents:
  pr_analysis: true
  doc_updates: true
  realization_check: true
```

### 3. Add a Spec

Create your first spec in `docs/specs/`:

```bash
mkdir -p docs/specs
cp docs/specs/_template.md docs/specs/my-feature.md
```

### 4. Open a PR

The Specwright bot will analyze your PR against the relevant specs and post a comment with spec references, discrepancies, and realization status.

## Claude Code Plugin {#claude-code-plugin}

The Claude Code plugin adds spec-driven development commands to your Claude Code sessions.

### Install

```bash
claude plugin add Gerner-Ventures/gv-exp-specwright
```

### Available Commands

| Command | Description |
|---------|-------------|
| `/sw:context` | Load spec context for your current task |
| `/sw:task` | Pick up a task, implement ACs, mark done |
| `/sw:verify` | Verify code against spec acceptance criteria |
| `/sw:new` | Create a new spec from template |
| `/sw:review` | Review changes against all documentation |
| `/sw:status` | Show spec coverage dashboard |
| `/sw:plan` | Spec-driven planning workflow |
| `/sw:update` | Update spec statuses from code evidence |

## MCP Server {#mcp-server}

The MCP server connects any MCP-compatible coding agent to the Specwright knowledge base.

### Configure in Claude Code

Add to your Claude Code MCP settings:

```json
{
  "mcpServers": {
    "specwright": {
      "command": "uvx",
      "args": ["specwright", "mcp"]
    }
  }
}
```

### Available Tools

- `search` — Hybrid search (vector + BM25) across all indexed specs and docs
- `get_spec` / `get_section` — Read parsed spec data with frontmatter, sections, and ACs
- `create_spec` — Create new specs from templates
- `update_section_status` — Update section statuses
- `add_realization` — Link code evidence to acceptance criteria
- `sync_spec_status` — Bulk updates in one commit

### Configure in Cursor / VS Code

MCP configuration varies by editor. Consult your editor's MCP documentation and point it at the Specwright MCP server endpoint.

## Self-Hosted {#self-hosted}

For full control over your data and configuration, deploy Specwright to your own Kubernetes cluster.

See the [Self-Hosting Guide](/guides/self-hosting) for detailed instructions covering:

- GitHub App creation
- Kubernetes secret management
- Helm chart installation
- Jira/Linear/GitHub Issues configuration
- DevSpace dev environment setup
