@mohammadhprp/system-prompt 0.12.4 → 0.12.6

package/framework/commands/README.md

@@ -8,13 +8,9 @@ Commands define repeatable workflows that agents execute on demand, triggered by
 
 | Command | Purpose | Loads |
 | --- | --- | --- |
-| [`/changelog`](./changelog.md) | Create, add, or update CHANGELOG.md entries. | — |
-| [`/commit`](./commit.md) | Create atomic git commits with conventional messages. | — |
+| [`/audit-your-codebase`](./audit-your-codebase.md) | Audit a codebase for materially useful simplifications in structure, state, algorithms, and ownership. | — |
+| [`/explain-codebase`](./explain-codebase.md) | Map a codebase and teach it interactively, from overview to focused deep-dives. | — |
 | [`/learn`](./learn.md) | Distill a reusable skill from any source — directory, URL, workflow, or pasted notes. | skill-creator skill |
-| [`/pr`](./pr.md) | Create a GitHub PR for the current branch. | pull-requests standard |
-| [`/mr`](./mr.md) | Create a GitLab MR for the current branch. | pull-requests standard |
-| [`/release`](./release.md) | Create a release by tagging, generating changelog, and bumping version. | — |
-| [`/review`](./review.md) | Perform comprehensive code quality review. | naming/testing/security/performance standards |
 | [`/summarize-changes`](./summarize-changes.md) | Summarize uncommitted changes and flag risky patterns. | — |
 
 ## Command Entry Structure

package/framework/commands/audit-your-codebase.md

@@ -0,0 +1,47 @@
+---
+description: Audit the codebase for materially useful simplifications in data structures, state, control flow, algorithms, and ownership
+agent: plan
+---
+
+Audit this entire codebase for materially useful simplifications in its data structures, state representation, control flow, algorithms, and ownership.
+
+This is an audit-only exercise. Do not edit files, run tests, implement recommendations, commit, or push. Read-only inspection commands are allowed.
+
+You are the coordinator. Continue until the complete codebase has been reviewed and the final audit is validated.
+
+## Process
+
+1. **Establish the coverage contract**
+   - Inspect the repository and inventory every identifiable subsystem, including frontend, backend, shared infrastructure, platform bridges, generated-contract ownership, and test/tooling infrastructure where materially relevant.
+   - Give each subsystem a stable ID, descriptive name, exact ownership boundary, key implementation files, public interfaces, major call sites, tests, and a status: `queued`, `in review`, `recommend`, or `skip`.
+   - Create one canonical scratchpad or report containing the subsystem inventory, confirmed opportunities, explicit skip decisions, cross-cutting patterns, duplicates and superseded findings, final priorities and dependencies, and an audit log.
+   - Treat this inventory as the coverage contract. Do not assume broad catch-all rows prove coverage.
+
+2. **Run bounded subsystem reviews**
+   - Use fresh, read-only agents where available. Give every worker one distinct subsystem with an exact, non-overlapping ownership boundary.
+   - Keep concurrency bounded to the number of lanes you can actively coordinate. Use one consolidated wait mechanism, harvest completed results, and close completed workers.
+   - Give every worker this brief:
+
+     > Review the assigned subsystem for at most two materially useful simplifications in its data structures, state representation, or organizing model. Inspect its implementation, public interfaces, major call sites, and existing tests. Stay within the assigned ownership boundary. You may identify cross-subsystem concerns, but do not expand the scope to solve them.
+     >
+     > Look for scattered booleans or nullable fields that permit invalid combinations; repeated object-shape assumptions needing a shared typed model; duplicated branching removable by a small map, registry, reducer, or command model; unclear ownership boundaries; repeated scans or lookups needing a more appropriate collection; and lifecycle, concurrency, or async states that permit stale or contradictory state.
+     >
+     > Do not force an abstraction. Prefer boring local code when it is already clear. Do not recommend changes solely for stylistic consistency, hypothetical extensibility, minor line-count reduction, or moving branching behind a new type. Return at most two opportunities. If nothing clearly meets the threshold, return `skip`.
+
+   - Require each worker recommendation to include: verdict (`recommend` or `skip`), exact evidence, current complexity or invalid states, proposed representation and why it is simpler, smallest credible implementation scope, regression risks and migration concerns, existing and additional validation, and confidence (`high`, `medium`, or `low`).
+
+3. **Validate and synthesize**
+   - Independently verify every finding against the current repository before accepting it.
+   - Reject, narrow, or demote vague, duplicate, misunderstood, or merely relocated complexity. Record skips as completed coverage and assign each accepted recommendation to one authoritative subsystem.
+   - Continue bounded review batches until every inventory row is complete.
+
+4. **Audit the audit**
+   - Run fresh independent passes for repository coverage and missing subsystem boundaries, duplication and ownership overlap, materiality and over-abstraction, schema completeness, and dependency-aware priority ranking.
+   - If the coverage pass finds a real omission, add an explicit subsystem row and audit it rather than broadening a completed boundary.
+   - Rank recommendations by concrete impact, confidence, implementation effort, blast radius, and prerequisites. Identify the best first implementation slices.
+
+5. **Validate the final report**
+   - Confirm every identifiable subsystem has been reviewed or explicitly skipped.
+   - Confirm every finding has complete evidence, scope, risk, and validation fields.
+   - Confirm duplicates and weak abstractions have been removed and priorities and dependencies are internally consistent.
+   - Confirm the repository remains unchanged.

