tau-coding-agent 0.1.6 → 0.2.0

package/skills/browser-tools/SKILL.md

@@ -1,253 +1,48 @@
 ---
 name: browser-tools
-description: Interactive browser automation via Chrome DevTools Protocol. Use when you need to interact with web pages, test frontends, or when user interaction with a visible browser is required.
+description: Interactive browser automation via Chrome DevTools Protocol. Use for real-browser frontend testing, dynamic-page interaction, or user selection in a visible browser.
 ---
 
 # Browser Tools
 
-Chrome DevTools Protocol tools for agent-assisted web automation. These tools connect to a Chromium-based browser (Chromium/Chrome) running on `:9222` with remote debugging enabled.
+Tools for interacting with Chromium or Google Chrome over remote debugging at `127.0.0.1:9222`. Ordinary source edits and pages retrievable without browser interaction do not require this skill.
 
-## Requirements
+## Setup and session ownership
 
-Chromium or Google Chrome with remote debugging support. The scripts auto-detect common installs; set `BROWSER_TOOLS_BROWSER` or `BROWSER_TOOLS_EXECUTABLE` if auto-detection picks the wrong browser.
+Chromium or Chrome with remote debugging support is required. Scripts auto-detect common macOS and Linux installs. For development in a source checkout, install dependencies with `npm install` at the repository root.
 
