---
name: happier-dev/happier-github-ops
source: https://app.decimal.ai/s/happier-dev-happier-github-ops@1/SKILL.md
source_sha256: 8f36b61b33e0
---

# Happier GitHub Ops (bot `gh` wrapper)

This repo provides `yarn ghops` as a thin wrapper around the GitHub CLI (`gh`) that **forces** authentication via the bot Personal Access Token. `HAPPIER_GITHUB_BOT_TOKEN` has highest priority; on macOS, the wrapper otherwise reads the validated token from Keychain service `happier/ghops`, account `happier-bot`.

## Prerequisites

- `gh` is installed on the host and reachable on `PATH`.
- Either environment variable `HAPPIER_GITHUB_BOT_TOKEN` is set to the bot's fine-grained PAT, or the token was stored on macOS with `yarn ghops auth store`.

## Contract / Safety

- `yarn ghops ...` refuses to run if neither the environment override nor the macOS Keychain credential is available.
- Runs non-interactively (`GH_PROMPT_DISABLED=1`).
- Uses an isolated repo-local `GH_CONFIG_DIR` by default.
- Never falls back to personal `gh`, `GH_TOKEN`, or `GITHUB_TOKEN` credentials.
- Forces `GH_HOST=github.com` so an inherited host override cannot redirect the bot token.
- `auth store` validates that the token belongs to `happier-bot` before persisting it.

## Bot credential lifecycle

On macOS, configure the bot once without echoing the token:

```bash
yarn ghops auth store
```

The command prompts securely when `HAPPIER_GITHUB_BOT_TOKEN` is absent. If the environment variable is present, it validates and stores that value without printing it.

Verify the resolved identity and source:

```bash
yarn ghops auth status
```

Remove only the stored Keychain credential:

```bash
yarn ghops auth clear
```

On non-macOS platforms, continue providing `HAPPIER_GITHUB_BOT_TOKEN`; Keychain lifecycle commands fail closed until a native credential-store adapter exists.

## What to write (LLM guidelines)

When creating/updating public issues, keep it **useful but minimal**:

- Prefer **user impact, repro steps, expected vs actual**, and **acceptance criteria**.
- Link to PRs/commits by URL when available.
- Avoid internal-only detail: no private logs, no secrets, no tokens, and no stack dumps from private environments.
- If you need to share sensitive debugging context, summarize it and keep the raw detail local.

Suggested comment format for progress updates:

- What changed (1–3 bullets)
- Why (brief)
- Next step / what’s blocked (one line)
- Links (PR/commit/issues)

## Common commands

Verify identity (must be the bot user):

```bash
yarn ghops api user
```

## Project conventions (Happier roadmap)

Canonical public roadmap project:

- Owner: `happier-dev`
- Project number: `1`
- URL: `https://github.com/orgs/happier-dev/projects/1`

## Labels (conventions)

These labels are intended to keep the public roadmap curated and consistent:

- `roadmap` (triage-owned): include this item on the public roadmap project
- `priority:p0`, `priority:p1`, `priority:p2`, `priority:p3` (triage-owned)
- `stage:not-shipped`, `stage:experimental`, `stage:beta`, `stage:ga` (optional; rollout state)
- `type: bug`, `type: feature`, `type: task` (recommended)
- `source: bug-report` (applied automatically by the bug-report service)

When asked to “create an issue and put it on the roadmap with P0”, do:

1) Create the issue
2) Apply `roadmap` and `priority:p0` (and a `type:*` label)
3) Ensure it lands on the roadmap project (automation should add it; if not, add explicitly)

When you create or meaningfully update an issue/PR, ensure it’s visible on the roadmap:

- Prefer GitHub Project automation (auto-add when `roadmap` label is present).
- If you’re not sure it will be auto-added, explicitly add it:

```bash
yarn ghops project item-add 1 --owner happier-dev --url https://github.com/happier-dev/happier/issues/123
```

Create an issue (repo explicit is recommended):

```bash
yarn ghops issue create -R happier-dev/happier --title "..." --body "..." --label "type: bug"
```

For CLI-created issues, format the body like the templates:

- Bug: summary + what happened + expected behavior + (optional) repro + (optional) frequency/severity + (optional) environment
- Feature: problem + proposal + acceptance criteria

For scripting / machine-readable output, prefer `gh api`:

```bash
yarn ghops api repos/happier-dev/happier/issues \
  -f title="..." \
  -f body="..." \
  --jq '{number: .number, url: .html_url}'
```

Comment on an issue:

```bash
yarn ghops api repos/happier-dev/happier/issues/123/comments -f body="Update: ..."
```

Apply labels (example):

```bash
yarn ghops api repos/happier-dev/happier/issues/123/labels -f labels[]="roadmap" -f labels[]="priority:p0"
```

## Titles (guidelines)

Prefer short, descriptive titles without noisy prefixes:

- Good: `Sessions flicker online/inactive`
- Good: `CLI: doctor fails when daemon is stopped`
- Avoid: `P0: ...` (priority belongs in the project/labels, not the title)
- Avoid: long bracket stacks like `[Bug][iOS][P0] ...`

Add an issue/PR to the org project (Project v2):

```bash
yarn ghops project item-add 1 --owner happier-dev --url https://github.com/happier-dev/happier/issues/123
```

List project fields/items (JSON):

```bash
yarn ghops project field-list 1 --owner happier-dev --format json
yarn ghops project item-list 1 --owner happier-dev --format json
```