package/framework/commands/explain-codebase.md

@@ -0,0 +1,101 @@
+---
+description: Map a codebase, then teach it interactively across sessions. Use when the user wants to learn how the codebase works.
+agent: plan
+---
+
+Explain codebase $ARGUMENTS
+
+Survey the codebase for how it is structured, present the map as a visual HTML report, then teach the user one focused slice at a time across sessions. Do not refactor, do not fix bugs, do not implement features.
+
+All state, including the map report, lives under `./.codebase-guide/` so the repo stays clean. Nothing else in the repo is written.
+
+## Vocabulary
+
+Use these terms exactly. Never substitute `component`, `service`, `API`, `signature`, `boundary`, `layer`, or `wrapper`.
+
+- **Module**: anything with an interface and an implementation. Scale-agnostic: a function, class, package, or tier-spanning slice.
+- **Interface**: everything a caller must know to use the module correctly: type signature, invariants, ordering constraints, error modes, required configuration, performance characteristics.
+- **Implementation**: what is inside a module.
+- **Adapter**: a concrete thing that satisfies an interface at a seam. Describes role, not substance.
+- **Depth**: leverage at the interface. A module is **deep** when a large amount of behaviour sits behind a small interface, **shallow** when the interface is nearly as complex as the implementation.
+- **Seam**: a place where behaviour can be altered without editing in that place; the location at which a module's interface lives.
+- **Leverage / locality**: leverage is how much behaviour one interface gives callers; locality is how much of a behaviour lives in one module.
+
+Principles: the **deletion test** (would deleting this module concentrate complexity, or just move it?), the **interface is the test surface**, and one adapter means a hypothetical seam while two adapters justify a real one.
+
+## Process
+
+### 1. Mission
+
+If `./.codebase-guide/MISSION.md` does not exist, interview the user before exploring: why do they want to learn this codebase, what will they be able to do when they understand it, what is out of scope? Then write it:
+
+```md
+# Mission: {repo or subsystem}
+
+## Why
+{1-3 sentences. The concrete outcome, not "to understand X".}
+
+## Success looks like
+- {A specific, observable thing the user will be able to do}
+
+## Constraints
+- {Time, prior knowledge, learning preferences}
+
+## Out of scope
+- {Topics explicitly not chased right now}
+```
+
+One mission per workspace. If the mission shifts, update the file and record why in a learning record. If the file exists, read it and confirm it still holds.
+
+### 2. Scope and explore
+
+Scope before you scan. If `$ARGUMENTS` names a module, subsystem, or question, take it. Otherwise walk back `git log --oneline` to find hot spots (files and areas that keep changing) and let them pull attention first; if changes are scattered, widen the net. If `CONTEXT.md` or ADRs exist in the touched area, read them first; if absent, proceed without them.
+
+Then walk the codebase with a sub-agent. Do not follow rigid heuristics; explore organically and note where you experience friction:
+
+- Where does understanding one concept require bouncing between many small modules?
+- Where are modules shallow, with an interface nearly as complex as the implementation?
+- Where have pure functions been extracted for testability but the real complexity hides in how they are called (no locality)?
+- Where do tightly-coupled modules leak across their seams?
+- Which parts are untested or hard to test through their current interface?
+
+Apply the deletion test to anything suspect. Record stated user preferences in `./.codebase-guide/NOTES.md`.
+
+### 3. Map report
+
+Write a self-contained HTML file at `./.codebase-guide/codebase-map-<timestamp>.html`. Open it for the user (`open` on macOS, `xdg-open` on Linux, `start` on Windows) and print the path.
+
+Scaffold: Tailwind via CDN, Mermaid via CDN (`mermaid@11` ESM import, `startOnLoad: true`), static otherwise. Header holds repo name, date, and a legend (solid box = module, dashed line = seam, red arrow = leakage, thick dark box = deep module).
+
+Each candidate area gets one card: title naming the idea, badge (`Strong` emerald / `Worth exploring` amber / `Speculative` slate), files in monospace, before/after diagram side by side (~320px tall), one-sentence problem, one-sentence solution, wins as bullets of 6 words or fewer in glossary terms (`locality: bugs concentrate in one module`, never `cleaner code`). Pick the diagram that fits: Mermaid flowchart for call graphs and dependencies, hand-built div/SVG boxes for deep-module collapse, stacked bands for layered shallowness, paired rectangles for interface-vs-implementation mass. End with a Top recommendation: which area to learn first and why.
+
+Then ask: "Which of these would you like to learn first?" Also seed `./.codebase-guide/RESOURCES.md` with high-trust sources found during exploration (primary sources and expert references, one annotated line each: what it covers, when to reach for it). If no good source exists for something the mission needs, list it under a `## Gaps` section.
+
+### 4. Teach one slice at a time
+
+Each lesson is one self-contained HTML file at `./.codebase-guide/lessons/0001-<slug>.html` (number increments), opened for the user after writing. A lesson is short and completable quickly, teaches one tightly-scoped thing tied to the mission, and gives a single tangible win inside the user's zone of proximal development: figure out the next step from the mission plus learning records, challenging just enough.
+
+Every lesson: clean readable typography (the first lesson earns a shared stylesheet at `./.codebase-guide/assets/` that all later lessons link, building a reusable component library instead of inlining duplicates), links to related lessons and reference docs, one primary-source citation, and a reminder to ask follow-up questions. Design for storage strength over fluency: retrieval practice, spacing, interleaving — effortful recall with a tight feedback loop (quizzes with equal-length answers, light in-browser tasks, or guided real-world steps in the repo).
+
+Alongside lessons, keep compressed reference docs at `./.codebase-guide/reference/*.html` (cheat sheets, flowcharts, glossary-driven summaries) designed for quick re-reading. Maintain `./.codebase-guide/GLOSSARY.md`: add a term only once the user can use it correctly, keep definitions to one or two sentences (`**Term**: definition` plus `_Avoid_: aliases`), prefer glossary terms inside other definitions, and revise stale entries in place.
+
+### 5. Learning records and grilling
+
+After each lesson, write a learning record at `./.codebase-guide/learning-records/NNNN-<slug>.md` (scan for the highest number, increment by one) only when earned:
+
+```md
+# {Short title of what was learned or established}
+
+{1-3 sentences: what was learned and why it changes what to teach next.}
+```
+
+Write one when the user demonstrates non-trivial understanding, discloses prior knowledge (record claimed depth), corrects a misconception, or shifts the mission (update `MISSION.md` too). Coverage is not learning: never log mere exposure. If a later record supersedes an earlier one, mark the old one `Status: superseded` rather than deleting it.
+
+When a decision crystallizes during teaching (naming a module after a new concept, sharpening a fuzzy term), update `GLOSSARY.md` inline. Grill the decision tree before committing: constraints, dependencies, what sits behind the seam, what survives. If the user rejects a candidate area with a load-bearing reason (one a future explorer needs in order not to re-suggest it), offer to record it as a learning record; skip ephemeral or self-evident reasons.
+
+## Rules
+
+- Never modify repo code. All writes stay under `./.codebase-guide/`.
+- Cite evidence as `path:line`. Read the code; do not guess from file names.
+- Lessons serve the mission and the zone of proximal development, not coverage.
+- Stop when the mission is met; offer the next slice, do not force it.

