| 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.
