# v1.0 Migration Guide

`claude-tempo` is now `agent-tempo`. v1.0.0 is a hard-break release — wire-level identifiers (Temporal search attributes, workflow types, workflow IDs, task queues) have been renamed without a backward-compatibility shim. Follow this guide in order; each step is short.

> **Read this fully before starting.** Several steps are irreversible.

## Before you begin

- Audit any work-in-progress sessions you care about (`claude-tempo recall`, conductor history, saved-state slots) and `report` / commit anything important.
- This guide assumes you're running claude-tempo v0.29.x. Older versions may need intermediate upgrades first; see CHANGELOG.

---

## 1. Drain in-flight work

Anything you care about should be reported, merged, or saved to a player-state slot before upgrading. v0.x workflows continue to exist in Temporal history after upgrade but become **unqueryable** by v1.x code — you cannot recall their messages, restore them, or inspect their state.

## 2. Stop all ensembles on every host

```sh
claude-tempo down --all
```

Repeat on every machine where a daemon is running. Verify no daemon remains live:

```sh
claude-tempo daemon status     # should report "not running"
```

## 3. Destroy v0.x workflows (recommended)

For each ensemble you no longer need:

```sh
claude-tempo destroy --ensemble <name> --all
```

Workflows you don't destroy will linger in Temporal history as orphans — harmless, but they accumulate. You can also bulk-destroy via Temporal CLI: `temporal workflow terminate --query 'WorkflowType STARTS_WITH "claude"'`.

## 4. Uninstall claude-tempo, install agent-tempo

```sh
npm uninstall -g claude-tempo
npm install -g agent-tempo
```

If you have a project-local install:

```sh
npm uninstall claude-tempo
npm install agent-tempo --save-dev
```

The final v0.x `claude-tempo` package on npm is a deprecation stub that prints a migration banner and exits — it has no functionality. Don't keep it installed.

## 5. Update `.mcp.json` in every project

Replace the `claude-tempo` server entry with `agent-tempo`. Example:

```jsonc
// before
{
  "mcpServers": {
    "claude-tempo": {
      "command": "claude-tempo-server"
    }
  }
}

// after
{
  "mcpServers": {
    "agent-tempo": {
      "command": "agent-tempo-server"
    }
  }
}
```

Claude Code regenerates tool prefixes from the server name automatically — `mcp__claude-tempo__cue` becomes `mcp__agent-tempo__cue`. Any agent prompts that hardcode tool names will need the prefix updated too.

## 6. Run the filesystem migration

```sh
agent-tempo migrate-from-claude-tempo
```

Copies `~/.claude-tempo/` → `~/.agent-tempo/` (config, lineups, saved state). Idempotent. The legacy directory is left in place as a safety net; you can delete it after a release cycle. On first invocation of any `agent-tempo` command, this runs automatically if it hasn't yet.

Dev profile users: same verb with `--dev` (top-level flag).

## 7. Rename environment variables

Update shell profiles, CI secrets, `.env` files:

| Before | After |
|---|---|
| `CLAUDE_TEMPO_*` | `AGENT_TEMPO_*` |

`TEMPORAL_*` and `COPILOT_BRIDGE_*` env vars are unchanged. The new vars are read **only**; old `CLAUDE_TEMPO_*` vars are silently ignored. Common offenders to check: `CLAUDE_TEMPO_ENSEMBLE`, `CLAUDE_TEMPO_DEFAULT_AGENT`, `CLAUDE_TEMPO_GH_APP_*` in GitHub Actions secrets.

## 8. Register search attributes on your Temporal namespace

**Self-hosted Temporal**: run the following commands once per namespace. The daemon will refuse to boot until these are registered, and its error message includes these exact commands.

```sh
temporal operator search-attribute create --name AgentTempoHostname --type Keyword --namespace default
temporal operator search-attribute create --name AgentTempoGitRoot --type Keyword --namespace default
temporal operator search-attribute create --name AgentTempoEnsemble --type Keyword --namespace default
temporal operator search-attribute create --name AgentTempoPlayerId --type Keyword --namespace default
temporal operator search-attribute create --name AgentTempoPlayerType --type Keyword --namespace default
temporal operator search-attribute create --name AgentTempoIsConductor --type Bool --namespace default
temporal operator search-attribute create --name AgentTempoAttachedHost --type Keyword --namespace default
temporal operator search-attribute create --name AgentTempoAttachmentState --type Keyword --namespace default
temporal operator search-attribute create --name AgentTempoAttachmentId --type Keyword --namespace default
```

Dev profile users substitute `--namespace agent-tempo-dev`.

**Temporal Cloud users**: ops will handle the namespace-level registration before this version is published. No user action.

The old `ClaudeTempo*` SAs remain registered on your namespace — they don't conflict and don't need to be deleted. Cleanup is a follow-up housekeeping task you can do at leisure (or never).

## 9. Recruit fresh ensembles

```sh
agent-tempo up --lineup <your-lineup-name>
```

Lineup YAML files in `examples/ensembles/` and any custom lineups you've saved need no edits — they reference player types, not internal identifiers. If you have custom MCP-tool-name references inside a lineup's startup messages, update the `mcp__claude-tempo__*` prefix to `mcp__agent-tempo__*`.

## 10. Reinstall the GitHub App (if applicable)

Only relevant if your repo uses the `agent-tempo[bot]` GitHub App for PR/issue automation. The App was renamed from `claude-tempo[bot]` as part of the v1.0 rebrand; existing installations migrate automatically (the installation ID is preserved). You'll see the bot account handle update in your repo's settings — no re-permissioning required.

If your CI workflows reference `CLAUDE_TEMPO_GH_APP_*` secrets, rename to `AGENT_TEMPO_GH_APP_*` and re-set the values.

## 11. Expect one-time dashboard state loss

The dashboard's `localStorage` keys (`claudeTempoDebug` etc.) were renamed. Your debug-panel toggle state, view preferences, and any cached pairing tokens are reset. Re-enable what you need via the dashboard settings panel or `?debug=1` URL parameter.

---

## Rollback

A hard break is one-way. If something goes catastrophically wrong, the rollback procedure is:

1. `npm uninstall -g agent-tempo && npm install -g claude-tempo@0.29.1`
2. Move `~/.agent-tempo/` aside; the legacy `~/.claude-tempo/` is untouched by migration so v0.x reads its original state.
3. v0.x workflows in Temporal history are still there. `claude-tempo up` should resume.
4. You'll need to redo step 8 work in reverse if you'd already deleted the old SAs (you weren't asked to).

This rollback path is best-effort and untested in CI — file an issue against `agent-tempo` if you need it and we'll help debug.

## Getting help

Issues: <https://github.com/vinceblank/agent-tempo/issues>
Migration questions: open an issue with label `migration`. We watch that label closely during the v1.0 release window.
