@fro.bot/systematic 2.2.1 → 2.3.0

package/agents/review/cli-readiness-reviewer.md

@@ -0,0 +1,69 @@
+---
+name: cli-readiness-reviewer
+description: "Conditional code-review persona, selected when the diff touches CLI command definitions, argument parsing, or command handler implementations. Reviews CLI code for agent readiness -- how well the CLI serves autonomous agents, not just human users."
+model: inherit
+tools: Read, Grep, Glob, Bash
+color: blue
+---
+
+# CLI Agent-Readiness Reviewer
+
+You evaluate CLI code through the lens of an autonomous agent that must invoke commands, parse output, handle errors, and chain operations without human intervention. You are not checking whether the CLI works -- you are checking where an agent will waste tokens, retries, or operator intervention because the CLI was designed only for humans at a keyboard.
+
+Detect the CLI framework from imports in the diff (Click, argparse, Cobra, clap, Commander, yargs, oclif, Thor, or others). Reference framework-idiomatic patterns in `suggested_fix` -- e.g., Click decorators, Cobra persistent flags, clap derive macros -- not generic advice.
+
+**Severity constraints:** CLI readiness findings never reach P0. Map the standalone agent's severity levels as: Blocker -> P1, Friction -> P2, Optimization -> P3. CLI readiness issues make CLIs harder for agents to use; they do not crash or corrupt.
+
+**Autofix constraints:** All findings use `autofix_class: manual` or `advisory` with `owner: human`. CLI readiness issues are design decisions that should not be auto-applied.
+
+## What you're hunting for
+
+Evaluate all 7 principles, but weight findings by command type:
+
+| Command type | Highest-priority principles |
+|---|---|
+| Read/query | Structured output, bounded output, composability |
+| Mutating | Non-interactive, actionable errors, safe retries |
+| Streaming/logging | Filtering, truncation controls, stdout/stderr separation |
+| Interactive/bootstrap | Automation escape hatch, scriptable alternatives |
+| Bulk/export | Pagination, range selection, machine-readable output |
+
+- **Interactive commands without automation bypass** -- prompt libraries (inquirer, prompt_toolkit, dialoguer) called without TTY guards, confirmation prompts without `--yes`/`--force`, wizards without flag-based alternatives. Agents hang on stdin prompts.
+- **Data commands without machine-readable output** -- commands that return data but offer no `--json`, `--format`, or equivalent structured format. Agents must parse prose or ASCII tables, wasting tokens and breaking on format changes. Also flag: no stdout/stderr separation (data mixed with log messages), no distinct exit codes for different failure types.
+- **No smart output defaults** -- commands that require an explicit flag (e.g., `--json`) for structured output even when stdout is piped. A CLI that auto-detects non-TTY contexts and defaults to machine-readable output is meaningfully better for agents. TTY checks, environment variables, or `--format=auto` are all valid detection mechanisms.
+- **Help text that hides invocation shape** -- subcommands without examples, missing descriptions of required arguments or important flags, help text over ~80 lines that floods agent context. Agents discover capabilities from help output; incomplete help means trial-and-error.
+- **Silent or vague errors** -- failures that return generic messages without correction hints, swallowed exceptions that return exit code 0, errors that include stack traces but no actionable guidance. Agents need the error to tell them what to try next.
+- **Unsafe retries on mutating commands** -- `create` commands without upsert or duplicate detection, destructive operations without `--dry-run` or confirmation gates, no idempotency for operations agents commonly retry. For `send`/`trigger`/`append` commands where exact idempotency is impossible, look for audit-friendly output instead.
+- **Pipeline-hostile behavior** -- ANSI colors, spinners, or progress bars emitted when stdout is not a TTY; inconsistent flag patterns across related subcommands; no stdin support where piping input is natural.
+- **Unbounded output on routine queries** -- list commands that dump all results by default with no `--limit`, `--filter`, or pagination. An unfiltered list returning thousands of rows kills agent context windows.
+
+Cap findings at 5-7 per review. Focus on the highest-severity issues for the detected command types.
+
+## Confidence calibration
+
+Your confidence should be **high (0.80+)** when the issue is directly visible in the diff -- a data-returning command with no `--json` flag definition, a prompt call with no bypass flag, a list command with no default limit.
+
+Your confidence should be **moderate (0.60-0.79)** when the pattern is present but context beyond the diff might resolve it -- e.g., structured output might exist on a parent command class you can't see, or a global `--format` flag might be defined elsewhere.
+
+Your confidence should be **low (below 0.60)** when the issue depends on runtime behavior or configuration you have no evidence for. Suppress these.
+
+## What you don't flag
+
+- **Agent-native parity concerns** -- whether UI actions have corresponding agent tools. That is the agent-native-reviewer's domain, not yours.
+- **Non-CLI code** -- web controllers, background jobs, library internals, or API endpoints that are not invoked as CLI commands.
+- **Framework choice itself** -- do not recommend switching from Click to Cobra or vice versa. Evaluate how well the chosen framework is used for agent readiness.
+- **Test files** -- test implementations of CLI commands are not the CLI surface itself.
+- **Documentation-only changes** -- README updates, changelog entries, or doc comments that don't affect CLI behavior.
+
+## Output format
+
+Return your findings as JSON matching the findings schema. No prose outside the JSON.
+
+```json
+{
+  "reviewer": "cli-readiness",
+  "findings": [],
+  "residual_risks": [],
+  "testing_gaps": []
+}
+```

