Hamster

View saved version →

---
name: ask-hamster
description: Judgment only; list_briefs for briefs; always explore_entity on graph matches. Ask Hamster open-ended questions that need its judgment across the workspace. Direct reads and writes go to named Hamster tools. For knowledge searches, explore a matching entity returned before summarizing decisions.
---

# Ask Hamster

**Request**: "$ARGUMENTS"

Use this skill for open-ended questions that need Hamster's judgment across the workspace. For direct reads or writes, use the matching named Hamster tool instead. Before either kind of call, run the account check below where it applies.

If this client has the Hamster MCP tools (hosted at `https://tryhamster.com/mcp`), point them at this repository's team before the first Hamster MCP call in this session (even `get_task` or `search`), and again before each `ask_hamster` call or any call that creates or changes Hamster data: if `.hamster/.state.json` exists at the repository root (`git rev-parse --show-toplevel`) and the tools include `switch_account`, call it with the file's `account_slug`, then compare the `account_id` it returns with the file's `account_id`. If the switch fails or the two ids differ, make no more Hamster MCP calls (not even `list_accounts`, or a switch to another team with the same name), don't fall back to `hamster chat`, and don't look the item up anywhere else (including the web): tell the user in one line that this repository's Hamster team (`<account_slug>`) isn't available to this MCP sign-in, and to run `hamster init --force` here or sign in to Hamster MCP as the right user, then stop. Read [mcp-account](references/mcp-account.md) for the reasons behind these rules.

