Ticket Solver

Step 2: Detect Platform

Check the current session context for the SessionStart hook output:

• Flow Plugin: Platform detected — **GitHub** (use gh CLI)
• Flow Plugin: Platform detected — **GitLab** (use glab CLI)

If no hook output is present, fall back to manual detection:

git remote get-url origin 2>/dev/null

• URL contains github.com → use gh CLI
• URL contains gitlab → use glab CLI
• No match → ask the user which platform to use

Store the platform for all subsequent commands. Never mix gh and glab in the same invocation. See references/platform-detect.md (in issue-engineer skill) for the full CLI command mapping.

Step 3: Single Ticket Workflow

Execute these steps in order for a single ticket. Each step must complete before the next begins.

3.1 Read the Issue

Fetch the full issue content:

GitHub:

gh issue view {number} --json title,body,labels,milestone,assignees

GitLab:

glab issue view {number}

Parse the response and extract:

• Title — for branch naming and PR title
• Acceptance criteria — the checkable items defining "done"
• Technical context — files, patterns, constraints mentioned in the issue
• Out of scope — explicit boundaries

If the issue body is empty or has no acceptance criteria, warn the user. Suggest using the issue-engineer skill to improve the ticket before proceeding. Do not implement tickets with no clear definition of done.

3.2 Create Worktree

Invoke superpowers:using-git-worktrees to create an isolated worktree.

Branch naming convention:

feature/issue-{number}-{slug}

Derive the slug from the issue title: lowercase, replace spaces and special characters with hyphens, remove consecutive hyphens, truncate to 40 characters, strip trailing hyphens.

Examples:

• #42 "Add user authentication" → feature/issue-42-add-user-authentication
• #15 "Fix login redirect bug" → feature/issue-15-fix-login-redirect-bug

Pass the branch name to the worktree skill. It handles git worktree add and changes the working directory into the new worktree.

3.3 Brainstorm → Plan → Implement (Automatic Chain)

This is the core of the ticket-solver. Invoke superpowers:brainstorming with the issue context. This single invocation triggers an automatic three-step chain:

brainstorming → writing-plans → subagent-driven-development

Do NOT invoke writing-plans or subagent-driven-development manually. The chain is automatic. Brainstorming completes its design exploration and automatically transitions to writing-plans. Writing-plans produces the implementation plan and automatically offers execution via subagent-driven-development (for 3+ independent tasks) or executing-plans (for 1-2 sequential tasks).

The ticket-solver's only job is to kick off brainstorming with the right context.

Context to provide in the brainstorming invocation:

1. The full issue title and body (verbatim, not summarized)
2. Acceptance criteria as an explicit checklist
3. Technical context from the issue (files to modify, patterns to follow)
4. The constraint: "Scope is bounded by the issue's acceptance criteria and out-of-scope section. Do not add functionality beyond what the ticket requires."
5. Relevant codebase context (project structure, tech stack, existing patterns)

What happens during the chain:

1. Brainstorming explores the problem, asks clarifying questions if needed, considers approaches, and produces a design. Then it automatically invokes writing-plans.
2. Writing-plans converts the design into a step-by-step implementation plan with file map, task breakdown, and checkboxes. Then it offers execution.
3. Subagent-driven-development (or executing-plans) implements the plan task by task.

Wait for the entire chain to complete before proceeding to the quality gate.

3.4 Quality Gate

After implementation completes, invoke the quality-gate agent:

Invoke agent: quality-gate

The agent runs four stages (see references/quality-gates.md for full details):

1. Stage 1: Build & Tests — blocking. If tests fail, stop and fix before retrying.
2. Stage 2: Parallel Agent Review — four pr-review-toolkit agents run simultaneously:
   • silent-failure-hunter — silent failures, swallowed errors
   • code-simplifier — unnecessary complexity
   • code-reviewer — project standards and conventions
   • pr-test-analyzer — test coverage gaps
3. Stage 3: Triage — findings categorized as Must-Fix / Should-Fix / Nice-to-Have
4. Stage 4: Report — structured output with PROCEED or FIX REQUIRED

Handle the result:

• PROCEED → move to verification (Step 3.6)
• FIX REQUIRED → fix all must-fix issues (Step 3.5), then re-invoke the quality gate

For trivial changes (typo fixes, documentation-only), skip Stage 2 and run only build & tests. See references/quality-gates.md for skip criteria.

3.5 Fix Must-Fix Issues

If the quality gate reported must-fix issues:

1. Fix each must-fix finding (file path and line number are in the report)
2. Re-run the test suite to confirm no regressions
3. Re-invoke the quality gate to verify all issues are resolved
4. For should-fix issues: present to the user, fix if they agree, otherwise note in PR

Repeat the quality gate cycle until the recommendation is PROCEED.

3.6 Verify

Invoke superpowers:verification-before-completion:

• Run the full test suite
• Run the build (if applicable)
• Walk through each acceptance criterion and confirm it is satisfied with evidence
• Check that no unintended files were modified

Do not claim completion without evidence. The verification skill requires actual command output confirming success — no assumptions.

