@mohammadhprp/system-prompt 0.12.5 → 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/unslop/SKILL.md

@@ -14,6 +14,12 @@ Edit text to remove AI patterns and add human voice.
 2. Rewrite. Preserve meaning, match intended tone.
 3. Add soul (see next section).
 4. Self-audit: "What makes this obviously AI generated?" Fix remaining tells.
+5. Output the full edited draft plus a short **What changed** section listing the patterns fixed.
+6. Run the checks in [eval.md](references/eval.md). If any check fails, fix the draft and re-check.
+
+## Detect mode
+
+When the user asks whether a piece is slop, or asks to audit, scan, or flag a draft without rewriting: name each pattern from this skill that appears, quote the line, and give the fix in a few words. Do not rewrite, score the draft, or guess whether AI wrote it. Offer to edit the draft after.
 
 ## Adding soul
 
@@ -39,7 +45,7 @@ Removing patterns is half the job. Sterile, voiceless writing is just as obvious
 
 ### Language
 
-7. **AI vocabulary.** Additionally, crucial, delve, enduring, enhance, fostering, garner, interplay, intricate, landscape (abstract), pivotal, showcase, tapestry (abstract), testament, underscore, vibrant. Replace with plain words.
+7. **AI vocabulary.** Additionally, beacon, crucial, cutting-edge, delve, empower, embark, elevate, enduring, enhance, ever-evolving, fostering, game changer, garner, interplay, intricate, landscape (abstract), meticulous, multifaceted, paradigm shift, paramount, pivotal, realm, robust, showcase, streamline, supercharge, tapestry (abstract), testament, this changes everything, this is huge, transformative, underscore, vibrant. Replace with plain words.
 8. **Fancy ways to say "is".** "serves as", "stands as", "boasts", "features". Just say "is" or "has".
 9. **"Not just X, but Y."** State the point directly instead.
 10. **Rule of three.** Forcing ideas into groups of three. Use the natural number.
@@ -64,8 +70,8 @@ Removing patterns is half the job. Sterile, voiceless writing is just as obvious
 
 ### Filler
 
-23. **Filler phrases.** "In order to" becomes "To". "Due to the fact that" becomes "Because". "It is important to note that" gets deleted.
-24. **Excessive hedging.** "could potentially possibly be argued that it might" becomes "may".
+23. **Filler phrases.** "In order to" becomes "To". "Due to the fact that" becomes "Because". "It is important to note that" gets deleted. Often-empty phrases that delay the point: it's worth noting, at the end of the day, when it comes to, at its core, in today's world, in the age of, in the world of, the reality is, the truth is, in terms of, with regard to, going forward, in this article, let's dive in. Cut them unless part of the writer's recognizable voice.
+24. **Excessive hedging.** "could potentially possibly be argued that it might" becomes "may". Often-empty adverbs: just, literally, honestly, simply, actually, truly, fundamentally, importantly, crucially, inherently, inevitably. Cut when they add nothing; keep when they carry emphasis, uncertainty, contrast, or spoken rhythm.
 25. **Generic conclusions.** "The future looks bright." State specific plans or facts.
 
 ### Jargon
@@ -79,3 +85,28 @@ Removing patterns is half the job. Sterile, voiceless writing is just as obvious
 29. **Active voice.** Prefer it. Catch "is/are/was/were + past participle" and name the actor: "queries are validated" becomes "the compiler validates queries", "the file is parsed by the loader" becomes "the loader parses the file". Passive is fine only when the actor is unknown or genuinely doesn't matter.
 30. **Cut adverbs, or use a stronger verb.** "runs quickly" becomes "is fast" or the number. "significantly improves" becomes the measured delta. An adverb propping up a weak verb means the verb is wrong.
 31. **Prefer the plain word.** "utilize" becomes "use", "leverage" becomes "use", "facilitate" becomes "help", "numerous" becomes "many", "in the event that" becomes "if". The fancier synonym is rarely clearer.
