@mrciphersmith/keryx 0.2.98 → 0.2.100

package/src/gdskills/bundled/skills/planning/planner/SKILL.codex.md

@@ -4,6 +4,10 @@ description: >
   Generates roadmap, milestones, task breakdown, and dependency graph from PRD.
   Use when: dispatched by gproject-orchestrator Phase 6.
   NOT for: direct user invocation.
+triggers:
+  - "create plan"
+  - "roadmap"
+  - "task breakdown"
 metadata:
   version: 1.0.0
   compatible_harnesses: "cursor,codex,zed,opencode"
@@ -28,6 +32,19 @@ to feed into job-orchestrator or task-implementer.
 | 5 | Each milestone MUST be independently deployable / demonstrable |
 | 6 | Infrastructure and setup tasks come before feature tasks |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "This task is obviously needed even though no user story asks for it." | Iron Law 1: every task traces to a user story. An untraceable task is either scope the PRD did not agree to, or a story the PRD is missing — both are worth surfacing, and neither is fixed by adding the task quietly. |
+| "A single estimate is clearer to read than a three-point range." | Iron Law 3: estimates are ranges. A single number is read as a commitment, and the pessimistic case — the one that decides whether the milestone holds — was never stated. |
+| "These two tasks depend on each other, which is just how the work is." | Iron Law 2: dependencies form a DAG. A cycle means the decomposition is wrong, not that the work is circular. Split one task at the boundary where it stops needing the other. |
+| "Milestone 1 is already large, so this P0 story can move to Milestone 2." | Iron Law 4: P0 stories are in Milestone 1. If M1 is too large, the split goes elsewhere — deferring a P0 silently redefines what the PRD called essential. |
+| "Milestone 2 is a coherent chunk of work, even if it demos nothing on its own." | Iron Law 5: each milestone is independently deployable or demonstrable. A milestone with no demo has no completion signal, and slips are invisible until the next one that does. |
+| "Setup is boring — the feature tasks are what matters for the estimate." | Iron Law 6: infrastructure and setup come first, and they are estimated like anything else. Unestimated setup is the most common reason a critical path is wrong from day one. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/planner/SKILL.cursor.md

@@ -4,6 +4,10 @@ description: >
   Generates roadmap, milestones, task breakdown, and dependency graph from PRD.
   Use when: dispatched by gproject-orchestrator Phase 6.
   NOT for: direct user invocation.
+triggers:
+  - "create plan"
+  - "roadmap"
+  - "task breakdown"
 metadata:
   version: 1.0.0
   compatible_harnesses: "cursor,codex,zed,opencode"
@@ -28,6 +32,19 @@ to feed into job-orchestrator or task-implementer.
 | 5 | Each milestone MUST be independently deployable / demonstrable |
 | 6 | Infrastructure and setup tasks come before feature tasks |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "This task is obviously needed even though no user story asks for it." | Iron Law 1: every task traces to a user story. An untraceable task is either scope the PRD did not agree to, or a story the PRD is missing — both are worth surfacing, and neither is fixed by adding the task quietly. |
+| "A single estimate is clearer to read than a three-point range." | Iron Law 3: estimates are ranges. A single number is read as a commitment, and the pessimistic case — the one that decides whether the milestone holds — was never stated. |
+| "These two tasks depend on each other, which is just how the work is." | Iron Law 2: dependencies form a DAG. A cycle means the decomposition is wrong, not that the work is circular. Split one task at the boundary where it stops needing the other. |
+| "Milestone 1 is already large, so this P0 story can move to Milestone 2." | Iron Law 4: P0 stories are in Milestone 1. If M1 is too large, the split goes elsewhere — deferring a P0 silently redefines what the PRD called essential. |
+| "Milestone 2 is a coherent chunk of work, even if it demos nothing on its own." | Iron Law 5: each milestone is independently deployable or demonstrable. A milestone with no demo has no completion signal, and slips are invisible until the next one that does. |
+| "Setup is boring — the feature tasks are what matters for the estimate." | Iron Law 6: infrastructure and setup come first, and they are estimated like anything else. Unestimated setup is the most common reason a critical path is wrong from day one. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/planner/SKILL.md

@@ -4,6 +4,10 @@ description: >
   Generates roadmap, milestones, task breakdown, and dependency graph from PRD.
   Use when: dispatched by gproject-orchestrator Phase 6.
   NOT for: direct user invocation.
+triggers:
+  - "create plan"
+  - "roadmap"
+  - "task breakdown"
 metadata:
   version: 1.0.0
 ---
@@ -27,6 +31,19 @@ to feed into job-orchestrator or task-implementer.
 | 5 | Each milestone MUST be independently deployable / demonstrable |
 | 6 | Infrastructure and setup tasks come before feature tasks |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "This task is obviously needed even though no user story asks for it." | Iron Law 1: every task traces to a user story. An untraceable task is either scope the PRD did not agree to, or a story the PRD is missing — both are worth surfacing, and neither is fixed by adding the task quietly. |
