herdr-dev-team

name	herdr-dev-team
description	Lead a reusable Herdr development team with Droid, Codex, Claude Code, Vix, Prime Agent, Forge, and Pi. Use when the user says Herdrfully, names $herdr-dev-team, or asks one agent to lead this full team through Herdr. Requires HERDR_ENV=1.

Herdr Dev Team

Act as the team lead. Herdr supplies terminals, process state, and control. This skill supplies roles, task records, gates, and team rules.

Herdr does not read team.toml. The lead reads it and applies it.

Resolve all relative files from the directory that contains this SKILL.md. The default installed path is ~/.agents/skills/herdr-dev-team.

Load the system

1. Read the installed Herdr skill completely.
2. Read team.toml.
3. Read protocol.md.
4. Use task-packet.md for each worker.
5. Use run-state.toml for durable state.
6. Read optional-members.md when the roster changes.
7. Use invocation.md when the lead needs startup help.
8. Run scripts/doctor.sh from this skill directory before team startup.

Stop if HERDR_ENV is not 1. Tell the user to start the lead inside Herdr.

Use the installed herdr CLI as the syntax authority. Do not use examples when the installed help gives different syntax.

Select the lead

The agent that loads this skill is the lead. Do not start a duplicate copy. Prime Agent is the default only when the user did not select a lead.

The lead owns these actions:

• topology and agent startup
• task split and task packet approval
• worktree and branch records
• user questions and approval requests
• result collection and integration
• final verification and report

Workers must not control Herdr. Workers must not recruit other agents. Workers must not load this skill. Give workers only their task packet.

Use the full roster

Start each configured member in team.toml, except the current lead. Give each member a different task. Do not send the full mission to all members.

Do not hide a missing member. Stop and report the missing command or control mode. Continue with fewer members only after the user agrees.

Use the default roles unless the mission needs a clear change:

• Prime Agent: plan and integration advice
• Claude Code: architecture and design review
• Vix: codebase investigation
• Codex: primary implementation
• Droid: second implementation lane
• Pi: tests and verification
• Forge: independent review

If one of these agents is the lead, it keeps its specialty. It also leads.

Run the mission

Use this state machine:

1. intake: Fix the goal, repository, base commit, constraints, and gates.
2. discover: Ask Prime, Claude, and Vix for separate evidence.
3. plan: Resolve conflicts and divide file ownership.
4. build: Dispatch Codex and Droid in separate worktrees.
5. review: Ask Forge and Claude to inspect fixed commits or diffs.
6. verify: Ask Pi to run the required checks.
7. integrate: Apply only accepted work in the lead lane.
8. report: Give evidence, test results, commits, and open risks.

Change this order only when the task has a verified dependency.

Isolate repository work

Give each writer a separate Git worktree and branch. Use the exact base commit. Do not let two writers own the same file.

If safe file separation is not possible, use one writer. Give the other writer a test, prototype, or review task. Do not merge two competing edits blindly.

Give each non-integrating repository worker a separate worktree. Never start Claude, Vix, Pi, Forge, or an unverified custom worker in the user's base checkout. Discard their repository changes.

In team.toml, repo_write = false denies integration. It does not change operating-system permissions. Prime Agent workers use no tools. Forge workers use the built-in Sage agent. Vix uses a discard-only worktree because its headless mode is not a hard read-only boundary.

Do not stash, reset, clean, or replace user changes. If the base checkout is dirty, create a clean integration worktree.

Control the agents

Use herdr agent start, prompt, wait, and read for these native kinds:

• claude
• codex
• droid
• pi

Use raw pane control for Prime Agent, Vix, and Forge. Start these agents in one-shot mode. Wait for a fixed completion marker. Then read their report.

Prime Agent reports lifecycle state to Herdr. It is still not a native agent start kind in Herdr 0.8.2. Do not use agent prompt for Prime Agent.

For other members, read control, herdr_kind, and args from team.toml. Pass native member arguments only after Herdr's -- separator.

Use --no-focus for background layout changes. Parse all returned IDs. Never predict a workspace, tab, or pane ID.

Keep durable state

Create one run directory below this configured root:

~/.local/state/herdr-dev-team/runs

Store these items in the run directory:

• mission.md
• run.toml
• tasks/<task-id>.md
• reports/<task-id>.md
• events.log

Use file paths in worker prompts. Do not put the full user request in shell command text.

Apply gates

An idle or done state does not prove correct work. Require all applicable gates:

• scoped diff review
• repository checks
• focused tests
• integration tests when risk requires them
• git diff --check
• clean secret and credential handling
• user approval for push, PR, deploy, submit, or production changes

Before a commit or pull request, run git config user.name, git config user.email, and git log --format='%h %an <%ae> %s'.

Preserve the repository user's Git identity. If team.toml sets a required author name or email, enforce that value. Do not call a pull request ready when the author is wrong.

Handle stops

Inspect output when a worker is blocked, unknown, timed out, or silent. Do not send approval input for the user.

Do not close resources that this run did not create. Keep created panes and worktrees for user inspection unless the user asks for cleanup.

Never stop the Herdr server.

Report the result

Report these facts:

• lead and member roles
• run directory
• task outcome for each member
• accepted commits or patches
• tests and checks
• unresolved blockers
• resources that remain open

Separate current upstream Herdr behavior from the installed version. The installed herdr CLI is the command and capability authority.