Build a Code Health Extension

Pattern under test

Code Health proves that a package can combine tool and agent contributions. The tool finds TODO/FIXME markers in Git-tracked content. The agent combines that output with file reads and search to prioritize maintainability risks.

autohand.code-health/
  autohand.extension.json
  README.md
  tools/find-todos.json
  agents/code-health-reviewer.md

Create the exact reference manifest

{
  "$schema": "https://raw.githubusercontent.com/autohandai/code-extensions/main/schema/autohand.extension.schema.json",
  "schemaVersion": 1,
  "extensionApi": 1,
  "id": "autohand.code-health",
  "name": "Code Health",
  "version": "1.0.0",
  "description": "Find maintainability risks and delegate focused code-health reviews.",
  "license": "Apache-2.0",
  "repository": "https://github.com/autohandai/code-extensions",
  "contributes": {
    "tools": ["tools/find-todos.json"],
    "agents": ["agents/code-health-reviewer.md"]
  }
}

The manifest declares one contribution of each type. If either path is misspelled, the entire package is rejected; the valid contribution does not activate alone.

Add the Git-aware discovery tool

{
  "name": "find_todos",
  "description": "Find TODO and FIXME comments under a path tracked by Git",
  "parameters": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Repository-relative file or directory"
      }
    },
    "required": ["path"]
  },
  "handler": "git grep -n -E 'TODO|FIXME' -- {{path}}",
  "source": "user"
}

git grep intentionally searches tracked content. The -- separates revisions/options from the path argument. Autohand additionally shell-escapes the value, but this command structure keeps path intent visible to human reviewers.

Add the reviewer

---
description: Review maintainability risks and prioritize focused cleanup
tools: read_file, fff_grep, find_todos
---
Review the requested code for correctness, unnecessary complexity, stale TODOs,
duplication, and maintainability risks. Preserve working contracts. Return a
prioritized set of specific findings with file evidence and the smallest safe
remediation for each finding.

The prompt distinguishes discovery from remediation. It asks for evidence and small safe changes rather than encouraging the agent to delete every TODO or launch an unbounded refactor.

Validate and install at project scope

autohand --path /work/sample extensions validate ./autohand.code-health
autohand --path /work/sample extensions install ./autohand.code-health --scope project
autohand --path /work/sample extensions show autohand.code-health --scope project
autohand --path /work/sample extensions doctor

Expected inspection: version 1.0.0, project scope, enabled, copied, tool find_todos, and agent code-health-reviewer.

Create a controlled fixture

In a disposable Git repository, add and commit a file containing one current TODO, one stale FIXME, and a nearby implementation. The expected output should include both markers with file and line context.

Ask Autohand:

Use code-health-reviewer on src/. Treat TODO and FIXME markers as leads,
not automatic defects. Read the surrounding implementation, rank only
evidence-backed risks, and make no edits.

Approve the git grep call if prompted. Confirm the reviewer reads context before assigning severity and distinguishes a tracked debt item from an actual correctness risk.

Test failure and denial paths

Pass a nonexistent path and confirm the tool returns a truthful Git error.
Request an untracked file and confirm the documented tracked-content behavior.
Deny the tool permission and confirm the agent does not invent TODO results.
Create a standalone meta-tool named find_todos in an isolated profile and confirm doctor reports a conflict instead of replacing it.
Disable the package and confirm both contributions disappear together.

Clean up

autohand --path /work/sample extensions disable autohand.code-health --scope project
autohand --path /work/sample extensions enable autohand.code-health --scope project
autohand --path /work/sample extensions remove autohand.code-health --scope project --yes

The source package remains untouched. If you installed with a copy, only the installed project copy and separate state are removed.