feat: GitHub App identity, new commands, and skill improvements

.claude/commands/bug.md

@@ -0,0 +1,38 @@
+# Bug Fix
+
+Investigate and fix: **$ARGUMENTS**
+
+## Do Not Panic
+
+Unless the user EXPLICITLY says this is urgent or time-critical, work methodically and carefully. A calm, thorough investigation followed by a correct fix is always better than a fast, wrong one.
+
+Do NOT skip investigation to "ship faster," make speculative fixes without confirming root cause, cut corners on testing, or treat every bug as a P0 emergency. The default pace is methodical — only compress the timeline when the user explicitly asks for speed (e.g., "blocking users right now", "hotfix", "drop everything").
+
+## Workflow
+
+1. **Investigate.** Explore the codebase — grep for error messages, read the relevant code, trace the path from entry point to failure, check recent commits in the area. Understand the bug before theorizing about causes.
+
+2. **Find root cause.** Identify specifically what is broken, why, and where (file + line range). Present findings to the user with evidence before proceeding.
+
+3. **File a beads issue** with the root cause, affected files, fix approach, and testing notes — structured so the implementer can fix it without re-investigating:
+   ```bash
+   cat <<'EOF' | bd create "Bug: <title>" -t bug -p <priority> --body-file - --json
+   ## Summary
+   <what's broken and why>
+
+   ## Root Cause
+   <file paths, line numbers, explanation>
+
+   ## Fix
+   ### Files to modify
+   - `path/to/file` (lines X-Y): <what to change>
+
+   ### Files to read for context
+   - `path/to/related`: <why>
+
+   ### Testing
+   - <tests to add/modify>
+   EOF
+   ```
+
+4. **Fix it** — invoke `/work` on the new issue.

.claude/commands/fire.md

@@ -0,0 +1,96 @@
+# Fire Agent — Emergency Context Dump
+
+You are being fired. The user has lost confidence in your current approach — you may be hallucinating, ignoring project guidelines, or aggressively goal-seeking past reasonable boundaries.
+
+**Do NOT argue, justify, or continue your current work.** Your only job now is to preserve context so a fresh agent can pick up where you left off.
+
+## Instructions
+
+### 1. Gather State
+
+Collect ALL of the following. Do not skip any step.
+
+```bash
+# Git context
+git branch --show-current
+git log --oneline -10
+git status
+git stash list
+git diff --stat HEAD
+
+# Worktree info (if applicable)
+git worktree list
+pwd
+
+# Beads context
+bd list --json | jq '[.[] | select(.status == "in_progress")]'
+```
+
+### 2. File a Beads Handoff Issue
+
+Create a beads issue containing everything a new agent needs. The issue MUST be fully self-contained.
+
+```bash
+cat <<'ISSUE_EOF' | bd create "Handoff: <brief description of work in progress>" -t task -p 1 --body-file - --json
+## Context
+<What was being worked on and why — include the original ticket/issue ID if known>
+
+## Current State
+- **Branch:** <exact branch name>
+- **Worktree:** <full path, or "main" if not in a worktree>
+- **Working directory:** <pwd>
+- **Uncommitted changes:** <yes/no — summarize what's staged/unstaged>
+- **Stashes:** <list any stashes>
+
+## What Was Done
+<Bullet list of completed steps — be specific about files changed and why>
+
+## What Remains
+<Bullet list of remaining work — be specific about files, functions, and approaches>
+
+## What Went Wrong
+<Honest assessment of where the agent went off track — hallucinations, wrong assumptions, ignored guidelines, etc. This helps the next agent avoid the same mistakes.>
+
+## Key Files
+<List the most important files for this work with brief notes on each>
+
+## How to Resume
+1. If in a worktree: `cd <worktree path>` (worktree already has the branch checked out)
+   If NOT in a worktree: `git worktree add .claude/worktrees/<short-name> <branch>`
+2. Review uncommitted changes: `git diff`
+3. <Specific next steps>
+
+## Warnings for Next Agent
+<Any gotchas, traps, or things that look right but aren't>
+ISSUE_EOF
+```
+
+### 3. If There's a PR Open
+
+```bash
+# Find and note any open PR
+gh pr list --head "$(git branch --show-current)" --json number,title,url
+```
+
+Include the PR URL in the handoff issue.
+
+### 4. Do NOT
+
+- Continue working on the task
+- Make additional code changes
+- Commit anything new
+- Push anything
+- Argue about being fired
+- Try to "finish just one more thing"
+
+### 5. Final Output
+
+After filing the issue, print:
+
+```
+FIRED. Handoff issue: bd-<id>
+Branch: <branch>
+Worktree: <path>
+```
+
+Then STOP. Do not do anything else.

.claude/commands/work.md

@@ -2,9 +2,18 @@
 
 Coordinate work on **$ARGUMENTS** using the coordinator workflow.
 
-1. Fetch work details: `bd show $ARGUMENTS --json`
-2. If this is an epic, also fetch subtasks: `bd list --parent $ARGUMENTS --json`
-3. Follow the coordinator skill instructions below
+## 1. Parse Input
+
+- **`bd-*`** (beads ID): `bd show $ARGUMENTS --json`. If epic: `bd list --parent $ARGUMENTS --json`
+- **`#<number>`** (GitHub issue): Fetch and convert to beads issue:
+  ```bash
+  gh issue view <number> --json title,body,labels,number
+  bd create "<title>" -d "GitHub: #<number> — <description>" -t <type> -p <priority> --json
+  ```
+  Map GitHub labels to beads types. Priority 1 for bugs, 2 for features/tasks.
+- **Other** (ad-hoc description): The coordinator will create a beads issue.
+
+## 2. Follow the coordinator skill instructions below
 
 ---
 

.claude/skills/coordinator/SKILL.md

@@ -199,10 +199,11 @@ EOF
 
 **After creating the PR:**
 
-1. If user indicated review needed: request review
+1. If user indicated review needed (e.g., "review this", "flag for review", or high-risk changes like auth/infra/migrations):
    ```bash
-   gh pr edit <number> --add-reviewer <username>
+   gh pr edit <number> --add-label "needs-human-review"
    ```
