@runfusion/fusion 0.73.0-beta.2 → 0.73.0-beta.4

package/dist/plugins/.fusion-ce-skills/ce-code-review/scripts/cross-model-adversarial-review.sh

@@ -0,0 +1,218 @@
+#!/usr/bin/env bash
+# cross-model-adversarial-review.sh
+#
+# Runs the adversarial review through a DIFFERENT model family (the "peer") in a
+# separate, read-only process, and writes its findings as JSON into the run dir.
+# The peer gets the same canonical adversarial brief the in-process reviewer uses
+# (references/personas/adversarial-reviewer.md) so it is genuinely "the adversarial
+# persona, on a different model."
+#
+# Usage:  cross-model-adversarial-review.sh <peer: codex|claude> <base-ref> <run-dir>
+#   <peer>     codex  -> use Codex (when the host is Claude or Cursor)
+#              claude -> use Claude (when the host is Codex)
+#   <base-ref> the diff base (e.g. a merge-base SHA or branch); the peer reviews
+#              only `git diff <base-ref>` in the current repository
+#   <run-dir>  an existing dir; output is written to <run-dir>/adversarial-<peer>.json
+#
+# Self-locates its sibling reference files via BASH_SOURCE (NOT the CWD, which is
+# the user's project on every host), and derives the repo root from git. The agent
+# only has to pass the three values above.
+#
+# NON-BLOCKING BY DESIGN: every failure logs to stderr and exits 0 without an output
+# file. The cross-model pass is additive and must never fail the review; the caller
+# detects success purely by the presence of <run-dir>/adversarial-<peer>.json.
+
+set -uo pipefail
+
+PEER="${1:-}"
+BASE="${2:-}"
+RUN_DIR="${3:-}"
+
+log()  { printf '[cross-model] %s\n' "$*" >&2; }
+skip() { log "$*"; exit 0; }   # non-blocking: announce reason, exit clean, no output
+
+# --- validate inputs -------------------------------------------------------
+case "$PEER" in codex|claude) ;; *) skip "invalid peer '${PEER:-<empty>}' (want codex|claude); skipping cross-model pass" ;; esac
+[ -n "$BASE" ]                  || skip "no base ref given; skipping"
+[ -n "$RUN_DIR" ] && [ -d "$RUN_DIR" ] || skip "run-dir '${RUN_DIR:-<empty>}' is not a directory; skipping"
+command -v "$PEER" >/dev/null 2>&1 || skip "$PEER CLI not installed; skipping"
+command -v jq      >/dev/null 2>&1 || skip "jq not installed; skipping"
+
+# --- self-locate skill root + canonical sibling files ----------------------
+SKILL_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" || skip "cannot resolve skill root; skipping"
+PERSONA="$SKILL_ROOT/references/personas/adversarial-reviewer.md"
+SCHEMA="$SKILL_ROOT/references/findings-schema.json"
+[ -f "$PERSONA" ] || skip "persona brief not found at $PERSONA; skipping"
+[ -f "$SCHEMA" ]  || skip "findings schema not found at $SCHEMA; skipping"
+
+# --- derive repo root (read-only) ------------------------------------------
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || skip "not inside a git repository; skipping"
+
+OUT="$RUN_DIR/adversarial-$PEER.json"
+PROMPT_FILE="$(mktemp "${TMPDIR:-/tmp}/xmodel-prompt-XXXXXX")"
+PEERLOG="$(mktemp "${TMPDIR:-/tmp}/xmodel-log-XXXXXX")"
+trap 'rm -f "$PROMPT_FILE" "$PEERLOG"' EXIT
+
+# --- compose the peer prompt from the canonical persona (single source) ----
+# The full findings schema is embedded so BOTH peers know every required field
+# (why_it_matters, confidence, evidence, routing) -- Codex gets no --output-schema
+# (its strict mode rejects the permissive draft-07 schema), so the prompt is its
+# only schema signal. Verified to produce complete, schema-shaped findings.
+{
+  cat "$PERSONA"
+  printf '\n\n---\n\n'
+  printf 'This is an authorized review of the maintainer\047s own repository.\n'
+  printf 'Think like an attacker and a chaos engineer: find the ways this change fails in production.\n'
+  printf 'Return ONE JSON object and nothing else (no prose, no code fence) matching this schema:\n\n'
+  cat "$SCHEMA"
+  printf '\n\nSet the top-level "reviewer" field to "adversarial-%s".\n' "$PEER"
+} > "$PROMPT_FILE"
+# Per-peer diff delivery (composed below): codex fetches its own diff inside its
+# read-only sandbox; claude is hard-denied shell (see below), so it gets the diff
+# embedded and needs no git.
+if [ "$PEER" = codex ]; then
+  printf '\nRun: git diff %q — review ONLY the changes in that diff, in this repository (read-only).\n' "$BASE" >> "$PROMPT_FILE"
+else
+  { printf '\nReview ONLY the change below (the output of `git diff %q`). You may Read repository files for context but cannot run shell commands.\n' "$BASE"
+    printf '\n=== BEGIN DIFF ===\n'; git -C "$REPO_ROOT" diff "$BASE"; printf '\n=== END DIFF ===\n'; } >> "$PROMPT_FILE"
+fi
+
+# --- run the peer: idle-timeout for streaming codex, hard cap for claude ----
+# codex exec streams its reasoning to stdout, so a productive long run is allowed to
+# continue and is killed only when its output STALLS for IDLE_SECS (the cross-model
+# "second opinion" idle-timeout pattern), with HARD_SECS as an absolute backstop.
+# claude's --output-format json is single-shot, so it gets a hard cap only.
+#
+# Orphan safety: codex runs in its OWN process group (set -m) and the watchdog reaps the
+# whole group (TERM then KILL) on idle/hard -- we do NOT signal a (g)timeout wrapper for
+# this, because an external kill of (g)timeout forwards only TERM (its -k escalates only
+# on gtimeout's OWN expiry), so a peer that defers SIGTERM could survive `wait` and write
+# $OUT after Stage 5 skipped it. claude keeps the (g)timeout wrapper: it is single-shot
+# and gtimeout's own timeout (with -k) escalates to KILL correctly; perl(alarm) is the
+# fallback when neither (g)timeout exists.
+IDLE_SECS="${CROSS_MODEL_IDLE_SECS:-180}"   # reap codex if its streamed output stalls this long
+HARD_SECS="${CROSS_MODEL_HARD_SECS:-600}"   # absolute ceiling (backstop) for either peer
+TO_BIN="$(command -v gtimeout || command -v timeout || true)"
+
+# Reap a backgrounded job's whole process group: TERM, then KILL after a short grace if
+# anything is still alive. The grace loop tests GROUP liveness (kill -0 on the negative
+# pgid), not just the leader pid -- otherwise a leader that exits while a child defers TERM
+# would let reap() return before the group KILL, leaking the child. Falls back to the bare
+# pid only when group signaling isn't accepted at all.
+reap() {
+  local pid="$1" grp
+  if kill -TERM -- -"$pid" 2>/dev/null; then grp=1; else kill -TERM "$pid" 2>/dev/null; grp=0; fi
+  for _ in 1 2 3 4 5; do
+    if [ "$grp" = 1 ]; then kill -0 -- -"$pid" 2>/dev/null || return 0
+    else kill -0 "$pid" 2>/dev/null || return 0; fi
+    sleep 1
+  done
+  if [ "$grp" = 1 ]; then kill -KILL -- -"$pid" 2>/dev/null; else kill -KILL "$pid" 2>/dev/null; fi
+}
+
+# Run codex in its own process group; stream to PEERLOG; reap the group on idle stall or
+# hard cap. This watchdog owns both bounds and the kill -- no (g)timeout wrapper to signal.
+run_codex() {
+  local prev; case "$-" in *m*) prev=1;; *) prev=0;; esac
+  set -m   # background job becomes a process-group leader (pgid == pid) so reap() kills the tree
+  # Force reasoning output on for THIS subprocess (overriding a user's hide_agent_reasoning
+  # = true), so the streamed reasoning keeps PEERLOG growing and gives the idle watchdog a
+  # liveness signal -- otherwise a long, quiet reasoning phase on a big diff could be
+  # misread as a stall and reaped.
+  codex exec - -C "$REPO_ROOT" -s read-only -o "$OUT" \
+    -c 'model_reasoning_effort="high"' -c 'hide_agent_reasoning=false' < "$PROMPT_FILE" > "$PEERLOG" 2>&1 &
+  local pid=$!
+  [ "$prev" = 0 ] && set +m   # group is already assigned; restoring silences job-control noise
+  local start last=-1 lastchg now size
+  start="$(date +%s)"; lastchg="$start"
+  while kill -0 "$pid" 2>/dev/null; do
+    sleep 5; now="$(date +%s)"; size="$(wc -c <"$PEERLOG" 2>/dev/null || echo 0)"
+    [ "$size" != "$last" ] && { last="$size"; lastchg="$now"; }
+    if [ $(( now - lastchg )) -ge "$IDLE_SECS" ]; then
+      log "codex output idle ${IDLE_SECS}s; reaping peer process group"; reap "$pid"; break
+    fi
+    if [ $(( now - start )) -ge "$HARD_SECS" ]; then
+      log "codex exceeded hard cap ${HARD_SECS}s; reaping peer process group"; reap "$pid"; break
+    fi
+  done
+  wait "$pid" 2>/dev/null || true
+}
+
+log "running $PEER adversarial review against base $BASE (read-only; idle ${IDLE_SECS}s / hard ${HARD_SECS}s)"
+case "$PEER" in
+  codex)
+    run_codex
+    # Fallback: codex's -o write is CLI-level and works under -s read-only, but if it
+    # ever fails to materialize, recover the same JSON from the stdout we already
+    # captured (codex prints the final message to stdout too). Belt-and-suspenders.
+    if { [ ! -s "$OUT" ] || ! jq -e . "$OUT" >/dev/null 2>&1; } && [ -s "$PEERLOG" ] && command -v python3 >/dev/null 2>&1; then
+      python3 - "$PEERLOG" "$OUT" <<'PY' 2>/dev/null && [ -s "$OUT" ] && log "recovered codex JSON from stdout (-o file unavailable)"
+import sys, json
+txt = open(sys.argv[1], encoding="utf-8", errors="replace").read()
+best, depth, start = None, 0, None
+for i, ch in enumerate(txt):
+    if ch == '{':
+        if depth == 0: start = i
+        depth += 1
+    elif ch == '}' and depth > 0:
+        depth -= 1
+        if depth == 0 and start is not None:
+            try:
+                obj = json.loads(txt[start:i+1])
+                if isinstance(obj, dict) and "findings" in obj: best = obj
+            except Exception: pass
+if best is not None: open(sys.argv[2], "w").write(json.dumps(best))
+PY
+    fi
+    ;;
+  claude)
+    # Single-shot output -> hard cap only. Disallowed tools as SEPARATE variadic args
+    # (unambiguous; a single quoted "Edit Write NotebookEdit" is risky since tool names
+    # can contain spaces). We deny the built-in mutators (Edit/Write/NotebookEdit/Bash)
+    # AND `mcp__*` (a user's pre-approved MCP write/deploy tools would otherwise run under
+    # dontAsk) AND `Task` (a subagent would bypass this deny list) -- so the peer stays
+    # read-only even with MCP servers configured. claude can't write a file under those
+    # perms, so it emits the JSON envelope on stdout (captured to PEERLOG); we extract it.
+    if [ -n "$TO_BIN" ]; then
+      "$TO_BIN" -k 10 "$HARD_SECS" claude -p --model opus --permission-mode dontAsk \
+        --disallowedTools Edit Write NotebookEdit Bash Task 'mcp__*' --max-turns 15 --no-session-persistence \
+        --json-schema "$(cat "$SCHEMA")" --output-format json \
+        < "$PROMPT_FILE" > "$PEERLOG" 2>/dev/null \
+        || log "claude exited non-zero or timed out"
+    else
+      perl -e 'alarm shift; exec @ARGV' "$HARD_SECS" claude -p --model opus --permission-mode dontAsk \
+        --disallowedTools Edit Write NotebookEdit Bash Task 'mcp__*' --max-turns 15 --no-session-persistence \
+        --json-schema "$(cat "$SCHEMA")" --output-format json \
+        < "$PROMPT_FILE" > "$PEERLOG" 2>/dev/null \
+        || log "claude exited non-zero or timed out"
+    fi
+    jq -e '.structured_output' "$PEERLOG" > "$OUT" 2>/dev/null \
+      || jq -r '.result // empty' "$PEERLOG" | jq -e '.' > "$OUT" 2>/dev/null \
+      || { log "could not parse Claude output"; rm -f "$OUT"; }
+    ;;
+esac
+
+# --- normalize the reviewer name -------------------------------------------
+# The persona's example JSON uses reviewer:"adversarial"; if the peer echoed that
+# instead of "adversarial-<peer>", Stage 5 would fold it as the in-process reviewer
+# and lose the cross-model agreement signal. Force the distinct name.
+if [ -s "$OUT" ]; then
+  _norm="$(mktemp "${TMPDIR:-/tmp}/xmodel-norm-XXXXXX")"
+  # Force the distinct reviewer name AND satisfy Stage 5's full top-level contract
+  # (reviewer string + findings/residual_risks/testing_gaps arrays). Backfill the two
+  # soft arrays if the peer omitted them; drop the return entirely if findings is not
+  # an array (empty output -> the validation below removes the file -> clean skip).
+  if jq --arg r "adversarial-$PEER" \
+       'if (.findings|type)=="array" then {reviewer:$r, findings, residual_risks:(.residual_risks // []), testing_gaps:(.testing_gaps // [])} else empty end' \
+       "$OUT" > "$_norm" 2>/dev/null; then mv "$_norm" "$OUT"; else rm -f "$_norm"; fi
+fi
+
+# --- validate the output against the Stage 5 reviewer-return contract -------
+if [ -s "$OUT" ] && jq -e '(.reviewer|type=="string") and (.findings|type=="array") and (.residual_risks|type=="array") and (.testing_gaps|type=="array")' "$OUT" >/dev/null 2>&1; then
+  n="$(jq '.findings | length' "$OUT" 2>/dev/null || echo '?')"
+  log "wrote $n finding(s) to $OUT (reviewer adversarial-$PEER)"
+else
+  log "$PEER produced no usable schema-shaped output; skipping fold-in"
+  rm -f "$OUT"
+fi
+exit 0

