@orchestrator-claude/definitions 3.32.2 → 3.34.0

package/README.md

@@ -0,0 +1,145 @@
+# @orchestrator-claude/definitions
+
+Built-in definitions (agents, skills, hooks, workflows, KB seeds) for the
+Orchestrator ecosystem, distributed as an npm package and installed into
+`~/.claude/*` via `orch-defs install`.
+
+## CLI
+
+```bash
+npx orch-defs <command>
+```
+
+| Command | Purpose |
+|---|---|
+| `install` | Materialize agents/skills/hooks/personas/kb into `~/.claude/*`, wire hooks into `~/.claude/settings.json`, and register MCP servers via `claude mcp add --scope user` (RFC-040 ④) |
+| `seed` | Seed a project's definitions into the orchestrator API (Postgres) |
+| `diff` | Compare the local package's definitions against a target |
+| `verify` | Verify manifest checksums |
+| `info` | Show manifest metadata |
+
+Run `npx orch-defs install --help` for the full flag reference and the
+in-context risk notes summarized below.
+
+## `install`: two configuration owners (RF-006)
+
+`orch-defs install` writes to **two physically distinct configuration
+surfaces**, each owned by a different Claude Code subsystem, and **never
+attempts to unify them**:
+
+| Surface | Owner | How the installer writes it |
+|---|---|---|
+| `~/.claude.json` (MCP server registry) | Internal Claude Code state — rewritten live by the running CLI, ~200KB, mostly telemetry | **Never** written directly. The installer only ever invokes `claude mcp add --scope user <name> ...` and checks `claude mcp list` first for idempotency. |
+| `~/.claude/settings.json` (`hooks` block) | Documented contract surface (published precedence, stable schema) | Read-modify-write JSON merge — existing non-orchestrator keys survive. |
+
+**Why not unified?** `~/.claude.json` is Claude Code's own live-rewritten
+internal state file — editing it directly races with the running CLI and
+risks corruption/state loss (`~/.claude/.mcp.json` is a dead path that Claude
+Code never reads, confirmed both in official docs and empirically). By
+contrast, `~/.claude/settings.json` is a documented, stable contract surface
+safe to edit directly. Collapsing both into one "installer config" write path
+would hide this differing discipline and reintroduce the exact corruption
+risk the split is designed to avoid (spec RF-006 / RF-004).
+
+The codebase enforces this split structurally: MCP registration
+(`McpRegistrar`) and hooks wiring (`HooksWirer`) are two separate modules,
+not one generic "write config" function that treats both files as
+interchangeable.
+
+## `install`: MCP server registration — dual-mode (`--monorepo-root` vs bare)
+
+The stdio MCP servers (`orchestrator-tools`, `orchestrator-extended`,
+`perplexity`) are declared in the bundled **`mcp-servers.json`**, whose stdio
+`args` carry a `{{MONOREPO_ROOT}}` placeholder. `orch-defs install` resolves
+that placeholder in one of two modes (RFC-040 §16, spec ADR-007 + ADR-P001):
+
+| Mode | Trigger | Resolution |
+|---|---|---|
+| **dev-checkout** | `--monorepo-root <path>` given | In-place substitution of the placeholder with `<path>` — byte-for-byte the original ADR-007 behavior. Use when running against a monorepo checkout on disk. |
+| **npm-user** (self-contained) | `--monorepo-root` **absent** | Resolves the real installed location of `@orchestrator-claude/mcp-server` via `createRequire(import.meta.url).resolve()` and rewrites the whole placeholder-bearing arg to it. **No monorepo on disk required.** |
+| **fallback** | resolution fails (no hoisting, Yarn PnP, …) | Skips the servers that need the placeholder + emits a warning (`Use --monorepo-root to register them`); placeholder-free servers still register. |
+
+**Self-contained by construction.** `@orchestrator-claude/mcp-server` is a real
+runtime **dependency** of this package (not a peer/dev dep), so a plain
+`npm i -g @orchestrator-claude/definitions` pulls the MCP backbone with it and
+the npm-user resolution above finds it on disk. mcp-server in turn depends on
+`@orchestrator-claude/project-root-resolver` — **published to npm since
+v3.33.0** (S388) — so the whole chain resolves from the registry with no
+monorepo checkout.
+
+The `files[]` allowlist ships the two runtime-required, non-`dist` assets the
+installer reads at runtime — **`mcp-servers.json`** and
+**`hooks-settings-template.json`**. Omitting them (the pre-S387 bug) made a real
+tarball install `ENOENT` while `--dry-run` masked it. **`--dry-run` does not
+prove a tarball — only `npm pack` + an isolated install does.**
+
+> **ESM note:** this package is `"type": "module"`, so bare `require.resolve`
+> is unavailable; `createRequire(import.meta.url)` synthesizes a CJS-style
+> resolver. `import.meta.resolve` is deliberately **not** used (ADR-P001 —
+> historically unstable across Node versions).
+
+## Dev-checkout mode (spec §5.2) — primary use case, not an edge case
+
+`orch-defs install` detects two modes:
+
+- **Clean-install**: cwd is a consumer project (e.g. `orch-testproj-rfc040`,
+  `trc`, `red-bull`) or a fresh machine — nothing competes with the
+  newly-materialized user-scope copy.
+- **Dev-checkout**: cwd is inside the orchestrator monorepo itself, where
+  `.claude/agents/`, `.claude/skills/` are the authored, git-tracked,
+  PR-reviewed source.
+
+**Dev-checkout is cmac's primary, everyday use case** — not a rare edge
+case. The "launch-from-root" goal (RFC-040) is primarily about starting
+sessions *outside* the monorepo, but cmac continues developing the
+orchestrator itself *from inside* the monorepo checkout on a daily basis.
+
+### Precedence — MEASURED (AC-007/TASK-036, S385)
+
+An earlier draft of this spec (§3.3) treated the precedence direction between
+project-scope and user-scope as **asserted by Claude Code's official docs but
+not empirically measured**. `scripts/probes/ac007-precedence-probe.ts`
+(TASK-035) has since run that probe for real (TASK-036): an isolated
+`CLAUDE_CONFIG_DIR` fixture, 3/3 deterministic runs per axis, with a
+hard isolation gate confirming the real `~/.claude` and the real repo were
+never mutated by the probe itself.
+
+**Verdict: CONFIRMS the documented claim.** Agents resolve by **project**
+scope (a local edit inside this repo takes effect on the next live session
+immediately); skills resolve by **user** scope (`~/.claude/skills` — editing
+a skill here has **no** effect on a live session until `orch-defs install`
+re-runs, unless the file happens to be an INTERIM per-file symlink,
+C6/TD-204). The precedence direction is **not inverted**.
+
+**The risk that remains is silent drift, not precedence direction.** Because
+`~/.claude/agents|skills` now resolves from the distributed **package**
+copy while `<repo>/.claude/agents|skills` remains the **authored** copy,
+the two can silently diverge over time — a project-scope skill edit has no
+effect on a live session until you re-run `orch-defs install` to refresh
+`~/.claude/skills`. `orch-defs install` detects dev-checkout mode and
+requires an explicit `--dev-checkout-ack` before proceeding, precisely
+because this drift risk is real and ongoing, not a one-time inverted-
+precedence hazard.
+
+### Full convergence — open question, not closed by this backlog
+
+Fully resolving requirement (a) for the dev-checkout case — converging
+`<repo>/.claude/{agents,skills}` into symlinks pointing at
+`packages/definitions/` (the C6 model, in the reverse direction) — is
+**bigger than this installer** and is explicitly **out of scope** here
+(spec §3.2/§5.2). `orch-defs install` v1 detects-and-warns; full repo
+convergence is a separate design decision, not implemented in this version.
+
+## Development
+
+```bash
+npm run build           # tsc + bundle-hooks + generate-manifest
+npm run test            # vitest run
+npm run test:coverage   # vitest run --coverage
+```
+
+Hooks (`hooks/*.ts`) are bundled into self-contained `hooks/*.mjs` bundles at
+build time (`npm run bundle-hooks`, `src/scripts/bundle-hooks.ts`) — a fresh
+install target has no `node_modules` of its own, so hooks must not depend on
+runtime module resolution outside the bundle. `tests/HooksBundleFreshness.test.ts`
+guards against source/bundle drift (see below).

