maintainer

name	maintainer
description	Daily maintainer workflow -- triage, GitHub issue, worktree, fix, PR, review feedback loop. BUG/FEATURE auto-classify.

Maintainer - Daily Issue Resolution Pipeline

Run the end-to-end issue triage and resolution pipeline for daily maintenance work.

Language rule: Write all conversation, reports, issues, PRs, and commits in English. Translate non-English user input before processing it. Never switch languages mid-conversation.

Arguments

Flag	Description
(input)	User report, transcript, image, GitHub issue URL, or plain description
--tdd	Tests-first: write regression tests before code changes, verify after
--parallel	Multi-agent parallel execution (plan with file ownership, then cook with parallel agents)
--deep	Deep analysis: per-area scouting and thorough research before implementation
--force-ui	Hard-gate UI evidence: block PR until screenshots/report exist and are user-approved
--skip-issue	Skip GitHub issue creation because the issue already exists
--skip-worktree	Skip worktree creation only when already in a dedicated branch/worktree
--pr-main	Target the PR to main instead of dev
--decompose	Decompose into parallel sub-issues with separate worktrees; auto-suggest if more than three files span more than two domains
--scan-reviews	Standalone mode: scan open PRs for unresolved review feedback
--from-signals	Observe-only intake: read drift, submodule, CI, issue, and PR signals; rank them; ask the user to choose
--max-fix-attempts N	Set review-loop iterations (default: 5)
--no-review-loop	Skip the review feedback loop after PR creation
"PR done"	Run post-merge cleanup for worktrees and branches

Compose --tdd, --parallel, --deep, and --force-ui as needed.

Core Invariants

• Keep --from-signals read-only. Never auto-pick a target or mutate state during signal intake.
• Preserve issue origin: distinguish a workflow-created issue from a user-provided issue so Step 5.5 can sync correctly. A user-provided issue may be claimed or labeled in Step 3, but never comment on or close a user-opened issue without explicit user authorization; confirm before any Step 5.5 comment.
• Use worktrees for code changes. Allow --skip-worktree only when already inside a dedicated worktree/branch.
• Let the maintainer own commits, pushes, PR creation, and cleanup. When a plan runs, stop /cook before its finalize step.
• Save reports, brainstorm outputs, and plans in the target repository's plans/ directory, not its worktree. Worktrees hold code changes only.
• Treat --force-ui as a blocking evidence gate. Do not create a PR until the user has reviewed the evidence.

Auto-Classification

Analyze the input and classify it as BUG or FEATURE:

Type	Signals	Route
BUG	"broken", "error", "crash", "doesn't work", "regression", label bug	Step 1a -> Step 2 -> Step 5 (/fix)
FEATURE	"add", "new", "would be nice", "enhance", "improve", label feat or enhancement	Step 2.5 -> Step 3 -> Step 4 -> Step 5 (/cook)
Ambiguous	No decisive signal	Default to BUG: Step 1a -> Step 2

Flag Routing Matrix

Use this matrix in Step 5:

Classification	No flags	--tdd	--parallel	--deep	--parallel --deep	--parallel --tdd
BUG	/fix --parallel	/fix --parallel + TDD	/ck:plan --parallel -> /cook --parallel	/ck:plan --deep -> /cook --auto	/ck:plan --deep -> /cook --parallel	/ck:plan --parallel --tdd -> /cook --parallel --tdd
FEATURE	/cook --auto	/cook --auto --tdd	/ck:plan --parallel -> /cook --parallel	/ck:plan --deep -> /cook	/ck:plan --deep -> /cook --parallel	/ck:plan --parallel --tdd -> /cook --parallel --tdd

Apply these routing rules:

• Insert /ck:plan before implementation whenever --parallel or --deep is present, including for BUGs.
• Treat --deep as planning thoroughness and --parallel as execution strategy. They are orthogonal.
• Append --tdd to the selected implementation route.
• Treat --decompose as orthogonal. Run the selected route independently for each sub-issue.
• Stop /cook before its finalize step because the maintainer owns Git operations.

Workflow

Input
  |
  +-- --from-signals -> [0/0a] read signals -> USER chooses target
  |
  v
[1] classify BUG or FEATURE
  |
  +-- BUG -> [1a] /brainstorm -> [2] /debug
  +-- FEATURE ------------------------------+
                                            |
                                            v
                              [2.5] complexity check
                                  |
                 +----------------+----------------+
                 |                                 |
              simple                         --decompose
                 |                                 |
                 v                                 v
        [3] create/claim issue          [3/3.5] parent + sub-issues
                 |                                 |
                 v                                 v
          [4] /worktree                   worktree per sub-issue
                 |                                 |
                 +----------------+----------------+
                                  |
                                  v
                      [4.5] optional /ck:plan
                                  |
                                  v
                     [5] flag-routed implementation
                                  |
                                  v
                      [5.5] progress comment
                                  |
                                  v
                     [6] /preview --explain
                                  |
                                  v
                 [7] optional parallel code review
                                  |
                                  v
                    [7.5] conditional UI evidence
                                  |
                                  v
                          [8] PR + Closes #N
                                  |
                                  v
                       [8.5] review/fix loop
                                  |
                                  v
                        [9] "PR done" cleanup

Reference Loading Rules

Read only the reference files required for the active mode or current step. Every reference is one level below this file.

Mode or Step	Required Action	Direct Reference
--from-signals (0, 0a)	Read before running the suggester, presenting candidates, or accepting a target.	references/signal-intake.md
Triage/classification (1, 1a, 2, 2.5)	Read before classifying, brainstorming/debugging a BUG, or deciding decomposition. FEATURE skips Step 2 but keeps Step 2.5.	references/triage-and-classify.md
GitHub issue/decomposition (3, 3.5)	Read before claiming/creating an issue or using --decompose. Skip issue operations with --skip-issue.	references/github-and-decompose.md
Worktree through PR (4, 4.5, 5, 5.5, 6, 7, 8)	Read before creating a worktree, planning, implementing, reporting progress, previewing, reviewing, or opening the PR.	references/implement-and-pr.md
Normal UI evidence (7.5)	Read both references when UI files changed and --force-ui is absent. Skip only for non-UI changes.	references/ui-diff-evidence.md and references/force-ui-evidence.md
Forced evidence (7.5 with --force-ui)	Read whenever --force-ui is present, including backend-only changes. This is a hard gate.	references/force-ui-evidence.md
Review loop (8.5)	Read after PR creation unless --no-review-loop; also read when scan mode finds actionable feedback.	references/review-feedback-loop.md
Cleanup (9)

For UI work with --force-ui, read both references/ui-diff-evidence.md for capture rules and references/force-ui-evidence.md for gate, mode, report, and PR-body requirements.

Completion

Do not stop at code edits. Complete the selected route through focused validation, reviewable explanation, PR handling, feedback resolution, and task-scoped cleanup when authorized.