Skip to content

VladimirGutuev/cross-agent-memory / skills/cross-agent-handoff

cross-agent-handoff

Verified

Transfer 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.

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
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall