clawsweeper

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# ClawSweeper

ClawSweeper lives at `~/Projects/clawsweeper`. It is the one Astroclaw
maintenance bot for sweeping, commit review, 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

```bash
cd ~/Projects/clawsweeper
git status --short --branch
git pull --ff-only
pnpm run build:all
```

Do not overwrite unrelated edits. If the tree is dirty, inspect first and keep
read-only report work read-only unless the requester asked to commit.

## 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 `astroclaw/clawsweeper` for comment-router
  re-review dispatch, workflow dispatch, run cancellation, and self-heal;
  optional Checks write for commit Check Runs.

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.

## Commit Reports

Canonical commit reports:

```text
records/<repo-slug>/commits/<40-char-sha>.md
```

Use the lister:

```bash
pnpm commit-reports -- --since 6h
pnpm commit-reports -- --since "24 hours ago" --findings
pnpm commit-reports -- --since 7d --non-clean
pnpm commit-reports -- --repo astroclaw/astroclaw --author steipete --since 7d
pnpm commit-reports -- --since 24h --json
```

Results: `nothing_found`, `findings`, `inconclusive`, `failed`,
`skipped_non_code`. One report per SHA; reruns overwrite the SHA-named report.

Manual rerun/backfill:

```bash
gh workflow run commit-review.yml --repo astroclaw/clawsweeper \
  -f target_repo=astroclaw/astroclaw \
  -f commit_sha=<end-sha> \
  -f before_sha=<start-or-parent-sha> \
  -f create_checks=false \
  -f enabled=true
```

Use `create_checks=true` only when the requester explicitly wants target commit Check
Runs. Add `-f additional_prompt="..."` for focused one-off review instructions.

## 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.

Useful commands:

```bash
pnpm run status
pnpm run audit
pnpm run reconcile
pnpm run apply-decisions -- --dry-run
```

## Create One Repair Job

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

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

Create from an existing ClawSweeper report:

From P1R4N351/astroclaw, MIT.

More from P1R4N351/astroclaw