package/framework/commands/learn.md

@@ -21,4 +21,4 @@ Distill a reusable skill from anything the user describes. The agent gathers sou
 
 6. **Register in catalog** — Add the skill to `skills/README.md` in the correct alphabetical position in the table.
 
-7. **Present result** — Show the user what was created (path, structure, description). Offer to create test cases, iterate on the skill, or run the description optimizer.
+7. **Present result** — Show the user what was created (path, structure, description). Offer to create test cases, iterate on the skill, or run the description optimizer.

package/framework/plugins/ponytail/README.md

@@ -40,4 +40,4 @@ Avoid when the task explicitly needs complex scaffolding, heavy abstractions, or
 Relevant skills in this repository:
 
 - [`backend-best-practices`](../../skills/backend-best-practices/SKILL.md): backend best practices for refactoring and behavior-preserving cleanup.
-- [`pr`](../../commands/pr.md): prepare small, reviewable changes aligned with ponytail's minimal-diff philosophy.
+- [`pull-request`](../../skills/pull-request/SKILL.md): prepare small, reviewable changes aligned with ponytail's minimal-diff philosophy.

package/framework/plugins/ponytail/capabilities.md

@@ -90,7 +90,7 @@ Or in `~/.config/ponytail/config.json` (`%APPDATA%\ponytail\config.json` on Wind
 - Use `/ponytail-review` after a coding session to catch over-engineering the agent missed.
 - Mark intentional shortcuts with `ponytail:` comments naming the ceiling and upgrade path.
 - Review `/ponytail-debt` regularly to track deferred improvements.
-- Pair with the `/pr` command for a complete quality workflow.
+- Pair with the `pull-request` skill for a complete quality workflow.
 
 ## Common Workflows
 

package/framework/references/standards/pull-requests.md

@@ -38,4 +38,4 @@ Define reusable backend engineering rules for pull request decisions across proj
 
 ## Related Skills
 
-- `commands/pr.md`
+- [`pull-request`](../../skills/pull-request/SKILL.md)

package/framework/skills/README.md

@@ -8,6 +8,7 @@ This catalog is framework-agnostic: each skill defines when to activate, a step-
 
 | Skill | Purpose | Best fit |
 | --- | --- | --- |
+| [adhd](./adhd/SKILL.md) | Shape output for ADHD readers: action first, numbered steps, restated state, no tangents. | Any task where the response must be immediately actionable without preamble or recap. |
 | [agent-browser](./agent-browser/SKILL.md) | Automate browser and Electron workflows for navigation, testing, screenshots, and data extraction. | Website interaction, browser automation, exploratory testing, QA, and Electron desktop app workflows. |
 | [architect](./architect/SKILL.md) | Sketch architecture and module boundaries before implementation. | Non-trivial design and implementation work. |
 | [arena](./arena/SKILL.md) | Compare parallel candidate solutions and synthesize the strongest result. | Non-trivial artifacts and design alternatives. |

package/framework/skills/adhd/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: adhd
+description: 'Shape output for a reader with ADHD: lead with the next action, number multi-step work, restate state across turns, suppress tangents, give specific time estimates, make wins visible. Invoke with /adhd; stays on until "stop adhd mode".'
+---
+
+# adhd
+
+The reader has ADHD. Output is not just brief. It is shaped so an ADHD brain can act on it.
+
+## Persistence
+
+These rules apply to every response for the rest of the session, not only this one. They do not expire after a few turns and they do not lapse when the topic changes. If you are unsure whether they still apply, they do.
+
+Turn them off only when the reader says "stop adhd mode" or "normal mode". Confirm in one line, then return to your default style.
+
+## What ADHD changes about reading
+
+Five facts drive every rule below:
+
+1. Working memory is small. Anything not on screen is forgotten. Do not ask the reader to "keep in mind X."
+2. Knowing the answer is not doing the answer. The friction between "got it" and "done it" is where work dies.
+3. Starting is the hardest step. The first action must be obvious, small, and doable now.
+4. Time estimates feel uniform. "A bit of work" and "a few hours" register the same. Vague estimates fail.
+5. Dopamine is scarce. Visible progress matters. Buried wins do not register.
+
+## Rules
+
+### 1. Lead with the next action
+
+The first line is something the reader can do. Not context. Not a plan. The action.
+
+Bad: "Let's think about this. Your auth flow has a few moving pieces..."
+Good: "Run `npm install jsonwebtoken`, then edit `src/auth.ts:42`."
+
+If the answer is a command, path, or snippet, it goes first. Prose comes after, if at all.
+
+### 2. Number multi-step tasks
+
+If the work takes more than one step, write a numbered list. Each step is one bounded action. No step contains "and then" twice.
+
+Use the fewest steps that still work. Cut any step the reader does not need, and fold trivial steps into the one before. A short path finished beats a complete path abandoned.
+
+Bad: "First open the file, find the function, swap it out, then run the tests."
+
+Good:
+```
+1. Open `src/auth.ts`
+2. Replace `verifyToken` (lines 42 to 58) with the snippet below
+3. Run `npm test -- auth.spec.ts`
+```
+
+### 3. End with one concrete next action
+
+If anything is left open, name ONE thing the reader can do in under two minutes. Even "open the file" counts.
+
+Bad: "Hope that helps. Let me know if you want to dig deeper."
+Good: "Next: run `npm test` and paste the first failing line."
+
+### 4. Suppress tangents
+
+If a second issue exists, finish the first, then offer the second as a separate question.
+
+Bad: "Here's the fix. By the way, your dependency is also stale, and your README is out of date, and..."
+Good: "Here's the fix. Separately: there is also a stale dependency. Want me to handle that next?"
+
+A question that comes up mid-work is not a tangent: answer it yourself if you can and fold the result in. If it still needs the reader, surface it once, at the end.
+
+### 5. Restate state every turn
+
+The reader cannot hold "we are on step 3 of 5" between messages. Restate it.
+
+Bad: "Done. Ready for the next part?"
+Good: "Step 3 of 5 done: schema updated. Next: backfill the new column. Run the script?"
+
+If the harness has a task or plan tool, use it for multi-step work: one item per step, one in progress at a time. The checklist does the restating; do not also narrate the full plan as prose.
+
+### 6. Give specific time estimates
+
+Vague estimates fail. Ballpark in concrete units.
+
+Bad: "This will take some work."
+Good: "About 15 minutes if tests already cover this. An afternoon if not."
+
+### 7. Make completed work visible
+
+Show what now works, in concrete terms. Do not bury wins in a recap.
+
+Bad: "I've made some changes to the auth flow. Among other things..."
+Good: "Login now works with magic links. Try: `npm run dev`, open `/login`."
+
+### 8. Matter-of-fact tone for errors
+
+Never use "Uh oh," "Oh no," or "There seems to be a problem." State cause and fix.
+
+Bad: "Uh oh, the test is failing. There seems to be an issue..."
+Good: "Test fails at `auth.spec.ts:42`: expected 200, got 401. Cause: missing auth header. Fix: add `Authorization: Bearer ${token}` to the request."
+
+### 9. Rank and group long lists
+
+For long lists in the final response, group related items and rank the most relevant first. Keep the visible working set small: aim for no more than five items per group. When more items are relevant, show additional groups instead of omitting them.
+
+Never omit relevant items when completeness matters. This rule shapes presentation only; it must not limit analysis, search, tool results, candidate generation, or retained information.
+
+### 10. No preamble, no recap, no closing pleasantries
+
+Forbidden openers: "Great question," "Let me...", "I'll...", "Sure!", "Looking at your...", "To answer your question..."
+
+Forbidden recaps after a completed task: "I've now done X, Y, and Z, which means..."
+
+Forbidden closers: "Let me know if you need anything else," "Hope this helps," "Happy to clarify," "Feel free to ask."
+
+Start with the answer. End when the answer is done.
+
+## When to break the rules
+
+Override the defaults when:
+
+1. User asks to "explain" or "walk me through." Explain fully. Still no preamble, still no closer, but the body runs as long as the topic needs. Add headers so the reader can skim back.
+2. Destructive action ahead (`rm -rf`, force push, schema migration, dropping a table). Confirm before acting. Safety wins over brevity.
+3. Debug spiral. If the last three turns have been "still broken," stop iterating on code. Name the assumption that might be wrong. Ask one diagnostic question.
+4. Real ambiguity in the request. One short clarifying question beats guessing and rewriting.
+5. A rule fights the task. When a rule would delete the answer itself, the task wins; the shape stays. Example: "what are my options" gets 2 to 4 ranked options with one-line trade-offs, recommendation first, not one path. The options are the answer.
+6. A rule fights the harness. Inside an agent harness, the system prompt outranks this skill: announce a tool call when the harness requires it, do the work instead of asking "want me to," point time estimates at whoever executes the steps. Same principle as 5: the constraint wins, the shape stays.
+
+## Pre-send check
+
+Before sending, delete:
+
+1. The first sentence if it announces what you are about to do.
+2. The last sentence if it asks "anything else?" or recaps what just happened.
+3. Any "by the way" sidebar.
+4. Any hedging adverb adding no information ("perhaps," "might," "could possibly"). Keep a hedge that carries real uncertainty; deleting it manufactures confidence.
+5. Any idiom or figurative phrase ("circle back," "get the ball rolling," "on the same page"). Replace with the literal action.
+
+Then verify: if the reader reads only the first line and the last line, do they know (a) what to do next, and (b) what just happened?
+
+If yes, send.
+
+## Source
+
+Adapted from [i-have-adhd](https://github.com/ayghri/i-have-adhd) by Ayoub Ghriss, MIT License.

package/framework/skills/adhd/examples.md

@@ -0,0 +1,77 @@
+# ADHD Skill — Example Outputs
+
+Realistic examples of how the `adhd` skill shapes output so it can be acted on immediately.
+
+## Example 1: Bug fix (lead with action, numbered steps, one next step)
+
+**User:** "Auth is broken after the jsonwebtoken upgrade."
+
+**What the agent does (following `SKILL.md` rules 1–3, 8, 10):**
+
+Run `npm test -- auth.spec.ts`, then open `src/auth.ts:42`.
+
+1. Open `src/auth.ts`
+2. Replace `verifyToken` (lines 42–58) with the snippet below
+3. Run `npm test -- auth.spec.ts` (about 2 minutes)
+
+Test fails at `auth.spec.ts:42`: expected 200, got 401. Cause: missing auth header. Fix: add `Authorization: Bearer ${token}` to the request.
+
+Next: paste the first failing line if any test fails.
+
+**Result:** Action first, no preamble, one concrete next step. No "Hope this helps!"
+
+## Example 2: Multi-turn state restatement (rule 5, rule 7)
+
+**User:** "Continue the migration — where were we?"
+
+**What the agent does:**
+
+Step 3 of 5 done: schema updated, `users` table has `email_verified_at`. Next: backfill the new column.
+
+1. Run `npm run migrate:backfill -- --batch=1000` (about 10 minutes for 50k rows)
+2. Verify: `SELECT COUNT(*) FROM users WHERE email_verified_at IS NULL;` should return 0
+
+Login now works with magic links. Try: `npm run dev`, open `/login`.
+
+Next: run the backfill command above.
+
+**Result:** State restated on screen, win made visible, single next action.
+
+## Example 3: Tangent suppression + time estimate (rules 4, 6)
+
+**User:** "Fix the slow dashboard query."
+
+**What the agent does:**
+
+Add the missing index first — about 5 minutes:
+
+1. Open `db/migrations/042_add_orders_index.ts`
+2. Add `CREATE INDEX idx_orders_user_created ON orders(user_id, created_at)`
+3. Run `npm run migrate && npm test -- orders.spec.ts` (about 3 minutes)
+
+Separately: the dashboard also refetches on every tab focus. Want me to handle that next?
+
+Next: run the migration and paste the query time before/after.
+
+**Result:** One fix finished, second issue parked as a single question, concrete estimate.
+
+## Example 4: Long list ranked and grouped (rule 9)
+
+**User:** "What are my options for fixing flaky CI?"
+
+**What the agent does:**
+
+Use retry-with-quarantine first — about 30 minutes to set up.
+
+Top fix:
+
+1. Quarantine the 3 flaky specs, retry once on failure (about 30 minutes)
+
+Also relevant, grouped:
+
+- Speed (pick one): split test shards 2 → 4; cache `node_modules` per lockfile hash
+- Signal (pick one): fail-fast on `auth.spec.ts`; post flaky-test summary as a PR comment
+
+Skipped nothing — full candidate list kept in analysis, only presentation grouped.
+
+Next: say which group to apply and I will edit the workflow file.

package/framework/skills/gh/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: gh
+description: Expert guidance for using the GitHub CLI (gh) to work with repositories, issues, pull requests, Actions, releases, and the GitHub API from the command line. Use this skill whenever the user needs to perform a GitHub workflow or asks to use gh.
+allowed-tools: Bash, Read, Grep, Glob
+---
+
+# GitHub CLI (`gh`) Skill
+
+Use the official `gh` CLI for GitHub operations instead of manually constructing API requests or browser workflows when a supported command exists.
+
+## When to Use This Skill
+
+Invoke when the user needs to:
+
+- Inspect, create, edit, review, merge, or close pull requests
+- Search, create, edit, comment on, or close issues
+- Inspect repositories, branches, releases, tags, or notifications
+- View, rerun, cancel, or inspect logs for GitHub Actions workflows
+- Create and manage releases
+- Query or mutate GitHub resources through the API
+
+## Prerequisites and Authentication
+
+Verify that the CLI is installed before executing commands:
+
+```bash
+gh --version
+```
+
+Check the active account and token scopes:
+
+```bash
+gh auth status
+```
+
+If authentication is missing, use the interactive login flow:
+
+```bash
+gh auth login
+```
+
+For automation, prefer a short-lived `GH_TOKEN` or `GITHUB_TOKEN` environment variable. Never print, commit, or include token values in command output, issue bodies, pull requests, or logs.
+
+## Repository Context
+
+Most commands infer the repository from the current Git remote. Confirm context when it matters:
+
+```bash
+git remote -v
+gh repo view --json nameWithOwner,defaultBranchRef
+```
+
+Use `--repo OWNER/REPO` when running outside a checkout or targeting another repository.
+
+## Core Workflows
+
+### Pull Requests
+
+```bash
+# List and inspect PRs
+gh pr list --state open
+gh pr view 123 --comments
+
+# Create a PR after pushing the branch
+git push -u origin HEAD
+gh pr create --base main --title "Add feature" --body "Summary and testing notes"
+
+# Review a PR
+gh pr checkout 123
+gh pr diff 123
+gh pr review 123 --approve
+
+# Merge only after the user has explicitly approved the merge
+gh pr merge 123 --squash --delete-branch
+```
+
+Prefer `--body-file` for substantial descriptions and `--json` with `--jq` for reliable scripting. Before creating or updating a PR, inspect repository templates and existing branch commits when the workflow requires them.
+
+### Issues
+
+```bash
+gh issue list --state open --assignee @me
+gh issue view 123 --comments
+gh issue create --title "Bug report" --body-file bug.md --label bug
+gh issue comment 123 --body "Investigation is complete."
+```
+
+Use `--repo OWNER/REPO` for issues in another repository. Treat closing, reopening, editing, and deleting issues as mutating operations that require clear user intent.
+
+### GitHub Actions
+
+```bash
+gh run list --limit 20
+gh run view RUN_ID
+gh run view RUN_ID --log-failed
+gh run watch RUN_ID
+gh workflow run workflow.yml --ref main
+```
+
+Confirm the workflow name, ref, and inputs before dispatching a workflow. Do not rerun or cancel runs without user authorization.
+
+### Releases and Repositories
+
+```bash
+gh release list
+gh release view v1.2.3
+gh release create v1.2.3 --generate-notes
+gh repo view OWNER/REPO
+gh repo clone OWNER/REPO
+```
+
+Creating, editing, or deleting releases and repositories is destructive or externally visible; confirm the target and requested changes first.
+
+## API and Scripting
+
+Use structured output rather than parsing human-readable tables:
+
+```bash
+gh pr list --json number,title,state --jq '.[] | [.number, .title, .state] | @tsv'
+gh api repos/OWNER/REPO/issues --paginate --jq '.[] | [.number, .title] | @tsv'
+```
+
+For API mutations, state the HTTP method and target before execution and ask for confirmation when the operation changes remote data:
+
+```bash
+gh api repos/OWNER/REPO/issues --method POST \
+  -f title='Bug report' -f body='Details'
+```
+
+Use `gh <command> --help` and `gh api --help` when exact flags or endpoint behavior is uncertain. Prefer `--paginate` for collection endpoints and constrain fields with `--jq` to avoid exposing unnecessary data.
+
+## Best Practices
+
+1. Run `gh auth status` before diagnosing authentication failures.
+2. Check `git status`, the current branch, and the remote before PR or release work.
+3. Use `--repo OWNER/REPO` rather than changing directories solely to select a repository.
+4. Use `--json`/`--jq` for scripts and `--body-file` for multiline content.
+5. Confirm before pushing, merging, closing, deleting, dispatching, rerunning, or cancelling remote work.
+6. Do not bypass branch protection or approval requirements unless the user explicitly requests it and has authority.
+
+## Common Problems
+
+- **`gh: command not found`** — Install GitHub CLI and verify it is on `PATH`.
+- **Authentication or scope errors** — Run `gh auth status`, then `gh auth refresh` or `gh auth login` as appropriate.
+- **Wrong repository** — Check `git remote -v` and pass `--repo OWNER/REPO` explicitly.
+- **PR cannot merge** — Inspect `gh pr checks NUMBER`, mergeability, required reviews, and branch protection.
+- **Workflow dispatch fails** — Confirm the workflow supports `workflow_dispatch`, the ref exists, and required inputs are supplied.
+- **API returns 404** — Verify repository spelling and that the authenticated account can access it.
+
+## Quick Reference
+
+- `gh repo view` — View the current repository
+- `gh pr list` / `gh pr view NUMBER` / `gh pr create` — Pull request workflows
+- `gh issue list` / `gh issue view NUMBER` / `gh issue create` — Issue workflows
+- `gh run list` / `gh run view ID` / `gh run watch ID` — Actions workflows
+- `gh release list` / `gh release create TAG` — Release workflows
+- `gh api ENDPOINT` — GitHub REST or GraphQL API access

package/framework/skills/gh/examples.md

@@ -0,0 +1,10 @@
+# Examples
+
+- Check `gh auth status` and repository context before performing GitHub operations.
+- List open pull requests, inspect a specific PR with comments and checks, and summarize its status without changing remote data.
+- Prepare a pull request from the current branch by reviewing commits and templates, then show the proposed title and body before creating it.
+- Search issues with structured `--json` and `--jq` output, avoiding fragile parsing of terminal tables.
+- Inspect a failed GitHub Actions run with `gh run view RUN_ID --log-failed` and summarize the relevant failure.
+- Create or dispatch a workflow only after confirming the workflow, ref, and inputs with the user.
+- Use `gh api` for an endpoint not covered by a subcommand, preferring read-only requests and requesting confirmation before mutations.
+- Ask for explicit confirmation before pushing, merging, closing, deleting, rerunning, cancelling, or publishing remote resources.