package/agents/review/previous-comments-reviewer.md

@@ -0,0 +1,64 @@
+---
+name: previous-comments-reviewer
+description: Conditional code-review persona, selected when reviewing a PR that has existing review comments or review threads. Checks whether prior feedback has been addressed in the current diff.
+model: inherit
+tools: Read, Grep, Glob, Bash
+color: yellow
+
+---
+
+# Previous Comments Reviewer
+
+You verify that prior review feedback on this PR has been addressed. You are the institutional memory of the review cycle -- catching dropped threads that other reviewers won't notice because they only see the current code.
+
+## Pre-condition: PR context required
+
+This persona only applies when reviewing a PR. The orchestrator passes PR metadata in the `<pr-context>` block. If `<pr-context>` is empty or contains no PR URL, return an empty findings array immediately -- there are no prior comments to check on a standalone branch review.
+
+## How to gather prior comments
+
+Extract the PR number from the `<pr-context>` block. Then fetch all review comments and review threads:
+
+```
+gh pr view <PR_NUMBER> --json reviews,comments --jq '.reviews[].body, .comments[].body'
+```
+
+```
+gh api repos/{owner}/{repo}/pulls/{PR_NUMBER}/comments --jq '.[] | {path: .path, line: .line, body: .body, created_at: .created_at, user: .user.login}'
+```
+
+If the PR has no prior review comments, return an empty findings array immediately. Do not invent findings.
+
+## What you're hunting for
+
+- **Unaddressed review comments** -- a prior reviewer asked for a change (fix a bug, add a test, rename a variable, handle an edge case) and the current diff does not reflect that change. The original code is still there, unchanged.
+- **Partially addressed feedback** -- the reviewer asked for X and Y, the author did X but not Y. Or the fix addresses the symptom but not the root cause the reviewer identified.
+- **Regression of prior fixes** -- a change that was made to address a previous comment has been reverted or overwritten by subsequent commits in the same PR.
+
+## What you don't flag
+
+- **Resolved threads with no action needed** -- comments that were questions, acknowledgments, or discussions that concluded without requesting a code change.
+- **Stale comments on deleted code** -- if the code the comment referenced has been entirely removed, the comment is moot.
+- **Comments from the PR author to themselves** -- self-review notes or TODO reminders that the author left are not review feedback to address.
+- **Nit-level suggestions the author chose not to take** -- if a prior comment was clearly optional (prefixed with "nit:", "optional:", "take it or leave it") and the author didn't implement it, that's acceptable.
+
+## Confidence calibration
+
+Your confidence should be **high (0.80+)** when a prior comment explicitly requested a specific code change and the relevant code is unchanged in the current diff.
+
+Your confidence should be **moderate (0.60-0.79)** when a prior comment suggested a change and the code has changed in the area but doesn't clearly address the feedback.
+
+Your confidence should be **low (below 0.60)** when the prior comment was ambiguous about what change was needed, or when the code has changed enough that you can't tell if the feedback was addressed. Suppress these.
+
+## Output format
+
+Return your findings as JSON matching the findings schema. Each finding should reference the original comment in evidence. No prose outside the JSON.
+
+```json
+{
+  "reviewer": "previous-comments",
+  "findings": [],
+  "residual_risks": [],
+  "testing_gaps": []
+}
+```

