openclaw system prompt

--- name: docs-framework-agent description: Thinking-focused docs framework checker for config-relative paths and route/file mapping consistency. model: sonnet tools: - Read - Glob - Grep permissionMode: default maxTurns: 10 --- You are the docs-framework sub-agent for technical documentation. Goals: - validate framework config-driven docs behavior - prevent path-mapping drift between source files and published routes Tasks: - detect and read framework config first (Fern/Sphinx/Mintlify/custom) - resolve paths relative to the declaring file/config - validate both maps: - config -> file exists - config/nav/routing -> URL path is valid and consistent Return: - config files reviewed - path assumptions made - mismatches (`missing file`, `stale route`, `wrong base path`)

--- name: synthesis-agent description: Long-context synthesis agent that merges sub-agent outputs into one prioritized and deduplicated documentation action plan. model: opus tools: - Read permissionMode: default maxTurns: 12 --- You are the synthesis sub-agent for technical documentation. Goal: - merge sub-agent outputs into one coherent, non-duplicated action plan Tasks: - prioritize blockers first, then non-blocking improvements - normalize to one precedence model for governance decisions - remove duplicated recommendations and contradictory fixes - keep final output concise and execution-ready Return: - prioritized fix plan - validation summary (done vs pending) - explicit remaining gaps/blockers

--- name: governance-agent description: Thinking-focused governance reviewer for AGENTS/CONTRIBUTING/alias precedence, conflict detection, and policy drift analysis. model: sonnet tools: - Read - Glob - Grep permissionMode: default maxTurns: 10 --- You are the governance sub-agent for technical documentation. Goals: - validate AGENTS/CONTRIBUTING/alias alignment and precedence - identify policy drift and conflicting instructions Tasks: - determine canonical instruction source and alias compatibility mapping - detect conflicts across nested scope files and tool-specific rule consumers - validate command examples against stated governance expectations Return: - precedence model - conflict list with severity - recommended low-risk remediations

--- name: inventory-agent description: Fast repo-surface discovery for technical documentation audits. Use for coverage mapping and missing-path detection before deeper review. model: haiku tools: - Read - Glob - Grep - LS permissionMode: default maxTurns: 6 --- You are the inventory sub-agent for technical documentation. Goals: - enumerate governance and docs-content surfaces in scope - detect missing files, broken references, and obvious command/path failures Tasks: - map `AGENTS.md`/`CONTRIBUTING.md`/aliases and docs surfaces (`docs/**`, README hierarchy, `.md/.mdx/.mdc/.rst/.rsc`) - list framework config files discovered (Fern/Sphinx/Mintlify or equivalent) - report hard failures only, with exact file paths Return: - coverage map - missing/broken path list - unresolved blockers

--- name: openclaw-small-bugfix-sweep description: Fix only small, high-certainty OpenClaw bugs from a pasted issue/PR list after deep code review. --- # OpenClaw Small Bugfix Sweep Batch workflow for pasted OpenClaw issue/PR refs. Execute, do not summarize. Triage reviews, proves, and patches local fixes first; publishing waits for Peter's manual review. ## Peter Review Gate Peter always wants to review code before commits. Default flow: 1. Review each issue deeply enough to prove current behavior and root cause. 2. Fix only easy, high-confidence bugs with narrow ownership and focused proof. 3. Stop with the dirty diff summary, touched files, and test/gate output for Peter's manual review. 4. After Peter approves shipping, make one commit per accepted fix, with a changelog entry for each user-facing fix. 5. Pull/rebase, push, then comment and close only the fixed or explicitly triaged-closed issues. Do not batch unrelated issue fixes into one commit. Do not push, create PRs, comment, close, label, land, merge, or otherwise publish during the review/prove phase. ## Companion Skills Use `$gitcrawl` first, `$openclaw-pr-maintainer` for live GitHub hygiene, `$github-deep-review` posture for source tracing, and `$openclaw-testing` for proof. ## Loop For each ref: 1. Read live target with `gh`. 2. Check `gitcrawl` for related, duplicate, closed, or already-fixed threads. 3. Read body, comments, linked refs, changed files, current code, adjacent tests, and dependency contracts when relevant. 4. Trace the real runtime path. 5. For issues: fix locally only if this is a bug, current code proves root cause, the implicated path is clear, and a narrow patch is cleaner than refactor. 6. For PRs: decide `ready-to-merge`, `needs-fixup`, or `skip`; do not alter PR branches unless explicitly asked. 7. Add focused regression proof when practical for local issue fixes or PR readiness checks. 8. Run the smallest meaningful gate. 9. Continue until every pasted ref is fixed or classified. No subagents unless explicitly requested. ## Skip If - not a bug - config/docs/workflow/release/support/dependency/product work - repro or root cause is uncertain - larger refactor or owner-boundary change is cleaner - already fixed on current `main` - dependency behavior is guessed - no focused proof is feasible Skip with terse reason. Do not pad with low-confidence fixes. ## Fix Rules - owner module first; generic seam only when required - existing patterns/helpers/types - no drive-by refactors - tests near failing surface - docs only for changed public behavior - no commit during the review/prove phase - after Peter approves shipping, one commit plus changelog per accepted user-facing fix - no push/create PR/comment/close/label/land/merge until Peter approves shipping after review ## PR Rules - `ready-to-merge`: code is good, current head checked, required proof is green or clearly pending only external CI; list for maintainer merge or `@clawsweeper automerge` - `needs-fixup`: small bug is clear, but PR branch needs changes; list exact files/tests and wait for explicit fix/push/automerge instruction - `skip`: broad, stale, speculative, config/product/security/release, owner-boundary, or refactor-sized - if source PR is untrusted/uneditable, do not create a replacement PR during sweep ## Output Shape Ledger: `fixed-local`, `ready-to-merge`, `needs-fixup`, `skipped`, `needs-human`. Final: issue files left on disk, PRs ready for merge/automerge, tests/gates, skip reasons.

--- name: autoreview description: "Auto Review closeout. Codex review is the default when no engine is set and is the recommended reviewer." --- # Auto Review Run the bundled structured review helper as a closeout check. This is code review, not Guardian `auto_review` approval routing. Codex review is the default when no engine is set. It usually delivers the best review results and should remain the normal final closeout engine. Use when: - user asks for Codex review / Claude review / autoreview / second-model review - after non-trivial code edits, before final/commit/ship - reviewing a local branch or PR branch after fixes ## Contract - Treat review output as advisory. Never blindly apply it. - Verify every finding by reading the real code path and adjacent files. - Read dependency docs/source/types when the finding depends on external behavior. - Reject unrealistic edge cases, speculative risks, broad rewrites, and fixes that over-complicate the codebase. - Prefer small fixes at the right ownership boundary; no refactor unless it clearly improves the bug class. - When an accepted finding shows a bug class or repeated pattern, inspect the current PR scope for sibling instances before fixing. - Fix the scoped bug class at once when practical; stop at touched surfaces, owner boundaries, and clear follow-up territory. - Keep going until structured review returns no accepted/actionable findings. - If a review-triggered fix changes code, rerun focused tests and rerun the structured review helper. - For security-audit suppression changes, verify accepted findings remain auditable: suppressed findings stay in structured output, active output keeps an unsuppressible suppression notice, and aggregate findings cannot hide unrelated active risk. - Never switch or override the requested review engine/model. If the review hits model capacity, retry the same command a few times with the same engine/model. - Be patient with large bundles. Structured review can take up to 30 minutes while the model call is active, especially with Codex tools or web search. - Treat heartbeat lines like `review still running: ... elapsed=... pid=...` as healthy progress, not a hang. Let the helper continue while heartbeats are advancing. Pass `--stream-engine-output` when live engine text is useful; Codex and Claude filter tool/file chatter, other engines pass raw output through. - Do not kill a review just because it has been quiet for 2-5 minutes, or because it is still running under the 30-minute window. Inspect the process only after missing multiple expected heartbeats, after 30 minutes, or after an obviously failed subprocess; prefer letting the same helper command finish. - Tools are useful in review mode. The helper allows read-only inspection tools and web search by default so reviewers can check dependency contracts, upstream docs, and current behavior. - Security perspective is always included, but it should not cripple legitimate functionality. Report security findings only when the change creates a concrete, actionable risk or removes an important safety check. - For regression provenance, if no blamed PR is traceable, use the blamed commit as the provenance: commit SHA, date, and author username. Do not guess a merger or frame missing PR metadata as a separate finding. - Do not invoke built-in `codex review`, nested reviewers, or reviewer panels from inside the review. The helper builds one bundle, calls one selected engine, validates one structured result, and stops. - Stop as soon as the helper exits 0 with no accepted/actionable findings. Do not run an extra review just to get a nicer "clean" line, a second opinion, or clearer closeout wording. - Treat the helper's successful exit plus absence of actionable findings as the clean review result, even if the underlying Codex CLI output is terse. - Multi-reviewer panels are opt-in only. Use them when explicitly requested or when risk justifies the extra spend; the main agent still verifies every accepted finding before fixing. - If rejecting a finding as intentional/not worth fixing, add a brief inline code comment only when it explains a real invariant or ownership decision that future reviewers should know. - If `gh`/Gitcrawl reports `database disk image is malformed`, run `gitcrawl doctor --json` once to let the portable cache repair before retrying review; do not bypass the shim unless repair fails and freshness requires live GitHub. - If Gitcrawl reports a portable manifest mismatch, source/runtime DB health error, or stale portable-store checkout, run `gitcrawl doctor --json` and inspect `source_db_health`, `runtime_db_health`, and `portable_store_status` before falling back to live GitHub. - Do not push just to review. Push only when the user requested push/ship/PR update. ## Pick Target Dirty local work: ```bash <autoreview-helper> --mode local ``` Use this only when the patch is actually unstaged/staged/untracked in the current checkout. `--mode uncommitted` is accepted as an alias for `--mode local`. For committed, pushed, or PR work, point the helper at the commit or branch diff instead; do not force dirty modes just because the helper docs mention dirty work first. A clean local review only proves there is no local patch. Branch/PR work: ```bash <autoreview-helper> --mode branch --base origin/main ``` Optional review context is first-class: ```bash <autoreview-helper> --mode branch --base origin/main --prompt-file /tmp/review-notes.md --dataset /tmp/evidence.json ``` If an open PR exists, use its actual base: ```bash base=$(gh pr view --json baseRefName --jq .baseRefName) <autoreview-helper> --mode branch --base "origin/$base" ``` Committed single change: ```bash <autoreview-helper> --mode commit --commit HEAD ``` or with the helper: ```bash /Users/steipete/Projects/agent-scripts/skills/autoreview/scripts/autoreview --mode commit --commit HEAD ``` Use commit review for already-landed or already-pushed work on `main`. Reviewing clean `main` against `origin/main` is usually an empty diff after push. For a small stack, review each commit explicitly or review the branch before merging with `--base`. ## Parallel Closeout Format first if formatting can change line locations. Then it is OK to run tests and review in parallel: ```bash scripts/autoreview --parallel-tests "<focused test command>" ``` On Windows, the default `--parallel-tests` shell preserves the platform `cmd.exe` semantics used by Python `shell=True`. Use `--parallel-tests-shell powershell` or `--parallel-tests-shell pwsh` when the focused test command is PowerShell-specific. Tradeoff: tests may force code changes that stale the review. If tests or review lead to code edits, rerun the affected tests and rerun review until no accepted/actionable findings remain. Once that rerun exits cleanly, stop; do not spend another long review cycle on redundant confirmation. ## Review Panels Run multiple reviewers against one frozen bundle: ```bash <autoreview-helper> --reviewers codex,claude ``` `--panel` is shorthand for Codex plus Claude unless `--engine` changes the first reviewer: ```bash <autoreview-helper> --panel ``` Set reviewer models and thinking/effort explicitly: ```bash <autoreview-helper> --reviewers codex,claude --model codex=gpt-5.1 --thinking codex=high --model claude=sonnet --thinking claude=max ``` Inline syntax is also supported: ```bash <autoreview-helper> --reviewers codex:gpt-5.1:high,claude:sonnet:max ``` Codex maps thinking to `model_reasoning_effort` and accepts `low`, `medium`, `high`, or `xhigh`. Claude maps thinking to `--effort` and also accepts `max`. Engines without a real thinking knob reject `--thinking`. ## Context Efficiency Run the helper directly so target selection, engine choice, structured validation, and exit status all stay in one path. If output is noisy, summarize the completed helper output after it returns; do not ask another agent or reviewer to rerun the review. ## Helper OpenClaw repo-local helper: ```bash .agents/skills/autoreview/scripts/autoreview --help ``` On native Windows, invoke the extensionless Python helper through Python: ```powershell python .agents\skills\autoreview\scripts\autoreview --help ``` The smoke harness has thin shell wrappers over a shared Python implementation: ```bash .agents/skills/autoreview/scripts/test-review-harness --fixture benign --engine codex ``` ```powershell .agents\skills\autoreview\scripts\test-review-harness.ps1 -Fixture benign -Engine codex ``` `agent-scripts` checkout helper: ```bash skills/autoreview/scripts/autoreview --help ``` Global helper from `agent-scripts`: ```bash ~/.codex/skills/agent-scripts/autoreview/scripts/autoreview --help ``` If installed from `agent-scripts`, path is: ```bash /Users/steipete/Projects/agent-scripts/skills/autoreview/scripts/autoreview --help ``` The helper: - chooses dirty local changes first - accepts `--mode uncommitted` as an alias for `--mode local` - otherwise uses current PR base if `gh pr view` works - otherwise uses `origin/main` for non-main branches - supports `--engine codex`, `claude`, `droid`, and `copilot`; default is `AUTOREVIEW_ENGINE` or `codex`; Codex should remain the default when nothing is set - resolves bare `git`, `gh`, reviewer, and PowerShell shell commands from absolute `PATH` entries only, never from the reviewed checkout; explicit relative `--*-bin` paths are resolved from the reviewed repository root - use `--mode commit --commit <ref>` for already-committed work, especially clean `main` after landing - should be left in `--mode auto` or forced to `--mode branch` for PR/branch work; do not force `--mode local` after committing - writes only to stdout unless `--output`, `--json-output`, or live streamed engine stderr is set - supports `--dry-run`, `--parallel-tests`, `--parallel-tests-shell`, `--prompt`, `--prompt-file`, `--dataset`, `--no-tools`, `--no-web-search`, and commit refs - supports `--stream-engine-output` or `AUTOREVIEW_STREAM_ENGINE_OUTPUT=1` for live engine text while preserving structured validation; Codex and Claude hide tool/file event details, emit compact activity summaries, and report usage at turn completion - supports opt-in review panels with `--panel` / `--reviewers`, plus per-engine `--model` and `--thinking` - allows read-only tools and web search by default where the selected CLI supports them; forbids nested review in the prompt; Codex is run through `codex exec` with read-only sandbox and structured output - prints `review still running: <engine> elapsed=<seconds>s pid=<pid>` to stderr at long-running intervals while waiting for the selected review engine, unless streamed output or compact Codex activity has been visible recently - prints `autoreview clean: no accepted/actionable findings reported` when the selected review command exits 0 - exits nonzero when accepted/actionable findings are present ## Final Report Include: - review command used - tests/proof run - findings accepted/rejected, briefly why - the clean review result from the final helper/review run, or why a remaining finding was consciously rejected Do not run another review solely to improve the final report wording. If the final helper run exited 0 and produced no accepted/actionable findings, report that exact run as clean.

--- name: openclaw-debugging description: Debug OpenClaw model, provider, tool-surface, code-mode, streaming, and live/Crabbox behavior by choosing the right logs, probes, and proof path before changing code. --- # OpenClaw Debugging Use this skill when OpenClaw behavior differs between local tests, live models, providers, code mode, Tool Search, Crabbox, or CI, and the next move should be a debug signal rather than a guess. ## Read First - `docs/logging.md` for log files, `openclaw logs`, and targeted debug flags. - `docs/reference/test.md` for local test commands. - `docs/reference/code-mode.md` for code-mode exec/wait and tool catalog rules. - Use `$openclaw-testing` for choosing test lanes. - Use `$crabbox` for broad, Docker, package, Linux, live-key, or CI-parity proof. ## Default Loop 1. State the suspected boundary: config, tool construction, provider payload, fetch, stream/SSE, transcript replay, worker/runtime, package/dist, or CI. 2. Add or enable the narrowest signal that proves that boundary. 3. Reproduce with the same provider/model/config. Do not randomly switch models unless the model itself is the variable being tested. 4. Compare configured state with actual run activation. 5. Patch the root cause. 6. Rerun the exact failing probe, then broaden only if the contract requires it. ## Model Transport Logs Use targeted env flags instead of global debug when the model request shape or stream timing matters: ```bash OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gateway OPENCLAW_DEBUG_MODEL_PAYLOAD=tools OPENCLAW_DEBUG_SSE=events openclaw gateway OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted OPENCLAW_DEBUG_SSE=peek openclaw gateway ``` Useful flags: - `OPENCLAW_DEBUG_MODEL_TRANSPORT=1`: request start, fetch response, SDK headers, first SSE event, stream done, and transport errors at `info`. - `OPENCLAW_DEBUG_MODEL_PAYLOAD=summary`: bounded payload summary. - `OPENCLAW_DEBUG_MODEL_PAYLOAD=tools`: all model-facing tool names. - `OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted`: capped, redacted JSON payload. Use only while debugging; prompts/message text may still appear. - `OPENCLAW_DEBUG_SSE=events`: first-event and stream-completion timing. - `OPENCLAW_DEBUG_SSE=peek`: first five redacted SSE events. - `OPENCLAW_DEBUG_CODE_MODE=1`: code-mode tool-surface diagnostics. Watch logs with: ```bash openclaw logs --follow ``` ## Common Boundaries - **Config vs activation:** config can be enabled while the run disables tools, is raw, has an empty allowlist, or lacks model tool support. Check the actual visible tools before enforcing provider payload invariants. - **Tool surface:** inspect final model-visible tool names, not only the tool registry or config. Code mode means exactly `exec` and `wait` only after it actually activates. - **Provider payload:** log fields, model id, service tier, reasoning, input size, metadata keys, prompt-cache key presence, and tool names before SDK call. - **Fetch vs SSE:** fetch response proves HTTP headers arrived; first SSE event proves provider body progress. A gap here is a stream/body/provider issue, not tool execution. - **Worker/dist:** run `pnpm build` when touching workers, dynamic imports, package exports, lazy runtime boundaries, or published paths. - **Live keys:** use the configured secret workflow for missing provider keys before saying live proof is blocked. Env checks are presence-only; never print secrets. ## Code Pointers - Model payload + Responses stream: `src/agents/openai-transport-stream.ts` - Guarded fetch/timing: `src/agents/provider-transport-fetch.ts` - OpenAI/Codex provider wrappers: `src/agents/pi-embedded-runner/openai-stream-wrappers.ts` - Tool construction, Tool Search, code-mode activation: `src/agents/pi-embedded-runner/run/attempt.ts` - Code-mode runtime and worker: `src/agents/code-mode.ts` `src/agents/code-mode.worker.ts` - Tool Search catalog: `src/agents/tool-search.ts` ## Proof Choice - Single helper/payload bug: local targeted Vitest. - Docs/logging-only: `pnpm check:docs` and `git diff --check`. - Worker/dist/lazy import/package surface: targeted tests plus `pnpm build`. - Live provider/model behavior: same provider/model with debug flags and a real key if available. - Docker/package/Linux/CI-parity: `$crabbox`. - CI failure: exact SHA, relevant job only, logs only after failure/completion. ## Output Habit Report: - boundary tested - exact command/env shape, redacted - observed signal, such as tool names or first SSE event timing - fix location - narrow proof and any remaining risk

--- name: release-openclaw-ci description: "Run, watch, debug, and summarize OpenClaw full release CI, release checks, live provider gates, install/update proofs, and release-secret preflights." --- # OpenClaw Release CI Use this with `$release-openclaw-maintainer` and `$openclaw-testing` when a release candidate needs full validation, install/update proof, live provider checks, or CI recovery. ## Guardrails - No version bump, tag, npm publish, GitHub release, or release promotion without explicit operator approval. - Validate provider secrets before dispatching expensive full release matrices. - Do not set GitHub secrets from unvalidated 1Password candidates. If a candidate returns 401/403, leave the existing secret alone and report the exact missing provider. - Use `$one-password` for secret reads/writes: one persistent tmux session, targeted items only, no secret output. - Watch one parent run plus compact child summaries. Avoid broad `gh run view` polling loops; REST quota is easy to burn. - Fetch logs only for failed or currently-blocking jobs. If quota is low, stop polling and wait for reset. - Treat live-provider flakes separately from code failures: prove key validity, provider HTTP status, retry evidence, and exact failing lane before editing code. - Full Release Validation parent monitors fail fast: once a required child job fails, the parent cancels the remaining child matrix and prints the failed job summary. Inspect that first red job instead of waiting for unrelated matrix tails. ## Preflight Before full release validation: ```bash node .agents/skills/release-openclaw-ci/scripts/verify-provider-secrets.mjs --required openai,anthropic,fireworks gh api rate_limit --jq '.resources.core' git status --short --branch git rev-parse HEAD ``` 1Password service-account values are the first source for release provider preflight. Inject those exact targeted keys first, then run the verifier; use ambient env only when it was already intentionally injected for this release. The script prints only provider status and HTTP class, never tokens. ## Dispatch Start product performance evidence as early as the release SHA exists, in parallel with other release work: ```bash gh workflow run openclaw-performance.yml \ --repo openclaw/openclaw \ --ref main \ -f target_ref=<release-sha> \ -f profile=release \ -f repeat=3 \ -f deep_profile=false \ -f live_openai_candidate=false \ -f fail_on_regression=false ``` - Do not wait for full release validation to start this early perf signal. - Compare available Kova, gateway startup, and CLI startup metrics with earlier release evidence or clawgrit reports before publish/closeout. - Call out any regression in the release proof. Treat a major regression as a release blocker until it is fixed, waived by the operator, or proven to be infrastructure noise. - Full Release Validation also records advisory product-performance evidence; the early standalone run is for overlap and faster regression discovery. Prefer the trusted workflow on `main`, target the exact release SHA: ```bash gh workflow run full-release-validation.yml \ --repo openclaw/openclaw \ --ref main \ -f ref=<release-sha> \ -f provider=openai \ -f mode=both \ -f release_profile=full \ -f rerun_group=all ``` Use `release_profile=stable` unless the operator explicitly asks for the broad advisory provider/media matrix. Use narrow `rerun_group` after focused fixes. Publish with `openclaw-release-publish.yml` using `release_profile=from-validation` unless a maintainer intentionally wants to cross-check a specific profile; the publish workflow reads the effective profile from the full-validation manifest. ## Watch Use the summary helper instead of repeated raw polling: ```bash node .agents/skills/release-openclaw-ci/scripts/release-ci-summary.mjs <full-release-run-id> ``` Then watch only when useful: ```bash gh run watch <full-release-run-id> --repo openclaw/openclaw --exit-status ``` Stop watchers before ending the turn or switching strategy. ## Failure Triage 1. Confirm parent SHA and child run IDs. 2. List failed jobs only: ```bash gh run view <child-run-id> --repo openclaw/openclaw --json jobs \ --jq '.jobs[] | select(.conclusion=="failure" or .conclusion=="timed_out" or .conclusion=="cancelled") | [.databaseId,.name,.conclusion,.url] | @tsv' ``` 3. Fetch one failed job log. If rate-limited, note reset time and avoid more REST calls. 4. For secret-looking failures, validate the provider endpoint from the same secret source before editing code. 5. For live-cache failures, inspect whether it is missing/invalid key, empty text, provider refusal, timeout, or baseline miss. Do not weaken release gates without clear provider evidence. 6. Fix narrowly, run local/changed proof, commit, push, rerun the smallest matching group. ## Evidence Record: - release SHA - full parent run URL - child run IDs and conclusions: CI, Release Checks, Plugin Prerelease, NPM Telegram, Product Performance - performance comparison result versus earlier releases when available - targeted local proof commands - provider-secret preflight result - known gaps or unrelated failures For lessons and recovery patterns, read `references/release-ci-notes.md`.

--- name: technical-documentation description: Build and review high-quality technical docs as well as agent instruction files in your repository. license: MIT metadata: source: "https://github.com/vincentkoc/dotskills" --- # Technical Documentation ## Purpose Produce and review technical documentation that is clear, actionable, and maintainable for both humans and agents, including contributor-governance files and agent instruction files. ## When to use - Creating or overhauling docs in an existing product/codebase (brownfield). - Building evergreen docs meant to stay accurate and reusable over time. - Reviewing doc diffs for structure, clarity, and operational correctness. - Running full-repo documentation audits that must include both governance files and product docs surfaces (`docs/`, `README*`, `.md/.mdx/.mdc`, Fern/Sphinx/Mintlify-style sources). - Updating or reviewing AGENTS.md and/or CONTRIBUTING.md to keep agent and contributor workflows aligned with current repo practices. - Improving repository onboarding/docs that include contribution instructions, issue templates, PR flow, and review gates. - Designing governance documentation strategy for repos with alias instruction files (for example `CLAUDE.md`, `AGENT.md`, `.cursorrules`, `.cursor/rules/*`, `.agent/`, `.agents/`, `.pi/`) where `AGENTS.md` is treated as canonical when present and aliases should be kept as compatibility surfaces. - Diagnosing agent-file drift where teams had to prompt iteratively to surface missing files, broken commands, or policy conflicts. - Applying repository-specific documentation overlays, including OpenClaw page-type, docs IA, preservation, and validation rules when present. ## Workflow 1. Classify task: `build` or `review`; context: `brownfield` or `evergreen`. 2. Inventory full documentation scope early (governance + product docs): AGENTS/CONTRIBUTING/aliases plus docs directories, framework sources, and root/module READMEs. 3. Detect multilingual scope (README/docs in multiple languages) and define required parity level. 4. Read `references/agent-and-contributing.md` for agent instruction and `CONTRIBUTING.md` workflow rules (inventory, canonical/alias mapping, dual-mode balance, deliverable standards, and precedence/conflict handling). 5. Read `references/principles.md` for the governing ruleset (Matt Palmer & OpenAI). 6. For OpenClaw docs work, read `references/openclaw.md` before the build/review playbook. 7. For build tasks, follow `references/build.md`. 8. For review tasks, follow `references/review.md` and proactively detect issues without waiting for repeated prompts. 9. For complex or high-risk tasks (build or review), it is acceptable to run longer, deeper, and more exhaustive investigations when needed for confidence. 10. When available, use sub-agents for bounded parallel discovery/review work, then merge outputs into one coherent final deliverable. 11. Use `references/tooling.md` when platform/tooling choices affect recommendations. 12. Run a proactive issue sweep for both governance and docs-content surfaces, and fix high-confidence defects in the same pass unless explicitly asked for report-only mode. 13. In brownfield mode, prioritize compatibility with current docs IA, tooling, and release state. 14. In evergreen mode, prioritize timeless wording, update strategy, and durable structure. 15. Return deliverables plus validation notes, parity status, and remaining gaps. ## Sub-agent orchestration guidance Prefer sub-agents when the repo is large or the requested change set is broad; use them by default for repo-wide, multi-framework, or high-conflict work. - `inventory-agent` -> `agents/inventory-agent.md` (`fast` / Claude `haiku`): file/config discovery, coverage map, and missing-path checks. - `governance-agent` -> `agents/governance-agent.md` (`thinking` / Claude `sonnet`): AGENTS/CONTRIBUTING/alias precedence, conflicts, and policy drift. - `docs-framework-agent` -> `agents/docs-framework-agent.md` (`thinking` / Claude `sonnet`): framework config, relative path base, and file-path vs URL-path mapping checks. - `synthesis-agent` -> `agents/synthesis-agent.md` (`long` / Claude `opus`): merge sub-agent outputs into one prioritized fix plan and unified precedence model. ## Inputs - Doc type (tutorial, how-to, reference, explanation) and audience. - File scope or diff scope. - Docs framework/tooling constraints (Fern, Mintlify, Sphinx, etc.). - Build/review mode and brownfield/evergreen intent. - Target agent and human compatibility intent. - Docs framework surfaces in scope (for example Fern, Sphinx, Mintlify, Markdown/MDX/MDC/RST/RSC files). - Desired investigation depth/time budget (quick pass vs exhaustive review). - Execution mode (`single-agent` or `sub-agent-assisted` when available). - Remediation mode (`apply-fixes` by default, or `report-only` when requested). - Multilingual scope: source-of-truth language, target locales, and parity expectations. - Repository-specific overlay constraints, if any. ## Outputs - Updated draft or review findings with clear next actions. - Validation notes (what was checked, what remains). - Navigation/maintenance recommendations for long-term quality. - Governance-doc alignment summary when AGENTS/CONTRIBUTING were touched. - Agent instruction-surface map (primary file, alias files, Codex/Claude/Cursor handling plan). - Documentation-surface coverage map (what was reviewed under `/docs`, README hierarchy, and framework-specific source trees). - Autodetected issue list with applied fixes (or explicit report-only findings). - Delegation notes when sub-agents were used (scope delegated and how findings were merged). - Multilingual parity note (in-sync, partial with rationale, or intentionally divergent). - Repository-specific overlay notes when one was used.

--- name: openclaw-pr-maintainer description: Use immediately for any pasted OpenClaw GitHub issue or PR URL/number, and for OpenClaw issue/PR review, triage, duplicate search, opener identity/who wrote it, author account age/activity, comments, labels, close, land, or maintainer evidence checks. --- # OpenClaw PR Maintainer Use this skill for maintainer-facing GitHub workflow, not for ordinary code changes. ## Start issue and PR triage with gitcrawl - Use `$gitcrawl` first anytime you inspect OpenClaw issues or PRs. - Check local `gitcrawl` data first for related threads, duplicate attempts, and already-landed fixes. - Use `gitcrawl` for candidate discovery and clustering; use `gh`, `gh api`, and the current checkout to verify live state before commenting, labeling, closing, or landing. - If `gitcrawl` is missing, stale, lacks the target thread, or has no embeddings for neighbor/search commands, fall back to the GitHub search workflow below. - Do not run expensive/update commands such as `gitcrawl sync --include-comments`, future enrichment commands, or broad reclustering unless the user asked to update the local store or stale data is blocking the decision. Common read-only path: ```bash gitcrawl threads openclaw/openclaw --numbers <issue-or-pr-number> --include-closed --json gitcrawl neighbors openclaw/openclaw --number <issue-or-pr-number> --limit 12 --json gitcrawl search openclaw/openclaw --query "<scope or title keywords>" --mode hybrid --json gitcrawl cluster-detail openclaw/openclaw --id <cluster-id> --member-limit 20 --body-chars 280 --json ``` ## Claim specific review targets When a maintainer asks Codex to review, triage, fix, or land a specific OpenClaw issue/PR, check assignment before deep work. - Identify the requesting maintainer's GitHub login. In this environment, default Peter to `steipete`; if another maintainer is clearly the requester, use that maintainer's bare login. - Read current assignees with live `gh issue view` / `gh pr view`; `gitcrawl` is not enough for assignment state. - If unassigned, assign the requester before deep review. This is allowed for specific requested targets; do not auto-assign broad discovery candidates or shortlists. - If assigned to someone else, say so clearly before analysis and include assignment age: - fresh: assigned within 6h; treat as actively owned unless user explicitly asks to continue or reassign - stale: assigned 6h+ ago; treat as ownership hint, not a hard block; continue only with that caveat - If assigned to requester plus others, mention co-assignees and continue. - If assignment event time is unavailable, say `assigned, time unknown`; treat as assigned, not stale. - Never remove or replace assignees unless explicitly asked. Assignment time proof: ```bash gh api "repos/openclaw/openclaw/issues/<number>/timeline" --paginate \ -H "Accept: application/vnd.github+json" \ --jq '[.[] | select(.event=="assigned") | {assignee:.assignee.login, assigner:.assigner.login, actor:.actor.login, created_at}]' ``` Use the newest `assigned` event for each current assignee. Issue timeline events expose `created_at`; GitHub GraphQL `AssignedEvent.createdAt` is also valid when REST pagination is awkward. Claim command for issues or PRs: ```bash gh api -X POST "repos/openclaw/openclaw/issues/<number>/assignees" -f 'assignees[]=<login>' >/dev/null ``` ## Surface opener identity - For every reviewed, triaged, closed, or landed issue/PR, show the opener's human name when available, GitHub login, and account age. - Get the login from `gh issue view` / `gh pr view` (`author.login`), then fetch profile metadata once with `gh api users/<login> --jq '{login,name,created_at,type}'`. - Report opener identity as one compact line: `By: Jane Doe (@jane, acct 2021-04-03) | OpenClaw: 4 PRs, 2 issues, 11 commits/12mo | GitHub: 9 repos, 86 commits, 9 PRs, 3 issues, 12 reviews` - Always show recent activity in two lanes: OpenClaw-local PRs, issues, and commits in the last 12 months; and general public GitHub activity over the same window. For linked issue-fixing PRs, include both the PR author and issue opener when they differ. - Prefer the bundled helper for activity lookups: ```bash .agents/skills/openclaw-pr-maintainer/scripts/github-activity.sh <login> [other-login...] .agents/skills/openclaw-pr-maintainer/scripts/github-activity.sh --global <login> ``` - The helper reports repo-local activity first and can fetch public GitHub contribution totals for the same window with `--global`; run the global form by default for review/triage identity summaries. - If the global contribution graph reports zero or looks inconsistent with visible public activity, sanity-check with `gh api users/<login>`, `gh api 'users/<login>/events/public?per_page=100'`, and recent public repo commits before calling the account inactive. - The helper is intentionally cache-friendly for gitcrawl-backed `gh`: it rounds repo-local windows to the UTC day, rounds global contribution windows to the UTC hour, and counts PRs/issues from one paginated issues response before fetching commits separately. Prefer reusing the helper instead of hand-rolling several `gh api` loops. - If the contribution graph is misleading or zero but public events/repos show activity, keep it one line, for example: `By: pickaxe (@ProspectOre, acct 2019-08-24) | OpenClaw: 5 PRs, 0 issues, 5 commits/12mo | GitHub: 5 repos, 29 recent events, 100 public own-repo commits; graph=0` - If `name` is empty, use the login only. If profile lookup is rate-limited or unavailable, say `account age unknown` rather than omitting the opener. - Use identity and activity as triage signal, not proof by itself: new, low-activity, or bot-like accounts can raise review caution, but code, repro, and CI evidence still decide. ## Suppress top-maintainer items in issue triage When asked for issue triage, hot issues, pressing bugs, Discord-correlated issues, or "what is still open", do not surface issues or PRs authored by top maintainers by default. Prefer external/user-reported hot issues and external PRs, not maintainer-owned work queues. Suppress by default when the opener/author is one of: - `@vincentkoc` - `@Takhoffman` - `@gumadeiras` - `@obviyus` - `@shakkernerd` - `@mbelinky` - `@joshavant` - `@ngutman` - `@vignesh07` - `@huntharo` Also suppress lower-priority maintainer-owned noise from the broader keep/top-maintainer group unless it is directly relevant: - `@thewilloftheshadow` - `@onutc` / `@osolmaz` - `@jacobtomlinson` - `@tyler6204` - `@velvet-shark` - `@jalehman` - `@frankekn` - `@ImLukeF` - `@mcaxtr` Exceptions: - Show maintainer-authored items when the requester explicitly asks for maintainer PRs/issues, PR landing candidates, release-blocking maintainer work, or a specific PR/issue number. - Show a maintainer-authored item when it is the canonical fix for an external hot issue, but frame it as the fix path rather than as a user-facing issue candidate. - Do not close, label, or deprioritize solely because an item is maintainer-authored; this section only controls what appears in triage shortlists. ## Apply close and triage labels correctly - If an issue or PR matches an auto-close reason, apply the label and let `.github/workflows/auto-response.yml` handle the comment/close/lock flow. - Do not manually close plus manually comment for these reasons. - If an issue/PR is already fixed on current `main` or solved by a new release, comment with proof plus the canonical commit/PR/release, then close it. - `r:*` labels can be used on both issues and PRs. - Current reasons: - `r: skill` - `r: support` - `r: no-ci-pr` - `r: too-many-prs` - `r: testflight` - `r: third-party-extension` - `r: moltbook` - `r: spam` - `invalid` - `dirty` for PRs only ## Select small high-confidence triage candidates When asked for `X` issues or PRs to triage, `X` means qualified candidates, not sampled threads. Issue triage is review/prove/patch-local by default: 1. Review the issue body, comments, related threads, current code, and adjacent tests. 2. Fix only issues that are easy, high-confidence, and narrowly owned by the implicated path. 3. Add focused regression proof when practical. 4. Stop with the dirty diff, touched files, and test/gate output for maintainer review. 5. After maintainer approval to ship, make one commit per accepted fix, with release-note context in the PR body or commit message when user-facing. 6. Pull/rebase, push, then comment and close only the issues that were fixed or explicitly triaged closed. Do not batch unrelated issue fixes into one commit. Do not publish, comment, close, or label during the review/prove phase. Missing `CHANGELOG.md` is not a PR review finding or merge blocker. If landing/fixing a user-visible change, make sure the PR body or commit message captures the release-note context; never ask or block solely on it. Only list candidates that pass all gates: - small owner/surface, with a likely narrow fix and focused regression test - symptom is reproducible or provable with logs, failing test, live command, dependency contract, or current-main behavior - root cause is traceable to code with file/line and the proposed fix touches that path - no strong smell that a broader refactor, ownership rethink, migration, or product decision is the better fix - dependency-backed behavior checked against upstream docs/source/types; live or web proof used when local proof is insufficient Loop: 1. Use `gitcrawl` / `gh` to gather candidate clusters. 2. Read issue/PR body, comments, current code, adjacent tests, and dependency contracts. 3. Try focused repro or proof. 4. Reject unclear, stale, speculative, broad-refactor, or owner-ambiguous items. 5. Continue until `X` qualified candidates or the bounded search is exhausted. Output only qualifying candidates, with: ref, surface, proof, cause, fix sketch, why small, expected test/gate. If none qualify, say so; do not pad. ## Structure PR review output - Start every PR review with 1-3 plain sentences explaining what the change does and why it matters. Put this before `Findings`. - Then list findings first. If none, say `No blocking findings` or `No findings`. - Show size near the top as `LOC: +<additions>/-<deletions> (<changedFiles> files)`, using live PR stats or local diff stats. - Always answer: bug/behavior being fixed, PR/issue URL and affected surface, provenance for regressions when traceable, and best-fix verdict. - For bug/regression fixes, include a compact `Provenance:` line after cause/root-cause when a bounded history pass can identify it. Use `git log -S/-G`, `git blame`, linked PRs/issues, and tests. - Provenance must separate roles when they differ: blamed code author username, blamed PR author username, blamed PR merger/committer username, automerge trigger when known, current PR author username, PR number, and date. Do not collapse them into one "introduced by" actor. - If the blamed PR was merged by `clawsweeper[bot]` or another automation, identify the human trigger when practical. Check live PR timeline/comments first; if rate-limited, use gitcrawl/cache or public PR HTML. Look for maintainer command comments such as `@clawsweeper automerge`, `/landpr`, labels/events that armed automerge, and ClawSweeper status comments. Report `automerge triggered by @login`; if not found, say trigger unknown rather than naming the bot as the human decision-maker. - For any confirmed bug, run `git blame` on the implicated line(s) after identifying the root cause. Report who broke it as the blamed PR merger/committer, and also name the blamed code author. Include the PR number. If no PR is traceable, use the blamed commit as the provenance: commit SHA, date, and author username. Do not guess a merger or frame missing PR metadata as a separate finding. - Phrase provenance as `introduced by`, `made visible by`, or `carried forward by`, with confidence (`clear`, `likely`, `unknown`). If unclear, say what evidence is missing instead of guessing. For features, docs, and refactors, use `Provenance: N/A` or omit it when no broken behavior is being fixed. - Keep summaries compact, but include enough proof that the verdict is auditable without rereading the PR. LOC proof: ```bash gh pr view <number> --json additions,deletions,changedFiles \ --jq '"LOC: +\(.additions)/-\(.deletions) (\(.changedFiles) files)"' ``` ## Read beyond the diff - Review the surrounding code path, not just changed lines. Open the caller, callee, data contracts, adjacent tests, and owner module. - Before any verdict, read enough code to fill this map: changed surface, runtime entry point, owner boundary, one caller, one callee, sibling implementations sharing the invariant, adjacent tests, current `main` behavior, and shipped/dependency/Codex contracts when relevant. - For large-codebase PRs, sample enough related files to understand the runtime boundary before deciding. Default to more code reading when the change touches agents, gateway, plugins, auth, sessions, process, config, or provider/runtime seams. - Compare the PR against current `origin/main` behavior. Check whether recent main already changed the same surface. - Dependency-backed behavior: MUST read upstream docs/source/types before judging API use, defaults, output shapes, errors, timeouts, memory behavior, or compatibility. Do not assume dependency contracts from memory or PR text. - Judge solution quality, not only correctness. Ask whether the PR is the clean owner-boundary fix or a wart/workaround that should be replaced by a small refactor, moved seam, contract change, or deletion of duplicate logic. - Mention the main files read when the verdict depends on code-path evidence. - If the user challenges the verdict or asks whether the idea is really good, resume code reading first. Do not defend, soften, or reverse the verdict until the missing caller/callee/sibling/dependency path is checked. ## Best-fix review loop Every PR review must explicitly answer: "Is this the best fix, or only a plausible fix?" Before verdict: 1. Reconstruct the bug, feature need, or behavior claim from issue/PR/proof. 2. Trace current behavior from entry point to failure or decision point. 3. Read touched files, callers, callees, owner modules, adjacent tests, and relevant docs. 4. Read sibling surfaces that should share the invariant or could be broken by a one-sided fix. 5. Compare against current `origin/main` and shipped behavior when regression/compat matters. 6. Inspect upstream dependency/Codex source or docs for dependency-backed behavior. 7. Identify at least one alternative fix location or shape, then reject it with evidence. 8. If any required path above is uninspected, keep reading or mark `Remaining uncertainty`; do not call the PR best, blocked, proof-sufficient, or merge-ready. Review output must include: - `Best-fix verdict:` best / acceptable mitigation / wrong layer / too narrow / too broad. - `Alternatives considered:` 1-3 concrete alternatives and why rejected. - `Code read:` compact list of main files/contracts checked. - `Remaining uncertainty:` what was not proven. If the best-fix answer is only "maybe", keep reading or state the missing evidence. Do not call proof sufficient until the best-fix judgment is explicit. ## Enforce the bug-fix evidence bar - Never merge a bug-fix PR based only on issue text, PR text, or AI rationale. - Whenever feasible, use Crabbox (`$crabbox`) for end-to-end verification before commenting that a bug is unreproducible, closing an issue, or opening/landing a fix PR. Prefer a real packaged/Docker/live lane that exercises the reported user flow over unit-only proof. - Before landing, require: 1. symptom evidence such as a repro, logs, or a failing test 2. a verified root cause in code with file/line 3. blame-backed provenance for regressions when traceable, including blamed PR merger and automerge trigger when known, or commit SHA/date when no PR is traceable 4. a fix that touches the implicated code path 5. a regression test when feasible, or explicit manual verification plus a reason no test was added - If the claim is unsubstantiated or likely wrong, request evidence or changes instead of merging. - If the linked issue appears outdated or incorrect, correct triage first. Do not merge a speculative fix. - If Crabbox/E2E proof is blocked, say exactly why and use the closest available local, Docker, mocked, or targeted proof. Do not present unit tests as real behavior proof. ## Close low-signal manual PRs carefully - Do not close for red CI alone. Require a clear low-signal category plus stale or failed validation. - Good manual-close categories: - blank or mostly untouched PR template with no concrete OpenClaw problem/fix - random docs-only churn such as root README translations, generic wording tweaks, or community-plugin discoverability docs that should go through ClawHub - test-only coverage without a linked bug, owner request, or behavior change - refactor-only cleanup, variable renames, formatting, or generated/baseline churn without maintainer request - third-party channel/provider/tool/skill/plugin work that belongs on ClawHub instead of core - risky ops/infra drive-bys such as new external CI services, release workflows, host upgrade scripts, Docker base migrations, or apt retry/fix-missing tweaks without owner request and green validation - dirty branches where a narrow stated change includes unrelated docs/generated/runtime/extension files - repeated bot-review spam or copied bot output without author-owned fixes - Keep or escalate plausible focused bug fixes, green PRs, active maintainer discussions, assigned work, recent author follow-up, and unique reproduction details. - For third-party capabilities, prefer the `r: third-party-extension` auto-response label when it applies; it points contributors to publish on ClawHub. ## Handle GitHub text safely - For issue comments and PR comments, use literal multiline strings or `-F - <<'EOF'` for real newlines. Never embed `\n`. - Do not use `gh issue/pr comment -b "..."` when the body contains backticks or shell characters. Prefer a single-quoted heredoc. - Do not wrap issue or PR refs like `#24643` in backticks when you want auto-linking. - PR landing comments should include clickable full commit links for landed and source SHAs when present. ## Search broadly before deciding - Prefer `gitcrawl` first. Then use targeted GitHub keyword search to verify gaps, live status, comments, and candidates not present in the local store. - Use `--repo openclaw/openclaw` with `--match title,body` first when using `gh search`. - Add `--match comments` when triaging follow-up discussion or closed-as-duplicate chains. - Do not stop at the first 500 results when the task requires a full search. Examples: ```bash gh search prs --repo openclaw/openclaw --match title,body --limit 50 -- "auto-update" gh search issues --repo openclaw/openclaw --match title,body --limit 50 -- "auto-update" gh search issues --repo openclaw/openclaw --match title,body --limit 50 \ --json number,title,state,url,updatedAt -- "auto update" \ --jq '.[] | "\(.number) | \(.state) | \(.title) | \(.url)"' ``` ## Follow PR review and landing hygiene - Never mention release-note bookkeeping in review-only output. It is landing or release-generation mechanics, not a correctness finding. - If bot review conversations exist on your PR, address them and resolve them yourself once fixed. - Leave a review conversation unresolved only when reviewer or maintainer judgment is still needed. - Before landing any PR with non-trivial code changes, run `$autoreview` until no accepted/actionable findings remain, unless equivalent manual review already covered it, the change is trivial/docs-only, or the user opts out. - When landing or merging any PR, follow the global `/landpr` process. - Use `scripts/committer "<msg>" <file...>` for scoped commits instead of manual `git add` and `git commit`. - Keep commit messages concise and action-oriented. - Group related changes; avoid bundling unrelated refactors. - Use `.github/pull_request_template.md` for PR submissions and `.github/ISSUE_TEMPLATE/` for issues. - Do not commit PR-only artifacts such as screenshots under `.github/pr-assets`; attach them to the PR/comment or use an external artifact store instead. ## Extra safety - If a close or reopen action would affect more than 5 PRs, ask for explicit confirmation with the exact count and target query first. - `sync` means: if the tree is dirty, commit all changes with a sensible Conventional Commit message, then `git pull --rebase`, then `git push`. Stop if rebase conflicts cannot be resolved safely.

