@rudderhq/agent-runtime-opencode-local 0.5.0 → 0.5.1

package/skills/rudder-create-agent/references/api-reference.md

@@ -1,179 +0,0 @@
-# Rudder Create Agent API Reference
-
-Internal/debug reference for the bundled `rudder-create-agent` skill.
-
-- Normal runtime execution should follow the CLI-first workflow in `../SKILL.md`.
-- The canonical command catalog lives in `cli-reference.md`.
-- Keep this document for route-level debugging, compatibility work, and payload-shape inspection.
-
-## CLI-to-API Mapping
-
-| CLI command | Primary route |
-| --- | --- |
-| `rudder agent config index` | `GET /llms/agent-configuration.txt` |
-| `rudder agent config doc <agentRuntimeType>` | `GET /llms/agent-configuration/:agentRuntimeType.txt` |
-| `rudder agent config list --org-id <orgId>` | `GET /api/orgs/:orgId/agent-configurations` |
-| `rudder agent config get <agentId>` | `GET /api/agents/:agentId/configuration` |
-| `rudder agent hire --org-id <orgId> --payload <json>` | `POST /api/orgs/:orgId/agent-hires` |
-| `rudder approval get <approvalId>` | `GET /api/approvals/:approvalId` |
-| `rudder approval comment <approvalId> --body-file <path>` | `POST /api/approvals/:approvalId/comments` |
-| `rudder approval resubmit <approvalId> [--payload <json>]` | `POST /api/approvals/:approvalId/resubmit` |
-| `rudder approval issues <approvalId>` | `GET /api/approvals/:approvalId/issues` |
-
-## Reflection Endpoints
-
-- `GET /llms/agent-configuration.txt`
-- `GET /llms/agent-configuration/:agentRuntimeType.txt`
-
-Auth:
-
-- board access, or
-- same-org agent auth with `canCreateAgents=true`
-
-These endpoints return plain text. The CLI wraps them directly.
-
-## Configuration Snapshots
-
-- `GET /api/orgs/:orgId/agent-configurations`
-- `GET /api/agents/:agentId/configuration`
-
-These responses are redacted snapshots for comparison and reuse.
-
-Representative shape:
-
-```json
-{
-  "id": "uuid",
-  "orgId": "uuid",
-  "name": "CTO",
-  "role": "cto",
-  "title": "Chief Technology Officer",
-  "status": "idle",
-  "reportsTo": "uuid-or-null",
-  "agentRuntimeType": "codex_local",
-  "agentRuntimeConfig": {
-    "cwd": "/absolute/path",
-    "model": "o4-mini"
-  },
-  "runtimeConfig": {
-    "heartbeat": {
-      "enabled": true,
-      "intervalSec": 300,
-      "wakeOnDemand": true,
-      "maxConcurrentRuns": 3
-    }
-  },
-  "permissions": {
-    "canCreateAgents": true
-  },
-  "updatedAt": "2026-04-19T12:00:00.000Z"
-}
-```
-
-## `POST /api/orgs/:orgId/agent-hires`
-
-Canonical hire route used by `rudder agent hire`.
-
-Request body:
-
-```json
-{
-  "role": "cto",
-  "title": "Chief Technology Officer",
-  "reportsTo": "uuid-or-null",
-  "capabilities": "Owns architecture and engineering execution",
-  "desiredSkills": ["vercel-labs/agent-browser/agent-browser"],
-  "agentRuntimeType": "codex_local",
-  "agentRuntimeConfig": {
-    "cwd": "/absolute/path",
-    "model": "o4-mini",
-    "promptTemplate": "# SOUL.md -- CTO Persona\n\nYou are the CTO.\n\n## Mission\nOwn technical strategy, architecture, engineering execution, and quality bars.\n\n## Responsibilities\n- Set technical direction and execution standards.\n- Review architecture and staffing trade-offs.\n- Keep delivery risks visible and actionable.\n\n## Boundaries\n- Do not approve risky shortcuts without naming the trade-off.\n- Escalate product or budget ambiguity instead of guessing.\n\n## Decision Principles\n- Prefer simple architectures with explicit trade-offs.\n- Treat reliability, developer velocity, and product learning as linked constraints.\n\n## Voice\nDirect, specific, and evidence-led.\n\n## Continuity\nPreserve durable technical standards, repeated failure patterns, and long-running architecture decisions in memory or explicit instructions."
-  },
-  "runtimeConfig": {
-    "heartbeat": {
-      "enabled": true,
-      "intervalSec": 300,
-      "wakeOnDemand": true,
-      "maxConcurrentRuns": 3
-    }
-  },
-  "budgetMonthlyCents": 0,
-  "sourceIssueId": "uuid-or-null",
-  "sourceIssueIds": ["uuid-1", "uuid-2"]
-}
-```
-
-`role` is validated as a fixed enum: `ceo`, `cto`, `cmo`, `cfo`, `engineer`, `designer`, `pm`, `qa`, `devops`, `researcher`, `general`.
-Use `title`, `capabilities`, and `agentRuntimeConfig.promptTemplate` for narrower job titles. For example, a Founding Engineer should be submitted as `"role": "engineer"` and `"title": "Founding Engineer"`.
-
-Response when approval is required:
-
-```json
-{
-  "agent": {
-    "id": "uuid",
-    "status": "pending_approval"
-  },
-  "approval": {
-    "id": "uuid",
-    "type": "hire_agent",
-    "status": "pending",
-    "payload": {
-      "desiredSkills": ["vercel-labs/agent-browser/agent-browser"]
-    }
-  }
-}
-```
-
-Response when approval is not required:
-
-```json
-{
-  "agent": {
-    "id": "uuid",
-    "status": "idle"
-  },
-  "approval": null
-}
-```
-
-Important notes:
-
-- `name` is optional; if omitted or blank, Rudder assigns a distinct first name automatically
-- `icon` is optional; omit it for normal hires so Rudder generates a DiceBear Notionists avatar automatically
-- only pass `icon` when the board/UI supplied an explicit DiceBear Notionists reference or uploaded `asset:<uuid>` image avatar reference
-- `desiredSkills` accepts organization skill ids, canonical keys, or a unique slug; the server resolves and stores canonical organization skill keys
-- `agentRuntimeConfig.promptTemplate`, when present for local runtimes during hire, is role/persona content that Rudder materializes as managed `SOUL.md`
-- write hire-time `promptTemplate` as a durable SOUL document with mission, responsibilities, boundaries, decision principles, voice, and continuity when the role has ongoing authority
-- do not put Rudder's shared operating contract in `promptTemplate`; supported local runtimes inject that contract from code
-- `sourceIssueId` and `sourceIssueIds` are the canonical way to link the hire back to originating issues
-- this route is preferred over creating `hire_agent` approvals manually because it preserves the organization's approval policy
-
-## Approval Lifecycle
-
-Relevant routes:
-
-- `GET /api/approvals/:approvalId`
-- `POST /api/approvals/:approvalId/comments`
-- `POST /api/approvals/:approvalId/resubmit`
-- `GET /api/approvals/:approvalId/issues`
-
-Statuses:
-
-- `pending`
-- `revision_requested`
-- `approved`
-- `rejected`
-- `cancelled`
-
-For hire approvals:
-
-- approved: linked agent transitions `pending_approval -> idle`
-- rejected: linked agent is terminated
-
-## Safety Notes
-
-- Config read APIs redact obvious secrets.
-- `pending_approval` agents cannot run heartbeats, receive assignments, or create keys.
-- All hire and approval actions are logged in activity for auditability.
-- Use markdown in issue and approval comments and include links to the approval, agent, and source issue.

