Skip to content

ticket gh init

Jump to bottom
Ian Smith edited this page Jun 3, 2026 · 3 revisions

ticket-gh-init — Design Document

Status: Draft, 2026-05-24.

Summary

A one-time bootstrap skill that prepares a GitHub-backed project for use with the ticket-* workflow. It creates the state labels in the GitHub repo and writes a fresh .project-conf.toml. It is idempotent and re-runnable.

The skill prints a clear explainer before taking any action, then asks a single user question (3-state vs. 4-state workflow), then performs all changes.

Goals

  • Set up everything a GitHub-backed project needs in one command.
  • Make all side-effects (label creation, file write) visible upfront via the explainer.
  • Idempotent: re-running detects existing setup and confirms rather than duplicating.

Non-goals

  • Migrating an existing Linear or JIRA project to GitHub. Out of scope; that's a manual project-level decision.
  • Configuring GitHub itself beyond labels — milestones, project boards, branch-protection rules are user responsibility.
  • Authenticating to GitHub. Requires gh auth status to be clean before running.
  • Repos hosted on enterprise GitHub variants (GHE Server / Cloud). First cut targets github.com only; the gh CLI commands used here generally work against GHE, but it's not validated.

Flow

1. Pre-flight

  • Verify cwd is inside a git repo: git rev-parse --is-inside-work-tree.
  • Verify a GitHub remote exists: parse git remote get-url origin for a github.com host.
  • Verify gh auth status succeeds. If not, stop with "GitHub CLI not authenticated. Run \gh auth login` first."`
  • Determine owner/repo from gh repo view --json nameWithOwner. Display it and pause for user confirmation (Confirm this is the right repo? [y/N]). Misidentification is a hard error.

2. Explainer — printed before any action

/slopstop:gh-init prepares this GitHub repo for the ticket-* workflow.

It will:
  - Create state labels in <owner>/<repo> (if missing):
      • status:in-progress
      • status:in-review  (only in the 4-state workflow)
  - Write .project-conf.toml in this directory with:
      • system = "github"
      • key    = "<owner>/<repo>"
      • prefix = "<your-chosen-prefix>"  (short ticket-ID prefix, e.g. BILL)
      • the chosen status_labels mapping

It will NOT:
  - Modify any existing issue, PR, or branch.
  - Touch the repo's other settings (milestones, projects, branch protection).
  - Authenticate to GitHub for you (handled separately by `gh auth login`).

Plain text rendered to stdout. The user reads it before answering the question in step 3.

3. Single question — 3-state vs. 4-state

Choose a workflow:

  3-state: todo → in-progress → done
  4-state: todo → in-progress → in-review → done

In BOTH workflows, the PR process includes the pre-merge simplify pass
and a CodeRabbit review. Those are part of the work in `in-progress`,
not what `in-review` means.

The 4-state workflow adds an `in-review` stage AFTER the code is
complete relative to its requirements. The stage exists for
shake-down validation:

  • another person running or reviewing the working code, OR
  • the author dogfooding the code for a period to make sure it
    behaves the way they wanted before declaring it done.

In other words: `in-review` is "the code works; now we're verifying
it does the right thing in practice." Choose 4-state if your workflow
includes such a validation step; choose 3-state otherwise.

Which workflow? [3/4]

The user types 3 or 4. No other prompts. The explainer + this question are the only user-facing interaction before action.

4. Apply changes (idempotent)

Label creation:

For each label that the chosen workflow needs (status:in-progress always; status:in-review only in 4-state mode):

  1. Check existence: gh label list --json name.
  2. If missing: gh label create "<name>" --color <color> --description "<desc>".
  3. If present: print "label '<name>' already exists — skipping" and continue.

Defaults:

Label Color Description
status:in-progress #fbca04 Ticket is actively being worked on
status:in-review #0e8a16 Code is complete; shake-down validation in progress (other-person review and/or author dogfood)

Overridable via flags (see Arguments below) if the user wants to match an existing repo convention.

.project-conf.toml write:

  • If the file already exists, read it. If system is not "github" or key doesn't match the current repo: stop with conflict error. The skill refuses to overwrite a different project's config.
  • If system = "github" and key matches: merge in the chosen [status_labels] (preserving any other namespaces like [rag], [exp]).
  • If absent: write a fresh file in the format defined in project-conf-toml.md.

Writes go through a temp file + atomic rename so a crashed write never leaves a partial file.

5. Confirm

ticket-gh-init complete.

Created labels: status:in-progress, status:in-review
Wrote: .project-conf.toml (system=github, key=<owner>/<repo>)

You can now run /slopstop:start <ISSUE-NUMBER> to begin work.

If any labels were already present and any config was already correct, the confirm line for that item reads "already configured."

Arguments and flags

/slopstop:gh-init [--workflow {3,4}]
                [--in-progress-color HEX]
                [--in-progress-label NAME]
                [--in-review-color HEX]
                [--in-review-label NAME]
  • --workflow {3,4} — skip the user prompt in step 3.
  • --in-progress-color HEX, --in-review-color HEX — override default label colors.
  • --in-progress-label NAME, --in-review-label NAME — override default label names (e.g. for a repo that already uses 🚧 In Progress instead of status:in-progress).

All optional. Without any, the skill behaves as described above.

Idempotency contract

Re-running /slopstop:gh-init on a fully-configured project must:

  1. Detect existing labels and skip creation.
  2. Detect existing .project-conf.toml, validate it, and confirm "already configured."
  3. Exit successfully.

This makes the skill safe to run as a "verify" operation, not just a "set up once" operation. CI scripts or onboarding flows can invoke it without conditional logic.

Error matrix

Condition Behavior
gh auth status fails Stop with auth instructions.
Not in a git repo Stop: "Run inside a git repository with a GitHub remote."
No GitHub remote Stop: "No GitHub remote found. Add \origin` first."`
Existing .project-conf.toml for system != "github" Stop: "This project is configured for system='<other>'. Refusing to overwrite."
Existing .project-conf.toml with mismatched key Stop: "Existing config points to '<other>/<repo>'; current repo is '<owner>/<repo>'. Refusing to overwrite."
User cancels the repo-confirm prompt Stop: "No changes made."
User cancels the workflow question Stop: "No changes made."
Label creation API error Stop with the API error; do not partially apply remaining labels.
.project-conf.toml write fails Stop with the OS error; temp-file + atomic rename ensures no partial file.

Partial application is forbidden — any error mid-flight stops the skill and reports what was already done so the user can clean up by hand if needed.

Open questions (refinement, not blockers)

  • done label. Should the skill also create a done label? Probably no — GitHub's native open/closed already represents done. Mentioned for completeness.
  • .gitignore for .project-conf.toml. Should the skill offer to add the config file to .gitignore? Depends on whether the project wants the config committed (more shareable) or local-only (more flexible per-clone). Default: do nothing; let the user decide.

Prerequisites

No dependency on the multi-ticket or RAG designs. ticket-gh-init is a self-contained bootstrap step that runs before any other ticket-* skill on a new GH-backed project.

Adjacent

Clone this wiki locally