Skip to content

dongshuyan/compass-skills / skills/session-handoff-prompt

session-handoff-prompt

Verified

Create a concise continuation prompt that a fresh agent session can paste in to resume a long or degraded session. Use when the user asks for a handoff prompt, restart prompt, continuation prompt, context transfer, fresh-session resume, or a compact summary for opening a new session. Do not use for ordinary summaries, task-forest maintenance, durable user-profile updates, automatic session creation, code execution, or external publishing.

scripts/smoke_test_handoff.py

View on GitHub
#!/usr/bin/env python3
"""Run representative local smoke tests for session-handoff-prompt."""

from __future__ import annotations

import argparse
import importlib.util
import json
import re
import tempfile
from pathlib import Path
from typing import Any


SAMPLE_PROMPT = """你正在接手一个已经进行过多轮的 agent session。请按以下上下文恢复任务状态;不要重新讨论已定事项。如果当前文件或可验证证据与这里冲突,以当前证据为准,并明确指出冲突。

【工作目录】
<workspace>

【用户目标】
把 session-handoff-prompt 作为 COMPASS 的正式 skill 接入,支持 macOS、Linux、Windows 和主流 agent。

【必须遵守的要求】
- [已验证] 内部说明用英文;交互和输出使用用户语言,默认中文。
- [已验证] 不读取 credential、cookie、浏览器 session 或无关私有日志。

【已确认事实与决策】
- [已验证] task-forest 负责长期任务结构,session-handoff-prompt 负责生成可粘贴到新 session 的续接 prompt。
- [推断] 默认 balanced 模式最符合还原度和简洁性的平衡。

【任务森林状态】
相关长期目标:COMPASS skills ecosystem。
当前任务节点:Add portable session handoff prompt skill。
未完成 todo:run validation and update README。
依赖 / 阻塞:none.
可能未同步之处:task-forest export may be stale; verify workspace before acting.

【已完成】
- 已设计 portable skill structure.
- 已补充 privacy modes and validation scripts.

【未完成 / 待验证】
- 需要运行 py_compile、smoke test、secret/path scan 和 manifest validation.

【关键文件 / 命令 / 产物】
- skills/session-handoff-prompt/SKILL.md
- skills/session-handoff-prompt/scripts/smoke_test_handoff.py

【不要重复 / 不要做】
- 不要自动创建新 agent session。
- 不要修改 task-forest。

【下一步】
1. 更新 README 和 skills.sh.json。
2. 运行验证。
3. 报告结果和剩余风险。
"""

SPANISH_PROMPT = """Retoma esta sesión usando el contexto verificado que aparece abajo.

Espacio de trabajo:
Un repositorio local de ejemplo.

Objetivo del usuario:
Continuar el trabajo sin repetir decisiones ya confirmadas.

Requisitos obligatorios:
- [verificado] Conservar el alcance y revisar la evidencia actual.

Completado:
- Se preparó el contexto principal y se comprobó su origen.

Pendiente / por verificar:
- Confirmar el estado de los archivos antes de editar.

Próximas acciones:
1. Revisar los archivos actuales.
2. Ejecutar la comprobación necesaria.
"""

SPANISH_LABELS = {
    "workspace": "Espacio de trabajo:",
    "goal": "Objetivo del usuario:",
    "requirements": "Requisitos obligatorios:",
    "completed": "Completado:",
    "pending": "Pendiente / por verificar:",
    "next": "Próximas acciones:",
    "fact_labels": ["[verificado]", "[inferido]", "[no verificado]"],
}


def import_module(path: Path, name: str) -> Any:
    spec = importlib.util.spec_from_file_location(name, path)
    if spec is None or spec.loader is None:
        raise RuntimeError(f"Cannot load module: {path}")
    module = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(module)
    return module


def write_sample_codex_jsonl(path: Path) -> None:
    rows = [
        {"type": "session_meta", "payload": {"id": "sample-session", "cwd": "/mnt/c/Users/example/project"}},
        {"type": "response_item", "payload": {"type": "message", "role": "user", "content": "Context is too long. Create a handoff prompt."}},
        {"type": "compacted", "payload": {"message": "Important compacted summary with prior decisions."}},
        {"type": "response_item", "payload": {"type": "function_call", "name": "shell", "arguments": "{\"cmd\":\"pytest\"}"}},
        {"type": "response_item", "payload": {"type": "function_call_output", "call_id": "call_1", "output": "tests passed in D:\\\\Data\\\\repo\\\\artifact.txt"}},
    ]
    path.write_text("\n".join(json.dumps(row, ensure_ascii=False) for row in rows) + "\n", encoding="utf-8")