+| "A single estimate is clearer to read than a three-point range." | Iron Law 3: estimates are ranges. A single number is read as a commitment, and the pessimistic case — the one that decides whether the milestone holds — was never stated. |
+| "These two tasks depend on each other, which is just how the work is." | Iron Law 2: dependencies form a DAG. A cycle means the decomposition is wrong, not that the work is circular. Split one task at the boundary where it stops needing the other. |
+| "Milestone 1 is already large, so this P0 story can move to Milestone 2." | Iron Law 4: P0 stories are in Milestone 1. If M1 is too large, the split goes elsewhere — deferring a P0 silently redefines what the PRD called essential. |
+| "Milestone 2 is a coherent chunk of work, even if it demos nothing on its own." | Iron Law 5: each milestone is independently deployable or demonstrable. A milestone with no demo has no completion signal, and slips are invisible until the next one that does. |
+| "Setup is boring — the feature tasks are what matters for the estimate." | Iron Law 6: infrastructure and setup come first, and they are estimated like anything else. Unestimated setup is the most common reason a critical path is wrong from day one. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/prd-creator/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: prd-creator
-description: "Use when a vague or unstructured request needs to be converted into a formal, testable Product Requirements Document."
+description: "Use when a vague or unstructured request needs to be converted into a formal, testable Product Requirements Document. NOT for: exploring which option to build before requirements exist (use brainstorm)."
 triggers:
-  - "Create a PRD"
+  - "create PRD"
+  - "product requirements"
+  - "specify feature"
   - "Formulate requirements"
   - "Write a product requirements document"
   - "Draft PRD"
@@ -184,7 +186,22 @@ Before finalizing PRD, the agent MUST verify:
 
 ---
 
-## 9. Intended Usage
+## 9. Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "The request is detailed, so there is nothing left to clarify." | Detail settles *what* to build; it almost never states non-goals, constraints, or how the result will be verified. Those are three of the six checklist items in Section 8, and a long request that omits them is exactly as ambiguous as a short one. |
+| "The missing constraint follows obviously from the stack, so I'll fill it in." | "The agent MUST NOT assume missing context" is a Section 2 prohibition, not advice. An inferred constraint reads in the finished PRD exactly like a confirmed one, and nothing downstream can tell them apart. Ask, or leave the gap visible. |
+| "The acceptance criteria describe the behaviour clearly, so Gherkin is just formatting." | Gherkin forces a concrete Given (the precondition) and a concrete Then (the observable outcome). Prose AC passes review while hiding both. Untestable criteria are a NO on the checklist and block finalization. |
+| "Five of the six checklist items are yes, so I'll finalize and note the sixth." | Any NO stops finalization. A PRD with a noted gap ships as a finished document and the note is the first thing dropped when it is summarized downstream. |
+| "A PRD for this feature already exists, so I'll write mine alongside it." | Section 6 requires updating `prd.md` in place and bumping its `Version`. Two PRDs for one feature means the implementer picks one, and it will not always be the newer. |
+| "I have asked 7 questions and ambiguity remains, so I'll write the PRD as best I can." | The 7-question limit is per iteration, not per request. Return the remaining questions to the user or orchestrator and run another round. |
+
+---
+
+## 10. Intended Usage
 
 Designed for multi-agent orchestration pipelines, such as:
 

package/src/gdskills/bundled/skills/planning/problem-definer/SKILL.codex.md

@@ -4,6 +4,10 @@ description: >
   Defines core problems, goals, non-goals, and success metrics from discovery data.
   Use when: dispatched by gproject-orchestrator Phase 1.
   NOT for: direct user invocation.
+triggers:
+  - "define problem"
+  - "goals non-goals"
+  - "success metrics"
 metadata:
   version: 1.0.0
   compatible_harnesses: "cursor,codex,zed,opencode"
@@ -26,6 +30,18 @@ This phase answers: "Why are we doing this?" and "How will we know we succeeded?
 | 4 | NEVER introduce solutions in the problem statement |
 | 5 | If discovery brief has low confidence areas, flag them — don't paper over |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "'Improve onboarding' is a real goal — the metric can come later." | Iron Law 1: every goal carries a measurable success metric, here. Phase 5 checks each user story against a goal's metric; a goal without one passes every check by being uncheckable. |
