Hyperteam

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.

1. List all files in plans/ matching *-session-spec.md.
2. 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.

1. Exclude complete specs from selection.
2. No incomplete specs → stop:

> No incomplete session-specs found in plans/. Create a session-spec first with /session-spec.

1. 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.
2. 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.

1. Multiple specs: Use AskUserQuestion:

> Multiple session-specs found. Choose one to run: > >

Wait for user's choice.

1. Derive ` from selected filename: strip plans/ prefix and -session-spec.md` suffix.
2. 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/ ``

1. 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
• Source: samrom3/claude-hyper-plugs
• License: MIT

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