# Branch Sandbox

> Create a branch, worktree, or scratch clone when a user explicitly requests isolation or a risky or parallel coding task needs a reversible workspace boundary. Use for broad refactors, migrations, autonomous runs, and concurrent work; skip routine micro-tasks and read-only investigation.

- **Type:** Skill
- **Install:** `agentstack add skill-aquish-lee-agent-handrails-branch-sandbox`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Aquish-Lee](https://agentstack.voostack.com/s/aquish-lee)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Aquish-Lee](https://github.com/Aquish-Lee)
- **Source:** https://github.com/Aquish-Lee/agent-handrails/tree/main/skills/branch-sandbox

## Install

```sh
agentstack add skill-aquish-lee-agent-handrails-branch-sandbox
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Branch Sandbox

Create only the isolation that materially reduces rollback, interference, or
working-tree risk. Isolation is a process boundary, not proof that a change is
correct or authorized.

Read [the local v2 contract](references/usable-loop-v2.md) when you need record
fields, authority rules, Checkpoint triggers, or runtime details.

## Decide whether to isolate

Use a worktree or branch for broad refactors, migrations, generated assets,
long autonomous work, experiments, concurrent tasks, production-like files, or
when the current checkout must remain usable. Prefer:

- no sandbox for a clear micro-task or read-only investigation;
- a branch when the checkout is clean and may be occupied by this task;
- a worktree when another branch/check-out must remain available;
- a scratch clone only for clean-clone, remote, or dependency isolation.

Do not silently pass control to another handrail. Return the sandbox result and
let the caller decide what happens next.

## Establish authority and state

Treat the current user request as authoritative when the user controls the task
and no permission or designated-source conflict exists. Otherwise mark derived
meaning provisional and expose the conflict.

Run the read-only preflight:

```bash
git rev-parse --show-toplevel
git status --short
git branch --show-current
git rev-parse HEAD
git worktree list
python /scripts/handrails_state.py inventory \
  --compact --repository . --base HEAD > 
```

Resolve `` from this installed `SKILL.md`, not from the project
working directory. Inside this source repository, `runtime/handrails_state.py`
is the canonical equivalent.

The runtime inventories staged, unstaged, committed-since-base, and untracked
state. Add ignored artifacts only with explicit `--declare-ignored` arguments.
Never infer or scan ignored caches, secrets, or local files. Keep the machine
inventory private and query only its digest, conflicts, counts, and path/layer
summary for the Work Boundary decision. The private path must be outside
participating worktrees or ignored and undeclared. Do not declare `.scratch`
merely because Handrails logs live there; declarations are only for ignored
content the task explicitly makes a candidate.

If a Review Boundary Seed exists, consume it as a hypothesis. Record actual
task-start state and the delta from the seed; do not convert expected paths into
an allowlist. Without a seed, report `No seed supplied`.

For a dirty checkout:

- keep it untouched by creating a worktree from a clean base when it is unrelated;
- include it only when the user says it belongs to this task;
- stop when ownership is ambiguous;
- stash only after explicit authorization.

## Create the boundary

Use a repository-conforming branch name. Typical commands are:

```bash
git switch -c /
git worktree add -b /  
git clone  
```

After creation, recapture branch, HEAD, status, and participating worktrees.
Return a compact Work Boundary containing:

- Task ID and Outcome Revision;
- workspace identity and actual task-start state;
- Review Boundary Seed delta, if any;
- participating workspaces and authorization guardrails;
- explicitly declared ignored artifacts;
- base/recovery identity, sandbox location, rollback path, and stale conditions.

Paths and expected changes remain hypotheses. The later claim/review boundary
must inventory all current candidates again.

## Safety and cleanup

Never auto-run stash, reset, rebase, overwrite, force branch deletion, or remove
a worktree that contains results. Ask for explicit authorization for each such
operation. By default, report the cleanup command and its preconditions without
executing it.

Before proposing worktree removal, show status, branch, HEAD, and whether the
results are integrated or recoverable. Never use isolation as a reason to hide
or delete pre-existing work.

## Direct result

Keep the ordinary result compact: chosen isolation, exact location/base,
captured dirty-state limitation, rollback/cleanup command, and the necessary
next step. Expand a Checkpoint only for a trigger listed in the local contract.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Aquish-Lee](https://github.com/Aquish-Lee)
- **Source:** [Aquish-Lee/agent-handrails](https://github.com/Aquish-Lee/agent-handrails)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-aquish-lee-agent-handrails-branch-sandbox
- Seller: https://agentstack.voostack.com/s/aquish-lee
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.