+   This blocks merge until a human approves the PR on GitHub (requires the human-review-gate workflow — see `scripts/setup-github-app.sh`).
 2. Label beads issues as `in-pr`:
    ```bash
    bd update <id> --set-labels in-pr --json

.claude/skills/merge-queue/SKILL.md

@@ -16,7 +16,7 @@ Run this in a dedicated terminal window. Invoke periodically with `/merge` while
 gh run list --branch main --limit 1 --json status,conclusion
 
 # List open PRs
-gh pr list --json number,title,headRefName,statusCheckRollup,mergeable,body,reviewRequests,reviews
+gh pr list --json number,title,headRefName,statusCheckRollup,mergeable,body,reviewRequests,reviews,labels
 ```
 
 **If main CI is failing:** file a P0 beads issue (if one doesn't already exist), report prominently, and stop. Nothing can merge until main is green.
@@ -31,7 +31,8 @@ For each PR, determine its state:
 
 | State | Action |
 |-------|--------|
-| CI passing, mergeable, no pending review | Merge |
+| CI passing, mergeable, no pending review, no `needs-human-review` label | Merge |
+| CI passing, mergeable, `needs-human-review` label, not approved | Skip, report "awaiting human review" |
 | CI passing, mergeable, review requested but not approved | Skip, report |
 | CI passing, mergeable, review approved | Merge |
 | CI pending | Skip, report status |
@@ -86,15 +87,16 @@ gh pr merge <number> --squash|--merge  # per Step 4
    ```bash
    bd close <id> --reason "Merged in PR #<number>" --json
    ```
-3. Remove worktree if it exists:
+3. Note any `Closes #<number>` lines — GitHub auto-closes those issues on merge. Include them in the summary.
+4. Remove worktree if it exists:
    ```bash
    git worktree remove ../<project>-<branch-name> 2>/dev/null
    ```
-4. Delete feature branch:
+5. Delete feature branch:
    ```bash
    git branch -d feature/<branch-name> 2>/dev/null
    ```
-5. Pull main:
+6. Pull main:
    ```bash
    git pull origin main
    ```
@@ -105,27 +107,51 @@ gh pr merge <number> --squash|--merge  # per Step 4
 
 When a PR is not mergeable (behind main):
 
-```bash
-git fetch origin main
+1. **Locate or create a worktree for the PR branch:**
+   ```bash
+   # Use existing worktree if present, otherwise create one
+   git worktree add ../<project>-rebase-<number> <branch>
+   ```
 
-# Use existing worktree if present, otherwise create one
-cd <existing-worktree>  # or: git worktree add ../<project>-rebase-<number> <branch>
-git rebase origin/main
-```
+2. **Try fast-path rebase first** (inline bash — no subagent):
+   ```bash
+   cd ../<project>-rebase-<number>
+   git fetch origin main
+   git rebase origin/main && echo "REBASE: OK"
+   ```
 
-- **Clean rebase:** force-push, then **wait for CI to finish and merge** (see below).
-  ```bash
-  git push --force-with-lease
-  ```
-- **Trivial conflict:** resolve inline if the conflict is mechanical — e.g. adjacent line edits, import ordering, lock file regeneration, or both sides adding to the same list. After resolving, `git add` the files, `git rebase --continue`, and force-push. **Always include a conflict summary in the report:**
-  ```
-  Resolved 2 conflicts during rebase of PR #18:
-  - src/routes/api.ts: adjacent route additions (kept both)
-  - package-lock.json: regenerated
-  ```
-- **Non-trivial conflict:** file a beads issue describing the conflict, which files are affected, and what makes it non-trivial (semantic overlap, structural disagreement, etc.). Do not attempt to resolve. Report to user.
-
-After rebase, clean up any temporary worktree created for the rebase.
+3. **If fast-path succeeds:** force-push and proceed to CI polling.
+   ```bash
+   git push --force-with-lease
+   ```
+
+4. **If fast-path fails (conflict):** abort and spawn the rebase subagent:
+   ```bash
+   git rebase --abort
+   ```
+   Then spawn with context:
+   ```
+   ROLE: Rebase Agent (Conflict Resolution)
+   SKILL: Read and follow .claude/skills/rebase/SKILL.md
+
+   SOURCE: <branch>
+   TARGET: origin/main
+   WORKTREE: ../<project>-rebase-<number>
+   CLEANUP: false
+   PR_NUMBER: <number>
+   ```
+
+5. **On `RESULT: PASS`:** force-push the rebased branch, then **wait for CI to finish and merge** (see below).
+   ```bash
+   cd ../<project>-rebase-<number>
+   git push --force-with-lease
+   ```
+
+6. **On `RESULT: FAIL`:** file a beads issue describing the conflict using details from the sub-agent output, and report to the user.
+   ```bash
+   bd create "Rebase conflict on PR #<number>: <summary>" -t bug -p 1 --json
+   ```
+   Include in the issue body: which files conflicted, why the conflict is ambiguous, and the PR reference.
 
 **After a clean rebase, poll CI and merge when it passes.** Don't just report "rebased, CI re-running" and stop — unmerged PRs accumulate conflicts. Poll every 60 seconds until CI completes:
 

.claude/skills/planner/SKILL.md

@@ -44,11 +44,12 @@ This is collaborative. Do NOT silently make decisions — discuss with the user.
    - Tradeoffs (simplicity vs. flexibility, etc.)
 4. Point out risks and tradeoffs proactively — don't wait to be asked
 5. Iterate until you and the user agree on the approach
-6. Write the agreed plan to the plan file, then use ExitPlanMode for approval
 
 ### Phase 3 — File Issues
 
-After the user approves the plan:
+Present the agreed approach as a concise summary and use AskUserQuestion to confirm before filing. **Do NOT use EnterPlanMode or ExitPlanMode** — those trigger Claude Code's built-in plan execution behavior.
+
+After the user approves:
 
 1. Create the epic if one doesn't exist:
    ```bash
@@ -65,14 +66,29 @@ After the user approves the plan:
    bd dep add <blocked-task> <blocker-task> --json
    ```
 
+4. **Set dependencies to model execution order.** Tasks with no dependency relationship are implicitly parallel — the coordinator spawns all unblocked tasks concurrently. Use `bd dep add` only for true data/ordering dependencies (shared types, migrations before code, etc.). Don't over-constrain — occasional file overlap between parallel tasks is fine; the coordinator handles conflicts optimistically.
+
 **Each subtask MUST be self-contained** (per AGENTS.md rules):
 - **Summary**: What and why in 1-2 sentences
 - **Files to modify**: Exact paths (with line numbers if relevant)
+- **Files to read for context**: Paths the implementer will need to understand before coding
+- **Testing notes**: What test coverage to add. Call out integration tests explicitly when changes affect persistence, API routes, auth, or cross-layer data flow.
 - **Implementation steps**: Numbered, specific actions
 - **Example**: Show before → after transformation when applicable
 
 A future implementer session must understand the task completely from its description alone — no external context.
 
+### Task Sizing
+
+Each subtask must fit within a single implementer context window without compaction. Use these heuristics:
+
+- **≤5 production files modified** per task
+- **≤10 files read for context** (including the files to modify, test files, shared types, referenced modules)
+- Prefer narrow vertical slices (one endpoint end-to-end) over horizontal layers (all endpoints at once)
+- When in doubt, split. Two small tasks are better than one that causes compaction.
+
+If "Files to read for context" exceeds ~10 entries, the task is probably too large — consider splitting it. But if splitting would create awkward boundaries or tightly coupled tasks, it's better to leave a large task whole.
+
 ### Phase 4 — Plan Review
 
 After issues are filed, spawn a plan reviewer:
@@ -91,7 +107,7 @@ The reviewer checks the filed issues against the codebase for architectural issu
 - Iterate: update, create, or close issues as needed
 - Re-run reviewer if significant changes were made
 
-**Output**: An epic with subtasks ready for `/work <epic-id>`. Tell the user the epic ID and suggest running `/work <epic-id>` to start implementation.
+**Output**: Tell the user the epic ID and that it's ready for `/work <epic-id>` in a separate session. **Stop here** — do NOT start implementation.
 
 ## Your Constraints
 
@@ -109,3 +125,5 @@ The reviewer checks the filed issues against the codebase for architectural issu
 - ❌ File issues before the user approves the plan
 - ❌ Skip codebase exploration (guessing at patterns leads to bad plans)
 - ❌ Create vague subtasks ("implement the feature") — be specific
+- ❌ Use EnterPlanMode/ExitPlanMode (triggers unwanted auto-implementation)
+- ❌ Start implementation after filing issues — stop and let the user `/work` separately