# Hyperteam

> Reads a session-spec, derives a task DAG, gets user approval, writes team-state.json, seeds the native task list, creates a specialist team, and monitors until the back-pressure gate passes.

- **Type:** Skill
- **Install:** `agentstack add skill-samrom3-claude-hyper-plugs-hyperteam`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [samrom3](https://agentstack.voostack.com/s/samrom3)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [samrom3](https://github.com/samrom3)
- **Source:** https://github.com/samrom3/claude-hyper-plugs/tree/main/hyperloop/skills/hyperteam

## Install

```sh
agentstack add skill-samrom3-claude-hyper-plugs-hyperteam
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Hyperteam

Converts session-spec into autonomous agent team. Executes full task DAG, tracks state in `plans/-team-state.json`, coordinates via native task list, offers PR when gate passes.

______________________________________________________________________

## Phase 0: Pre-Flight

> **Prerequisites:** Requires Agent Teams feature + `gh` CLI. Set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`. Verify `gh` CLI installed and authenticated for PR creation.

Run checks in order. **Stop and surface each issue as encountered.**

### Step 1 — Scan `plans/` and select a session-spec

1. **Legacy check:** List files matching `*-prd.md` in `plans/`. Any found → stop:
   > Legacy `-prd.md` plans found: ``. Rename to `-session-spec.md` to proceed, or create a new spec with `/session-spec`. Do not silently process old-format files.
2. List all files in `plans/` matching `*-session-spec.md`.
3. For each `plans/-session-spec.md`, determine state:
   - No `plans/-team-state.json` → **unstarted**.
   - `metadata.status = "running"` → **in-progress**.
   - `metadata.status = "complete"` → **complete**.
   - Any other value → **in-progress**.
4. Exclude **complete** specs from selection.
5. No incomplete specs → stop:
   > No incomplete session-specs found in `plans/`. Create a session-spec first with `/session-spec`.
6. Build ordered selection list: unstarted first, then in-progress. Within each group, sort by file modification time (most recent first). Format each entry: `. plans/-session-spec.md`. Append for in-progress entries: `⚠ This spec may have an in-flight hyperteam run. Ensure no other session is working on it before proceeding.`
7. **Single spec:** Use `AskUserQuestion`:
   > Only one incomplete session-spec found:
   >
   > `plans/-session-spec.md` [warning if in-progress]
   >
   > Proceed with this spec?

   User confirms → select it. Otherwise stop.
8. **Multiple specs:** Use `AskUserQuestion`:
   > Multiple session-specs found. Choose one to run:
   >
   > 

   Wait for user's choice.
9. Derive `` from selected filename: strip `plans/` prefix and `-session-spec.md` suffix.
10. Derive `` from `` by stripping leading `feat-` prefix if present. If `` does not start with `feat-`, use `` as `` unchanged.

### Step 2 — Checkout git branch

1. Run `git branch --show-current`.
2. Result matches `` → proceed to Step 3.
3. Mismatch:
   a. Run `git branch --list `.
   b. **Branch exists locally** → `git checkout `.
   c. **Branch absent** → `git fetch origin main && git checkout -b  origin/main`.
   d. Verify `git branch --show-current` equals ``. Mismatch → `AskUserQuestion` and stop.

### Step 3 — Verify symlink

1. Run `test -L plans/`.
2. Absent or not symlink → create:
   ```
   mkdir -p plans && ln -sf ~/.claude/tasks/ plans/
   ```
3. Verify: `readlink plans/` must return path ending in `.claude/tasks/`. Fails → `AskUserQuestion` and stop.

> **Note:** Task list scoping handled automatically by `TeamCreate` in Phase 2, Step 2. `TeamCreate` with `team_name: ""` creates task list at `~/.claude/tasks//` and sets `CLAUDE_CODE_TEAM_NAME` on all teammates. No manual `export` of `CLAUDE_CODE_TASK_LIST_ID` needed.

### Step 4 — Detect fresh start vs. resume

Check `plans/-team-state.json`:
- **Absent** → Read `references/phase-1-fresh-start.md` and follow in full. Return here, proceed to Step 5.
- **Present** → Read `references/phase-1-resume.md` and follow in full. Return here and proceed to Step 5 (or stop if user declines).

### Step 5 — Gate discretion

After spec parsed and task DAG proposed, assess whether back-pressure gate task is needed.

**Gate recommended when any of:**

- Total step count ≥ 4
- Cross-step integration required (one step's output is another's input)
- Output not easily human-verifiable in-session (e.g., data pipelines, infra changes)

**Gate optional when ALL of:**

- Total step count ≤ 3
- Each step has independent verify criteria (no cross-step deps)
- Human already in verification loop (e.g., UI changes requiring manual review, or user will run `claude plugin validate .` themselves)
- Unit/integration tests alone sufficient to confirm correctness

Present recommendation via `AskUserQuestion`:

> Gate task **recommended / not recommended** because [reason].
>
> Proceed with gate? [Yes / No / Override]

User can override either way. If Yes (or override to Yes) → include GATE task in DAG and Phase 2 team creation. If No → omit GATE task.

Proceed to Phase 2.

______________________________________________________________________

## Phase 2: Team Creation and Coordination

### Step 1 — Count parallel-eligible tasks

1. Read `plans/-team-state.json`.
2. Count tasks where `status: pending` AND `blocked_by` is empty (or all listed blockers already terminal). Call this count `N`.
3. Clamp to `M`: `M = min(max(N, 1), 4)`.

### Step 2 — Create the team

Call `TeamCreate` with:
- Team name: ``
- Teammates: 1 `hyperteam-lead`, `M` `hyperteam-worker` instances, 1 `hyperteam-reviewer`
- Prompt includes: branch name, paths to `plans/-team-state.json`, `plans/-progress.txt`, `plans/-session-spec.md`

### Step 3 — Seed the native task list

For every task in `team-state.json` with `status: pending`:

1. Call `TaskCreate` with YAML front-matter block + full step text as `description`:
   ```
   ---
   id: 
   type: 
   skills:
     - 
   blocked_by:
     - 
     - 
   ---

   
   ```

### Step 4 — Broadcast kickoff

Send broadcast `SendMessage` to team:

> Hyperteam `` is starting.
> State file: `plans/-team-state.json`
> Progress log: `plans/-progress.txt`
>
> All workers: claim tasks from native task list. Parse YAML front-matter in each task's description for `type` (FEAT or DOC) and `blocked_by`. Load `skills:` listed in task front-matter via `Skill` tool before beginning work. Resolve blockers via `team-state.json` (blocker terminal when status `validated` or `completed`).
>
> Reviewer: begin scanning `team-state.json` for completed FEAT tasks with `reviewed: false` immediately.

### Step 5 — Monitor

Main thread monitors run. Lead agent (dispatched in Step 2) handles coordination: review outcomes, failure resets, blocker broadcasts, GATE readiness detection.

React to events:
- **`SendMessage` from lead signalling GATE PASS** → proceed to Phase 4.
- **`SendMessage` from any teammate requiring main-thread intervention** → address and resume.

Main thread does **not** dispatch individual workers or validators. Teammates self-claim.

______________________________________________________________________

## Phase 3: Back-Pressure Gate

> Runs **inside** reviewer agent — not main thread. Reviewer claims GATE native task when lead broadcasts GATE OPEN. See `references/gate-task-template.md` for full gate agent instructions.

Lead notifies main thread only after GATE passes. Proceed to Phase 4.

______________________________________________________________________

## Phase 4: Completion and PR Offer

Read `references/phase-4-completion.md` and follow in full.

______________________________________________________________________

## Phase 5: Team Cleanup

After Phase 4 completes (summary written, PR offered/created/declined), call `TeamDelete` for team ``. Removes all shared team resources. Must be done after Phase 4 so all teammates fully idle before cleanup.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [samrom3](https://github.com/samrom3)
- **Source:** [samrom3/claude-hyper-plugs](https://github.com/samrom3/claude-hyper-plugs)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-samrom3-claude-hyper-plugs-hyperteam
- Seller: https://agentstack.voostack.com/s/samrom3
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.