box

---
name: box
description: >
license: MIT
---

# Box

## Flags

| Flag | Default | Effect |
|---|---|---|
| `--persist` | off | Upsert the local repo in the working directory's `AGENTS.md` |
| `--update` | off | Pull an existing clone before search |
| `--list` | off | List the manifest and stop |
| `--no-subagents` | off | Run every stage in the main thread |

No flags clone if needed, search, and report. Never persist without
`--persist`.

## Paths and mode

Resolve `<anchor>` as the absolute directory containing this `SKILL.md`.
Use `<anchor>/sandbox/manifest.json` and `<anchor>/sandbox/<slug>/`. Include
absolute paths in every brief. Resolve the working directory and its
`AGENTS.md` to absolute paths; never place sandbox data there.

Use Direct mode for `--no-subagents` or when no subagent tool exists. Otherwise
use Delegated mode. Direct runs each contract itself. Delegated uses one Prepare
writer, disjoint read-only Search workers, and one Persist writer; the
coordinator only detects, dispatches, aggregates, and reports.
In Delegated mode the coordinator never executes a stage contract. A failed
stage worker makes the run `BLOCKED`. Direct mode uses the same ledger.

Record:
`mode | slug | URL | prepare | search scopes | persist | current | terminal`.
After interruption, verify the manifest, clone, returned search evidence, and
persist markers. Resume at the earliest incomplete done condition and
redispatch any search scope without a result.

## 1. Detect

`--list` or a bare invocation treats a missing manifest as `[]`, prints each
slug, URL, and local path, marks invalid clones stale, then stops. With a URL,
use its final path segment without `.git` as the slug. With a name, match slug
case-sensitively. Zero or several matches ask for the URL.

Done when the list is reported or slug, URL, and local path are resolved.

## 2. Prepare

Run or dispatch the Prepare contract in `./REFERENCE.md`. Wait before search.
A failed or partial clone is never added to the manifest. On retry, move a
manifest-free invalid clone to a timestamped `.partial` sibling before cloning;
never delete an unknown directory.

Done when the local path contains a valid clone, its origin matches the URL,
and the manifest entry is current, or a prepare error is reported.

## 3. Search

Run or dispatch the Search contract in `./REFERENCE.md`. Partition parallel
workers by non-overlapping subtree or question. If the request gives no
question, inspect structure, README, manifests, and entry points. Bound each
worker to its scope and require `path:line` citations or `no matches`. Reject
overlapping scopes before dispatch.

Done when every scope returned evidence or an explicit no-match result.

## 4. Aggregate and persist

Answer the user's question by theme, deduplicate citations, and disclose
unsearched areas. With `--persist`, run or dispatch the Persist contract only
after search. It may edit only the working directory's `AGENTS.md`.

Done when the answer is cited and, when requested, the marker block exists
exactly once.

## 5. Report

Report repo, absolute local path, prepare status, searched scopes, no-match
areas, and persist status. Terminal values are `SUCCESS`, `BLOCKED`, and
`NO_MATCHES`. Use `NO_MATCHES` only when every scope returned no matches.

Never push, commit inside clones, infer contents from a URL, or let stages
overlap their write ownership.