+| "The obvious fix is a dashboard, so the problem is 'users have no dashboard'." | Iron Law 4: no solutions in the problem statement. A problem phrased as a missing solution pre-decides the PRD, and the stack and architecture phases then optimise for the wrong thing with nothing to notice. |
+| "Non-goals are filler — two obvious ones are enough." | Iron Law 2 sets a floor of three, and non-goals are the only part of this document that stops scope growth later. The useful ones are the plausible features you are deliberately not building, not the absurd ones. |
+| "The discovery brief was thin on this area, but I can reason my way to the goal." | Iron Law 5: flag low-confidence areas. Reasoning over a gap produces a goal that reads as firm as the evidenced ones, and no later phase can tell them apart. |
+| "This problem is really about the database schema, which is the true root cause." | Iron Law 3: problems are stated from the user's perspective. A technical root cause belongs in the architecture phase; stated here it becomes the thing success is measured against, instead of what the user experiences. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/problem-definer/SKILL.cursor.md

@@ -4,6 +4,10 @@ description: >
   Defines core problems, goals, non-goals, and success metrics from discovery data.
   Use when: dispatched by gproject-orchestrator Phase 1.
   NOT for: direct user invocation.
+triggers:
+  - "define problem"
+  - "goals non-goals"
+  - "success metrics"
 metadata:
   version: 1.0.0
   compatible_harnesses: "cursor,codex,zed,opencode"
@@ -26,6 +30,18 @@ This phase answers: "Why are we doing this?" and "How will we know we succeeded?
 | 4 | NEVER introduce solutions in the problem statement |
 | 5 | If discovery brief has low confidence areas, flag them — don't paper over |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "'Improve onboarding' is a real goal — the metric can come later." | Iron Law 1: every goal carries a measurable success metric, here. Phase 5 checks each user story against a goal's metric; a goal without one passes every check by being uncheckable. |
+| "The obvious fix is a dashboard, so the problem is 'users have no dashboard'." | Iron Law 4: no solutions in the problem statement. A problem phrased as a missing solution pre-decides the PRD, and the stack and architecture phases then optimise for the wrong thing with nothing to notice. |
+| "Non-goals are filler — two obvious ones are enough." | Iron Law 2 sets a floor of three, and non-goals are the only part of this document that stops scope growth later. The useful ones are the plausible features you are deliberately not building, not the absurd ones. |
+| "The discovery brief was thin on this area, but I can reason my way to the goal." | Iron Law 5: flag low-confidence areas. Reasoning over a gap produces a goal that reads as firm as the evidenced ones, and no later phase can tell them apart. |
+| "This problem is really about the database schema, which is the true root cause." | Iron Law 3: problems are stated from the user's perspective. A technical root cause belongs in the architecture phase; stated here it becomes the thing success is measured against, instead of what the user experiences. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/problem-definer/SKILL.md

@@ -4,6 +4,10 @@ description: >
   Defines core problems, goals, non-goals, and success metrics from discovery data.
   Use when: dispatched by gproject-orchestrator Phase 1.
   NOT for: direct user invocation.
+triggers:
+  - "define problem"
+  - "goals non-goals"
+  - "success metrics"
 metadata:
   version: 1.0.0
 ---
@@ -25,6 +29,18 @@ This phase answers: "Why are we doing this?" and "How will we know we succeeded?
 | 4 | NEVER introduce solutions in the problem statement |
 | 5 | If discovery brief has low confidence areas, flag them — don't paper over |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "'Improve onboarding' is a real goal — the metric can come later." | Iron Law 1: every goal carries a measurable success metric, here. Phase 5 checks each user story against a goal's metric; a goal without one passes every check by being uncheckable. |
+| "The obvious fix is a dashboard, so the problem is 'users have no dashboard'." | Iron Law 4: no solutions in the problem statement. A problem phrased as a missing solution pre-decides the PRD, and the stack and architecture phases then optimise for the wrong thing with nothing to notice. |
+| "Non-goals are filler — two obvious ones are enough." | Iron Law 2 sets a floor of three, and non-goals are the only part of this document that stops scope growth later. The useful ones are the plausible features you are deliberately not building, not the absurd ones. |
+| "The discovery brief was thin on this area, but I can reason my way to the goal." | Iron Law 5: flag low-confidence areas. Reasoning over a gap produces a goal that reads as firm as the evidenced ones, and no later phase can tell them apart. |
+| "This problem is really about the database schema, which is the true root cause." | Iron Law 3: problems are stated from the user's perspective. A technical root cause belongs in the architecture phase; stated here it becomes the thing success is measured against, instead of what the user experiences. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/project-discovery/SKILL.codex.md

@@ -4,6 +4,10 @@ description: >
   Collects and structures initial project information from multiple sources.
   Use when: dispatched by gproject-orchestrator Phase 0.
   NOT for: direct user invocation — always called through orchestrator.
+triggers:
+  - "project discovery"
+  - "discover project"
+  - "initial analysis"
 metadata:
   version: 1.0.0
   compatible_harnesses: "cursor,codex,zed,opencode"
