agents-handoff 0.0.0-stage → 2.0.2

package/docs/index.md

@@ -0,0 +1,83 @@
+---
+title: agent-handoff
+---
+
+# agent-handoff documentation
+
+agent-handoff turns an AI working session — chat turns, tool calls, reasoning, however the
+client stored it — into a folder of plain files that a different agent, a different harness,
+or a colleague can read and continue from without the original chat. It builds from a
+transcript or an adapter export, keeps a hash chain so a handoff can be re-verified, and
+merges later turns into the same session instead of duplicating it.
+
+## Quick start
+
+```bash
+# 1. Install the skill
+npx agents-handoff
+
+# 2. Build a handoff from a transcript
+node tools/handoff.mjs build --source transcript.jsonl --project my-project
+
+# 3. Find it, read it, check it
+node tools/handoff.mjs list
+node tools/handoff.mjs show <id-prefix>
+node tools/handoff.mjs verify <id-prefix>
+```
+
+`build` also accepts `--session`, `--harness`, `--model` and `--objective`. Run
+`node tools/handoff.mjs config` to see which store root the engine resolved and why.
+
+## Where to start
+
+| If you want to… | Read |
+|---|---|
+| install it | [INSTALL.md](INSTALL.md) |
+| understand how the pieces fit | [ARCHITECTURE.md](ARCHITECTURE.md) |
+| look up a command, flag or exit code | [CLI.md](CLI.md) |
+| know exactly what a handoff folder holds | [FORMAT.md](FORMAT.md) |
+| see captured sessions, and check them | [SESSIONS.md](SESSIONS.md) |
+| fix something that is not working | [TROUBLESHOOTING.md](TROUBLESHOOTING.md) |
+| feed it a transcript from your own tool | [INTEGRATION.md](INTEGRATION.md) and [../refs/ADAPTERS.md](https://github.com/Alot1z/agent-handoff/blob/main/refs/ADAPTERS.md) |
+| understand what the hashes prove | [PROVENANCE.md](PROVENANCE.md) |
+
+## All pages
+
+| Document | Contents |
+|---|---|
+| [INSTALL.md](INSTALL.md) | Installer commands, install locations, requirements |
+| [UPGRADE.md](UPGRADE.md) | Updating an installation, pinning a version, what a version change touches |
+| [UNINSTALL.md](UNINSTALL.md) | Removing an installation, and which files are deliberately kept |
+| [ARCHITECTURE.md](ARCHITECTURE.md) | The layers, the data flow, the store root, the write-safety discipline, the boundaries |
+| [CLI.md](CLI.md) | Every executable, verb, flag, exit code, environment variable and file written |
+| [FORMAT.md](FORMAT.md) | Handoff folder layout, every file in it, the manifest and the schemas |
+| [SESSIONS.md](SESSIONS.md) | Session index: a sample store, its captured sessions, and how to verify and re-render them |
+| [INTEGRATION.md](INTEGRATION.md) | Embedding the engine, configuration and environment, CI and pipeline use |
+| [LEVEL4.md](LEVEL4.md) | Dynamic runtime layer: runtime verbs, gates and promotion |
+| [LEVEL5.md](LEVEL5.md) | Collaborative dispatch: routing a handoff to another agent |
+| [PERMISSIONS.md](PERMISSIONS.md) | Permission levels, risk classes, and the policy file |
+| [SECURITY.md](SECURITY.md) | What is read and written, secrets, malicious input, guarantees not made |
+| [COMPATIBILITY.md](COMPATIBILITY.md) | Platforms, Node versions, input formats, exit codes |
+| [PROVENANCE.md](PROVENANCE.md) | The hash chain, how to verify it, what it cannot prove |
+| [TROUBLESHOOTING.md](TROUBLESHOOTING.md) | Symptom, cause and fix, keyed to the real exit codes |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Test suite, project layout, how to add an adapter |
+| [Changelog](https://github.com/Alot1z/agent-handoff/blob/main/CHANGELOG.md) | What changed in each release, and how to add an entry |
+| [../refs/ADAPTERS.md](https://github.com/Alot1z/agent-handoff/blob/main/refs/ADAPTERS.md) | Canonical input shape and how each session source maps onto it |
+
+## Engine commands
+
+| Command | Effect |
+|---|---|
+| `build --source <file>` | Build or update a handoff from a transcript |
+| `--handoff --source <file>` | Alias of `build` |
+| `list [project-or-prefix]` | List sessions, newest first |
+| `show <id-prefix>` | Print the rendered brief |
+| `verify <id-prefix>` | Re-check the hash chain |
+| `rename <id-prefix> <project>` | Move a session to another project |
+| `retitle <id-prefix> <name>` | Give a session a readable name |
+| `config` | Report the resolved store root, its source and the schema path |
+
+Zero dependencies, Node 18 or newer. [CLI.md](CLI.md) has the full command surface, including
+the runtime layer, bounded execution and the capability registry. See
+[../README.md](https://github.com/Alot1z/agent-handoff/blob/main/README.md) for the repository overview and [../SKILL.md](https://github.com/Alot1z/agent-handoff/blob/main/SKILL.md) for
+the skill definition.

package/handoff.config.example.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "./handoff.config.schema.json",
+  "version": 1,
+  "handoff_dir": "handoffs/",
+  "project_name": null,
+  "auto_capture": false,
+  "max_brief_tokens": 30000,
+  "exclude_from_handoff": [
+    "node_modules/",
+    ".git/",
+    "dist/",
+    "build/",
+    "*.token",
+    "*.key",
+    "*.pem",
+    ".env",
+    "*.log"
+  ],
+  "capture": {
+    "include_tool_outputs": true,
+    "truncate_tool_outputs": false,
+    "max_tool_output_length": 100000
+  },
+  "linking": {
+    "enabled": true,
+    "min_overlap_score": 0.06
+  },
+  "integrity": {
+    "sha256_manifest": true,
+    "verify_on_read": false
+  },
+  "storage": {
+    "type": "filesystem"
+  }
+}

package/handoff.config.schema.json

@@ -0,0 +1,117 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/Alot1z/agent-handoff/handoff.config.schema.json",
+  "title": "Agent Handoff Configuration",
+  "description": "Schema for handoff.config.json — where handoffs are stored, and how a session is captured. Copy handoff.config.example.json to your project root as handoff.config.json to opt in; with no config file the engine keeps its default store. HANDOFFS_ROOT always overrides anything set here.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional pointer to this schema, for editor completion."
+    },
+    "version": {
+      "type": "integer",
+      "enum": [1],
+      "default": 1,
+      "description": "Config format version."
+    },
+    "handoff_dir": {
+      "type": "string",
+      "minLength": 1,
+      "default": "handoffs/",
+      "description": "Where handoffs are stored. Relative paths resolve against the directory holding this file; absolute paths are used as-is.",
+      "examples": ["handoffs/", ".context/handoffs/", "/srv/handoffs/"]
+    },
+    "project_name": {
+      "type": ["string", "null"],
+      "default": null,
+      "description": "Project used for grouping handoffs. Auto-detected when null."
+    },
+    "auto_capture": {
+      "type": "boolean",
+      "default": false,
+      "description": "Accepted and validated; reserved — no tool auto-captures sessions yet."
+    },
+    "max_brief_tokens": {
+      "type": "integer",
+      "minimum": 1000,
+      "maximum": 100000,
+      "default": 30000,
+      "description": "Accepted and validated; reserved — brief truncation is not implemented."
+    },
+    "exclude_from_handoff": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": [
+        "node_modules/",
+        ".git/",
+        "dist/",
+        "build/",
+        "*.token",
+        "*.key",
+        "*.pem",
+        ".env",
+        "*.log"
+      ],
+      "description": "Accepted and validated; reserved — the engine copies no project trees, so nothing is filtered yet."
+    },
+    "capture": {
+      "type": "object",
+      "additionalProperties": false,
+      "default": {},
+      "properties": {
+        "exclude_patterns": { "type": "array", "items": { "type": "string" } },
+        "include_tool_outputs": { "type": "boolean", "default": true },
+        "truncate_tool_outputs": { "type": "boolean", "default": false },
+        "max_tool_output_length": { "type": "integer", "default": 100000, "minimum": 0 }
+      }
+    },
+    "linking": {
+      "type": "object",
+      "additionalProperties": false,
+      "default": {},
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "HONOURED: when false, cross-project link notes are not written."
+        },
+        "min_overlap_score": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "default": 0.06,
+          "description": "Accepted and validated; reserved — the engine uses its built-in 0.06 threshold."
+        }
+      }
+    },
+    "integrity": {
+      "type": "object",
+      "additionalProperties": false,
+      "default": {},
+      "properties": {
+        "sha256_manifest": { "type": "boolean", "default": true },
+        "verify_on_read": { "type": "boolean", "default": false }
+      }
+    },
+    "storage": {
+      "type": "object",
+      "additionalProperties": false,
+      "default": {},
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["filesystem", "sqlite"],
+          "default": "filesystem",
+          "description": "Only filesystem is implemented; sqlite validates but is not honoured."
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "HONOURED and beats handoff_dir: an explicit store path."
+        }
+      }
+    }
+  }
+}

