Macroscope

View saved version →

---
name: autoloop
description: Run the local review-fix-verify loop until the branch is clean.
---

Run a local-only Macroscope autopilot cycle using the installed CLI:

**local review -> fix -> verify -> re-review -> repeat**

This mode applies fixes directly to the working tree. It does not interact with GitHub, PRs, or remote correctness checks.

- Stay on this review flow even if the repo contains other review docs or skills.
- Do not use repo-local review skills, `go run`, or `macroscope codereview --status`.

## 1. Initialize the loop

1. Capture the current branch name and `HEAD`.
2. Keep an iteration counter and cap the loop at **5** iterations.

## 2. Determine the local review scope

```bash
base_branch="$(git symbolic-ref --quiet refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')"
if [ -z "$base_branch" ] && ! git remote get-url origin >/dev/null 2>&1; then
  # No origin remote: fall back to a local default branch. When origin exists but
  # its default branch cannot be determined, leave base_branch empty and fail
  # closed below rather than guessing a local branch.
  for candidate in "$(git config --get init.defaultBranch)" main master; do
    [ -n "$candidate" ] && git rev-parse --verify --quiet "refs/heads/${candidate}^{commit}" >/dev/null && { base_branch="$candidate"; break; }
  done
fi
```

- Use the resulting `base_branch` as the comparison branch.
- If `base_branch` is empty (for example `origin` is configured but has no resolvable default branch), stop and explain why — never guess a local branch when `origin` exists.
- Resolve the comparison as `base_ref`. `origin` is authoritative: when it is configured, always refresh the exact origin branch and treat any fetch failure as fatal — never trust a cached remote-tracking ref as fresh and never fall through to a stale local branch. Use a local branch only when there is no `origin` remote:

```bash
# origin is authoritative. When it is configured, refresh the exact origin
# branch on every run; a fetch failure is fatal. Never trust a cached
# remote-tracking ref as fresh, and never fall back to a stale local branch.
# A local branch is used only when there is no origin remote.
if git remote get-url origin >/dev/null 2>&1; then
  if ! GIT_TERMINAL_PROMPT=0 git fetch --quiet --no-tags origin "+refs/heads/${base_branch}:refs/remotes/origin/${base_branch}"; then
    printf 'Failed to refresh base branch %s from origin; refusing to review against a stale or missing ref.\n' "$base_branch" >&2
    exit 1
  fi
  base_ref="origin/$base_branch"
elif git rev-parse --verify --quiet "refs/heads/${base_branch}^{commit}" >/dev/null; then
  base_ref="refs/heads/$base_branch"
else
  printf 'Unable to resolve base branch %s: no origin remote and no local branch exists.\n' "$base_branch" >&2
  exit 1
fi
```

- If `git rev-parse --abbrev-ref HEAD` exactly equals `base_branch`, skip `--base` and review local changes only.
- Otherwise use `--base "$base_ref"`.

## 3. Run the local CLI review (Codex-adapted)

Codex has a tool-call timeout that is shorter than the `codereview` blocking duration. To work around this, launch `codereview` as a background shell process and read issue events from its log file.

- Always pass `--auto-update`. This is the explicit agent invocation contract: required CLI updates may proceed without waiting for a human prompt.
- Before launch, allocate a unique log file and PID file:

```bash
review_log="$(mktemp "${TMPDIR:-/tmp}/macroscope-review.XXXXXX")"
pid_file="$(mktemp "${TMPDIR:-/tmp}/macroscope-pid.XXXXXX")"
```

- Start the review in the background. Capture the child PID, then wait for it in the same shell so the process stays attached while later tool calls poll the log:

With `--base`:

```bash
macroscope codereview --raw --base "$base_ref" --auto-update > "$review_log" 2>&1 &
child_pid=$!
printf '%s\n' "$child_pid" > "$pid_file"
wait "$child_pid"
```

Without `--base`:

```bash
macroscope codereview --auto-update > "$review_

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: codereview
description: Run a local Macroscope code review on this branch.
---

Run a local Macroscope review using the installed CLI.

- Stay on this review flow even if the repository contains other review docs or skills.
- Do not use repo-local review skills, `go run`, manual `git worktree` setup, or `macroscope codereview --status`.
- The CLI is the source of truth for base resolution and isolation. By default it refreshes the authoritative base, creates an isolated review worktree, and captures uncommitted changes there. Do **not** recreate that logic in the skill.

## 1. Launch the review (Codex adapter)

Codex tool calls can time out before a review completes. Start one background shell session from the repository being reviewed; it must wait for the child so later tool calls can poll its log:

```bash
review_log="$(mktemp "${TMPDIR:-/tmp}/macroscope-review.XXXXXX")"
printf '%s\n' "$review_log"
macroscope codereview --raw --auto-update > "$review_log" 2>&1 &
child_pid=$!
printf '%s\n' "$child_pid"
wait "$child_pid"
```

- Always pass `--auto-update`. It is the explicit agent invocation contract for required CLI updates.
- Default to the CLI-created review worktree. Only when the user explicitly asks for in-place fixes, add `--in-place` to the launch and apply fixes in their checkout. Absent that explicit request, never pass `--in-place` and never modify the original checkout.
- Do not pass `--base` unless the user explicitly supplies a comparison ref; the CLI validates and resolves it.
- Keep this shell session alive; use separate calls to read `"$review_log"`. Do not start another review or use `macroscope codereview --status`.

## 2. Follow the stream contract

All machine tokens arrive on **stderr**; the launch above redirects them into `"$review_log"`. They are emitted at different times; do not wait for late tokens before starting work:

1. `review_session_id=<uuid>` — emitted first and stable across retries. Capture it as the startup signal.
2. `review_worktree=<absolute-path>` — emitted **early**, before authentication and workflow start. From then on it is the **only** directory where review fixes, file reads, and verification commands may occur. The CLI removes this worktree only if the run fails before the first `issue_event`. Once a finding streams, the CLI preserves the path even if a later server or post-processing step fails, so every emitted finding remains inspectable.
3. `issue_event=<json>` — findings stream while the review runs. Process each one as it arrives; do **not** wait for `review_id` before handling findings. Use a tracked line offset when polling so findings are not processed twice.
4. `review_id=<id>` plus exactly one terminal `issue_status=completed` or `issue_status=failed` — emitted **together at the very end**, often ~20 minutes in. Long silent gaps (15+ minutes after the last `issue_event`) are normal.

Do not wait for `review_id=` before processing issues. Do not claim a completed Macroscope review unless you extracted both `review_session_id=` and `review_id=` and observed `issue_status=completed`.

**Stay attached.** Do not end your turn. Do not return a final response, kill the child, or abandon the review during a silence: the review is not done until the terminal `issue_status=` line appears in the log, and abandoning the process early is the most common failure mode. Keep polling `"$review_log"` until that terminal status or child exit. Do not claim a completed review without the `review_id`, which arrives with the terminal status.

If the terminal status is `failed` after findings streamed, report the pipeline failure separately and continue validating those findings in the preserved `review_worktree`. A late failure does not invalidate or erase already-emitted findings.

The CLI emits `review_worktree=` only when it creates a worktree, and it legitimately skips creation in exactly two cases: a user-requested `--in-place` run, and a run launched from inside an existin

Preview of the first 4,000 characters. Read full instructions →