def write_sample_task_forest(workspace: Path) -> None:
    export_dir = workspace / ".agent-workbench" / "task-forest" / "exports"
    export_dir.mkdir(parents=True)
    (export_dir / "task-forest.graph.json").write_text(json.dumps({
        "nodes": [
            {"id": "TF-0001", "kind": "global_task", "title": "Maintain COMPASS skills", "status": "in_progress"},
            {"id": "TF-0002", "kind": "task", "title": "Add session handoff prompt", "status": "review_needed"},
        ],
        "edges": [{"from": "TF-0002", "to": "TF-0001", "kind": "child_of"}],
    }, ensure_ascii=False), encoding="utf-8")
    (export_dir / "task-forest.todos.json").write_text(json.dumps([
        {"id": "TODO-1", "title": "Run smoke test", "status": "open", "priority": "high"}
    ], ensure_ascii=False), encoding="utf-8")
    (export_dir / "task-forest.timeline.json").write_text(json.dumps([
        {"event": "created", "summary": "Added handoff skill task"}
    ], ensure_ascii=False), encoding="utf-8")


def assert_language_contract(skill_dir: Path) -> None:
    skill = (skill_dir / "SKILL.md").read_text(encoding="utf-8")
    output_contract = (skill_dir / "references" / "output-contract.md").read_text(encoding="utf-8")
    metadata = (skill_dir / "agents" / "openai.yaml").read_text(encoding="utf-8")

    assert "Section headers in the continuation prompt must also use the user's language." in skill
    assert "regardless of language" not in skill
    assert "section labels may be translated" in output_contract
    assert "--labels-json" in skill
    assert "--labels-json" in output_contract
    short_description = re.search(r'^  short_description: "(.*)"$', metadata, re.MULTILINE)
    assert short_description is not None
    assert 25 <= len(short_description.group(1)) <= 64


def main() -> int:
    parser = argparse.ArgumentParser(description="Smoke test session-handoff-prompt scripts.")
    parser.add_argument("--skill-dir", default=str(Path(__file__).resolve().parents[1]))
    args = parser.parse_args()
    skill_dir = Path(args.skill_dir).resolve()
    scripts = skill_dir / "scripts"

    assert_language_contract(skill_dir)

    project = import_module(scripts / "project_session_events.py", "project_session_events")
    task_forest = import_module(scripts / "read_task_forest_exports.py", "read_task_forest_exports")
    redact = import_module(scripts / "redact_handoff.py", "redact_handoff")
    validate = import_module(scripts / "validate_handoff_prompt.py", "validate_handoff_prompt")

    with tempfile.TemporaryDirectory(prefix="compass-handoff-smoke-") as tmp:
        root = Path(tmp)
        jsonl = root / "session.jsonl"
        write_sample_codex_jsonl(jsonl)
        events = project.parse_codex_jsonl(jsonl, max_chars=400, redact_paths=True)
        assert any(event.get("kind") == "compacted" for event in events), "compacted event not projected"
        assert any(event.get("kind") == "session_meta" and event.get("cwd") == "<LOCAL_PATH>" for event in events), "session cwd was not redacted"
        assert any(event.get("kind") == "tool_output" and event.get("output") == "tests passed in <LOCAL_PATH>" for event in events), "tool output missing or not redacted"

        workspace = root / "workspace"
        workspace.mkdir()
        write_sample_task_forest(workspace)
        tf_summary = task_forest.summarize(workspace)
        assert tf_summary["found"] is True, "task-forest exports not found"
        assert tf_summary["summary"].get("graph_records"), "graph records missing"

        local_result = validate.validate(SAMPLE_PROMPT, mode="balanced", privacy="local")
        assert local_result["ok"], local_result
        spanish_without_labels = validate.validate(SPANISH_PROMPT, mode="minimal", privacy="local")
        assert not spanish_without_labels["ok"], spanish_without_labels
        spanish_with_labels = validate.validate(
            SPANISH_PROMPT,
            mode="minimal",
            privacy="local",
            labels=SPANISH_LABELS,
        )
        assert spanish_with_labels["ok"], spanish_with_labels
        assert spanish_with_labels["label_mode"] == "custom", spanish_with_labels
        shareable_fail = validate.validate(SAMPLE_PROMPT + "\n/Volumes/work/demo\n", mode="balanced", privacy="shareable")
        assert not shareable_fail["ok"] and "local_path_in_shareable_prompt" in shareable_fail["hard"], shareable_fail
        path_blob = "\n".join(
            [
                "/home/example/private",
                "/Volumes/work/demo",
                "/var/folders/ab/cd/T/demo",
                "/tmp/agent-output",
                "/mnt/c/Users/example/project",
                r"D:\Data\repo\file.txt",
                r"\\server\share\repo\file.txt",
                r"\\?\C:\Users\alice\repo\file.txt",
                "~/.codex/skills/private",
            ]
        )
        redacted = redact.redact(SAMPLE_PROMPT + "\nsk-abcdefghijklmnopqrstuvwxyz\n" + path_blob + "\n", privacy="shareable")
        shareable_result = validate.validate(redacted, mode="balanced", privacy="shareable")
        assert shareable_result["ok"], shareable_result
        assert redacted.count("<LOCAL_PATH>") >= 8, "shareable path redaction missing extended path families"
        assert "sk-<REDACTED>" in redacted, "secret redaction missing"

    print("ok=session-handoff-prompt smoke test passed")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())
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 CodeCodexUnverifiedInstall
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