-## Setup
-
-When hacking on this skill from a source checkout:
-
-```bash
-npm install
-```
-
-## Tools
-
-Important: Always run commands from this skill directory.
-
-### Start Chromium / Chrome
-
-```bash
-"./scripts/browser-start.js"              # Dedicated tool profile
-"./scripts/browser-start.js" --profile    # Seed from your browser profile (cookies, logins)
-"./scripts/browser-start.js" --watch      # Start background JSONL logging
-"./scripts/browser-start.js" --browser chromium
-"./scripts/browser-start.js" --browser chrome
-```
-
-Launch a browser with remote debugging on `:9222`. Use `--profile` to preserve your authentication state. If a browser is already running on `:9222`, it is reused; launch options like `--browser`, `--executable`, and `--profile` only affect new browser instances.
-
-If the auto-detection picks the wrong browser, set:
-
-- `BROWSER_TOOLS_BROWSER=chromium` (or `chrome`)
-- `BROWSER_TOOLS_EXECUTABLE=/absolute/path/to/browser`
-- `BROWSER_TOOLS_PROFILE_SRC=/absolute/path/to/profile/dir` (optional; useful with `--executable --profile`)
-
-### Navigate
-
-```bash
-"./scripts/browser-nav.js" https://example.com
-"./scripts/browser-nav.js" https://example.com --new
-```
-
-Navigate to URLs. Use `--new` flag to open in a new tab instead of reusing current tab.
-
-### Evaluate JavaScript
-
-```bash
-"./scripts/browser-eval.js" 'document.title'
-"./scripts/browser-eval.js" 'document.querySelectorAll("a").length'
-"./scripts/browser-eval.js" 'const el = document.querySelector("textarea"); return el?.value'
-"./scripts/browser-eval.js" --file ./snippet.js
-printf 'return document.title\n' | "./scripts/browser-eval.js" --stdin
-```
-
-Execute JavaScript in the active tab. Code runs in async context. Expressions and statement bodies are both supported. Use `return` when passing statements or multi-line code.
-
-### Screenshot
-
-```bash
-"./scripts/browser-screenshot.js"
-```
-
-Capture current viewport and return temporary file path. Use this to visually inspect page state or verify UI changes.
-
-### Pick Elements
-
-```bash
-"./scripts/browser-pick.js" "Click the submit button"
-```
-
-Use this when the user wants to select specific DOM elements on the page. This launches an interactive picker: click elements to select them, Cmd/Ctrl+Click for multi-select, Enter to finish.
-
-### Dismiss cookie banners
-
-```bash
-"./scripts/browser-dismiss-cookies.js"          # Accept cookies
-"./scripts/browser-dismiss-cookies.js" --reject # Reject (where possible)
-```
-
-Run after navigation if cookie dialogs interfere with interaction.
-
-### Cookies
-
-```bash
-"./scripts/browser-cookies.js"
-"./scripts/browser-cookies.js" --format=netscape > cookies.txt
-```
-
-Display all cookies for the current tab including domain, path, httpOnly, and secure flags.
-
-The `--format=netscape` option outputs cookies in Netscape format for use with curl/wget (`curl -b cookies.txt`).
-
-### Extract Page Content
-
-```bash
-"./scripts/browser-content.js" https://example.com
-```
-
-Navigate to a URL and extract readable content as markdown. Uses Mozilla Readability for article extraction and Turndown for HTML-to-markdown conversion.
-
-### Background logging (console + errors + network)
-
-Start the watcher:
-
-```bash
-"./scripts/browser-watch.js"
-```
-
-Or launch the browser with logging enabled:
-
-```bash
-"./scripts/browser-start.js" --watch
-```
-
-Logs are written as JSONL to a temp directory by default:
-
-- Default: `/tmp/agent-browser-tools/logs/YYYY-MM-DD/<targetId>.jsonl`
-- Override: `BROWSER_TOOLS_LOG_ROOT=/some/dir`
-
-Tail the most recent log:
-
-```bash
-"./scripts/browser-logs-tail.js"           # dump and exit
-"./scripts/browser-logs-tail.js" --follow  # follow
-```
-
-Summarize network responses (status codes, failures):
+Run browser commands from this skill directory. All command paths in this skill and its references are relative to this directory, not `references/`.
 
 ```bash
-"./scripts/browser-net-summary.js"
-"./scripts/browser-net-summary.js" --file /path/to/log.jsonl
-```
-
-### When to Use
-
-- Testing frontend code in a real browser
-- Interacting with pages that require JavaScript
-- When user needs to visually see or interact with a page
-- Debugging authentication or session issues
-- Scraping dynamic content that requires JS execution
-
-## Efficiency Guide
-
-### DOM Inspection Over Screenshots
-
-**Don't** lead with screenshots to inspect page state. **Do** prefer parsing the DOM directly first, and use screenshots when you need visual/layout verification:
-
-```javascript
-// Get page structure
-document.body.innerHTML.slice(0, 5000);
-
-// Find interactive elements
-Array.from(document.querySelectorAll('button, input, [role="button"]')).map((e) => ({
-  id: e.id,
-  text: e.textContent.trim(),
-  class: e.className,
-}));
-```
-
-### Complex Scripts in Single Calls
-
-Use one eval call for multi-step workflows. `browser-eval.js` supports statement bodies, `return`, and `await`:
-
-```javascript
-const data = document.querySelector("#target")?.textContent;
-const buttons = document.querySelectorAll("button");
-
-buttons[0]?.click();
-
-return {
-  data,
-  buttonCount: buttons.length,
-};
-```
-
-### Batch Interactions
-
-**Don't** make separate calls for each click. **Do** batch them:
-
-```javascript
-const actions = ["btn1", "btn2", "btn3"];
-actions.forEach((id) => document.getElementById(id)?.click());
-return "Done";
-```
-
-### Typing/Input Sequences
-
-For normal form inputs, set the value and dispatch events in one call:
-
-```javascript
-const input = document.querySelector('input[name="email"]');
-if (!input) return "Input not found";
-
-input.value = "user@example.com";
-input.dispatchEvent(new Event("input", { bubbles: true }));
-input.dispatchEvent(new Event("change", { bubbles: true }));
-
-document.querySelector('button[type="submit"]')?.click();
-return "Submitted";
-```
-
-### Reading App/Game State
-
-Extract structured state in one call:
-
-```javascript
-const state = {
-  score: document.querySelector(".score")?.textContent,
-  status: document.querySelector(".status")?.className,
-  items: Array.from(document.querySelectorAll(".item")).map((el) => ({
-    text: el.textContent,
-    active: el.classList.contains("active"),
-  })),
-};
-return state;
+"./scripts/browser-start.js"                         # Dedicated tool profile
+"./scripts/browser-start.js" --profile               # Seed cookies/logins from your browser profile
+"./scripts/browser-start.js" --browser chromium      # Or chrome
+"./scripts/browser-start.js" --executable /path/to/browser
 ```
 