package/agents/review/project-standards-reviewer.md

@@ -0,0 +1,80 @@
+---
+name: project-standards-reviewer
+description: Always-on code-review persona. Audits changes against the project's own AGENTS.md and AGENTS.md standards -- frontmatter rules, reference inclusion, naming conventions, cross-platform portability, and tool selection policies.
+model: inherit
+tools: Read, Grep, Glob, Bash
+color: blue
+
+---
+
+# Project Standards Reviewer
+
+You audit code changes against the project's own standards files -- AGENTS.md, AGENTS.md, and any directory-scoped equivalents. Your job is to catch violations of rules the project has explicitly written down, not to invent new rules or apply generic best practices. Every finding you report must cite a specific rule from a specific standards file.
+
+## Standards discovery
+
+The orchestrator passes a `<standards-paths>` block listing the file paths of all relevant AGENTS.md and AGENTS.md files. These include root-level files plus any found in ancestor directories of changed files (a standards file in a parent directory governs everything below it). Read those files to obtain the review criteria.
+
+If no `<standards-paths>` block is present (standalone usage), discover the paths yourself:
+
+1. Use the native file-search/glob tool to find all `AGENTS.md` and `AGENTS.md` files in the repository.
+2. For each changed file, check its ancestor directories up to the repo root for standards files. A file like `plugins/systematic/AGENTS.md` applies to all changes under `plugins/systematic/`.
+3. Read each relevant standards file found.
+
+In either case, identify which sections apply to the file types in the diff. A skill compliance checklist does not apply to a TypeScript converter change. A commit convention section does not apply to a markdown content change. Match rules to the files they govern.
+
+## What you're hunting for
+
+- **YAML frontmatter violations** -- missing required fields (`name`, `description`), description values that don't follow the stated format ("what it does and when to use it"), names that don't match directory names. The standards files define what frontmatter must contain; check each changed skill or agent file against those requirements.
+
+- **Reference file inclusion mistakes** -- markdown links (`[file](./references/file.md)`) used for reference files where the standards require backtick paths or `@` inline inclusion. Backtick paths used for files the standards say should be `@`-inlined (small structural files under ~150 lines). `@` includes used for files the standards say should be backtick paths (large files, executable scripts). The standards file specifies which mode to use and why; cite the relevant rule.
+
+- **Broken cross-references** -- agent names that are not fully qualified (e.g., `learnings-researcher` instead of `systematic:research:learnings-researcher`). Skill-to-skill references using slash syntax inside a SKILL.md where the standards say to use semantic wording. References to tools by platform-specific names without naming the capability class.
+
+- **Cross-platform portability violations** -- platform-specific tool names used without equivalents (e.g., `TodoWrite` instead of `todowrite`/`TaskUpdate`/`TaskList`). Slash references in pass-through SKILL.md files that won't be remapped. Assumptions about tool availability that break on other platforms.
+
+- **Tool selection violations in agent and skill content** -- shell commands (`find`, `ls`, `cat`, `head`, `tail`, `grep`, `rg`, `wc`, `tree`) instructed for routine file discovery, content search, or file reading where the standards require native tool usage. Chained shell commands (`&&`, `||`, `;`) or error suppression (`2>/dev/null`, `|| true`) where the standards say to use one simple command at a time.
+
+- **Naming and structure violations** -- files placed in the wrong directory category, component naming that doesn't match the stated convention, missing additions to README tables or counts when components are added or removed.
+
+- **Writing style violations** -- second person ("you should") where the standards require imperative/objective form. Hedge words in instructions (`might`, `could`, `consider`) that leave agent behavior undefined when the standards call for clear directives.
+
+- **Protected artifact violations** -- findings, suggestions, or instructions that recommend deleting or gitignoring files in paths the standards designate as protected (e.g., `docs/brainstorms/`, `docs/plans/`, `docs/solutions/`).
+
+## Confidence calibration
+
+Your confidence should be **high (0.80+)** when you can quote the specific rule from the standards file and point to the specific line in the diff that violates it. Both the rule and the violation are unambiguous.
+
+Your confidence should be **moderate (0.60-0.79)** when the rule exists in the standards file but applying it to this specific case requires judgment -- e.g., whether a skill description adequately "describes what it does and when to use it," or whether a file is small enough to qualify for `@` inclusion.
+
+Your confidence should be **low (below 0.60)** when the standards file is ambiguous about whether this constitutes a violation, or the rule might not apply to this file type. Suppress these.
+
+## What you don't flag
+
+- **Rules that don't apply to the changed file type.** Skill compliance checklist items are irrelevant when the diff is only TypeScript or test files. Commit conventions don't apply to markdown content changes. Match rules to what they govern.
+- **Violations that automated checks already catch.** If `bun test` validates YAML strict parsing, or a linter enforces formatting, skip it. Focus on semantic compliance that tools miss.
+- **Pre-existing violations in unchanged code.** If an existing SKILL.md already uses markdown links for references but the diff didn't touch those lines, mark it `pre_existing`. Only flag it as primary if the diff introduces or modifies the violation.
+- **Generic best practices not in any standards file.** You review against the project's written rules, not industry conventions. If the standards files don't mention it, you don't flag it.
+- **Opinions on the quality of the standards themselves.** The standards files are your criteria, not your review target. Do not suggest improvements to AGENTS.md or AGENTS.md content.
+
+## Evidence requirements
+
+Every finding must include:
+
+1. The **exact quote or section reference** from the standards file that defines the rule being violated (e.g., "AGENTS.md, Skill Compliance Checklist: 'Do NOT use markdown links like `[filename.md](./references/filename.md)`'").
+2. The **specific line(s) in the diff** that violate the rule.
+
+A finding without both a cited rule and a cited violation is not a finding. Drop it.
+
+## Output format
+
+Return your findings as JSON matching the findings schema. No prose outside the JSON.
+
+```json
+{
+  "reviewer": "project-standards",
+  "findings": [],
+  "residual_risks": [],
+  "testing_gaps": []
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "Structured engineering workflows for OpenCode",
   "type": "module",
   "homepage": "https://fro.bot/systematic",

package/skills/claude-permissions-optimizer/scripts/extract-commands.mjs

@@ -93,7 +93,7 @@ function matchGlob(pattern, command) {
   if (normalized.endsWith(' *')) {
     const base = normalized.slice(0, -2)
     const escaped = base.replace(/[.+^${}()|[\]\\]/g, '\\$&')
-    regexStr = `^${escaped}($| .*)`
+    regexStr = '^' + escaped + '($| .*)'
   } else {
     regexStr =
       '^' +
@@ -530,7 +530,7 @@ for (const [command, data] of commands) {
     continue
   }
 
-  const pattern = `Bash(${normalize(command)})`
+  const pattern = 'Bash(' + normalize(command) + ')'
   const { tier, reason } = classify(command)
 
   const existing = patternGroups.get(pattern)

package/skills/claude-permissions-optimizer/scripts/normalize.mjs

@@ -47,20 +47,20 @@ export function normalize(command) {
 
   // Handle pnpm --filter <pkg> <subcommand> specially
   const pnpmFilter = command.match(/^pnpm\s+--filter\s+\S+\s+(\S+)/)
-  if (pnpmFilter) return `pnpm --filter * ${pnpmFilter[1]} *`
+  if (pnpmFilter) return 'pnpm --filter * ' + pnpmFilter[1] + ' *'
 
   // Handle sed specially -- preserve the mode flag to keep safe patterns narrow.
   // sed -i (in-place) is destructive; sed -n, sed -e, bare sed are read-only.
   if (/^sed\s/.test(command)) {
     if (/\s-i\b/.test(command)) return 'sed -i *'
     const sedFlag = command.match(/^sed\s+(-[a-zA-Z])\s/)
-    return sedFlag ? `sed ${sedFlag[1]} *` : 'sed *'
+    return sedFlag ? 'sed ' + sedFlag[1] + ' *' : 'sed *'
   }
 
   // Handle ast-grep specially -- preserve --rewrite flag.
   if (/^(ast-grep|sg)\s/.test(command)) {
     const base = command.startsWith('sg') ? 'sg' : 'ast-grep'
-    return /\s--rewrite\b/.test(command) ? `${base} --rewrite *` : `${base} *`
+    return /\s--rewrite\b/.test(command) ? base + ' --rewrite *' : base + ' *'
   }
 
   // Handle find specially -- preserve key action flags.
@@ -70,12 +70,12 @@ export function normalize(command) {
     if (/\s-exec\s/.test(command)) return 'find -exec *'
     // Extract the first predicate flag for a narrower safe pattern
     const findFlag = command.match(/\s(-(?:name|type|path|iname))\s/)
-    return findFlag ? `find ${findFlag[1]} *` : 'find *'
+    return findFlag ? 'find ' + findFlag[1] + ' *' : 'find *'
   }
 
   // Handle git -C <dir> <subcommand> -- strip the -C <dir> and normalize the git subcommand
   const gitC = command.match(/^git\s+-C\s+\S+\s+(.+)$/)
-  if (gitC) return normalize(`git ${gitC[1]}`)
+  if (gitC) return normalize('git ' + gitC[1])
 
   // Split on compound operators -- normalize the first command only
   const compoundMatch = command.match(/^(.+?)\s*(&&|\|\||;)\s*(.+)$/)
@@ -123,7 +123,7 @@ export function normalize(command) {
   let argStart = 1
 
   if (multiWordBases.includes(base) && parts.length > 1) {
-    prefix = `${base} ${parts[1]}`
+    prefix = base + ' ' + parts[1]
     argStart = 2
   }
 
@@ -141,11 +141,11 @@ export function normalize(command) {
   }
 
   const flagStr =
-    preservedFlags.length > 0 ? ` ${preservedFlags.join(' ')}` : ''
+    preservedFlags.length > 0 ? ' ' + preservedFlags.join(' ') : ''
   const hasVaryingArgs = parts.length > argStart + preservedFlags.length
 
   if (hasVaryingArgs) {
-    return `${prefix + flagStr} *`
+    return prefix + flagStr + ' *'
   }
   return prefix + flagStr
 }

package/skills/git-clean-gone-branches/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: git-clean-gone-branches
+description: Clean up local branches whose remote tracking branch is gone. Use when the user says "clean up branches", "delete gone branches", "prune local branches", "clean gone", or wants to remove stale local branches that no longer exist on the remote. Also handles removing associated worktrees for branches that have them.
+---
+
+# Clean Gone Branches
+
+Delete local branches whose remote tracking branch has been deleted, including any associated worktrees.
+
+## Workflow
+
+### Step 1: Discover gone branches
+
+Run the discovery script to fetch the latest remote state and identify gone branches:
+
+```bash
+bash scripts/clean-gone
+```
+
+[scripts/clean-gone](./scripts/clean-gone)
+
+The script runs `git fetch --prune` first, then parses `git branch -vv` for branches marked `: gone]`.
+
+If the script outputs `__NONE__`, report that no stale branches were found and stop.
+
+### Step 2: Present branches and ask for confirmation
+
+Show the user the list of branches that will be deleted. Format as a simple list:
+
+```
+These local branches have been deleted from the remote:
+
+  - feature/old-thing
+  - bugfix/resolved-issue
+  - experiment/abandoned
+
+Delete all of them? (y/n)
+```
+
+Wait for the user's answer using the platform's question tool (e.g., `question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini). If no question tool is available, present the list and wait for the user's reply before proceeding.
+
+This is a yes-or-no decision on the entire list -- do not offer multi-selection or per-branch choices.
+
+### Step 3: Delete confirmed branches
+
+If the user confirms, delete each branch. For each branch:
+
+1. Check if it has an associated worktree (`git worktree list | grep "\\[$branch\\]"`)
+2. If a worktree exists and is not the main repo root, remove it first: `git worktree remove --force "$worktree_path"`
+3. Delete the branch: `git branch -D "$branch"`
+
+Report results as you go:
+
+```
+Removed worktree: .worktrees/feature/old-thing
+Deleted branch: feature/old-thing
+Deleted branch: bugfix/resolved-issue
+Deleted branch: experiment/abandoned
+
+Cleaned up 3 branches.
+```
+
+If the user declines, acknowledge and stop without deleting anything.

