# Handover public knowledge corpus Updated: 2026-08-04 Canonical index: https://handover.sh/ai-index.json Handover is the versioned, inspectable handoff layer where humans and AI agents publish work, review evidence, and continue from the same record. Handover is operated by 44pixels Limited, UK company number 15515395. Entity record: https://handover.sh/about # Public continuation demo A complete no-login demo shows three actors continuing an inventory reporting workflow through Markdown, SQL, JSON, a visual artifact, three revisions, and one resolved review thread. Human view: https://handover.sh/demo Agent manifest: https://handover.sh/demo.json Raw Markdown: https://handover.sh/demo/context.md Raw SQL: https://handover.sh/demo/inventory.sql Evidence JSON: https://handover.sh/demo/evidence.json # Install and connect Generic MCP hosts use a named, scoped Handover service credential. Gatana and other clients explicitly configured with Handover's Google OAuth application can preserve per-user Google identity. Handover does not yet expose first-party dynamic OAuth registration for arbitrary MCP clients. Host-specific setup: https://handover.sh/install Installable Agent Skills catalog: https://skills.handover.sh/ Machine-readable skills index: https://skills.handover.sh/index.json Machine-readable recipes: https://handover.sh/recipes/mcp-hosts.json Copyable MCP memory setup: https://handover.sh/examples/mcp-memory-server-setup.md AI agent governance checklist: https://handover.sh/examples/ai-agent-governance-checklist.md Multi-agent workflow: https://handover.sh/examples/multi-agent-handoff-workflow.md End-to-end reviewed MCP handoff: https://handover.sh/examples/end-to-end-mcp-handoff-workflow.md # Security and trust Handover derives organization access from the authenticated identity and server-side membership rather than a client-provided organization identifier. Agent credentials are named, scoped, and revocable. Revisions are immutable, mentions do not grant access, and public availability requires an explicit publication action. Security model: https://handover.sh/security Security documentation: https://handover.sh/docs/security-and-privacy Privacy policy: https://handover.sh/privacy # Open benchmark The AI Handoff Continuity Benchmark tests whether a model can recover continuation-critical state from a transcript, compressed memory, or structured handoff. The open pilot includes three authored cases, nine prompts per system, a published answer key, and deterministic scoring without an LLM judge. First pilot finding: across OpenAI gpt-5.6-terra and Anthropic claude-sonnet-5, structured handoffs had the highest mean condition score at 79.45. Conversation transcripts scored 76.67 and compressed memory scored 45.00. This is a small authored pilot, not a general model ranking. Schema adherence affected the scores, and one run per system does not estimate variance. Methodology: https://handover.sh/benchmark Dataset: https://handover.sh/benchmark/v1/dataset.json Runner: https://handover.sh/benchmark/v1/run.mjs Machine-readable results: https://handover.sh/benchmark/v1/results/2026-08-04/summary.json Raw responses and reproducibility record: https://handover.sh/benchmark/v1/results/2026-08-04/README.md # Runnable examples Browse and filter: https://handover.sh/examples - Inspect a complete human-agent continuation: Open a no-login demo containing Markdown, SQL, JSON, a visual artifact, three attributable revisions, and a resolved review thread. Hosts: Any model, Human workspace Artifacts: Markdown, SQL, JSON, Images Workflow: Agent handoff URL: https://handover.sh/demo - Continue work across multiple agent hosts: Publish a structured handoff, retrieve it from another host, and append the next revision without losing decisions or ownership. Hosts: Codex, Claude Code, Cursor, Gemini CLI Artifacts: Markdown Workflow: Agent handoff URL: https://handover.sh/examples/multi-agent-handoff-workflow.md - Run a reviewed MCP handoff across separate identities: Publish Markdown, SQL, and JSON, review the exact revision, correct the evidence with optimistic concurrency, resolve the finding, and prove a successor can continue. Hosts: Codex, Claude Code, Cursor, Gemini CLI, Human workspace Artifacts: Markdown, SQL, JSON Workflow: Agent handoff URL: https://handover.sh/examples/end-to-end-mcp-handoff-workflow.md - Connect one MCP context server to three coding agents: Configure Claude Code, Cursor, and Codex with separate named credentials, then prove a second host can retrieve and continue the first host's work. Hosts: Codex, Claude Code, Cursor Artifacts: Markdown, JSON Workflow: Context portability URL: https://handover.sh/examples/mcp-memory-server-setup.md - Preserve unfinished work across coding agents: Separate durable repository instructions from changing task state, checkpoint Git evidence, and give the successor an exact verification sequence. Hosts: Codex, Claude Code, Cursor, Gemini CLI Artifacts: Markdown, Git Workflow: Context portability URL: https://handover.sh/guides/preserve-context-across-ai-coding-agents - Publish and retrieve context from the CLI: Install the Handover command, authenticate once, publish a folder, and pull the same context into another working session. Hosts: Terminal, Codex, Claude Code Artifacts: Markdown, HTML, SQL, Images, Binary Workflow: Context portability URL: https://handover.sh/docs/cli-and-api - Measure whether a successor agent can continue: Compare transcript, compressed-memory, and structured-handoff conditions with a deterministic continuation benchmark. Hosts: Any model Artifacts: JSON, JavaScript Workflow: Evaluation URL: https://handover.sh/benchmark - Run a closed-loop human-agent review: Publish an artifact, anchor actionable feedback, mention or assign an authorized resolver, and link every resolved finding to the corrected revision. Hosts: Human workspace, Agent hosts Artifacts: Markdown, HTML, SQL, Code Workflow: Human review URL: https://handover.sh/examples/human-agent-review-loop.md - Inventory service identities for unattended agents: Document every service agent, credential owner, scope, rotation date, and revocation path in one reusable record. Hosts: Service agents Artifacts: Markdown Workflow: Identity governance URL: https://handover.sh/templates/agent-service-account-inventory - Govern an AI agent from inventory through offboarding: Assign an owner and risk tier, map identity and access, define approval gates, retain evidence, test controls, and revoke the agent cleanly. Hosts: Human workspace, Agent hosts, Service agents Artifacts: Markdown, Tables Workflow: Identity governance URL: https://handover.sh/examples/ai-agent-governance-checklist.md - Move a context bundle through OKF: Export a complete, versioned context bundle and import it into another tool without making Handover the only readable copy. Hosts: Terminal, Custom MCP Artifacts: OKF, TAR, Binary Workflow: Import and export URL: https://handover.sh/docs/imports-and-exports - Migrate a static report library without losing files: Inventory products, folders, HTML entry points, nested assets, owners, audiences, URLs, and publishing clients before a reversible dual-run cutover. Hosts: Human workspace, Agent hosts, Terminal Artifacts: HTML, Markdown, SQL, JSON, Images, Binary Workflow: Import and export URL: https://handover.sh/guides/migrate-static-report-folders-to-shared-ai-context - Build and test an Agent Skill that uses MCP: Package one reliable Handover workflow in SKILL.md, connect it to authenticated MCP capabilities, and test identity, success, denied access, continuity, and revocation. Hosts: Codex, Claude Code, Cursor, VS Code Artifacts: Markdown, SKILL.md Workflow: Agent Skills URL: https://handover.sh/examples/agent-skill-mcp-workflow.md - Install and verify one Agent Skill across four hosts: Install the same Handover skill into Claude Code, Codex, Cursor, or Gemini CLI, then verify discovery, activation, MCP identity, read-back, denied access, and cross-host continuation. Hosts: Codex, Claude Code, Cursor, Gemini CLI Artifacts: Markdown, SKILL.md Workflow: Agent Skills URL: https://handover.sh/examples/cross-host-agent-skill-install.md - Verify a Handover CLI connection before an agent writes: Check the endpoint, authenticated principal, workspace, role, scopes, and a protected context read, then run a two-identity continuation test. Hosts: Terminal, Agent hosts, Service agents Artifacts: Markdown, JSON Workflow: Connection verification URL: https://handover.sh/examples/handover-cli-connection-check.md # Category guides ## How to hand off context between AI agents The reliable way to hand off context between AI agents is to publish a versioned continuation record containing the objective, current state, decisions, evidence, constraints, next action, and owner. The receiving agent should read that record, verify unresolved feedback, and append a new revision instead of reconstructing the task from chat history. ### What is an AI agent handoff? An AI agent handoff is a transfer of responsibility and working state from one authenticated agent or person to another. Framework handoffs often transfer control inside one run; a durable handoff also preserves the work so a different model, tool, or teammate can resume later. ### What information belongs in the handoff record? A useful handoff follows the Handover Continuity Record: seven fields that let the next actor understand both what happened and what should happen next. - Objective: the outcome being pursued and its acceptance criteria. - Current state: what is complete, in progress, blocked, or unverified. - Decisions: choices already made and the reasons behind them. - Evidence: files, queries, outputs, links, and observations supporting the state. - Constraints: permissions, safety rules, deadlines, budgets, and known exclusions. - Next action: the smallest concrete step that moves the work forward. - Ownership: the person or agent responsible for the next action. ### How should the receiving agent continue the work? The receiving agent should search for the canonical record, read its current revision and open annotations, verify assumptions against attached evidence, and continue with optimistic concurrency. That sequence prevents duplicate handoffs and avoids overwriting a revision created by another actor. ### How is a durable handoff different from agent routing? Agent routing chooses which specialist acts next, while a durable handoff preserves enough context for that specialist to resume across sessions and systems. OpenAI's Agents SDK describes in-run delegation; MCP standardizes how hosts connect to servers that provide context and tools. Handover adds the persistent, attributable record between those layers. ### What mistakes make agent handoffs fail? Agent handoffs fail when they pass a transcript without a current state, omit the reason behind decisions, detach claims from evidence, or leave the next action ambiguous. A summary is helpful, but it is not sufficient unless the underlying files and revision history remain inspectable. Canonical: https://handover.sh/guides/how-to-hand-off-context-between-ai-agents ## Shared context vs agent memory Agent memory helps one runtime retain information; shared context gives multiple authorized people and agents an explicit record they can inspect, review, version, and continue. Production systems commonly need both: memory for local continuity and shared context for collaboration, accountability, and portability. ### What is agent memory? Agent memory is information retained by an agent runtime across turns or sessions. It can improve local continuity, but its visibility, lifecycle, authorship, and portability depend on the runtime that stores it. ### What is shared context for AI agents? Shared context is an access-controlled operating record that several authenticated actors can inspect and update. It makes state, evidence, revisions, and feedback visible outside one model session. ### When should a team use shared context instead of memory? Use shared context when work crosses identity, model, tool, or organizational boundaries, or when a human must review the evidence. Use runtime memory for preferences and local conversational continuity that do not need a shared audit trail. - The task may move from Claude, ChatGPT, Gemini, Cursor, or Codex to another tool. - A teammate needs to verify or annotate the work before it continues. - Files, SQL, HTML, images, or reports must travel with the summary. - The company needs authorship, access control, revisions, or retention policy. ### Can MCP provide shared context? MCP provides a standard client-server protocol for context exchange, tools, resources, and notifications. A context platform can expose shared records through MCP, but the protocol itself does not decide how records are versioned, governed, or reviewed. ### How do memory and shared context work together? Keep transient reasoning and preferences in the runtime, then publish durable outcomes and evidence to shared context at meaningful checkpoints. The next agent can retrieve the canonical record through MCP or HTTP and seed its own local working memory from verified state. Canonical: https://handover.sh/guides/shared-context-vs-agent-memory ## AI agent handoff vs memory vs routing Agent routing selects who acts next, agent memory retains information for a runtime or user, and a durable handoff transfers responsibility, verified state, evidence, and next actions across actors or systems. They solve different problems and usually work together: route work inside a run, use memory for local continuity, and publish a durable handoff when work crosses a model, session, person, or organizational boundary. ### What is the difference between handoff, memory, and routing? Routing is an orchestration decision, memory is retained information, and a durable handoff is an accountable transfer of work. Routing answers who should act now. Memory answers what this runtime should remember. A durable handoff answers what another authenticated actor needs to verify and continue later. ### What is the Continuity Boundary Test? The Continuity Boundary Test chooses a pattern by asking whether work stays in the same run, stays in the same runtime, or crosses into another accountable actor or system. Use routing for the run boundary, memory for the runtime boundary, and a durable handoff for an accountability boundary. This prevents teams from treating every persistent state problem as memory. ### When should an agent system use routing? Use routing when a coordinator or peer agent must choose the best specialist during an active workflow. OpenAI's Agents SDK models handoffs as delegation to another agent that takes over the conversation, while manager-style orchestration keeps a central agent in control. Both are execution patterns; neither automatically creates a provider-neutral record another system can resume tomorrow. - The work remains inside one orchestrated run. - The next agent can receive the current conversation or a filtered input. - Tracing the execution is sufficient for operational debugging. - No separate human review or cross-tool continuation is required yet. ### When should an agent system use memory? Use memory for information the same application should recall across turns or sessions, such as user preferences, prior interactions, or thread state. LangGraph distinguishes short-term thread state from long-term information shared across sessions. Memory can improve relevance, but its authorship, review model, portability, and retention policy still depend on the application that stores it. - The information is useful to future runs but is not itself a work product. - The application controls the memory namespace and retention lifecycle. - A compact recall is more useful than preserving every supporting artifact. - The information does not require revision-level approval by another actor. ### When is a durable agent handoff required? Use a durable handoff when responsibility crosses a model, person, tool, session, or company workflow and the receiver must verify what happened. The handoff should preserve the current objective and state alongside immutable files, decisions, unresolved review comments, the next action, and authenticated authorship. - Work moves from Claude to Codex, Gemini, Cursor, ChatGPT, or another host. - A human must inspect SQL, HTML, Markdown, images, or generated reports. - A second agent needs the exact evidence rather than a reconstructed summary. - The team needs access control, revision history, attribution, or retention. ### How should routing, memory, and handoffs work together? Use routing and local memory while work is active, then publish a durable checkpoint at a meaningful boundary. The receiving actor searches for that canonical handoff, verifies its identity and current revision, reads attached evidence and open annotations, and seeds its own working memory before continuing with a new immutable revision. Canonical: https://handover.sh/guides/ai-agent-handoff-vs-memory-vs-routing ## Handover vs HANDOFF.md: when is a file enough? A HANDOFF.md file is often enough for one repository, one visibility boundary, and a small sequential workflow. Use a handover platform when several people or agents need authenticated authorship, immutable revisions, attached evidence, review comments, search, or access policy. The two patterns also work together: keep a concise HANDOFF.md in the repository and publish it with the supporting artifacts at important continuation boundaries. ### What does a HANDOFF.md file do well? A HANDOFF.md file is portable, readable, inexpensive, and easy to keep beside the code it describes. It can summarize the objective, current state, decisions, validation results, unresolved risks, and next action without requiring another service. Git can preserve changes to the file alongside the repository. - One developer or agent controls the repository. - The next actor already has access to the same checkout. - The handoff can inherit the repository's visibility and retention rules. - Sequential updates and Git history provide enough coordination. ### What is the File Sufficiency Test? The File Sufficiency Test asks whether one repository can provide the full continuity boundary. A file is enough when the evidence belongs in one repository, all receivers share the same access boundary, one current writer is sufficient, and Git attribution is adequate. If any answer is no, publish a durable handover that keeps the file but adds identity, access, revisions, review, and retrieval. ### What does research say about structured agent handoffs? A 2026 takeover study evaluated 724 runs per successor model across repository-only, raw-trace, summary-note, and structured-note handoff views. Context-bearing handoffs reduced median agent events by 20–59% and cumulative prompt tokens by 42–63% relative to repository-only takeover. The efficiency gains were consistent, while solved-rate effects were smaller and model-dependent. - Repository state alone does not preserve predecessor intent, attempted work, or failure evidence. - Raw traces reduced rediscovery but carried much larger initial prompts. - Summary and structured notes provided bounded alternatives to an unfiltered trace. - The study measures takeover efficiency; it does not prove that any specific product improves correctness. ### Is a repository instruction file the same as a handoff? No. Files such as AGENTS.md and CLAUDE.md primarily describe stable repository rules, while a handoff describes the changing state of interrupted work. A separate 2026 controlled study of 288 runs found no measurable correctness improvement from repository context-file strategy across the tested Claude Code and Codex tasks. Instructions can reduce rediscovery or improve compliance without supplying the implementation skill needed to solve a task. ### When should a team move beyond HANDOFF.md? Move beyond a standalone file when work leaves the repository or becomes a shared operational record. The trigger is not file size; it is the need for an accountable continuation boundary that the repository alone cannot enforce. - A person must review a specific HTML report, image, SQL file, or slide deck. - Multiple agents need separate credentials and attributable actions. - A company must isolate workspaces or grant access to selected users. - Comments must remain anchored to exact artifact ranges across revisions. - Another model or host must find and retrieve the current record through MCP. - Retention, archival, export, or audit requirements extend beyond one repository. ### What is the practical hybrid workflow? Keep the low-friction file and add the platform only at a meaningful boundary. Generate or update HANDOFF.md during local work, commit it when repository history matters, then publish that file with the exact supporting artifacts before another person, model, tool, or team takes responsibility. Canonical: https://handover.sh/guides/handover-vs-handoff-md ## Human-in-the-loop review for AI agent output A reliable human-in-the-loop review workflow preserves the exact AI-generated artifact, anchors each finding to the revision and selected evidence, assigns an authorized resolver, and requires a later immutable revision before the finding is closed. The agent reads open annotations before continuing, and the human can verify which revision addressed each comment. ### What is human-in-the-loop review for an AI agent? Human-in-the-loop review is a control in which an identified person inspects an agent's proposed output or action and can request changes, approve progression, or stop the workflow. For durable work products, the review should preserve what the person actually saw, the evidence behind it, the requested correction, and the actor who responded. ### What should a human reviewer check first? The reviewer should confirm the objective, evidence, assumptions, and acceptance criteria before polishing wording. A fluent output can still be wrong, unsupported, incomplete, or outside the task's permissions. ### How should feedback be anchored? Feedback should identify one immutable revision and artifact, preserve the selected quote or code range, and include enough surrounding context to survive later revisions. That anchor makes the review legible to both the original author and another agent. ### What makes an annotation actionable for an agent? An actionable annotation states the problem, expected change, and evidence or constraint the agent must use. Mentions can notify an owner, but they should never widen access to the underlying handover. - Name the claim, line, or decision that needs attention. - Explain why it is incomplete, risky, or inconsistent. - Specify the expected correction or verification step. - Assign an owner when the next actor is known. ### How does an agent close the review loop? The agent retrieves open annotations, publishes a new revision without mutating the reviewed artifact, and resolves only the threads the new revision actually addresses. The resolution should reference that revision so a reviewer can verify the correction. ### What is the difference between feedback and approval? Artifact feedback identifies a finding and requested change; runtime approval authorizes a proposed action. Permissions, destructive-action gates, and tool-call approval belong in the client, policy engine, or access layer. Comments preserve review work and evidence, but they should never be treated as authorization to execute a consequential action. ### How do you test that the review loop really closed? Inspect the original revision, open finding, corrected revision, and resolution link as separate records. The test passes only when authorship is attributable, the correction is visible in a later revision, resolved findings name that revision, unresolved findings remain open, and mentions or assignments did not widen access. - The original artifact remains inspectable. - The corrected artifact has a later immutable revision ID. - The review and resolution actions show authenticated identities. - Every resolved annotation links to the revision that addressed it. - A second reviewer can reproduce the evidence behind the correction. Canonical: https://handover.sh/guides/human-review-of-ai-agent-output ## End-to-end MCP agent handoff: publish, review, correct, and continue An end-to-end MCP agent handoff has ten observable checkpoints: verify the publishing identity, search before creating, publish the source files, read the result back, verify a separate reviewing identity, retrieve the exact revision and artifacts, annotate the evidence, publish a correction with expectedRevisionId, resolve the finding against that correction, and let a successor continue from the new canonical revision. The handoff is not complete merely because the first tool call succeeded. ### What proves an MCP agent handoff worked end to end? A complete test proves connectivity, workflow completion, and continuity as separate properties. Connectivity proves the host can call the server. Workflow completion proves an authenticated actor created a retrievable revision with intact source artifacts. Continuity proves a different authenticated actor can inspect that revision, contribute attributable review or work, and leave the record ready for the next actor. - The server resolves each person or service agent independently. - The publisher preserves Markdown, SQL, and JSON as original artifacts. - The reviewer reads the exact immutable revision before commenting. - The correction becomes a later revision instead of replacing the reviewed file. - The resolved annotation links to the revision that addressed it. - A successor retrieves the latest canonical revision without the original chat. ### What is the complete MCP tool sequence? Use ten explicit checkpoints and save the returned identifiers at each write boundary. Search before create prevents duplicate records, read-back proves artifact integrity, and expectedRevisionId prevents one collaborator from silently overwriting another. ### Why should the workflow publish files instead of only a summary? A summary helps discovery, but the next actor needs the original evidence to verify and continue the work. Publish the operating brief in Markdown, executable analysis in SQL or code, and structured claims in JSON so each artifact remains inspectable, downloadable, and independently usable. - context.md records objective, state, decisions, constraints, and next action. - query.sql preserves executable analysis instead of paraphrasing it. - evidence.json gives agents structured claims, provenance, and verification state. - Credentials, hidden reasoning, and unrelated personal data never belong in an artifact. ### How does review stay attached to the evidence? The reviewer first reads the immutable artifact, then creates an annotation containing the handover ID, artifact ID, revision ID, exact selected text, surrounding context, and actionable feedback. Mentions and assignments can notify authorized collaborators, but they do not grant access or approve consequential actions. ### How is the correction verified and resolved? The resolver rereads the current revision, publishes corrected artifacts with that revision as expectedRevisionId, and receives a new immutable revision. The reviewer then reads the corrected file and resolves the annotation with resolvedRevisionId set to that new revision. Resolution is evidence about a completed correction, not a substitute for publishing one. - Do not resolve against the original revision. - Do not resolve before reading the corrected artifact. - Keep unrelated findings open. - Record what changed in the continuation note and brief. ### Which failure paths must the test include? A production test should deliberately exercise authorization and concurrency failures. A principal outside the workspace must be unable to retrieve the record, and a continuation using an obsolete expectedRevisionId must return a revision conflict. Those failures prove that continuity does not weaken access control or overwrite protection. - Denied identity: search or get does not reveal protected context. - Read-only identity: retrieval succeeds but create, annotate, or continue is refused. - Stale revision: continue fails and the actor must reread before retrying. - Revoked credential: subsequent protected calls fail without exposing the credential. ### What are the pass criteria? The workflow passes only when all actors are server-attributed, all source files round-trip intact, every revision is immutable, the review remains anchored to the reviewed revision, the correction is a later revision, resolution names that correction, the successor can state the objective and next action without the original conversation, and denied or stale operations fail as designed. Canonical: https://handover.sh/guides/end-to-end-mcp-agent-handoff ## A practical MCP workflow for multi-agent collaboration A practical MCP workflow gives every authenticated agent access to the same canonical handoff while keeping each revision attributable. The first agent publishes objective, state, evidence, constraints, and next action; the next agent searches and reads that record, checks open annotations, then continues it with optimistic concurrency instead of starting a disconnected copy. ### How does MCP help multiple agents collaborate? MCP standardizes how an AI host discovers and calls tools from a server. Handover uses that connection to expose durable search, read, create, continue, and annotation operations, so agents in different hosts can act on one versioned record rather than exchanging pasted transcripts. ### What is the minimum multi-agent workflow? Use six explicit checkpoints. Each checkpoint is observable to a person and reproducible by another agent. ### How do agents avoid overwriting each other? The receiving agent reads the current revision identifier and includes it as expectedRevisionId when continuing. If another actor published first, the stale write is rejected and the agent must reread before trying again. Omitted artifacts are inherited, so a continuation can add evidence without silently deleting prior files. ### How is authorship preserved? Every person uses their own sign-in and every unattended agent uses a named, scoped service credential. Authorship comes from the credential accepted by Handover, never from a user-supplied author field. This keeps the revision timeline useful for review and incident analysis. ### What should the prompt tell each agent? Tell the agent to treat Handover as the canonical continuation layer: search before creating, read the current revision and annotations before writing, attach evidence rather than paraphrasing it away, and resolve only feedback addressed by the new revision. - Use handover.search before handover.create. - Use handover.get and handover.read_artifact before continuing. - Use handover.annotations to retrieve unresolved human or agent feedback. - Use handover.continue with expectedRevisionId. - Never put a token, password, or private key into an artifact. Canonical: https://handover.sh/guides/mcp-workflow-for-multi-agent-collaboration ## Move context between Claude, ChatGPT, Gemini, Cursor, and Codex To move context between Claude, ChatGPT, Gemini, Cursor, and Codex, publish the work as a provider-neutral handoff, then connect each supported host to the same Handover MCP endpoint or retrieve the record through the CLI. The models do not share hidden memory; they continue from the same explicit objective, state, evidence, constraints, and next action. ### Can AI models share the same conversation memory? No. Each provider controls its own conversation and memory systems. Portability comes from moving durable task state into a neutral record that authorized hosts can retrieve, not from attempting to synchronize private chain-of-thought or proprietary memory. ### What is the provider-neutral workflow? Publish a checkpoint before changing tools. Include the acceptance criteria, completed work, evidence, unresolved decisions, constraints, and the exact next action. In the new host, ask the agent to search Handover, read the current record and artifacts, and continue it rather than creating a parallel version. ### How does connection setup differ by host? Codex, Claude Code, Gemini CLI, and Cursor each have their own MCP configuration surface. ChatGPT web uses its connector or plugin experience and does not read a local Codex configuration file. The Handover endpoint and credential stay the same, but the host-specific setup does not. - Codex uses its MCP configuration and supports remote streamable HTTP servers. - Claude Code can add a remote HTTP server with claude mcp add. - Gemini CLI can add a remote HTTP server with gemini mcp add or settings.json. - Cursor uses its MCP configuration in the IDE or cursor-agent CLI. - ChatGPT web uses an installed connector or plugin rather than local CLI configuration. ### What should move and what should stay private? Move the information needed to verify and continue the work: decisions, outputs, source files, constraints, and next steps. Do not move hidden reasoning, unrelated chat history, credentials, or personal information that the next actor does not need. ### How do you verify the handoff worked? Ask the receiving agent to state the objective, current revision, unresolved feedback, and next action before it writes. If those fields match the canonical record and the agent can read attached evidence, the transfer is ready to continue. Canonical: https://handover.sh/guides/move-context-between-claude-chatgpt-gemini-cursor-codex ## What belongs in an AI agent handoff record? An AI agent handoff record should contain seven things: objective, current state, decisions, evidence, constraints, next action, and ownership. It should also preserve attached files and unresolved review comments. It should not contain secrets, unrelated transcripts, hidden reasoning, or claims that cannot be traced to evidence. ### What are the seven required fields? The Handover Continuity Record is intentionally compact enough to complete at every meaningful checkpoint and explicit enough for a different actor to resume. - Objective: desired outcome and acceptance criteria. - Current state: complete, in progress, blocked, and unverified work. - Decisions: choices already made with concise rationale. - Evidence: files, queries, outputs, links, and observations. - Constraints: permissions, safety rules, deadlines, budgets, and exclusions. - Next action: the smallest concrete continuation step. - Ownership: the person or agent responsible for that step. ### What supporting material should be attached? Attach the source material needed to verify the state instead of flattening it into prose. Handover records can carry Markdown, HTML, SQL, source code, JSON, images, and other artifacts as immutable revision files. ### What should never be included? Do not include passwords, API tokens, private keys, session cookies, unnecessary personal data, or hidden chain-of-thought. Refer to secrets by their approved environment-variable or secret-manager name, and include only reasoning summaries needed to justify a decision. ### How detailed should the record be? Use the minimum detail that lets a new actor reproduce the important conclusions and take the next action without asking the original author to reconstruct the task. Link or attach deep evidence; keep the top-level record oriented around continuation. ### How do you know a handoff is complete? A handoff is complete when a receiving actor can state what success means, what changed, what remains uncertain, where the evidence lives, what constraints apply, and what to do next. The downloadable checklist provides a fast review before publishing. Canonical: https://handover.sh/guides/what-belongs-in-ai-agent-handoff ## A shared workspace for humans and AI agents A shared workspace for humans and AI agents should store durable work as access-controlled, versioned records rather than as one global chat or memory pool. Every record needs a clear company boundary, workspace scope, revision history, attached evidence, named author, review state, and explicit visibility so authorized people and service identities can continue the work safely. ### What does a shared human-agent workspace contain? A shared human-agent workspace contains canonical context records, their immutable revisions, supporting files, annotations, and ownership metadata. It is a collaboration layer for inspectable work, not a replacement for each model's private working memory. - Spaces separate products, departments, clients, or other durable areas of responsibility. - Folders organize related handovers without changing their access rules. - Handovers preserve objective, state, decisions, evidence, constraints, and next action. - Annotations keep human and agent feedback attached to the exact artifact and revision reviewed. ### How should company context be separated? Company context should be tenant-isolated by default, then narrowed through workspace membership and record visibility. A user or service identity must be authorized inside the company before it can discover private records; a mention, copied URL, or matching email address must never bypass that boundary. ### How do people and agents keep distinct identities? Interactive people should authenticate with their own SSO identity, while unattended agents should use named, single-purpose service credentials. The platform should derive authorship from the accepted credential, record every revision under that principal, and avoid accepting a caller-supplied author name. ### What should be searchable across the workspace? Authorized actors should be able to search titles, summaries, artifact names, structured context, and assigned annotations across the scopes they can access. Search results must preserve the same authorization checks as direct reads so indexing does not become a side channel. ### When should context be public or externally shared? Context should become public or externally shared only through an explicit visibility change made by an authorized owner. Public links need a deliberate publication surface, while restricted collaboration should grant a named person or group the minimum required role without exposing the rest of the company workspace. ### What is the minimum governance checklist? A production workspace needs tenant isolation, least-privilege roles, named machine identities, immutable revision history, audit events, retention controls, and a tested offboarding path. Those controls should apply equally whether the caller uses the web interface, API, CLI, or MCP. Canonical: https://handover.sh/guides/shared-workspace-for-humans-and-ai-agents ## Service accounts for AI agents A service account for an AI agent is a non-human identity used by one unattended agent or automation. It should be named for a single purpose, scoped to the minimum workspaces and actions required, stored outside prompts and artifacts, rotated or revoked independently, and recorded as the author of every action it performs. ### Why does an AI agent need its own service account? An AI agent needs its own service account so its work is attributable and its access can be changed without affecting a human user. Sharing one person's token or one global agent key obscures which automation acted and increases the impact of credential leakage. ### How should an agent service account be scoped? Scope the identity to one agent, one operational purpose, and the smallest set of workspaces and actions it needs. Separate read-only retrieval from publishing or administration when those functions have different risk, and do not grant company-wide access merely because setup is easier. - Name the agent, owner, purpose, environment, and expiry or review date. - Grant only the spaces and operations required by the workflow. - Keep production and test agents on separate credentials. - Review recent use before rotating, disabling, or deleting the identity. ### Where should the credential be stored? Store the credential in the host's secret store, environment, or managed workload identity system. Never place it in a prompt, handover artifact, repository, chat transcript, screenshot, or copied MCP configuration that may be shared. ### How does service-account access work with MCP? A remote MCP server can use OAuth for interactive people and a bearer credential for unattended service identities. The server must validate the token for its own resource, map it to a principal and scopes, and enforce the same authorization rules on every tool call. ### How should agent actions be audited? Audit records should include the service identity, operation, target workspace or record, timestamp, result, and resulting revision. A service identity should not be able to override authorship with a request field, because caller-controlled attribution makes the audit trail unreliable. ### How should a service account be retired? Disable the identity first, verify that no workflow still depends on it, then revoke or delete the credential after a defined observation period. Preserve historical authorship so old revisions continue to identify which agent created them. Canonical: https://handover.sh/guides/service-accounts-for-ai-agents ## MCP OAuth vs service accounts for AI agents Use OAuth when an interactive person is connecting an MCP client and should approve access under their own identity. Use a named service account when an unattended agent, scheduled job, or shared automation needs stable non-human access. Both approaches should produce a distinct principal, narrow scopes, revocable credentials, and server-side authorship; a person's copied access token should never become an agent identity. ### What is the difference between MCP OAuth and a service account? OAuth delegates access from an interactive resource owner to an MCP client after a browser-based authorization flow. A service account is a non-human identity provisioned for one agent or automation and authenticated with a credential stored by that runtime. OAuth answers which person approved this client; a service account answers which automation performed this work. ### When should an MCP client use OAuth? Use OAuth when a person is present to sign in, review the requested access, and have tool calls attributed to their own account. The MCP authorization specification uses protected-resource metadata to help clients discover the authorization server, then an OAuth 2.1 flow issues tokens intended for that MCP resource. - A person is adding a remote MCP server to their own client. - The product must preserve the person's existing organization membership and permissions. - Each employee should be distinguishable without sharing credentials. - The client supports the server's registration and browser authorization flow. ### When should an agent use a service account? Use a service account when no person is available to complete an interactive flow for each run, or when the automation must remain operational independently of an employee account. Create one identity per agent or profile so access, authorship, rotation, and revocation remain independent. - Scheduled research, reporting, synchronization, or monitoring. - A shared company agent running outside one employee's session. - CI, background jobs, and server-side agent orchestration. - MCP hosts that cannot complete the server's supported OAuth client-registration flow. ### Why is copying a human token into an agent unsafe? A copied human token makes unattended work appear to come from that person, inherits permissions intended for their interactive account, and may remain embedded in configuration after their role changes. It also prevents an operator from revoking the agent without disrupting the employee. ### What does a standards-based MCP OAuth flow require? A protected MCP server advertises protected-resource metadata and the location of an OAuth authorization server. The authorization server publishes discovery metadata and supports an accepted client-registration approach. Public clients use authorization code with PKCE, tokens are sent in the Authorization header, and the resource server validates issuer, audience, expiry, and scopes on every request. ### How should a company support both identity types? Keep human and agent principals in the same authorization model but label their type explicitly. Apply organization, workspace, and operation scopes to both; derive authorship from the authenticated principal; expose recent use and revocation controls; and never allow a request body to choose its own author. ### Which authentication path does Handover support? Handover supports named, scoped service identities for generic MCP hosts today. Gatana and other clients explicitly configured with Handover's Google OAuth application can use per-user Google attribution. Handover is adapting the first-party OAuth authorization-server pattern proven in Clara MCP so arbitrary compatible hosts can open a browser, register securely, and preserve the signed-in human identity. Canonical: https://handover.sh/guides/mcp-oauth-vs-service-accounts ## How to version and review AI-generated reports Version AI-generated reports by storing every published output as an immutable revision with a named author, timestamp, source evidence, change summary, and review state. Human or agent comments should remain anchored to the exact file and revision reviewed, while corrections are published as a new revision instead of silently replacing the original. ### What should be versioned with an AI-generated report? Version the report together with its input references, queries, code, attached assets, assumptions, and declared limitations. A rendered HTML page without the material that produced it is difficult to verify and expensive for the next agent to continue. ### Why should report revisions be immutable? Immutable revisions preserve what a reviewer actually saw and prevent later edits from rewriting the audit trail. A new correction can supersede the previous revision while retaining the earlier artifact, author, and review discussion. ### How should reviewers comment on report files? A reviewer should anchor each comment to the report revision, artifact, and selected quote or code range, then state the expected change. The thread remains open until a later revision addresses it and records the resolution. - Review factual claims against attached evidence. - Distinguish calculations, assumptions, and model-generated interpretation. - Assign material follow-up work to a named person or agent. - Resolve comments only after the correcting revision is available. ### How should SQL, HTML, Markdown, and assets travel together? Publish related files as one report revision so the rendered output and its working materials share the same version boundary. Keep each artifact downloadable in its original format, provide safe previews where possible, and preserve relative relationships between files. ### What belongs in the report change summary? The change summary should name material additions, removals, corrected claims, refreshed data, unresolved review items, and the next owner. It should explain why the revision exists rather than repeat the report title. ### How can another agent continue the report? The next agent should retrieve the current revision, source artifacts, open annotations, and expected revision identifier before writing. It can then publish a new version that inherits unchanged files, adds new evidence, and links resolved review threads to the correction. Canonical: https://handover.sh/guides/version-and-review-ai-generated-reports ## MCP context server vs vector memory An MCP context server and vector memory solve different problems. MCP standardizes how an AI host discovers and calls tools or retrieves resources; vector memory ranks semantically similar chunks. Use vector search to find relevant material, use an MCP context server to expose governed context and actions across clients, and combine them when agents need both semantic retrieval and an inspectable system of record. ### What is an MCP context server? An MCP context server is a program that exposes context and capabilities to compatible AI applications through the Model Context Protocol. It can provide resources for retrieval, tools for actions, and prompts for reusable workflows while the host controls the connection, permissions, and model interaction. ### What is vector memory? Vector memory stores embeddings for content and retrieves chunks that are semantically similar to a query. A vector store can rank results, apply metadata filters, and return matching text, but it does not by itself define authorship, revision history, review state, write operations, or how different AI hosts connect. ### What is the practical difference? Vector search answers which stored passages are likely to be relevant. An MCP server answers which context and actions an AI client can discover and invoke. One is a retrieval implementation; the other is an interoperability boundary that can expose vector search, exact search, files, version history, annotations, and write operations through one governed interface. - Retrieval: vector memory ranks similar chunks; MCP can expose semantic search, exact search, or direct resource reads. - Actions: an MCP tool can publish, annotate, resolve, or continue work; a vector query normally retrieves data. - Portability: MCP gives compatible hosts a common connection and capability model; a vector store remains an implementation behind an API. - Governance: identity, tenancy, revisions, and approval remain application responsibilities regardless of the vector database used. ### When is vector search enough? Vector search is often enough for read-oriented retrieval over a controlled document collection when approximate semantic matching is the main requirement. It is a good fit for finding passages in manuals, policies, support content, or research notes that do not need a collaborative revision and review workflow. - The corpus has a clear ingestion and deletion policy. - Chunk-level retrieval is more important than preserving a whole work package. - A single application owns authentication, ranking, and user experience. - Retrieved content does not need comments, assignments, or an immutable history. ### When does a team need an MCP context layer? Use an MCP context layer when work must move between AI clients or authenticated actors, or when retrieval is only one step in a larger continuation workflow. The context layer should preserve the canonical artifact, its revision, evidence, ownership, access policy, and unresolved feedback while exposing safe operations to agents. - Claude, ChatGPT, Gemini, Cursor, Codex, or custom agents must reach the same record. - Humans need to inspect and annotate the exact files an agent produced. - Agents must publish new versions without overwriting concurrent work. - The company needs named service identities, workspace isolation, and an audit trail. ### Should MCP and vector memory be combined? Yes, when semantic retrieval improves discovery. Keep the durable record and access policy in the context system, index permitted content for semantic search, then expose retrieval and continuation through MCP. Search results should resolve back to the canonical record and immutable revision rather than becoming detached copies. ### How should a team choose? Start from the workflow rather than the storage technology. If the requirement is only to retrieve related passages, begin with vector search. If another person or agent must verify, update, comment on, or take ownership of the work, add a durable context system and expose it through MCP. Use both when semantic discovery and accountable continuation are required together. Canonical: https://handover.sh/guides/mcp-context-server-vs-vector-memory ## How to preserve context across AI coding agents Preserve context across AI coding agents by separating stable repository instructions from changing task state. Keep conventions and verification commands in the instruction file each host reads, keep the current objective, decisions, evidence, risks, and next action in a HANDOFF.md record, commit code and tests to Git, then publish the handoff with its supporting files when work crosses a model, machine, person, or access boundary. ### What context should survive a coding-agent switch? The successor needs more than a summary of the conversation. It needs the intended outcome, the exact repository state, decisions already made, commands already run, evidence from tests or logs, unresolved risks, and one bounded next action. Preserve pointers to the canonical files instead of copying large source files into prose. - Objective and acceptance criteria. - Branch, commit, worktree, and relevant uncommitted changes. - Files changed and files intentionally left untouched. - Decisions, rejected alternatives, and reasons. - Commands run with material results, including failures. - Known risks, missing verification, and access constraints. - The next command or edit and the actor expected to perform it. ### How are instruction files different from a handoff? Instruction files describe durable repository behavior; a handoff describes the changing state of one interrupted task. Codex discovers layered AGENTS.md files, Claude Code uses CLAUDE.md project memory, Gemini CLI loads hierarchical GEMINI.md context, and Cursor uses project rules while its CLI can also read AGENTS.md and CLAUDE.md. Put stable commands and conventions in those files. Do not rewrite them for every task. ### What is the minimum repository handoff workflow? Before switching agents, make the repository state inspectable, update the handoff record, and run the smallest relevant verification. The receiving agent should independently inspect Git state and active instructions before acting. It should not assume the handoff is newer than the checkout. ### What should the successor verify before editing? The successor should compare the handoff's declared commit and branch with the actual checkout, read the applicable nested instruction files, inspect changed files, reproduce one meaningful result, and check for open review comments. If evidence is stale or the expected revision changed, it should stop and refresh the record instead of writing over concurrent work. - The repository and working directory are the intended ones. - The branch, commit, and worktree match the handoff. - No newer revision or unresolved comment changes the next action. - Secrets, credentials, generated files, and local-only state were not copied. - The stated failure or passing test can still be reproduced. - The proposed next edit respects the nearest instruction file. ### When is HANDOFF.md enough? A committed HANDOFF.md is usually enough for one repository, one visibility boundary, one writer at a time, and a workflow whose evidence already lives in Git. Add a shared handover when work spans machines or repositories, includes files outside Git, needs authenticated authorship, carries human review, has parallel actors, or must remain searchable after branches are deleted. ### How should coding agents use Handover through MCP? Connect each host to the same Handover workspace, then have the sender publish a checkpoint and the successor search, read the exact current revision, retrieve artifacts and open annotations, and continue with the expected revision identifier. The agent identity comes from its authenticated credential; it should never claim authorship through tool input. ### What should never be placed in a handoff? Do not publish reusable credentials, private keys, raw environment files, unnecessary personal data, hidden chain-of-thought, or large generated directories. Record the result and the evidence needed to verify it, not every token produced while reaching it. Keep organization access explicit and use named, scoped service credentials for unattended agents. Canonical: https://handover.sh/guides/preserve-context-across-ai-coding-agents ## Use an MCP memory server with Claude Code, Cursor, and Codex Use an MCP memory server across Claude Code, Cursor, and Codex by connecting every host to the same remote MCP endpoint with a separate named credential, then testing search, read, publish, and continuation as distinct actors. Handover uses https://handover.sh/api/mcp as the endpoint. It preserves canonical files, revisions, annotations, access policy, and authorship rather than storing only an opaque chat summary or a bag of retrieved text chunks. ### What does an MCP memory server preserve? A useful cross-agent memory layer preserves continuation state: the objective, current state, decisions, evidence, constraints, unresolved review, next action, and owner. Handover stores that state as a versioned record with original artifacts. The MCP connection lets each host search, read, annotate, and continue the same record without treating one model conversation as the source of truth. - Stable record identity instead of a new summary in every chat. - Immutable revisions instead of silent replacement. - Markdown, HTML, SQL, JSON, images, and binary evidence. - Human and agent authorship from authenticated identities. - Anchored comments and mentions that remain attached to a revision. - Workspace isolation and explicit public or principal-level sharing. ### What do you need before connecting an agent? Create or join a Handover workspace, then choose an identity for each client. Interactive people should use a supported sign-in flow. Unattended agents and generic MCP hosts should use separate named service credentials created under Company > Agents. Store the credential in an environment variable and never commit it to an MCP configuration file. ### How do you connect Handover to Claude Code? Add Handover as a user-scoped remote HTTP server so it is available across Claude Code projects. Claude Code supports remote HTTP MCP servers, custom headers, and environment-variable expansion. After adding the server, inspect its status and ask Claude Code to identify the authenticated Handover actor before reading or writing context. ### How do you connect Handover to Cursor? Add Handover to ~/.cursor/mcp.json for a global connection or .cursor/mcp.json for one project. Cursor supports remote Streamable HTTP servers and project or global MCP configuration. Keep the token in the environment, open Cursor's MCP settings to confirm the server is enabled, and leave tool approval on while validating the connection. ### How do you connect Handover to Codex? Register the remote server with Codex and point bearer-token lookup at HANDOVER_TOKEN. This keeps the credential outside the stored server URL. Confirm that the server appears in the MCP list, then ask Codex to call the Handover identity tool before using search or write operations. ### How do you verify cross-agent continuity? Run one small handoff from end to end. Agent A creates a record with a unique marker and one artifact. Agent B searches for that marker, reads the exact artifact and current revision, lists unresolved annotations, and continues the record with the expected revision ID. The test passes only when the second actor can cite the original evidence and the history shows both identities. - Call handover.whoami and confirm the expected workspace and actor. - Create a handover containing a unique test marker and explicit next action. - Search from a second host without pasting the first conversation. - Read the canonical record, artifact, revision ID, and open annotations. - Continue with expectedRevisionId so concurrent updates cannot be overwritten. - Confirm both actors and both revisions in the human workspace. ### Why not use one shared token for every agent? A shared token erases attribution and expands the impact of credential leakage. Use one revocable credential per agent, host profile, or automation boundary, grant only the scopes it needs, and rotate or revoke it independently. MCP security guidance recommends authorization for user-specific data and auditability, and recommends minimizing scopes rather than granting an omnibus permission set. ### How is this different from vector memory? Vector memory ranks semantically similar chunks; it does not by itself preserve a canonical work package, immutable versions, ownership, review threads, or safe write operations. Handover can sit beside vector retrieval: use search to discover relevant material, then resolve results to the governed record and continue it through MCP. Choose vector-only retrieval when passages are enough; choose a context system when another actor must verify or advance the work. Canonical: https://handover.sh/guides/mcp-memory-server-for-claude-code-cursor-codex ## How to migrate static report folders into shared AI context Migrate static report folders by inventorying every collection, entry file, supporting asset, URL, owner, and audience before copying anything. Map broad business areas to Spaces, use folders only for organization, import each report as a stable handover with immutable revisions and original files, verify rendering and hashes, then run the old and new publishing destinations in parallel until human and agent acceptance tests pass. ### What maps from a report library into Handover? Preserve the meaning of the old library without reproducing its storage limitations. A Reporter product or top-level business area becomes a Space. A folder remains an organizational view inside that Space, not an access-control boundary. A report becomes one stable handover whose revisions preserve the files, authorship, evidence, and continuation history. ### What should be inventoried before migration? Capture the source structure and access intent before transforming it. The inventory should be machine-readable and include every report slug, entry file, nested asset, owner, last update, audience, public URL, product, folder membership, and publishing client. Record broken links and missing owners as migration exceptions instead of silently repairing them. - Products, business areas, and product-level files. - Folders, folder membership, and any folder-specific audience rules. - Reports, revisions, owners, timestamps, summaries, and tags. - HTML entry points and every relative CSS, JavaScript, image, or data dependency. - Public and restricted URLs referenced by Slack, documentation, or customers. - MCP clients, service agents, local scripts, and scheduled publishers. - Backlog items, unresolved review, and reports with no active owner. ### How should products, folders, and permissions be separated? Use Spaces for durable company segments such as products, departments, clients, or initiatives. Use folders for navigation and thematic collections within a Space. Translate old allow-lists into Handover visibility and principal grants; do not treat folder membership as authorization. Create restricted Spaces and service identities before importing restricted material. ### How do you preserve HTML reports and slide decks? Import the complete directory without flattening paths or rewriting binary files. Declare the intended entry file, preserve nested relative assets, and compare content hashes before and after transfer. Render representative desktop and mobile reports in an isolated artifact viewer, test in-report navigation, and retain every non-entry file in the artifact navigator so people and agents can inspect the full work package. ### What is the safest cutover sequence? Use a reversible dual-run. Inventory and map first, import in batches, verify the copied material, then let a small group publish and pull through Handover while Reporter remains available. Change the default destination only after the acceptance gate passes. Preserve the source read-only for a defined rollback window instead of deleting it during cutover. - Freeze mapping rules, not source publishing. - Import one representative Space with mixed file types and access levels. - Verify counts, hashes, URLs, rendering, ownership, and search. - Run human sign-in and agent publish-pull tests with separate identities. - Compare new revisions created during the dual-run window. - Switch MCP and automation defaults as a separate, reversible change. - Archive the source only after the rollback window and link audit close. ### What must pass before the old library becomes read-only? The gate should prove both preservation and continuation. Counts alone are insufficient. Every sampled work package must render, download, search, preserve authorship, enforce its intended visibility, and be retrievable by an authorized successor agent. Public links need a redirect or an explicitly communicated replacement. - Inventory totals reconcile or every exception is signed off. - Artifact hashes and nested paths match the source. - HTML, Markdown, SQL, JSON, image, and binary samples render or download correctly. - Restricted, company, and public access tests behave as declared. - A human can annotate a migrated artifact and an agent can retrieve the thread. - An agent can publish, another identity can pull, and a new revision can continue the work. - Rollback restores the previous publishing destination without data loss. ### How should migration history remain auditable? Keep the source system identifier, original slug, source revision, imported timestamp, importer identity, and file hashes as provenance. Migration should create attributable Handover revisions rather than pretending imported work originated in Handover. Record mapping exceptions, redirects, and final cutover approval in a dedicated migration handover. Canonical: https://handover.sh/guides/migrate-static-report-folders-to-shared-ai-context ## An AI agent governance framework for shared company context A practical AI agent governance framework maps every agent to an owner, purpose, identity, data boundary, allowed action set, approval rule, evidence trail, and revocation path. Apply the controls at the same interfaces agents actually use: model hosts, MCP servers, APIs, shared context, and publishing workflows. Review risk continuously from inventory through offboarding, and require attributable records for consequential work. ### What is AI agent governance? AI agent governance is the operating system for deciding which agents may exist, what they may access, which actions they may take, how humans supervise consequential work, and what evidence proves the controls worked. It combines organizational ownership, risk management, identity and access management, review workflows, monitoring, and incident response. A principles document is useful, but it is not governance until the rules are enforced and testable. ### What should an AI agent inventory contain? Inventory each deployed or experimental agent as a governed resource. Give it a stable identifier and record enough context to evaluate its access, lifecycle, and blast radius without reverse-engineering a prompt or repository. - Business owner, technical owner, and review owner. - Purpose, expected outcome, users, and deployment environment. - Models, hosts, MCP servers, APIs, tools, and data sources. - Human identity or named service identity used at every boundary. - Read, write, publish, delete, execute, and administrative capabilities. - Risk tier, approval gates, monitoring signals, and incident contact. - Credential rotation, last review, expiry, disable, and deletion dates. ### How should companies tier AI agent risk? Tier the deployed use case, not the model name. Risk grows with data sensitivity, action reversibility, autonomy, external impact, and the difficulty of detecting a wrong result. A retrieval assistant reading public documents is materially different from an unattended agent that can publish externally, change production data, or approve spending. ### How should identity and access be designed for AI agents? Treat each unattended agent as a distinct non-human principal. Use a single-purpose, revocable identity; grant only the scopes and workspaces required for its current job; derive authorship from the accepted credential; and separate read, create, continue, publish, delete, and administrative permissions. Never let a caller choose its own author identity or company boundary in tool input. - Use per-user OAuth for interactive people when the host supports it. - Use one named service identity per unattended agent or automation boundary. - Keep credentials outside prompts, source code, URLs, and shared configuration. - Bind tokens to their intended resource and validate them on every request. - Apply the same authorization checks to search indexes as direct record reads. - Disable unused identities before deletion and verify that access actually stops. ### Where should human approval be required? Require approval at the point of consequential action, not as a generic chat instruction. The reviewer should see the proposed action, affected resource, evidence, uncertainty, alternatives, and rollback plan. Approval should be attributable, time-bounded, and scoped to that action; it should not silently grant the agent broader future access. - External publication or communication. - Destructive or hard-to-reverse changes. - Production, financial, legal, employment, or customer-impacting actions. - Access to a new sensitive data class or company area. - Privilege elevation, credential creation, or delegation to another agent. - Resolution of a high-severity review finding or policy exception. ### What evidence should an agent leave behind? Keep an attributable continuation record for work another person or agent may need to verify. Preserve the objective, current state, decisions, evidence, constraints, open questions, next action, exact artifacts, model or tool boundary, and review status. Revisions should be immutable so later corrections do not erase what a reviewer originally saw. ### How should AI agent governance be tested? Test controls as workflows, not checkboxes. Use a second identity to confirm isolation, attempt an out-of-scope search and write, exercise approval gates, revoke the credential, and verify the agent can no longer read or act. Then reconstruct one consequential decision from the retained evidence and review history. - Authorization test: denied scopes and workspaces remain undiscoverable. - Attribution test: every revision and comment names the authenticated principal. - Continuity test: a successor recovers the exact state without the original chat. - Approval test: gated actions cannot execute before the named approval. - Revocation test: a disabled credential fails immediately across API, CLI, and MCP. - Recovery test: the owner can stop the agent and resume from the last trusted state. ### What should happen when an AI agent is retired? Offboarding should disable the identity first, preserve records needed for audit or continuation, transfer ownership of active work, remove secrets and scheduled jobs, and only then delete the identity after the retention window. Reusing the same credential for a replacement agent destroys attribution and can silently inherit excessive access. Canonical: https://handover.sh/guides/ai-agent-governance-framework ## How Agent Skills and MCP work together Agent Skills and MCP solve different layers of an agent workflow. A SKILL.md packages procedural knowledge: when to activate, which sequence to follow, what evidence to preserve, and how to verify success. MCP provides runtime capabilities: authenticated tools, resources, and data. A dependable integration uses the skill to orchestrate MCP calls, derives identity and access from the MCP connection, handles denied access explicitly, and verifies the resulting record. ### What is the difference between Agent Skills and MCP? An Agent Skill is a portable instruction package, normally a folder with a SKILL.md file and optional scripts, references, or assets. It tells an agent how to perform a repeatable task and loads progressively when the task matches. MCP is a protocol for connecting a model host to external tools, resources, and prompts. A skill can teach the workflow for using MCP, but it should not duplicate the server, carry credentials, or make authorization decisions. ### When should an MCP server ship an Agent Skill? Ship a skill when correct use requires more than choosing one obvious tool. A skill is valuable when the agent must select among several operations, preserve a domain-specific record, respect an ordering constraint, recover from stale state, or verify a result. Keep simple tool descriptions in the MCP schema; reserve a skill for reusable procedure and judgment. - Several MCP calls must happen in a dependable order. - The agent must inspect current state before writing. - The workflow has a success test and a meaningful denied path. - Users repeat the same task across multiple compatible agent hosts. - The procedure benefits from examples, checklists, or reference material. - The skill can remain useful while the MCP server enforces all permissions. ### What belongs in a SKILL.md for an MCP workflow? Write a narrow activation description, state the required MCP server and access, verify the active identity before protected actions, define the smallest reliable call sequence, and finish with an observable verification step. Keep detailed API schemas on the server or in focused references rather than copying a large tool catalog into the skill. - A lowercase name matching the skill folder. - A description that names both the capability and trigger phrases. - Compatibility requirements such as the MCP server, CLI, or network access. - Identity and scope verification before the first write. - Expected outputs, preserved evidence, and failure behavior. - A denied-access rule that stops instead of searching for a bypass. - A final read-back or test proving the operation succeeded. ### How do you build an Agent Skill around Handover MCP? Create one focused skill, connect the host to Handover MCP, and test it with two named identities. The skill should call handover.whoami, resolve the canonical record, read the current revision and required artifacts, perform one bounded workflow, and read the result back. Handover derives authorship, company, workspace, and access from the authenticated principal rather than accepting those values from skill text. ### How should Agent Skills handle identity and security? Treat skill source as operational code even when it is only Markdown. A skill can influence which tools an agent calls and what data it sends, so keep credentials outside the skill, inspect third-party source, declare requirements, and grant the connected principal only the access the workflow needs. The MCP server must remain the authority for authentication and authorization. - Never place bearer tokens, API keys, or copied sessions in SKILL.md. - Never let prompt content choose the author, organization, role, or scope. - Default publication and sharing to private unless the person explicitly changes it. - Do not retry denied access with another identity or infer hidden records. - Test with the smallest role and revoke the credential after the test. - Keep publisher provenance and complete source visible before installation. ### How do you test an Agent Skill and MCP integration end to end? Use a fresh session and test behavior rather than only validating frontmatter. Confirm activation from a natural-language request, verify the intended identity, run the workflow, inspect the exact resulting artifact or revision, and repeat one denied or stale-state path. Then start a second compatible host and prove it can retrieve the same canonical result without receiving the first chat. - Format test: validate the skill against the Agent Skills specification. - Discovery test: confirm the installer finds the intended skill and no templates. - Identity test: the server reports the expected person or service agent. - Success test: the expected immutable result exists and is readable. - Boundary test: an out-of-scope read or write remains denied. - Continuity test: another host can retrieve and continue the result. - Revocation test: disabling the credential immediately removes access. ### How do you publish a Handover-compatible Agent Skill? Publish inspectable source with declared compatibility, publisher provenance, and test evidence. Handover's contributor contract requires a successful run, a denied or unavailable path, least-privilege access, authenticated attribution, and private-by-default behavior. Catalog inclusion helps discovery but never widens Handover access or replaces the installer's source review. Canonical: https://handover.sh/guides/agent-skills-and-mcp ## Install Agent Skills in Claude Code, Codex, Cursor, and Gemini CLI Use the open skills CLI to install the same SKILL.md into Claude Code, Codex, Cursor, or Gemini CLI, then verify three separate layers: the installer placed the skill in the host's project scope, the host activates the skill from a matching request, and the authenticated MCP server completes and reads back the intended result. A copied skill file alone does not prove the runtime connection or workflow works. ### What is the shortest cross-agent install path? Inspect the available skills first, then target one host explicitly. Project installation is the safest default because the skill remains visible with the repository and can be reviewed by the team. Add --global only when the workflow should be available in every project for one user. ### Which host name and verification step should I use? The installer supports all four hosts, but host-native discovery is not identical. Claude Code exposes skills through its skills menu and direct /skill-name invocation. Codex exposes /skills and $skill-name. Gemini CLI exposes /skills list and /skills reload. For Cursor, verify the installer record with the skills CLI and then run a natural-language trigger test because its public documentation does not currently describe the same native skills menu. - Claude Code: use --agent claude-code, check /skills, then invoke /handover-publish or ask a matching request. - Codex: use --agent codex, check /skills, then mention $handover-publish or ask a matching request. - Cursor: use --agent cursor, run npx skills list --agent cursor, then ask a matching request and inspect the resulting behavior. - Gemini CLI: use --agent gemini-cli, check /skills list, and use /skills reload after changing an installed skill. - All hosts: inspect the installed SKILL.md before activation because skills can influence tool use and may include scripts. ### Where does the installer place the skill? Project installs use the location each host discovers. In current clean-install tests, Claude Code received .claude/skills/handover-publish while Codex, Cursor, and Gemini CLI received .agents/skills/handover-publish. Native host documentation remains the authority for manual installation paths, precedence, reload behavior, and enterprise controls. ### How do I connect the skill to Handover MCP? A Handover skill teaches the workflow but does not contain credentials or replace the runtime. Connect each host to https://handover.sh/api/mcp using browser OAuth for a person or a scoped service credential for an unattended agent. Then call handover.whoami before the first protected action and confirm the returned person or service agent, company, workspace, role, and scopes. - Use a separate named service identity for each unattended agent. - Keep credentials in the host's secret store or environment, never in SKILL.md. - Derive author, company, workspace, and access from the authenticated connection. - Stop on denied access instead of retrying with another identity. - Keep new context private unless a person explicitly selects broader sharing. ### How do I prove the skill actually works? Run a behavioral test, not only a filesystem check. Start a fresh session, request the skill's outcome in ordinary language, confirm the expected skill activates, verify identity through MCP, publish a uniquely marked handover, and read the exact revision and artifact back. A pass requires the correct authenticated author, workspace, files, access, and canonical link. ### What should I test when using the same skill in another host? Do not transfer the first host's transcript. Give the second host only the canonical link or a search marker, then ask it to retrieve the current revision, state the next action, and continue the record with optimistic concurrency. This proves the durable Handover record, rather than hidden local memory, carries the work across models. - The second host finds the same canonical handover. - It reads the exact current revision and all required artifacts. - Open review comments and assignments remain visible. - A continuation creates a new immutable revision. - Both human or service identities remain separately attributable. - Revoking one credential removes only that principal's access. ### What commonly causes an installed skill to appear broken? Most failures belong to one of three layers: installation, activation, or runtime. First confirm the host-specific skill listing and installed path. Next test whether the skill description matches the request and invoke it explicitly when the host supports that. Finally verify MCP identity and scopes. Reinstalling a skill will not fix an expired credential, denied workspace, or missing MCP connection. - Installed but not listed: reload or restart the host and check the project root. - Listed but not activated: improve the description or invoke the skill explicitly. - Activated but no Handover tools: connect MCP and inspect the host's server status. - Tools available but writes denied: check handover.whoami, role, workspace, and scopes. - Write reported as complete but no record exists: require a final read-back before claiming success. Canonical: https://handover.sh/guides/install-agent-skills-claude-code-codex-cursor-gemini ## How to test an MCP server connection from the CLI A useful MCP connection test must verify more than transport. Check the configured endpoint, resolve the authenticated person or service agent, confirm the intended workspace and scopes, and complete a real read against protected context. With the Handover CLI, `handover doctor` performs those checks without printing the credential or changing any handover. ### What is the fastest way to test the connection? Install the public Handover CLI, authenticate with a named person or service credential, and run the read-only diagnostic. A passing result identifies the API endpoint, principal type, company, workspace, role, scopes, sampled context read, and round-trip time. ### What does a successful diagnostic prove? It proves that the CLI can reach Handover, the credential resolves to an active identity, the identity belongs to a visible workspace, and the API permits at least one protected context-list request. It does not prove write access, broad company access, or that a complete publish-and-resume workflow succeeds. - Endpoint: the normalized Handover API root accepted both requests. - Identity: the server, not prompt content, supplied the actor name and type. - Boundary: company, workspace, role, and scopes match the intended principal. - Read: the identity can perform a protected context request. - Safety: the command is read-only and never includes the credential in output. ### Why is a transport-only check insufficient? An HTTP connection can succeed while the wrong user is active, the credential belongs to another workspace, or required scopes are missing. MCP authorization separates the protected resource from its authorization server and requires clients to discover and use the resource's authorization metadata. Operational verification therefore needs both connectivity and identity-aware access. ### How should an agent use the JSON result? An agent should require `ok: true`, compare the returned workspace and scopes with the task's expected boundary, and stop if they differ. It must not infer authorship from the prompt or silently switch credentials. After the diagnostic passes, the agent should search for a known marker, read one exact revision and artifact, and only then attempt a write if its role permits it. ### What should I do when the check fails? Treat the first failing layer as the diagnosis. A network error points to the URL, DNS, proxy, or service availability. An authentication error points to a missing, expired, or revoked credential. A valid identity in the wrong workspace points to account or configuration selection. A denied read points to role, scope, or sharing policy rather than installation. - Cannot reach endpoint: verify HANDOVER_URL and retry from the same environment as the agent host. - Unauthorized: sign in again or rotate the named service credential. - Wrong identity: remove the saved connection with `handover logout`, then authenticate explicitly. - Wrong workspace or scopes: correct membership or service-agent grants instead of reusing a more privileged token. - Read denied: inspect Handover sharing and access policy; do not treat a broader credential as a workaround. ### How do I prove end-to-end agent continuity after the diagnostic? Use a second authenticated identity and a unique marker. The first actor publishes a private test handover with one artifact. The second authorized actor receives only the canonical link or marker, retrieves the exact revision, states the next action, and appends a new attributable revision with an expected-revision check. That test proves durable continuity rather than local chat memory. Canonical: https://handover.sh/guides/test-mcp-server-connection-cli # Product documentation - What is Handover?: Handover is a shared, versioned context platform where humans and AI agents can publish work, review it, and continue from the same record. https://handover.sh/docs/what-is-handover - Connect an AI agent to Handover with MCP: Use Handover's hosted MCP server to let authorized agents search, read, publish, review, and continue shared context. https://handover.sh/docs/mcp-server - Review files with humans and AI agents: Annotate exact text and code in a Handover artifact, mention collaborators, and expose actionable review threads to agents. https://handover.sh/docs/annotations - Organizations, Spaces, and access control: Organize company context by product or business area while keeping personal workspaces and company tenants isolated. https://handover.sh/docs/organizations-and-access - Use the Handover CLI and HTTP API: Publish folders, pull immutable context, automate continuations, and integrate directly through Handover's CLI and OpenAPI contract. https://handover.sh/docs/cli-and-api - Import and export portable context: Bring GitHub folders and signed HTTP payloads into Handover, then export immutable revisions without changing the canonical record. https://handover.sh/docs/imports-and-exports - Migrate from Reporter to Handover: Move Reporter products, folders, reports, and MCP publishing workflows into Handover through a staged, reversible migration. https://handover.sh/docs/reporter-migration - How Handover protects shared context: Understand tenant isolation, Google SSO, service identities, scoped credentials, restricted handovers, and deliberate public publishing. https://handover.sh/docs/security-and-privacy # Reusable templates - AI agent handoff template: A model-neutral continuation record for transferring work between agents, tools, or people. Page: https://handover.sh/templates/agent-handoff Raw: https://handover.sh/templates/agent-handoff.md - Production incident handoff template: A time-sensitive record for transferring an investigation without losing impact, evidence, or mitigations. Page: https://handover.sh/templates/production-incident-handoff Raw: https://handover.sh/templates/production-incident-handoff.md - Research handover template: A structured record for preserving questions, methods, sources, findings, uncertainty, and follow-up analysis. Page: https://handover.sh/templates/research-handover Raw: https://handover.sh/templates/research-handover.md - Human review checklist for AI agent output: A concise checklist for reviewing evidence, assumptions, access, and follow-up before accepting agent work. Page: https://handover.sh/templates/agent-review-checklist Raw: https://handover.sh/templates/agent-review-checklist.md - AI agent service account inventory: A governance record for every unattended agent identity, its owner, scope, credential location, and review lifecycle. Page: https://handover.sh/templates/agent-service-account-inventory Raw: https://handover.sh/templates/agent-service-account-inventory.md - AI-generated report review record: A revision-aware review record for generated reports and their supporting files, evidence, comments, and disposition. Page: https://handover.sh/templates/ai-report-review-record Raw: https://handover.sh/templates/ai-report-review-record.md # Product releases Human changelog: https://handover.sh/changelog Agent JSON: https://handover.sh/releases.json RSS: https://handover.sh/feed.xml ## 2026-08-04 — skills.handover.sh is now the home for Handover workflows The Handover Skills catalog now helps people and agents discover official and reviewed community workflows that operate through Handover MCP or the CLI. - Separates portable skill instructions from the authenticated MCP and CLI runtimes that perform the work. - Filters the catalog by MCP or CLI compatibility and searches tools, tasks, publishers, and outcomes. - Preserves publisher provenance, inspectable source, requirements, and compatibility on every listing. - Publishes raw SKILL.md files, index.json, .well-known/skills.json, llms.txt, and a dedicated sitemap for machine discovery. - Adds a release-grade continuity test covering multi-file read-back, revision-anchored review, correction, successor recovery, and negative access paths. - Provides a reviewed contribution path for product, engineering, research, support, and operations workflows. What this means for agents: Agents can discover a workflow, read its raw SKILL.md source, confirm whether it uses MCP or the CLI, act through a server-resolved Handover identity, and qualify continuity beyond a successful connection. Canonical: https://handover.sh/changelog#2026-08-04-skills-for-handover ## 2026-08-04 — Public report links now preview the report Shared public handovers now carry their own title, summary, canonical URL, and revision-derived image into Slack, X, LinkedIn, Discord, and other link previews. - Selects an explicit handover-preview, social, og, cover, or preview image when the published revision contains one. - Falls back to another safe raster artifact and then the Handover brand image. - Supports Open Graph and large Twitter cards for HTML, Markdown, code, image, and other viewable publication entries. - Keeps organization-only publication metadata and artifacts unavailable to anonymous crawlers. What this means for agents: Agents can include a 1200 × 630 handover-preview.png artifact when publishing a public report so shared links communicate the work itself rather than a generic product page. Canonical: https://handover.sh/changelog#2026-08-04-public-report-previews ## 2026-08-04 — One-command connection verification for people and agents Handover can now verify the endpoint, authenticated identity, workspace, role, scopes, and a protected context read before an agent writes. - Added the read-only handover doctor command to the npm and direct-download CLI. - Published the handover-verify Agent Skill with MCP and CLI paths, failure classification, and a two-identity continuity test. - Added a query-focused connection testing guide and raw agent-readable verification checklist. - Kept verification fail-closed: credentials never appear in output, and a transport pass is never reported as a write or continuity pass. What this means for agents: Agents can verify their server-resolved identity and least-privilege boundary, test one protected read, and stop at the first failed layer before attempting protected work. Canonical: https://handover.sh/changelog#2026-08-04-connection-verification ## 2026-08-03 — A public CLI and inspectable discovery surface Handover became installable from npm and discoverable through the official MCP Registry, mcpub, Glama, search engines, and agent-readable indexes. - Published the dependency-free handover-sh CLI with repository provenance and clean install verification. - Added the open AI Handoff Continuity Benchmark, reusable templates, working examples, and source-linked field guides. - Published llms.txt, llms-full.txt, ai-index.json, host recipes, and an MCP discovery manifest. - Automated IndexNow notifications and a weekly audit of every public canonical, social preview, crawler rule, and agent index. What this means for agents: Agents can install a public CLI, inspect the hosted MCP contract, retrieve reusable knowledge assets, and verify Handover's current public capabilities without relying on marketing copy. Canonical: https://handover.sh/changelog#2026-08-03-public-cli-and-discovery ## 2026-08-03 — Revision-anchored review for humans and agents People and agents can comment on the exact text, code, or file revision they reviewed, mention another authorized collaborator, and carry unresolved feedback into the next continuation. - Added anchored annotations for Markdown, code, JSON, and rendered artifact review. - Made annotation threads available in the workspace, full-screen reader, mobile drawer, HTTP API, and MCP. - Added edit, reply, resolve, reopen, and mention workflows without changing immutable revision contents. - Kept mentions access-neutral: a notification never grants permission to the underlying handover. What this means for agents: Authorized agents can read unresolved review threads, add or edit feedback, mention a person or service identity, and resolve a thread after publishing the revision that addresses it. Canonical: https://handover.sh/changelog#2026-08-03-revision-anchored-annotations ## 2026-07-31 — Resumable Reporter migration and clearer revision history Reporter inventories can move into Handover through bounded, resumable batches while preserving folders, publication bundles, file relationships, and the review queue. - Added resumable inventory, bounded retries, batch mappings, and recovery for interrupted Reporter imports. - Preserved Reporter-compatible publishing folders as projections over canonical Handover revisions. - Improved revision timelines with attributable human and agent activity. - Added readable formatting for SQL, scripts, Markdown source, and rendered previews. What this means for agents: Agents can continue imported work through the same canonical MCP tools instead of targeting a separate legacy report store. Canonical: https://handover.sh/changelog#2026-07-31-reporter-migration-and-history ## 2026-07-27 — Private personal workspaces for individual developers A person can use Handover without first creating a company, then move into shared company workflows when collaboration requires it. - Added private personal organizations isolated from every company workspace. - Added clear onboarding paths for individuals, company owners, employees, and service agents. - Added a full-page artifact reader and sign-in return paths for shared private links. - Published the CLI installer and external-user privacy and terms pages. What this means for agents: An individual can issue a named agent credential inside a private workspace and preserve identity across model switches without exposing context to a company. Canonical: https://handover.sh/changelog#2026-07-27-personal-workspaces-and-onboarding ## 2026-07-26 — Company SSO, Spaces, and attributable agent access Company members can join through an approved Google Workspace domain, organize context into Spaces, and give each human or agent an attributable identity. - Added Google SSO through Cloudflare Access and per-user OAuth attribution for supported MCP clients. - Added company naming, approved domains, invitations, membership roles, and a company view. - Added Spaces as logical product, department, or operating-area boundaries inside a company. - Added signed-in account details, logout, workspace selection, and automatic refresh. What this means for agents: Agents authenticate as named service identities or supported human OAuth identities; authorship is derived from the credential rather than supplied in tool arguments. Canonical: https://handover.sh/changelog#2026-07-26-company-sso-and-shared-spaces ## 2026-07-25 — The first versioned handover platform Handover launched on company-owned Cloudflare infrastructure with canonical D1 and R2 storage, MCP and HTTP interfaces, arbitrary artifacts, Spaces, and Reporter-compatible workflows. - Added immutable handover revisions, artifact storage, search, continuation briefs, comments, and lifecycle controls. - Added tenant isolation, scoped service credentials, backup verification, storage cells, and request tracing. - Added Markdown, SQL, HTML, JSON, image, and arbitrary-file publishing. - Added provider-neutral imports, exports, OKF interoperability, and production-safe MCP access. What this means for agents: Agents gained one authenticated interface for finding, reading, publishing, and continuing durable context alongside human collaborators. Canonical: https://handover.sh/changelog#2026-07-25-versioned-handover-foundation