feat: add compaction-style structured summary to hand-off session skill · Entire

feat: add compaction-style structured summary to hand-off session skill

7121c36→main·

alishakawaguchi·3mo ago·16 files·+865 added/-40 removed

Replace raw JSONL transcript dumping with a two-phase approach: extract transcript silently, then produce a structured compaction summary with Task Overview, Current State, Important Discoveries, Next Steps, Context to Preserve, and Unanswered Question sections. This reduces context consumption and improves handoff quality.

Co-Authored-By: Claude Opus 4.6 (1M context) noreply@anthropic.com

Changes

16

{
  "name": "entire-agent-skills-dev",
  "description": "Development marketplace for Entire-focused cross-agent skills and commands",
  "owner": {
    "name": "Entire.io",
    "email": "support@entire.io"
  },
  "plugins": [
    {
      "name": "entire-agent-skills",
      "description": "Entire-focused cross-agent skills and commands",
      "version": "0.1.0",
      "source": "./",
      "author": {
        "name": "Entire.io",
        "email": "support@entire.io"
      }
    }
  ]
}

A.claude-plugin/marketplace.json+20

{
  "name": "entire-agent-skills",
  "version": "0.1.0",
  "description": "Entire-focused skills and commands",
  "skills": [
    "hand-off-session"
  ],
  "commands": [
    "hand-off-session",
    "description": "Entire-focused cross-agent skills and commands",
    "author": {
      "name": "Entire.io",
      "email": "support@entire.io"
    },
    "license": "MIT",
    "keywords": [
      "entire",
      "skills",
      "handoff",
      "agent-workflows"
    ]
  }
}

Installing Entire Agent Skills for Codex

Enable Entire agent skills in Codex via native skill discovery.

Prerequisites

Installation

  1. Create the skills symlink:
mkdir -p ~/.agents/skills
ln -s /path/to/entire-agent-skills/skills ~/.agents/skills/entire-agent-skills

Replace /path/to/entire-agent-skills with the path to your local clone of this repository.

  1. Restart Codex to discover the skills. Verify by asking: "Use the hand-off-session skill."

# Codex Install

Install the `hand-off-session` skill and command for Codex from this repository.

# Installing Entire Agent Skills for Cursor

Enable Entire agent skills in Cursor via native skill discovery.

## Prerequisites

- Git
- A local clone of this repository

## Installation

1. Create the skills symlink:

```bash
mkdir -p ~/.agents/skills
ln -s /path/to/entire-agent-skills/skills ~/.agents/skills/entire-agent-skills

Replace /path/to/entire-agent-skills with the path to your local clone of this repository.

  1. Restart Cursor to discover the skills. Verify by asking: "Use the hand-off-session skill."

# Installing Entire Agent Skills for Gemini

Enable Entire agent skills in Gemini via native skill discovery.

## Prerequisites

- Git
- A local clone of this repository

## Installation

1. Create the skills symlink:

```bash
mkdir -p ~/.agents/skills
ln -s /path/to/entire-agent-skills/skills ~/.agents/skills/entire-agent-skills

Replace /path/to/entire-agent-skills with the path to your local clone of this repository.

  1. Restart Gemini to discover the skills. Verify by asking: "Use the hand-off-session skill."

# Installing Entire Agent Skills for OpenCode

Enable Entire agent skills in OpenCode via native skill discovery.

## Prerequisites

- Git
- A local clone of this repository

## Installation

1. Create the skills symlink:

```bash
mkdir -p ~/.agents/skills
ln -s /path/to/entire-agent-skills/skills ~/.agents/skills/entire-agent-skills

Replace /path/to/entire-agent-skills with the path to your local clone of this repository.

  1. Restart OpenCode. That's it. Verify by asking: "Use the hand-off-session skill."

# Hand-Off Session Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Build a `superpowers`-style Entire skills repo and ship the first cross-agent `hand-off-session` skill that reads repo-local Entire metadata, understands session or checkpoint context privately, and returns only a compact understanding summary.

**Architecture:** Keep reusable behavior in `skills/hand-off-session/` and `commands/`, with a shared helper in `lib/` that discovers sessions, resolves checkpoint relationships, parses `prompt.txt` and `full.jsonl`, filters transcript noise, and produces a small handoff summary. Platform-specific folders remain thin install/bootstrap wrappers so behavior stays consistent across Codex, Claude, OpenCode, Cursor, and Gemini.

**Tech Stack:** Markdown skill docs, shell wrapper scripts, a small shared CLI helper, fixture-based tests, and repo documentation.

---

### Task 1: Scaffold The Repository Layout

**Files:**
- Create: `README.md`
- Create: `skills/hand-off-session/SKILL.md`
- Create: `commands/hand-off-session.md`
- Create: `.codex/README.md`
- Create: `.opencode/README.md`
- Create: `.claude-plugin/plugin.json`
- Create: `lib/hand_off_session.sh`
- Create: `tests/fixtures/`
- Create: `tests/test_hand_off_session.sh`

**Step 1: Write the failing test**

Create a smoke test that asserts the repo contains the expected top-level files and that the helper script is executable.

```sh
test -f README.md
test -f skills/hand-off-session/SKILL.md
test -f commands/hand-off-session.md
test -f .codex/README.md
test -f .opencode/README.md
test -f .claude-plugin/plugin.json
test -x lib/hand_off_session.sh

Step 2: Run test to verify it fails

Run: sh tests/test_hand_off_session.sh

Expected: FAIL because the files do not exist yet.

Step 3: Write minimal implementation

Create the directories and placeholder files with enough content for the smoke test to pass.

Step 4: Run test to verify it passes

