@mrciphersmith/keryx 0.2.97 → 0.2.99

package/src/gdskills/bundled/skills/planning/spec-writer/SKILL.cursor.md

@@ -5,6 +5,10 @@ description: >
   architecture doc, and best practices. Does NOT invent new architectural decisions.
   Use when: dispatched by gproject-orchestrator Phase 4.
   NOT for: direct user invocation.
+triggers:
+  - "write spec"
+  - "technical specification"
+  - "implementation plan"
 metadata:
   version: 1.0.0
   compatible_harnesses: "cursor,codex,zed,opencode"

package/src/gdskills/bundled/skills/planning/spec-writer/SKILL.md

@@ -5,6 +5,10 @@ description: >
   architecture doc, and best practices. Does NOT invent new architectural decisions.
   Use when: dispatched by gproject-orchestrator Phase 4.
   NOT for: direct user invocation.
+triggers:
+  - "write spec"
+  - "technical specification"
+  - "implementation plan"
 metadata:
   version: 1.0.0
 ---

package/src/gdskills/bundled/skills/planning/stack-advisor/SKILL.codex.md

@@ -5,6 +5,10 @@ description: >
   technology stack with trade-off analysis.
   Use when: dispatched by gproject-orchestrator Phase 2.
   NOT for: direct user invocation.
+triggers:
+  - "stack advice"
+  - "choose stack"
+  - "technology choice"
 metadata:
   version: 1.0.0
   compatible_harnesses: "cursor,codex,zed,opencode"

package/src/gdskills/bundled/skills/planning/stack-advisor/SKILL.cursor.md

@@ -5,6 +5,10 @@ description: >
   technology stack with trade-off analysis.
   Use when: dispatched by gproject-orchestrator Phase 2.
   NOT for: direct user invocation.
+triggers:
+  - "stack advice"
+  - "choose stack"
+  - "technology choice"
 metadata:
   version: 1.0.0
   compatible_harnesses: "cursor,codex,zed,opencode"

package/src/gdskills/bundled/skills/planning/stack-advisor/SKILL.md

@@ -5,6 +5,10 @@ description: >
   technology stack with trade-off analysis.
   Use when: dispatched by gproject-orchestrator Phase 2.
   NOT for: direct user invocation.
+triggers:
+  - "stack advice"
+  - "choose stack"
+  - "technology choice"
 metadata:
   version: 1.0.0
 ---

package/src/gdskills/bundled/skills/platform/agent-entrypoint-distiller/SKILL.md

@@ -1,9 +1,13 @@
 ---
 name: agent-entrypoint-distiller
-description: Use when the user asks to split, decompose, distill, or refactor a large AGENTS.md or CLAUDE.md into Metaproject rules and project-specific skills while keeping root entrypoints compact.
+description: "Use when the user asks to split, decompose, distill, or refactor a large AGENTS.md or CLAUDE.md into Metaproject rules and project-specific skills while keeping root entrypoints compact. NOT for: adding a newly learned convention or command to an existing CLAUDE.md (use claude-md-management)."
 triggers:
-  - "distill AGENTS.md"
+  - "distill claude"
   - "split CLAUDE.md"
+  - "разбери CLAUDE.md"
+  - "создай правила из CLAUDE.md"
+  - "entrypoint rules"
+  - "distill AGENTS.md"
   - "разнеси CLAUDE.md по правилам"
 metadata:
   version: "1.0.0"
@@ -35,10 +39,33 @@ keryx rules distill
 
 ```bash
 keryx rules sync
-keryx flow check 001
+keryx flow check
 ```
 
