Hiver SDE AI Kit

One place for Hiver's Claude Code skills, plugins, and the agentic dev workflow. Install a single skill, install a themed plugin bundle, or run the full Archon + skills SDLC end to end.

Skills are reusable AI prompt workflows (markdown files with YAML frontmatter) that live in collections. The CLI copies them into the right directory for your IDE — Claude Code, Cursor, or Windsurf. Plugins bundle related skills + agents and install through Claude Code's marketplace.

When to use what

| I want to… | Where | |------------|-------| | Drop one or a few skills into my project | Install skills (npm) | | Install a themed plugin (skills + agents) into Claude Code | Install plugins (marketplace) | | Cut a release / publish a new version | Build & Release | | Drive a run end to end (start here) | ./scripts/hiver-run.sh <RUN-ID> — see Agentic dev workflow | | Run the full agentic SDLC (PRD → plan → PR → validate) | Agentic dev workflow | | Investigate a production incident from Claude | Local AI incident investigator | | Add or change skills / agents / bundles | Contributing |

Install skills & plugins

Two install channels off the same source. Skills = individual, fine-grained (npm CLI). Plugins = curated bundles for Claude Code (marketplace).

Install skills (npm CLI)

Skills are reusable Claude Code / Cursor / Windsurf prompt workflows. The CLI copies them into your project.

npx @hiver/sde-ai-kit add

This walks you through:

1. Pick your IDE — Claude Code, Cursor, or Windsurf
2. Pick a collection — common (generic), web (React/Hiver), extension, qa-skills (QA→release; start with qa-kit), devops, or mobile
3. Pick type — Skills or Agents (only shown if both exist)
4. Pick items — select which to install

Dependencies are auto-resolved and installed (transitively, across collections).

Other CLI commands

npx @hiver/sde-ai-kit list                            # List all available skills & agents
npx @hiver/sde-ai-kit add discuss-problem create-prd  # Install specific skills directly
npx @hiver/sde-ai-kit update                          # Check for updates (diff, asks before overwriting)
npx @hiver/sde-ai-kit remove discuss-problem          # Remove an installed skill
npx @hiver/sde-ai-kit help                            # Show help

Navigation

• Arrow keys — move up/down
• Space — toggle selection (multi-select) — you must press Space to check an item
• Enter — confirm
• Esc — go back

Install plugins (marketplace)

Plugins bundle related skills + agents and install through Claude Code's /plugin system from the hiver marketplace.

# One-time: add the marketplace
/plugin marketplace add GrexIt/hiver-sde-ai-kit

# Browse & install
/plugin                      # interactive browser
/plugin install hiver-qa@hiver

Each plugin is self-contained (its skills and any dependencies are bundled), so installing one gets you everything it needs.

Build & Release

Releases go out on two channels off the same source: the npm CLI (@hiver/sde-ai-kit) and the Claude Code marketplace (plugins/ + .claude-plugin/marketplace.json, served straight from this GitHub repo). Both must stay in sync when you cut a release.

Local build & test

yarn build          # esbuild → dist/cli.js (the CLI)
yarn build:plugins  # collections + bundles.json → plugins/ + marketplace.json
yarn build:all      # both
yarn test           # builds both, then validates both install channels

GitHub workflows

There are 3 workflows in .github/workflows/ (CI runs on Node 22):

| Workflow | File | Trigger | Purpose | |----------|------|---------|---------| | Verify pull request | verify-pull-request.yml | Auto on PR open/sync | Runs yarn test — builds the CLI + plugins and validates both install channels. Must pass before merging. | | Npm release process | publish-to-npm.yml | Manual (workflow_dispatch) | Publishes a stable version to NPM from master. | | Beta Release Process | publish-to-npm-beta.yml | Manual (workflow_dispatch) | Publishes a beta version to NPM from any branch. |

How to release a change

Step 1 — get your PR merged

