clawpatch

description	Operate Clawpatch for semantic feature mapping, automated review, explicit finding fixes, revalidation, reports, and state recovery.
argument-hint	[init | map | review | rereview-all | report | fix <finding-id> | revalidate <finding-id> | status]
name	clawpatch
metadata	{"skiller":{"source":".agents/rules/clawpatch.mdc"}}

Clawpatch

Use this skill when the user asks for Clawpatch, .clawpatch, automated code review, finding reports, clawpatch review, clawpatch fix, revalidation, or a forced re-review of existing Clawpatch feature records.

Source Of Truth

• Docs: https://clawpatch.ai/
• GitHub docs: https://github.com/openclaw/clawpatch
• In this repo pair, the active Slate v2 Clawpatch project usually lives at .tmp/slate-v2
• Clawpatch state is local runtime state. Keep .clawpatch/ out of git unless the user explicitly asks to preserve it as an artifact.

Before making claims, inspect the actual target directory:

pwd
test -f .clawpatch/config.json && clawpatch status --json
find .clawpatch/features -maxdepth 1 -type f 2>/dev/null | wc -l
find .clawpatch/reports -maxdepth 1 -type f 2>/dev/null | sort | tail -5

If the expected feature count or config is missing, stop and report the wrong checkout or missing state. Do not initialize over a missing project by reflex.

You can also run from another cwd with global flags:

clawpatch --root .tmp/slate-v2 status --json
clawpatch --root .tmp/slate-v2 report --status open --json

What Clawpatch Does

Clawpatch maps a repo into semantic feature records, reviews those bounded feature contexts with a provider, persists findings, applies explicit one-finding fixes, runs configured validation commands, and records audit state.

State layout:

• .clawpatch/config.json: settings, provider, commands, review limits, git safety flags.
• .clawpatch/project.json: detected project metadata when present.
• .clawpatch/features/*.json: feature records, status, finding ids, analysisHistory.
• .clawpatch/findings/*.json: finding records and triage status.
• .clawpatch/patches/*.json: fix attempts and validation results.
• .clawpatch/runs/*.json: command runs, claimed features, errors.
• .clawpatch/reports/*.md: generated Markdown reports.
• .clawpatch/locks/: transient feature locks; should clear after runs.

Feature status is not the same as finding status. A feature can be reviewed, needs-fix, or fixed; a finding can be open, fixed, wont-fix, false-positive, or uncertain.

Command Reference

Core commands:

• clawpatch init: initialize .clawpatch/.
• clawpatch map: build semantic feature records.
• clawpatch ci: initialize, map, review, write a report, and append a GitHub Actions step summary in one CI-friendly command.
• clawpatch status: summarize project state.
• clawpatch review: review queued or selected features.
• clawpatch report: render finding reports.
• clawpatch show --finding <id>: inspect one finding.
• clawpatch next: pick the next finding, defaulting to open.
• clawpatch triage: change a finding status with a note.
• clawpatch fix: apply one explicit fix attempt.
• clawpatch open-pr: turn an applied patch attempt into an explicit GitHub pull request.
• clawpatch revalidate: re-check finding validity after changes.
• clawpatch doctor: check local setup.
• clawpatch clean-locks: clear stale feature locks.

Useful global flags:

• --root <path>: operate on a target repo from another cwd.
• --state-dir <path>: use a non-default state directory.
• --config <path>: use a specific config file.
• --json: machine-readable output.
• --debug: extra diagnostics.
• --no-input: avoid interactive prompts.

Install And Doctor

Baseline requirements from the Clawpatch docs:

• Node.js 22+
• Git 2.x
• local Codex CLI for the default provider

Install:

npm install -g clawpatch
# or
pnpm add -g clawpatch

Probe before real work:

clawpatch --version
codex --version
clawpatch doctor

Providers

Default provider is local Codex. Current provider surface also includes:

• codex: default local Codex CLI provider.
• claude: routes map, review, fix, and revalidate through local Claude Code CLI print mode.
• pi: routes review, fix, revalidate, and agent map through pi.dev.
• cursor: experimental Cursor Agent CLI provider. Treat it as opt-in only; do not use it unless the user explicitly asks or the target config already chooses it.

Useful provider controls:

clawpatch review --provider claude --json
clawpatch review --reasoning-effort high --json
CLAWPATCH_REASONING_EFFORT=high clawpatch review --json
CLAWPATCH_CODEX_SANDBOX=workspace-write clawpatch review --json

Use provider-specific flags only when they are relevant. Do not turn a normal Clawpatch pass into a provider experiment.

Initialize And Map

Use this only when the target repo truly has no Clawpatch state.

clawpatch init
clawpatch map
clawpatch status --json

clawpatch init creates .clawpatch/config.json. The default config excludes large/generated folders and .clawpatch/**, uses the local Codex provider, and sets git.requireCleanWorktreeForFix: true.

Do not run clawpatch init in plate-2 when the target is .tmp/slate-v2. Run commands from the actual target root.

Review

Plain review:

clawpatch review --json

Batch review:

clawpatch review --limit 10 --json

Specific feature:

clawpatch review --feature <featureId> --json

Dry-run queue check:

clawpatch review --dry-run --json

Hard rule: clawpatch review --json reviews the eligible queue, not necessarily every feature record on disk. reviewed: 0 can be correct when clawpatch review --dry-run --json says wouldReview: 0, even if clawpatch status --json reports many feature records.

Review controls added in current Clawpatch:

clawpatch review --include-dirty --json
clawpatch review --prompt-file review-guidance.md --json
clawpatch review --prompt-file - --json
clawpatch review --export-tribunal-ledger .clawpatch/runs/review-ledger.jsonl --json
clawpatch review --jobs 4 --json
clawpatch review --rate-limit-per-minute 20 --json
CLAWPATCH_RPM=20 clawpatch review --json
CLAWPATCH_REVIEW_RETRIES=2 clawpatch review --json
clawpatch review --prompt-retries 2 --json

Rules for these controls:

• Use --include-dirty when the point is to audit uncommitted local changes.
• Use --prompt-file for extra reviewer law instead of pasting huge guidance into chat.
• Use --export-tribunal-ledger only when downstream ingestion is explicitly useful.
• Leave --jobs unset unless local resources or provider limits demand it; Clawpatch defaults to a CPU-aware value capped at 10.
• Use --rate-limit-per-minute / CLAWPATCH_RPM for provider quota pressure, not as a substitute for narrowing scope.
• Use retry controls only for transient malformed-provider output. Do not retry deterministic auth, quota, unsupported-provider, refusal, or cancellation failures as if they are flaky findings.

Current review output is stricter than older runs: provider findings must cite included files, valid line ranges, and matching evidence quotes. A run can complete while dropping invalid individual findings into run.errors with schema-drop or validation-drop. Always inspect run.errors before claiming the review was clean.

Prompt provenance and budget accounting are now part of review output. When a review looks oddly small or noisy, inspect included files, omitted files, prompt bytes, and approximate token counts before blaming the reviewer model.

CI

Use CI mode when the user asks for a one-command automation path or a GitHub Actions summary:

clawpatch ci --json
clawpatch ci --since HEAD~1 --json
clawpatch ci --include-dirty --json
clawpatch ci --jobs 4 --rate-limit-per-minute 20 --json

clawpatch ci --since can legitimately report reviewed: 0 on an empty filtered diff. Treat that as an empty queue, not a failed run.

Force Re-Review All Features

When the user asks to re-review all known features, do not use plain clawpatch review. Force each feature explicitly.

mkdir -p .clawpatch/runs/forced-rereview-$(date -u +%Y%m%dT%H%M%SZ)
jq -r '.featureId' .clawpatch/features/*.json | sort > .clawpatch/runs/forced-rereview/features.txt

while IFS= read -r feature_id; do
  clawpatch review --feature "$feature_id" --json
done < .clawpatch/runs/forced-rereview/features.txt

For long runs, record each result to JSONL so interruption is recoverable:

run_dir=".clawpatch/runs/forced-rereview-$(date -u +%Y%m%dT%H%M%SZ)"
mkdir -p "$run_dir"
jq -r '.featureId' .clawpatch/features/*.json | sort > "$run_dir/features.txt"

while IFS= read -r feature_id; do
  printf '%s\n' "$feature_id"
  if output=$(clawpatch review --feature "$feature_id" --json 2>&1); then
    printf '{"featureId":%s,"ok":true,"output":%s}\n' \
      "$(jq -Rn --arg v "$feature_id" '$v')" \
      "$(jq -Rn --arg v "$output" '$v')" >> "$run_dir/review-results.jsonl"
  else
    printf '{"featureId":%s,"ok":false,"output":%s}\n' \
      "$(jq -Rn --arg v "$feature_id" '$v')" \
      "$(jq -Rn --arg v "$output" '$v')" >> "$run_dir/review-results.jsonl"
  fi
done < "$run_dir/features.txt"

Avoid zsh's reserved status variable in shell loops. Use names like ok, exit_code, or feature_status.

Report And Triage

Open findings:

clawpatch report --status open --json
clawpatch status --json
clawpatch next --json

Markdown report:

clawpatch report

Filtered reports:

clawpatch report --severity high --json
clawpatch report --feature <featureId> --json
clawpatch report --category <category> --json
clawpatch report --triage <triage> --json
clawpatch report --output .clawpatch/reports/open.md

A report may include old findings with non-open statuses. Do not count the whole Markdown report as current work. Use report --status open --json and status --json for the live queue.

For JSON reports, prefer total and items as the stable shape. results is an alias, and the legacy findings key is a count, not the finding array.

False positives should be recorded in Clawpatch, not silently ignored:

clawpatch triage --finding <findingId> --status false-positive --note "<evidence>"

Use wont-fix only for a deliberate product/architecture decision. Use uncertain when evidence is insufficient.

Fix

Fix is explicit and one finding at a time:

clawpatch fix --finding <findingId> --json

Default safety blocks fixes on a dirty worktree:

{
  "git": {
    "requireCleanWorktreeForFix": true,
    "commit": false,
    "openPr": false
  }
}

For a local multi-finding fix batch where Clawpatch dirties the tree with its own prior patch, it is acceptable to temporarily set requireCleanWorktreeForFix: false, run the batch, then restore it to true before handoff. Record this in the plan.

Never let Clawpatch commit, push, or open PRs in this repo unless the user explicitly asks for that behavior.

Patch-to-PR is explicit:

clawpatch open-pr --patch <patchId> --json

In plate-2, do not use clawpatch open-pr just because a patch exists. It creates git state and remote side effects. Use it only when the user explicitly asks for Clawpatch to open the PR; otherwise keep patches local and report the finding/patch ids.

Revalidate

Use revalidation after manual fixes, Clawpatch patches, or upstream changes:

clawpatch revalidate --finding <findingId> --json

Broader revalidation:

clawpatch revalidate --all --status open --json
clawpatch revalidate --feature <featureId> --json
clawpatch revalidate --since HEAD~1 --json
clawpatch revalidate --limit 10 --status open --json
clawpatch revalidate --include-dirty --json

Trust revalidation scope. If source is fixed but the finding remains open because exported artifacts are stale, rebuild the relevant package and revalidate again.

Example from Slate v2:

bun --filter slate-react build
clawpatch revalidate --finding <findingId> --json

Locks

clawpatch status --json reports activeLocks and lockFiles. If locks remain after a process exits, inspect before cleaning:

find .clawpatch/locks -maxdepth 1 -type f -print -exec sed -n '1,120p' {} \;
ps -p <pid-from-lock> -o pid=,comm= 2>/dev/null || true

If the process is gone and no Clawpatch run is active, clean stale locks:

clawpatch clean-locks --json

Do not delete lock files manually unless clean-locks is unavailable and the process is proven dead.

Mapping Notes

Current Clawpatch has broader mapper coverage than older local habits:

• Node app roots under apps/* and packages/* can map even without a local package file when positive source/framework signals exist.
• Bun text lockfiles are detected as bun.lock.
• Node route mapping preserves literal Express, Hono, Flask, Django include, FastAPI router, Laravel group, Fastify, and Rails route prefixes more reliably.
• Maven/Spring projects have dedicated root, nested, and multi-module mapping.
• Large flat directories are split by repeated filename families into more coherent review slices.

Do not paper over a weird map by assuming the old mapper limits still apply. Run clawpatch map --json or inspect the feature record first.

Slate V2 Operating Rules

• Default target: .tmp/slate-v2 from the plate-2 root when the user says the Slate v2 Clawpatch state moved there.
• Keep .clawpatch/ ignored. The state can be huge and local.
• Use the active goal plus one docs/plans/** goal plan for restartable progress when the run spans many commands. Do not create hook fallback state.
• pending means more autonomous work remains.
• done means the active Clawpatch target is met.
• blocked means the target cannot continue without restored state, missing tooling, or a user decision.

Verification Closeout

For review-only work:

clawpatch status --json
clawpatch report --status open --json
node .agents/rules/autogoal/scripts/check-complete.mjs docs/plans/<goal-plan>.md

For fix work, run the configured Clawpatch validation plus the repo's relevant checks. In Slate v2 batches this has usually meant:

npm run typecheck
npm run lint:fix
npm run lint
npm run test
clawpatch status --json

For generated skills in plate-2, after editing .agents/rules/*.mdc or .agents/AGENTS.md, run:

pnpm install

Then verify the generated skill mirrors the source:

test -f .agents/skills/clawpatch/SKILL.md
rg -n "Force Re-Review All Features|review --dry-run|requireCleanWorktreeForFix|\\.tmp/slate-v2" .agents/rules/clawpatch.mdc .agents/skills/clawpatch/SKILL.md