package/skills/rudder-create-agent/references/cli-reference.md

@@ -1,132 +0,0 @@
-# Rudder Create Agent CLI Reference
-
-Canonical CLI contract for the bundled `rudder-create-agent` skill. Prefer these commands over direct `/api` calls.
-
-## Defaults
-
-- All commands support `--json`.
-- `--org-id` defaults to `RUDDER_ORG_ID` when relevant.
-- Mutating commands attach `RUDDER_RUN_ID` automatically when available.
-- `agent config index` and `agent config doc` print plain text by default. With `--json`, they emit that text as a JSON string.
-
-## Core CLI Surface
-
-### Identity and discovery
-
-```sh
-rudder agent me --json
-rudder agent list --org-id "$RUDDER_ORG_ID" --json
-rudder agent get "<agent-id-or-shortname>" --org-id "$RUDDER_ORG_ID" --json
-rudder agent config index
-rudder agent config doc "<agent-runtime-type>"
-rudder agent config list --org-id "$RUDDER_ORG_ID" --json
-rudder agent config get "<agent-id-or-shortname>" --org-id "$RUDDER_ORG_ID" --json
-```
-
-Use these in order:
-
-1. `agent me` to verify auth and org context
-2. `agent config index` to discover installed runtimes
-3. `agent config doc` to read one runtime's required fields and examples
-4. `agent list` plus `agent config list/get` to reuse proven patterns from related agents
-
-### Organization skills
-
-```sh
-rudder skill list --org-id "$RUDDER_ORG_ID" --json
-rudder skill get "<skill-id>" --org-id "$RUDDER_ORG_ID" --json
-rudder skill file "<skill-id>" --org-id "$RUDDER_ORG_ID" --path SKILL.md --json
-rudder skill import --org-id "$RUDDER_ORG_ID" --source "<source>" --json
-rudder skill scan-local --org-id "$RUDDER_ORG_ID" --roots "<csv>" --json
-rudder skill scan-projects --org-id "$RUDDER_ORG_ID" --project-ids "<csv>" --workspace-ids "<csv>" --json
-```
-
-Use these before hiring when the new role needs `desiredSkills`.
-
-`desiredSkills` accepts:
-
-- exact organization skill key
-- exact organization skill id
-- exact slug when it is unique in the organization
-
-### Canonical hire flow
-
-```sh
-rudder agent hire --org-id "$RUDDER_ORG_ID" --payload '{
-  "role": "cto",
-  "title": "Chief Technology Officer",
-  "reportsTo": "<ceo-agent-id>",
-  "capabilities": "Owns technical roadmap, architecture, staffing, execution",
-  "desiredSkills": ["vercel-labs/agent-browser/agent-browser"],
-  "agentRuntimeType": "codex_local",
-  "agentRuntimeConfig": {
-    "cwd": "/abs/path/to/repo",
-    "model": "o4-mini",
-    "promptTemplate": "# SOUL.md -- CTO Persona\n\nYou are the CTO.\n\n## Mission\nOwn technical strategy, architecture, engineering execution, and quality bars.\n\n## Responsibilities\n- Set technical direction and execution standards.\n- Review architecture and staffing trade-offs.\n- Keep delivery risks visible and actionable.\n\n## Boundaries\n- Do not approve risky shortcuts without naming the trade-off.\n- Escalate product or budget ambiguity instead of guessing.\n\n## Decision Principles\n- Prefer simple architectures with explicit trade-offs.\n- Treat reliability, developer velocity, and product learning as linked constraints.\n\n## Voice\nDirect, specific, and evidence-led.\n\n## Continuity\nPreserve durable technical standards, repeated failure patterns, and long-running architecture decisions in memory or explicit instructions."
-  },
-  "runtimeConfig": {"heartbeat": {"enabled": true, "intervalSec": 300, "wakeOnDemand": true, "maxConcurrentRuns": 3}},
-  "sourceIssueId": "<issue-id>"
-}' --json
-```
-
-Canonical semantics:
-
-- this wraps `POST /api/orgs/:orgId/agent-hires`
-- if the organization does not require board approval, the response contains `approval: null` and the agent is created directly
-- if the organization requires board approval, the response contains both `agent` and `approval`, and the new agent stays `pending_approval`
-
-Do not use `rudder approval create --type hire_agent` as a replacement for `agent hire` during normal skill execution. That is a lower-level compatibility surface and does not preserve the canonical direct-create behavior.
-
-`agentRuntimeConfig.promptTemplate`, when used during hire, is for role/persona content. Rudder materializes it as the managed instruction bundle's `SOUL.md`. Write it as a durable SOUL document with mission, responsibilities, boundaries, decision principles, voice, and continuity when the role has ongoing authority. Do not include Rudder's shared operating contract in this field; supported local runtimes inject that contract from code.
-
-### Approval follow-up
-
-```sh
-rudder approval get "<approval-id>" --json
-rudder approval comment "<approval-id>" --body-file "<path>" --json
-rudder approval resubmit "<approval-id>" --payload '{"...":"..."}' --json
-rudder approval issues "<approval-id>" --json
-```
-
-Notes:
-
-- `approval comment` should use markdown and link the approval, pending agent, and source issue when available
-- `approval resubmit` is only for a revision-requested approval; update the payload instead of creating a second hire
-- if the run wakes with `RUDDER_APPROVAL_ID`, treat that approval as the first task
-
-## Payload Notes
-
-The `agent hire` payload accepts the same shape as the hire API, including:
-
-- `name` optional; blank or omitted means Rudder assigns a distinct first name
-- `role`: one of `ceo`, `cto`, `cmo`, `cfo`, `engineer`, `designer`, `pm`, `qa`, `devops`, `researcher`, `general`
-- `title`
-- `icon` optional; omit it for normal hires so Rudder generates a DiceBear Notionists avatar automatically. Only provide an explicit DiceBear reference or uploaded `asset:<uuid>` image avatar reference when the board/UI supplied one.
-- `reportsTo`
-- `capabilities`
-- `desiredSkills`
-- `agentRuntimeType`
-- `agentRuntimeConfig`
-- `runtimeConfig`
-- `budgetMonthlyCents`
-- `metadata`
-- `sourceIssueId`
-- `sourceIssueIds`
-
-`role` is a fixed enum. Do not invent role keys such as `founding_engineer`, `frontend_engineer`, or `reviewer`. Use the closest enum value, then put the specialization in `title`, `capabilities`, and `agentRuntimeConfig.promptTemplate`; for example use `"role": "engineer"` with `"title": "Founding Engineer"`.
-
-Issue linkage rule:
-
-- prefer `sourceIssueId` or `sourceIssueIds` inside the hire payload
-- use `approval issues` to inspect the resulting approval links after the server creates them
-
-## Related Commands
-
-Post-hire adjustments use the normal agent and skill surfaces:
-
-```sh
-rudder agent get "<agent-id-or-shortname>" --org-id "$RUDDER_ORG_ID" --json
-rudder agent skills enable "<agent-id>" "<selection-ref>" --json
-rudder agent skills sync "<agent-id>" --desired-skills "<csv>" --json
-rudder agent local-cli "<agent-id-or-shortname>" --org-id "$RUDDER_ORG_ID" --json
-```