package/agents/adversarial-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: adversarial-reviewer
-description: PME workflow adversarial review gate executor (per ADR-021). Use as gate (NOT phase) after RESEARCH / FRAMEWORK / DELIVER phases when task scopes critical review through assigned persona's bias lens. Read-only artifact handling: NEVER writes to artifact under review, only outputs critique with severity:high|medium|low findings. Max 3 iterations, converges when severity:high count == 0. NAO use para code review (use coderabbit:code-reviewer ou reviewer) ou para friendly review (use reviewer).
+description: "PME workflow adversarial review gate executor (per ADR-021). Use as gate (NOT phase) after RESEARCH / FRAMEWORK / DELIVER phases when task scopes critical review through assigned persona's bias lens. Read-only artifact handling: NEVER writes to artifact under review, only outputs critique with severity:high|medium|low findings. Max 3 iterations, converges when severity:high count == 0. NAO use para code review (use coderabbit:code-reviewer ou reviewer) ou para friendly review (use reviewer)."
 tools: Read, Grep, Glob, mcp__orchestrator-tools__startAgentInvocation, mcp__orchestrator-tools__completeAgentInvocation, mcp__orchestrator-extended__artifactRetrieve, mcp__orchestrator-extended__artifactStore
 model: sonnet
 color: red