@@ -27,6 +31,18 @@ depends on the quality of discovery.
 | 4 | Web research MUST cite sources |
 | 5 | Codebase analysis MUST reference actual file paths |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "The domain is obvious from the request, so `D_domain` is safe to fill in." | Iron Law 1 and 2: an inference is an assumption and must be labelled one. `D_domain` is a decision every later phase treats as settled — an unlabelled guess here becomes a stack choice in Phase 2 nobody re-examines. |
+| "One area has no data, but the rest is solid — I'll note the gap and return `DONE`." | Iron Law 3: a critical area with no data is `NEEDS_CONTEXT` with a concrete A/B/C/D question. A gap recorded as a note is read by the next phase as something already handled. |
+| "I recognise this framework's layout, so I can describe the codebase without opening files." | Iron Law 5 requires actual file paths. A described layout that does not match the repository misdirects every phase that follows, and nothing downstream reads the code again to catch it. |
+| "The best-practice claim is common knowledge, so a citation is ceremony." | Iron Law 4: web research cites sources. Uncited common knowledge is where a stale convention enters the brief and survives to the architecture document as a constraint. |
+| "The user already explained this in the request — restating it in the brief is redundant." | The brief is the only artifact Phase 1 receives; the original request is not passed along. Anything left out of it is lost to the entire pipeline. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/project-discovery/SKILL.cursor.md

@@ -4,6 +4,10 @@ description: >
   Collects and structures initial project information from multiple sources.
   Use when: dispatched by gproject-orchestrator Phase 0.
   NOT for: direct user invocation — always called through orchestrator.
+triggers:
+  - "project discovery"
+  - "discover project"
+  - "initial analysis"
 metadata:
   version: 1.0.0
   compatible_harnesses: "cursor,codex,zed,opencode"
@@ -27,6 +31,18 @@ depends on the quality of discovery.
 | 4 | Web research MUST cite sources |
 | 5 | Codebase analysis MUST reference actual file paths |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "The domain is obvious from the request, so `D_domain` is safe to fill in." | Iron Law 1 and 2: an inference is an assumption and must be labelled one. `D_domain` is a decision every later phase treats as settled — an unlabelled guess here becomes a stack choice in Phase 2 nobody re-examines. |
+| "One area has no data, but the rest is solid — I'll note the gap and return `DONE`." | Iron Law 3: a critical area with no data is `NEEDS_CONTEXT` with a concrete A/B/C/D question. A gap recorded as a note is read by the next phase as something already handled. |
+| "I recognise this framework's layout, so I can describe the codebase without opening files." | Iron Law 5 requires actual file paths. A described layout that does not match the repository misdirects every phase that follows, and nothing downstream reads the code again to catch it. |
+| "The best-practice claim is common knowledge, so a citation is ceremony." | Iron Law 4: web research cites sources. Uncited common knowledge is where a stale convention enters the brief and survives to the architecture document as a constraint. |
+| "The user already explained this in the request — restating it in the brief is redundant." | The brief is the only artifact Phase 1 receives; the original request is not passed along. Anything left out of it is lost to the entire pipeline. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/project-discovery/SKILL.md

@@ -4,6 +4,10 @@ description: >
   Collects and structures initial project information from multiple sources.
   Use when: dispatched by gproject-orchestrator Phase 0.
   NOT for: direct user invocation — always called through orchestrator.
+triggers:
+  - "project discovery"
+  - "discover project"
+  - "initial analysis"
 metadata:
   version: 1.0.0
 ---
@@ -26,6 +30,18 @@ depends on the quality of discovery.
 | 4 | Web research MUST cite sources |
 | 5 | Codebase analysis MUST reference actual file paths |
 
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "The domain is obvious from the request, so `D_domain` is safe to fill in." | Iron Law 1 and 2: an inference is an assumption and must be labelled one. `D_domain` is a decision every later phase treats as settled — an unlabelled guess here becomes a stack choice in Phase 2 nobody re-examines. |
+| "One area has no data, but the rest is solid — I'll note the gap and return `DONE`." | Iron Law 3: a critical area with no data is `NEEDS_CONTEXT` with a concrete A/B/C/D question. A gap recorded as a note is read by the next phase as something already handled. |
+| "I recognise this framework's layout, so I can describe the codebase without opening files." | Iron Law 5 requires actual file paths. A described layout that does not match the repository misdirects every phase that follows, and nothing downstream reads the code again to catch it. |
+| "The best-practice claim is common knowledge, so a citation is ceremony." | Iron Law 4: web research cites sources. Uncited common knowledge is where a stale convention enters the brief and survives to the architecture document as a constraint. |
+| "The user already explained this in the request — restating it in the brief is redundant." | The brief is the only artifact Phase 1 receives; the original request is not passed along. Anything left out of it is lost to the entire pipeline. |
+
 ---
 
 ## Input Contract

package/src/gdskills/bundled/skills/planning/spec-writer/SKILL.codex.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.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"
@@ -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"
@@ -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.