3.7 Create PR

Create a pull request that links back to the issue.

GitHub:

gh pr create \
  --title "{issue title}" \
  --body "$(cat <<'EOF'
Closes #{number}

## Summary
{description of what was implemented}

## Acceptance Criteria
- [x] Criterion 1
- [x] Criterion 2
- [x] Criterion 3

## Quality Gate
- Build & Tests: PASSED
- Must-Fix issues: 0
EOF
)"

GitLab:

glab mr create \
  --title "{issue title}" \
  --description "$(cat <<'EOF'
Closes #{number}

## Summary
{description of what was implemented}

## Acceptance Criteria
- [x] Criterion 1
- [x] Criterion 2
- [x] Criterion 3

## Quality Gate
- Build & Tests: PASSED
- Must-Fix issues: 0
EOF
)"

Critical: The body must contain Closes #{number} so merging auto-closes the issue. Use commit-commands:commit-push-pr as an alternative — ensure the issue reference is included regardless of method.

Report completion to the user with the PR link, branch name, and confirmation that all acceptance criteria passed.

Step 4: Epic/Milestone Workflow

Use this workflow when the scope is a milestone, epic, or multiple tickets.

4.1 Fetch All Tickets

GitHub — by milestone:

gh issue list --milestone "{name}" --state open --json number,title,labels,body,assignees

GitLab — by milestone:

glab issue list --milestone "{name}" --opened --output-format json

Multiple specific tickets:

Fetch each issue individually using the commands from Step 3.1.

4.2 Determine Order

Spawn the epic-orchestrator agent with all ticket details:

Invoke agent: epic-orchestrator
Context: All fetched tickets with titles, bodies, labels, and dependencies

The agent returns:

• Ordered implementation sequence with reasoning
• Dependency map (which tickets block which)
• Parallelizable groups
• Complexity estimates (S/M/L)

Present the proposed order to the user. Accept adjustments before starting.

4.3 Initialize Progress Tracking

Create a task to track progress across context compactions:

TaskCreate: "Epic: {name}"
- Ticket #{a}: {title} — pending
- Ticket #{b}: {title} — pending
- Ticket #{c}: {title} — pending

4.4 Execute Tickets

For each ticket in the determined order:

1. Execute the full single ticket workflow (Steps 3.1 through 3.7)
2. Update progress: TaskUpdate: Ticket #{number} — done (PR #{pr})
3. Compact context to free space for the next ticket
4. Continue with the next ticket

4.5 Handle Failures

Blocking failure (subsequent tickets depend on the failed one):

• Stop execution
• Report which tickets are blocked
• Ask user: skip blocked tickets, or abort entirely

Independent failure (no dependencies broken):

• Log the failure
• Update task: Ticket #{number} — FAILED ({reason})
• Skip to the next ticket

4.6 Final Summary

Present a summary table after all tickets are processed:

## Epic Complete: {name}

| Ticket | Title                   | PR   | Status |
| ------ | ----------------------- | ---- | ------ |
| #42    | Add user authentication | #101 | done   |
| #43    | Add password reset      | #102 | done   |
| #44    | Add OAuth2 support      | —    | FAILED |

Completed: 2 of 3 tickets
PRs created: #101, #102
Failed: #44 — {failure reason}

Step 5: Context Management

These rules apply to all execution modes:

Auto-Compact

In epic/milestone mode, compact after every completed ticket. Each ticket consumes significant context (issue content, brainstorming, plan, implementation, quality gate). Without compaction, context limits are reached after 2-3 tickets. The task list persists through compaction.

Subagent-Driven Implementation

The brainstorming → writing-plans → subagent-driven-development chain delegates heavy work to subagents operating in isolated contexts. Only results return to the main context, not full implementation traces. This is the primary mechanism for keeping the main context manageable.

Progress Tracking

Use TaskCreate and TaskUpdate to maintain state across compactions:

• Create the task before the first ticket
• Update after each ticket completes or fails
• If the conversation is interrupted, the task shows exactly where to resume

Source of Truth

GitHub/GitLab is the source of truth, not in-memory state. To check if a ticket was already implemented after a context loss:

gh pr list --search "closes #{number}" --json number,state

Skip tickets that already have open or merged PRs.

Error Handling

• CLI not installed: Inform user with install instructions (brew install gh or brew install glab). Do not fall back to raw API calls.
• Auth required: Instruct user to run gh auth login or glab auth login.
• Issue not found: Verify the issue number and repository. Suggest checking with gh issue view {number}.
• Worktree conflict: If the branch already exists, ask user whether to reuse or create a new branch with a suffix.
• Quality gate loop: If must-fix issues persist after 3 fix attempts, stop and present the remaining issues to the user for manual resolution.

References

• references/implementation-flow.md — detailed step-by-step flow with all commands, decision points, and the full epic workflow including failure handling
• references/quality-gates.md — quality gate stages, agent table, severity categories, report format, and skip criteria
• references/platform-detect.md (in issue-engineer skill) — platform detection logic and the complete gh vs glab CLI command mapping