# Humand Tech

Engineering plugin for the Humand tech team. Distributed via the Claude Code marketplace.

## What's Included

### Vendored: Superpowers (pinned)

The [superpowers](https://github.com/obra/superpowers) methodology by Jesse Vincent is vendored at a fixed version. This gives the team TDD discipline, structured planning, debugging workflows, and code review patterns — without depending on auto-updates from the public marketplace.

Current pinned version is tracked in `.superpowers-version.json`.

### Own: Humand Tech Skills & Rules

Company-specific skills (`skills/`) and rules (`rules/`) for the engineering team.

### Own: Workflow Orchestration Layer

Workflow skills (`/start`, `/commit`, `/pr`, `/merge-watch`, `/status`, `/archive-merged`, `/history`, `/daily-seek`, `/summary`, `/initial-setup`) with multi-repo orchestration.

- Bundled config: `config/workflow/` — `repos.json`, `teams.json`, `dailyseek.json` (shared, committed)
- User config: `~/.config/humand-tech-workflow/local-config.json` — local repo paths (per machine, not committed)
- State: `~/.local/state/humand-tech-workflow/` — feature contexts, history

Precedence model:

1. User explicit instruction
2. Superpowers rule
3. Humand workflow orchestration rule

### License

Superpowers is vendored under the [MIT License](https://github.com/obra/superpowers/blob/main/LICENSE) by Jesse Vincent. See the upstream repository for full license text.

## Updating Superpowers

### Automatic (daily check)

A GitHub Actions cron job runs daily at 08:00 UTC. It checks the latest release on [obra/superpowers](https://github.com/obra/superpowers/releases) and compares it with the pinned ref in `.superpowers-version.json`. If a new version is available and no PR already exists for it, the workflow runs the sync script and opens a PR automatically.

No action needed — just review and merge the PR when it appears.

### Manual: GitHub Action

1. Go to **Actions → "Sync Superpowers" → Run workflow**.
2. Enter the superpowers git ref (e.g. `v5.1.0`).
3. The workflow runs the sync, validates, and opens a PR.
4. Review the PR diff and merge.

### Manual: Local script

1. Check [superpowers releases](https://github.com/obra/superpowers/releases) for new versions.
2. Review the changelog for security or breaking changes.
3. Run the sync script:

   ```bash
   node plugins/humand-tech/scripts/sync-superpowers.mjs v5.1.0
   ```

4. Review changes with `git diff`.
5. Commit and push.

## Adding Own Skills

Create a new skill directory under `skills/`:

```
skills/my-new-skill/
  SKILL.md    # Must have YAML frontmatter with `name` and `description`
```

Avoid naming collisions with vendored superpowers skills (listed in `.superpowers-version.json`).

## Adding Own Rules

Add `.mdc` files to `rules/`. Each must have YAML frontmatter with `description`.

## Validation

From the repo root:

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

## First-time setup

Run `/initial-setup` to verify tools, seed `local-config.json`, and optionally migrate state from a previous `humand-dev-workflow` workspace. The session-start hook handles migration automatically on first run if `HUMAND_WORKFLOW_LEGACY_WORKSPACE_ROOT` is set.