frostney · frostney · Jun 2, 2026 · Jun 2, 2026
diff --git a/.agents/skills/create-issue/SKILL.md b/.agents/skills/create-issue/SKILL.md
@@ -1,58 +1,118 @@
 ---
 name: create-issue
-description: Create a well-structured GocciaScript GitHub issue from a tagline or short description, using the repository issue template and project issue style. Use when the user enters /create-issue.
+description: >-
+  Creates a well-structured GitHub issue from a tagline or short description in
+  any repository, investigating for duplicates and invoking the grill skill
+  (grill-with-docs / grill-me) as a mandatory gate before drafting, using the
+  project's issue template and label conventions, and capturing UI/UX context
+  (screenshots, design references, accessibility, responsive, theme) when the
+  change is user-facing. Use when the user runs /create-issue or asks to file a
+  GitHub issue.
+license: Unlicense OR MIT
+compatibility: >-
+  Requires the GitHub CLI (gh) authenticated to the target repository and
+  network access.
 ---
 
-# Create Issue
+# Create issue
 
-Create a GitHub issue from the user's tagline or short description.
+## Instructions
 
-## Steps
+Create a GitHub issue in the current repository from the user's tagline or short description.
 
-1. Parse the user's tagline or short description from the command arguments. If it is missing, ask for it.
-2. Read `.github/ISSUE_TEMPLATE/default.md`.
-3. Use the established GocciaScript issue style. Good issues in this repo typically include:
-   - A specific, plain-language title without an area prefix.
+### Non-negotiable gates (do not skip, do not rationalize)
+
+These gates are mandatory. Do not skip them because the tagline "looks clear" or because creating an issue feels like a quick task.
+
+1. **GATE A — Grill before drafting.** When a grill skill is registered, you **must** invoke it (step 4) before drafting the issue body. Do not draft without it.
+2. **GATE B — Investigate before drafting.** You **must** complete the investigation in step 3 (search for duplicates, read the implementation area) before drafting. Do not draft from the tagline alone.
+
+**Forbidden rationalizations** — if you catch yourself writing any of these, stop and follow the gate instead:
+
+- ❌ "The tagline is clear enough, I'll just draft it." → No. Grill and investigate first; a sharper issue comes from the questions you haven't asked yet.
+- ❌ "Grill isn't necessary for a simple issue." → No. If it's registered, run it.
+- ❌ "I treated `grill-with-docs` as 'answer with doc-grounding' instead of actually running the grilling loop." → No. Invoking grill means **executing the grill skill itself** — its real, interactive question loop — not answering in a doc-grounded style, not paraphrasing what it would ask. Load the skill and run it.
+- ❌ "I'll ask a couple of clarifying questions of my own; that's basically grilling." → No. That is not the grill skill. Run the actual `grill-with-docs` / `grill-me` skill.
+
+### Use the grill skill for thoroughness (always when available)
+
+Before drafting, the agent **always invokes the grill skill** when it is registered in this environment — not only when something is ambiguous. This is GATE A above. The grill output is folded into the issue body so the result is more thorough than the raw tagline would produce.
+
+**Invoking the grill skill means literally running that skill — not imitating its spirit.** `grill-with-docs` and `grill-me` are separate skills with their own multi-question interrogation loop. To invoke one you **read its `SKILL.md` and execute its procedure**: actually ask the user the grilling questions it generates and wait for the answers, iterating until the loop completes. The following are **NOT** invoking it and are forbidden substitutes:
+
+- Treating the mention of `grill-with-docs` as a style instruction — "answer with doc-grounding," "be thorough," "cite the docs" — and then proceeding. ❌
+- Summarizing or paraphrasing the questions grilling *would* ask instead of asking them. ❌
+- Asking one or two clarifying questions of your own and calling that grilling. ❌
+- Skipping it because you believe you already understand the tagline. ❌
+
+If you cannot run the grill skill, do not silently downgrade it to "doc-grounded answering" — say explicitly that no grill skill was found (see discovery hint) and proceed on the input as given.
+
+- **`/grill-with-docs` is preferred.** Use `/grill-me` only when `/grill-with-docs` is not registered.
+- Discovery hint: look for a skill or command named `grill-with-docs` or `grill-me` (e.g. `~/.cursor/skills/grill-with-docs/`, `~/.cursor/skills/grill-me/`, `.cursor/skills/...`, `.agents/skills/...`).
+- If neither is registered, state explicitly that no grill skill was found, then proceed with the workflow on the input as given.
+
+### Steps
+
+1. Parse the tagline or short description. If missing, ask.
+2. Resolve the issue template:
+   - Prefer `.github/ISSUE_TEMPLATE/` (multiple templates); pick the one matching the issue type (bug, feature, chore, etc.).
+   - Fall back to `.github/ISSUE_TEMPLATE/default.md` or `.github/ISSUE_TEMPLATE.md`.
+   - If no template exists, use a minimal structure: Summary, Reproduction (bugs), Current vs Expected, Scope, Related.
+3. **Investigate before drafting (GATE B):**
+   - Search code, docs, tests, and existing open/closed issues for duplicates and related work.
+   - Read the implementation area the issue touches. Do not draft from the tagline alone.
+   - If the tagline cannot become a concrete issue without guessing, stop and ask.
+4. **Run the grill skill (GATE A).** When `grill-with-docs` / `grill-me` is registered, **read that skill and execute its actual question loop now** on the tagline plus your investigation findings — ask the questions, wait for answers, iterate to completion — then fold its output into the issue body. Do not substitute a "doc-grounded" answer or your own ad-hoc questions for the skill. If none is registered, say so explicitly and continue.
+5. Draft the issue. A good issue typically includes:
+   - A specific, plain-language title with no area prefix (use labels for area/type).
    - A short problem summary.
