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/shared libraries; low = UI/docs/tests
- **PR strategy**: single PR (< 8 tasks, cohesive) vs. multiple (large/spanning domains)

---

## Mode Picker

Ask the user with 3 options:

1. **CEO Review (Founder Mode)** — rethink from first principles; deep 10-section review
2. **Eng Review (Architecture Mode)** — lock in architecture; 4 sections with diagrams and test plan
3. **Quick Analysis** — done; skip to Offer Transition

---

## CEO Review Mode

**Prime Directives**: zero silent failures; data flows mapped through 4 shadow paths (happy/nil/empty/error); observability is first-class scope; everything deferred gets written down.

**Step 0 — Scope Challenge** (ask the user): **SCOPE EXPANSION** (what's the 10-star version?), **HOLD SCOPE** (bulletproof execution; surface every risk), or **SCOPE REDUCTION** (strip to minimum value; defer the rest).

Work through 10 sections, asking the user for any critical finding that needs a decision:

1. **Architecture** — component dependency graph; data flow through the 4 paths; state machines for stateful transitions; integration points
2. **Error & Rescue Map** — table: method → exception → handler → what user sees; flag unhandled+untested+user-visible gaps; cascading failure risks
3. **Security & Threat Model** — auth boundaries, privilege escalation, input validation coverage, secret handling, trust boundaries
4. **Data Flow Edge Cases** — race conditions, stale data, cascading failures, TOCTOU
5. **Code Quality** — DRY across tasks, naming consistency, complexity hotspots
6. **Test Review** — test diagram for new UX/data/codepaths; untested critical paths; missing negative-path tests
7. **Performance** — N+1 risks, memory pressure, caching, latency budget
8. **Observability** — logs/metrics/traces needed; alerts; runbooks
9. **Deployment & Rollout** — migrations, feature flags, rollback plan, smoke tests
10. **Long-Term Trajectory** — tech debt introduced, path dependency, reversibility

**Output**: summary table (section → Clear / Issues Found / Needs Decision), unresolved decisions with tradeoffs, deferred items with reasoning. If EXPANSION was chosen: a **Delight Opportunities** section.

---

## Eng Review Mode

**Step 0 — Scope Challenge** (ask the user): **BIG CHANGE** (interactive, one section at a time, max 8 issues per section) or **SMALL CHANGE** (compressed single pass, one top issue per section).

4 sections:

1. **Architecture Lock-in** — ASCII data flow diagram, state management approach, API contracts, integration points, and a "what already exists" inventory of reusable patterns/services/types
2. **Code Quality** — DRY across planned changes, naming consistency, complexity hotspots, type safety gaps
3. **Test Strategy** — mandatory vs. nice-to-have tests, integration boundaries (mock vs. real); write a **Test Plan Artifact** to `.hamster/plans/{brief-slug}-test-plan.md`
4. **Performance** — N+1 detection, data fetching patterns, caching needs, latency analysis

**Issue resolution**: ask the user one question at a time; lead with the recommendation ("Do B. Here's why:"), 2-3 lettered options mapped to simplicity/correctness/performance tradeoffs.

**Output**: ASCII diagrams per major flow, test plan artifact, completion summary table, and an explicit **NOT-in-scope** section.

---

## Offer Transition

Ask the user: "Ship this brief?" — "Yes, ship now" → run `/hamster:ship {slug}`; "No, just planning" → end.

---

## Error Recovery

| Error | Recovery |
|-------|----------|
| `.hamster/` missing | Stop — run this plugin's `setup` skill, then retry |
| Account unresolved | Stop; follow Account Resolution's team-selection/re-sync guidance |
| Brief not found | Show partial matches, suggest closest |
| Malformed argument | Show usage examples, ask user to re-enter |

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
     command -v pnpm >/dev/null && pnpm test -- --testPathPattern='smoke' 2>/dev/null
   elif [ -f "Cargo.toml" ]; then cargo test smoke 2>/dev/null
   elif [ -f "go.mod" ]; then go test -run 'Smoke' ./... 2>/dev/null
   fi
   ```

4. Report pass/fail.

### Regression Mode (`regression`)

1. Get recently changed files (since branch point or last 5 commits):
   ```bash
   git diff "origin/$default_branch...HEAD" --name-only 2>/dev/null || git diff HEAD~5 --name-only
   ```

2. Map changed files → dependent files via import graph:
   - For each changed file, search for files that import it
   ```bash
   for f in $(git diff "origin/$default_branch...HEAD" --name-only 2>/dev/null); do
     base=$(basename "$f" | sed 's/\.[^.]*$//')
     grep -rl "$base" --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' --include='*.go' --include='*.rs' . 2>/dev/null
   done | sort -u
   ```

3. Run tests for changed files AND their dependents.

4. Compare results against last known pass (if CI data available):
   ```bash
   gh run list --branch "$current_branch" --limit 5 --json conclusion,headSha 2>/dev/null
   ```

5. Flag any NEW failures as regressions (failures not present in previous runs).

---

## Step 5: Issue Taxonomy

Classify each failure or finding:

| Category | Severity |
|----------|----------|
| **Functional** | critical / high / medium / low |
| **Type Safety** | critical / high / medium / low |
| **Integration** | critical / high / medium / low |
| **Performance** | high / medium / low |
| **Coverage Gap** | high / medium / low |

---

## Step 6: Fix Loop (Optional)

Ask the user: "Found N issues. Fix them now?"
- **Option A: Fix all** — automated fix loop for all issues
- **Option B: Fix critical only** — fix only critical/high severity
- **Option C: Just report, don't fix** — output report and stop

If fixing:
- One commit per fix: `fix(qa): {test-file} — {description}`
- Re-run affected tests after each fix to verify
- **Self-regulation**: Stop after 20 fixes in one session. If a fix introduces a new failure → revert immediately
- After all fixes complete, re-run the full affected test suite for verification

---

## Step 7: QA Report

```
QA Report: {mode} mode
Date: {YYYY-MM-DD}
Branch: {branch-name}

Tests: {pass}/{total} ({pass_rate}%)
Coverage: {coverage}% (delta: {+/-}% vs {base_branch})

CRITICAL: {count}
HIGH: {count}
MEDIUM: {count}
LOW: {count}

{detailed findings with file:line references}

Ship readiness: {READY | NEEDS_WORK | BLOCKED}
```

**Ship readiness criteria:**
- **READY**: All tests pass, no critical issues, coverage acceptable
- **NEEDS_WORK**: Minor issues or coverage gaps, but no blockers
- **BLOCKED**: Test failures, critical issues, or significant coverage regressions

---

## Error Recovery

| Error | Recovery |
|-------|----------|
| `.hamster/` missing | Stop with message to initialize project |
| No test runner detected | Report which tooling was checked, suggest setup |
| Test runner fails to start | Check configuration, report specific error |
| Coverage tool not available | Skip coverage reporting, note in output |
| `gh` CLI not available | Skip CI comparison in regression mode |

---

## Notes

- This command makes NO git operations except reading (no commits, no pushes)
- Fix loop commits are the exception — clearly marked as `fix(qa):` commits
- Safe to run repeatedly as you iterate
- Diff mode is the most useful for day-to-day development
- Quick mode is designed for rapid feedback before pushing
- Run `/hamster:qa diff` before `/hamster:review-hamster` for a complete pre-landing check

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 Resolution and use the literal slug it prints"; exit 1; }
# Signal B: briefs with in_progress tasks
for tasks_dir in .hamster/${account}/briefs/*/tasks; do
  [ -d "$tasks_dir" ] || continue
  matches=$(grep -l '^status: "in_progress"' "$tasks_dir"/*.md 2>/dev/null)
  [ -n "$matches" ] && echo "in_progress: $(basename "$(dirname "$tasks_dir")")"
done
```

Resolution order:
1. **Argument provided** → run **Brief Selection → If argument provided** in [brief-selection](references/brief-selection.md) and use its resolved `$slug`. If selection asks, wait for the user's answer; do not fall through to the signals below. With no argument, use steps 2–4 instead of that reference's no-argument picker.
2. **Branch matches** `feature/{key}-{n}-{slug}` (`{key}` is the tasks' display ID key, lowercased, e.g. `ham`, `acme`) → extract the slug
3. **One brief** has in_progress tasks → use it; **multiple** → ask the user
4. **None** → tell the user nothing to resume; suggest `/hamster:ship`

---

## Find the Resume Point

Read [brief-selection](references/brief-selection.md) and run its **Scheduling** step (the inline frontmatter parse + wave grouping). Then overlay git state in one call:

```bash
# Committed parents, as display IDs (HAM-42, ACME-7)
git log --format=%s | grep -oE '^feat\([a-z][a-z0-9]*-[0-9]+\)' | sed -E 's/^feat\((.*)\)$/\1/' | tr a-z A-Z | sort -u
# Uncommitted in-flight work
git status --porcelain
```

Walk the waves in order:
- All parents in a wave committed → wave complete, skip
- Some committed → partial wave: resume only the uncommitted parents
- None committed → resume from the start of this wave
- A task `in_progress` with uncommitted changes → it was interrupted mid-execution; pass a note to its executor to check `git diff` and continue from the partial work rather than restarting

Report compactly and ask the user to confirm ("Resume from Wave {n}?" / "Start from a different task" / "Cancel"):

```
Resuming: {title}
  Done:  Wave 1 — HAM-100, HAM-300 (committed)
  Next:  Wave 2 — HAM-200 (todo), HAM-400 (in_progress, has uncommitted changes)
  Remaining: {n} parents across {m} waves
```

---

## Continue

Verify the branch first: if not on `feature/{key}-{n}-{slug}`, ask whether to switch or create it.

Dirty working tree not attributable to an in_progress task → show the changes, ask: commit as part of current task / stash / discard.

Then read [execution-loop](references/execution-loop.md) and run its **Execution Loop** and **Completion** sections exactly as written, starting at the resume wave (partial waves: launch executors only for uncommitted parents). At completion, an existing PR needs both a push and a body update: merge resumed task statuses and Plan Feedback with its prior entries and resolutions, preserving other existing content, and report its URL. If no PR exists, keep the loop's user consent before creating one.

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** — Celebrate specific accomplishments anchored in commits
10. **3 Things to Improve** — Actionable, specific, tied to data
11. **3 Habits for Next Week** — Forward-looking recommendations

---

## Error Recovery

| Error | Recovery |
|-------|----------|
| `.hamster/` missing | Stop with message to initialize project |
| No commits in window | Report "no activity" and suggest a wider window |
| `gh` CLI not available | Skip PR data, note in output |
| No prior retro snapshots | Skip historical comparison, note this is the first retro |
| Date command incompatibility (macOS vs Linux) | Try both `date -v` and `date -d` syntax |

---

## Notes

- This command is read-only — no code changes, no git operations (except saving the snapshot JSON)
- The snapshot is saved to `.hamster/retros/` for trend tracking across retros
- Safe to run repeatedly; each run overwrites the same-date snapshot
- Best run weekly (7-day window) for actionable insights
- 14-day and 30-day windows are useful for sprint retros and monthly reviews
- The narrative is written for sharing with the team — paste it into Slack, a doc, or a standup

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 it.
```

---

## Step 7: Interactive Resolution for CRITICAL Issues

For each CRITICAL finding, ask the user one at a time:

Present the issue with three options:
- **Option A: Fix now** — describe the recommended fix approach
- **Option B: Acknowledge risk, ship anyway** — the reviewer notes this as an accepted risk
- **Option C: Mark as false positive** — explain why and the reviewer removes it from the list

If the user chooses "Fix now":
1. Edit the file to apply the fix
2. Verify the fix doesn't introduce new issues
3. Move to the next critical finding

### Final Verdict

After resolving all critical findings:

- If ANY critical issues remain unfixed (user chose "ship anyway"):
  ```
  Verdict: BLOCK — {N} critical issue(s) acknowledged but unfixed
  ```

- If all critical issues are resolved or marked false positive, and only informational remain:
  ```
  Verdict: APPROVE — {N} informational suggestion(s) noted
  ```

- If no issues at all:
  ```
  Verdict: APPROVE — Clean review
  ```

---

## Error Recovery

| Error | Recovery |
|-------|----------|
| `.hamster/` missing | Stop with message to initialize project |
| Not a git repository | Stop with message |
| On base branch | Stop — nothing to review |
| No diff | Report "no changes" and exit |
| `gh` CLI not available | Fall back to hardcoded "main" as default branch |
| `git fetch` fails | Continue with local-only diff |

---

## Notes

- This command makes NO commits and NO git operations (read-only)
- Safe to run repeatedly as you iterate on fixes
- Focus on the diff, not pre-existing issues in unchanged code
- Findings are specific (file:line) and actionable (concrete fix suggestions)
- Run this before `/hamster:ship` to catch issues early, or independently on any feature branch

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 them to their client's sign-in; the client owns it, never handle their credentials:

- Claude Code: open `/mcp` and select `plugin:hamster:hamster`.
- Codex: run `codex mcp login hamster` in a terminal.
- Copilot CLI: `/mcp auth hamster`.
- Grok Build: open `/mcps`, select `hamster`, and press `i`.
- Cursor: follow Cursor's Hamster sign-in prompt.
- Antigravity: in the CLI, open `/mcp`, select `hamster_hamster`, then Authenticate; in the app, select Authenticate on `hamster_hamster` under Settings → Customizations → Installed MCP Servers.
- Pi: run `pi mcp login hamster` in a terminal.

If the client has no Hamster MCP server, `ask-hamster` still works through the CLI. To add the Hamster tools, tell the user to add `https://tryhamster.com/mcp` as a remote MCP connector and sign in through OAuth; in Codex that is `codex mcp add hamster --url https://tryhamster.com/mcp`, then `codex mcp login hamster`, and in Pi `pi mcp add hamster --url https://tryhamster.com/mcp`, then `pi mcp login hamster`.

Then tell the user they can ask Hamster about this repo with the `ask-hamster` skill and ship a brief with `ship`.

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="${errors}.hamster/ directory not found. Run 'hamster sync' first.\n"
command -v gh >/dev/null 2>&1 || errors="${errors}gh CLI not found. Install from https://cli.github.com\n"
dirty=$(git status --porcelain 2>/dev/null | head -5)
[ -n "$dirty" ] && errors="${errors}Uncommitted changes:\n${dirty}\n"
if [ -n "$errors" ]; then printf "PREREQ_FAIL:\n$errors"; exit 1; fi
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 "PREREQ_OK account=${account} sync_pid=${watch}"
else hamster sync --watch > /dev/null 2>&1 & echo "PREREQ_OK account=${account} sync_pid=$!"; fi
```

- `PREREQ_FAIL` → show errors and stop (for uncommitted changes only: ask whether to proceed or stash)
- `sync_pid=existing` → a watcher whose working directory is this repo is already running (an interrupted session, or the user's own). Reuse it; do NOT kill it at completion
- `sync_pid=unknown` → a watcher exists but its working directory could not be read, so it may belong to another repo. Advisory only: reuse it rather than starting a second one, and never kill it
- Numeric `sync_pid` → remember the literal number. Each Bash call is a fresh shell, so `$sync_pid` does not survive to later calls — at Completion, substitute it literally (e.g. `kill 12345`)

---

## Brief Selection and Scheduling

Follow **Brief Selection** and **Scheduling** in [brief-selection](references/brief-selection.md): argument parsing, the brief picker, the inline frontmatter parse, and wave grouping, ending with the single execute/modify/cancel confirmation.

---

## Branch + Merge Base

One call:

```bash
lowest_id=$(ls "$tasks_dir"/*.md 2>/dev/null | xargs -n1 basename | grep -oE '^[a-z][a-z0-9]*-[0-9]+' | sort -t- -k2,2n | head -1)
branch="feature/${lowest_id}-${slug}"
git checkout -b "$branch"
default_branch=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name 2>/dev/null || echo "main")
git fetch origin "$default_branch" && git merge "origin/$default_branch" --no-edit
echo "branch=$branch base=$default_branch"
```

Merge conflict → **STOP**, report conflicts, do NOT auto-resolve.

---

## Execution and Completion

Read [execution-loop](references/execution-loop.md) and follow it for every wave: parallel execution, the validate/test gate, wave review, bisectable per-parent commits, and the progress report — then its Completion section for the watcher shutdown, final validation, optional PR, and brief status update.

---

## Error Recovery

| Error | Recovery |
|-------|----------|
| Prereq failure | Stop with instructions (uncommitted changes: ask stash/proceed) |
| Account unresolved | Stop; follow Account Resolution's team-selection/re-sync guidance |
| Brief not found | Show partial matches, ask user |
| Auth expired | `hamster auth login`; continue without status updates if it fails |
| Merge conflict (base or between executors) | Stop, report, never auto-resolve |
| Test gate fails | Stop, report, ask fix or skip |
| NEEDS_FIXES after 2 rounds | Report to user, ask skip or manual fix |
| Worker fails | Report, ask retry or skip |
| Executor returns PLAN_ISSUE | Verify: resolved authority-correct work → review; unresolved local fix → corrected re-launch; scope beyond authority or unresolved decision → ask user |
| Task already done | Skip it |

## Notes

- One commit set per parent (subtasks are never committed individually)
- Interrupted? `/hamster:resume-hamster` reconstructs state from git + task statuses
- Single PR per brief by default; >15 tasks → ask about splitting

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