-### Waiting for Updates
+- An existing browser on `:9222` is reused. `--browser`, `--executable`, and `--profile` affect only new instances. Do not kill or restart a user's browser to apply launch options.
+- New instances use `~/.cache/browser-tools`. `--profile` syncs the source profile into that dedicated directory, excluding session/tab files. It does not operate directly on the source profile, but can overwrite tool-profile state. Use it when existing authentication is needed, not as a routine reset.
+- Preserve the user's tabs, drafts, and authentication. Open a new tab rather than navigating an unrelated one. Check the target URL before acting. Close only tabs you created and no longer need, not user-owned tabs or the reused browser.
 
-If DOM updates after actions, wait inside the same eval call:
+Environment overrides:
 
-```javascript
-document.querySelector("#submit")?.click();
-await new Promise((resolve) => setTimeout(resolve, 500));
+| Variable                    | Purpose                                                                                                          |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `BROWSER_TOOLS_BROWSER`     | `chromium` or `chrome` selection                                                                                 |
+| `BROWSER_TOOLS_EXECUTABLE`  | Explicit browser executable path                                                                                 |
+| `BROWSER_TOOLS_PROFILE_SRC` | Source profile directory for `--profile`. With a custom executable in auto mode, set this or select `--browser`. |
+| `BROWSER_TOOLS_LOG_ROOT`    | Watcher log directory. See the logging reference before enabling capture.                                        |
 
-return {
-  status: document.querySelector(".status")?.textContent,
-};
-```
-
-### Investigate Before Interacting
+## Task router
 
-Always start by understanding the page structure:
+Read only the reference needed for the task before running its commands.
 
-```javascript
-return {
-  title: document.title,
-  forms: document.forms.length,
-  buttons: document.querySelectorAll("button").length,
-  inputs: document.querySelectorAll("input").length,
-  mainContent: document.body.innerHTML.slice(0, 3000),
-};
-```
+| Task                                                              | Read                                     | Scripts                                                                                          |
+| ----------------------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| Navigate, inspect DOM, interact, or wait for app state            | [Interaction](references/interaction.md) | `browser-nav.js`, `browser-eval.js`                                                              |
+| Verify appearance or let the user select elements                 | [Interaction](references/interaction.md) | `browser-screenshot.js`, `browser-pick.js`                                                       |
+| Extract readable content that needs a browser                     | [Interaction](references/interaction.md) | `browser-content.js`                                                                             |
+| Diagnose console errors or network activity                       | [Logging](references/logging.md)         | `browser-watch.js`, `browser-logs-tail.js`, `browser-net-summary.js`, `browser-start.js --watch` |
+| Handle blocking consent dialogs or inspect/export session cookies | [Cookies](references/cookies.md)         | `browser-dismiss-cookies.js`, `browser-cookies.js`                                               |
 
-Then target specific elements based on what you find.
+Choose DOM inspection for structure and values, screenshots for visual questions, and the picker when the user wants to identify elements. Batch only steps whose intermediate results do not need inspection. Verify observable outcomes rather than equating a click or elapsed delay with success.

package/skills/browser-tools/references/cookies.md

@@ -0,0 +1,36 @@
+# Consent dialogs and cookies
+
+Run commands from the browser-tools skill root. These scripts act on the selected tab. Confirm the URL before changing consent or accessing session data.
+
+## Blocking consent dialogs
+
+```bash
+"./scripts/browser-dismiss-cookies.js"          # Accept cookies
+"./scripts/browser-dismiss-cookies.js" --reject # Reject where possible
+```
+
+Use only when a cookie dialog blocks the task, not automatically after every navigation. Honor the user's consent preference. The default accepts cookies, so do not use it as a neutral close operation. If the choice is consequential and unspecified, clarify it rather than granting consent silently.
+
+The script uses heuristic selectors and text matches across the page and likely consent frames. Inspect an ambiguous dialog directly instead of trusting a generic match. Verify the resulting dialog state and consent choice. A reported click is not proof that consent was saved, and “no dialog found” does not prove none exists. Do not add fixed sleeps as a substitute for observing the dialog or its dismissal.
+
+## Inspect or export cookies
+
+```bash
+"./scripts/browser-cookies.js"
+```
+
+Prints cookies for the current tab, including values, domain, path, httpOnly, and secure flags. This exposes session secrets. Inspect only when needed for the authorized task. Do not paste cookie values into reports, logs, source control, or unrelated services.
+
+`--format=netscape` produces cookie-file output for curl/wget. If the task requires authenticated retrieval outside the browser, keep the export private and temporary:
+
+```bash
+(
+  umask 077
+  cookie_file=$(mktemp) || exit 1
+  trap 'rm -f "$cookie_file"' EXIT
+  "./scripts/browser-cookies.js" --format=netscape > "$cookie_file" || exit 1
+  curl -b "$cookie_file" https://example.com/protected-page
+)
+```
+
+Replace the URL with the authorized destination. The subshell owns the cookie file until the request completes, then removes it. The export still contains credentials. Do not clear cookies, log out, or reset the user's profile as diagnostic cleanup.