Run: sh tests/test_hand_off_session.sh

Expected: PASS for the scaffold checks.

Step 5: Commit

git add README.md skills/hand-off-session/SKILL.md commands/hand-off-session.md .codex/README.md .opencode/README.md .claude-plugin/plugin.json lib/hand_off_session.sh tests/test_hand_off_session.sh
git commit -m "feat: scaffold hand-off-session repo structure"

Task 2: Add Fixture-Based Metadata Discovery Tests

Files:

Step 1: Write the failing test

Add tests that call the helper with fixture repos and verify:

Example assertions:

output="$(lib/hand_off_session.sh --repo tests/fixtures/single-session list)"
printf '%s' "$output" | grep 'session_id'

Step 2: Run test to verify it fails

Run: sh tests/test_hand_off_session.sh

Expected: FAIL because the helper cannot yet parse fixtures.

Step 3: Write minimal implementation

Create realistic fixture metadata shaped like:

Keep fixtures intentionally small but representative.

Step 4: Run test to verify it passes

Run: sh tests/test_hand_off_session.sh

Expected: PASS for fixture discovery once parsing exists.

Step 5: Commit

git add tests/fixtures tests/test_hand_off_session.sh
git commit -m "test: add hand-off-session discovery fixtures"

Task 3: Implement Session And Checkpoint Discovery

Files:

Step 1: Write the failing test

Add exact tests for:

Example:

output="$(lib/hand_off_session.sh --repo tests/fixtures/single-session latest)"
printf '%s' "$output" | grep '"selected_type":"session"'

Step 2: Run test to verify it fails

Run: sh tests/test_hand_off_session.sh

Expected: FAIL because discovery and resolution logic is not implemented.

Step 3: Write minimal implementation

Implement helper subcommands:

Implementation requirements:

Step 4: Run test to verify it passes

Run: sh tests/test_hand_off_session.sh

Expected: PASS for discovery and selection behavior.

Step 5: Commit

git add lib/hand_off_session.sh tests/test_hand_off_session.sh
git commit -m "feat: add hand-off-session discovery and selection"

Task 4: Implement Private Transcript Understanding

Files:

Step 1: Write the failing test

Add tests that verify the helper:

Example:

output="$(lib/hand_off_session.sh --repo tests/fixtures/single-session show test-session)"
printf '%s' "$output" | grep '"summary"'
! printf '%s' "$output" | grep 'raw transcript line'

Step 2: Run test to verify it fails

Run: sh tests/test_hand_off_session.sh

Expected: FAIL because summarization and transcript filtering are not implemented.

Step 3: Write minimal implementation

Implement transcript understanding logic that:

Step 4: Run test to verify it passes

Run: sh tests/test_hand_off_session.sh

Expected: PASS with no raw transcript leakage in default output.

Step 5: Commit

git add lib/hand_off_session.sh tests/test_hand_off_session.sh
git commit -m "feat: add private transcript summarization"

Task 5: Write The Canonical Skill

Files:

Step 1: Write the failing test

Add assertions that skills/hand-off-session/SKILL.md documents:

Step 2: Run test to verify it fails

Run: sh tests/test_hand_off_session.sh

Expected: FAIL because the skill document is still placeholder content.

Step 3: Write minimal implementation

Document:

Step 4: Run test to verify it passes

Run: sh tests/test_hand_off_session.sh

Expected: PASS for skill content checks.

Step 5: Commit

git add skills/hand-off-session/SKILL.md tests/test_hand_off_session.sh
git commit -m "docs: define hand-off-session skill behavior"

Task 6: Add The Slash-Command Wrapper

Files:

Step 1: Write the failing test

Add assertions that the command wrapper:

Step 2: Run test to verify it fails

Run: sh tests/test_hand_off_session.sh

Expected: FAIL because the command wrapper is still placeholder content.

Step 3: Write minimal implementation

Write a thin wrapper document that:

Step 4: Run test to verify it passes

Run: sh tests/test_hand_off_session.sh

Expected: PASS for command wrapper checks.

Step 5: Commit

git add commands/hand-off-session.md tests/test_hand_off_session.sh
git commit -m "feat: add hand-off-session command wrapper"

Task 7: Add Platform Packaging And Install Docs

Files:

Step 1: Write the failing test

Add checks that:

Step 2: Run test to verify it fails

Run: sh tests/test_hand_off_session.sh

Expected: FAIL because install and packaging docs are incomplete.

Step 3: Write minimal implementation

Document installation and usage in the same spirit as superpowers, while keeping all logic centralized in the skill and helper.

Step 4: Run test to verify it passes

Run: sh tests/test_hand_off_session.sh

Expected: PASS for packaging and doc checks.

Step 5: Commit

git add README.md .codex/README.md .opencode/README.md .claude-plugin/plugin.json tests/test_hand_off_session.sh
git commit -m "docs: add hand-off-session installation and packaging"

Task 8: Verify End-To-End Behavior

Files:

Step 1: Write the failing test

Add an end-to-end assertion that:

Step 2: Run test to verify it fails

Run: sh tests/test_hand_off_session.sh

Expected: FAIL until the final behavior is wired together consistently.

Step 3: Write minimal implementation

Tighten wording and output formatting only as needed to satisfy the tests and approved design. Avoid adding new features.

Step 4: Run test to verify it passes

Run: sh tests/test_hand_off_session.sh

Expected: PASS end-to-end.

Step 5: Commit

git add tests/test_hand_off_session.sh README.md skills/hand-off-session/SKILL.md commands/hand-off-session.md lib/hand_off_session.sh
git commit -m "test: verify hand-off-session end-to-end"