--- name: agent-transcript description: "Add a redacted agent transcript section to GitHub PR or issue bodies during OpenClaw agent-created PR/issue workflows." --- # Agent Transcript Best-effort local-only provenance for OpenClaw PR/issue bodies. Use during agent-created GitHub PR or issue workflows before creating/updating the body. ## Contract - Never use network. Session discovery reads local agent logs only. - Never upload raw logs. Render sanitized Markdown first. - Always ask the user before adding transcript logs to a GitHub PR/issue body. - Tell the user sanitized session logs help reviewers and can make PRs easier to prioritize. - Offer a local HTML preview before insertion. If the user wants preview, open it and wait for confirmation before adding the section. - Fail closed on unresolved secrets, private keys, browser/session/cookie details, or auth URLs. - Drop system/developer prompts, raw tool outputs, reasoning, env, cookies, tokens, and broad local paths. - Keep user prompts, assistant visible decisions, terse tool summaries, and test/proof outcomes. - Remove session turns unrelated to the PR/issue work. Use the PR/issue title, branch name, changed files, and stated goal as scope; omit earlier/later unrelated tasks even when they are in the same session log. - Best effort only: PR/issue creation must continue if no safe transcript is found. - Add the `## Agent Transcript` section only when inserting a real transcript. Never add a placeholder transcript heading or text such as "A sanitized local transcript preview was generated but not included." - Use a collapsed `<details>` section and update existing markers instead of duplicating sections. ## Helper ```bash .agents/skills/agent-transcript/scripts/agent-transcript --help ``` Find a likely local session: ```bash .agents/skills/agent-transcript/scripts/agent-transcript find \ --query "$PR_TITLE $BRANCH_OR_PR_URL" \ --cwd "$PWD" \ --since-days 14 ``` `find` scans the newest 400 matching local JSONL logs by default across Codex, Claude, Pi, and OpenClaw agent sessions. Use `--max-files N` for a wider local search. Render a PR/issue body section: ```bash .agents/skills/agent-transcript/scripts/agent-transcript render \ --session "$SESSION_JSONL" \ --out /tmp/agent-transcript.md ``` Preview one candidate session locally: ```bash .agents/skills/agent-transcript/scripts/agent-transcript preview \ --session "$SESSION_JSONL" \ --out /tmp/agent-transcript-preview.html open /tmp/agent-transcript-preview.html ``` Append/update a body file before `gh pr create --body-file` or connector PR creation: ```bash .agents/skills/agent-transcript/scripts/agent-transcript append-body \ --body /tmp/pr-body.md \ --session "$SESSION_JSONL" \ --out /tmp/pr-body.with-transcript.md ``` ## PR/Issue Workflow 1. Draft the normal PR/issue body first. 2. Run `find` with title, branch, PR URL/number if known, and cwd. 3. If a high-confidence session is found, ask: `Include a redacted agent transcript? It helps reviewers and can make the PR easier to prioritize. I can open a local preview first.` 4. If the user wants preview, run `preview`, open the HTML with `open`, and wait for confirmation. 5. Before insertion, trim unrelated session turns from the generated section. Keep only turns that explain this PR/issue's goal, implementation choices, files, tests, proof, blockers, and final outcome. 6. If the user approves, run `append-body`. 7. Use the enriched body file for creation/update. 8. If no safe session is found, say nothing and continue without transcript. If the user declines, continue without transcript and do not add any transcript placeholder section. ## Review Artifacts For manual audits across many PR/session candidates, create a local HTML preview from a local JSON file. This is for maintainers only and is not part of the PR/issue workflow: ```bash .agents/skills/agent-transcript/scripts/agent-transcript html \ --prs /tmp/recent-prs.json \ --out /tmp/agent-transcript-preview.html ```

--- name: security-triage description: "Triage OpenClaw security advisories, drafts, and GHSA reports with shipped-tag and trust-model proof." --- # Security Triage Use when reviewing OpenClaw security advisories, drafts, or GHSA reports. Goal: high-confidence maintainers' triage without over-closing real issues or shipping unnecessary regressions. ## Close Bar Close only if one of these is true: - duplicate of an existing advisory or fixed issue - invalid against shipped behavior - out of scope under `SECURITY.md` - fixed before any affected release/tag Do not close only because `main` is fixed. If latest shipped tag or npm release is affected, keep it open until released or published with the right status. ## Required Reads Before answering: 1. Read `SECURITY.md`. 2. Read the GHSA body with `gh api /repos/openclaw/openclaw/security-advisories/<GHSA>`. 3. Inspect the exact implicated code paths. 4. Verify shipped state: - `git tag --sort=-creatordate | head` - `npm view openclaw version --userconfig "$(mktemp)"` - `git tag --contains <fix-commit>` - if needed: `git show <tag>:path/to/file` 5. Search for canonical overlap: - existing published GHSAs - older fixed bugs - same trust-model class already covered in `SECURITY.md` ## Review Method For each advisory, decide: - `close` - `keep open` - `keep open but narrow` Default to one advisory at a time when comments/closures are involved: 1. Review exactly one GHSA. 2. Print the GHSA URL first. 3. Summarize the decision and evidence for discussion. 4. Draft one maintainer-ready comment. 5. Copy only that one comment to the clipboard. 6. Stop and wait for Peter to post/discuss before moving to the next GHSA. Do not batch multiple close comments unless Peter explicitly asks for a batch. Check in this order: 1. Trust model - Is the prerequisite already inside trusted host/local/plugin/operator state? - Does `SECURITY.md` explicitly call this class out as out of scope or hardening-only? 2. Shipped behavior - Is the bug present in the latest shipped tag or npm release? - Was it fixed before release? 3. Exploit path - Does the report show a real boundary bypass, not just prompt injection, local same-user control, or helper-level semantics? - If data only moves between trusted workspace-memory files called out in `SECURITY.md`, do not treat "injection markers" alone as a security bug. - In that case, frame sanitization as optional hardening only if it preserves expected memory workflows. 4. Functional tradeoff - If a hardening change would reduce intended user functionality, call that out before proposing it. - Prefer fixes that preserve user workflows over deny-by-default regressions unless the boundary demands it. 5. Hardening follow-up - Even when the GHSA should close, ask whether a narrow hardening change would reduce footguns without changing the documented trust boundary. - Separate hardening from vulnerability status. Phrase it as "not required for GHSA closure, but worth considering". - Bring up hardening only if it is concrete, low-risk, and preserves intended maintainer/operator workflows. - If hardening would require a product/security model change, say that explicitly and do not imply it is a required fix for closure. ## Response Format When preparing a maintainer-ready close reply: 1. Print the GHSA URL first. 2. Then draft a detailed response the maintainer can post. 3. Include: - exact reason for close - exact code refs - exact shipped tag / release facts - fix provenance or canonical duplicate GHSA when applicable - optional hardening note only if worthwhile and functionality-preserving Keep tone firm, specific, non-defensive. ## Public Wording Hygiene - Keep raw commit hashes, PR titles/numbers, and fix-mechanism summaries out of public advisory text. Use the patched release/version field only. - Keep exact commit SHAs, PRs, and implementation notes in internal notes and verification files. - For hardening/no-publish outcomes, do not add exploit-heavy details, "Fixed by" text, or a "Fix Commit(s)" section. Thank reporters, preserve credit, state the `SECURITY.md` boundary, and say clearly that the GHSA will close without publication. - For published CVE/GHSA text, prefer `### Patched Versions` with the fixed release. Do not explain how the patch works unless Peter explicitly asks for that public detail. - Keep GHSA ids out of changelog and release-note wording unless Peter explicitly asks. ## Discussion Mode When Peter is manually posting GHSA comments, use this flow: 1. Show the URL. 2. Give a terse verdict (`close`, `keep open`, or `keep open but narrow`). 3. List the strongest evidence bullets. 4. State any optional hardening follow-up separately from the close reason. 5. Copy the proposed comment body with `pbcopy`. 6. End the reply after the one advisory. Do not continue to the next advisory until Peter says to continue. If the GitHub API cannot post comments for private advisories, say so once and keep using clipboard/UI paste. ## Clipboard Step After drafting the final post body for the current advisory, copy it: ```bash pbcopy <<'EOF' <final response> EOF ``` Tell the user that the clipboard now contains the proposed response for that advisory. ## Useful Commands ```bash gh api /repos/openclaw/openclaw/security-advisories/<GHSA> gh api /repos/openclaw/openclaw/security-advisories --paginate git tag --sort=-creatordate | head -n 20 npm view openclaw version --userconfig "$(mktemp)" git tag --contains <commit> git show <tag>:<path> gh search issues --repo openclaw/openclaw --match title,body,comments -- "<terms>" gh search prs --repo openclaw/openclaw --match title,body,comments -- "<terms>" ``` ## Decision Notes - “fixed on main, unreleased” is usually not a close. - “needs attacker-controlled trusted local state first” is usually out of scope. - “same-host same-user process can already read/write local state” is usually out of scope. - “trusted workspace memory promotes/reindexes trusted workspace memory” is usually out of scope unless it crosses a documented boundary. - “helper function behaves differently than documented config semantics” is usually invalid. - If only the severity is wrong but the bug is real, keep it open and narrow the impact in the reply.

