Tutorials · Extensions

Build the Release Assistant extension

Gather an exact release range and changelog diff, then delegate planning to a specialist that refuses to claim readiness when validation evidence is missing.

Pattern under test

autohand.release-assistant demonstrates a versioned package with two tools, one agent, and a handler that renders two required parameters. It collects release evidence but deliberately does not tag, push, or publish.

autohand.release-assistant/
  autohand.extension.json
  README.md
  tools/release-range.json
  tools/changelog-context.json
  agents/release-planner.md

Create the manifest

{
  "$schema": "https://raw.githubusercontent.com/autohandai/code-extensions/main/schema/autohand.extension.schema.json",
  "schemaVersion": 1,
  "extensionApi": 1,
  "id": "autohand.release-assistant",
  "name": "Release Assistant",
  "version": "1.0.0",
  "description": "Gather a release range and delegate evidence-based release planning.",
  "license": "Apache-2.0",
  "repository": "https://github.com/autohandai/code-extensions",
  "contributes": {
    "tools": ["tools/release-range.json", "tools/changelog-context.json"],
    "agents": ["agents/release-planner.md"]
  }
}

Add the release range tool

{
  "name": "release_range",
  "description": "Show commits between a release base and HEAD",
  "parameters": {
    "type": "object",
    "properties": {
      "from": {
        "type": "string",
        "description": "Previous release tag or commit"
      }
    },
    "required": ["from"]
  },
  "handler": "git log {{from}}..HEAD --oneline",
  "source": "user"
}

The tool uses an explicit previous release base. It does not guess the last tag, which keeps the caller responsible for the release boundary.

Add the multi-parameter changelog tool

{
  "name": "changelog_context",
  "description": "Show changes to a changelog path since a release base",
  "parameters": {
    "type": "object",
    "properties": {
      "from": {
        "type": "string",
        "description": "Previous release tag or commit"
      },
      "path": {
        "type": "string",
        "description": "Repository-relative changelog path"
      }
    },
    "required": ["from", "path"]
  },
  "handler": "git diff {{from}}..HEAD -- {{path}}",
  "source": "user"
}

Both placeholders are required. The fixed -- makes the final value a path, while Autohand shell-escapes both arguments before execution.

Add the release planner

---
description: Build evidence-based release notes and a release-readiness checklist
tools: read_file, git_status, release_range, changelog_context
---
Use the exact release range and repository evidence. Group user-visible changes,
compatibility notes, fixes, and operational risks. Call out missing validation
or migration steps. Never claim a release is ready when required proof is absent.

The specialist can inspect status and files, but it has no publishing command. Its product boundary is planning and readiness evidence.

Create a release fixture

Use a disposable repository with:

  • A tag such as v1.0.0.
  • At least three later commits: one feature, one fix, and one internal refactor.
  • A CHANGELOG.md updated for only some of those commits.
  • One uncommitted file to exercise git_status.
autohand extensions validate ./autohand.release-assistant
autohand extensions install ./autohand.release-assistant --link
autohand extensions show autohand.release-assistant
autohand extensions doctor

Run the planning task

Delegate to release-planner for the range v1.0.0..HEAD.
Use CHANGELOG.md for changelog context. Group user-visible changes,
identify missing entries and dirty-tree risk, and return a readiness checklist.
Do not tag, commit, push, or publish.

Verify that the planner cites the exact commits and changelog diff, reports the dirty tree, and does not turn missing test evidence into a “ready” claim.

Test parameter and range failures

  1. Omit path from changelog_context; input validation should block rendering.
  2. Use a nonexistent base revision; Git should return a truthful error.
  3. Use a missing changelog path; the planner should report no available changelog evidence.
  4. Deny the shell call; the planner should explain which proof could not be collected.

Clean up and prepare a compatible update

autohand extensions remove autohand.release-assistant --yes

# After a compatible prompt or handler correction, bump the package version.
autohand extensions validate ./autohand.release-assistant
autohand extensions install ./autohand.release-assistant
autohand extensions show autohand.release-assistant

Use a patch version for a compatible correction, a minor version for additive contributions, and a major version for renamed tools or changed required inputs.