herdrpowers: Instructions file for Claude Code

Claude Code Guide

This repository IS the herdrpowers plugin: the payload lives directly at the repo root in skills/ and commands/, discovered by the Claude Code, Codex, and Cursor plugin conventions (manifests in .claude-plugin/, .codex-plugin/, .cursor-plugin/, plus the Codex marketplace file at .agents/plugins/marketplace.json), and by OpenCode through package.json, whose main is .opencode-plugin/index.mjs: that plugin registers skills/ and every commands/*.md (as /herdrpowers:<name>) at config time. package.json carries the pack version alongside the four manifests, and must not declare "type": "module" — that would turn the payload's CommonJS scripts (skills/writing-skills/render-graphs.js) into broken ES modules.

When editing pack behavior, edit skills/ or commands/ directly. docs/ holds the human-facing framework docs. This file and AGENTS.md are maintainer instructions only — they are not part of the payload.

Pack Invariants

• No in-process subagents in the payload. Every dispatch in a skill or command goes through orchestration → using-herdr-sibling-panes. If a payload file tells an agent to use the Agent tool or a named subagent type for development work, that is a bug. Two exceptions: writing-skills, where a fresh-context sample may come from a raw API call, and a review task whose resolved mode is orchestrator, which the orchestrator runs in a spawned in-process subagent rather than inline — both say so explicitly.
• Roles and task names, not tool names. Skills speak in roles (Orchestrator, Reviewer, Coder, Generalist) and delegation-task names (complex-coding, test-authoring, chores, task-review, …). Routing resolves at runtime from the target repo's .herdrpowers/config.yaml over the shipped defaults in skills/orchestration/roles.yaml: a roles: list, a fallbacks: map, a delegation: block (pane_scope, execution), and an assignments: table giving every delegation task a role and a mode. No skill or command may hard-code a route. roles.yaml is the default layer only — never the customization point, because plugin installs are read-only.
• The YAML is the source of truth for defaults; prose points at it. No skill, command, or doc restates a shipped role/mode value — they name what a task covers and say "read the resolved assignment". A | Default | column in a payload table is a bug: it goes stale silently and gives agents a second, wrong answer. Adding a role, a delegation task, or a delegation: key means updating roles.yaml plus the tables in skills/orchestration/SKILL.md, commands/init.md, and docs/roles.md — the tables, not defaults inside them.
• Delegation never crosses the orchestrator's tab unless the repo says so. delegation.pane_scope defaults to tab; an out-of-scope pane is not a candidate, not a fallback target, and not counted toward an agent type's availability. A payload file that selects panes without filtering on tab_id is a bug. Scope is never widened mid-run — that is a configuration change, and configuration is read-only inside a run.
• A role that binds to agents: (a list) runs one delegation per entry. That is what makes a review a double review — a property of the role, not of the task — so it applies to any task assigned to such a role, and the different-agent-types, degrade-don't-block, and name-it-in-the-report rules come with it. An entry may pin a model as agent@model, read from the pane's footer (pane-model.sh); two slots of one type count as different only as pinned entries whose models differ, neither containing the other. Routing selects panes by model and never switches one.
• Independence is structural, and not configurable. Every reset-backed delegation (composer-submit.sh) starts a fresh session — that is the independence property, not pane identity. The same physical pane may later review work it previously wrote after a reset. Routing follows the resolved assignment only: agent: → one idle pane of that type; agents: → one delegation per listed type. There is no "prefer a different agent type than the implementer" heuristic. A disabled review removes a review; it never converts one into an in-session self-review (unreset continuing work such as mode: implementer must not review itself inside that same session). The test half is a mode, not a loophole: test-authoring / fix-round-test-authoring in delegate put tests in a pane that never sees the implementation; in implementer they leave the reviewers as the only check on that test code. Both are legitimate, and the report always names which pane wrote the tests. Do not weaken either half silently. Every assignment a repo changed and every disabled review is named in the workflow's final report.
• <KEY> placeholders are intentional. They resolve at runtime from each target repo's Herdrpowers Configuration section (written by the init workflow). When adding a new placeholder, add it to the key table in commands/init.md.
• Keep skill cross-references as bare skill names (writing-plans, not herdrpowers:writing-plans); Claude Code namespaces them automatically at install time (herdrpowers:<name>).