@@ -96,7 +96,7 @@ The iteration counter is **per-gate**, not per-workflow. Each new gate invocatio
 4. MUST NOT proceed with a generic critique when persona file is missing.
 5. MUST NOT auto-iterate beyond iteration 3 — BLOCKED verdict is the terminal state.
 6. MUST NOT apply code-quality standards (SOLID, TypeScript, test coverage) unless the persona's own demands explicitly invoke them.
-7. MUST NOT store the critique in `.orchestrator/artifacts/` directly — use `artifactStore` MCP tool only.
+7. MUST NOT store the critique on the filesystem directly — use the `artifactStore` MCP tool only.
 
 ### SHOULD (Recommended)
 

package/agents/azure-devops-engineer.md

@@ -1,6 +1,6 @@
 ---
 name: azure-devops-engineer
-description: Engenheiro DevOps senior especializado em Azure stack — Bicep + Azure Verified Modules, Azure Developer CLI (AZD), GitHub Actions com OIDC federated credentials, Deployment Stacks, ACA/APIM/Functions/Cosmos DB, Lighthouse delegation, Súmula 331 audit-trail patterns. Use durante phase IMPLEMENT de workflows com escopo IaC ou CI/CD em Azure (Bicep changes, GHA workflows, Azure resource provisioning, AZD CLI ops, schema migrations, Entra ID app registrations, audit-trail evidence pack wiring). NÃO use para application code TypeScript/React (mantém implementer genérico) ou design decisions arquiteturais (mantém specifier/planner).
+description: "Engenheiro DevOps senior especializado em Azure stack — Bicep + Azure Verified Modules, Azure Developer CLI (AZD), GitHub Actions com OIDC federated credentials PARA AZURE, Deployment Stacks, ACA/APIM/Functions/Cosmos DB, Lighthouse delegation, Súmula 331 audit-trail patterns. Use durante phase IMPLEMENT de workflows com escopo IaC ou CI/CD ESPECÍFICO de Azure (Bicep changes, GHA workflows que provisionam/deployam recursos Azure, Azure resource provisioning, AZD CLI ops, schema migrations Cosmos, Entra ID app registrations, audit-trail evidence pack wiring). NÃO use para application code TypeScript/React (mantém implementer genérico), design decisions arquiteturais (mantém specifier/planner), nem para containers/CI/git-pipelines NÃO-específicos de Azure (Docker/docker-compose, GHA service containers genéricos, Neo4j/Postgres/Redis em CI, debugging de CI vermelho cloud-agnóstico, Dockerfile authoring → use cicd-platform-engineer). Em escopo misto (pipeline GHA genérico que faz deploy para Azure), colabore com cicd-platform-engineer: ele cuida do scaffolding container/CI/git/readiness, você cuida da parte Azure (Bicep, azd, OIDC-to-Azure, recursos)."
 tools: Read, Edit, Write, Bash, Grep, Glob, mcp__plugin_azure_azure__acr, mcp__plugin_azure_azure__advisor, mcp__plugin_azure_azure__aks, mcp__plugin_azure_azure__appconfig, mcp__plugin_azure_azure__applens, mcp__plugin_azure_azure__applicationinsights, mcp__plugin_azure_azure__appservice, mcp__plugin_azure_azure__azd, mcp__plugin_azure_azure__azurebackup, mcp__plugin_azure_azure__azuremigrate, mcp__plugin_azure_azure__azureterraform, mcp__plugin_azure_azure__azureterraformbestpractices, mcp__plugin_azure_azure__bicepschema, mcp__plugin_azure_azure__cloudarchitect, mcp__plugin_azure_azure__compute, mcp__plugin_azure_azure__containerapps, mcp__plugin_azure_azure__cosmos, mcp__plugin_azure_azure__deploy, mcp__plugin_azure_azure__documentation, mcp__plugin_azure_azure__eventgrid, mcp__plugin_azure_azure__eventhubs, mcp__plugin_azure_azure__extension_azqr, mcp__plugin_azure_azure__extension_cli_generate, mcp__plugin_azure_azure__extension_cli_install, mcp__plugin_azure_azure__functionapp, mcp__plugin_azure_azure__functions, mcp__plugin_azure_azure__get_azure_bestpractices, mcp__plugin_azure_azure__group_list, mcp__plugin_azure_azure__group_resource_list, mcp__plugin_azure_azure__keyvault, mcp__plugin_azure_azure__loadtesting, mcp__plugin_azure_azure__managedlustre, mcp__plugin_azure_azure__monitor, mcp__plugin_azure_azure__mysql, mcp__plugin_azure_azure__policy, mcp__plugin_azure_azure__postgres, mcp__plugin_azure_azure__pricing, mcp__plugin_azure_azure__quota, mcp__plugin_azure_azure__redis, mcp__plugin_azure_azure__resourcehealth, mcp__plugin_azure_azure__role, mcp__plugin_azure_azure__search, mcp__plugin_azure_azure__servicebus, mcp__plugin_azure_azure__signalr, mcp__plugin_azure_azure__sql, mcp__plugin_azure_azure__storage, mcp__plugin_azure_azure__subscription_list, mcp__plugin_azure_azure__wellarchitectedframework, mcp__plugin_azure_azure__workbooks, mcp__plugin_microsoft-docs_microsoft-learn__microsoft_code_sample_search, mcp__plugin_microsoft-docs_microsoft-learn__microsoft_docs_fetch, mcp__plugin_microsoft-docs_microsoft-learn__microsoft_docs_search, mcp__orchestrator-tools__createCheckpoint, mcp__orchestrator-tools__startAgentInvocation, mcp__orchestrator-tools__completeAgentInvocation, mcp__orchestrator-extended__artifactStore, mcp__orchestrator-extended__artifactRetrieve
 model: sonnet
 color: blue
@@ -779,6 +779,14 @@ Use `implementer` (genérico) para:
 - Database queries / Cosmos document modeling (não schema migration)
 - Business logic / domain layer
 
+Use `cicd-platform-engineer` (DevOps cloud-agnóstico) para:
+- Docker / docker-compose / Dockerfile authoring & optimization
+- GitHub Actions genéricos (CI lint/test/build, service containers, matrix, caching, reusable) que NÃO provisionam/deployam recursos Azure
+- Orquestração de serviços efêmeros em CI (Neo4j, Postgres, Redis, MinIO)
+- RCA de CI vermelho com reprodução local (docker/act), readiness/healthcheck patterns
+- git pipelines & workflow hygiene (unmask de `continue-on-error` com prova)
+- **Colaboração:** em pipeline GHA misto (CI genérico + deploy Azure), ele cuida do scaffolding container/CI/git/readiness e você da parte Azure (Bicep/azd/OIDC-to-Azure/recursos).
+
 Use `specifier` para: feature spec inicial.
 Use `planner` para: technical implementation plan.
 Use `task-generator` para: backlog atomic.