# Signoff + Ref companion setup

Set up Ref as the optional planning companion to Signoff on this computer.

Keep the responsibility boundary explicit:

- Ref Plans owns collaborative implementation plans, comments, agent handoff, and pull request progress.
- Ref Context provides optional documentation search.
- Signoff owns the executable user-facing specification, build-pinned QA runs, evidence, findings, and verdicts.
- WorkerBee, when installed, owns project-scoped local infrastructure and runtime diagnostics.

Ref is an independent third-party service. It requires its own account and API key, and usage or credits may be subject to Ref's current terms. Signoff must never collect, proxy, print, log, or commit the Ref API key.

## 1. Inspect the current harness

Detect the active coding harnesses and their global MCP configuration before changing anything. Preserve every existing MCP server and unrelated setting. Do not create project-local configuration when the user asked for a global installation.

Look for an existing Ref Context server named `ref` or `ref-context` before adding another entry. Reuse a working entry instead of creating a duplicate.

## 2. Register Ref Plans first

Register a global remote Streamable HTTP MCP server named `ref-plan`:

- URL: https://api.plan.ref.tools/mcp
- Header: `x-ref-api-key: <REF_API_KEY>`

Prefer the harness's environment-backed header or secret store. If the harness can only persist a static custom header, restrict the configuration file to the current user and do not echo its contents.

For Codex, the equivalent global `~/.codex/config.toml` entry is:

```toml
[mcp_servers.ref-plan]
url = "https://api.plan.ref.tools/mcp"
env_http_headers = { "x-ref-api-key" = "REF_API_KEY" }
```

Use the user's existing `REF_API_KEY` environment value when available. Otherwise ask the user to create or retrieve a key from Ref and configure it through the harness's supported secret mechanism. Never invent or display a key.

## 3. Offer Ref Context separately

When the user wants public or private documentation search in the MCP client, register a global server named `ref` or `ref-context`:

- URL: https://api.ref.tools/mcp
- Header: `x-ref-api-key: <REF_API_KEY>`

For Codex:

```toml
[mcp_servers.ref]
url = "https://api.ref.tools/mcp"
env_http_headers = { "x-ref-api-key" = "REF_API_KEY" }
```

Do not make Ref Context a prerequisite for Ref Plans or Signoff.

## 4. Preserve the project workflow boundary

Add this short guidance to the project instruction file only when the project benefits from persistent implementation planning:

```markdown
Use Ref Plans for substantial collaborative implementation planning, plan comments, agent handoff, and pull request progress. Use Ref Context when current documentation search is needed. Do not create Ref plans for trivial work or copy secrets, raw provider payloads, or unredacted WorkerBee logs into Ref.

For new or changed user-facing behavior, bug fixes, releases, or QA requests, call Signoff whoami first and follow its live contract. Signoff remains the source of truth for build-pinned checks, real-product evidence, and verdicts. Ref progress and WorkerBee health are supporting context and never earn a Signoff verdict.
```

Preserve existing project instructions and avoid duplicating an equivalent Ref trigger.

## 5. Verify without mutating user plans

1. Start a fresh session in each configured harness so it reloads MCP tools.
2. Confirm `ref-plan` is enabled and its tool catalog loads.
3. Call the Ref Plans list tool with a limit of one only, without printing plan titles, IDs, metadata, or content in setup logs.
4. If Ref Context was installed, run one bounded documentation search and do not reproduce private results in the setup report.
5. Do not create, edit, comment on, archive, or link a plan merely to verify installation.

Finish with a redacted report listing the harness configuration files changed, the server names discovered, whether authenticated tool discovery succeeded, and any user action still required.

## Source and ownership

Ref is an independent third-party service maintained by Ref. Signoff provides this optional handoff for teams that want persistent implementation planning alongside evidence-backed product QA.

- Ref: https://ref.tools
- Ref Plans installation: https://docs.ref.tools/plans/install