package/skills/browser-tools/references/interaction.md

@@ -0,0 +1,90 @@
+# Browser interaction
+
+Run commands from the browser-tools skill root, not this reference directory. Scripts select the visible, focused page, falling back to the last HTTP(S) page and then the last page. Confirm `location.href` before acting, especially with multiple tabs open.
+
+## Navigate and inspect
+
+```bash
+"./scripts/browser-nav.js" https://example.com --new # Preserve unrelated tabs
+"./scripts/browser-nav.js" https://example.com       # Reuse the selected tab
+"./scripts/browser-eval.js" '({ url: location.href, title: document.title })'
+"./scripts/browser-screenshot.js"
+```
+
+Navigation waits for `DOMContentLoaded`, not application readiness. Screenshots capture the current viewport and print a temporary image path to open with the image-reading tool.
+
+Inspect what the task needs: DOM for text, controls, and structured state; screenshots for layout, styling, occlusion, and visual verification. Neither must always come first. Identify the intended target and its current state before changing it. Avoid broad HTML dumps when a focused query answers the question.
+
+## Evaluate JavaScript
+
+```bash
+"./scripts/browser-eval.js" 'document.title'
+"./scripts/browser-eval.js" 'const el = document.querySelector("textarea"); return el?.value'
+"./scripts/browser-eval.js" --file ./snippet.js
+printf 'return document.title\n' | "./scripts/browser-eval.js" --stdin
+```
+
+Code runs in the page's async context. Expressions and statement bodies are supported, including `await`. Use an explicit `return` for statements or multi-line bodies. Objects and arrays print as JSON. The page context is not a Puppeteer `page` object or a Node environment. `./snippet.js` is a file you supply relative to the skill root.
+
+Batch related reads or independent, reversible interactions when no intermediate decision or verification is needed. Separate actions when navigation, validation, asynchronous updates, or consequential effects could change the next step. Do not batch clicks blindly or report success just because a handler was invoked. Apply the user's authorization to submissions and other external changes.
+
+For an ordinary input, setting a value and dispatching events can be done together:
+
+```javascript
+const input = document.querySelector('input[name="email"]');
+if (!input) throw new Error("Email input not found");
+input.value = "user@example.com";
+input.dispatchEvent(new Event("input", { bubbles: true }));
+input.dispatchEvent(new Event("change", { bubbles: true }));
+return { value: input.value };
+```
+
+This does not submit the form or prove the app accepted the value. Controlled inputs and custom widgets may need different handling. Synthetic events also do not prove real keyboard or pointer behavior. Inspect the app's response before proceeding and use real user interaction when that is the contract being tested.
+
+## Wait for observable readiness
+
+After an action, wait for the relevant state: a result appears, validation completes, a loading indicator clears, or a known request finishes. Use a bounded wait with an explicit failure, not a fixed sleep followed by an assumed success. For a DOM-driven app, adapt the selector and readiness predicate to the page:
+
+```javascript
+return await new Promise((resolve, reject) => {
+  const observer = new MutationObserver(check);
+  const timeout = setTimeout(() => {
+    observer.disconnect();
+    reject(new Error("Results did not become ready within 10 seconds"));
+  }, 10000);
+
+  function check() {
+    const result = document.querySelector('#results[data-state="ready"]');
+    if (!result) return;
+    observer.disconnect();
+    clearTimeout(timeout);
+    resolve({ text: result.textContent });
+  }
+
+  observer.observe(document.documentElement, {
+    subtree: true,
+    childList: true,
+    attributes: true,
+    characterData: true,
+  });
+  check();
+});
+```
+
+The timeout is a failure bound, not the readiness signal. Tie readiness to the action just performed so stale results cannot satisfy it. If the action navigates, inspect the new document in a subsequent call rather than expecting an in-page eval to survive navigation.
+
+## User-selected elements
+
+```bash
+"./scripts/browser-pick.js" "Click the submit button"
+```
+
+Use the picker when the user wants to select specific DOM elements. It requires a visible page and an available user, not a headless workflow. A normal click selects and finishes. Cmd/Ctrl+Click collects multiple selections, Enter finishes them, and Escape cancels with `null`. Treat cancellation as cancellation, not a successful empty selection. Let the user make the selection rather than simulating it.
+
+## Readable page content
+
+```bash
+"./scripts/browser-content.js" https://example.com
+```
+
+This navigates the selected tab and extracts Markdown using Mozilla Readability and Turndown, with a main-content fallback. Use a task-owned tab to preserve user work. It is not a read-only snapshot of the current DOM, and extraction does not guarantee the requested app state finished loading. Verify the final URL and relevant content. For pages that do not need browser interaction, fetch the supplied URL directly instead.