package/skills/rudder-create-plugin/SKILL.md

@@ -1,103 +0,0 @@
----
-name: rudder-create-plugin
-description: Create new Rudder plugins with the current alpha SDK/runtime. Use when scaffolding a plugin package, adding a new example plugin, or updating plugin authoring docs. Covers the supported worker/UI surface, route conventions, scaffold flow, and verification steps.
-  Create new Rudder plugins with the current alpha SDK/runtime. Use when
-  scaffolding a plugin package, adding a new example plugin, or updating plugin
-  authoring docs. Covers the supported worker/UI surface, route conventions,
-  scaffold flow, and verification steps.
-allowed-tools: 
-disable: true
----
-
-# Create a Rudder Plugin
-
-Use this skill when the task is to create, scaffold, or document a Rudder plugin.
-
-## 1. Ground rules
-
-Read these first when needed:
-
-1. `doc/engineering/PLUGIN_AUTHORING_GUIDE.md`
-2. `packages/plugins/sdk/README.md`
-3. `doc/engineering/PLUGIN_RUNTIME_CONTRACT.md` only for future-looking context
-
-Current runtime assumptions:
-
-- plugin workers are trusted code
-- plugin UI is trusted same-origin host code
-- worker APIs are capability-gated
-- plugin UI is not sandboxed by manifest capabilities
-- no host-provided shared plugin UI component kit yet
-- `ctx.assets` is not supported in the current runtime
-
-## 2. Preferred workflow
-
-Use the scaffold package instead of hand-writing the boilerplate:
-
-```bash
-pnpm --filter @rudderhq/create-rudder-plugin build
-node packages/plugins/create-rudder-plugin/dist/index.js <npm-package-name> --output <target-dir>
-```
-
-For a plugin that lives outside the Rudder repo, pass `--sdk-path` and let the scaffold snapshot the local SDK/shared packages into `.rudder-sdk/`:
-
-```bash
-pnpm --filter @rudderhq/create-rudder-plugin build
-node packages/plugins/create-rudder-plugin/dist/index.js @acme/plugin-name \
-  --output /absolute/path/to/plugin-repos \
-  --sdk-path /absolute/path/to/rudder/packages/plugins/sdk
-```
-
-Recommended target inside this repo:
-
-- `packages/plugins/examples/` for example plugins
-- another `packages/plugins/<name>/` folder if it is becoming a real package
-
-## 3. After scaffolding
-
-Check and adjust:
-
-- `src/manifest.ts`
-- `src/worker.ts`
-- `src/ui/index.tsx`
-- `tests/plugin.spec.ts`
-- `package.json`
-
-Make sure the plugin:
-
-- declares only supported capabilities
-- does not use `ctx.assets`
-- does not import host UI component stubs
-- keeps UI self-contained
-- uses `routePath` only on `page` slots
-- is installed into Rudder from an absolute local path during development
-
-## 4. If the plugin should appear in the app
-
-For bundled example/discoverable behavior, update the relevant host wiring:
-
-- bundled example list in `server/src/routes/plugins.ts`
-- any docs that list in-repo examples
-
-Only do this if the user wants the plugin surfaced as a bundled example.
-
-## 5. Verification
-
-Always run:
-
-```bash
-pnpm --filter <plugin-package> typecheck
-pnpm --filter <plugin-package> test
-pnpm --filter <plugin-package> build
-```
-
-If you changed SDK/host/plugin runtime code too, also run broader repo checks as appropriate.
-
-## 6. Documentation expectations
-
-When authoring or updating plugin docs:
-
-- distinguish current implementation from future spec ideas
-- be explicit about the trusted-code model
-- do not promise host UI components or asset APIs
-- prefer npm-package deployment guidance over repo-local workflows for production

