# Sidequest

> Run a task in a background git worktree that opens a PR, so your main checkout stays free to keep working.

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

## Install

```sh
agentstack add skill-samanpwbb-sidequest-claude-skill-skill
```

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

## About

You are a dispatcher. Your job is to explicitly create an isolated worktree, launch a background agent inside it, then hand off to `/loop` so you can tail the worker's status file and report progress as it writes.

## ⚠️ Prerequisites — required settings.json permissions

The worker runs as a background sub-agent. Background sub-agents CANNOT prompt the user for bash permission, so any command not pre-approved in `~/.claude/settings.json` (or project `.claude/settings.local.json`) silently fails. The following patterns MUST exist in `permissions.allow` before /sidequest can succeed:

- `Bash(git worktree add:*)`
- `Bash(git worktree remove:*)`
- `Bash(git -C:*)`
- `Bash(yarn --cwd:*)` (or `Bash(npm --prefix:*)` / `Bash(pnpm --dir:*)` / `Bash(pnpm -C:*)` for that package manager)
- `Bash(gh -R:*)`
- `Bash(gh repo view:*)`

Notes:
- Settings changes may require a Claude Code session restart to take effect. If the worker was launched in a session that started before these patterns were added, it won't see them.
- `permissions.deny` must not block `git worktree …` or `git -C …`. A blanket `git checkout:*` deny is fine — the worker never checks out (the dispatcher uses `git worktree add -b`).
- If the worker reports `STATUS: isolation-failed` on its first verification step and the status file is empty, a missing permission pattern is almost always the cause.

## Step 1 — gather context

1. `git rev-parse --abbrev-ref HEAD` → `$PARENT_BRANCH`
2. `git rev-parse --show-toplevel` → `$PARENT_REPO_ROOT`
3. Detect package manager from lockfile (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `package-lock.json` → npm) → `$PACKAGE_MANAGER`
4. `gh repo view --json nameWithOwner -q .nameWithOwner` → `$GH_REPO` (e.g. `puzzmo-com/app`). Needed so the worker can run `gh` without changing directory.
5. Generate a branch name: `sidequest/` (2-4 word kebab-case summary of the task) → `$BRANCH_NAME`
6. Compute a slug from `$BRANCH_NAME` (replace `/` with `-`) → `$SLUG`
7. `$WORKTREE_PATH = /tmp/sidequest-worktrees/$SLUG`
8. `$STATUS_FILE = /tmp/sidequest-$SLUG.log`

## Step 2 — create the worktree and status file

9. `mkdir -p /tmp/sidequest-worktrees`
10. `git worktree add -b $BRANCH_NAME $WORKTREE_PATH` — creates the branch AND the worktree in one step, with the worktree already checked out on the new branch. If this fails (e.g. branch or path already exists), stop and report the error so the user can clean up.
11. `: > $STATUS_FILE` — create/truncate the status file.

## Step 3 — launch the worker

Call the Agent tool with:
- `subagent_type`: `"sidequest-worker"`
- `run_in_background`: `true`
- prompt: only the block below, with variables interpolated:

```
Task: $ARGUMENTS

Context:
- parent_branch: $PARENT_BRANCH
- parent_repo_root: $PARENT_REPO_ROOT
- branch_name: $BRANCH_NAME
- worktree_path: $WORKTREE_PATH
- package_manager: $PACKAGE_MANAGER
- gh_repo: $GH_REPO
- status_file: $STATUS_FILE
```

Do NOT pass `isolation: "worktree"`. The worktree is managed explicitly in Step 2 — passing the isolation flag would tell the runtime to create a *second* worktree on the same branch and fail.

Report to the user, in this format:

```
Sidequest launched on branch `$BRANCH_NAME`.
- worktree: $WORKTREE_PATH
- status:   $STATUS_FILE  (tail -f to watch progress)
- cleanup:  auto-removed on a passing PR; on draft/blocked, run `git worktree remove --force $WORKTREE_PATH` manually
```

## Step 4 — start the progress loop

Invoke the `loop` skill via the Skill tool with no interval (self-paced). Pass these args verbatim:

```
Tail sidequest status file: $STATUS_FILE

On each tick:
1. Read $STATUS_FILE.
2. Compare the lines to what you have already told the user in this conversation. Emit any new lines as one short update each. If nothing is new, stay silent — that is the correct behavior.
3. If a line starting with `DONE` appears, post a final summary and end the loop (do NOT schedule another wake).
4. If a line starting with `STATUS: isolation-failed` or `STATUS: blocked:` appears, post it and end the loop.
5. Otherwise, pace the next tick 120–240s out.

You will also receive an Agent task-completion notification when the worker finishes. When that fires, read $STATUS_FILE one last time, emit any remaining lines, then end the loop.

Keep each update under ~15 words. The user can interrupt at any time.
```

Do not do anything else. The loop skill owns the rest.

## Source & license

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

- **Author:** [samanpwbb](https://github.com/samanpwbb)
- **Source:** [samanpwbb/sidequest-claude-skill](https://github.com/samanpwbb/sidequest-claude-skill)
- **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-samanpwbb-sidequest-claude-skill-skill
- Seller: https://agentstack.voostack.com/s/samanpwbb
- 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%.