1. Create a feature branch and make your changes.
2. If you touched collections/** or bundles.json, regenerate and commit the generated marketplace artifacts so the marketplace stays in sync:

   yarn build:all        # regenerates plugins/ + .claude-plugin/marketplace.json
   git add plugins .claude-plugin/marketplace.json

3. Open a PR to master. The Verify pull request workflow runs automatically and must pass.
4. Get review and merge to master.

Because the marketplace is served from this repo (/plugin marketplace add GrexIt/hiver-sde-ai-kit), merging the regenerated plugins/ + marketplace.json to master is what ships a plugin change — there is no separate marketplace publish step.

Step 2a — stable npm release (production-ready changes)

1. Go to GitHub Actions → "Npm release process".
2. Click "Run workflow".
3. Enter the version number (e.g., 1.2.0).
4. Click "Run workflow".

What it does: checks out master, installs deps, yarn build, bumps the version in package.json, npm publish --access public, then commits and pushes the version bump.

After release, consumers get the new version with:

npx @hiver/sde-ai-kit@latest add

Step 2b — beta npm release (test before stable)

Use this when you want others to test a change before making it the default version.

1. Go to GitHub Actions → "Beta Release Process".
2. Click "Run workflow".
3. Enter the branch to publish from (e.g., feat/new-skill or master).
4. Enter the beta version (e.g., 1.2.0-beta.1).
   • Always use the format x.y.z-beta.N.
   • Increment N for subsequent beta releases (beta.1, beta.2, …).
5. Click "Run workflow".

What it does: checks out the specified branch, installs deps, builds, bumps the version (not committed), and publishes to NPM with the beta tag.

Consumers test the beta with:

npx @hiver/sde-ai-kit@beta add

The beta tag means npx @hiver/sde-ai-kit add (without a tag) still resolves to the latest stable version — beta is opt-in only.

When to use which?

| Scenario | Workflow | |----------|----------| | Merged a new skill, ready for everyone | Stable release | | Updated skill content, small fix | Stable release (patch bump) | | WIP feature on a branch, need someone to test | Beta release from that branch | | Big change, want to validate before going stable | Beta release first, then Stable release |

Required secrets

Configured in the repository settings:

| Secret | Purpose | |--------|---------| | NPM_TOKEN_NEW | NPM authentication token for publishing | | CI_SYSTEM_GITHUB_WORKFLOW | GitHub PAT for pushing the version-bump commit | | GITHUB_TOKEN | Auto-provided by GitHub Actions (used for PR checks) |

Contributing

Adding or changing skills, agents, and marketplace bundles → see docs/contributing.md.

collections/ is the single source of truth; everything under plugins/ and .claude-plugin/marketplace.json is generated (yarn build:all) — never edit those by hand.

Agentic dev workflow

The full skills-based agentic SDLC — one-command setup (./bootstrap.sh), an Archon workspace, and the /hiver-* flow from a PRD/bug to a validated PR. The architecture is below; the full setup and workflow guide covers everything else — the /hiver-* skills, per-repo config, PR iteration, and Git/PR conventions.

Local Archon execution and Brain's autonomous GitHub Actions execution share the same specflow/v1 artifacts and readiness gates.

The end-user entry point hides run and artifact plumbing:

hiver-sde develop --prd ./feature.md
# or
hiver-sde develop --requirement "Add ..."
# frontend references are discovered from PRD frontmatter, or supplied directly:
hiver-sde develop --prd ./frontend-feature.md --design "https://figma.com/design/..."

The command selects the target from the configured repository list enriched by Brain's service catalog. One high-confidence target proceeds automatically; multi-repository or ambiguous scope gets one confirmation. Override discovery when needed (repeat the flag for a cross-repo feature):

hiver-sde develop --repo hot-api-mono --prd ./feature.md
hiver-sde develop --repo hot-api-mono --repo web --prd ./cross-repo-feature.md

From an existing Claude chat, invoke /hiver-spec-to-pr with only the PRD or requirement. It performs the same selection in the current conversation. Both entry points prepare and execute identical independently gated repository slices and finish with validated draft PRs. ./bootstrap.sh installs a repo-backed hiver-sde command, so this works from an unreleased development branch as well as from the npm package.

Architecture of the flow

The canonical product-intake path starts in Brain and does not ask the user to define an execution run:

  raw requirement / product idea
          │
          ▼
  /hiver-prd                    ──►  focused discussion + canonical Brain PRD
          │
          ▼
  Brain PR review + merge       ──►  GitHub drafts the linked tech spec
          │
          ▼
  reviewed tech spec PR merge   ──►  automatic approval + common specflow/v1 artifacts
                                      via Brain Actions or the local adapter

/hiver-prd stops after opening the Brain PR. It does not select implementation repositories or start delivery; those decisions are grounded by the later tech spec. The lower-level Run Pack path remains available for direct local work and custom orchestration:

For a pre-merge end-to-end trial, use the same codex/** branch name in Brain and this repository. PRD and generated spec PRs target that Brain branch, the delivery workflow automatically loads the matching setup-kit branch, and target implementation branches use the canonical qa-<slug> name. Use a unique slug for a disposable trial so it cannot collide with a later production run. Prefer a disposable branch such as codex/specflow-v1-e2e-test, forked from the rollout branch in both repositories, so the sample PRD/spec do not become part of the eventual framework merge.

  ClickUp / Jira ticket                    raw PRD / ask / bug
          │                                        │
          ▼                                        │
  /hiver-ticket-intake          ──►  PRD (verbatim: description, comment
          │                          thread, attachments, intake gaps)
          │                                        │
          └────────────────┬───────────────────────┘
                           ▼
  /hiver-requirement-clarifier  ──►  Agent Run Pack (in-depth brainstorming: options +
          │                          decisions & why + explicit repo selection)
          ▼
  /hiver-figma-plus (if UI)     ──►  Design Pack (per-screen design source of truth:
          │                          Figma link or screenshot, states, Design IDs)
          ▼
  /hiver-qa-test-designer       ──►  QA Test Case Pack (happy/edge/error/security + VIS visual cases)
          │
          ▼
  /hiver-repo-context-discoverer ─►  Repo Context Brief (+ design-system/asset conventions,
          │                          confirms parked decisions)
          ▼
  /hiver-agent-planner          ──►  Agent Execution Plan (+ system change diagram, test coverage
          │                          matrix → TC IDs, design-gated Frontend Task Breakdown)
          ▼
  specflow/v1 readiness gate    ──►  shared delivery-manifest.json
                                      (QA + context + design/N-A + plan + approval)
          │
          ▼
  Archon: archon-plan-to-pr     ──►  implementation branch + GitHub PR + review
          │
          ▼
  /hiver-env-deploy             ──►  run's branches running in a live dev env, in the
          │                          plans' deploy order (MUTATES a namespace — gated)
          ▼
  /hiver-env-verify             ──►  Test Funnel Report: every TC ID from the plan's
          │                          coverage matrix marked Pass / Fail / Untested
          │                          with a reason (read-only against the env)
          ▼
  Archon: archon-validate-pr    ──►  validated PR (main vs feature, E2E, verdict)
          │
          ▼
  ── Post-PR iteration (human-driven; human feedback is the source of truth) ──
  Human review / CI failure / QA finding
          │
          ▼
  /hiver-pr-iteration-assistant ──►  PR Iteration Brief (classify + minimal repair plan; NO code)
          │
          ▼
  Human supervisor approves the brief  ──►  say "proceed" in the Claude session
          │
          ▼
  Archon: archon-piv-loop        ──►  approved fixes on the SAME PR branch (same PR updated)
  (--branch <pr-branch>)              + reran tests + updated Test Funnel Report + diff summary
          │
          ▼
  Human re-reviews   (repeat as iteration 2, 3, … if more feedback)

This post-PR loop is not an autonomous AI PR review. We deliberately do not default to archon-smart-pr-review; human feedback is the source of truth, scope never expands, and no file is changed before the supervisor approves the brief.

→ Full workflow, skills reference, and setup: docs/agentic-workflow.md.

Local AI incident investigator

The Claude-first investigator is separate from the spec-to-PR pipeline. It runs on demand in the active agent session, uses the MCP connectors available there, and persists resumable evidence-backed artifacts. It has no always-running server and does not depend on Archon.

Claude session
  -> /hiver-incident-investigator
  -> deterministic local routing/state/budget commands
  -> read-only MCP evidence + pinned local Git reads
  -> evidence + hypotheses + incident report
  -> optional exact-preview approval -> Slack thread reply

Repository context is resolved through service -> repo_key -> repos_root using config/investigator/service-catalog.yml and archon-hiver.yml. The harness verifies the clone's origin and requires an immutable deployed commit before bounded git grep/git show reads. It never fetches, checks out, or reads uncommitted working-tree code.

The sole optional write is a final reply to a specific existing Slack thread. The harness displays the normalized target, exact generated message, and SHA-256 hash; only explicit operator approval unlocks the mapped collaboration.replyToThread call. Timeouts are marked uncertain and never retried automatically.

./scripts/install-investigator.sh
./scripts/install-skills.sh

./scripts/new-investigation.sh INV-DEMO-001 --signal api_latency
hiver-investigator status --id INV-DEMO-001
./scripts/validate-investigation.sh INV-DEMO-001

The harness records agent-reported MCP receipts rather than independently intercepting host calls, so connector scopes and Claude permissions remain part of the safety boundary. See config/schemas/investigation-artifacts.md.