clawsweeper

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# ClawSweeper

ClawSweeper lives at `~/Projects/clawsweeper`. It is the one OpenClaw
maintenance bot for sweeping, repair jobs, and guarded fix PRs.
Use this skill whenever asked about reports, findings, dispatch health,
repair/cloud PR creation, comment commands, automerge, permissions, or gates.

## Start

Inspect `git status --short --branch` in the ClawSweeper checkout. Status and
report requests stay read-only: use current reports and live read APIs when
freshness matters, without pulling or building just to inspect them.

For authorized implementation or execution, update a clean task-owned checkout
and build only when the selected command needs it. Preserve unrelated edits
and other operators' active workflows.

## One Bot, One App

Use the ClawSweeper repo and the `clawsweeper` GitHub App. Use only
`CLAWSWEEPER_*` configuration for this automation. Do not use legacy apps,
variables, labels, or skills.

Required app setup:

- `CLAWSWEEPER_APP_CLIENT_ID`: public app client ID for `clawsweeper`.
- `CLAWSWEEPER_APP_PRIVATE_KEY`: private key used only inside
  `actions/create-github-app-token` steps.
- Target app permissions: read target scan context; write issues and pull
  requests; contents write for report commits, repair branches, and workflow
  inputs; Actions write on `openclaw/clawsweeper` for comment-router
  re-review dispatch, workflow dispatch, run cancellation, and self-heal.

Token boundary:

- Codex workers do not get mutation credentials.
- Review workers run with stripped secret/token env.
- Deterministic scripts own comments, labels, branch pushes, PR creation,
  closes, and merges through short-lived GitHub App tokens.
- Merge and write gates default closed.

## Hosted Commit Reviews

Hosted per-commit reports and commit Check Runs are retired. For the retained
offline review of a committed branch, use `pnpm local-review -- --base main`.
`$autoreview --mode commit --commit <sha>` remains a separate general-purpose
review path.

## Sweep Reports

Issue/PR reports live at:

```text
records/<repo-slug>/items/<number>.md
records/<repo-slug>/closed/<number>.md
```

Lead with counts, concrete findings, and report links. Do not post unsolicited
GitHub comments from report-reading work. Public surfaces are markdown reports,
durable ClawSweeper review comments, and optional checks.

PR reports include Codex `/review`-style `reviewFindings` with priority,
confidence, repository-relative file, and line range. Public PR comments show a
short `Review findings:` list when findings exist; full review comments,
evidence links, likely owners, and runtime details stay inside the collapsed
`Review details` block.

For a simple status request, read existing reports and bounded live workflow
state. Use `pnpm run audit` only for a requested full audit.

Reconciliation is a separate authorized mutation: bare `pnpm run reconcile`
moves/deletes report and work-plan files. Inspect its dry-run only when that
maintenance task is requested; do not run reconciliation during status/report
reads. Likewise, `apply-decisions` belongs to an explicitly authorized apply
workflow, beginning with its dry-run.

## Create One Repair Job

Create a job from issue/PR refs and a maintainer prompt:

```bash
pnpm run repair:create-job -- \
  --repo openclaw/openclaw \
  --refs 123,456 \
  --prompt-file /tmp/clawsweeper-prompt.md
```

Create from an existing ClawSweeper report:

```bash
pnpm run repair:create-job -- \
  --from-report ../clawsweeper/records/openclaw-openclaw/items/123.md
```

The job creator checks for an existing open PR, body match, or remote
`clawsweeper/<cluster-id>` branch before writing another job. Use `--dry-run`
to inspect. Use `--force` only after deciding the duplicate guard is stale.

Validate, commit, then dispatch:

```bash
pnpm run repair:validate-job -- jobs/openclaw/inbox/clawsweeper-openclaw-openclaw-123.md
pnpm run repair:dispatch -- jobs/openclaw/inbox/clawsweeper-openclaw-openclaw-123.md \
  --mode autonomous \
  --runner blacksmith-4vcpu-ubuntu-2404 \
  --execution-runner blacksmith-16vcpu-ubuntu-2404 \
  --model gpt-6-astra
```

Do not dispatch a just-created job before the job file is committed and pushed;
the workflow reads the job path from GitHub.

## Replacement PRs

For a useful but uneditable/stale/unsafe source PR, make the maintainer prompt
explicit:

```md
Treat #123 as useful source work. If the source branch cannot be safely updated

From ngpestelos-mirrors/openclaw, MIT.