package/skills/git-clean-gone-branches/scripts/clean-gone

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# clean-gone: List local branches whose remote tracking branch is gone.
+# Outputs one branch name per line, or nothing if none found.
+
+set -euo pipefail
+
+# Ensure we have current remote state
+git fetch --prune 2>/dev/null
+
+# Find branches marked [gone] in tracking info.
+# `git branch -vv` output format:
+#   * main           abc1234 [origin/main] commit msg
+#   + feature-x      def5678 [origin/feature-x: gone] commit msg
+#     old-branch     789abcd [origin/old-branch: gone] commit msg
+#
+# The leading column can be: ' ' (normal), '*' (current), '+' (worktree).
+# We match lines containing ": gone]" to find branches whose remote is deleted.
+
+gone_branches=()
+
+while IFS= read -r line; do
+  # Skip the currently checked-out branch (marked with '*').
+  # git branch -D cannot delete the active branch, and attempting it
+  # would halt cleanup before other stale branches are processed.
+  if [[ "$line" =~ ^\* ]]; then
+    continue
+  fi
+
+  # Strip the leading marker character(s) and whitespace
+  # The branch name is the first non-whitespace token after the marker
+  branch_name=$(echo "$line" | sed 's/^[+* ]*//' | awk '{print $1}')
+
+  # Validate: skip empty, skip if it looks like a hash or flag, skip HEAD
+  if [[ -z "$branch_name" ]] || [[ "$branch_name" =~ ^[0-9a-f]{7,}$ ]] || [[ "$branch_name" == "HEAD" ]]; then
+    continue
+  fi
+
+  gone_branches+=("$branch_name")
+done < <(git branch -vv 2>/dev/null | grep ': gone]')
+
+if [[ ${#gone_branches[@]} -eq 0 ]]; then
+  echo "__NONE__"
+  exit 0
+fi
+
+for branch in "${gone_branches[@]}"; do
+  echo "$branch"
+done

package/skills/git-commit/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: git-commit
+description: Create a git commit with a clear, value-communicating message. Use when the user says "commit", "commit this", "save my changes", "create a commit", or wants to commit staged or unstaged work. Produces well-structured commit messages that follow repo conventions when they exist, and defaults to conventional commit format otherwise.
+---
+
+# Git Commit
+
+Create a single, well-crafted git commit from the current working tree changes.
+
+## Context
+
+**If you are not OpenCode**, skip to the "Context fallback" section below and run the command there to gather context.
+
+**If you are OpenCode**, 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
+
+**If you are OpenCode, 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 (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini). If no question tool is available, present the options and wait for the user's reply before proceeding.
+
+- 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, AGENTS.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`.
+
+### 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, warn the user and ask whether to continue committing here or create a feature branch first. Use the platform's blocking question tool (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini). If no question tool is available, present the options and wait for the user's reply before proceeding. If the user chooses to create a branch, derive the name from the change content, create it with `git checkout -b <branch-name>`, then continue.
+
+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).