github-ticket

What this skill does

# GitHub Ticket Skill

## When to Use This Skill

Use this Skill when you want to:

- create GitHub issues without opening the browser
- capture backlog work quickly with smart defaults
- fetch or list issues across `monolith` and a small repo set
- view your assigned work
- route planning work into repo-local execution issues
- add created issues to `Diversio Work` with the right board fields
- keep GitHub issue creation skill-driven instead of form-driven

This Skill is the GitHub-native replacement for the old `clickup-ticket`
workflow. Issue forms in `monolith` are a human fallback and a schema
reference, not the primary creation path.

## Prerequisites

Before doing anything else:

1. Run `gh auth status`.
2. Confirm `gh` is authenticated for the right GitHub account.
3. Confirm the token has the scopes needed for the requested action:
   - `repo` for issue read/write
   - `read:org` for org visibility
   - `project` when project add or field hydration is expected
4. Fail fast if `gh` is missing or unauthenticated.

Preferred auth model:

- normal `gh` login
- no plugin-specific token in the common case
- if project hydration is part of the workflow and `project` scope is missing,
  prefer `gh auth refresh -s project`

## Default Operating Model

Treat these defaults as the steady-state baseline unless the user overrides
them:

- planning repo: `DiversioTeam/monolith`
- execution repos:
  - `DiversioTeam/Django4Lyfe`
  - `DiversioTeam/Diversio-Frontend`
  - `DiversioTeam/Optimo-Frontend`
  - `DiversioTeam/diversio-ds`
  - `DiversioTeam/infrastructure`
  - `DiversioTeam/naboo`
  - `DiversioTeam/diversio-serverless`
  - `DiversioTeam/launchpad`
  - `DiversioTeam/skiddie`
  - `DiversioTeam/terraform-modules`
  - `DiversioTeam/agent-skills-marketplace`
- canonical IDs: native GitHub issue numbers
- legacy ClickUp `GH-xxxx` IDs: metadata only when applicable

Routing rules:

- If you are in the monolith root and no repo is specified, prefer
  `DiversioTeam/monolith`.
- If you are inside a repo checkout and no repo is specified, prefer that repo
  as the execution repo after normalizing the git remote into `owner/repo`.
- If the work clearly spans repos or still needs planning, create the issue in
  `DiversioTeam/monolith`.
- If the user asks for implementation work in a specific repo, create the
  issue in that repo when issues are enabled there.
- If repo detection yields a GitHub repo outside the default execution list,
  it is still valid to use that repo; do not reject it only because it is not
  prelisted in config.

## Local Config

Default config path:

```bash
CONFIG_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/github-ticket"
CONFIG_FILE="${CONFIG_DIR}/config.json"
```

Use a small JSON file with fields like:

- `planning_repo`
- `execution_repos`
- `backlog_labels`
- `quick_issue_labels`
- `project_owner`
- `project_number`
- `project_field_defaults`
- optional `path_repo_map`

See `references/config-and-body-shape.md` for a sample config and issue body.

For the current Diversio baseline, prefer organization project `#2`
(`Diversio Work`) unless the user overrides project placement.
Treat `project_field_defaults` as a display-name keyed map for stable defaults
like `Status` and `Priority`, not as a place to hard-code field or option IDs.
Prefer runtime repo detection from the current git checkout before falling back
to `path_repo_map`. In worktree-heavy setups, avoid hard-coded absolute path
maps unless there is a real non-git edge case.

## Repo Alias Map

Allow these shorthand values when the user names a repo informally:

- `monolith` -> `DiversioTeam/monolith`
- `backend` -> `DiversioTeam/Django4Lyfe`
- `frontend` -> `DiversioTeam/Diversio-Frontend`
- `optimo-frontend` -> `DiversioTeam/Optimo-Frontend`
- `design-system` -> `DiversioTeam/diversio-ds`
- `infrastructure` -> `DiversioTeam/infrastructure`
- `naboo` -> `DiversioTeam/naboo`
- `diversio-serverless` -> `DiversioTeam/diversio-serverless`
- `launchpad` -> `DiversioTeam/launchpad`
- `skiddie` -> `DiversioTeam/skiddie`
- `terraform-modules` -> `DiversioTeam/terraform-modules`
- `agent-skills-marketplace` -> `DiversioTeam/agent-skills-marketplace`
- `skills-marketplace` -> `DiversioTeam/agent-skills-marketplace`

If a repo alias is ambiguous, ask one short clarifying question.

## Command Modes

### `configure`

Goal:

- validate `gh` auth
- create or update local defaults
- keep prompts minimal

Workflow:

1. Run `gh auth status`.
2. Detect the current checkout path and repo if possible:
   - prefer `git rev-parse --show-toplevel`
   - then `git remote get-url origin`
   - normalize SSH or HTTPS GitHub remotes into `owner/repo`
3. Create `${XDG_CONFIG_HOME:-$HOME/.config}/github-ticket/config.json` if missing.
4. Gather only the missing defaults:
   - planning repo
   - preferred execution repos
   - backlog labels
   - quick-issue labels
   - project owner/number
   - optional project field defaults such as `Status` and `Priority`
   - only add `path_repo_map` when repo detection via git is insufficient

Use `jq` to write or update the config rather than inventing a custom format.
If project config is present but `gh auth status` shows no `project` scope,
surface that clearly instead of pretending project hydration will work.

### `get-issue`

Accepted input formats:

- `1234`
- `#1234`
- `owner/repo#1234`
- a GitHub issue URL

Behavior:

1. Resolve the issue reference to a repo plus number.
2. Use `gh issue view`.
3. Return title, state, assignees, labels, body summary, and key links.
4. If the issue is in another repo, show that clearly.

### `list-issues`

Prefer the smallest backend that matches the ask:

- one repo: `gh issue list`
- cross-repo or richer filtering: `gh search issues`

Support these filters:

- repo
- assignee
- label
- open / closed state
- `imported: clickup`
- updated recently

Keep the filter model smaller than the old ClickUp plugin.

### `my-issues`

This is the convenience view for assigned work.

Default behavior:

- search across the planning repo plus configured execution repos
- show open issues assigned to `@me`
- prefer recently updated or explicitly blocked work near the top

Use `gh search issues --assignee @me --state open` when a cross-repo query is
needed.

### `create-issue`

This is the full interactive creation path.

Gather:

- title
- work type
- target repo
- problem or request
- success criteria
- optional constraints or non-goals
- optional supporting links
- optional legacy ClickUp metadata

Then:

1. Choose the repo using the routing rules.
2. Build the canonical issue body.
3. Apply labels:
   - always include `triage` unless the user says otherwise
   - map work type to `type:*` labels when available
4. Create the issue with `gh issue create`.
5. If project config exists, or the current Diversio baseline applies, add the
   issue to the project with `gh project item-add`.
6. If the project add succeeds, hydrate the common project fields immediately:
   - `Status`
   - `Target Repo`
   - optional `Priority`
7. For `Status`, prefer:
   - `Ready` for scoped, actionable work
   - `Blocked` when the issue depends on incomplete upstream work
   - `Inbox` only for intentionally rough capture
8. For `Target Repo`, map the destination repository to the matching project
   option when that field exists. If there is no exact option for that repo,
   use `other` instead of leaving the field blank.
9. Never block issue creation on project assignment or field hydration, but do
   report the failure clearly so the user is not left with invisible board
   items.
10. If project hydration fails because of missing `project` scope, say that
    explicitly and point at `gh auth refresh -s project`.

### `quick-issue`

This should stay under three prompts.

Required input:

- title

Preferred flow:

1. Infer repo from current directory or config.
2. Use default quick-issue labels.
3. Create a minimal but useful body.
4. If the result is still intentionally