# AGENTS.MD Telegraph style. Root rules only. Read scoped `AGENTS.md` before subtree work. Skills own workflows; root owns hard policy and routing. ## Start - Repo: `https://github.com/openclaw/openclaw` - Replies: repo-root refs only: `extensions/telegram/src/index.ts:80`. No absolute paths, no `~/`. - Docs/user-visible work: `pnpm docs:list`, then read relevant docs only. - Fix/triage answers need source, tests, current/shipped behavior, and dependency contract proof. - Reviews/answers: high confidence required. Default to exhaustive relevant codebase search/read, including owners, callers, siblings, tests, docs, and upstream/dependency contracts before verdict. Diff-only review is insufficient. - Review default: read the whole changed function/module plus callers, callees, sibling implementations, adjacent tests, scoped docs, and dependency/Codex contracts before saying `good`, `bad`, `best fix`, `proof sufficient`, or posting a comment. If challenged, keep reading first; do not defend the earlier verdict until the missing path is checked. - Dependency-touching work: direct dependency inspection is mandatory when feasible; do not rely on assumptions, wrappers, or memory. Most dependencies are OSS, so read their source/docs/types. Codex-related work has a hard gate: the acting agent must personally inspect sibling `../codex` source for the exact protocol/runtime behavior before any verdict, comment, approval, merge recommendation, code change, or `proof sufficient` claim. If missing, clone `https://github.com/openai/codex.git` there first. Subagent reports, PR text, OpenClaw wrappers, generated schemas, memory, and prior bot reviews do not satisfy this gate. No direct `../codex` check means no Codex verdict. Cite Codex files/lines checked in final/review/comment. - Dependency-backed behavior: read upstream docs/source/types first. No API/default/error/timing guesses. - External API work: live test required. Google/search for additional proof. Prefer official docs/source/types; cite current proof. No memory-only API claims. - Live-verify when feasible. Never print secrets. - Missing deps: `pnpm install`, retry once, then report first actionable error. - CODEOWNERS: maint/refactor/tests ok. Larger behavior/product/security/ownership: owner ask/review. - Product/docs/UI/changelog wording: "plugin/plugins"; `extensions/` is internal. - New channel/plugin/app/doc surface: update `.github/labeler.yml` + GH labels. - New `AGENTS.md`: add sibling `CLAUDE.md` symlink; edit `AGENTS.md` only. ## ClawSweeper Review Policy - OpenClaw-specific review rules live here; generic ClawSweeper prompts stay repo-agnostic. - ClawSweeper-owned schema, labels, close reasons, protected-label gates, maintainer-item gates, and mutation rules live in `openclaw/clawsweeper`. - Review workers read this full root `AGENTS.md` before judging; no reliance on search snippets, `head`, partial ranges, local excerpts, or truncated copies. Then read every scoped `AGENTS.md` that owns touched paths. - Optional integrations, providers, channels, skill bundles, MCP surfaces, and service workflows route to plugins, ClawHub, or owner repos when current seams suffice. Keep core items for missing core/plugin APIs, bundled regressions, security/core hardening, or maintainer product decisions. - Plugin APIs, provider routing, auth/session state, persisted preferences, config loading, config/default additions, migrations, setup, startup checks, and fallback behavior are compatibility/upgrade-sensitive. Treat config breaks, new config/default surfaces, removed fallbacks, fail-closed changes, stricter validation, or new operator action as merge risk even with green CI when they can affect existing users, upgrades, provider/plugin behavior, or maintainer operations. - For PRs that add, remove, or change config/default surfaces with possible compatibility, upgrade, provider/plugin, operator, setup, startup, or fallback impact, ClawSweeper review should emit a `reviewMetrics` entry when practical. The metric should name the count and direction of the changes, such as added, changed, or removed config/default surfaces, and explain why the metric matters before merge. When the metric indicates concrete merge risk, also surface the concern in `risks`, use `mergeRiskLabels` when the risk matches the label rubric, make `bestSolution` name the desired pre-merge state, and ensure `labelJustifications` explain the specific reason rather than restating the label. - Review whole decision surfaces, not only the touched runtime, provider, channel, harness, plugin seam, or context path. Check sibling Codex/Pi-style runtimes, provider/model routing, channel delivery, gateway/protocol, plugin SDK, and context-management paths when relevant. - Every PR review must explicitly ask whether the PR is the best fix, not merely a plausible fix. Verdicts need a best-fix judgment backed by enough code reading to compare owner boundaries, callers, siblings, tests, docs, current `main`, shipped behavior when relevant, and dependency/Codex contracts when involved. - Before a PR verdict, build a small evidence map: changed surface, entry point, owner boundary, at least one caller and callee, sibling surfaces that share the invariant, existing tests, and current `main` behavior. If any cell is missing, say the gap instead of concluding. - One-sided fixes need sibling-surface proof, an explanation for why siblings are unaffected, or explicit follow-up work. - Changelog findings: see Docs / Changelog. - Public ClawSweeper comments prefer `https://docs.openclaw.ai/...` when a public docs page exists; structured evidence still cites repo files, lines, SHAs. - Findings need current source, shipped/current behavior, tests/CI evidence, and dependency contract proof when dependency-backed behavior is involved. Validation is judged against touched and sibling surfaces plus this file's commands; real behavior proof matters for user-visible changes, with Telegram/Desktop proof for Telegram-visible behavior when feasible. - Prefer findings for concrete behavior regressions, missing changed-surface proof, owner-boundary violations, security/API contract issues, or docs/config mismatches. - Do not file findings for repo policy preference when changed code follows the relevant scoped guide and no user-visible, runtime, security, or maintainer-risk impact is shown. ## Map - Core TS: `src/`, `ui/`, `packages/`; plugins: `extensions/`; SDK: `src/plugin-sdk/*`; channels: `src/channels/*`; loader: `src/plugins/*`; protocol: `packages/gateway-protocol/*`; docs/apps: `docs/`, `apps/`. - Installers: sibling `../openclaw.ai`. - Scoped guides: `extensions/`, `src/{plugin-sdk,channels,plugins,gateway,agents}/`, `packages/`, `test/helpers*/`, `docs/`, `ui/`, `scripts/`. ## Docs - Source docs: `docs/**`; publish repo: `openclaw/docs`; host: `https://docs.openclaw.ai`. - Flow: source -> `docs-sync-publish.yml` -> mirror build -> R2 -> Worker router. - Docs AI: `openclaw/ask-molty`; see its `AGENTS.md`. ## Architecture - Core stays plugin-agnostic. No bundled ids/defaults/policy in core when manifest/registry/capability contracts work. - Plugins cross into core only via `openclaw/plugin-sdk/*`, manifest metadata, injected runtime helpers, documented barrels (`api.ts`, `runtime-api.ts`). - Plugin prod code: no core `src/**`, `src/plugin-sdk-internal/**`, other plugin `src/**`, or relative outside package. - Core/tests: no deep plugin internals (`extensions/*/src/**`, `onboard.js`). Use public barrels, SDK facade, generic contracts. - Owner boundary: owner-specific repair/detection/onboarding/auth/defaults/provider behavior lives in owner plugin. Shared/core gets generic seams only. - Dependency ownership follows runtime ownership: plugin-only deps stay plugin-local; root deps only for core imports or intentionally internalized bundled plugin runtime. - Internal bundled plugins ship in core dist; bundled-only facade loader ok only for them. - External official plugins own package/deps and are excluded from core dist; core uses registry-aware `facade-runtime` or generic contracts. - Externalizing a bundled plugin: update package excludes, official catalogs, docs, tests, and prove core runtime paths resolve installed plugin roots before root-dep removal. - Runtime reads canonical config only. No silent compat for old/malformed config keys. If a config change invalidates existing files, add a matching `openclaw doctor --fix` migration. Core/auth config repairs live in core doctor; plugin-owned config repairs live in that plugin's doctor contract (`legacyConfigRules` / `normalizeCompatibilityConfig`). - OpenAI Codex is folded into `openai`. No new/live `openai-codex` provider/plugin/auth/model routes; treat them as legacy input only. Runtime/setup/auth/catalog use `openai` + `openai/*`; doctor/migrations repair stale `openai-codex/*` profiles/metadata. - Config/env surface bar is high; `openclaw.json` and environment variables are already large. Before adding a config option or env var, first prove existing product behavior, provider selection, defaults, or doctor migration cannot solve it. Prefer removing or consolidating config/env options when touching these surfaces. Core supports only the latest config shape; `openclaw doctor --fix` migrates older shipped shapes into the current one. - CLI setup flows are public API when external docs, installers, or integrations can copy them. Changes to `openclaw onboard`, `openclaw configure`, their documented flags, non-interactive behavior, or generated config shape are compatibility-sensitive API contract changes; prefer additive flags/aliases, deprecation windows, and backward-preserving migrations over breaking existing snippets. - Fix shape: default to clean bounded refactor, not smallest patch. Move ownership to right boundary; delete stale abstractions, duplicate policy, dead branches, wrappers, fallback stacks. - Fix observed local failures with generic product rules; do not hardcode names, ids, log phrases, or user examples in prod code unless they are an explicit contract. - Tests may use observed examples, but prod literals need a short contract reason. - Compatibility is opt-in. "Shipped" means reachable from a release Git tag; main/GitHub/PR/unreleased code is not shipped. - Refactor default: one canonical path. Delete the old path unless user explicitly wants compat or the shipped public contract is obvious and cited. - Core runtime consumes only current canonical shapes/config/data. Legacy or retired shapes normalize only in doctor/migration code before runtime; no runtime shims, aliases, or fallback readers. - State/storage migrations are database-first. Runtime reads/writes the canonical store only. Old file stores, sidecars, aliases, and fallback readers belong in `openclaw doctor --fix` migration code only, never steady-state runtime. - Storage default: SQLite only. Do not add JSON/JSONL/TXT/sidecar files for OpenClaw-owned runtime state, caches, queues, registries, indexes, cursors, checkpoints, or plugin scratch data. - SQLite runtime access uses Kysely helpers, not raw SQL statement strings, except schema DDL, migrations, low-level DB bootstrap, or narrowly justified SQLite primitives. - Use the shared state DB (`state/openclaw.sqlite`) for global runtime state and plugin KV data. Use the per-agent DB (`agents/<agentId>/agent/openclaw-agent.sqlite`) for agent-scoped state/cache. Use a dedicated SQLite DB only when schema, volume, or lifecycle clearly does not fit those stores. - Legacy state/cache files are migration debt. When touching code that reads/writes them, prefer moving the data into SQLite or calling out the refactor follow-up; do not add parallel file paths. - File storage must be a named product artifact: import/export, user attachment, log, backup, or external tool contract. If it is app state or cache, it belongs in SQLite. - Before adding any path under state dirs, choose one: shared state DB, plugin KV, agent DB, or dedicated SQLite schema. If none fits, design the SQLite owner/schema first. - Cache/transient state gets no compat migration unless a shipped user contract is cited. Prefer delete/drop/rebuild over import. If old state can be lost without user-visible data loss, remove the old path entirely. - Persistent user state gets one migration owner. Doctor migrates, verifies, and then runtime assumes the new shape. No dual-write, read-through fallback, lazy import, or "if SQLite fails use JSON" branches. - Fallback is a product decision, not an implementation convenience. Before adding one, name the shipped contract, failure mode, removal plan, and why doctor cannot solve it. Otherwise delete it. - Keep old behavior only for an explicit public API/config/plugin SDK/data contract, tagged upgrade path, security/migration boundary, dependency contract, or observed prod state. - If unsure, ask before preserving compat. Do not keep aliases, shims, fallback stacks, stale names, or obsolete tests just in case. - Tests alone do not make internals contracts. If compat stays, name the contract and migration/removal plan in code, test, or PR. - Lean code is a goal. No internal shims, aliases, legacy names, broad fallbacks, or defensive branches just to reduce diff or handle unrealistic edge cases. - Handle real production states, tagged upgrade paths, security boundaries, and dependency contracts. Public/hostile/observed malformed input gets care; hypothetical malformed input does not. - Deprecate shipped public contracts only. - Plugin SDK exception: shipped external API gets new API first plus named compat/deprecation, small tests/docs if useful, removal plan. - Migrate internal/bundled callers to modern API in the same change. Do not let internal compat become permanent architecture. - Channels are implementation under `src/channels/**`; plugin authors get SDK seams. Providers own auth/catalog/runtime hooks; core owns generic loop. - Message/channel plugins stay transport-only. They render portable presentation/actions, enforce transport limits, and map native callback envelopes. They do not own product command trees, plugin/provider policy, or feature-specific menus. - Portable command UI must use typed presentation actions, not raw string inference. Do not make channels guess that `value` starting with `/` means a native command; core/owner plugins declare command actions, channels map them when supported. - Raw callback data is transport/private. Approval, command, URL, web-app, and select actions must stay distinguishable before channel encoding so transport adapters do not special-case product strings. - Agent run terminal state: normalize/merge via `src/agents/agent-run-terminal-outcome.ts`; do not rederive timeout/cancel precedence in projections. - Hot paths should carry prepared facts forward: provider id, model ref, channel id, target, capability family, attachment class. Do not rediscover with broad plugin/provider/channel/capability loaders. - Do not fix repeated request-time discovery with scattered caches. Move the canonical fact earlier; reuse prepared runtime objects; delete duplicate lookup branches. - Gateway/plugin metadata is process-stable: installs, manifests, catalogs, generated paths, bundled metadata. Changes require restart or explicit owner reload/install/doctor flow. - Runtime hot paths: no freshness polling (`stat`/`realpath`/JSON reread/hash). Reuse current snapshots, install records, discovery, lookup tables, root scopes, resolved paths. - Process-local metadata caches ok when lifecycle-owned and bounded/single-slot. Freshness exceptions need named owner + tests. - Inline comments: preserve reviewer context at the code site. Required for non-obvious cross-path/state invariants, lifecycle ordering, ownership boundaries, queue/dedupe symmetry, TTL/cache expiry, cleanup/release coupling, session/id adoption, fallback behavior, platform/dependency caps, deterministic ordering, compact encoded state, or intentional caller differences. - Comment shape: 1-3 short lines; state why the branch/helper exists, what contract it protects, and the bad outcome if removed. Cite nearby constants/helpers when useful. No syntax narration, PR/user-specific lore, or obvious mechanics. - Gateway protocol changes: additive first; incompatible needs versioning/docs/client follow-through. - Protocol version bumps: explicit owner confirmation only; never automatic/generated. - Config contract: exported types, schema/help, metadata, baselines, docs aligned. Retired public keys stay retired; compat in raw migration/doctor only. - Prompt cache: deterministic ordering for maps/sets/registries/plugin lists/files/network results before model/tool payloads. Preserve old transcript bytes when possible. - Agent tool schema cleanup: remove stale args cleanly; no hidden compat for model-facing params just to avoid churn. ## Commands - Runtime: Node 22.19+; Node 24 recommended. Keep Node + Bun paths working. - Package manager/runtime: repo defaults only. No swaps without approval. - Install: `pnpm install` (keep Bun lock/patches aligned if touched). - CLI: `pnpm openclaw ...` or `pnpm dev`; build: `pnpm build`. - Tests in a normal source checkout: `pnpm test <path-or-filter> [vitest args...]`, `pnpm test:changed`, `pnpm test:serial`, `pnpm test:coverage`; never raw `vitest`. - If raw Vitest is unavoidable, use `vitest run ...`; bare `vitest ...` starts local watch mode and will not exit on its own. - Tests in a Codex worktree or linked/sparse checkout: avoid direct local `pnpm test*`; use `node scripts/run-vitest.mjs <path-or-filter>` for tiny explicit-file proof, or Crabbox/Testbox for anything broader. - Checks in a normal source checkout: `pnpm check:changed` delegates to Crabbox/Testbox; lanes: `pnpm changed:lanes --json`; staged: `pnpm check:changed --staged`; full: `pnpm check`. - Checks in a Codex worktree or linked/sparse checkout: avoid direct local `pnpm check*`; use `node scripts/crabbox-wrapper.mjs run ... -- env OPENCLAW_CHECK_CHANGED_REMOTE_CHILD=1 OPENCLAW_CHANGED_LANES_RAW_SYNC=1 corepack pnpm check:changed` so pnpm runs inside Testbox, not locally. - Extension tests: `pnpm test:extensions`, `pnpm test extensions`, `pnpm test extensions/<id>`. - Typecheck: `tsgo` lanes only (`pnpm tsgo*`, `pnpm check:test-types`); never add `tsc --noEmit`, `typecheck`, `check:types`. - Formatting: `oxfmt`, not Prettier. Use repo wrappers (`pnpm format:*`, `pnpm lint:*`, `scripts/run-oxlint.mjs`). - Build before push when build output, packaging, lazy/module boundaries, dynamic imports, or published surfaces can change. ## Validation - Use `$openclaw-testing` for test/CI choice and `$crabbox` for remote/full/E2E proof. - Crabbox request means real scenario proof: install/update/call/repro user path; not just copy tests and run them remotely. - Visual proof: use Crabbox, set up like a user, then screenshot-verify. No harness/bypass/shortcut unless explicitly asked. - Small/narrow tests, lints, format checks, and type probes are fine locally only in a healthy normal checkout. - In Codex worktrees, direct local `pnpm test*`, `pnpm check*`, `pnpm crabbox:run`, and `scripts/committer` can trigger pnpm dependency reconciliation or install prompts. Prefer `node` wrappers locally and Crabbox/Testbox for pnpm-gated proof. - Full suites, broad changed gates, Docker/package/E2E/live/cross-OS proof, or anything that bogs down the Mac: Crabbox/Testbox. - One/few files local. If a local command fans out, stop and move broad proof to Crabbox/Testbox. - Before handoff/push: prove touched surface. Before landing to `main`: issue proof plus appropriate full/broad proof unless scope is clearly narrow. - Pre-land/pre-commit code changes: mandatory fresh `$autoreview` until no accepted/actionable findings remain. Do not land code on CI, ClawSweeper, prior review comments, or your own manual review alone unless user explicitly opts out or scope is truly trivial/docs-only. If findings want refactor, refactor; no ugly fixes. - If proof is blocked, say exactly what is missing and why. - Do not land related failing format/lint/type/build/tests. If unrelated on latest `origin/main`, say so with scoped proof. - Docs/changelog-only and CI/workflow metadata-only: `git diff --check` plus relevant docs/workflow sanity; escalate only if scripts/config/generated/package/runtime behavior changed. - Prompt snapshots: CI truth is Linux Node 24. If macOS local passes but CI drifts, reproduce/generate in Linux before rerun. ## GitHub / PRs - Use `$openclaw-pr-maintainer` immediately for maintainer-side OpenClaw issue/PR review, triage, duplicates, labels, comments, close, land, or evidence. Contributor PR creation/refresh follows the requested contributor workflow; linked refs alone do not require maintainer archive tooling. - Issue/PR start: `git status -sb`; if clean, `git pull --ff-only`; if dirty, yell before pull/rebase. - PR refs: `gh pr view/diff` or `gh api`, not web search. Prefer `gitcrawl` for maintainer discovery; missing/stale `gitcrawl` falls through to live `gh`, not contributor setup. Verify live with `gh` before mutation. - Bare issue/PR URL/number: inspect live and take the efficient maintainer path; switch branches/refs when useful. - No unsolicited PR labels/retitles/rebases/fixups/landing. Comments/reviews ok only for reviewable findings, pre-merge proof, or close/duplicate reason after explicit close/sweep/landing request. - Maintainer decision closes the cluster: if deciding reported behavior/proposed fix is not planned, comment+close all directly associated open issues/PRs unless explicitly told to keep one open. Associated means linked PRs/issues, duplicates, companion workaround PRs, and the canonical issue for the rejected behavior. - Do not leave associated issues open for hypothetical future repros. Close with rationale; ask for a new issue or reopen only if concrete new evidence appears. Close comment states: decision, why, supported alternative, and what evidence would change the decision. - Issue/PR work: search strong related issues/PRs before final; close proven dupes/fixed siblings. If none close, suggest one next related follow-up. - PR superseded by `main`: if code proof shows `main` already has same-or-better behavior, comment canonical commit/PR + focused proof, then close. Bar high: inspect PR diff, current code/tests, linked issue, caller/sibling path. If unsure, leave open. - Issue/PR numbers need a short summary every time; assume the reader has not opened or read them. - Before presenting a batch of issues/PRs, use smart subagents to verify live state and current `main`; omit closed/fixed items, and comment+close items already fixed on `main` when maintainer action is authorized. - PR review answer: bug/behavior, URL(s), affected surface, provenance for regressions when traceable, best-fix judgment, evidence from code/tests/CI/current or shipped behavior. - PR reviewable findings: post them on the PR, not chat-only, so author sees actionable feedback. - Issue/PR final answer: last line is the full GitHub URL. - PR verification: before merge, post land-ready work done, exact local commands, CI/Testbox run IDs, before/after proof when used, and known proof gaps. - Issue fixed on `main` with proof: comment proof + commit/PR, then close. - After landing or requested close/sweep: search duplicates; comment proof + canonical commit/PR/release before closing. - After landing/ship final: include 2-5 sentence recap of what landed: behavior change, key files/surface, proof run, issue/PR state. Do not answer with only status/links. - `ship` that fixes an issue: after push, comment proof + commit link, then close the issue. - Public GH comments: show draft in chat first unless user explicitly asked to post/comment/reply/close/merge/land. After work starts and changes/proof exist, post the review/proof/commit comment. - Representing user: if user already has a comment/thread for the point, update/reply there when possible; avoid duplicate PR/issue comments. - No surprise GH writes: chat must mention every posted/updated public comment with URL. - GH comments with backticks, `$`, or shell snippets: use heredoc/body file, not inline double-quoted `--body`. - PR create: real body required. Include Summary + Verification; mention refs, behavior, and proof. - PR create/refresh: keep PR branches takeover-ready. Use a branch maintainers can push to, or for fork PRs ensure `maintainer_can_modify` / GitHub's `Allow edits by maintainers` is enabled unless explicitly told otherwise or GitHub's Actions/secrets warning makes that unsafe. - GitHub issue/PR create: read `$agent-transcript`; ask about sanitized transcript logs when available. - Contributor PRs: parsed `Real behavior proof` uses exact `field: value` labels: `Behavior addressed`, `Real environment tested`, `Exact steps or command run after this patch`, `Evidence after fix`, `Observed result after fix`, `What was not tested`. - PR artifacts/screenshots: attach to PR/comment/external artifact store. Never push screenshots, videos, proof images, or proof assets to OpenClaw or any product repo branch, including temp artifact branches. Use Crabbox artifact publishing plus the manifest URL. Do not commit `.github/pr-assets`. - CI polling: exact SHA, relevant checks only, minimal fields. Skip routine noise (`Auto response`, `Labeler`, docs agents, performance/stale). Logs only after failure/completion or concrete need. - OpenClaw write-access maintainers may skip `Real behavior proof` when local tests or Crabbox verified behavior; record proof in PR verification. - `/landpr`: use `~/.codex/prompts/landpr.md`; do not idle on `auto-response` or `check-docs`. ## Code - TS ESM, strict. Avoid `any`; prefer real types, `unknown`, narrow adapters. - No `@ts-nocheck`. Lint suppressions only intentional + explained. - External boundaries: prefer `zod` or existing schema helpers. - Runtime branching: discriminated unions/closed codes over freeform strings. Avoid semantic sentinels (`?? 0`, empty object/string). - Cross-function state: when valid combos matter, return a closed mode/result shape. Avoid parallel nullable fields or derived booleans that callers must keep in sync; make impossible states unrepresentable. - Formatter-friendly shape: when oxfmt explodes an expression vertically, extract named booleans, payloads, or small helpers. Do not change width or use format-ignore for local compactness. - Calls should be boring: complex decisions happen above; call args/object fields are names, literals, or simple property reads. - Prefer early returns over nested condition pyramids. Split code into gather -> normalize -> decide -> act. - Use named intermediates only for domain meaning or readability; avoid temp-variable soup. - Code size matters. Prefer small clear code; maintainability includes not growing LOC without payoff. - Refactors should delete about as much local complexity as they add. If LOC grows, the new ownership/API needs to clearly pay for it. - Refactors should reduce non-test LOC unless they remove a larger architectural cost. Treat positive prod LOC as a smell. Before closeout, run `git diff --numstat`; if non-test LOC grew, trim or explicitly justify why fewer paths now exist. - Prefer deleting branches, modes, adapters, and tests over preserving them. A refactor that adds a second path has probably failed unless the old path is a cited shipped contract. - New helpers/files must pay rent immediately: fewer call paths, fewer concepts, or less repeated logic. No helpers for one-off compat, naming translation, or speculative resilience. - Before adding helpers/files, check whether existing code can absorb the behavior with less new surface. - Keep APIs narrow: export only current caller needs; keep types/helpers local by default. - Return the smallest useful shape. Avoid broad result objects, flags, metadata unless callers use them. - Avoid adapter layers that only rename fields. Move real responsibility or leave code local. - Inline simple one-use objects/spreads when clearer. Extract only when it removes duplication or hard logic. - Tests prove behavior/regressions, not every internal branch. - Tests are welcome, but review them before landing for duplication and value. Delete useless tests, such as assertions for behavior or paths just removed. - Tests protect canonical behavior and migration boundaries, not obsolete internals. Delete tests for removed fallback paths instead of updating them. - For non-trivial refactors, check `git diff --numstat` before closeout. If LOC grew, trim or explain why. - Prefer existing narrow helpers over repeated casts/guards. Add local helpers when 2+ nearby call sites share real boundary logic. - Prefer ctor parameter properties for injected deps/config. Do not ban them for erasable-syntax purity. - Prefer `satisfies` for registries/config maps; derive types from schemas when a runtime schema already exists. - Table-drive repetitive tests when it reduces code and keeps failure names clear. - Dynamic import: no static+dynamic import for same prod module. Use `*.runtime.ts` lazy boundary. After edits: `pnpm build`; check `[INEFFECTIVE_DYNAMIC_IMPORT]`. - Cycles: keep `pnpm check:import-cycles` + architecture/madge green. - Classes: no prototype mixins/mutations. Prefer inheritance/composition. Tests prefer per-instance stubs. - Split files around ~700 LOC when clarity/testability improves. - Naming: **OpenClaw** product/docs; `openclaw` CLI/package/path/config. - English: American spelling. ## Tests - Vitest. Colocated `*.test.ts`; e2e `*.e2e.test.ts`; example models `sonnet-4.6`, `gpt-5.5`; test GPT with 5.5 preferred, 5.4 ok; no GPT-4.x agent-smoke defaults. - Prefer behavior tests over workflow/docs string greps. Put operator policy reminders in AGENTS/docs. - Clean timers/env/globals/mocks/sockets/temp dirs/module state; `--isolate=false` safe. - Prefer injection and narrow `*.runtime.ts` mocks over broad barrels or `openclaw/plugin-sdk/*`. - Do not edit baseline/inventory/ignore/snapshot/expected-failure files to silence checks without explicit approval. - Do not run independent `pnpm test`/Vitest commands concurrently in one worktree; Vitest cache races with `ENOTEMPTY`. Group one command or use distinct `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH`. - Test workers max 16. Memory pressure: `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`. - Live: `OPENCLAW_LIVE_TEST=1 pnpm test:live`; verbose `OPENCLAW_LIVE_TEST_QUIET=0`. - Guide: `docs/reference/test.md`. ## Docs / Changelog - Use `$technical-documentation` for docs writing/review. Docs change with behavior/API. - Codex harness upgrade (`extensions/codex/package.json` `@openai/codex`): refresh `docs/plugins/codex-harness.md` model snapshot from the new harness `model/list`. - Docs final answers: include relevant full `https://docs.openclaw.ai/...` URL(s). If issue/PR work too, GitHub URL last. - `CHANGELOG.md`: release-only. Do not edit for normal PRs, direct `main` fixes, or `ship it`; release generation owns it. Do not ask contributors/agents for changelog edits. - User-facing `fix`/`feat`/`perf`: put release-note context in PR body, squash message, or direct commit: behavior, surface, issue/PR refs, credited human author/reporter. - Release generation: derive `CHANGELOG.md` from merged PRs + all direct `main` commits. Entries: active `### Changes`/`### Fixes`, single-line, thank credited humans; never thank bots/forbidden handles: `@openclaw`, `@clawsweeper`, `@codex`, `@steipete`. ## Git - Commit via `scripts/committer "<msg>" <file...>`; stage intended files only. - Commits: conventional-ish, concise, grouped. - No manual stash/autostash unless explicit. Branch switches ok when useful; no new worktrees unless requested. - `main`: no merge commits; rebase on latest `origin/main` before push. After one green run plus clean rebase sanity, do not chase moving `main` with repeated full gates. - User says `commit`: your changes only. `commit all`: all changes in grouped chunks. `push`: may `git pull --rebase` first. - User says `ship it`: commit intended changes, pull --rebase, push. - Do not delete/rename unexpected files; ask if blocking, else ignore. - Bulk PR close/reopen >50: ask with count/scope. ## Security / Release - Never commit real phone numbers, videos, credentials, live config. - Secrets: channel/provider creds in `~/.openclaw/credentials/`; model auth profiles in `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`. - Dependency patches/overrides/vendor changes need explicit approval. `pnpm-workspace.yaml` patched dependencies use exact versions only. - Release/package guards: no hard-coded retired-package denylists; use generic artifact/dependency checks or fix build source. - Lockfiles/shrinkwrap are security surface: review `pnpm-lock.yaml`, `npm-shrinkwrap.json`, `package-lock.json`; root/plugin npm packages ship shrinkwrap, not package-lock. - Carbon pins owner-only: do not change `@buape/carbon` unless Shadow (`@thewilloftheshadow`, verified by `gh`) asks. - Releases/publish/version bumps need explicit approval. Use `$release-openclaw-maintainer`. - Backport means apply to newest open `release/` branch unless user names another target. - GHSA/advisories: `$openclaw-ghsa-maintainer` / `$security-triage`. Secret scanning: `$openclaw-secret-scanning-maintainer`. - Beta tag/version match: `vYYYY.M.D-beta.N` -> npm `YYYY.M.D-beta.N --tag beta`. ## Platform / Ops - Before simulator/emulator testing, check real iOS/Android devices. - "restart iOS/Android apps" = rebuild/reinstall/relaunch, not kill/launch. - SwiftUI: Observation (`@Observable`, `@Bindable`) over new `ObservableObject`. - Mac gateway: dev watch = `pnpm gateway:watch`; managed installs = `openclaw gateway restart/status --deep`; logs = `./scripts/clawlog.sh`. No launchd/ad-hoc tmux. - Mac app permission testing: stable app path + real signing identity required. No `--no-sign`, `SIGN_IDENTITY=-`, or raw debug binary; TCC prompts/listing won't stick. - Version bump surfaces live in `$release-openclaw-maintainer`. - Parallels: `$openclaw-parallels-smoke`; Discord roundtrip: `$parallels-discord-roundtrip`. - Crabbox/WebVNC human demos: keep remote desktop visible/windowed; no fullscreen remote browser unless video/capture-style output. - Before sharing WebVNC links, use Crabbox screenshot first; verify real app/path works and target UI is not broken. - ClawSweeper ops: `$clawsweeper`. Deployed hook sessions may post one concise `#clawsweeper` note only when surprising/actionable/risky; if using message tool, reply exactly `NO_REPLY`. - Generated-media completions wake the requester agent first. Requester visible-reply config decides final text vs message tool; direct media send is fallback/recovery only. - `message_tool_only`: normal agent final visible reply = current-source `message(action=send)` only. No `NO_REPLY` prompt/contract; no message call = no source reply. Plugin-owned bound-thread reply = plugin return value; no message tool needed. Never auto-publish private final. - Memory wiki prompt digest stays tiny; prefer `wiki_search` / `wiki_get`; verify contact data before use; source-class provenance for generated people facts. - Rebrand/migration/config warnings: run `openclaw doctor`. - Never edit `node_modules`. - Local-only `.agents` ignores: `.git/info/exclude`, not repo `.gitignore`. - Provider tool schemas: prefer flat string enum helpers over `Type.Union([Type.Literal(...)])`; some providers reject `anyOf`. - External messaging: no token-delta channel messages. Follow `docs/concepts/streaming.md`.