MicroFish/.claude/onboarding/step3_planning/01_ticket_sync.md

Step 3 — Ticket Sync (GitHub Issues + gh CLI)

Date: 2026-05-06

Tooling Decision (vs. the original Notion prompt)

The Notion prompt is Jira/MCP-oriented. For this project we use:

• Issue tracker: GitHub Issues at https://github.com/salestech-group/MiroFish
• Transport: the gh CLI (already installed and authenticated as dseemann).
• No Atlassian MCP usage in these commands — gh is faster, scoped by token, and matches the rest of the team's Git workflow.

Equivalences vs. the prompt:

• "board.md" → .ticket/repo.md (stores owner/name).
• "IN ARBEIT" transition → GitHub doesn't have a built-in in-progress state; we approximate it with self-assignment + an in-progress label (graceful fallback if the label doesn't exist).

What Was Created

.ticket/

• Directory created. Most contents are gitignored — only repo.md and .gitkeep are tracked, so the local cache of in-progress tickets stays out of the repo.
• .ticket/repo.md — declares salestech-group/MiroFish as the target repo.
• .gitignore — added .ticket/* with negations for repo.md and .gitkeep.

.claude/commands/ticket.md

Slash command: /ticket <issue-number>

• Reads the repo from .ticket/repo.md.
• gh issue view --json … to fetch the issue.
• Self-assigns (gh issue edit --add-assignee @me).
• Tries to add the in-progress label; silently skips if the label doesn't exist on the repo.
• Snapshots the issue (frontmatter + full body) to .ticket/<n>.md so later planning / implementation steps have the description without re-fetching.

.claude/commands/ticket-list.md

Slash command: /ticket-list (interactive)

• Reads the repo from .ticket/repo.md.
• Asks the user for filters before running anything:
  • include closed
  • status (todo / in-progress / all open)
  • assigned to me only
  • milestone
  • labels
• Builds a single gh issue list invocation from the answers.
• For "no assignee" filtering, post-processes the JSON locally because gh has no --no-assignee flag.
• Renders a compact markdown table; ends with a hint to use /ticket <n> to start work.

.claude/settings.json

• Allow-listed gh issue view/list/edit/comment, gh repo view, gh pr view/list, gh auth status so the slash commands run without permission prompts.

Verification

• gh issue list --repo salestech-group/MiroFish --state open returned the open issue list (issue #1 currently open).
• settings.json parses as valid JSON.
• gh auth status confirmed (token: ghp_…, scopes incl. repo).

Limitations / Notes

• "In progress" semantics on GitHub Issues is convention-driven. If the team adopts a GitHub Project (v2) with a Status field, update the /ticket command to call gh project item-edit … instead of the label/assignee approximation.
• Atlassian MCP setup from Step 0 is unused here. Leave it configured for any cross-project Jira lookups.

Next

• Step 4: Planning (MANDATORY) — /plan command, persistence, hooks.