package/skills/skill-optimizer/CHANGELOG.md

@@ -1,29 +0,0 @@
-# Changelog
-
-## v4.3 framing evidence hardening
-
-- Added sequencing guidance for requests that ask to optimize a skill after another live task: complete and verify the primary task first, then optimize from evidence.
-- Added explicit treatment of strong user corrections as high-signal evidence, especially framing corrections and wrong-abstraction-level failures.
-- Added framing checks for user outcome vs UI surface, scenario spine vs fixture rows, source of truth vs derivative signal, and product intent vs local convenience.
-- Relaxed the final response contract for larger workflows so the primary task result can be reported before concise skill changes.
-
-## v4.2 open-source package
-
-- Added package mode and open-source project structure guidance.
-- Added explicit adapter file lookup under `references/adapters/`.
-- Added packaging expectations for README, examples, evals, changelog, and distributable skill zip.
-- Preserved the generic analysis framework: core optimizer plus modular domain adapters.
-
-## v4.1 adapter hardening
-
-- Added explicit domain adapter use rule: source of truth, required inputs, review owner, authority gates, privacy, output template, validation cases, and must-not behaviors.
-- Added benchmark reporting split for trigger accuracy, patch-quality coverage, and downstream transfer.
-- Added warning that synthetic verifier scores are regression signals, not official leaderboard results.
-
-## v4.0 generic
-
-- Reframed Skill Optimizer from a software-focused hardening checklist into a domain-general analysis framework.
-- Added universal optimization lens covering purpose, triggers, inputs, workflow, tools, outputs, quality, safety, failure, and maintainability.
-- Moved domain-specific checks into modular adapter patterns.
-- Added trigger optimization guidance and benchmark mode.
-- Preserved strict patch safety around high-impact actions.

