Installation | Specwright
Description: AI-native enterprise documentation platform. Living specs, agent-maintained docs, repo-native knowledge.

Skip to content

# 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 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 ​

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 ​

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 ​

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

See the Self-Hosting Guide for detailed instructions covering:

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