package/skills/browser-tools/references/logging.md

@@ -0,0 +1,34 @@
+# Browser logging
+
+Run commands from the browser-tools skill root. The watcher records console output, page errors/crashes, navigation, and network request/response/failure metadata as JSONL. It attaches to all existing pages and new pages, not just the active tab. Enable it only when that browser-wide capture is appropriate. URLs and console messages can contain credentials or personal data. Keep logs local and redact sensitive material before sharing.
+
+## Start capture
+
+```bash
+"./scripts/browser-watch.js"          # Foreground watcher
+"./scripts/browser-start.js" --watch  # Launch/reuse browser and start a detached watcher
+```
+
+Prefer the foreground watcher when you need to own its lifetime. Start capture before reproducing the problem and wait for the watcher's startup confirmation. It cannot recover events from before attachment.
+
+Default log paths on macOS/Linux:
+
+- `/tmp/agent-browser-tools/logs/YYYY-MM-DD/<targetId>.jsonl`
+- Override the root with `BROWSER_TOOLS_LOG_ROOT=/some/dir` for both capture and readers.
+- The date directory is chosen when the watcher starts.
+
+One watcher per log root is tracked by `.watch.pid`. If one already exists, it is reused rather than replaced. Keep track of whether you started it. Stop your foreground watcher with Ctrl+C when done. For a detached watcher, inspect the PID file under that log root and verify it still identifies the watcher you started before sending SIGTERM. Do not stop someone else's watcher or the browser. Retain only logs the task needs and remove your temporary logs when no longer needed.
+
+## Read capture
+
+```bash
+"./scripts/browser-logs-tail.js"                          # Dump latest log and exit
+"./scripts/browser-logs-tail.js" --file /path/to/log.jsonl
+"./scripts/browser-logs-tail.js" --file /path/to/log.jsonl --follow
+"./scripts/browser-net-summary.js"
+"./scripts/browser-net-summary.js" --file /path/to/log.jsonl
+```
+
+Without `--file`, readers choose the most recently modified JSONL file in the newest dated directory. That may belong to another tab. Use `target.attached` or `page.navigated` URLs to identify the task's capture, then pass its file explicitly. `--follow` follows that chosen file, not whichever tab becomes active later. Stop the follow process when finished.
+
+The network summary reports request/response totals, status counts, and up to ten failures. It does not prove application success, include response bodies, or replace examination of relevant log records. Correlate the observed failure with the reproduction and visible app state.

package/skills/git-clean-history/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: git-clean-history
-description: "Reimplement the current Git branch on a fresh branch off `main` with a clean, narrative-quality commit history."
+description: "Rebuild the current branch from `main` on a fresh branch with a clean, narrative commit history."
 ---
 
-# Git Rebase
+# Git Clean History
 
 Use this skill to reimplement the current branch on a new branch with a clean, narrative-quality git commit history suitable for reviewer comprehension.
 
@@ -31,13 +31,13 @@ Use this skill to reimplement the current branch on a new branch with a clean, n
    - Each commit must:
      - Introduce a single coherent idea
      - Include a clear commit message and description
-     - Follow best practices for the message as outlined by the `git-commit` skill
-   - **Use `git commit --no-verify` for all intermediate commits**
-     - Pre-commit hooks check tests, types, and imports that may not pass until the full implementation is complete; do not waste time fixing issues in intermediate commits that will be resolved by later commits
+     - Follow the repository's commit-message conventions
+   - **Use `git commit --no-verify` for all intermediate commits while cleaning history.**
+     - Pre-commit hooks check tests, types, and imports that may not pass until the full implementation is complete. Do not spend time fixing intermediate issues that later commits in the reconstruction will resolve.
 
 6. **Verify correctness**
    - Confirm the final state exactly matches the source branch
