intelligencex-write-tool-authoring

# Skill: intelligencex-write-tool-authoring Use this skill when adding or refactoring write-capable (mutating) tools. ## Goal - Keep write tools consistent, low-maintenance, and safe by default. - Reuse shared helpers instead of open-coding governance, schema, and response logic. ## Required Build Pattern 1. Define schema with shared extensions: - Start with `ToolSchema.Object(...)`. - Prefer `.WithWriteGovernanceDefaults()` for write tools. - For probe-aware auth flows prefer `.WithWriteGovernanceAndAuthenticationProbe()`. - Use low-level `.WithWriteGovernanceMetadata()` / `.WithAuthenticationProbeReference()` only for advanced custom ordering. 2. Define write contract with shared factories: - Boolean intent: `ToolWriteGovernanceConventions.BooleanFlagTrue(...)`. - String intent: `ToolWriteGovernanceConventions.StringEquals(...)`. 3. Define authentication contract with shared factories: - Host-managed auth: `ToolAuthenticationConventions.HostManaged(...)`. - Probe-aware auth: set `supportsConnectivityProbe: true` and `probeToolName`. 4. Return success with standardized write envelope: - Use `ToolResponse.OkWriteActionModel(...)` for mutating actions with dry-run/apply mode. ## Write Intent Rules - Write-intent argument must be explicit (`send`, `apply`, `intent=read_write`, etc.). - Keep default behavior non-mutating when possible. - Use explicit confirmation (`allow_write` or same as intent flag) for actual writes. ## Governance Metadata Rules - Always expose canonical metadata args in schema: - `write_execution_id` - `write_actor_id` - `write_change_reason` - `write_rollback_plan_id` - `write_rollback_provider_id` - `write_audit_correlation_id` - Runtime policy decides which fields are required at execution time. ## Authentication + Probe Rules - When tool supports auth preflight probes: - set `supportsConnectivityProbe: true` and provide `probeToolName`. - expose `auth_probe_id` in schema using `.WithWriteGovernanceAndAuthenticationProbe()` (or `.WithAuthenticationProbeReference()` for custom pipelines). - do not hand-roll schema argument names; use `ToolAuthenticationArgumentNames`. - For strict probe gating before writes: - validate probe references through `ToolAuthenticationProbeValidator`. - use a stable target fingerprint derived from endpoint/auth context. - keep probe max-age configurable in tool options. ## Pack Guidance Rules - Ensure tool catalog traits expose: - mutating action arguments - write-governance metadata arguments - Ensure authentication metadata exposes: - `supports_connectivity_probe` - `probe_tool_name` (when probe-aware) - Do not add tool-specific ad-hoc metadata fields when canonical ones fit. ## Test Requirements - Add or update: - schema contract/snapshot tests - registry/governance registration tests - authentication contract/registry tests (especially probe-aware contracts) - response envelope tests for write mode (`dry-run` vs `apply`) - Prefer focused unit tests over broad end-to-end tests unless behavior spans components. ## Automated Enforcement - Internal maintainability rule `IXTOOL001` validates write-capable tool schemas under `IntelligenceX.Tools/**`. - Internal maintainability rule `IXTOOL003` validates `max_results` metadata helper usage under `IntelligenceX.Tools/**`. - The rule flags `ToolDefinition` entries with non-null `writeGovernance` that do not use: - `WithWriteGovernanceDefaults()` - `WithWriteGovernanceAndAuthenticationProbe()` - `IXTOOL003` flags direct `meta.Add("max_results", ...)` and requires `AddMaxResultsMeta(...)`. - Local verification command: - `dotnet run --project IntelligenceX.Cli/IntelligenceX.Cli.csproj --framework net8.0 -- analyze run --workspace . --config .intelligencex/reviewer.json --out artifacts --pack intelligencex-maintainability-default --strict true` - `dotnet run --project IntelligenceX.Cli/IntelligenceX.Cli.csproj --framework net8.0 -- analyze gate --workspace . --config .intelligencex/reviewer.json` ## Reusable Scaffold Assets - Tool template: - `templates/write-tool-template.cs.txt` - Test template: - `templates/write-tool-tests-template.cs.txt` - Pre-PR checklist helper: - `scripts/new-write-tool-checklist.ps1` ## Suggested Execution Order 1. Copy the tool template and replace `__PLACEHOLDER__` markers. 2. Register schema + write/auth contracts before implementing business logic. 3. Return mutating responses via `ToolResponse.OkWriteActionModel(...)`. 4. Copy test template and wire tool-specific argument names and expected contracts. 5. Run checklist script and fix all failing checks before opening PR. ## Special Cases (Read + Write Dual-Mode Tools) - For tools that can run safely in read-only mode and mutating mode (for example shell tools): - keep read-only path default - require explicit intent switch for write path - enforce governance only on write-intent calls ## Runtime Policy Integration (Host/Service) - Do not hand-wire per-tool runtime guardrails in app code. - Use centralized runtime policy bootstrap so host/service stay aligned: - write mode: `enforced|yolo` - audit sink mode/path: `none|file|sqlite` - auth runtime preset: `default|strict|lab` - run-as profile catalog path - Ensure tool packs consume shared runtime dependencies through pack options (for example shared auth probe store) instead of creating private per-tool stores in each runtime host.