+
+### Voice preservation (from no-ai-slop)
+
+32. **Minimum effective edit.** Fix AI patterns, errors, repetition, and unclear passages. Leave strong human sentences alone. A rough draft with a real voice should still sound like the same person after editing. Do not make every paragraph equally tidy.
+33. **Show, don't label.** Cut commentary that labels a point important, surprising, subtle, or obvious instead of demonstrating why ("That last part matters more than it sounds", "The key point is", "As you can see", "This distinction matters", redundant "In other words"). If the prose already shows the point, delete the aside. Otherwise replace it with facts.
+34. **Protect the specific fact.** Don't smooth a useful detail into generic importance. "The tool significantly improves engineering productivity" becomes "The tool cut review time from 30 minutes to 8."
+35. **Portability test.** If a sentence could move unchanged to another person, company, country, or product, it is filler. Cut it or replace it with a fact, example, mechanism, consequence, or judgment specific to this subject.
+
+### Dramatic setups and endings (from no-ai-slop)
+
+36. **Throat-clearing openers.** "Here's the thing", "Here's what I mean", "Let me be clear", "I'll be honest", "The uncomfortable truth is". Cut and state the point. Keep a personal aside only when it creates context, tension, or character.
+37. **Faux-insight setups.** "What nobody tells you", "What most people get wrong", "The part everyone misses", "This is the part most people skip". These flatter the writer as the lone expert. Cut the setup; make the claim stand on its own.
+38. **Binary contrasts.** "It's not X. It's Y.", "The question isn't X, it's Y." State Y directly. "The question isn't the model. It's the eval." becomes "The eval matters more than the model." (See also 9.)
+39. **Negative listing.** "Not a X. Not a Y. A Z." Just say Z.
+40. **Rhetorical setups.** "What if I told you...", "Think about it:", "Plot twist:", self-answered "Question? Answer." pairs. Drop them and make the point.
+41. **Colon reveals.** A noun phrase, a colon, then a lowercase dramatic reveal: "The best part: it learns." Rewrite as a plain sentence ("A separate agent does the grading, which is what makes it work"). Colons are for lists, labels, and quotes, not fake drama. (See also 14.)
+42. **Dramatic fragmentation.** "That's it. That's the whole thing.", "X. And Y. And Z." Use complete sentences unless the fragment is clearly the writer's own cadence.
+43. **Robotic rhythm.** Repeated sentence shapes, identical paragraph structures, stacked punchy fragments. Vary the shape only when it helps the point.
+44. **Fake-profound kickers.** Cut the final "deep" line when it turns the point into a metaphor, aphorism, or mic-drop ("The future isn't coming. It's already here."). Do not rewrite it into a better metaphor. Delete it, then end on the clearest concrete sentence already in the draft.
+45. **Summary-recap endings.** "In conclusion", "Ultimately", "Overall", or a final paragraph restating the piece. The reader was just there. End on the last concrete point, takeaway, or next action instead. (See also 25.)
+46. **Formatting slop.** Bullet lists where two sentences of prose would read better, headers over two-sentence sections. Format follows the content, not decorates it. (See also 15, 18.)
+
+## Source
+
+Patterns 32–46, detect mode, and `references/eval.md` adapted from [no-ai-slop](https://github.com/petergyang/no-ai-slop) by Peter Yang, MIT License.

package/framework/skills/unslop/examples.md

@@ -3,3 +3,5 @@
 - Rewrite release notes to remove inflated claims, filler, and generic AI phrasing while preserving meaning.
 - Edit technical prose for plain language, varied rhythm, active voice, and a natural human tone.
 - Scan a document for em-dash overuse, formulaic transitions, vague claims, and unnecessary jargon before rewriting it.
+- Detect mode: flag each slop pattern with a quoted line and a short fix, without rewriting. Example: "`The best part: it learns.` — colon reveal (41). Rewrite as a plain sentence."
+- Minimum effective edit: leave strong human sentences alone. Example: keep the writer's blunt aside, cut only the throat-clearing opener and the fake-profound kicker.

package/framework/skills/unslop/references/eval.md

@@ -0,0 +1,44 @@
+# Unslop eval
+
+Use after the rewrite. Answer each check with pass or fail. If any check fails, fix the draft before returning it.
+
+For detect requests, make sure the response names each pattern found with a quoted line and a short fix, without rewriting the draft.
+
+## Edit integrity
+
+1. Does the edit preserve the user's point without adding claims, examples, stats, quotes, or opinions?
+2. Does it preserve the writer's distinctive vocabulary, cadence, bluntness, humor, uncertainty, and level of polish (32)?
+3. Does it leave strong human sentences alone instead of making every paragraph equally tidy (32)?
+4. Is the amount of cutting proportional to the actual slop, with no aggressive compression that strips out character?
+5. Does the draft lead with what the reader needs while keeping personal setup that adds context, tension, or character (36)?
+6. Do sentences earn their place, with concrete facts, protected details (34), and direct verbs?
+7. Does every generic sentence pass the portability test (35), or was it cut or made specific?
+8. Does the draft use active voice with human subjects where possible (29)?
+9. Are genuinely tangled sentences fixed while clear spoken cadence and changes in pace remain intact (28)?
+
+## Words to cut
+
+1. Are banned words (7), filler phrases (23), often-empty adverbs (24), and inflated claims removed unless quoted as examples?
+
+## Patterns to cut
+
+1. Are binary contrasts (9, 38), negative listings (39), rhetorical setups (40), and throat-clearing openers (36) removed?
+2. Are faux-insight setups (37), colon reveals (41), superficial -ing phrases (3), fancy "is" verbs (8), synonym cycling (11), dramatic fragments (42), and robotic rhythm (43) fixed?
+3. Are puffery (1), promotional language (4), and vague attributions (5) replaced with plain facts and named sources, or flagged when no source exists?
+4. Is interpretive metadiscourse (33) removed, including emphasis markers and redundant glossing?
+5. Are fake-profound kickers (44) deleted instead of rewritten into better metaphors?
+6. Are summary-recap endings (45) cut so the piece ends on a concrete point, takeaway, or next action?
+7. Is formatting slop removed: decorative emoji (18), decorative bold (15), bullets that should be prose, headers over tiny sections (46)?
+8. Are em dashes (13), colons (14), title case headings (17), and curly quotes (19) fixed?
+
+## Final read
+
+1. Does the draft avoid robotic symmetry, repeated sentence shapes, and stacked punchy fragments (43)?
+2. Would the writer recognize the edited draft as their own voice?
+3. Would the edited draft sound natural if read to a sharp colleague?
+4. Does the final output include the full edited draft and a short **What changed** section?
+5. For detect requests, does the response name each pattern with a quoted line and a short fix, without rewriting, scoring, or claiming AI authorship?
+
+## Source
+
+Adapted from [no-ai-slop](https://github.com/petergyang/no-ai-slop) `eval.md` by Peter Yang, MIT License.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mohammadhprp/system-prompt",
-  "version": "0.12.5",
+  "version": "0.12.6",
   "description": "AI Coding Agent Framework — interactive bootstrap CLI",
   "keywords": [
     "ai",

package/src/catalog.js

@@ -4,6 +4,7 @@ export const categories = {
     description: 'Task-specific procedures for AI coding agents',
     sourceDir: 'framework/skills',
     items: [
+      { id: 'adhd', name: 'ADHD', description: 'Shape output for ADHD readers: action first, numbered steps, restated state, no tangents' },
       { id: 'agent-browser', name: 'Agent Browser', description: 'Automate browser and Electron workflows for navigation, testing, screenshots, and data extraction' },
       { id: 'architect', name: 'Architect', description: 'Sketch architecture and module boundaries before implementation' },
       { id: 'arena', name: 'Arena', description: 'Compare parallel candidate solutions and synthesize the strongest result' },
@@ -57,13 +58,9 @@ export const categories = {
     description: 'Slash command workflows for repeatable tasks',
     sourceDir: 'framework/commands',
     items: [
-      { id: 'changelog', name: 'Changelog', description: 'Create, add, or update CHANGELOG.md entries' },
-      { id: 'commit', name: 'Commit', description: 'Create atomic git commits with conventional messages' },
+      { id: 'audit-your-codebase', name: 'Audit Your Codebase', description: 'Audit for materially useful simplifications in structure, state, algorithms, and ownership' },
+      { id: 'explain-codebase', name: 'Explain Codebase', description: 'Map a codebase and teach it interactively, from overview to focused deep-dives' },
       { id: 'learn', name: 'Learn', description: 'Distill a reusable skill from any source' },
-      { id: 'pr', name: 'PR', description: 'Create a GitHub PR for the current branch' },
-      { id: 'mr', name: 'MR', description: 'Create a GitLab MR for the current branch' },
-      { id: 'release', name: 'Release', description: 'Tag releases, update changelog, and bump versions' },
-      { id: 'review', name: 'Review', description: 'Review local, GitHub, or GitLab changes and write review.json' },
       { id: 'summarize-changes', name: 'Summarize Changes', description: 'Summarize uncommitted changes and flag risks' },
     ],
   },

package/framework/commands/changelog.md

@@ -1,44 +0,0 @@
----
-description: Create, add, or update entries in CHANGELOG.md
-agent: build
----
-
-Changelog $ARGUMENTS
-
-Maintain CHANGELOG.md entries for my changes.
-
-## Process
-
-1. **Review and categorize** - Review conversation history, read current `CHANGELOG.md`, determine if changes are `Added`, `Changed`, `Fixed`, `Removed`, `Deprecated`, or `Security`. Read the existing `## Unreleased` section.
-
-2. **Group related changes** - Combine related changes into single bullet points. Use past tense ("Added...", "Fixed..."). Include file paths or component names in backticks when helpful. Match existing style and tone.
-
-3. **Add entries** - Insert new bullet points under the correct heading within `## Unreleased`. Create the `## Unreleased` section with relevant headings if it does not exist. Preserve all existing entries.
-
-4. **Verify** - Read the final `CHANGELOG.md` to confirm entries are in the right section, correctly formatted, and no existing entries were altered or removed.
-
-## Entry Format
-
-```markdown
-## Unreleased
-
-### Added
-- New features, entries, additions.
-
-### Changed
-- Changes in existing functionality, refactors, renames.
-
-### Fixed
-- Bug fixes, corrections.
-
-### Removed
-- Removed features, files, entries.
-
-### Deprecated
-- Soon-to-be-removed features.
-
-### Security
-- Vulnerabilities, security fixes.
-```
-
-**Note:** Group entries by section. Order sections: Added, Changed, Fixed, Removed, Deprecated, Security. Within each section, entries are reverse-chronological (newest first). Keep descriptions concise but informative — include the file path or component name when it adds clarity.

package/framework/commands/commit.md

@@ -1,28 +0,0 @@
----
-description: Create atomic git commits with conventional messages
-agent: build
----
-
-Commit $ARGUMENTS
-
-Create git commits for my changes.
-
-## Process
-
-1. **Analyze and plan** - Review conversation history, run `git status -s` and `git diff`, determine if changes should be one or multiple logical commits, group related files, draft conventional commit messages (`type: description`) in imperative mood focusing on why
-2. **Present plan** - List files for each commit, show commit messages with type prefix, ask: "I plan to create [N] commit(s) with these changes. Shall I proceed?"
-3. **Execute upon confirmation** - Use `git add` with specific files (never `-A` or `.`), create commits with planned messages, show result with `git log --oneline -n [N]`
-
-## Commit Message Format
-
-Use conventional commit format: `type: description`
-
-**Types:**
-- `feat:` - New feature (user-facing)
-- `fix:` - Bug fix (user-facing)
-- `docs:` - Documentation only
-- `chore:` - Maintenance, tooling, dependencies
-- `refactor:` - Code restructuring without behavior change
-- `test:` - Adding or updating tests
-- `perf:` - Performance improvement
-- `ci:` - CI/CD changes

package/framework/commands/mr.md

@@ -1,45 +0,0 @@
----
-description: Create a merge request from the current branch
----
-
-Create $ARGUMENTS merge request
-
-Create a merge request for the current branch.
-
-## Process
-
-1. **Collect information**
-   - Get current branch name: `git branch --show-current`
-   - Read MR template from `.gitlab/merge_request_templates/default.md` of exsits
-
-2. **Format MR title**
-   - Take the branch name, replace all `-` with spaces, capitalize first character
-
-3. **Collect commits and build summary**
-   - List commits on the branch that are not on `dev`: `git log dev..HEAD --oneline`
-   - Read each commit message, convert to a bullet list summarizing user-facing changes
-   - Merge/squash related commits (e.g. multiple commits for the same change)
-   - Keep concise, one bullet per logical change
-
-4. **Fill template**
-   - Set Summary to the bullet list from step 3
-   - Keep the Checklist section as-is
-
-5. **Present plan and confirm** - Show:
-   - Source branch
-   - Target branch: `develop`
-   - Title
-   - Filled description
-   - Ask: "Shall I create this MR?"
-   - Push the changes if user says Yes
-
-6. **Create upon confirmation** - Use `glab mr create`:
-   - `--source-branch`: Current branch
-   - `--target-branch`: `develop`
-   - `--title`: Prepend "Draft: " to the formatted branch name
-   - `--description`: Filled template content
-   - `--assignee`: `1`
-   - `--squash`
-   - `--remove-source-branch`
-
-7. **Show the resulting URL.**

package/framework/commands/pr.md

@@ -1,39 +0,0 @@
----
-description: Create a GitHub PR for the current branch
-agent: build
----
-
-PR $ARGUMENTS
-
-Create or update a pull request for the current branch using `gh` cli.
-
-## Process
-
-1. **Collect information**
-   - Get current branch name: `git branch --show-current`
-   - Read PR template from `.github/pull_request_template.md` of exsits
-
-2. **Format PR title**
-   - Take the branch name, replace all `-` with spaces, capitalize first character
-
-3. **Collect commits and build summary**
-   - List commits on the branch that are not on `dev`: `git log dev..HEAD --oneline`
-   - Read each commit message, convert to a bullet list summarizing user-facing changes
-   - Merge/squash related commits (e.g. multiple commits for the same change)
-   - Keep concise, one bullet per logical change
-
-4. **Fill template**
-   - Set Summary to the bullet list from step 3
-   - Keep the Checklist section as-is
-
-5. **Present plan and confirm** - Show:
-   - Source branch
-   - Target branch: `develop`
-   - Title
-   - Filled description
-   - Ask: "Shall I create this PR?"
-   - Push the changes if user says Yes
-
-6. **Create upon confirmation** - Use `gh` cli:
-   - `gh pr create --title "<title>" --body "<body>" --base <target>`
-   - Show the resulting URL.

package/framework/commands/release.md

@@ -1,34 +0,0 @@
----
-description: Create a release by tagging the current state, generating changelog, and bumping version
-agent: build
----
-
-Release $ARGUMENTS
-
-Create a release from the current branch state.
-
-## Process
-
-1. **Review recent commits** - Run `git fetch --tags`, `git describe --tags --abbrev=0` to find the latest tag. Run `git log <latest-tag>..HEAD --oneline --format="%s"` to collect all conventional commits since the last release. Read any existing `CHANGELOG.md`.
-
-2. **Categorize commits** - Group commits by conventional commit type:
-   - `feat!:` or `BREAKING CHANGE:` → breaking change
-   - `feat:` → minor feature
-   - `fix:` → patch fix
-   - `perf:`, `refactor:`, `test:` → patch (if no features)
-   - `chore:`, `docs:`, `ci:` → filtered from changelog
-
-3. **Determine next version** - Based on the [`commit.md`](./commit.md) semver convention:
-   - Breaking changes → increment major version (e.g., `1.2.3` → `2.0.0`)
-   - New features → increment minor version (e.g., `1.2.3` → `1.3.0`)
-   - Only fixes/refactors → increment patch version (e.g., `1.2.3` → `1.3.4`)
-   - If no previous tag exists, propose `0.1.0`
-
-4. **Present release plan** - Show: current version, new version, categorized changelog entries, and ask: "Shall I create this release (tag vX.Y.Z and update CHANGELOG.md)?"
-
-5. **Execute on confirmation**:
-   - Update `CHANGELOG.md`: create a new `## [vX.Y.Z]` section under `## Unreleased`, move categorized entries (excluding chore/docs/ci) into it, add the release date, keep the `## Unreleased` section empty for future work
-   - Run `git add CHANGELOG.md && git commit -m "chore: release vX.Y.Z"`
-   - Run `git tag -a vX.Y.Z -m "vX.Y.Z"`
-
-6. **Verify** - Run `git log --oneline -n 3` and `git tag --list --sort=-v:refname -n5` to confirm the release tag and commit are in place.

package/framework/commands/review.md

@@ -1,9 +0,0 @@
----
-description: Review local, GitHub, or GitLab changes and write review.json
-agent: plan
----
-
-Review `$ARGUMENTS` using the `review` skill. Select local changes, a GitHub
-pull request, or a GitLab merge request from the arguments. Use `gh` or `glab`
-for read-only remote inspection, never publish comments, and write the required
-`review.json` artifact.