package/dist/plugins/.fusion-ce-skills/ce-commit/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: ce-commit
+description: Create a git commit with a clear, value-communication message. Use when the user asks to commit/save staged or unstaged changes with a repo-appropriate, value-communicating message.
+---
+
+# Git Commit
+
+Create a single, well-crafted git commit from the current working tree changes.
+
+## Context
+
+**On platforms other than Claude Code**, skip to the "Context fallback" section below and run the command there to gather context.
+
+**In Claude Code**, the five labeled sections below (Git status, Working tree diff, Current branch, Recent commits, Remote default branch) contain pre-populated data. Use them directly throughout this skill -- do not re-run these commands.
+
+**Git status:**
+!`git status`
+
+**Working tree diff:**
+!`git diff HEAD`
+
+**Current branch:**
+!`git branch --show-current`
+
+**Recent commits:**
+!`git log --oneline -10`
+
+**Remote default branch:**
+!`git rev-parse --abbrev-ref origin/HEAD 2>/dev/null || echo '__DEFAULT_BRANCH_UNRESOLVED__'`
+
+### Context fallback
+
+**In Claude Code, skip this section — the data above is already available.**
+
+Run this single command to gather all context:
+
+```bash
+printf '=== STATUS ===\n'; git status; printf '\n=== DIFF ===\n'; git diff HEAD; printf '\n=== BRANCH ===\n'; git branch --show-current; printf '\n=== LOG ===\n'; git log --oneline -10; printf '\n=== DEFAULT_BRANCH ===\n'; git rev-parse --abbrev-ref origin/HEAD 2>/dev/null || echo '__DEFAULT_BRANCH_UNRESOLVED__'
+```
+
+---
+
+## Workflow
+
+### Step 1: Gather context
+
+Use the context above (git status, working tree diff, current branch, recent commits, remote default branch). All data needed for this step is already available -- do not re-run those commands.
+
+The remote default branch value returns something like `origin/main`. Strip the `origin/` prefix to get the branch name. If it returned `__DEFAULT_BRANCH_UNRESOLVED__` or a bare `HEAD`, try:
+
+```bash
+gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'
+```
+
+If both fail, fall back to `main`.
+
+If the git status from the context above shows a clean working tree (no staged, modified, or untracked files), report that there is nothing to commit and stop.
+
+If the current branch from the context above is empty, the repository is in detached HEAD state. Explain that a branch is required before committing if the user wants this work attached to a branch. Ask whether to create a feature branch now. Use the platform's blocking question tool: `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_question` in Antigravity CLI (`agy`), `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to presenting options in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question.
+
+- If the user chooses to create a branch, derive the name from the change content, create it with `git checkout -b <branch-name>`, then run `git branch --show-current` again and use that result as the current branch name for the rest of the workflow.
+- If the user declines, continue with the detached HEAD commit.
+
+### Step 2: Determine commit message convention
+
+Follow this priority order:
+
+1. **Repo conventions already in context** -- If project instructions (AGENTS.md, CLAUDE.md, or similar) are already loaded and specify commit message conventions, follow those. Do not re-read these files; they are loaded at session start.
+2. **Recent commit history** -- If no explicit convention is documented, examine the 10 most recent commits from Step 1. If a clear pattern emerges (e.g., conventional commits, ticket prefixes, emoji prefixes), match that pattern.
+3. **Default: conventional commits** -- If neither source provides a pattern, use conventional commit format: `type(scope): description` where type is one of `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `perf`, `ci`, `style`, `build`.
+
+When using conventional commits, choose the type that most precisely describes the change (the type list above). Where `fix:` and `feat:` both seem to fit, default to `fix:`: a change that remedies broken or missing behavior is `fix:` even when implemented by adding code. Reserve `feat:` for capabilities the user could not previously accomplish. Other types remain primary when they fit better. The user may override for a specific change.
+
+### Step 3: Consider logical commits
+
+Before staging everything together, scan the changed files for naturally distinct concerns. If modified files clearly group into separate logical changes (e.g., a refactor in one directory and a new feature in another, or test files for a different change than source files), create separate commits for each group.
+
+Keep this lightweight:
+- Group at the **file level only** -- do not use `git add -p` or try to split hunks within a file.
+- If the separation is obvious (different features, unrelated fixes), split. If it's ambiguous, one commit is fine.
+- Two or three logical commits is the sweet spot. Do not over-slice into many tiny commits.
+
+### Step 4: Stage and commit
+
+If the current branch from the context above is `main`, `master`, or the resolved default branch from Step 1, automatically create a feature branch before committing. Derive the branch name from the change content, create it with `git checkout -b <branch-name>`, run `git branch --show-current` to confirm, and use the new branch as the current branch for the rest of the workflow. Do not ask whether to branch — committing on the default branch is not an option here.
+
+Write the commit message:
+- **Subject line**: Concise, imperative mood, focused on *why* not *what*. Follow the convention determined in Step 2.
+- **Body** (when needed): Add a body separated by a blank line for non-trivial changes. Explain motivation, trade-offs, or anything a future reader would need. Omit the body for obvious single-purpose changes.
+
+For each commit group, stage and commit in a single call. Prefer staging specific files by name over `git add -A` or `git add .` to avoid accidentally including sensitive files (.env, credentials) or unrelated changes. Use a heredoc to preserve formatting:
+
+```bash
+git add file1 file2 file3 && git commit -m "$(cat <<'EOF'
+type(scope): subject line here
+
+Optional body explaining why this change was made,
+not just what changed.
+EOF
+)"
+```
+
+### Step 5: Confirm
+
+Run `git status` after the commit to verify success. Report the commit hash(es) and subject line(s).

package/dist/plugins/.fusion-ce-skills/ce-commit-push-pr/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: ce-commit-push-pr
+description: Commit, push, and open a PR. Use when asked to ship/open a PR, or for PR-description-only flows like writing, rewriting, or describing a PR body.
+---
+
+# Git Commit, Push, and PR
+
+**Asking the user:** When this skill says "ask the user", use the platform's blocking question tool: `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_question` in Antigravity CLI (`agy`), `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to presenting the question in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question.
+
+## Mode
+
+- **Description-only** — user wants *just* a description ("write/draft a PR description", "describe this PR", or pasted a PR URL/number alone). Run Step 4 only; print the result. Apply only if the user asks. If a PR ref was pasted, pass it to Step 4 so Pre-A resolves the right range.
+- **Description update** — user wants to refresh/rewrite an existing PR's description with no commit/push intent. If no open PR, report and stop. Otherwise run Step 4 (PR mode using the existing PR's URL), then Step 5 to preview, confirm, and apply via `gh pr edit`.
+- **Full workflow** — otherwise. Run Steps 1-5 in order.
+
+## Context
+
+**On platforms other than Claude Code**, run the Context fallback below. **In Claude Code**, the labeled sections contain pre-populated data — use them directly.
+
+**Git status:**
+!`git status`
+
+**Working tree diff:**
+!`git diff HEAD`
+
+**Current branch:**
+!`git branch --show-current`
+
+**Recent commits:**
+!`git log --oneline -10`
+
+**Remote default branch:**
+!`git rev-parse --abbrev-ref origin/HEAD 2>/dev/null || echo 'DEFAULT_BRANCH_UNRESOLVED'`
+
+**Existing PR check:**
+!`gh pr view --json url,title,state 2>/dev/null || echo 'NO_OPEN_PR'`
+
+### Context fallback
+
+```bash
+printf '=== STATUS ===\n'; git status; printf '\n=== DIFF ===\n'; git diff HEAD; printf '\n=== BRANCH ===\n'; git branch --show-current; printf '\n=== LOG ===\n'; git log --oneline -10; printf '\n=== DEFAULT_BRANCH ===\n'; git rev-parse --abbrev-ref origin/HEAD 2>/dev/null || echo 'DEFAULT_BRANCH_UNRESOLVED'; printf '\n=== PR_CHECK ===\n'; gh pr view --json url,title,state 2>/dev/null || echo 'NO_OPEN_PR'
+```
+
+---
+
+## Step 1: Resolve branch and PR state
+
+The remote default branch returns something like `origin/main`; strip the `origin/` prefix. If it returned `DEFAULT_BRANCH_UNRESOLVED` or bare `HEAD`, try `gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'`. If both fail, fall back to `main`.
+
+Branch routing:
+
+- **Detached HEAD** — explain a branch is required and ask whether to create a feature branch. If yes, derive a name from the change content. If no, stop.
+- **On default branch with work to do** (uncommitted, unpushed, or no upstream) — automatically create a feature branch (pushing the default directly is not supported). Derive a name from the change content and continue at Step 3, which handles branch creation safely. Do not ask whether to branch — committing on the default is not an option here.
+- **On default branch with no work** — report no feature branch work and stop.
+- **Feature branch** — continue.
+
+Note the existing PR URL from the PR check if `state: OPEN`. Step 5 uses it to route between new-PR and existing-PR application.
+
+## Step 2: Determine conventions
+
+Match repo style for commit messages and PR titles (project instructions in context > recent commits > conventional commits as default). With conventional commits, default to `fix:` over `feat:` when ambiguous — adding code to remedy broken or missing behavior is `fix:`. Reserve `feat:` for capabilities the user could not previously accomplish. The user may override.
+
+## Step 3: Commit and push
+
+If on the default branch, branch creation needs to handle stale local `<base>`, unpushed commits on local `<base>`, and uncommitted changes that collide with the fresh remote base. Read `references/branch-creation.md` and follow its decision flow before continuing.
+
+Scan changed files for naturally distinct concerns. If they clearly group into separate logical changes, create separate commits (2-3 max). Group at file level only — no `git add -p`. When ambiguous, one commit is fine.
+
+Stage and commit each group. **Avoid `git add -A` and `git add .`** — they sweep in `.env`, build artifacts, and generated files:
+
+```bash
+git add file1 file2 file3 && git commit -m "$(cat <<'EOF'
+commit message here
+EOF
+)"
+```
+
+Then push:
+
+```bash
+git push -u origin HEAD
+```
+
+If the working tree is clean and all commits are already pushed, this step is a no-op.
+
+## Step 4: Compose the PR title and body
+
+**You MUST read `references/pr-description-writing.md`** in full — the core principle at the top governs every step. The only input it needs from this skill is the PR ref, if one was identified by mode dispatch (description-only with a pasted URL, or description update).
+
+**Evidence decision** before composition. CE no longer owns a dedicated capture workflow; modern harnesses provide their own browser, screenshot, terminal recording, and artifact capture tools. Treat evidence as user-supplied context or as validation prose, not as a separate skill dispatch.
+
+1. **User supplied evidence** (URL, markdown image/embed, local artifact path they want referenced) — incorporate it into the PR body as `## Demo`, `## Screenshots`, or `## Evidence`, matching the artifact type. Do not invent or upload evidence.
+2. **User explicitly asks to include evidence but has not supplied it** — ask for the URL/markdown/path, or tell them to use the current harness's capture flow and return with the artifact. Do not launch another CE skill.
+3. **Agent judgment on authored changes** — if you authored the commits and know the change is non-observable (internal plumbing, type-only, backend refactor without user-facing effect, docs/markdown/changelog/CI/test-only, pure refactors), skip evidence handling without asking.
+
+Otherwise, if the branch diff changes observable behavior (UI, CLI output, API behavior with runnable code, generated artifacts, workflow output), include a concise validation note in the PR body describing what was exercised and how it behaved. If no real run was possible because of unavailable credentials, paid services, deploy-only infrastructure, hardware, or missing local setup, say that plainly in the validation section.
+
+Do not block PR creation solely because no visual artifact exists. Test output and manual validation notes are acceptable validation evidence, but do not label test output as "Demo" or "Screenshots."
+
+Then continue with the rest of the reference (Steps A through G) to compose the title and body.
+
+## Step 5: Apply and report
+
+**Description-only mode** — print the title and body. Stop unless the user asks to apply.
+
+**New PR** (full workflow, no existing PR from Step 1) — apply per "Applying via gh" below using `gh pr create`. Report the URL.
+
+**Existing PR** (full workflow, found in Step 1) — the new commits are already on the PR from Step 3. Report the PR URL, then ask whether to rewrite the description.
+
+- **No** — done.
+- **Yes** — run Step 4 if not already done, then preview and apply (see below).
+
+**Description update mode, or existing-PR rewrite confirmed** — preview before applying. Ask: "New title: `<title>` (`<N>` chars). Summary leads with: `<first two sentences>`. Total body: `<L>` lines. Apply?" If declined, the user may pass focus text back for a regenerate; do not apply. If confirmed, apply per "Applying via gh" below using `gh pr edit` and report the URL.
+
+---
+
+## Applying via gh
+
+The body **must** be written to a temp file and passed via `--body-file <path>`. Never use `--body-file -`, stdin pipes, heredoc-to-stdin, or `--body "$(cat ...)"` — wrappers and stdin handling can silently produce an empty PR body while `gh` still exits 0 and returns a URL.
+
+```bash
+BODY_FILE=$(mktemp "${TMPDIR:-/tmp}/ce-pr-body.XXXXXX") && cat >> "$BODY_FILE" <<'__CE_PR_BODY_END__'
+<the composed body markdown goes here, verbatim>
+__CE_PR_BODY_END__
+```
+
+The quoted sentinel keeps `$VAR`, backticks, and any literal `EOF` inside the body from being expanded.
+
+For `<TITLE>`: substitute verbatim. If it contains `"`, `` ` ``, `$`, or `\`, escape them or switch to single quotes.
+
+```bash
+gh pr create --title "<TITLE>" --body-file "$BODY_FILE"   # new PR
+gh pr edit   --title "<TITLE>" --body-file "$BODY_FILE"   # existing PR
+```

package/dist/plugins/.fusion-ce-skills/ce-commit-push-pr/references/branch-creation.md

@@ -0,0 +1,55 @@
+# Branch creation from default branch
+
+Local `<base>` may have stale commits (another session/worktree advanced it) or commits the user authored intending to branch from later. Local git can't distinguish these — ask when unpushed commits are present.
+
+## Decision flow
+
+### 1. Fetch fresh remote base
+
+```bash
+git fetch --no-tags origin <base>
+```
+
+If fetch fails (network, auth, no remote), use the fallback at the bottom.
+
+### 2. Check for unpushed local commits on `<base>`
+
+```bash
+git log origin/<base>..HEAD --oneline
+```
+
+- **Empty output:** set `BASE_REF=origin/<base>` and proceed to step 3.
+- **Non-empty output:** show the commit list and ask (per the "Asking the user" convention in `SKILL.md`):
+
+  > "Local `<base>` has N unpushed commits not on `origin/<base>`. Carry them onto the new feature branch, or leave them on local `<base>`?"
+
+  - **Carry forward** → `BASE_REF=HEAD`. The new branch starts from local HEAD, preserving the commits.
+  - **Leave on `<base>`** → `BASE_REF=origin/<base>`. The new branch starts clean; commits remain on local `<base>`.
+
+  Never default silently — carrying foreign commits into a PR is worse than asking again.
+
+### 3. Create the feature branch
+
+```bash
+git checkout -b <branch-name> "$BASE_REF"
+```
+
+If checkout fails because uncommitted changes would be overwritten, stash and retry:
+
+```bash
+git stash push -u -m "ce-commit-push-pr: pre-branch <branch-name>"
+git checkout -b <branch-name> "$BASE_REF"
+git stash pop
+```
+
+If `git stash pop` reports conflicts, surface the conflict output and the stash ref to the user — do not auto-resolve.
+
+## Fetch failure fallback
+
+If `git fetch` fails, branch from current local HEAD:
+
+```bash
+git checkout -b <branch-name>
+```
+
+Note in the user-facing summary that base freshness was not verified. Skip the unpushed-commits check — without a fresh `origin/<base>`, the answer is unreliable.

package/dist/plugins/.fusion-ce-skills/ce-commit-push-pr/references/pr-description-writing.md

@@ -0,0 +1,115 @@
+# PR Description Writing
+
+## The core principle
+
+The diff is already visible on GitHub. The description exists to explain what the diff cannot show: what was impossible before and is now possible, what was broken and is now fixed, what shape changed. Cut any sentence a reader could reconstruct from the diff itself.
+
+- Bad: "Adds `evidence-decider.ts`, modifies `ce-commit-push-pr/SKILL.md` to call it, and updates two test files."
+- Good: "Evidence capture now decides automatically whether a change has observable behavior. CLI tools and libraries are now eligible alongside web UIs."
+
+If the lead sentence describes what was moved, renamed, or added rather than what's now possible or fixed, rewrite it. This applies to every section, not just the opening — restating the diff is the failure mode this skill exists to prevent.
+
+For user-facing bugs, run an extra before/after pass before writing the mechanism: name what the user would have seen before and what they now see instead. Only then mention the technical cause or fix, and only if it helps the reviewer understand risk. A lead like "Playback hooks now ignore late async responses" is still too mechanical if the visible bug was "old videos, thumbnails, or errors could appear after switching selections."
+
+---
+
+## Step Pre-A: Resolve the range and base
+
+Two modes:
+
+- **Current-branch mode** (default) — describe HEAD vs the repo's default base.
+- **PR mode** — describe a specific PR. Triggered when the caller passes a PR ref.
+
+For PR mode, fetch metadata first:
+
+```bash
+gh pr view <ref> --json baseRefName,headRefOid,url,body,state,isCrossRepository,headRepositoryOwner
+```
+
+If `state` is not `OPEN`, report and stop — do not invent a description. Use `baseRefName` as `<base>` and `headRefOid` as `<head>`.
+
+For current-branch mode, resolve `<base>` in priority order: caller-supplied (`base:<ref>`) → `git rev-parse --abbrev-ref origin/HEAD` (strip `origin/`) → `gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'` → try `main`/`master`/`develop` via `git rev-parse --verify origin/<candidate>`. If none resolve, ask the user. `<head>` is `HEAD`.
+
+**Base remote:** `origin` for current-branch mode and same-repo PRs. For fork PRs, match the PR's base owner/repo against `git remote -v`. If no local remote matches, skip to the `gh` fallback — do not diff against `origin` (wrong base).
+
+```bash
+git fetch --no-tags <base-remote> <base>
+git fetch --no-tags <base-remote> <head>   # PR mode only: <head> is headRefOid and may not be local
+git log  --oneline "<base-remote>/<base>..<head>"
+git diff           "<base-remote>/<base>...<head>"
+```
+
+If the commit list is empty, report "No commits to describe" and stop.
+
+**Fallback** — use `gh pr diff <ref>` and `gh pr view <ref> --json commits` when local git can't reach the refs (fork PR with no matching remote, shallow clone, offline, merge-base on unrelated histories). For GHES configurations that reject SHA fetch but allow `refs/pull/`:
+
+```bash
+git fetch --no-tags <base-remote> "refs/pull/<number>/head"
+PR_HEAD_SHA=$(awk '/refs\/pull\/[0-9]+\/head/ {print $1; exit}' "$(git rev-parse --git-dir)/FETCH_HEAD")
+```
+
+Note in the user-facing summary when the API fallback was used.
+
+---
+
+## Step A: Size the description
+
+Match weight to weight. When in doubt, shorter wins. Subtract fix-up commits (review fixes, lint, rebase resolutions) when sizing — they're invisible to the reader. Large PRs need more selectivity, not more content.
+
+| Change profile | Description approach |
+|---|---|
+| Small + simple (typo, config, dep bump) | 1-2 sentences, no headers. Under ~300 characters. |
+| Small + non-trivial (bugfix, behavioral change) | 3-5 sentences. No headers unless two distinct concerns. |
+| Medium feature or refactor | Narrative frame, then what changed and why. Call out design decisions. |
+| Large or architecturally significant | Narrative frame + 3-5 design-decision callouts + brief test summary. Target ~100 lines, cap ~150. For PRs with many mechanisms, use a Summary table; do not create an H3 per mechanism. |
+| Performance improvement | Include before/after measurements as a markdown table. |
+
+For small + simple PRs, the value-led sentence is the entire description.
+For small + non-trivial bugfixes, the 3-5 sentence target still needs a user-visible before/after lead when the bug affected UI, CLI output, workflow output, or any other user-observable behavior. Concision is not a reason to skip the visible symptom.
+
+---
+
+## Step B: Compose the title
+
+`type: description` or `type(scope): description`.
+
+- Type by intent, not file extension. When `fix` and `feat` both seem to fit, default to `fix` — adding code to remedy missing behavior is `fix`. Reserve `feat` for capabilities the user could not previously accomplish. Use `refactor`/`docs`/`chore`/`perf`/`test` when more precise.
+- Scope (optional): narrowest useful label. Omit when no single label adds clarity.
+- Description: imperative, lowercase, under 72 chars, no trailing period.
+- Match repo conventions visible in recent commits.
+- **Never use `!` or `BREAKING CHANGE:` without explicit user confirmation** — they trigger automated major-version bumps.
+
+---
+
+## Step C: Assemble the body
+
+In order: opening → body sections that earn their keep → test plan if non-obvious → evidence block if one exists → Compound Engineering badge after a `---` rule.
+
+The opening goes under `## Summary` if the body uses any `##` headings; bare paragraph otherwise. No orphaned opening paragraphs above the first heading.
+
+**Evidence handling:** preserve any existing `## Demo` or `## Screenshots` block verbatim unless the user's focus asks to refresh it. If the caller passed a freshly captured URL or path, splice as `## Demo`. Otherwise omit. Place before the badge. Never label test output as "Demo" or "Screenshots."
+
+**Visual aids:** reach for a diagram or table when it conveys the change faster than prose — relationships, flows, state transitions, sequences, trade-offs, before/after data, or any structure prose would have to enumerate. Mermaid and markdown tables cover most shapes; don't be limited to a particular type if a different one fits the change better. Place inline at the point of relevance. Skip for simple, prose-clear, or rename/dep-bump changes. Prose is authoritative when it conflicts with a visual.
+
+**GitHub gotchas:** never prefix list items with `#` (GitHub auto-links `#1` as an issue ref). Use `org/repo#123` or full URL for actual references.
+
+---
+
+## Step D: Badge
+
+```markdown
+---
+
+[![Compound Engineering](https://img.shields.io/badge/Built_with-Compound_Engineering-6366f1)](https://github.com/EveryInc/compound-engineering-plugin)
+![HARNESS](https://img.shields.io/badge/MODEL_SLUG-COLOR?logo=LOGO&logoColor=white)
+```
+
+| Harness | `LOGO` | `COLOR` |
+|---|---|---|
+| Claude Code | `claude` | `D97757` |
+| Codex | (omit `?logo=` param) | `000000` |
+| Antigravity CLI (`agy`) | `googlegemini` | `4285F4` |
+
+**Model slug:** spaces become underscores; append context window and thinking level in parens if known. **URL-encode literal parens as `%28` / `%29`** — unencoded parens inside markdown image URLs break release-please's commit parser, which silently drops the commit from the changelog. Examples: `Opus_4.6_%281M,_Extended_Thinking%29`, `Sonnet_4.6_%28200K%29`, `Gemini_3.1_Pro`.
+
+Skip the badge if regenerating a body that already contains it.