-   - Reproduction commands or a minimal code sample for bugs.
-   - Current behavior and expected behavior.
-   - Spec context or project context when relevant.
-   - Test impact, blocked tests, or user impact.
+   - For bugs: reproduction command or minimal code/UI sample; current vs expected behavior.
+   - Project context (spec, RFC, related issue) when relevant.
+   - Test impact, user impact, or blocked work.
    - Likely fix area, scope notes, constraints, and related issues.
-4. Investigate the codebase enough to avoid creating a vague or duplicate issue. Search for related code, docs, tests, and existing issues. If the tagline cannot be turned into a concrete issue without guessing, ask clarifying questions.
-5. Draft the issue using the repository template. Preserve the template's headings unless another project issue pattern is clearly more appropriate for the issue type.
-6. Choose labels by matching existing project label conventions. Use labels, not title prefixes, to capture area and type. Do not invent new labels unless the user asks.
-7. Show the title, labels, and body draft to the user before creating the issue unless the user explicitly asked to create it without review.
-8. Create the issue with GraphQL first. Include `labelIds` only when labels were selected:
-
-```bash
-gh api graphql \
-  -f query='mutation($repositoryId:ID!, $title:String!, $body:String!, $labelIds:[ID!]) {
-    createIssue(input: {
-      repositoryId: $repositoryId,
-      title: $title,
-      body: $body,
-      labelIds: $labelIds
-    }) {
-      issue { url number }
-    }
-  }' \
-  -F repositoryId="$REPOSITORY_ID" \
-  -f title="$ISSUE_TITLE" \
-  -f body="$ISSUE_BODY"
-```
-
-When labels were selected, append one `-F labelIds[]="$LABEL_ID"` argument per label ID.
-
-9. If GraphQL is rate-limited or unavailable, create the issue with REST:
-
-```bash
-gh api "repos/$OWNER/$REPO/issues" \
-  -f title="$ISSUE_TITLE" \
-  -f body="$ISSUE_BODY" \
-  --jq '.html_url'
-```
-
-When labels were selected, append one `-f labels[]="$LABEL_NAME"` argument per label name.
-
-10. Return the issue URL to the user.
+6. **If the change is UI/UX, also include:**
+   - Affected screens, routes, or components.
+   - Current visual state: screenshot, short recording, or precise description (layout, copy, state).
+   - Expected visual state: screenshot, mock, design link (Figma, etc.), or precise description.
+   - Accessibility expectations: keyboard navigation, focus order, visible focus, ARIA roles/labels, color contrast (target WCAG AA or the project's standard), motion / `prefers-reduced-motion`.
+   - Responsive scope: which breakpoints and devices apply, and which themes (light/dark/system).
+   - Design system or component library in use, and the specific tokens or components involved.
+7. Choose labels by matching existing repo conventions. Use labels (not title prefixes) for area and type. Do not invent labels unless the user asks.
+8. Show the title, labels, and body to the user before creating, unless the user asked to create without review.
+9. Resolve the repository ID, then create the issue with GraphQL:
+
+   ```bash
+   REPOSITORY_ID=$(gh api graphql \
+     -f query='query($owner:String!,$name:String!){repository(owner:$owner,name:$name){id}}' \
+     -f owner="$OWNER" -f name="$REPO" --jq '.data.repository.id')
+
+   gh api graphql \
+     -f query='mutation($repositoryId:ID!, $title:String!, $body:String!, $labelIds:[ID!]) {
+       createIssue(input: {
+         repositoryId: $repositoryId,
+         title: $title,
+         body: $body,
+         labelIds: $labelIds
+       }) {
+         issue { url number }
+       }
+     }' \
+     -F repositoryId="$REPOSITORY_ID" \
+     -f title="$ISSUE_TITLE" \
+     -f body="$ISSUE_BODY"
+   ```
+
+   When labels were selected, append one `-F labelIds[]="$LABEL_ID"` argument per label ID.
+
+10. If GraphQL is rate-limited or unavailable, fall back to REST:
+
+    ```bash
+    gh api "repos/$OWNER/$REPO/issues" \
+      -f title="$ISSUE_TITLE" \
+      -f body="$ISSUE_BODY" \
+      --jq '.html_url'
+    ```
+
+    When labels were selected, append one `-f labels[]="$LABEL_NAME"` argument per label name.
+
+11. Return the issue URL.
diff --git a/.agents/skills/create-pr/SKILL.md b/.agents/skills/create-pr/SKILL.md
@@ -1,60 +1,78 @@
 ---
 name: create-pr
-description: Commit relevant changes, push the branch, and create a GocciaScript pull request using the repository PR template. Use when the user enters /create-pr.
+description: >-
+  Commits relevant local changes, pushes a focused branch, and opens a draft
+  pull request on the current GitHub repository using the project's PR template
+  (single or multi-template). Use when the user runs /create-pr.
+license: Unlicense OR MIT
+compatibility: >-
+  Requires git and the GitHub CLI (gh) authenticated to the target repository,
+  plus network access.
 ---
 
 # Create PR
 
-This command is explicit permission to commit relevant changes, push the branch, and create a pull request.
+## Instructions
 
-## Steps
+Explicit permission to commit relevant changes, push the branch, and open a draft pull request.
 
-1. Inspect the repository state:
+### Steps
+
+1. Inspect the repository:
    - `git status --short --branch`
    - `git diff`
    - `git diff --staged`
    - `git log --oneline -5`
-2. Confirm there are changes to commit. If there are none, stop.
-3. If the current branch is `main`, create a focused branch before committing. Use an issue number or change summary for the branch name when available; otherwise ask the user.
-4. Stage only relevant files. Exclude secrets and unrelated user changes.
-5. Commit with a concise message passed via HEREDOC.
-6. Push the branch with upstream tracking when needed: `git push -u origin HEAD`.
-7. Build the PR body from the repository's pull request template. Read `.github/pull_request_template.md`, or the relevant template under `.github/PULL_REQUEST_TEMPLATE/` if the repository uses multiple templates. Fill the template faithfully and preserve its structure.
-8. Create the pull request as a **draft** with GraphQL first:
-
-```bash
-gh api graphql \
-  -f query='mutation($repositoryId:ID!, $base:String!, $head:String!, $title:String!, $body:String!) {
-    createPullRequest(input: {
-      repositoryId: $repositoryId,
-      baseRefName: $base,
-      headRefName: $head,
-      title: $title,
-      body: $body,
-      draft: true
-    }) {
-      pullRequest { url number }
-    }
-  }' \
-  -F repositoryId="$REPOSITORY_ID" \
-  -f base="$BASE_BRANCH" \
-  -f head="$HEAD_BRANCH" \
-  -f title="$PR_TITLE" \
-  -f body="$PR_BODY"
-```
-
-9. If GraphQL is rate-limited or unavailable, create the pull request as a **draft** with REST:
-
-```bash
-gh api "repos/$OWNER/$REPO/pulls" \
-  -f title="$PR_TITLE" \
-  -f head="$HEAD_BRANCH" \
-  -f base="$BASE_BRANCH" \
-  -f body="$PR_BODY" \
-  -F draft=true \
-  --jq '.html_url'
-```
-
-10. Return the PR URL to the user.
+2. If there is nothing to commit, stop.
+3. Resolve the base branch from the remote default (do not hardcode `main`):
+
+   ```bash
+   BASE_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')
+   ```
+
+4. If the current branch is the base branch, create a focused branch first. Use the issue number or a change summary; ask when ambiguous.
+5. Stage only relevant files. Exclude secrets and unrelated local changes.
+6. Commit with a concise message passed via HEREDOC.
+7. Push with upstream tracking when needed: `git push -u origin HEAD`.
+8. Resolve the PR template:
+   - Read `.github/pull_request_template.md`, or pick the matching template under `.github/PULL_REQUEST_TEMPLATE/` if the repo uses multiple.
+   - If none exists, use a minimal structure: Summary, Testing, Linked issues.
+   - Fill the template faithfully and preserve its structure.
+9. Open as a **draft** via GraphQL first:
+
+   ```bash
+   gh api graphql \
+     -f query='mutation($repositoryId:ID!, $base:String!, $head:String!, $title:String!, $body:String!) {
+       createPullRequest(input: {
+         repositoryId: $repositoryId,
+         baseRefName: $base,
+         headRefName: $head,
+         title: $title,
+         body: $body,
+         draft: true
+       }) {
+         pullRequest { url number }
+       }
+     }' \
+     -F repositoryId="$REPOSITORY_ID" \
+     -f base="$BASE_BRANCH" \
+     -f head="$HEAD_BRANCH" \
+     -f title="$PR_TITLE" \
+     -f body="$PR_BODY"
+   ```
+
+10. If GraphQL is rate-limited or unavailable, fall back to REST as a **draft**:
+
+    ```bash
+    gh api "repos/$OWNER/$REPO/pulls" \
+      -f title="$PR_TITLE" \
+      -f head="$HEAD_BRANCH" \
+      -f base="$BASE_BRANCH" \
+      -f body="$PR_BODY" \
+      -F draft=true \
+      --jq '.html_url'
+    ```
+
+11. Return the PR URL.
 
 Do not skip git hooks or verification unless the user explicitly asks.
diff --git a/.agents/skills/git-workflow/SKILL.md b/.agents/skills/git-workflow/SKILL.md
@@ -0,0 +1,80 @@
+---
+name: git-workflow
+description: >-
+  Default git workflow for the user's repositories: feature branches off the
+  remote default branch, merge (never rebase) to take baseline updates, plain
+  pushes (no --force or --force-with-lease), always-new commits (no amend), and
+  squash-merge for all pull requests. Use when running any git action —
+  branching, syncing, conflict resolution, committing, pushing, or merging — on
+  the user's repos.
+license: Unlicense OR MIT
+compatibility: >-
+  Requires git; pull-request operations also require the GitHub CLI (gh) and
+  network access.
+---
+
+# Git workflow
+
+## Instructions
+
+These are the user's repository defaults. Apply them on every git action unless the user explicitly overrides them in the same turn.
+
+### Rules
+
+- **Squash-merge** every pull request. Never use "Create a merge commit" or "Rebase and merge" on GitHub.
+- **Never rebase.** Use merge to integrate changes — including baseline catch-up and conflict resolution.
+- **Never force push.** Plain `git push` only. No `--force`, no `--force-with-lease`.
+- **Never amend commits.** Always create new commits. `git commit --amend` is forbidden, even for typo fixes, unless the user explicitly asks in the same turn.
+
+### Branching
+
+Resolve the base branch from the remote default — do not hardcode `main`:
+
+```bash
+BASE_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')
+```
+
+- Create focused branches off the base. Name them from the issue or change (e.g. `issue-123-short-slug`, `fix-checkout-validation`).
+- Never commit directly to the base branch.
+
+### Keeping a branch up to date
+
+When the branch is behind the remote base, **merge** the baseline:
+
+```bash
+git fetch origin "$BASE_BRANCH"
+git merge "origin/$BASE_BRANCH" --no-edit
+```
+
+Resolve any conflicts and commit the merge before continuing. Do not `git rebase origin/$BASE_BRANCH`.
+
+### Commits
+
+- Each logical change is its own commit. Use a HEREDOC for multi-line messages so formatting is preserved.
+- Do not amend. If a commit needs a fix-up, add a new commit.
+- Do not skip hooks (`--no-verify`) unless the user explicitly asks.
+
+### Pushing
+
+```bash
+git push                       # routine push
+git push -u origin HEAD        # first push of a new branch
+```
+
+Never `git push --force` or `git push --force-with-lease`. If a remote push is rejected because the histories diverged, stop and ask the user — do not paper over with a force push.
+
+### Merging pull requests
+
+- Always **squash-merge** on GitHub. Edit the squash commit message to a clean summary before confirming the merge.
+- Delete the source branch after the squash-merge (the GitHub option, or local cleanup).
+- After the squash-merge, sync any local working copy that still has the merged branch:
+
+```bash
+git checkout "$BASE_BRANCH"
+git pull origin "$BASE_BRANCH"
+git branch -D <merged-branch>
+```
+
+### Exceptions
+
+Deviate from any rule only when the user explicitly asks in the same turn. State the deviation in chat so it is not silently normalized.