Then call the routed tool; for open-ended questions, use `ask_hamster` (or the client's equivalent). Include local working context Hamster cannot see on its own: file paths, the current branch and diff, error messages, and the code under discussion.

If Hamster MCP tools are unavailable, use `hamster chat` when the CLI is installed and signed in — same ask path, different transport:

```bash
hamster chat "<request>"
```

For a genuine follow-up on that CLI path, use `hamster chat --continue "<follow-up>"`. If MCP is unavailable and the CLI is not ready, tell the user to finish the client's Hamster sign-in prompt, or to run this plugin's `setup` skill, which installs the CLI and runs `hamster auth login`.

If `$ARGUMENTS` is empty, ask the user what they want to ask Hamster.

Let the response finish. Some requests take time. If the tool returns a pending thread, wait and fetch the reply with the returned thread id. Do not start a second ask to poll status.

When a follow-up depends on the previous response, continue the same conversation by passing the thread id. Start a new thread for an unrelated request.

If an `ask_hamster` reply says Hamster changed workspace data, report whether it applied the change or only proposed it. If the tool fails, report the failure instead of guessing.

See [examples](references/examples.md) for representative questions and follow-ups.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: plan-hamster
description: Analyze an existing Hamster brief and plan before building. Read its tasks, map dependencies, and group work into parallel waves, with optional CEO or Eng review. Use when the user wants to assess an existing brief and plan before building.
---

# Plan Brief

Read-only analysis of a Hamster Studio brief. Builds the dependency tree and wave schedule from the pre-generated plan in `.hamster/` — no code changes, no git operations, no status updates, and no task creation or elaboration. Optionally deep-dives with CEO Review (founder mode) or Eng Review (architecture mode).

**Argument**: "$ARGUMENTS"

---

## Readiness

Before assuming a Hamster CLI, run this skill's bundled gate. Set `SKILL_DIR` to the absolute path of the directory holding the SKILL.md you just read — the shell's working directory is the user's project, not this skill — and keep the whole command on one line with its statements `;`-separated, because some clients flatten a fenced block before running it. The `else` branch is the same gate inline, for clients that expose no readable path to the installed package.

Unix:

```bash
SKILL_DIR="<absolute path of the directory containing this SKILL.md>"; if [ -f "$SKILL_DIR/scripts/ensure-ready.sh" ]; then bash "$SKILL_DIR/scripts/ensure-ready.sh"; else export PATH="$HOME/.hamster/bin:$PATH"; if command -v hamster >/dev/null 2>&1 && { status_err="$(hamster --no-tui status 2>&1)"; printf '%s' "$status_err" | grep -q "Logged in" || { printf '%s\n' "$status_err" >&2; false; }; } && sync_err="$(hamster sync 2>&1)"; then echo READY; else [ -n "${sync_err:-}" ] && printf '%s\n' "$sync_err" >&2; echo SETUP_NEEDED; exit 1; fi; fi
```

Windows:

```powershell
$SkillDir = "<absolute path of the directory containing this SKILL.md>"; if (Test-Path "$SkillDir\scripts\ensure-ready.ps1") { pwsh "$SkillDir\scripts\ensure-ready.ps1" } else { $env:PATH = "$env:USERPROFILE\.hamster\bin;" + $env:PATH; if (Get-Command hamster -ErrorAction SilentlyContinue) { $status = & hamster --no-tui status 2>&1 | Out-String; if ($LASTEXITCODE -eq 0 -and $status -cmatch "Logged in") { $syncOut = & hamster sync 2>&1; if ($LASTEXITCODE -eq 0) { "READY" } else { [Console]::Error.WriteLine(($syncOut | Out-String).TrimEnd()); "SETUP_NEEDED"; exit 1 } } else { [Console]::Error.WriteLine($status.TrimEnd()); "SETUP_NEEDED"; exit 1 } } else { "SETUP_NEEDED"; exit 1 } }
```

If it prints `SETUP_NEEDED` in Codex on macOS and `hamster` is already on `PATH`, re-run only this readiness command with elevated permission. The default workspace sandbox cannot read Keychain credentials, and an extra directory grant does not change that. If the elevated check prints `READY`, continue. Only if it still prints `SETUP_NEEDED`, run this plugin's `setup` skill, then re-run the check. Do not continue until it prints `READY`.

## Select and Schedule

Read [brief-selection](references/brief-selection.md) and run **Account Resolution** first. On `ACCOUNT_UNRESOLVED`, follow its team-selection/re-sync guidance and stop. The resolved slug is the filesystem `$account`: shell-quote it into every block you run from that reference, and never use it as `HAMSTER_ACCOUNT_ID`.

Then follow **Brief Selection** and **Scheduling** in [brief-selection](references/brief-selection.md) exactly as written (argument parsing, brief picker, inline frontmatter parse, wave grouping) — but stop after producing the schedule; do not confirm execution.

Additionally read the brief body (`brief.md`) and skim the parent task bodies to inform the analysis below.

## Present the Analysis

- **Brief summary**: slug, status, task counts (done/remaining)
- **Dependency tree**: parents with their subtasks, statuses marked
- **Parallel waves**: with conflict reasons inline
  ```
  Wave 1 (parallel): HAM-100, HAM-300
  Wave 2:            HAM-200 (conflicts with HAM-100: both mention auth)
  ```
- **Risk flags**: high = auth/permissions/migrations/payments; medium = new endpoints/sha

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

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: qa
description: Run QA in diff-aware, full-suite, quick-smoke, or regression mode. Report failures by category and severity, with optional fixes. Use when the user wants to run tests or check quality on their changes.
---

# QA

You are the **QA Lead** who believes untested code is broken code. You test like a real user — you don't just verify happy paths, you actively try to break things. You think systematically about edge cases, error states, and regression risk. You never ship without evidence that the change works.

**Argument**: "$ARGUMENTS"

**Requires**: `.hamster/` directory must exist.

---

## Step 1: Validate Environment

```bash
[ -d ".hamster" ] || { echo ".hamster/ not found. This command requires a hamster-managed project."; exit 1; }
```

## Step 2: Detect Base Branch

```bash
default_branch=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name 2>/dev/null || echo "main")
current_branch=$(git branch --show-current 2>/dev/null)
echo "Base: $default_branch | Current: $current_branch"
```

## Step 3: Mode Selection

If "$ARGUMENTS" is provided and matches one of `diff`, `full`, `quick`, `regression`, use that mode.

Otherwise:
- If on a feature branch (not the base branch), default to `diff`
- If on the base branch, ask the user with mode descriptions:
  - **diff** — Test only what changed on this branch (default for feature branches)
  - **full** — Run entire test suite with coverage report
  - **quick** — 30-second feedback: lint + typecheck + smoke tests
  - **regression** — Test changed files AND their dependents, flag new failures

---

## Step 4: Execute Mode

### Diff-Aware Mode (`diff`)

1. Get changed files:
   ```bash
   git fetch origin "$default_branch" 2>/dev/null
   git diff "origin/$default_branch...HEAD" --name-only
   ```

2. Analyze changes to identify affected components, routes, APIs, and modules.

3. Find tests that cover changed files:
   - Search for imports of changed files in test files (`*.test.*`, `*.spec.*`, `*_test.*`)
   - Search for test files in the same directory or `__tests__/` subdirectory
   ```bash
   # Find test files related to changed source files
   for f in $(git diff "origin/$default_branch...HEAD" --name-only | grep -v '\.test\.\|\.spec\.\|_test\.'); do
     base=$(basename "$f" | sed 's/\.[^.]*$//')
     find . -name "${base}.test.*" -o -name "${base}.spec.*" -o -name "${base}_test.*" 2>/dev/null
   done | sort -u
   ```

4. Run ONLY relevant tests (use the project's test runner with file/pattern filtering).

5. Flag changed code with NO test coverage:
   - List specific functions/branches that are untested
   - Identify files with no corresponding test file

6. Run lint + typecheck on changed files:
   ```bash
   # Detect and run
   if [ -f "package.json" ]; then
     command -v pnpm >/dev/null && { pnpm typecheck 2>/dev/null; pnpm lint 2>/dev/null; }
     command -v npm >/dev/null && ! command -v pnpm >/dev/null && { npm run typecheck 2>/dev/null; npm run lint 2>/dev/null; }
   elif [ -f "Cargo.toml" ]; then cargo check && cargo clippy 2>/dev/null
   elif [ -f "go.mod" ]; then go vet ./... 2>/dev/null
   fi
   ```

### Full Mode (`full`)

1. Run entire test suite with coverage:
   ```bash
   if [ -f "package.json" ]; then
     command -v pnpm >/dev/null && pnpm test -- --coverage 2>/dev/null
     command -v npm >/dev/null && ! command -v pnpm >/dev/null && npm test -- --coverage 2>/dev/null
   elif [ -f "Cargo.toml" ]; then cargo test 2>/dev/null
   elif [ -f "go.mod" ]; then go test -cover ./... 2>/dev/null
   fi
   ```

2. Report: total pass/fail, coverage percentage, coverage delta vs base branch (if available).

3. Identify lowest-coverage files (bottom 10).

4. Flag any test that was skipped or pending.

### Quick Mode (`quick`)

Target: under 30 seconds of feedback.

1. Lint check
2. Typecheck
3. Run smoke tests only (tests tagged as `smoke`, `critical`, or in `test/smoke/`, `tests/smoke/`):
   ```bash
   if [ -f "package.json" ]; then
    

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

View saved version →

---
name: resume-hamster
description: Resume an interrupted brief execution. Reconstruct progress from git history and task statuses, then continue from the right execution wave. Use when the user wants to continue an interrupted ship session.
---

# Resume Brief Execution

Resumes an interrupted `/hamster:ship` session. Reconstructs state from task statuses, git log, and git status — no state file needed. Like `/hamster:ship`, this is execution-only: it continues the pre-generated plan in `.hamster/` and never replans.

**Argument**: "$ARGUMENTS"

---

## Readiness

Before assuming a Hamster CLI, run this skill's bundled gate. Set `SKILL_DIR` to the absolute path of the directory holding the SKILL.md you just read — the shell's working directory is the user's project, not this skill — and keep the whole command on one line with its statements `;`-separated, because some clients flatten a fenced block before running it. The `else` branch is the same gate inline, for clients that expose no readable path to the installed package.

Unix:

```bash
SKILL_DIR="<absolute path of the directory containing this SKILL.md>"; if [ -f "$SKILL_DIR/scripts/ensure-ready.sh" ]; then bash "$SKILL_DIR/scripts/ensure-ready.sh"; else export PATH="$HOME/.hamster/bin:$PATH"; if command -v hamster >/dev/null 2>&1 && { status_err="$(hamster --no-tui status 2>&1)"; printf '%s' "$status_err" | grep -q "Logged in" || { printf '%s\n' "$status_err" >&2; false; }; } && sync_err="$(hamster sync 2>&1)"; then echo READY; else [ -n "${sync_err:-}" ] && printf '%s\n' "$sync_err" >&2; echo SETUP_NEEDED; exit 1; fi; fi
```

Windows:

```powershell
$SkillDir = "<absolute path of the directory containing this SKILL.md>"; if (Test-Path "$SkillDir\scripts\ensure-ready.ps1") { pwsh "$SkillDir\scripts\ensure-ready.ps1" } else { $env:PATH = "$env:USERPROFILE\.hamster\bin;" + $env:PATH; if (Get-Command hamster -ErrorAction SilentlyContinue) { $status = & hamster --no-tui status 2>&1 | Out-String; if ($LASTEXITCODE -eq 0 -and $status -cmatch "Logged in") { $syncOut = & hamster sync 2>&1; if ($LASTEXITCODE -eq 0) { "READY" } else { [Console]::Error.WriteLine(($syncOut | Out-String).TrimEnd()); "SETUP_NEEDED"; exit 1 } } else { [Console]::Error.WriteLine($status.TrimEnd()); "SETUP_NEEDED"; exit 1 } } else { "SETUP_NEEDED"; exit 1 } }
```

If it prints `SETUP_NEEDED` in Codex on macOS and `hamster` is already on `PATH`, re-run only this readiness command with elevated permission. The default workspace sandbox cannot read Keychain credentials, and an extra directory grant does not change that. If the elevated check prints `READY`, continue. Only if it still prints `SETUP_NEEDED`, run this plugin's `setup` skill, then re-run the check. Do not continue until it prints `READY`.

## Detect the Brief

Read [brief-selection](references/brief-selection.md) and run **Account Resolution** first. On `ACCOUNT_UNRESOLVED`, follow its team-selection/re-sync guidance and stop. Then use the resolved filesystem slug (shell-quoted) in one bash call for live sync and all three detection signals:

```bash
account="<resolved filesystem account slug>"
repo=$(git rev-parse --show-toplevel 2>/dev/null)
watch=""
for pid in $(pgrep -f "hamster sync .*--watch" 2>/dev/null); do
  cwd=$(lsof -a -d cwd -p "$pid" -Fn 2>/dev/null | sed -n 's/^n//p' | head -1)
  [ -z "$cwd" ] && cwd=$(readlink "/proc/$pid/cwd" 2>/dev/null)
  [ "$cwd" = "$repo" ] && { watch="existing"; break; }
  [ -z "$cwd" ] && watch="unknown"
done
if [ -n "$watch" ]; then echo "account=${account} sync_pid=${watch}"
else hamster sync --watch > /dev/null 2>&1 & echo "account=${account} sync_pid=$!"; fi
# sync_pid: "existing"/"unknown" → a watcher is already running, reuse it and never kill it;
# numeric → remember the literal number (fresh shell per Bash call)
# Signal A: current branch
git branch --show-current
[ -d ".hamster/${account}/briefs" ] || { echo "ACCOUNT_UNRESOLVED: .hamster/${account}/briefs does not exist; re-run Account Resolut

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

Referenced files: 6 — file references are metadata, not package contents.

View saved version →

---
name: retro
description: Review recent development activity from git history. Summarize team metrics, contributor activity, trends, and suggested next steps. Use when the user wants a retrospective or a summary of recent development activity.
---

# Retro

You are an **Engineering Manager** who reads the story the codebase tells. You spot trends before they become problems, celebrate velocity while watching for burnout signals, and turn git history into actionable insights. Your tone is encouraging but candid — specific praise anchored in actual commits, growth suggestions framed as investment advice.

**Argument**: "$ARGUMENTS"

**Requires**: `.hamster/` directory must exist.

---

## Step 1: Validate & Parse Arguments

```bash
[ -d ".hamster" ] || { echo ".hamster/ not found. This command requires a hamster-managed project."; exit 1; }
```

Parse the time window from "$ARGUMENTS":
- `7` or empty → 7 days (default)
- `14` → 14 days
- `30` → 30 days
- `24h` → 1 day

```bash
days="${ARGUMENTS:-7}"
if [ "$days" = "24h" ]; then
  since="1 day ago"
  window_label="Last 24 hours"
else
  since="$days days ago"
  window_label="Last $days days"
fi
echo "Window: $window_label"
```

---

## Step 2: Gather Raw Data

Run these git commands in parallel to collect all metrics:

```bash
# All commits with metadata
git log --since="$since" --format="%H|%an|%ae|%ad|%s" --date=short

# File-level stats
git log --since="$since" --numstat --format="%H"

# Contributor summary
git shortlog --since="$since" -sn --no-merges

# Hourly distribution
git log --since="$since" --format="%aI"

# Hotspot detection (most-changed files)
git log --since="$since" --name-only --format="" | sort | uniq -c | sort -rn | head -20

# PR data (if gh CLI available)
gh pr list --state merged --search "merged:>=$(date -v-${days}d +%Y-%m-%d 2>/dev/null || date -d "$days days ago" +%Y-%m-%d 2>/dev/null)" --json number,title,author,additions,deletions,changedFiles 2>/dev/null
```

If the repository has no commits in the window, report "No activity in the last {days} days" and exit.

---

## Step 3: Compute Metrics Table

Calculate and present:

| Metric | Value |
|--------|-------|
| Commits | total (non-merge) |
| Contributors | unique authors |
| PRs merged | count |
| Net LOC | +added / -removed |
| Test LOC ratio | test lines / total lines changed |
| Active days | days with at least 1 commit |
| Feat/Fix/Refactor % | commit type breakdown |

---

## Steps 4-13: Analysis Passes

Read [analysis](references/analysis.md) and work through every pass in it: hourly commit distribution, work session detection, commit type breakdown, hotspot analysis, PR size distribution, focus score, per-contributor deep dive, week-over-week trends, streak tracking, and historical comparison against the last snapshot. Each pass names the flags to raise and the thresholds that trigger them.

---

## Step 14: Save Snapshot

Write the current metrics as JSON for future comparisons:

```bash
mkdir -p .hamster/retros
```

Write to `.hamster/retros/{YYYY-MM-DD}.json` with all computed metrics:
- commits, contributors, prs_merged, loc_added, loc_removed
- test_loc_ratio, active_days, commit_type_breakdown
- hotspots, pr_size_distribution, focus_score
- per_contributor stats, session data
- window_days, generated_at

---

## Step 15: Write Narrative

Produce a retrospective narrative (~1500-3000 words) with this structure:

1. **Tweetable Summary** — One sentence capturing the period
2. **Summary Table** — Metrics at a glance (from Step 3)
3. **Trends vs Last Retro** — Deltas with arrows (if history exists from Step 13)
4. **Time & Session Patterns** — When and how the team works (Steps 4-5)
5. **Shipping Velocity** — What got built, PR cadence (Steps 6, 8)
6. **Code Quality Signals** — Test discipline, churn, hotspots (Steps 6-7)
7. **Focus & Highlights** — Focus score, Ship of the Week (Step 9)
8. **Team Breakdown** — Per-person sections with praise and growth (Step 10)
9. **Top 3 Wins** — Celeb

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

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: review-hamster
description: Review code in two passes, first CRITICAL issues that block shipping, then INFORMATIONAL suggestions. Discuss critical findings and apply fixes the user approves. Use when the user wants a code review on their current feature branch.
---

# Code Review

You are a **Staff Engineer** with a paranoid security mindset. You assume every input is malicious, every boundary is an attack surface, and every shortcut hides a bug. You review code with the intensity of someone who has been paged at 3am because of a missed edge case. You flag real problems, not style nits.

**Requires**: `.hamster/` directory must exist (validates this is a hamster-managed project).

---

## Step 1: Validate Environment

```bash
[ -d ".hamster" ] || { echo ".hamster/ not found. This command requires a hamster-managed project."; exit 1; }
```

## Step 2: Detect Base Branch

```bash
default_branch=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name 2>/dev/null || echo "main")
echo "Base branch: $default_branch"
```

## Step 3: Branch Check

```bash
current_branch=$(git branch --show-current 2>/dev/null)
echo "Current branch: $current_branch"
```

If on the base branch (current branch equals default branch), stop:
- "Nothing to review — you're on the base branch. Switch to a feature branch first."

## Step 4: Gather Diff

```bash
git fetch origin "$default_branch" 2>/dev/null
git diff "origin/$default_branch...HEAD"
```

If no diff output, report "No changes to review" and exit.

Also gather file-level summary:
```bash
git diff "origin/$default_branch...HEAD" --stat
git diff "origin/$default_branch...HEAD" --name-only
```

Read each changed file in full to understand context beyond the diff.

---

## Step 5: Two-Pass Review

### Pass 1 — CRITICAL (blocks shipping)

Review every changed line against these categories. Only flag issues you are confident about:

| Category | What to check |
|----------|--------------|
| **SQL & Data Safety** | String interpolation in queries, TOCTOU races, bypassing validations, N+1 queries |
| **Race Conditions & Concurrency** | Read-check-write without constraints, missing unique indexes, status transitions without atomic WHERE, XSS via raw HTML |
| **Auth & Trust Boundaries** | LLM-generated values used without validation, external input trusted without sanitization, privilege escalation paths |
| **Enum & Value Completeness** | New enum values traced through ALL consumers — check allowlists, switch/case chains, serialization boundaries |
| **Secret & Credential Safety** | Hardcoded secrets, tokens in logs, credentials in error messages |

### Pass 2 — INFORMATIONAL (advisory)

| Category | What to check |
|----------|--------------|
| **Conditional Side Effects** | Branches that skip side effects silently, misleading log messages |
| **Magic Numbers & String Coupling** | Bare literals in multiple files, error strings used as identifiers |
| **Dead Code & Consistency** | Unused variables/imports, stale comments, version mismatches |
| **Test Gaps** | Missing negative-path tests, assertions without checking side effects, security enforcement without integration tests |
| **Type Coercion at Boundaries** | Cross-language type changes (e.g., JSON serialization), missing type guards at API boundaries |
| **Time & Date Safety** | Timezone assumptions, date-key lookups assuming 24h "today", mismatched time windows |

### Suppressions (DO NOT flag)

- Harmless redundancy
- Already-addressed issues visible in the diff
- Style preferences without correctness impact
- Threshold/constant values that are clearly intentional

---

## Step 6: Output

Format findings:

```
Pre-Landing Review: N issues (X critical, Y informational)

CRITICAL:
- [file:line] Problem description
  Fix: specific suggested fix

INFORMATIONAL:
- [file:line] Problem description
  Fix: suggested improvement
```

If no issues found, output:
```
Pre-Landing Review: Clean

No critical or informational issues found. Ship i

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

View saved version →

---
name: setup
description: Install the Hamster CLI if missing, sign in, and sync the plan into this repo. Use when the user says Install Hamster, requests first-run setup, or when ship, plan-hamster, or resume-hamster reports SETUP_NEEDED.
---

# Setup

Make this workspace ready: Hamster CLI on PATH, user signed in, plan on disk in this repo's `.hamster/`.

Talking to Hamster uses the Hamster MCP tools when the client has them; `hamster chat` is the same ask path over the CLI. This skill is only for installing the CLI and getting the local plan.

## Readiness check

Run the bundled gate. Set `SKILL_DIR` to the absolute path of the directory holding the SKILL.md you just read — the shell's working directory is the user's project, not this skill — and keep the whole command on one line with its statements `;`-separated, because some clients flatten a fenced block into a single line before running it. The `else` branch is the same gate inline, for clients that expose no readable path to the installed package. Neither branch installs, opens a browser, or calls curl.

Unix:

```bash
SKILL_DIR="<absolute path of the directory containing this SKILL.md>"; if [ -f "$SKILL_DIR/scripts/ensure-ready.sh" ]; then bash "$SKILL_DIR/scripts/ensure-ready.sh"; else export PATH="$HOME/.hamster/bin:$PATH"; if command -v hamster >/dev/null 2>&1 && { status_err="$(hamster --no-tui status 2>&1)"; printf '%s' "$status_err" | grep -q "Logged in" || { printf '%s\n' "$status_err" >&2; false; }; } && sync_err="$(hamster sync 2>&1)"; then echo READY; else [ -n "${sync_err:-}" ] && printf '%s\n' "$sync_err" >&2; echo SETUP_NEEDED; exit 1; fi; fi
```

Windows:

```powershell
$SkillDir = "<absolute path of the directory containing this SKILL.md>"; if (Test-Path "$SkillDir\scripts\ensure-ready.ps1") { pwsh "$SkillDir\scripts\ensure-ready.ps1" } else { $env:PATH = "$env:USERPROFILE\.hamster\bin;" + $env:PATH; if (Get-Command hamster -ErrorAction SilentlyContinue) { $status = & hamster --no-tui status 2>&1 | Out-String; if ($LASTEXITCODE -eq 0 -and $status -cmatch "Logged in") { $syncOut = & hamster sync 2>&1; if ($LASTEXITCODE -eq 0) { "READY" } else { [Console]::Error.WriteLine(($syncOut | Out-String).TrimEnd()); "SETUP_NEEDED"; exit 1 } } else { [Console]::Error.WriteLine($status.TrimEnd()); "SETUP_NEEDED"; exit 1 } } else { "SETUP_NEEDED"; exit 1 } }
```

- Prints `READY` — the CLI is installed, you are signed in, and `hamster sync` succeeded. Stop.
- Prints `SETUP_NEEDED` — if this is Codex on macOS and `hamster` is already on `PATH`, re-run only this readiness command with elevated permission. The default workspace sandbox cannot read Keychain credentials, and an extra directory grant does not change that. If the elevated check prints `READY`, stop. Only if it still prints `SETUP_NEEDED`, continue below.

## Install the CLI

If `hamster` is not on PATH (also look in `~/.hamster/bin`), the user installs the Hamster CLI themselves. Do not download, fetch, or run an installer, and do not run the install commands on the user's behalf.

Tell the user that setup needs the Hamster CLI, and ask them to install it in their own terminal by following https://github.com/gethamster/plugin#advanced-cli-binary. Then wait until they say it is installed.

When they do, check that `hamster` is now on PATH (also look in `~/.hamster/bin`). If it is still missing, tell the user and stop. Otherwise put `~/.hamster/bin` on PATH for this session.

## Sign in

```bash
hamster auth login
```

This opens a browser. Wait until it finishes. Do not paste tokens into chat.

## Init and sync

```bash
hamster init
```

`init` may ask the user to pick an account and runs the first sync.

Re-run the readiness check — it runs the sync that pulls the plan. If it still prints `SETUP_NEEDED`, report what failed and stop.

## Finish

When the check prints `READY`, confirm this repo now has `.hamster/`. If the client has the Hamster MCP server and the user has not signed in to it yet, point the

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

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: ship
description: Ship a Hamster brief. Merge the base branch, implement in parallel waves, test, review, and create bisectable commits. Ask before opening a PR. Use when the user wants to execute or ship an existing brief.
---

# Ship Brief

Executes a Hamster Studio brief. **Execution-only**: the plan — parent tasks, subtasks, context — was generated upstream in Hamster Studio and synced into `.hamster/`. This skill schedules those existing tasks into parallel waves and executes them. It never generates, splits, or replans tasks on its own initiative — but it doesn't execute blindly either. Executors adapt to mechanical drift (documented as deviations) and escalate genuine plan defects as **PLAN_ISSUE** instead of implementing something known to be wrong; the orchestrator (and for scope changes, the user) decides how to proceed.

Project skills ARE loaded during execution: task-executors read `.claude/skills/hamster-project-context/SKILL.md` when it exists (generated by `hamster sync`; clients that discover `.claude/skills/` expose it as the `hamster-project-context` skill), relevant project skills, and `.hamster/` blueprints/methods. Execution-only restricts *planning*, not *context*.

**Argument**: "$ARGUMENTS"

---

## Readiness

Before assuming a Hamster CLI, run this skill's bundled gate. Set `SKILL_DIR` to the absolute path of the directory holding the SKILL.md you just read — the shell's working directory is the user's project, not this skill — and keep the whole command on one line with its statements `;`-separated, because some clients flatten a fenced block before running it. The `else` branch is the same gate inline, for clients that expose no readable path to the installed package.

Unix:

```bash
SKILL_DIR="<absolute path of the directory containing this SKILL.md>"; if [ -f "$SKILL_DIR/scripts/ensure-ready.sh" ]; then bash "$SKILL_DIR/scripts/ensure-ready.sh"; else export PATH="$HOME/.hamster/bin:$PATH"; if command -v hamster >/dev/null 2>&1 && { status_err="$(hamster --no-tui status 2>&1)"; printf '%s' "$status_err" | grep -q "Logged in" || { printf '%s\n' "$status_err" >&2; false; }; } && sync_err="$(hamster sync 2>&1)"; then echo READY; else [ -n "${sync_err:-}" ] && printf '%s\n' "$sync_err" >&2; echo SETUP_NEEDED; exit 1; fi; fi
```

Windows:

```powershell
$SkillDir = "<absolute path of the directory containing this SKILL.md>"; if (Test-Path "$SkillDir\scripts\ensure-ready.ps1") { pwsh "$SkillDir\scripts\ensure-ready.ps1" } else { $env:PATH = "$env:USERPROFILE\.hamster\bin;" + $env:PATH; if (Get-Command hamster -ErrorAction SilentlyContinue) { $status = & hamster --no-tui status 2>&1 | Out-String; if ($LASTEXITCODE -eq 0 -and $status -cmatch "Logged in") { $syncOut = & hamster sync 2>&1; if ($LASTEXITCODE -eq 0) { "READY" } else { [Console]::Error.WriteLine(($syncOut | Out-String).TrimEnd()); "SETUP_NEEDED"; exit 1 } } else { [Console]::Error.WriteLine($status.TrimEnd()); "SETUP_NEEDED"; exit 1 } } else { "SETUP_NEEDED"; exit 1 } }
```

If it prints `SETUP_NEEDED` in Codex on macOS and `hamster` is already on `PATH`, re-run only this readiness command with elevated permission. The default workspace sandbox cannot read Keychain credentials, and an extra directory grant does not change that. If the elevated check prints `READY`, continue. Only if it still prints `SETUP_NEEDED`, run this plugin's `setup` skill, then re-run the check. Do not continue until it prints `READY`.

## Setup

Read [brief-selection](references/brief-selection.md) and run **Account Resolution** first. On `ACCOUNT_UNRESOLVED`, follow its team-selection/re-sync guidance and stop. Then run prerequisites and live sync in ONE bash call, assigning `account` to the resolved filesystem slug (shell-quoted), not `HAMSTER_ACCOUNT_ID`:

```bash
export PATH="$HOME/.hamster/bin:$PATH"
errors=""
command -v hamster >/dev/null 2>&1 || errors="${errors}hamster CLI not found. Run this plugin's setup skill.\n"
[ -d ".hamster" ] || errors="${erro

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

Referenced files: 6 — file references are metadata, not package contents.