Repository Project-Local AGENTS.md

Public disclosure safety

Before publishing to GitHub or another public destination, inspect the exact outgoing material, including commits (diffs, messages, and metadata), issues, pull requests, comments, reviews, releases, logs, artifacts, and attachments.

Publish only necessary, authorized information. Omit secrets, confidential material, private personal details, and private infrastructure information. Redact sensitive details in diagnostic output, paths, screenshots, and examples using non-reconstructable placeholders without distorting technical evidence.

Preserve legitimate public attribution and record integrity: Git author and committer identities, co-author credits, and release acknowledgments are not inherently sensitive merely because they identify people. Do not silently anonymize contributors, change Git identities, falsify evidence, or rewrite history as a privacy precaution.

If private information cannot be withheld without altering an authoritative record, withhold publication and seek authorization for a correction. Access to private material is not authorization to publish it. Do not assume another agent, reviewer, or scanner has already checked the outgoing content.

If a disclosure occurs, do not repeat the sensitive material publicly. Revoke or rotate exposed credentials and coordinate remediation privately; edits and deletion may not remove already published copies.

Repository documentation

Product, guide, reference, and maintainer documentation describes verified current extension behavior. Historical ADRs instead preserve decisions made at the time, including rejected alternatives and later supersession; they do not redefine current runtime semantics.

• Keep SKILL.md, docs/reference/, docs/guides/, and other current-behavior documentation current-version-only.
• Do not add historical release, migration, legacy-name, or compatibility guidance for removed behavior to current-behavior documentation.
• Document only verified current semantics and known limitations in those pages.

Product philosophy

Repository changes must follow the scope and ownership principles in Product philosophy.

Keep Herdsman focused on the orchestration problems it owns. Prefer the smallest integration-agnostic capability supported by demonstrated need, and leave provider-, model-, extension-, tool-, storage-, and service-specific semantics to their owners.

Evidence-gated simplification

Treat compiler diagnostics, static analysis, audit findings, and review suggestions as evidence to investigate, not automatic change requests.

Before acting on a finding:

1. Trace affected callers, consumers, runtime reachability, and the authoritative contract.
2. Identify the root cause; group cascading or duplicate diagnostics.
3. Prefer deletion, reuse, consolidation, and native capabilities over new code, dependencies, tooling, or configuration.
4. Make changes only when they demonstrably improve correctness, safety, simplicity, or maintainability; preserve existing behavior and safeguards.
5. Validate the affected contract using the smallest meaningful existing check.

Do not optimize for diagnostic counts, coverage percentages, or line counts. Do not add abstractions, suppressions, or tooling merely to satisfy an analyzer. If no worthwhile improvement is demonstrated, make no change.

For occasional repository-wide investigations, use the simplification-audit skill.

Instruction and interface design

Repository changes must follow the principles in Instruction and interface design.

Apply them across runtime behavior, model-facing instructions, tools, schemas, state, validation, documentation, tests, and public interfaces.

Runtime instruction authority

Runtime behavior and authoritative runtime contracts define Herdsman's operational semantics. SKILL.md, documentation, examples, and tests project those semantics; they do not independently redefine them.

The runtime contract must remain sufficient without loading SKILL.md. SKILL.md may reinforce high-salience invariants and add strategy, rationale, examples, and recovery detail.

When changing an invariant:

1. change its authoritative source first;
2. update only affected projections;
3. remove obsolete or overlapping reinforcement;
4. verify that all remaining representations preserve the same meaning.

A behavioral invariant may be reinforced at multiple model-facing decision points when timing or salience materially affects reliability. Those projections must preserve one meaning and must not evolve into independent rules.

Do not add runtime skill loading, generated prompt files, a prompt registry, or another synchronization subsystem merely to keep prose copies aligned.

Architecture decisions

Before making a durable architectural change, inspect relevant records in docs/adr/. Do not contradict an active ADR without superseding it in the same change. Record only durable, non-obvious architectural decisions; keep local implementation facts in code or comments and agent operating instructions in AGENTS.md.

Code map

