github-ticket

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:

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 rough, prefer Status: Inbox when adding it to a project. Only upgrade to Ready when the issue is already actionable from the captured context.
5. Return the created issue URL.

add-to-backlog

This is the fastest capture path.

Default behavior:

• repo: DiversioTeam/monolith
• labels: triage plus configured backlog labels
• minimal body with problem/request plus optional links
• when added to Diversio Work, prefer Status: Inbox

Do not over-prompt. If the user only gives a title, create the issue.

create-linked-issue

Use this when turning planning work into explicit follow-up or execution work.

Safe default:

1. Read the source issue.
2. Create the new issue in the target repo.
3. Mention the source issue in the new body.
4. Add reciprocal comments with gh issue comment on both issues.
5. If the new issue is added to a project, prefer Ready unless its own dependency chain means it should start in Blocked.

Do not rely on child-issue-only GitHub features for MVP behavior.

route

Use this when a planning issue in monolith should become repo-local execution work.

Behavior:

1. Read the planning issue.
2. Decide the target repo or confirm it with one short question.
3. Call the same creation logic as create-linked-issue.
4. Leave the planning issue open unless the user explicitly wants it closed.

Project Hygiene

When the issue lands in Diversio Work, treat project visibility as part of the ticket workflow instead of optional cleanup.

• If a work item should show up in active board views, do not leave Status blank.
• Inbox is appropriate for rough backlog capture; it is not appropriate for already-scoped execution work.
• quick-issue and add-to-backlog may legitimately choose Inbox even when a global config default says Ready, because the capture mode is part of the semantics.
• Ready is the default for issue-sized, actionable work that can be picked up now.
• Blocked is the default when dependency text like requires, depends on, or blocked by means the issue should exist on the board but not enter the active queue yet.
• When the project has a Target Repo field, set it to the repo that will own execution so grouped board views stay useful. If the project does not have a dedicated option for that repo, use other.
• After creation, verify the issue is attached to the expected project and is not hidden by a blank Status.

Project Commands

Use the GitHub CLI's project commands directly instead of inventing ad hoc GraphQL:

1. Resolve the project metadata:
   • gh project view <number> --owner <owner> --format json
2. Resolve field ids and single-select option ids:
   • gh project field-list <number> --owner <owner> --format json
3. Add the issue to the project:
   • gh project item-add <number> --owner <owner> --url <issue-url>
4. Resolve the project item id by matching the created issue:
   • gh project item-list <number> --owner <owner> --format json
5. Update one field per call with gh project item-edit:
   • --single-select-option-id for fields like Status, Target Repo, and Priority
   • --project-id is required for non-draft issue field edits

Do not assume field ids or option ids are stable across projects. Read them from the active project each time unless a higher-level cache is explicitly in scope.

Canonical Issue Body

Generated issues should use these sections in this order:

1. ## Problem or request
2. ## Success criteria
3. ## Constraints / non-goals
4. ## Supporting links
5. ## Legacy metadata

Only include Legacy metadata when there is actual ClickUp carryover.

Keep the body aligned with the monolith issue forms so manual and skill-created issues look comparable.

Implementation Backend

Prefer this command set:

• gh issue create
• gh issue view
• gh issue list
• gh search issues
• gh issue comment
• gh project view
• gh project field-list
• gh project item-add
• gh project item-list
• gh project item-edit
• gh api

Use gh api only when a simpler gh issue ... subcommand does not cover the action cleanly.

Output Expectations

When this Skill completes a write action, always return:

• repo
• issue number
• title
• URL
• labels applied
• whether project add succeeded or was skipped
• which project fields were applied, skipped, or failed

When it completes a read or list action, keep the response scan-friendly and show enough context that the user does not need to open GitHub immediately.

Adjacent Skill Fallout

This Skill unblocks the GitHub issue workflow, but it does not by itself clean up every older ClickUp assumption elsewhere.

Known follow-up areas:

• backend-pr-workflow
• backend-atomic-commit
• repo-local harness docs or commands that still require clickup_* branches

If those older instructions conflict with repo-local GitHub workflow docs, the repo-local GitHub workflow docs should win.