-   - Run the final commit **without** `--no-verify` to ensure all checks pass
+   - Run the final commit **without** `--no-verify`, and ensure the repository's required checks pass
 
 ### Rules
 

package/skills/git-commit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: git-commit
-description: "Commit changes with an emphasis on tidiness and reviewability: small, focused commits, with clear rationale in messages."
+description: "Propose commit messages and create small, focused commits with clear rationale."
 ---
 
 # Git Commit
@@ -11,7 +11,6 @@ Use this skill as the playbook for producing reviewable commits and a clean, con
 
 1. Check what files have changed
 2. If there are no changes to commit, inform the user and stop
-3. If there are unstaged changes, stage relevant hunks or files with `git add -p` or `git add`
 
 Rules:
 
@@ -44,7 +43,10 @@ Rules:
 
 ## Phase 3: Commit
 
-1. Commit staged changes with `git commit`
+Only proceed when the user requested a commit. For message-only requests, return the proposed message and stop.
+
+1. If there are unstaged changes, stage relevant hunks or files with `git add -p` or `git add`
+2. Commit staged changes with `git commit`
 
 Rules:
 

package/skills/github-pull-request/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: github-pull-request
+description: "Create and steward GitHub PRs. Use when opening a PR, monitoring CI, handling review feedback, resolving conflicts, or getting a PR ready to merge."
+---
+
+# GitHub Pull Request
+
+Create or steward a GitHub pull request through CI and review. Once requested, continue routine stewardship under the checkpoints below. Repository instructions and explicit user direction take precedence. Requests for copy, analysis, a proposal, or status-only monitoring do not authorize commits, pushes, PR creation, or publishing metadata changes.
+
+## Task router
+
+| Request                                             | Route                                                                                                                                                                                    |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Open a PR                                           | [Create a PR](references/create.md): discover conventions, audit the branch, create and verify, then steward. Resume an existing open PR for the branch instead of creating a duplicate. |
+| Monitor or steward an existing PR                   | [Existing-PR stewardship](references/stewardship.md): start with its live state, current head, CI, and feedback. Do not repeat creation phases or create another PR.                     |
+| Analyze status, assess feedback, or draft copy only | Use the relevant reference for context, then return the requested analysis or copy without publishing or changing code/history.                                                          |
+
+## Authorization
+
+“Explicit” means explicitly requested or done manually by the user. Autonomous actions below remain limited to the authorized task. Only clearly identified bots or GitHub Apps count as automated reviewers; otherwise treat feedback as human.
+
+| Action                                                                                  | Default                                                                       |
+| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| Determine the branch, base, title, body, and commonly used descriptive labels           | Autonomous                                                                    |
+| Commit, push, and open the PR                                                           | Autonomous once requested; draft by default                                   |
+| Make small factual PR metadata updates                                                  | Autonomous, while preserving user edits                                       |
+| Monitor CI, pending checks, and automated reviews                                       | Autonomous                                                                    |
+| Request or re-request automated reviewers                                               | Autonomous when the repository workflow calls for it                          |
+| Rerun clearly flaky or infrastructure-failed checks                                     | Autonomous                                                                    |
+| Fix small, confident, in-scope CI or automated-review findings                          | Autonomous                                                                    |
+| Reply to and resolve automated findings                                                 | Autonomous when fixed, already addressed, invalid, low-value, or out of scope |
+| Resolve trivial conflicts and update the PR branch                                      | Autonomous; use `--force-with-lease` when needed                              |
+| Handle findings or changes that are large, uncertain, architectural, or scope-expanding | Checkpoint: assess and wait                                                   |
+| Change an existing PR's base, close or reopen it, or resolve nontrivial conflicts       | Checkpoint: explain and wait                                                  |
+| Mark ready for review                                                                   | Explicit                                                                      |
+| Apply review/readiness or automation-triggering labels                                  | Explicit                                                                      |
+| Request human reviewers                                                                 | Explicit                                                                      |
+| Address, reply to, or resolve human feedback                                            | Checkpoint: assess and wait                                                   |
+| Enable auto-merge or merge                                                              | Explicit                                                                      |
+| Delete the merged remote PR branch                                                      | Autonomous when safe                                                          |
+| Update the base branch after merge                                                      | Explicit                                                                      |
+
+For human feedback, investigate and recommend an action, but do not edit, reply, or resolve without explicit direction. Authorization to make a code fix does not itself authorize replying or resolving. For large or uncertain automated findings, assess with the user and leave the feedback untouched.
+
+## Completion, readiness, and merge boundaries
+
+For authorized stewardship, continue until the current-stage readiness criteria are met or a checkpoint/blocker requires user input. A bounded analysis or copy request ends with that requested output, not publication.
+
+Report that a draft appears ready when:
+
+- the branch is mergeable and based correctly
+- current-stage checks passed on the current head, with none pending
+- current-stage automated reviews are complete, with no unresolved threads
+- the title and body describe the final scope
+
+Never infer success from command errors, missing status, or results for an earlier head. Track the new head after every push. Treat live PR metadata as authoritative and preserve user-supplied or approved copy.
+
+Never mark ready automatically. If the user does, continue stewardship for newly triggered checks and reviews. Later invocations resume the current PR. Report when repository approval rules are satisfied. Enable auto-merge or merge only when explicit, using the requested or repository-standard strategy.
+
+After merge, delete the remote PR branch unless another open PR targets it. Do not delete the local branch or update the base branch unless requested.

