VladimirGutuev/cross-agent-memory / skills/cross-agent-handoff
cross-agent-handoff
VerifiedTransfer unfinished feature work between Claude Code, Codex, Kimi Code, Antigravity, or another coding-agent harness with a verified worktree snapshot. Use only when the user asks to hand off, continue, resume, pause, close, or supersede work in progress, or when the shared-memory index contains an active handoff that clearly matches the current task. Do not invoke for a new unrelated task or ordinary shared-memory recall.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.8 KB |
| agents/openai.yaml | config | 222 B |
| assets/handoff-template.md | markdown | 1.2 KB |
| references/handoff-schema.md | markdown | 3.8 KB |
| scripts/close-handoff.ps1 | script | 7.4 KB |
| scripts/new-handoff.ps1 | script | 8.8 KB |
| scripts/validate-handoffs.ps1 | script | 12.4 KB |
scripts/validate-handoffs.ps1
View on GitHub[CmdletBinding()]
param(
[string]$RepositoryRoot,
[string]$MemoryRoot
)
$ErrorActionPreference = 'Stop'
$script:failures = 0
$script:warnings = 0
function Write-Pass([string]$message) {
Write-Host "[PASS] $message" -ForegroundColor Green
}
function Write-Warn([string]$message) {
$script:warnings += 1
Write-Host "[WARN] $message" -ForegroundColor Yellow
}
function Write-Fail([string]$message) {
$script:failures += 1
Write-Host "[FAIL] $message" -ForegroundColor Red
}
function Join-PathSegments([string]$basePath, [string[]]$segments) {
$result = $basePath
foreach ($segment in $segments) {
$result = Join-Path $result $segment
}
return $result
}
function Get-RelativeDisplayPath([string]$path) {
if ($path.StartsWith($script:resolvedRepositoryRoot, [StringComparison]::OrdinalIgnoreCase)) {
return $path.Substring($script:resolvedRepositoryRoot.Length).TrimStart('\', '/').Replace('\', '/')
}
return $path
}
function Get-FrontMatter([string]$content, [string]$displayPath) {
$match = [regex]::Match(
$content,
'\A---\r?\n(?<frontmatter>.*?)\r?\n---(?:\r?\n|$)',
[System.Text.RegularExpressions.RegexOptions]::Singleline
)
if (-not $match.Success) {
Write-Fail "$displayPath is missing YAML frontmatter"
return $null
}
$metadata = @{}
foreach ($line in ($match.Groups['frontmatter'].Value -split '\r?\n')) {
if ($line -match '^\s*([A-Za-z][A-Za-z0-9_-]*):\s*(.*?)\s*$') {
$key = $Matches[1]
$value = $Matches[2].Trim()
if (
$value.Length -ge 2 -and
(($value.StartsWith("'") -and $value.EndsWith("'")) -or
($value.StartsWith('"') -and $value.EndsWith('"')))
) {
$value = $value.Substring(1, $value.Length - 2)
}
$metadata[$key] = $value
}
}
return $metadata
}
function Test-RequiredMetadata(
[hashtable]$metadata,
[string[]]$requiredFields,
[string]$displayPath
) {
foreach ($field in $requiredFields) {
if (-not $metadata.ContainsKey($field) -or [string]::IsNullOrWhiteSpace($metadata[$field])) {
Write-Fail "$displayPath is missing frontmatter field '$field'"
}
}
}
function Test-HandoffFile(
[System.IO.FileInfo]$file,
[string[]]$allowedStatuses,
[string]$location
) {
$displayPath = Get-RelativeDisplayPath $file.FullName
$content = Get-Content -LiteralPath $file.FullName -Raw -Encoding UTF8
$metadata = Get-FrontMatter $content $displayPath
if (-not $metadata) {
return $null
}
Test-RequiredMetadata $metadata @(
'id',
'status',
'source_agent',
'target_agent',
'created_at',
'updated_at',
'repository',
'worktree',
'branch',
'base_sha',
'head_sha',
'dirty'
) $displayPath
if ($metadata.ContainsKey('id') -and $metadata['id'] -ne $file.BaseName) {
Write-Fail "$displayPath id must match file name '$($file.BaseName)'"
}
if ($metadata.ContainsKey('status') -and $metadata['status'] -notin $allowedStatuses) {
Write-Fail "$displayPath status '$($metadata['status'])' is invalid in $location"
}
foreach ($shaField in @('base_sha', 'head_sha')) {
if ($metadata.ContainsKey($shaField) -and $metadata[$shaField] -notmatch '^[0-9A-Fa-f]{40}$') {
Write-Fail "$displayPath $shaField must be a 40-character Git SHA"
}
}
if ($metadata.ContainsKey('dirty') -and $metadata['dirty'] -notin @('true', 'false')) {
Write-Fail "$displayPath dirty must be true or false"
}
if (
$metadata.ContainsKey('worktree') -and
$metadata['worktree'] -notmatch '^(?:[A-Za-z]:[\\/]|/|\\\\)'
) {
Write-Fail "$displayPath worktree must be an absolute Windows, UNC, or POSIX path"
}
$parsedTimestamps = @{}
foreach ($timestampField in @('created_at', 'updated_at')) {
if (-not $metadata.ContainsKey($timestampField)) {
continue
}
$parsedTimestamp = [DateTimeOffset]::MinValue
$parsed = [DateTimeOffset]::TryParseExact(
$metadata[$timestampField],
'yyyy-MM-ddTHH:mm:ssZ',
[System.Globalization.CultureInfo]::InvariantCulture,
[System.Globalization.DateTimeStyles]::AssumeUniversal,
[ref]$parsedTimestamp
)
if (-not $parsed) {
Write-Fail "$displayPath $timestampField must use UTC YYYY-MM-DDTHH:MM:SSZ"
}
else {
$parsedTimestamps[$timestampField] = $parsedTimestamp
}
}
if (
$parsedTimestamps.ContainsKey('created_at') -and
$parsedTimestamps.ContainsKey('updated_at') -and
$parsedTimestamps['updated_at'] -lt $parsedTimestamps['created_at']
) {
Write-Fail "$displayPath updated_at precedes created_at"
}
$requiredHeadings = @(
'Goal',
'Scope and ownership',
'Completed',
'Changed files',
'Verification evidence',
'Not verified',
'Failed attempts',
'Decisions and assumptions',
'External state and permissions',
'Blockers',
'Next safe action',
'References'
)
foreach ($heading in $requiredHeadings) {
if ($content -notmatch "(?m)^##\s+$([regex]::Escape($heading))\s*$") {
Write-Fail "$displayPath is missing heading '## $heading'"
}
}
if ($content -match 'FILL BEFORE TRANSFER|\bTODO\b') {
Write-Fail "$displayPath still contains unresolved transfer placeholders"
}
if ($metadata.ContainsKey('status') -and $metadata['status'] -eq 'superseded') {
if (
-not $metadata.ContainsKey('superseded_by') -or
[string]::IsNullOrWhiteSpace($metadata['superseded_by'])
) {
Write-Fail "$displayPath must name superseded_by"
}
}
return [pscustomobject]@{
File = $file
Content = $content
Metadata = $metadata
DisplayPath = $displayPath
}
}
if ($RepositoryRoot) {
$script:resolvedRepositoryRoot = (Resolve-Path -LiteralPath $RepositoryRoot).Path
}
else {
$gitRoot = (& git rev-parse --show-toplevel 2>$null | Out-String).Trim()
if ($LASTEXITCODE -ne 0 -or -not $gitRoot) {
throw 'Run this script inside a Git repository or pass -RepositoryRoot.'
}
$script:resolvedRepositoryRoot = (Resolve-Path -LiteralPath $gitRoot).Path
}
if ($MemoryRoot) {
if ([System.IO.Path]::IsPathRooted($MemoryRoot)) {
$resolvedMemoryRoot = [System.IO.Path]::GetFullPath($MemoryRoot)
}
else {
$resolvedMemoryRoot = [System.IO.Path]::GetFullPath(
(Join-Path $script:resolvedRepositoryRoot $MemoryRoot)
)
}
}
else {
$resolvedMemoryRoot = Join-PathSegments $script:resolvedRepositoryRoot @('docs', 'agent-memory')
}
$indexPath = Join-Path $resolvedMemoryRoot 'MEMORY.md'
$activeRoot = Join-PathSegments $resolvedMemoryRoot @('handoffs', 'active')
$archiveRoot = Join-PathSegments $resolvedMemoryRoot @('handoffs', 'archive')
foreach ($requiredPath in @($indexPath, $activeRoot, $archiveRoot)) {
if (Test-Path -LiteralPath $requiredPath) {
Write-Pass "$(Get-RelativeDisplayPath $requiredPath) exists"
}
else {
Write-Fail "$(Get-RelativeDisplayPath $requiredPath) is missing"
}
}
if (-not (Test-Path -LiteralPath $indexPath -PathType Leaf)) {
Write-Host "`nCross-agent handoffs have $script:failures failure(s)." -ForegroundColor Red
exit 1
}
$indexContent = Get-Content -LiteralPath $indexPath -Raw -Encoding UTF8
$indexDisplayPath = Get-RelativeDisplayPath $indexPath
$markerPattern = '(?ms)<!-- cross-agent-handoffs:start -->\s*(?<body>.*?)\s*<!-- cross-agent-handoffs:end -->'
$markerMatches = [regex]::Matches($indexContent, $markerPattern)
if ($markerMatches.Count -ne 1) {
Write-Fail "$indexDisplayPath must contain exactly one active-handoff marker block"
$markerBody = ''
}
else {
$markerBody = $markerMatches[0].Groups['body'].Value
}
$activeFiles = @()
if (Test-Path -LiteralPath $activeRoot -PathType Container) {
$activeFiles = @(Get-ChildItem -LiteralPath $activeRoot -Filter '*.md' -File | Sort-Object Name)
}
$archiveFiles = @()
if (Test-Path -LiteralPath $archiveRoot -PathType Container) {
$archiveFiles = @(Get-ChildItem -LiteralPath $archiveRoot -Filter '*.md' -File | Sort-Object Name)
}
$pointerMatches = [regex]::Matches(
$markerBody,
'\]\((?<path>handoffs/active/(?<id>[0-9]{8}-[0-9]{6}-[a-z0-9]+(?:-[a-z0-9]+)*)\.md)\)'
)
$pointerCounts = @{}
foreach ($pointerMatch in $pointerMatches) {
$pointerId = $pointerMatch.Groups['id'].Value
if ($pointerCounts.ContainsKey($pointerId)) {
$pointerCounts[$pointerId] += 1
}
else {
$pointerCounts[$pointerId] = 1
}
$targetPath = Join-PathSegments $resolvedMemoryRoot ($pointerMatch.Groups['path'].Value -split '/')
if (-not (Test-Path -LiteralPath $targetPath -PathType Leaf)) {
Write-Fail "$indexDisplayPath points to missing active handoff '$pointerId'"
}
}
$hasNonePointer = $markerBody -match '(?m)^\s*-\s+None\.\s*$'
if ($activeFiles.Count -eq 0) {
if (-not $hasNonePointer) {
Write-Fail "$indexDisplayPath must contain '- None.' when there are no active handoffs"
}
if ($pointerMatches.Count -gt 0) {
Write-Fail "$indexDisplayPath contains active pointers but the active directory is empty"
}
}
else {
if ($hasNonePointer) {
Write-Fail "$indexDisplayPath cannot contain '- None.' while active handoffs exist"
}
foreach ($activeFile in $activeFiles) {
if (-not $pointerCounts.ContainsKey($activeFile.BaseName)) {
Write-Fail "$indexDisplayPath does not point to active handoff '$($activeFile.BaseName)'"
}
elseif ($pointerCounts[$activeFile.BaseName] -ne 1) {
Write-Fail "$indexDisplayPath must point to '$($activeFile.BaseName)' exactly once"
}
}
}
if ($markerBody -match 'handoffs/archive/') {
Write-Fail "$indexDisplayPath active-handoff block must not link archived handoffs"
}
$records = @()
foreach ($activeFile in $activeFiles) {
$record = Test-HandoffFile $activeFile @('active', 'paused', 'blocked') 'handoffs/active'
if ($record) {
$records += $record
}
}
foreach ($archiveFile in $archiveFiles) {
$record = Test-HandoffFile $archiveFile @('closed', 'superseded') 'handoffs/archive'
if ($record) {
$records += $record
}
}
$ids = @{}
foreach ($record in $records) {
$id = $record.File.BaseName
if ($ids.ContainsKey($id)) {
Write-Fail "Handoff id '$id' exists more than once"
}
else {
$ids[$id] = $record.DisplayPath
}
}
foreach ($record in $records) {
if (
$record.Metadata.ContainsKey('status') -and
$record.Metadata['status'] -eq 'superseded' -and
$record.Metadata.ContainsKey('superseded_by') -and
-not $ids.ContainsKey($record.Metadata['superseded_by'])
) {
Write-Warn "$($record.DisplayPath) superseded_by target is not present in this memory tree"
}
}
$memoryFiles = @((Get-Item -LiteralPath $indexPath)) + @($activeFiles) + @($archiveFiles)
$secretPatterns = @(
'-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----',
'(?<![A-Za-z0-9])gh[pousr]_[A-Za-z0-9]{20,}',
'(?<![A-Za-z0-9])sk-[A-Za-z0-9_-]{20,}',
'(?<![A-Za-z0-9])xox[baprs]-[A-Za-z0-9-]{20,}'
)
$nativeMemoryPathPatterns = @(
'(?i)[\\/]\.codex[\\/]memories[\\/]',
'(?i)[\\/]\.claude[\\/]projects[\\/][^\r\n]+[\\/]memory(?:[\\/]|$)'
)
foreach ($memoryFile in $memoryFiles) {
$displayPath = Get-RelativeDisplayPath $memoryFile.FullName
$content = Get-Content -LiteralPath $memoryFile.FullName -Raw -Encoding UTF8
foreach ($secretPattern in $secretPatterns) {
if ($content -match $secretPattern) {
Write-Fail "$displayPath appears to contain a credential or private key"
break
}
}
foreach ($nativePathPattern in $nativeMemoryPathPatterns) {
if ($content -match $nativePathPattern) {
Write-Fail "$displayPath contains an absolute client-native memory path"
break
}
}
}
if ($script:failures -gt 0) {
Write-Host "`nCross-agent handoffs have $script:failures failure(s) and $script:warnings warning(s)." -ForegroundColor Red
exit 1
}
Write-Host "`nCross-agent handoffs are valid with $script:warnings warning(s)." -ForegroundColor Green
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |