---
title: humand-tech restructure to support obra/superpowers v5.1.0
date: 2026-05-05
status: approved
---

## Goal

Make the `Sync Superpowers` workflow succeed against `obra/superpowers v5.1.0`, which removed the `agents/` and `commands/` directories upstream. The next scheduled cron run (08:00 UTC) should then open the v5.1.0 vendor PR cleanly, without manual intervention.

## Non-goals

- Running the v5.1.0 sync locally as part of this change. The cron will do it.
- Hardening `scripts/validate-template.mjs` against future structural breaks. A loud failure once per major upstream restructure is preferred over silently relaxed validation.
- Introducing a Humand-specific named agent (e.g. `humand-tech:code-reviewer`). Upstream merged the only named agent into the `requesting-code-review` skill; we follow the same model.
- Touching other plugins in the marketplace (`humand-product-workflow`, `humand-backend`, `humand-frontend-sandbox`, etc.).

## Background

`obra/superpowers v5.1.0` (released 2026-05-04) introduces two structural removals relevant to us:

- **`agents/` directory removed.** The only named agent (`code-reviewer`) was consolidated into `skills/requesting-code-review/code-reviewer.md` as a self-contained Task-dispatch template. Anyone dispatching `Task (superpowers:code-reviewer)` should switch to `Task (general-purpose)` with the prompt template.
- **`commands/` directory removed.** Legacy slash commands `/brainstorm`, `/execute-plan`, `/write-plan` were deleted (they were deprecated stubs).

Today's failure (`gh run 25366317195`) chained from these removals:

1. `sync-superpowers.mjs` ran successfully and skipped `agents/` and `commands/` (logged as "not found in source").
2. After sync, `agents/` no longer existed locally (the previously vendored `code-reviewer.md` was removed and `removeEmptyDirs` cleaned up the directory).
3. `scripts/validate-template.mjs` then failed because `plugins/humand-tech/.cursor-plugin/plugin.json` still declared `"agents": "./agents/"` — a missing referenced path → exit 1, no PR opened.

## Changes

All in a single PR, branched off `main`. Branch name must NOT be `chore/sync-superpowers-v5.1.0` — that name is reserved for the workflow's auto-generated PR. Suggested: `chore/humand-tech-restructure-for-superpowers-v51`.

### 1. `plugins/humand-tech/.cursor-plugin/plugin.json`

Remove the `"agents": "./agents/"` line. The `.claude-plugin/plugin.json` does not declare this field (Claude Code auto-discovers component directories), so no change there.

### 2. `plugins/humand-tech/scripts/sync-superpowers.mjs`

Update `VENDOR_DIRS` from `["skills", "agents", "commands", "hooks"]` to `["skills", "hooks"]`. This makes the contract explicit: we replicate skills and hooks. If upstream reintroduces `agents/` or `commands/` in the future, we will manually re-add them here at that time.

### 3. Local directories

- Delete `plugins/humand-tech/agents/` (currently contains the vendored `code-reviewer.md`).
- Delete `plugins/humand-tech/commands/` (currently empty).

### 4. `plugins/humand-tech/.superpowers-version.json`

Do NOT update in this PR. Keep it pinned at `v5.0.7`. Tomorrow's scheduled cron run will detect the version mismatch (`v5.0.7` → `v5.1.0`), run the sync script, and produce a separate PR with the vendored content update.

The sync script removes previously vendored files using `fs.rm(..., { force: true })`, which is a no-op when the file is already gone. So the stale `agents/code-reviewer.md` entry in `vendoredFiles` is harmless tomorrow — the file is already deleted by this PR, the rm call silently succeeds, and the new manifest written post-sync will not list it.

## Validation

Locally before pushing:

```
node scripts/validate-template.mjs
```

Must pass with only the existing benign warnings (other plugins missing `hooks/hooks.json` and `mcp.json` — unrelated to this change).

## Rollout

1. Today: merge this PR.
2. Tomorrow at 08:00 UTC: scheduled cron in `.github/workflows/sync-superpowers.yml` runs. Reads pinned ref `v5.0.7`, fetches latest `v5.1.0`, sees mismatch, runs sync. Validation passes. Opens PR `chore/sync-superpowers-v5.1.0` with refreshed `skills/` and `hooks/` content from upstream v5.1.0.
3. Review and merge that PR.

If we want to short-circuit step 2, manual `workflow_dispatch` with input `ref=v5.1.0` after this PR merges produces the same result.

## Risks and rollback

- **Risk:** an internal Humand workflow or skill outside `humand-tech` dispatches `Task (superpowers:code-reviewer)`. Search of the repo (`rg "superpowers:code-reviewer"`) returns only files inside vendored `humand-tech/skills/` content, all of which upstream rewrites in v5.1.0. No external Humand code paths affected.
- **Mitigation if found later:** dispatch `Task (general-purpose)` with the prompt template at `plugins/humand-tech/skills/requesting-code-review/code-reviewer.md`. No revert of this PR required.
- **Revert path:** restore `agents/code-reviewer.md`, restore `"agents": "./agents/"` in `.cursor-plugin/plugin.json`, restore `agents`/`commands` entries in `VENDOR_DIRS`. The repo will work again on `v5.0.7` but the workflow will fail again the next time upstream changes structure.