docs(agents): document specialized roles

README.md

@@ -345,6 +345,17 @@ Examples include:
 - `stack-ops.slice-builder` for one approved slice at a time.
 - `stack-ops.security-reviewer` for security, privacy, auth, secrets, and
   dependency risk.
+- `stack-ops.bug-hunter` for regressions, failing tests, stack traces, and
+  unexplained behavior.
+- `stack-ops.test-strategist` for coverage gaps, regression cases, edge cases,
+  and flake triage.
+- `stack-ops.contract-reviewer` for public APIs, CLIs, schemas, configs, package
+  exports, and observable behavior.
+- `stack-ops.delivery-engineer` for CI, build, packaging, versioning, and
+  distribution failures.
+- `stack-ops.data-reliability-engineer`, `stack-ops.performance-engineer`, and
+  `stack-ops.search-rag-engineer` for data, performance, and AI/search slices
+  when the repository needs those domains.
 - `stack-ops.readiness` for deciding whether a phase, PR, slice, or stack can
   advance.
 - `stack-ops.stack-operator` for stax and GitHub mechanics after readiness.

docs/concepts/agents-and-roles.md

@@ -1,8 +1,8 @@
 # Agents and roles
 
 `pi-stack-ops` includes focused Pi agents for planning, implementation, review,
-validation, security, readiness, and stack operations. You do not need to call
-these agents directly during normal use.
+validation, security, readiness, stack operations, and specialized diagnosis. You
+usually don't need to call these agents directly during normal use.
 
 ## Why roles matter
 
@@ -12,7 +12,10 @@ boundaries clearer.
 
 ## Packaged roles
 
-The package includes these role types.
+The package includes these role types. Core workflow agents are always relevant
+to Stack Ops. Specialized agents are available when the current repository or
+slice has matching evidence, such as a failing test, public contract change,
+data migration, performance target, or search/RAG system.
 
 | Role | Purpose |
 | --- | --- |
@@ -22,6 +25,13 @@ The package includes these role types.
 | `stack-ops.slice-builder` | Implements one approved slice. |
 | `stack-ops.reviewer` | Reviews specs, plans, diffs, and slices. |
 | `stack-ops.security-reviewer` | Checks security, privacy, secrets, and dependency risk. |
+| `stack-ops.bug-hunter` | Diagnoses failures, regressions, stack traces, and unexplained behavior. |
+| `stack-ops.test-strategist` | Designs focused coverage, regression cases, and flake triage. |
+| `stack-ops.contract-reviewer` | Reviews public contracts across APIs, CLIs, schemas, and observable behavior. |
+| `stack-ops.delivery-engineer` | Diagnoses CI, build, packaging, versioning, and distribution failures. |
+| `stack-ops.data-reliability-engineer` | Reviews persistence, migrations, queries, and data-integrity risks. |
+| `stack-ops.performance-engineer` | Reviews measurable performance and resource concerns. |
+| `stack-ops.search-rag-engineer` | Reviews search, retrieval, embeddings, grounding, and RAG evaluation. |
 | `stack-ops.validator` | Runs focused validation and summarizes evidence. |
 | `stack-ops.workflow-reviewer` | Audits workflow and artifact hygiene; it reports only and is not the gate. |
 | `stack-ops.readiness` | Returns the READY/BLOCKED gate decision for a phase, PR, slice, or stack. |

docs/reference/agents.md

@@ -13,6 +13,13 @@ usually interact with prompts rather than calling these agents directly.
 | `stack-ops.slice-builder` | Implements one approved slice. |
 | `stack-ops.reviewer` | Reviews specs, plans, and diffs. |
 | `stack-ops.security-reviewer` | Reviews security, privacy, auth, and dependency risk. |
+| `stack-ops.bug-hunter` | Diagnoses failures, regressions, stack traces, and unexplained behavior. |
+| `stack-ops.test-strategist` | Designs focused coverage, regression cases, and flake triage. |
+| `stack-ops.contract-reviewer` | Reviews public contracts and compatibility across APIs, CLIs, schemas, and observable behavior. |
+| `stack-ops.delivery-engineer` | Diagnoses CI, build, packaging, versioning, and distribution failures. |
+| `stack-ops.data-reliability-engineer` | Reviews persistence, migrations, queries, and data-integrity risks. |
+| `stack-ops.performance-engineer` | Reviews measurable performance and resource concerns. |
+| `stack-ops.search-rag-engineer` | Reviews search, retrieval, embeddings, grounding, and RAG evaluation. |
 | `stack-ops.validator` | Runs validation and summarizes evidence. |
 | `stack-ops.workflow-reviewer` | Audits workflow and artifact hygiene; reports only. |
 | `stack-ops.readiness` | Returns the READY/BLOCKED gate decision. |

prompts/implement.md

@@ -14,7 +14,11 @@ Rules:
 - Implement at most one slice unless direct current-session human approval names the extra slice.
 - Use `stack-ops.slice-builder` as the single writer.
 - Run `stack-ops.validator` for focused validation.
-- Run fresh-context `stack-ops.reviewer` and, when relevant, `stack-ops.security-reviewer`.
+- Run fresh-context `stack-ops.reviewer` and relevant specialists, such as
+  `stack-ops.security-reviewer`, `stack-ops.bug-hunter`,
+  `stack-ops.test-strategist`, `stack-ops.contract-reviewer`,
+  `stack-ops.delivery-engineer`, `stack-ops.data-reliability-engineer`,
+  `stack-ops.performance-engineer`, or `stack-ops.search-rag-engineer`.
 - Use `stack-ops.blocker-resolver` only for accepted blocker fixes.
 - Use `stack-ops.readiness` before advancing or submitting/updating PRs.
 - Before starting another slice, run `stack-ops context-budget --guard next-slice --out .pi/stack-ops/context-budget/implement-<slice>.json --json`; continue only on `continue` and stop with a handoff on `stop` or `unknown`.

skills/stack-ops/SKILL.md

@@ -34,6 +34,13 @@ Use namespaced agents:
 - `stack-ops.slice-builder`
 - `stack-ops.reviewer`
 - `stack-ops.security-reviewer`
+- `stack-ops.bug-hunter`
+- `stack-ops.test-strategist`
+- `stack-ops.contract-reviewer`
+- `stack-ops.delivery-engineer`
+- `stack-ops.data-reliability-engineer`
+- `stack-ops.performance-engineer`
+- `stack-ops.search-rag-engineer`
 - `stack-ops.workflow-reviewer`
 - `stack-ops.validator`
 - `stack-ops.readiness`