package/skills/skill-optimizer/SKILL.md

@@ -1,205 +0,0 @@
----
-name: skill-optimizer
-description: Improve, debug, benchmark, or refactor an existing Agent Skill from conversation evidence, execution traces, user corrections, eval failures, or target skill files. Use this skill whenever the user asks to optimize, harden, generalize, validate, benchmark, package, or turn observed behavior into durable skill changes. Produces evidence-based diagnosis, reviewable patches, trigger evals, validation cases, and safe next-run behavior; do not use it to perform the target skill's normal task.
----
-
-# Skill Optimizer
-
-## Mission
-
-Turn real usage evidence into safer, more reliable, easier-to-trigger, and easier-to-evaluate Agent Skills.
-
-This is a meta-skill. It does not merely rewrite prose. It analyzes the fit between a skill's purpose, trigger description, inputs, procedure, tools, outputs, risks, examples, and evaluations, then proposes small reviewable changes.
-
-## Use when
-
-Use this skill when the user asks to improve, optimize, debug, refactor, benchmark, validate, generalize, harden, package, or document another skill. Also use it when the user says the current conversation should be captured into a skill, or that a previous skill run exposed something that should happen differently next time.
-
-Do not use this skill for ordinary task execution. If the user asks to run the release skill, do not optimize the release skill unless they ask to improve it.
-
-## Modes
-
-- Diagnose: identify what should change without writing a patch.
-- Patch: produce a reviewable diff, replacement section, or revised `SKILL.md`.
-- Validate: create validation cases and failure-mode checks.
-- Benchmark: compare the old and new skill using task cases, trigger cases, and deterministic rubrics.
-- Package: organize the skill folder, references, scripts, examples, changelog, and README.
-
-## Required inputs
-
-Infer these from the conversation before asking follow-up questions:
-
-- target skill name and purpose
-- current `SKILL.md` and supporting files, if available
-- execution evidence: user request, tool use, output, corrections, mistakes, delays, or surprises
-- environment: chat, code agent, workspace agent, API, or another harness
-- intended optimization mode
-- risk level and write-action authority
-- sequencing constraints when optimization is requested after another live task
-
-If the target skill file is unavailable, do not fabricate an exact diff. Produce an inferred improvement plan, draft replacement sections, validation cases, and assumptions.
-
-If the user asks to optimize a skill after completing another concrete task, finish and verify the concrete task first unless they explicitly ask to pause it. Then optimize from the observed evidence. Do not interrupt the user's primary workflow just because this skill is mentioned.
-
-## Universal optimization lens
-
-Analyze every target skill through these lenses:
-
-1. Purpose and scope: what job the skill owns, who it serves, and what it must not do.
-2. Triggering and boundaries: description quality, should-trigger cases, near-negative cases, competing skills, and under/over-triggering risks.
-3. Inputs and assumptions: required inputs, source of truth, missing-data behavior, units, locale, time horizon, and user preferences.
-4. Workflow and decision rules: ordered steps, branch conditions, heuristics, stop conditions, escalation paths, and exception handling.
-5. Tools and authority: required tools, permissions, external writes, approvals, dry runs, and exact operations.
-6. Outputs and interfaces: templates, file formats, citations, links, machine-readable fields, handoff artifacts, and user-facing summaries.
-7. Quality bar and evaluation: success criteria, deterministic verifiers, examples, regression tests, trigger evals, and human review points.
-8. Safety, privacy, and policy: sensitive data, regulated advice, consent, audit trail, access control, retention, and harmful misuse.
-9. Failure and recovery: blocked states, retries, rollback, partial completion, cleanup, and user-visible status.
-10. Maintainability: concise instructions, bundled resources, changelog, version notes, known limitations, and portability across harnesses.
-
-Use `references/universal-optimization-lens.md` when a deeper diagnosis is needed.
-
-## Evidence rules
-
-Treat the current conversation as evidence, not as a script to memorize.
-
-For each important observation, capture:
-
-- Evidence: what happened or what the user corrected.
-- Root cause: why the current skill allowed it.
-- Durable change: what should be added, removed, or clarified.
-- Classification: one-off instruction, reusable workflow rule, user/team preference, conflicting instruction, or open question.
-
-Do not overfit one unusual task into a permanent rule. Convert it into a reusable rule only when it improves future behavior.
-
-Treat strong user corrections as high-signal evidence. Phrases like "no", "not this", "wrong direction", "first principles", or a correction from a component-level answer to a user-scenario answer usually indicate a framing failure, not just a missing detail. Capture:
-
-- the wrong abstraction level the previous run optimized for
-- the user's intended source of truth
-- what should have been downstream evidence rather than the starting point
-- how the target skill should avoid the same drift next time
-
-When the evidence comes from a multi-step execution, include the verification results, not only the final prose. A durable skill change should be grounded in what was requested, what was attempted, what was corrected, and what was ultimately validated.
-
-## Framing and abstraction checks
-
-Before proposing a patch, ask whether the target skill optimized the right object:
-
-- User outcome vs. UI surface: a feature or component may be only a view over a deeper workflow.
-- Scenario spine vs. fixture rows: realistic data should come from causal user activity, not isolated screen states.
-- Source of truth vs. derivative signal: logs, runs, issues, costs, or decisions may be primary; dashboards, calendars, and summaries may be downstream.
-- Product intent vs. local convenience: read available product, requirement, or reference docs before encoding a domain rule from one conversation.
-
-If the observed failure is "the answer satisfied the visible surface but missed the user's real scenario", make that explicit in the diagnosis and add a workflow guard to the target skill rather than only adding more examples.
-
-## Patch rules
-
-Prefer small, auditable patches over broad rewrites. Preserve the target skill's identity, useful examples, and safety constraints.
-
-A patch may change:
-
-- frontmatter description and trigger boundaries
-- required inputs and assumptions
-- workflow steps and decision rules
-- output templates
-- safety and approval requirements
-- failure handling
-- examples and references
-- validation cases and benchmark tasks
-
-Never silently weaken safety requirements. For write actions, publishing, financial actions, medical or legal consequences, hiring decisions, external communication, deletion, deployment, migration, or permissions changes, require explicit authority unless the target skill already has a clear safe policy.
-
-## Trigger optimization
-
-The frontmatter description is the primary discovery signal. After improving a skill, evaluate whether the description should change.
-
-Create trigger evals with:
-
-- realistic should-trigger queries
-- realistic should-not-trigger near misses
-- ambiguous cases where another skill might be more appropriate
-- casual phrasing, typos, file paths, role context, and domain language
-
-Optimize for accurate triggering, not maximum triggering.
-
-## Domain adaptation
-
-This skill is domain-general. Do not bake one domain's checklist into the core instructions.
-
-When the domain matters, attach or consult a short domain adapter. A good adapter names:
-
-- source of truth
-- required inputs
-- review owner
-- consequential actions and approval gates
-- privacy, confidentiality, or consent constraints
-- output template
-- validation cases and deterministic checks
-- must-not behaviors
-
-Use the transcript to extract observed domain markers, but do not encode hidden rubric terms or unrelated best practices as mandatory rules. Keep adapters modular so the optimizer can handle software, healthcare operations, law, finance, education, research, HR, customer support, operations, creative work, personal productivity, and other workflows.
-
-Use `references/domain-adapter-patterns.md` when building or selecting an adapter. If a matching file exists under `references/adapters/`, consult it as a compact checklist rather than copying it wholesale into the target skill.
-
-## Validation format
-
-Every meaningful behavior change needs at least one validation case.
-
-Use this format:
-
-```md
-### Case: <name>
-
-Input:
-...
-
-Expected behavior:
-...
-
-Must not:
-...
-```
-
-Include at least one normal case, one edge case, and one regression case when the change could break prior behavior.
-
-## Benchmark reporting
-
-When running evals, separate three scores:
-
-1. Trigger accuracy: whether Skill Optimizer should activate.
-2. Patch-quality coverage: whether the proposed change includes evidence, scope classification, patch, safety, outputs, and validation.
-3. Downstream transfer: whether the optimized target skill actually improves on its own task suite.
-
-Label synthetic verifier scores as synthetic. Do not report them as official benchmark or leaderboard results.
-
-## Packaging expectations
-
-When packaging a skill or skill optimizer project, include:
-
-- `SKILL.md` and supporting references
-- README with purpose, installation, usage, eval, limitations, and license
-- changelog and version note
-- examples of target skills and optimization outputs
-- eval cases or a lightweight benchmark harness when available
-- a distributable zip that contains exactly one skill folder for installation
-
-## Final response contract
-
-Return these sections unless the user asks for a narrower result:
-
-1. Target skill and optimization mode
-2. Diagnosis summary
-3. Evidence ledger
-4. Improvement categories
-5. Proposed patch or revised skill draft
-6. Trigger eval suggestions when discovery may change
-7. Validation cases
-8. Benchmark or eval result, if run
-9. Assumptions, conflicts, and unresolved questions
-
-When direct file editing is available and the user explicitly requested edits, apply the patch. Otherwise present a reviewable patch.
-
-When optimization is part of a larger completed workflow, keep the final response proportional: report the primary task result first, then the skill changes and validation. Do not force the full nine-section contract if it would obscure the work the user was actually trying to finish.
-
-## Quality bar
-
-A successful optimization makes the next run of the target skill more predictable, easier to trigger correctly, safer around irreversible actions, clearer in output, and easier to verify.

package/skills/skill-optimizer/references/adapters/creative-brand-content.md

@@ -1,30 +0,0 @@
-# Creative, Brand, and Content Skill Optimization Adapter
-
-    ## Sources of truth
-    - Brand guide, campaign brief, rights/licensing records, channel specs, localization glossary.
-
-## Required inputs
-- audience
-- channel
-- brand voice
-- claims that need substantiation
-- rights and review owner
-
-## Risk gates
-- legal/brand review for external content
-- rights/licensing check
-- accessibility and localization review
-
-## Output expectations
-- creative brief, draft, claims table, review checklist, channel variants
-
-## Must not
-- must not make unsupported claims
-- must not use unlicensed content
-- must not ignore accessibility/localization constraints
-
-## Validation prompts
-
-- What normal case proves the improvement works?
-- What edge case catches missing context or low confidence?
-- What regression case prevents the old failure from returning?