package/install/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog — agents-handoff
+
+The installer is a separate package from the skill. It follows the same
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format and Semantic Versioning.
+
+## [1.1.0] — 2026-10-09
+
+First release published to npm. `npx agents-handoff` now installs the skill on a
+machine that has neither a checkout nor an unpacked archive.
+
+### Added
+
+- A download path for the published package. When no skill tree sits beside the installer, the
+  archive for the requested version is fetched from
+  `https://codeload.github.com/Alot1z/agent-handoff/tar.gz` and unpacked; the same install
+  manifest then copies out of it, so an installed copy is identical either way.
+  `--version latest` resolves the newest release tag and falls back to the `main` branch,
+  saying so, when the repository has no release object.
+- An install that cannot resolve a source file fails with the missing paths and the count,
+  instead of warning per file and reporting success.
+
+### Changed
+
+- Install sources are written in the shipped tree's terms and resolved against both layouts
+  (shipped first, `repo-upstream/` second), so one manifest installs the same files from a
+  clone, a release archive, and a fetched archive.
+- The version reported after an install is read back from the installed `SKILL.md`, and the
+  fallback version used before a tree exists is parsed from `SKILL.md` too. The shipped suite
+  asserts the two agree, so a release cannot install under the previous version number.
+
+### Fixed
+
+- `README.md`, `LICENSE` and the twelve guides installed as nothing outside the development
+  tree: they were addressed under `repo-upstream/<path>`, which only that tree has.
+- `repository` pointed at a repository that does not serve this package; `homepage` and `bugs`
+  were missing.
+
+## [1.0.0] — 2026-10-08
+
+### Added
+
+- `install` (default), `update`, `remove`, `verify`, `list` and `where`.
+- Location targets `global`, `local` and `project`, with `--path` for an exact directory.
+- Global root resolution instead of a hard-coded path: an account-skill store that already
+  holds `agent-handoff`, else `~/.agents/skills`, else an account-skill store found on the
+  machine, else `~/.agents/skills`, created on install. `where` prints the resolved root and
+  the rule that chose it. `AGENT_HANDOFF_GLOBAL_DIR` overrides it.
+- `--version` to install a specific version, and `--force` to skip confirmations.