-Skip `flow check` when the project has no Task Manager flow.
+`flow check` takes no flow id: it validates every package under `.metaproject/flows/` — id uniqueness, `flow.json` against the published schema, the six required documents, and the acceptance-criteria checksum. With no flows it prints `All flows are consistent.` and exits 0, so it is safe to run either way.
+
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "`keryx rules distill` exited 0, so the split is correct." | Exit 0 says the command ran, not that it split well. It happily writes an empty rule, a rule titled after a heading it could not classify, and two rules holding the same paragraph. Open every file listed in step 3 before reporting anything. |
+| "The root entrypoint is short now, so the job is done." | Shortness is a side effect, not the goal. A root that no longer points at `.metaproject/index.md`, or that lost an always-on instruction into a rule nothing loads, is a regression that looks like success on a line count. |
+| "This section read like a project rule, so I moved it out of the root." | Global, personal and highest-priority always-on instructions stay in the root by design. If you had to guess which kind a section was, it belongs in the ambiguous list for a human — not silently in a rule file. |
+| "The project has no flow, so I can skip verification." | `keryx flow check` is not conditional either — with no flows it reports `All flows are consistent.` and exits 0. `keryx rules sync` runs every time; skipping it ships a rules tree whose index and files disagree. |
+| "`keryx rules distill` rewrote the root files, so I don't need to read them." | The rewrite is exactly what needs checking. Reading the post-distill `AGENTS.md` and `CLAUDE.md` is the only way to see what was carried out of them. |
+
+## Verification
+
+Before reporting, all of these must hold:
+
+- `keryx rules sync` exits 0.
+- `.metaproject/rules/entrypoints/index.md` exists and names every file written under `.metaproject/rules/entrypoints/`.
+- Every generated rule and project-skill file is non-empty and was read, not just listed.
+- `AGENTS.md` and `CLAUDE.md` both still reference `.metaproject/index.md`.
+- `keryx flow check` exits 0. It takes no id and checks every flow package in the project, so a distill that corrupted one reports here even though the distill never touched flows.
+- Every section you could not confidently classify appears in the ambiguous list of the Output Contract. An empty ambiguous list on a large entrypoint is a claim, and it must be a true one.
 
 ## Output Contract
 

package/src/gdskills/bundled/skills/platform/claude-md-management/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: claude-md-management
-description: "Use when saving session learnings, coding patterns, conventions, or commands discovered during work into CLAUDE.md files."
+description: "Use when saving session learnings, coding patterns, conventions, or commands discovered during work into CLAUDE.md files. NOT for: breaking an oversized entrypoint apart into Metaproject rules and skills (use agent-entrypoint-distiller)."
 triggers:
-  - "/revise-claude-md"
+  - "CLAUDE.md management"
+  - "agent entrypoint"
   - "Update claude md"
   - "Save learnings"
   - "Update project instructions"
@@ -10,7 +11,7 @@ triggers:
 metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
-  category: "configuration"
+  category: "platform"
   compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
 ---
@@ -85,3 +86,26 @@ Present diff preview:
 - NEVER add entries that duplicate what's already there
 - Keep CLAUDE.md files under 100 lines
 - Prefer project-level for project-specific things
+
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "I established this pattern earlier in the session, so it is a project convention." | One occurrence in one session is an anecdote. Write it only if you saw it hold more than once, or the user stated it as a rule. Everything else is noise that a future session will obey as if it were law. |
+| "`--auto` was passed, so I can skip reading the current files." | `--auto` removes the approval step in Step 5, not Steps 2-3. Skipping the read is how the same bullet lands three times and the file stops being read by anyone. |
+| "This entry is genuinely useful, so the project CLAUDE.md is the safe place for it." | A personal preference written into the project file is committed and imposed on every contributor. Classify against the Step 3 table first: global preferences go to `~/.claude/CLAUDE.md`, project-specific personal notes to the per-project user file. |
+| "The file is already at the 100-line cap, so one more line is harmless." | The cap is a limit, not a starting point. Going over means condensing or removing something outdated — and the removal has to be shown and explained, never done quietly. |
+| "The new entry contradicts an existing one, so the newer one obviously wins." | Maybe the old entry is still right and what you observed was a one-off. Surface the contradiction in the proposal and let the user decide which survives. |
+
+## Verification
+
+Before reporting, all of these must hold:
+
+- Every target file was re-read after editing, not assumed from the diff.
+- No bullet you added duplicates or contradicts an existing line, in that file or in a sibling CLAUDE.md.
+- Each edited file is still under 100 lines, uses `##` section headers, and has no YAML frontmatter.
+- Every insight landed in the file the Step 3 table names for its type — no project file carrying a personal preference.
+- Unless `--auto` was passed, the user saw the proposed diff and approved it before any write.
+- The report names each file changed, each entry added, and each entry removed with the reason it was removed.

