pi-herdsman 0.1.0

package/docs/getting-started.md

@@ -0,0 +1,168 @@
+# Getting started
+
+[Documentation index](README.md) · [Agent coordination API](agent-api.md) · [Pi Herdsman](concepts/supervision.md)
+
+This is the shortest human-facing path from installation to useful Pi Herdsman
+orchestration. You do not need to type structured `worker` requests for this
+path.
+
+## 1. Check requirements
+
+You need:
+
+- [herdr](https://github.com/herdrdev/herdr) `>=0.8.0`;
+- Pi `>=0.84.2 <0.86.0` (the version range tested for this release);
+- herdr Pi integration version `2` or newer;
+- Node `>=22.19.0`.
+
+Install or refresh the herdr Pi integration:
+
+```sh
+herdr integration install pi
+herdr integration status
+```
+
+Install the package from npm:
+
+```sh
+pi install npm:pi-herdsman
+```
+
+Pi reads the package manifest and loads the extension plus the optional
+`workers` skill.
+
+## 2. Start the lead Pi session inside herdr
+
+The lead Pi session must run inside herdr. A lead Pi session started outside herdr
+cannot safely manage herdr workers.
+
+The extension distinguishes a lead Pi session, valid managed workers, and
+unmanaged or invalid environments. Only supported managed environments receive
+Pi Herdsman controls and status UI.
+
+## 3. Delegate work without leaving the conversation
+
+Ask the lead Pi agent in ordinary language, for example:
+
+```text
+Use an implementer worker to implement the approved change.
+```
+
+Pi Herdsman starts the work asynchronously. Once the assignment is accepted, the
+lead Pi session remains the session you interact with instead of waiting for the
+worker to finish.
+
+While workers work, you can continue discussing or planning with the
+lead Pi session, delegate other independent work, inspect active work, or focus a
+managed worker pane.
+
+You do not need to poll for completion. Results and worker questions are
+delivered back to the owning controller when they need attention.
+The exact semantics are owned by [Lifecycle](concepts/lifecycle.md).
+
+Pi Herdsman is opinionated about coordination, not workflow. Use the agent roles,
+tools, extensions, and process that fit your project; the lead agent handles the
+structured coordination API internally.
+
+## 4. Open the workers menu
+
+In the lead Pi TUI, run:
+
+```text
+/workers
+```
+
+The native menu contains:
+
+```text
+Running
+Definitions
+Layout
+Stop all…
+```
+
+`Running` is the complete authoritative live-agent inventory and focuses the
+selected pane directly. `Definitions` manages the effective bundled, project,
+and global agent definitions. Project definitions participate only when the
+trusted project setting `piHerdsman.projectAgents` is `true`; effective precedence
+is bundled < project < global. `Layout` controls whether newly started agents
+use tabs or splits. `Stop all…` is destructive emergency control.
+
+See [`/workers` commands](reference/commands.md) for exact behavior.
+
+## 5. Configure definitions and layout
+
+Open `Definitions` to inspect the effective bundled, project, and global roster
+and edit the selected definition's model, thinking level, or enabled state.
+The `[project]` marker identifies project participation and `*` identifies a
+global override. Definition Details shows the effective metadata and can
+expand the resolved definition instructions with Pi's native `Ctrl+O`
+behavior. These edits always write global overrides, never project files.
+
+Use `Layout` to choose the current `tab` or `split` placement for newly started
+workers.
+
+For complete configuration ownership, see:
+
+- [Agent definitions](guides/agent-definitions.md)
+- [Customizing bundled agents](guides/customizing-agents.md)
+- [Agent-definition schema](reference/agent-definition-schema.md)
+- [Configuration](reference/configuration.md)
+
+## 6. Watch and focus work
+
+The status widget shows active managed work and transient `starting` activity.
+Workers exist for one assignment only. After a terminal result is delivered,
+Pi Herdsman cleans up the worker; the exact Pi session remains available for
+continuation. The `Running` menu shows the complete authoritative inventory of
+live or unresolved lifecycle work.
+
+Managed worker panes show their validated breadcrumb identity. Their own active
+Pi tool names can appear as compact bracketed metadata on that breadcrumb.
+
+See [Status widget](reference/status-widget.md) for exact state, refresh, and
+rendering behavior.
+
+To continue a completed assignment with its existing conversational context,
+use the exact `session_id` returned with its result in a new `delegate.session`
+request. This starts a new worker generation with the saved session and current
+effective definition configuration.
+
+## 7. Recover only when needed
+
+Normal coordination and targeted cleanup belong to the agent API. Use
+`Stop all…` only when you deliberately want lead-level emergency cleanup of the
+proven owned worker tree.
+
+For failure diagnosis and conservative cleanup, see [Recovery](guides/recovery.md).
+
+## 8. Optionally supervise leads
+
+When several independent lead sessions run in the same herdr runtime, an
+eligible lead can become the chief with:
+
+```text
+/chief
+```
+
+This is optional and does not change worker ownership. In a UI session, use
+`/chief leave` to leave after reviewing its confirmation, which reports
+known outstanding supervised lead asks and leaves them pending. Cancellation
+does nothing; an unavailable count is reported as unknown. Without a UI, leave
+proceeds without interactive confirmation. See the [supervision
+reference](reference/supervision.md) before using its model-facing tools.
+
+The `/chief` command is state-sensitive: from an ordinary lead, it
+activates chief mode only and shows the ambient widget. When already active
+as chief, `/chief` opens the interactive overview instead. Use
+`/chief leave` to leave chief mode and remove the widget.
+While active, chief mode is supervision-only; leave it to resume ordinary
+workspace-local Pi work.
+
+## Next steps
+
+- Keep delegating naturally through the lead Pi session.
+- Use [`/workers` commands](reference/commands.md) when you need human control.
+- Configure [agent definitions](guides/agent-definitions.md).
+- Read [Agent coordination API](agent-api.md) only when you need the model and
+  agent-facing contracts.

package/docs/guides/agent-definitions.md

@@ -0,0 +1,234 @@
+# Agent definitions
+
+[Documentation index](../README.md)
+
+Agent definitions describe a worker's capabilities, not a required
+workflow. They are Markdown files containing strict frontmatter plus an optional
+prompt body.
+
+This guide covers normal creation and selection. For the complete field contract,
+see the [agent-definition schema](../reference/agent-definition-schema.md).
+
+## Sources
+
+Bundled definitions live in:
+
+```text
+dist/agent-definitions/
+```
+
+Global definitions live by default in:
+
+```text
+~/.pi/agent/agents/
+```
+
+Project definitions are optional and live in the current project:
+
+```text
+<cwd>/.pi/agents/
+```
+
+For example:
+
+```text
+.pi/
+├── settings.json
+└── agents/
+    └── reviewer.md
+```
+
+with project settings:
+
+```json
+{ "piHerdsman": { "projectAgents": true } }
+```
+
+They are discovered only when the trusted project settings contain
+`piHerdsman.projectAgents: true`. Precedence is `bundled < project < global`;
+global definitions remain final user policy. Project definitions apply only to
+their project cwd, and the Definitions UI writes global overrides, never
+project files.
+
+When Pi uses a custom agent directory, the global definitions live under that
+agent directory's `agents/` subdirectory.
+
+A project or global definition whose `name` matches a lower-precedence
+definition overlays it. An unmatched definition is standalone.
+
+## Enable or disable a definition
+
+Definitions are enabled by default. Set `enabled: false` in a matching project
+or global overlay to make a definition unavailable without copying the bundled
+bundled definition:
+
+```markdown
+---
+name: reviewer
+enabled: false
+---
+```
+
+The lead effective roster and `/workers agents` output keep disabled rows and
+show their disabled status so the source can be re-enabled. A delegating worker
+does not receive disabled workers in its definition list. A delegating worker referencing
+a disabled worker can remain discoverable, but is rejected during assignment or
+fresh worker startup with an explicit disabled-worker reason rather than silently
+dropping that worker.
+
+Definition and session delegations reject disabled definitions with an
+actionable error. An already active worker may finish and remains controllable
+according to its current available actions; disabling a definition does not
+mutate that assignment.
+
+## Bundled roster
+
+### `implementer`
+
+Focused source-edit worker for an explicitly approved implementation.
+
+### `researcher`
+
+Focused current/external research worker. Read-only local policy. It also
+allows the default web tool names exposed by `pi-web-access`:
+`web_search`, `fetch_content`, `get_search_content`, and `source_check`.
+Web access is optional. Install it with:
+
+```text
+pi install npm:pi-web-access
+```
+
+Pi Herdsman does not depend on or install `pi-web-access`. Without those tools,
+the researcher retains local inspection capabilities and reports unavailable
+external evidence. Normal Pi extension discovery is intentionally enabled for
+this role so an installed compatible extension can provide the tools. If
+`pi-web-access` is configured with different public tool names, replace the
+researcher's `tools` array through a matching project or global overlay.
+Extension code itself is not sandboxed by the callable-tool allowlist.
+
+### `reviewer`
+
+Independent read-only reviewer.
+
+### `scout`
+
+Fast read-only codebase reconnaissance.
+
+### `worker`
+
+General-purpose scoped execution worker.
+
+The bundled definitions are portable defaults, not required workflow stages.
+Project definitions are for repository-specific policy; global definitions are
+for user-specific final policy.
+
+## Create a standalone definition
+
+Create a Markdown file in the global agents directory:
+
+```markdown
+---
+name: docs-reviewer
+description: Read-only documentation reviewer
+model: openai-codex/gpt-5.6-luna
+thinking: medium
+systemPromptMode: replace
+noSkills: true
+noExtensions: true
+tools: ["read", "ls", "find", "grep"]
+---
+
+Review documentation for correctness, navigation, duplication, and broken
+examples. Do not edit files.
+```
+
+Read-only behavior must be enforced by the effective tool policy, not only by
+prompt text. For normal filesystem inspection, explicitly allow `read`, `ls`,
+`find`, and `grep`, and omit mutation-capable tools such as `bash`,
+`powershell`, `edit`, and `write`. Disable extension discovery when the role
+does not need extension-provided capabilities.
+
+The `name` is authoritative; the filename itself is not the public definition
+name.
+
+## Allow direct workers
+
+```markdown
+---
+name: coordinator
+tools: ["read", "bash"]
+workers: ["scout", "researcher"]
+---
+
+Coordinate the assigned analysis and integrate direct worker results.
+```
+
+The effective roster is validated atomically. Every `workers` name must exist.
+Bundled role descriptions and bodies describe role behavior only; orchestration
+guidance comes from the active controller contract.
+
+With a non-empty explicit `tools` allowlist, `worker` is inferred unless
+explicitly denied. See [Delegation](../concepts/delegation.md).
+
+## Add body files
+
+A body line that consists only of one supported reference includes that file:
+
+```markdown
+---
+name: docs-reviewer
+---
+
+Use the following additional policy.
+
+@./prompts/docs-policy.md
+```
+
+Supported forms:
+
+```text
+@./relative.md
+@../relative.md
+@/absolute/path.md
+```
+
+References are resolved from the Markdown file that declares them.
+
+For exact expansion, deduplication, and caller-file precedence, see
+[Handoffs and files](handoffs.md).
+
+## Inspect effective definitions
+
+A lead Pi session can use:
+
+```text
+/workers agents
+```
+
+or the model can use:
+
+```json
+{ "action": "list" }
+```
+
+Both resolve the same effective roster.
+
+The human `Definitions` menu includes bundled, project, and global
+participation. Project participation is marked `[project]`; a global override
+adds `*`, so `[project] *` means both layers contribute. Model, thinking, and
+enabled settings can be changed through the menu, but edits always write global
+overrides. `Use default` removes only that field and inherits the next lower
+layer or Pi's normal default.
+
+## Override an existing bundled role
+
+Do not copy the complete bundled file just to change one property. Create a
+matching partial global definition instead.
+
+See [Customizing bundled agents](customizing-agents.md).
+
+## See also
+
+- [Agent-definition schema](../reference/agent-definition-schema.md)
+- [`/workers` commands](../reference/commands.md)
+- [Configuration](../reference/configuration.md)

package/docs/guides/customizing-agents.md

@@ -0,0 +1,238 @@
+# Customizing bundled agents
+
+[Documentation index](../README.md)
+
+Matching project and global definitions partially overlay lower-precedence
+roles, in the order `bundled < project < global`.
+
+This allows local customization while continuing to inherit future bundled
+changes for omitted fields.
+
+## Minimal model override
+
+```markdown
+---
+name: reviewer
+model: openai-codex/gpt-5.6-luna
+thinking: high
+---
+```
+
+The bundled reviewer body and omitted frontmatter remain inherited.
+
+## Frontmatter merge rules
+
+For a matching higher-precedence definition:
+
+- omitted fields inherit;
+- strings and booleans replace;
+- arrays replace wholesale, including `[]`;
+- the complete effective definition is validated after composition.
+
+`enabled` is a boolean that defaults to `true`. Use it in a minimal override to
+disable a bundled role without copying its body or other frontmatter:
+
+```markdown
+---
+name: reviewer
+enabled: false
+---
+```
+
+The disabled row remains visible to the lead Pi session, while owner-visible
+definition lists omit it. A delegating worker referencing a disabled worker can remain
+discoverable, but is rejected during assignment or fresh worker startup with an
+explicit disabled-worker reason.
+
+There is no compatibility layer or second definition registry.
+
+## Body composition
+
+An empty higher-precedence body inherits the lower-layer body.
+
+A non-empty overlay body replaces it by default:
+
+```markdown
+---
+name: reviewer
+---
+
+Use this completely different reviewer behavior.
+```
+
+Use `bodyMode: append` to preserve the lower-layer body and add local behavior:
+
+```markdown
+---
+name: reviewer
+bodyMode: append
+---
+
+Also verify database migrations.
+```
+
+When both bodies are non-empty, append mode produces one blank line between the
+bundled and override bodies.
+
+`bodyMode` is valid only when a definition overlays an existing lower-layer
+definition. Interactive edits in the Definitions UI always write global
+overrides.
+It is consumed during definition composition and does not become runtime
+frontmatter.
+
+## Runtime system-prompt composition
+
+`bodyMode` and `systemPromptMode` solve different problems:
+
+```text
+lower-layer body + overlay body
+          ↓ bodyMode
+effective definition body
+          ↓ systemPromptMode
+Pi base system prompt
+```
+
+`systemPromptMode: replace` sends the effective body as Pi's replacement system
+prompt.
+
+`systemPromptMode: append` appends the effective body to Pi's normal system
+prompt.
+
+Managed workers additionally receive shared herdr worker guidance at launch,
+including the `ask_owner` contract. This shared guidance is infrastructure and
+is not copied into every bundled role body.
+
+## Add local body files
+
+```markdown
+---
+name: reviewer
+bodyMode: append
+---
+
+@./prompts/local-review-policy.md
+```
+
+The path is resolved relative to the declaring project or global file before
+body composition, so each layer preserves its own declaring-file provenance.
+
+References expand when each new worker generation is constructed. A session
+continuation keeps the saved Pi history but uses the current effective
+definition configuration for its new generation.
+
+See [Handoffs and files](handoffs.md).
+
+## Local tools, skills, and extensions
+
+Bundled definitions are portable by design. Add repository-specific
+capabilities in a matching project definition, or user-specific final
+capabilities in a matching global override.
+
+Example:
+
+```markdown
+---
+name: reviewer
+bodyMode: append
+tools: ["read", "bash", "my_local_tool"]
+skills: ["/absolute/path/to/code-review/SKILL.md"]
+extensions: ["/absolute/path/to/local-extension.ts"]
+---
+
+Use my local tool only when it materially improves the review.
+```
+
+`extensions` loads the extension code, while `tools` controls which registered
+tool names are callable by the model. Extension-provided tools use the same
+name-based policy as built-in and custom tools, so an extension tool omitted
+from an explicit allowlist is unavailable to the model (and an exclusion wins).
+This does not sandbox the extension: its handlers, commands, shortcuts,
+providers, and other non-tool behavior may still run.
+
+Pi Herdsman passes this native policy through rather than maintaining a second
+tool registry. Provider or conversion integrations can have their own
+presentation layer, so their displayed tool set may require separate
+integration-level verification; loaded provider code is not sandboxed by this
+setting.
+
+An explicit `tools` list controls selection even when `noTools` or
+`noBuiltinTools` also selects restrictive defaults, while `excludeTools` wins
+over the list. Managed workers retain `ask_owner` as mandatory infrastructure
+and remove it from explicit exclusions; this exception does not apply to
+unmanaged Pi launches. Same-named tools cannot be permissioned by source, and
+collision winner ordering is not promised. Launcher-injected worker and
+Herdr-state extensions are separate from definition extensions and remain
+available when `noExtensions` disables ordinary discovery.
+
+For an integration-level smoke check, load the repository's
+`scripts/tool-policy-diagnostic.mjs` extension and set `POLICY_EVIDENCE`,
+`POLICY_LAUNCH`, `POLICY_ACTIVE`, `POLICY_PROVIDER`, and `POLICY_FORBIDDEN` to
+the expected tool-name sets before launching Pi with the same `--tools` and
+extension arguments as the target agent. The diagnostic asserts the launch
+allowlist and active set, records callable provider names and tool-call
+outcomes, fails on forbidden active/provider/call names, and can verify an
+allowed control with
+`POLICY_CONTROL`; it does not capture prompts or secrets. The hook observes
+Pi's provider-request payload, not a provider's final HTTP or WebSocket
+serialization.
+
+The same diagnostic's no-network negative probe can be run with
+`node scripts/tool-policy-diagnostic.mjs --dispatch-check`; it emits a
+deterministic forbidden `exec_command` call into an empty tool context and
+asserts Pi returns `Tool exec_command not found` without execution.
+
+Remember that arrays replace the bundled array rather than append to it.
+Explicitly include every value you want in the effective array.
+
+Skill and extension paths are passed to Pi unchanged; unlike body `@file`
+references, herdr does not resolve them relative to the definition file.
+
+## Interactive agent settings
+
+Lead Pi sessions with UI can use:
+
+```text
+/workers agents
+```
+
+The native Definitions menu lists bundled, project, and global participation.
+Project participation is marked `[project]`; a global override adds `*`, so
+`[project] *` means both layers contribute. Select a
+definition to open:
+
+```text
+Model
+Thinking
+Enabled
+Details…
+Back
+```
+
+Model and thinking each offer `Use default` plus their available values.
+Selecting `Use default` removes only that field. The model chooser stores the
+canonical provider/model token; thinking uses the selected model's supported
+levels when available. `Enabled` toggles the definition.
+
+Edits always write global overrides, and standalone custom definitions can be
+edited through the same flow.
+
+It changes only the selected top-level line in the global Markdown override and
+preserves unrelated frontmatter, line endings, and body content.
+
+Removing a saved field from a bundled definition restores its bundled value.
+Removing a field from a standalone definition uses Pi's normal default. The
+override file is not deleted.
+
+Enable and disable write the scalar `enabled` field in the same global override.
+Removing that field inherits the bundled value, or `true` when no source
+declares it.
+
+Changes affect future definition delegations and session continuations, whose
+runtime configuration comes from the current effective definition. They do not
+mutate an already-running worker or the lead Pi session.
+
+## See also
+
+- [Agent-definition schema](../reference/agent-definition-schema.md)
+- [`/workers` commands](../reference/commands.md)
+- [Agent definitions](agent-definitions.md)