@webpresso/plugin-codex 0.0.4

package/.codex-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "agent-kit",
+  "version": "0.0.4",
+  "description": "Webpresso agent-kit: blueprints, skills, hooks, and MCP server",
+  "author": {
+    "name": "Webpresso",
+    "url": "https://github.com/webpresso"
+  },
+  "homepage": "https://github.com/webpresso/agent-kit#readme",
+  "repository": "https://github.com/webpresso/agent-kit",
+  "license": "Elastic-2.0",
+  "keywords": ["agent", "blueprint", "mcp", "skills", "developer-tools"],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "hooks": "./hooks/hooks.json",
+  "interface": {
+    "displayName": "Webpresso agent-kit",
+    "shortDescription": "Blueprints, skills, hooks, and MCP tools.",
+    "developerName": "Webpresso",
+    "category": "Development",
+    "capabilities": ["Read", "Write"]
+  }
+}

package/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "webpresso": {
+    "command": "wp",
+    "args": ["mcp"],
+    "env": {
+      "WP_SKIP_UPDATE_CHECK": "1"
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,104 @@
+Elastic License 2.0
+===================
+
+Copyright (c) 2026 Webpresso, Inc.
+
+Acceptance
+----------
+
+By using the software, you agree to all of the terms and conditions below.
+
+Copyright License
+-----------------
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+Limitations
+-----------
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key
+functionality in the software, and you may not remove or obscure any
+functionality in the software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+Patents
+-------
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software.
+
+If you or your company make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license for the software
+granted under these terms ends immediately. If your company makes such a claim,
+your patent license ends immediately for work on behalf of your company.
+
+Notices
+-------
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+No Other Rights
+---------------
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+Termination
+-----------
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+No Liability
+------------
+
+As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.
+
+Definitions
+-----------
+
+The licensor is the entity offering these terms, and the software is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+you refers to the individual or entity agreeing to these terms.
+
+your company is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+control means ownership of substantially all the assets of an entity, or the
+power to direct its management and policies by vote, contract, or otherwise.
+Control can be direct or indirect.
+
+your licenses are all the licenses granted to you for the software under these
+terms.
+
+use means anything you do with the software requiring one of your licenses.
+
+trademark means trademarks, service marks, and similar rights.

package/bin/wp

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const shimPath = fileURLToPath(import.meta.url);
+
+function isExecutableFile(candidate) {
+  try {
+    const stat = statSync(candidate);
+    if (!stat.isFile()) return false;
+    if (process.platform !== "win32") accessSync(candidate, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function assertExecutableWp(candidate, label) {
+  if (isExecutableFile(candidate) && candidate !== shimPath) return candidate;
+  throw new Error(
+    `${label} points to ${candidate}, but that executable is not available. ` +
+      "Set WEBPRESSO_WP_BIN to the Webpresso wp executable, set WP_FORCE_JIT_PATH to an agent-kit checkout, or install the Webpresso app.",
+  );
+}
+
+function fixedAppWpLauncher() {
+  const home = process.platform === "win32" ? process.env.USERPROFILE || homedir() : homedir();
+  return process.platform === "win32"
+    ? join(home, ".webpresso", "bin", "wp.exe")
+    : join(home, ".webpresso", "bin", "wp");
+}
+
+function resolveWebpressoWp() {
+  const explicitPath = process.env.WEBPRESSO_WP_BIN;
+  const jitRoot = process.env.WP_FORCE_JIT_PATH;
+  if (explicitPath && jitRoot) {
+    throw new Error("WEBPRESSO_WP_BIN and WP_FORCE_JIT_PATH are both set; unset one.");
+  }
+  if (explicitPath) return assertExecutableWp(explicitPath, "WEBPRESSO_WP_BIN");
+  if (jitRoot) return assertExecutableWp(join(jitRoot, "bin", "wp"), "WP_FORCE_JIT_PATH");
+  return assertExecutableWp(fixedAppWpLauncher(), "Webpresso app launcher");
+}
+
+const result = spawnSync(resolveWebpressoWp(), process.argv.slice(2), {
+  stdio: "inherit",
+  env: {
+    ...process.env,
+    WP_SKIP_UPDATE_CHECK: process.env.WP_SKIP_UPDATE_CHECK ?? "1",
+  },
+});
+
+if (result.error) {
+  throw result.error;
+}
+
+process.exit(result.status ?? (result.signal ? 1 : 0));

package/hooks/hooks.json

@@ -0,0 +1,3 @@
+{
+  "hooks": {}
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@webpresso/plugin-codex",
+  "version": "0.0.4",
+  "private": false,
+  "description": "Codex plugin adapter for Webpresso agent-kit skills, hooks, and MCP runtime.",
+  "homepage": "https://github.com/webpresso/app#readme",
+  "bugs": {
+    "url": "https://github.com/webpresso/app/issues"
+  },
+  "license": "Elastic-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/webpresso/app.git",
+    "directory": "packages/plugin-codex"
+  },
+  "files": [
+    ".codex-plugin",
+    "plugin-skill-ownership.json",
+    ".mcp.json",
+    "skills/**/SKILL.md",
+    "skills/**/references/**",
+    "skills/**/LICENSE*",
+    "hooks",
+    "bin/wp",
+    "LICENSE",
+    "!README.md",
+    "!CHANGELOG.md",
+    "!**/*.test.js",
+    "!**/*.test.ts"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}

package/plugin-skill-ownership.json

@@ -0,0 +1,99 @@
+{
+  "schemaVersion": 1,
+  "host": "codex",
+  "packageName": "@webpresso/plugin-codex",
+  "packageVersion": "0.0.4",
+  "runtimeDirs": [".codex/skills", ".agents/skills"],
+  "skills": {
+    "ai-deslop": {
+      "digest": "sha256:c1da1003009073dd3923454947e1141efc2e7df5ad8d725a511ed5cff03bfb5c"
+    },
+    "autopilot": {
+      "digest": "sha256:cd97b441a78e2d3253ed3f8bcb8822b37684c7c8f0adba43f1d84987b678f528"
+    },
+    "autoresearch": {
+      "digest": "sha256:b4d51cd53beb4a3271827172dfbd0b1d27bd58761ca07a35d49a5d6324b87fdf"
+    },
+    "best-practice-research": {
+      "digest": "sha256:6d26b524d206067c7305da8a9334270f2525e4323aa3faa56ef02679e4d61849"
+    },
+    "browse": {
+      "digest": "sha256:21fd24862e7f7c8a1feadea6bc376492b136b99fc381cf1b8927c9db80615431"
+    },
+    "claude": {
+      "digest": "sha256:908367f139d3c3e033248be5e4b003475b01b62d4851ad1ff271079af76a53f8"
+    },
+    "codex": {
+      "digest": "sha256:9cf714ed78dafbb2370e8f6e4bee5f22db7d540444c4dd96540c8b8dd22bd4a4"
+    },
+    "deep-interview": {
+      "digest": "sha256:e5289c1299ef12cecd35ad713d1a1cb66d7f6a6c0c8029562612d6122af90cbc"
+    },
+    "deep-research": {
+      "digest": "sha256:01dafd194066a2936db0b437fd5c3beef6d7ff82478d0d995393093d89496f18"
+    },
+    "delivery-program": {
+      "digest": "sha256:b6ef474f3636c5fcc2b53dce014c022f2635cfeb32a9c698de8c7c21b37b4018"
+    },
+    "design-review": {
+      "digest": "sha256:5b213735e2842568774572f36b198bccf03c03a54b2732484aadd023f04acb23"
+    },
+    "devex-review": {
+      "digest": "sha256:306355888da0827e3523022077f731845726bbaaf595ca12515cc91d8605b5e6"
+    },
+    "fix": {
+      "digest": "sha256:46d75461d262e35c5f5a7f344464ea013cc29258419db66c2a5ff881af72e196"
+    },
+    "grok": {
+      "digest": "sha256:796104b04f70c8dd48cf1056c8d72d9492648f89486a35515e00af1d0de42f0a"
+    },
+    "hooks-doctor": {
+      "digest": "sha256:c7bbfcea5822702ff8b940140eb7f79b4ab05b3e0eee6c82e79bd6cc30b27329"
+    },
+    "investigate": {
+      "digest": "sha256:778b3a1f38323e8dd6101c6ace26ff8aada1246b20952b3641d5d1049bc50055"
+    },
+    "lore-protocol": {
+      "digest": "sha256:a80fbacc765e8b886437b9fdf7dd71e1ceb1b98b939078ec90fc88d06a8b4c69"
+    },
+    "opencode-go": {
+      "digest": "sha256:c9d9e2c59a4e0c895ddd92c5bc5a55d9feb670a9d44cedb96a893eb2aa9cfd7b"
+    },
+    "plan-ceo-review": {
+      "digest": "sha256:4d426158518dd71f8998770e8d4037bcbfa3c65d7265a93a4a78a9b015ba881e"
+    },
+    "plan-design-review": {
+      "digest": "sha256:a8a33efe67844d0602ff595c0b7e8f5529e52f51a781112952636c91963ce19e"
+    },
+    "plan-devex-review": {
+      "digest": "sha256:a49b4f61f1c54a7d89111c270616684dcbf2a7236bc817fafb5919366a7cda31"
+    },
+    "plan-eng-review": {
+      "digest": "sha256:b728dad90254d4c9f81b3818321d34ab53519b79ce20ff3bfe08bfacb2aa3e86"
+    },
+    "plan-refine": {
+      "digest": "sha256:fb883aa53d933324a7979301ca452aed356a8b452827e3695703fb16ccd9e236"
+    },
+    "ralplan": {
+      "digest": "sha256:db285d477f43ed23df990d4c03750d9916cdc7809356c1bf025efdf6a9add9ed"
+    },
+    "team": {
+      "digest": "sha256:bf9843f11c2c683bb0e0929c4030a728a93c5ff8087f2c3dc43b88faa7cbd427"
+    },
+    "tech-debt": {
+      "digest": "sha256:8b1f30e55ec6e5ab185ff19ecf15384438dbd619f675c2c65f2e53cedecbae5c"
+    },
+    "testing-philosophy": {
+      "digest": "sha256:43fa05bcb7eaf8efd4a8dcc0f9fb9c30ae9f80079d9b3dbfdc926734a64a2973"
+    },
+    "tph": {
+      "digest": "sha256:bed3684a850651534f315d355cdeae50d951c429817df0f105cccdb7f4e1561b"
+    },
+    "ultragoal": {
+      "digest": "sha256:338952843c8f6b884a18be434daf5b2e190093796b3524e264e6f2c714bd01e1"
+    },
+    "verify": {
+      "digest": "sha256:0eaa83fa98b39aeb1b3616301cfb22fea7897a1e16c589986febb29811c5a73f"
+    }
+  }
+}

package/skills/ai-deslop/SKILL.md

@@ -0,0 +1,91 @@
+---
+type: skill
+slug: ai-deslop
+title: AI Deslop
+status: active
+scope: repo
+applies_to: [agents]
+related: [fix, verify, investigate]
+created: "2026-07-16"
+last_reviewed: "2026-07-16"
+name: ai-deslop
+description: "Bounded anti-slop cleanup pass: simplify, delete noise, or review-only with --review."
+license: MIT
+upstream:
+  source: https://github.com/Yeachan-Heo/oh-my-claudecode/tree/590fb988931d34a12604be0ca4215c818079018e/skills/ai-slop-cleaner
+  last_synced: "2026-07-16"
+argument-hint: "[--review] <files|path|scope>"
+---
+
+# AI Deslop
+
+Use this skill after behavior is already correct but the resulting code or docs
+still feel bloated, repetitive, over-scaffolded, or obviously machine-shaped.
+
+## Boundary
+
+- `ai-deslop` is a cleanup pass, not a feature lane.
+- Preserve behavior. If the work needs a logic change, route back to `fix`.
+- Prefer deletion and simplification over new abstraction.
+- Keep scope bounded to the requested files, changed files, or clearly named
+  area. Do not expand into broad redesign.
+
+## When to use it
+
+- The user explicitly asks to deslop, clean up AI slop, simplify, or trim noise.
+- A completed feature still contains dead code, duplicate helpers, wrapper
+  layers, weak boundaries, or generated-sounding prose/comments.
+- `verify` finds stale compatibility branches, cargo-cult abstractions, or
+  cleanup debt after the behavioral proof is already green.
+- The user wants a reviewer-only anti-slop pass via `--review`.
+
+## When not to use it
+
+- Behavior is still failing or root cause is not established.
+- The request is really a new feature, redesign, or semantic refactor.
+- Verification is too weak to protect preserved behavior.
+
+## Modes
+
+### Standard mode
+
+1. Lock behavior first with the narrowest regression proof available.
+2. Write a short cleanup plan naming the concrete slop to remove.
+3. Classify each smell:
+   - dead code / unused exports
+   - duplication / needless wrappers
+   - compatibility scaffolding that no longer serves a consumer
+   - noisy comments, docs, or prompts that restate the obvious
+   - weak boundaries or helper proliferation with no clear owner
+4. Apply the smallest safe deletions and consolidations first.
+5. Re-run the same scoped verification after each meaningful pass.
+
+### Review mode (`--review`)
+
+Use this to review a drafted cleanup pass without writing code.
+
+1. Inspect the cleanup plan, changed files, and verification evidence.
+2. Look specifically for leftover dead code, duplicate logic, needless
+   abstraction, and accidental behavior drift.
+3. Return a verdict plus required follow-ups.
+4. Do not both write and self-approve the same high-impact cleanup pass.
+
+## Verification
+
+Run only the narrowest checks that protect preserved behavior:
+
+- targeted tests
+- targeted lint/typecheck
+- any changed docs or command-surface checks
+
+If the cleanup touches shared/public surfaces or broad repo-owned docs, hand the
+result to `verify` before calling it done.
+
+## Output
+
+Return:
+
+- cleanup scope
+- slop classes removed
+- proof that behavior stayed locked
+- remaining follow-ups, if any

package/skills/autopilot/SKILL.md

@@ -0,0 +1,77 @@
+---
+type: skill
+slug: autopilot
+title: Autopilot
+status: active
+scope: repo
+applies_to: [agents]
+related: [goal, plan-refine, verify, testing-philosophy, ultragoal, fix]
+created: "2026-07-10"
+last_reviewed: "2026-07-21"
+name: autopilot
+description: "Drive a brief through the bounded native goal pipeline."
+argument-hint: "<brief|force: brief>"
+---
+
+# Autopilot
+
+Drive an approved brief through `plan -> execute -> qa -> validate -> land -> complete`
+using `wp_ultragoal_run` / `wp ultragoal run` and the current handoff.
+
+## Outside-voice (required)
+
+After each ultragoal **phase or plan-gate milestone**, run an **OpenCode Go** outside-voice review and pick the model by purpose. The purpose→family ordering lives in one place — the committed reviewer policy rendered into the `opencode-go` skill — so follow that skill and do not restate the ordering here. Resolve IDs from live `opencode models opencode-go`. `wp_review_gate` is only for exact-version draft plan approval/auto-promotion; `wp_review_run` is advisory for implementation/phase review and never mutates blueprint approval state. Never self-approve. Full protocol: the `ultragoal` skill. Respect `review_budget` (default owned by `workflow-skills-routing.md`): one sequential path, no multi-host stampede.
+
+## Vague gate
+
+A brief is anchored when it includes a file path, symbol, issue number, test name, or numbered steps
+(blueprint slug and explicit budgets also count). Route any unanchored brief through
+`plan-refine` before execution.
+
+**Reject** (unless rewritten with scope + budgets): “complete all”, “full autopilot”,
+“go to sleep”, “elegantly merge everything” without a named blueprint/PR set.
+
+A leading `force:` is the only explicit bypass; strip it before creating the goal and
+record the bypass in the blueprint.
+
+Default budgets if the user omits them: `concurrency=4`, `fix_budget=1`, no
+`/loop`; `review_budget` per `workflow-skills-routing.md`. See `ultragoal`
+skill.
+
+## Tooling map
+
+| Pipeline step        | Tools                                                                                                                                               |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Plan                 | `plan-refine`, `wp_blueprint_*`, `wp_session_capture` for decisions                                                                                 |
+| Create controller    | `wp_ultragoal_new`, `wp_worktree`                                                                                                                   |
+| Execute              | ready-set via blueprint tools; `/goal` or parallel subagents; `wp_session_context` for delegates; `wp_blueprint_task_verify` only to complete tasks |
+| Opportunistic repair | `/fix` up to `fix_budget`; else handoff backlog                                                                                                     |
+| QA                   | `wp_qa` / `wp_lint` / `wp_typecheck` / `wp_test`; PR checks via `wp_pr_status` / `wp_pr_wait`                                                       |
+| Validate             | one outside voice if merge-bound (OpenCode Go by purpose, or claude/codex/grok); `wp review gate` for authority                                     |
+| Land                 | `wp_pr_upsert`, green required checks, merge + owner cleanup                                                                                        |
+| Blocked / stop       | `wp_ultragoal_handoff` ≤40 lines; `wp_ultragoal_cancel` if abandoned                                                                                |
+
+## Pipeline
+
+1. **Plan:** refine blueprints and satisfy provenance-backed promotion approvals.
+2. **Execute:** implement current **ready** tasks in parallel up to `concurrency`; use only
+   `wp_blueprint_task_verify` to mark them done.
+3. **QA:** run affected checks and `wp_qa`; preserve normalized failure evidence. Prefer
+   PR-bound CI when a PR exists.
+4. **Validate:** obtain verification + code-review evidence within `review_budget`. Each
+   lane appends a tracked `reviews.md` record in one of these exact forms:
+
+   ```text
+   <!-- wp:goal-validation {"kind":"verify","reviewer":"<identity>","artifact":"<tracked-path>"} -->
+   <!-- wp:goal-validation {"kind":"code-review","reviewer":"<different-identity>","artifact":"<tracked-path>"} -->
+   ```
+
+5. **Land:** require green PR checks, complete the blueprint in the same PR, merge, and
+   run owner cleanup.
+6. **Complete:** stop only when `wp_ultragoal_run` records terminal evidence.
+
+Resume from durable state after interruption. Obey `WP_ULTRAGOAL_DISABLE=1`,
+iteration/error/validation caps, and repository ownership. Never self-approve, directly
+mark tasks done, bypass evidence, push to main, or increase timeouts (keep every loop bounded and never increase timeouts). After every phase
+transition recorded by `wp ultragoal run`, obtain a fresh OpenCode Go outside review
+before treating the milestone as closed (see Outside-voice above and the `ultragoal` skill).

package/skills/autoresearch/SKILL.md

@@ -0,0 +1,49 @@
+---
+type: skill
+slug: autoresearch
+title: Autoresearch
+status: active
+scope: repo
+applies_to: [agents]
+related: [deep-research, best-practice-research, plan-refine, verify]
+created: "2026-07-13"
+last_reviewed: "2026-07-13"
+name: autoresearch
+description: "Artifact-gated research loop with explicit validation."
+argument-hint: "<research mission and validator>"
+---
+
+# Autoresearch
+
+Use when the user wants research to continue until a concrete validator accepts the result. This is for bounded research deliverables, not quick factual lookup or ordinary planning context.
+
+## Boundary
+
+- Use `deep-research` for one-pass citation-backed reports.
+- Use `best-practice-research` for focused upstream guidance.
+- Use `autoresearch` when completion depends on an explicit evaluator, benchmark, review rubric, or acceptance artifact.
+
+## Workflow
+
+1. Define the research mission, output artifact path, validator, and stop condition.
+2. Choose one validation mode:
+   - command validator: a repo command or script must pass and write the result.
+   - review validator: an independent review must approve the produced artifact against the mission.
+3. Create or update the durable research artifact before iterating.
+4. Gather sources and repo context until the artifact addresses the mission and cites material claims.
+5. Run the validator. If it fails, preserve the failure evidence, revise the artifact, and repeat.
+6. Stop only when the validator passes or a blocker prevents more evidence-gathering.
+
+## Output
+
+Return:
+
+- mission
+- artifact path
+- validation mode
+- validator command or review rubric
+- evidence gathered
+- pass/fail result
+- remaining gaps or blocker
+
+Do not treat elapsed turns, model confidence, or a draft report as completion evidence. Completion requires the declared validator to pass.

package/skills/best-practice-research/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: best-practice-research
+description: "Official/upstream best-practice research wrapper with bounded evidence and dated citations."
+argument-hint: "<technology|decision|practice question>"
+---
+
+# Best-Practice Research
+
+Use this skill when a task depends on current external best practices, version-aware guidance, standards, official recommendations, or upstream behavior. This is a workflow wrapper: it routes evidence gathering and synthesis; it is not a new research authority and it does not replace the `deep-research` skill.
+
+## Purpose
+
+Produce a cited, reusable best-practice answer or handoff that separates current external evidence from repo-local facts and dependency-selection decisions.
+
+## Activate When
+
+- The user asks for best practices, recommended approach, current guidance, official recommendations, standards, or version-aware external behavior.
+- `$ralplan`, `$team`, or another workflow needs current external evidence before planning or execution can be correct.
+- The task involves an already chosen technology and needs authoritative usage guidance, migration notes, API behavior, lifecycle rules, or current safety guidance.
+
+## Do Not Activate When
+
+- The answer is fully repo-local; use `explore` for codebase facts.
+- The main question is whether to adopt, replace, upgrade, or compare dependencies — that decision is out of scope; inform it with evidence but return the choice to the caller.
+- The user only needs implementation against already-grounded requirements; hand off to the caller's execution workflow (`$team` or `$ralplan`) as appropriate.
+- The task can be answered from stable local project conventions without current external lookup.
+
+## Specialist Routing
+
+1. Use `explore` first for brownfield facts: current code usage, local constraints, versions, config, and integration points.
+2. Gather official/upstream docs, release notes, standards, migration guides, and source-backed evidence yourself with web search and doc fetches; escalate to the `deep-research` skill for exhaustive multi-source research on an already chosen technology.
+3. Adoption / upgrade / replacement / comparison decisions are out of scope: surface the evidence, but return the decision to the caller.
+4. Return to the caller with explicit evidence, uncertainty, and any implementation handoff constraints.
+
+## Source-Quality Rules
+
+- Prefer official documentation, upstream source, release notes, changelogs, standards, and maintainer guidance.
+- Include source URLs for material claims.
+- State date/version context for current best-practice claims.
+- Label third-party summaries as supplemental; do not use them before official/upstream sources.
+- Flag stale, conflicting, undocumented, or version-mismatched evidence.
+- Do not over-fetch: gather the smallest evidence set that can support the decision.
+
+## Workflow
+
+1. Classify the question: conceptual best practice, implementation guidance, migration/version guidance, standards/compliance guidance, or mixed local + external guidance.
+2. Gather repo-local facts with `explore` when local usage or constraints affect the answer.
+3. Gather external evidence with web search and official-doc fetches (escalate to the `deep-research` skill for depth) when current or version-aware practice affects correctness.
+4. Synthesize a concise answer with source quality, version/date context, caveats, and an implementation or planning handoff.
+5. Stop when the answer is grounded enough for the caller; otherwise report the exact blocker or specialist handoff needed.
+
+## Output Contract
+
+```md
+## Best-Practice Research: <question>
+
+### Direct Recommendation
+
+<actionable guidance or decision support>
+
+### Evidence Used
+
+- Official/upstream: <source URL> — <what it establishes>
+- Supplemental, if any: <source URL> — <why it is secondary>
+
+### Version / Date Context
+
+<versions, dates, release channels, or unknowns>
+
+### Repo-Local Context
+
+<facts from explore, or "not needed">
+
+### Boundaries / Non-goals
+
+<what this research does not decide>
+
+### Handoff
+
+<planning/execution/test implications>
+```
+
+## Stop Rules
+
+- Stop after a source-backed recommendation is reusable by the caller.
+- Stop and route upward if the task becomes dependency comparison, broad architecture, or implementation.
+- Do not continue researching when remaining work would only polish wording rather than change the recommendation.
+
+Task: {{ARGUMENTS}}