• extension/index.ts: Pi extension composition, shared registration, and runtime selection.
• extension/agent-controller.ts: Shared owner-side Agent delegation, control, recovery, and result lifecycle.
• extension/managed-agent-runtime.ts: Managed-Agent request, result, context, metadata, and nested-delegation runtime.
• extension/lead-runtime.ts: Lead lifecycle, role composition, supervision, and project integration wiring.
• extension/lead/commands.ts: Lead command menus, settings UI, and command dispatch.
• extension/lead/project.ts: Managed project work operations and Git worktree inspection.
• extension/lead/coordination.ts: Lead coordination, peer messaging, and session discovery.
• extension/agent-definitions.ts: Agent-definition discovery, validation, overrides, and launch arguments.
• extension/herdr.ts: Herdr topology, startup, shutdown, and process ownership.
• extension/mailbox.ts: Durable mailbox protocol and record persistence.
• extension/core.ts: Shared lifecycle and message-preparation logic.
• extension/errors.ts: Structured extension error categories.
• extension/lock.ts: Process-lock ownership.
• extension/presentation.ts: Model, TUI, and status presentation.
• extension/config.ts: Flat Pi Herdsman configuration.
• extension/supervision.ts: Chief lease, supervision projection, lead transport, and staff tool contracts.
• extension/support.ts: Shared extension integration-test mocks and fixtures.
• extension/extension-contract.test.ts: Extension and model contract behavior.
• extension/controller-api.test.ts: Controller authorization and live-control behavior.
• extension/herdr.test.ts: Herdr inspection/read and topology contract behavior.
• extension/controller-lifecycle.test.ts: Authorized delegation lifecycle behavior.
• extension/agent-runtime.test.ts: Managed-agent runtime behavior.
• extension/recovery.test.ts: Failure, recovery, and cleanup behavior.
• extension/lead/commands.test.ts: Direct Lead command-factory behavior.
• extension/lead/project.test.ts: Direct managed project runtime and Git inventory behavior.
• extension/lead/coordination.test.ts: Direct Lead coordination behavior.
• extension/commands.test.ts: Command registration and integration behavior.
• extension/supervision.test.ts: Chief roles, lease, supervision, transport, and staff tool behavior.
• extension/supervision-malformed-cleanup.test.ts: malformed supervision cleanup behavior.

GitHub issue creation

Before creating or substantially revising a GitHub issue, follow the issue guidance, including its AI-assisted issue creation rules. Evaluate the proposal against relevant evidence, explain material inconsistencies to the user, and seek their decision before changing the intended scope or outcome. Preserve uncertainty and review the exact outgoing content under the public disclosure policy above.

GitHub workflow

• Work on a feature branch, either in this repository or a fork, depending on write access. Open pull requests against upstream main.
• Never push directly to upstream main or bypass branch protection.
• Use Conventional Commit PR titles (see CONTRIBUTING.md). Pull requests are squash-merged.
• Before merging, required CI checks must pass and the branch must be up to date with upstream main.

Development loop

During implementation, run the smallest relevant test file first:

npm test -- extension/<area>.test.ts

Narrow further when useful:

npm test -- --test-name-pattern="<pattern>" extension/<area>.test.ts

Focused tests provide development feedback. Focused tests, smoke testing, review, and all intermediate checks must happen before formatting. Do not format during those phases. Before handoff, follow the detailed validation order in Development validation: run npm run format once as the final pre-commit mutation, then run the read-only checks npm run format:check, npm run typecheck, npm run lint -- --deny-warnings, npm run check, and git diff --check before staging or committing.

For changes crossing the real Pi/Herdr runtime boundary, prefer the relevant simulated smoke scenario first when it covers the behavior. Pi, Herdsman, and Herdr still run for real; only model decisions are scripted:

npm run smoke -- core --simulated
npm run smoke -- continuation --simulated
npm run smoke -- chief-tree --simulated
npm run smoke -- terminal-failure --simulated

Use real-model smoke (omit --simulated) when validating model decisions, instruction adherence, provider behavior, or coverage simulation cannot prove. manager-recovery is live-only (npm run smoke -- manager-recovery). Run only relevant scenarios. Smoke is opt-in, and plain npm run smoke still uses the configured real model. Complete smoke before final formatting/validation; see Smoke testing.

Testing architecture

• Test behavior at its lowest authoritative layer.
• Integration tests prove wiring and layer crossings, not duplicate lower-layer matrices.
• Table-drive variants of one invariant.
• Keep separate test files only for source boundaries or required process/module-mock isolation.
• Add no dependency or fixture abstraction when node:test and a few lines suffice.

Backlog

• The ignored .backlog/ repository exists only in the main worktree. Run Backlog CLI reads and writes from the worktree where .backlog/ exists; do not copy, synchronize, or manually edit it in another worktree.
• For each newly verified material issue, search first, then record the exact reproduction, expected and observed behavior, impact, and evidence through the CLI. Do not file speculative or duplicate issues; report the task ID, impact, and whether it blocks the current work.

Validation

• Follow the detailed validation order in Development validation.