package/src/gdskills/bundled/skills/platform/hookify/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: hookify
-description: "Use when adding automated hook behavior to Claude Code or Cursor from a natural language description."
+description: "Use when adding automated hook behavior to Claude Code or Cursor from a natural language description. NOT for: recording a convention or command as prose an agent reads (use claude-md-management)."
 triggers:
-  - "/hookify"
+  - "hookify"
+  - "hook guidance"
+  - "safe hooks"
   - "Create hook"
   - "Add hook"
   - "Run lint after edit"
@@ -10,7 +12,7 @@ triggers:
 metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
-  category: "configuration"
+  category: "platform"
   compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
 ---
@@ -88,7 +90,7 @@ After confirmation, merge into settings.
 
 - **Auto-lint**: PostToolUse(Edit) → `eslint --fix $FILE`
 - **Auto-format**: PostToolUse(Write) → `prettier --write $FILE`
-- **Type-check gate**: PreToolUse(Bash:git commit) → `npx tsc --noEmit`
+- **Type-check gate**: PreToolUse(Bash:git commit) → `keryx health run --changed --source typescript` (or the project's own configured type-check command when keryx health is not configured — never a hardcoded `npx tsc`)
 - **Notify on done**: Stop → notification command
 
 ## Rules
@@ -98,3 +100,26 @@ After confirmation, merge into settings.
 - Keep timeouts reasonable (10-60s)
 - Warn if hook could slow down every tool call
 - Test commands before adding as hooks
+
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "The JSON is valid, so the hook works." | Valid JSON says nothing about whether the binary is on PATH, the matcher spells the tool name the way the harness emits it, or the command exits non-zero on a clean run. Step 4 exists because a hook that fails silently is worse than no hook: it runs on every tool call and reports nothing. |
+| "The user described what they want clearly, so I can skip the preview." | The preview is where a matcher mistake is caught — "after every edit" meaning `Edit` but not `Write`, or a `PreToolUse` hook that will block the tool instead of warning. Show the resolved event, matcher, command and timeout, and apply only after confirmation. |
+| "There is already a hook on this event, so I'll replace it." | Overwriting is the one thing this skill forbids. Merge into the existing array, or ask which should win. A removed hook does not announce itself — the user finds out when the check it enforced stops running. |
+| "It's only a lint run, so the timeout does not matter." | A `PostToolUse(Edit)` hook runs on every single edit. A 5-minute lint on a large repo turns every edit into a stall, and the user will disable hooks entirely rather than debug it. Keep it in the 10-60s band and say so when the command is likely to be slow. |
+| "The command works in my shell, so it works as a hook." | Hooks run without the interactive shell's profile, aliases or cwd assumptions. Use an absolute or project-relative invocation, and test it the way the hook will run it. |
+
+## Verification
+
+Before reporting, all of these must hold:
+
+- The command was run standalone (when safe to do so) and its exit code observed — not assumed.
+- The event name and matcher were checked against the Hook Event Reference table, and the matcher matches the tool the user actually meant.
+- Existing hooks on that event were read and preserved; the written config contains them plus the new one.
+- The timeout is set explicitly and is within the 10-60s band, or the report explains why it is not.
+- The user saw the preview block (event, matcher, command, timeout) and confirmed before the settings file was written.
+- The report names the settings file that changed and the exact hook entry added; for `--remove`, it names the entry deleted.

package/src/gdskills/bundled/skills/quality/api-truth/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: api-truth
+model_tier: deep
+description: |
+  Use when code is about to call a dependency nobody has read today — a client
+  method, an option object, a config key, a CLI flag — and the only thing
+  vouching for the signature is somebody's recollection of it. Recollection has
+  a cutoff date; the version resolved in this project does not. Settles what
+  "checked" means: the version actually installed here rather than the newest
+  one, the artefacts that carry it in rank order, and which side wins when the
+  published documentation and the installed build disagree. Every call that went
+  out unchecked is MARKED as unchecked, so a later reader can tell a verified
+  signature from a remembered one.
+  NOT for: moving a project onto newer releases of the packages it already has,
+  and NOT for picking which library or architectural pattern to adopt before
+  anything is installed.
+triggers:
+  - "check this against the installed version"
+  - "is that still the API"
+  - "did you make that signature up"
+  - "which version do we actually have"
+  - "look up the real API"
+metadata:
+  author: "MrCipherSmith"
+  version: "1.0.0"
+  category: "quality"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
+license: "MIT"
+---
+
+# API Truth
+
+A remembered API call is a claim about a version. The claim is usually right,
+which is the problem: it fails quietly, in the small fraction of cases where the
+library moved, and it fails in the worst possible way — the code compiles, the
+option object accepts the unknown key and ignores it, and nothing surfaces until
+production or never.
+
+Model weights have a cutoff date. A dependency does not. The gap between them
+grows every day the project is alive, and no signal inside the editor announces
+it.
+
+This skill is not "look things up". Looking things up on every call is a rule
+agents follow twice and abandon. It is four decisions: **when** the check is
+worth its cost, **which version** counts as the truth, **what** counts as a
+source, and **how** the unchecked calls are marked so somebody downstream can
+see them.
+
+---
+
+## 1. The version is the one installed here, not the latest
+
+"I checked the docs" means nothing until it names a version. The default failure
+is checking the current documentation of a library this project pinned eighteen
+months ago — same defect as recollection, with a citation attached.
+
+Three different numbers exist, and only one of them runs:
+
+| Number | Where | What it is |
+|---|---|---|
+| The range | `package.json` / `pyproject.toml` / `go.mod` | What the project will *accept*. Not a version. |
+| The resolved version | `bun.lock`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `poetry.lock`, `Cargo.lock`, `go.sum` | What a fresh install produces. |
+| The installed version | `node_modules/<pkg>/package.json` → `"version"`; `pip show <pkg>`; `cargo tree -p <pkg>` | What is on disk and executing **now**. |
+
+Read the third. When the third and the second disagree, the tree is stale and
+that is itself worth reporting — a call verified against a stale tree is
+verified against nothing anyone else has.
+
+For a transitive dependency, the version your direct dependency pulls is often
+not the version at the top level. Resolve the one on the actual path.
+
+## 2. When the check is worth paying for
+
+A skill that says *always verify everything* is ignored by the third task. The
+cost is real, so spend it where the failure is silent.
+
+**Check before writing the call when any of these hold:**
+
+- The symbol is not visible in types you can see — an untyped package, a config
+  object typed `Record<string, unknown>`, a CLI flag, an HTTP endpoint, a
+  template convention. Nothing will catch you.
+- The option is a **key in a bag**. Unknown keys in option objects, YAML, and
+  env-var maps are ignored in silence; a typo and a removed option are
+  indistinguishable from working code.
+- The call has an effect you cannot see locally — a write, a payment, an auth
+  decision, a migration, a cache invalidation, a webhook.
+- You know a major version boundary sits between your recollection and the
+  installed number, or you cannot say which side of one you are on.
+- Defaults matter to the behaviour you promised. Defaults change in *minor*
+  releases more often than signatures do, and no compiler mentions it.
+
+**Do not pay for it when:**
+
+- The call is typed and the type-checker runs on it. A strict `tsc --noEmit`
+  against the package's own shipped `.d.ts` **is** a check against the installed
+  version, performed by a machine, for free — that is §3's rank 1 already done.
+- A test you watched fail and then pass exercises this exact call path.
+- You read this same symbol, at this same version, earlier in this session.
+  Record it once; do not re-fetch per call site.
+- It is the language or runtime standard library at a version the toolchain
+  already pins.
+
+Everything outside both lists is a judgement call, and the tiebreaker is: how
+long would this defect stay invisible? Loud and immediate — write it and let the
+failure teach you. Silent — check first.
+
+## 3. What counts as a source, in rank order
+
+1. **The installed artefact itself** — the `.d.ts` beside the package, the
+   `node_modules` source, `inspect.signature`, the binary's `--help`. It cannot
+   be at the wrong version, because it *is* the version. Highest rank, and
+   usually the fastest to reach.
+2. **The package's own documentation, pinned to the installed version** — the
+   docs for the exact version installed, reached by whichever of these the
+   environment actually has. None of them ships with this skill or is installed
+   for you; check what is there before you reach for one:
+
+   - A versioned docs URL, or the repository at the tag matching that version.
+   - A docs-retrieval tool, where one is configured — a `ctx7`-style MCP server,
+     or `npx ctx7@latest library "Library Name" "<the actual question>"` then
+     `npx ctx7@latest docs /org/project/<installed-version> "<the question>"` if
+     that CLI is reachable. Official spelling ("Next.js", not "nextjs"), the real
+     question rather than one word, three commands of budget, no credentials.
+   - With neither, the docs shipped *inside* the installed artefact — its README,
+     its `docs/`, the binary's long help — pinned by construction. If that is
+     empty too, rank 2 is unavailable here: say so and rely on rank 1.
+3. **The package's own documentation, unpinned** — acceptable only after you
+   state the gap between it and the installed version, and treat everything it
+   says as provisional across that gap.
+4. **The changelog or migration guide**, for the narrow question of *what
+   changed between two versions you have named*. Not for what the API is now.
+5. **A blog post, a forum answer, another project's code, and your own
+   recollection** — all the same rank, which is *hypothesis*. They are worth
+   something: they tell you what to go and look at in ranks 1–3. They are worth
+   nothing as evidence, and a citation of one is not a check.
+
+## 4. When the documentation and the installed build disagree
+
+This is common, and it is the point where a careless agent picks the wrong side.
+
+**The installed artefact wins.** Documentation describes a version, usually the
+newest; `node_modules` is what executes. If the docs show an option the types do
+not have, the option does not exist here.
+
+The disagreement is not noise to route around — it is a finding, and it has to
+be named before you carry on:
+
+- Say which version the docs were at and which is installed. Nine times out of
+  ten the gap explains the disagreement, and now the next person does not
+  re-derive it.
+- Same version, still disagreeing? Then the docs are wrong, or you are reading a
+  different export path, or a patch/override is rewriting the package. Check the
+  path before concluding the docs are wrong.
+- Never split the difference by writing the documented call and adding a
+  fallback for the installed one. Two paths, one of which has never run, is a
+  larger defect than the one you were avoiding.
+- If the behaviour you need exists only in the documented version, that is an
+  upgrade decision and it belongs to whoever owns the dependency — say so, and
+  do not smuggle the bump in beside the feature.
+
+## 5. Marking what was not verified
+
+This is the part that survives into review, and the part agents skip.
+
+A checked call and a remembered call look identical in a diff. Unless the
+difference is written down, the reviewer inherits a file where every line
+carries the same implied confidence, and the one guess is camouflaged by forty
+facts around it.
+
+At the call site, on anything that went out unchecked:
+
+```
+// unverified: <symbol> against <pkg>@<version> — from recollection,
+// settle with: <the command or file that would settle it>
+```
+
+In the report or PR body, a short section that lists them: the symbol, the
+package and version, why the check was skipped (§2), and the one observation
+that would close it. An empty list is a fine result and should be stated as
+empty rather than omitted.
+
+And the converse, which is the cheaper half: when you *did* check, say against
+what. "Verified against `@aws-sdk/client-s3@3.620.0` types" is a sentence a
+reviewer can re-run. "I checked the docs" is not.
+
+Never mark a call verified on the strength of rank 5.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "It compiled, so the API is right." | Compilation proves the shape the *types* declare, and the silent failures live where types do not reach: unknown keys in an option bag, a string enum the library parses at runtime, a config file, a CLI flag. Those compile perfectly and do nothing. |
+| "I read the library's documentation, so this is checked." | Not until the version is named. The docs site serves the newest release; this project resolves whatever the lockfile says. An unversioned citation is a remembered call with a footnote — the same defect, harder to spot. |
+| "`package.json` says `^4.2.0`, so we are on 4.x." | That is the range the project accepts, not the build that is running. Read `node_modules/<pkg>/package.json`, and when it disagrees with the lockfile, say so — the tree is stale and nobody else's is like it. |
+| "The docs show this option but the types do not, so the types are out of date." | Backwards nearly every time. The types ship inside the installed package; the docs describe some version, usually a newer one. The artefact on disk is what executes — name the gap instead of overriding it. |
+| "I will write the documented call and add a fallback for the old signature." | You have shipped two branches and exercised one. The dead branch is never run, never tested and wrong in a way nobody discovers, and you took on that debt to avoid reading one file. |
+| "This is a well-known library, I have used it a hundred times." | Familiarity is the exposure, not the protection. The APIs recalled most confidently are the ones learned longest ago, so recollection is most stale exactly where it feels safest, and confident wrong calls skip their own review. |
+| "A blog post shows this exact pattern working." | It worked, at some version, on some day, for somebody whose lockfile you cannot see. That makes it a lead worth thirty seconds against the installed types — it does not make it evidence, and citing it does not turn a guess into a check. |
+| "Checking every call would take all day, so I checked none." | The list is not every call. It is the ones whose failure is silent — option bags, untyped surfaces, effects you cannot observe locally, changed defaults. Typed calls under a type-check are already verified; that is most of them. |
+| "I was not sure about two of these, but the rest are solid." | Then the two are invisible, because a diff shows no difference between them and the forty around them. Mark them at the call site with what would settle them, or the reviewer's only options are re-check everything or trust everything. |
+
+## Verification
+
+Do not report the work as done until all of these hold:
+
+- Every dependency call this change introduced is either verified against a
+  named source at a named version, or carries an `unverified:` marker at the
+  call site.
+- Each version named is the one installed on disk — read from the package's own
+  installed metadata, not from a manifest range — and any disagreement with the
+  lockfile is reported.
+- Every check cites its rank (§3): which artefact or versioned document, not
+  "the docs". No call is reported as verified on rank 5 alone.
+- Where documentation and the installed build disagreed, the report says which
+  versions were compared, which side was followed, and why — and no call site
+  branches across both.
+- The report carries the unverified list — symbol, package, version, reason the
+  check was skipped, and the observation that would close it — stated as empty
+  when it is empty.
+- Any needed behaviour that exists only in a newer release is written up as an
+  upgrade decision for the dependency's owner, and no version was bumped inside
+  this change to obtain it.
+
+Credit: [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills)
+(MIT) is where the pairing comes from — check the dependency before calling it,
+and mark what went out unchecked. The ranks and the version rule are ours.

package/src/gdskills/bundled/skills/quality/changelog/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: changelog
-description: "Use when generating a changelog, release notes, or summarizing what changed between tags, versions, or date ranges."
+description: "Use when generating a changelog, release notes, or summarizing what changed between tags, versions, or date ranges. NOT for describing a single pull request or its linked issue (use `pr-issue-documenter`)."
 triggers:
-  - "/changelog"
-  - "Generate changelog"
+  - "generate changelog"
+  - "release notes"
+  - "what changed"
   - "What changed since"
-  - "Release notes"
   - "What's new"
 metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
-  category: "workflow"
+  category: "quality"
   compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
 ---
@@ -82,3 +82,23 @@ If `gh` CLI available: fetch PR titles for merge commits, get authors and labels
 - If no conventional commits found, fall back to plain list by date
 - Breaking changes always go first
 - One line per change
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "This commit has no `feat:`/`fix:` prefix, but it reads like a feature — I'll file it under Features" | Classification comes from the commit's own prefix. Guessing a section invents a release note nobody wrote. Unprefixed commits go to the plain dated fallback list |
+| "The subject is terse, so I'll describe what the change probably did" | You read the log, not the diff. A changelog entry that states an effect the commit never claimed is a false release note that ships to users |
+| "No tag matches the range, so I'll start from the first commit" | That silently turns "since last release" into the project's whole history. State the range you could not resolve and ask, rather than emitting a thousand-line changelog |
+| "The merge commit summarizes the branch nicely, keep it alongside the branch's commits" | It double-counts: the merge subject and the commits underneath describe the same work. Use the PR title, drop the merge |
+| "The type is `fix:` so it belongs in Bug Fixes, even though the body says BREAKING CHANGE" | `BREAKING CHANGE` outranks the type prefix. A breaking change filed under Bug Fixes is the entry a reader upgrades past without noticing |
+
+## Verification
+
+Do not report the changelog as done until all of the following hold:
+
+- The range actually used (tag-to-tag, tag-to-HEAD, or `--since` date) is stated in the output, including when it was a fallback
+- Every commit in `git log <range> --oneline` is either an entry or a deliberate skip (merge commit, exact duplicate) — none dropped silently
+- No section header is emitted with zero entries under it
+- Breaking Changes, when present, is the first section
+- With `--output` / `--prepend`: the target file exists, the pre-existing content is still intact, and the new block sits at the top rather than replacing it

package/src/gdskills/bundled/skills/quality/commit/SKILL.md

@@ -1,15 +1,16 @@
 ---
 name: commit
-description: "Use when committing code changes and a well-structured conventional commit message is needed, with optional amend or selective staging."
+description: "Use when committing code changes and a well-structured conventional commit message is needed, with optional amend or selective staging. NOT for publishing the branch to the remote (use `push`) or opening a pull request (use `pr`)."
 triggers:
-  - "/commit"
-  - "Commit changes"
+  - "commit changes"
+  - "git commit"
+  - "conventional commit"
   - "Commit this"
   - "Save changes"
 metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
-  category: "workflow"
+  category: "quality"
   compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
 ---
@@ -29,7 +30,7 @@ Create well-structured git commits from current changes.
 If nothing is staged, intelligently stage relevant files:
 - Stage modified and new files that are part of the logical change
 - **NEVER** stage `.env`, credentials, secrets, or large binary files
-- Prefer `git add <specific files>` over `git add -A`
+- Stage explicit pathspecs (`git add <specific files>`); **NEVER** `git add -A`, `--all`, or `.`
 - Ask the user before staging untracked files that look unrelated to recent work
 
 ### Phase 3: Generate Commit Message
@@ -64,3 +65,23 @@ Show the result: `git log --oneline -1` and `git status`
 - NEVER add Co-Authored-By lines
 - If pre-commit hook fails: fix the issue, re-stage, create a NEW commit (don't amend)
 - Follow existing commit message conventions in the repository
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "Everything in the tree is my work, so staging it all is faster" | It is not all your work. A parallel agent, a running lane, or a half-finished edit of the user's rides along invisibly. Never stage by wildcard — list explicit pathspecs |
+| "The pre-commit hook failed on a file I didn't touch, `--no-verify` gets me past it" | The hook is the repository's gate, not an obstacle to route around. Fix the issue, re-stage, commit again |
+| "The last commit is mine and close enough — I'll amend it" | Amend only when the user explicitly asked. Amending a commit that is already pushed rewrites history someone else has fetched |
+| "The diff shows what happened, so `chore: updates` is enough" | The subject line is all a `git log` reader gets. Name the change and its scope in under 72 chars |
+| "The user is out of the loop on this untracked file, but it looks like mine" | Untracked files that look unrelated to recent work get a question, not a guess — that is how an `.env` or a scratch dump gets committed |
+
+## Verification
+
+Do not report the commit as done until all of the following hold:
+
+- `git log --oneline -1` shows the new commit, subject in `<type>(<scope>): <description>` form and under 72 chars
+- `git show --stat HEAD` lists exactly the intended files — no `.env`, credential, key, or large binary file
+- `git status` shows nothing else newly staged that you did not mean to include
+- `git show HEAD` carries no `Co-Authored-By` or generated-by trailer
+- Hooks ran — no `--no-verify` was passed; if a hook failed, a NEW commit exists rather than an amend

package/src/gdskills/bundled/skills/quality/db-migrate/SKILL.md

@@ -1,16 +1,17 @@
 ---
 name: db-migrate
-description: "Use when creating, applying, rolling back, or checking the status of database migrations."
+description: "Use when creating, applying, rolling back, or checking the status of database migrations. NOT for shipping the application release that carries the migration (use `deploy`)."
 triggers:
-  - "/db-migrate"
+  - "database migration"
+  - "db migrate"
+  - "migration status"
   - "Create migration"
   - "Run migrations"
-  - "Migration status"
   - "Rollback migration"
 metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
-  category: "database"
+  category: "quality"
   compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
 ---
@@ -64,3 +65,23 @@ Search for: `prisma/schema.prisma`, `ormconfig.*`, `data-source.ts`, `knexfile.*
 - NEVER apply to production without explicit confirmation
 - For destructive operations (drop table, remove column), double-warn
 - If ORM can't be detected, ask the user
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "The ORM autogenerated it, so the SQL must be correct" | Autogenerate routinely emits drop-and-recreate for a change that could have been an in-place alter. The generated file is a draft to read, not an answer to trust |
+| "It's only the dev database, no need to show the SQL first" | The same file is what runs against production later. The preview is the one moment the destructive statement can still be caught, and skipping it in dev means nobody ever read it |
+| "A rollback is unlikely, so an empty `down` is fine" | An empty `down` is worse than a missing one: the rollback reports success while changing nothing, and the schema silently stays ahead of the code |
+| "Two migration tools are configured; I'll use the one I know" | Each tool keeps its own history table. Picking the wrong one writes a migration the project's real tool will never see and cannot roll back. Ask which is authoritative |
+| "`prisma migrate dev` is the standard create command, just run it" | On a database with any drift it offers to reset — i.e. drop the data. Know what the create command does to an existing database before pointing it at one |
+
+## Verification
+
+Do not report the migration as done until all of the following hold:
+
+- The status command shows the intended migration in the intended state (applied, or pending for `create`), and no other migration changed state
+- The migration file carries both directions (up and down, or the ORM's equivalent) and the down path was read, not assumed
+- Any destructive statement (`DROP`, `ALTER … DROP`, `TRUNCATE`, a column removal) was shown to the user and confirmed in this conversation before it ran
+- The report names the detected tool, the migration name/id, and the environment the command ran against
+- For a production target: an explicit confirmation exists in this conversation, and the SQL preview preceded it

package/src/gdskills/bundled/skills/quality/dependency-update/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: dependency-update
-description: "Use when checking for outdated packages or upgrading dependencies with compatibility verification."
+description: "Use when checking for outdated packages or upgrading dependencies with compatibility verification. NOT for finding which packages are vulnerable in the first place (use `security-audit`)."
 triggers:
-  - "/dependency-update"
-  - "Update dependencies"
-  - "Upgrade packages"
+  - "update dependencies"
+  - "upgrade packages"
+  - "bump deps"
   - "Check outdated"
   - "Update npm packages"
 metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
-  category: "maintenance"
+  category: "quality"
   compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
 ---
@@ -79,3 +79,24 @@ npm run lint && npx tsc --noEmit && npm test && npm run build
 - Commit each group separately
 - Respect pinned versions
 - Check peer dependency warnings
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "The suite passes with all of them installed, so batching the majors saved five rounds" | When it breaks you cannot tell which major did it, and bisecting a batch costs more than the rounds you saved. Majors go one at a time, tests after each (Step 4) |
+| "Tests broke after the major bump — I'll migrate the call sites while I'm here" | Two fix attempts, then rollback. An open-ended API migration is a separate task with its own review; smuggling it into a dependency bump hides it from everyone |
+| "This version is pinned, but the pin looks stale" | A pin is a decision someone made, usually about a break you cannot see from `npm outdated`. Report it as pinned and let the user unpin it |
+| "`npm outdated` printed nothing, so the project is up to date" | It prints nothing when the lockfile belongs to a different package manager. Detect from the lockfile (`bun.lock`, `pnpm-lock.yaml`, `yarn.lock`) before concluding "current" |
+| "Peer dependency warnings are warnings, not errors" | They are the standard cause of the runtime failure that shows up two commits later, in something that was never touched. Carry them into the report |
+| "One commit for the whole update is tidier than three" | It makes the one bad package unrevertable without dropping the good ones. Commit per risk group, as Step 4 specifies |
+
+## Exit Criteria
+
+Do not report the update as done until all of the following hold:
+
+- `npm run lint && npx tsc --noEmit && npm test && npm run build` — or the project's own equivalents — all pass on the final tree
+- Every major was applied and tested on its own, with its own commit; no major shares a commit with another
+- Every package the plan proposed is accounted for in the report as updated, skipped (with the reason), or rolled back
+- `git status` is clean and the lockfile is committed alongside the manifest it belongs to
+- Pinned versions are unchanged, and peer dependency warnings that appeared are listed in the report