package/skills/github-pull-request/references/create.md

@@ -0,0 +1,40 @@
+# Create a PR
+
+Use this route when PR creation is requested, subject to the [authorization matrix](../SKILL.md#authorization). For copy or analysis alone, use only the relevant reading and drafting steps. Do not stage, commit, push, or publish as a side effect.
+
+## Discover conventions
+
+1. Confirm GitHub CLI availability and authentication.
+2. Read repository instructions, contribution docs, local PR guidance, and every applicable template.
+3. Identify the repository, default and current branches, remote, related issues, and any stacked PR.
+4. Inspect recent relevant human-authored PRs for conventions, preferring the user's own when comparably relevant; exclude bots and one-offs.
+5. Resume any open PR associated with the current branch through [stewardship](stewardship.md) instead of creating a duplicate.
+
+Repository evidence outranks generic advice. If conventions appear ambiguous, ask before proceeding.
+
+## Audit the branch
+
+1. Fetch the intended base branch.
+2. Inspect the working tree, commits, and complete base-to-head diff. Confirm one coherent change free of unrelated, sensitive, temporary, or accidental content.
+3. For a stacked PR, verify the exact commits and diff against its parent branch.
+4. Check changelog, generated-file, test, commit-hook, and commit-signing requirements.
+5. If on the default branch, create a correctly named branch. Otherwise rename it before its initial push when required.
+6. Use the `git-commit` skill for new commits. Do not rewrite commits merely for cleanup; base rebases follow the [conflict rules](stewardship.md#ci-and-conflicts).
+
+If the changes belong in separate PRs, stop and explain why.
+
+## Create and verify
+
+- Match the repository's PR title style. For a single commit, consider its title as a starting point.
+- Follow local PR instructions and retain required template sections. Use `N/A` when inapplicable unless conventions allow omission.
+- Focus the body on what changed, why, the approach, and meaningful trade-offs.
+- Omit boilerplate Summary, Testing, Demo, or file-inventory sections unless the repository or change requires them.
+- A simple issue reference such as `Closes #123` may be the complete body.
+- Preserve user-supplied or approved copy. Append nothing to copy supplied exactly.
+- Pass the body through a temporary Markdown file, never inline escaped newlines.
+- Apply descriptive labels only when commonly used on comparable PRs. Review/readiness or automation-triggering labels still require explicit authorization.
+- Never push the default branch. Push the PR branch and set its upstream.
+- Create with an explicit base, head, title, and `--body-file`. Use `--draft` unless requested otherwise.
+- Re-fetch the live PR and verify its repository, branches, metadata, draft state, and rendered body. Ensure it has no literal `\n` sequences or stale placeholders.
+
+Continue with [CI and review stewardship](stewardship.md), stopping at the root skill's [readiness and merge checkpoints](../SKILL.md#completion-readiness-and-merge-boundaries).