package/install/README.md

@@ -0,0 +1,76 @@
+# agents-handoff
+
+npx installer for the agent-handoff skill.
+
+## Quick start
+
+```bash
+npx agents-handoff
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `install` | Install the skill (default) |
+| `update` | Update to latest or specified version |
+| `remove` | Remove the installation |
+| `verify` | Verify installation integrity |
+| `list` | List all installed locations |
+| `where` | Show the resolved global root and why it was chosen |
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--location L` | Install location: `global` (default), `local`, `project` |
+| `--path P` | Custom installation path |
+| `--version V` | Version to install: `latest` (default) or specific version |
+| `--force`, `-f` | Skip confirmations, overwrite existing |
+
+## Examples
+
+```bash
+# Install to global location
+npx agents-handoff
+
+# Install to project-local
+npx agents-handoff --location project
+
+# Update to latest
+npx agents-handoff --update
+
+# Remove without confirmation
+npx agents-handoff --remove --force
+
+# Verify installation
+npx agents-handoff --verify
+
+# Show all installations
+npx agents-handoff --list
+
+# Show which global root was chosen, and why
+npx agents-handoff where
+```
+
+## Locations
+
+- **global**: resolved, not hard-coded — an account-skill root that already holds
+  `agent-handoff`, else `~/.agents/skills`, else any account-skill store found on this
+  machine (`<store>/<account-id>/<profile-id>/agent-handoff/`), else `~/.agents/skills`,
+  created on install. See it resolved:
+  `npx agents-handoff where`. Override with `AGENT_HANDOFF_GLOBAL_DIR`, or target an
+  exact path with `--path`.
+- **local**: `./local/skills/agent-handoff/`
+- **project**: `./skills/agent-handoff/` (only detected if in a git repo)
+
+## Requirements
+
+- Node.js >= 18.0.0
+- curl, wget, or native fetch for downloading
+
+## Development
+
+This installer is part of the agent-handoff skill source code.
+
+See the [agent-handoff docs](https://github.com/Alot1z/agent-handoff/tree/main/docs) for more.