jhste-skills 0.1.0

package/README.md

@@ -0,0 +1,254 @@
+# jhste-skills
+
+Languages: [English](README.md) · [한국어](README.ko.md) · [中文](README.zh.md) · [日本語](README.ja.md)
+
+An installable working-rules kit that helps AI coding agents consistently follow your engineering standards.
+
+`jhste-skills` gives Codex, Claude Code, and other AI coding agents a shared engineering workflow. It helps agents verify assumptions before editing, respect repo-local instructions, keep API/database/automation boundaries clear, check whether each module has one clear responsibility under SRP (Single Responsibility Principle), run changed-file guards, and perform a red-team code review before claiming work is complete.
+
+This tool does **not** take over your project. Repo-local `AGENTS.md`, `CLAUDE.md`, and docs remain authoritative. The default setup is advisory, marker-managed, and designed to be low-risk to try.
+
+Skills are designed to be used automatically when the situation calls for them. For example, when an agent edits API code, it is guided to use the API/database boundary skill; before completion, it is guided to use the red-team review skill. You can also call a skill directly, for example: `use jhste-engineering-judgment to review this change premise`, or `run jhste-red-team-review on this diff`.
+
+## Why install this?
+
+AI coding agents are fast, but they fail in predictable ways:
+
+- They silently accept unclear requirements or incorrect premises.
+- They expand the scope while trying to be helpful.
+- They mix UI, route/controller, service, database, and side-effect responsibilities in one place, breaking the “one module, one responsibility” principle (SRP).
+- They hide failures or produce unsafe logs.
+- They say “done” before the changed code has been checked.
+- They forget repo-specific rules when you switch machines or repositories.
+
+`jhste-skills` gives agents a repeatable loop for reducing those failures:
+
+```text
+Before a non-trivial code change:
+  check the goal, premise, ownership seam, data contract, failure path, and SRP responsibility
+
+While editing:
+  treat repo-local instructions as the authority
+
+After changing code:
+  run a fast changed-file guard when available
+
+Before saying “done”:
+  run a read-only red-team code review
+
+If warnings appear:
+  attempt a bounded fix, re-check, and stop instead of looping forever
+```
+
+The expected result is smaller diffs, clearer SRP boundaries, safer API/database code, fewer silent assumptions, and more honest completion reports.
+
+## Who should install this?
+
+Install `jhste-skills` if you:
+
+- use Codex, Claude Code, or another coding agent across multiple repositories;
+- want agents to verify assumptions before non-trivial code changes;
+- want existing repo docs to remain the source of authority;
+- want lightweight advisory checks before commit or before declaring work complete;
+- care about SRP, API/database boundaries, safe logging, input validation, side effects, and automation reliability;
+- want to restore the same AI coding workflow across machines and repositories.
+
+You may not need this if you only want a single prompt file, want strict CI enforcement immediately after installation, do not want generated `.jhste/` files or bridge blocks, or expect this tool to automatically refactor code.
+
+## Quick start
+
+```bash
+npx jhste-skills install
+```
+
+Or install the CLI globally with npm and use it from any repository:
+
+```bash
+npm install -g jhste-skills
+jhste-skills install
+```
+
+Use `npx` when you want a one-off run without a global install. Use `npm install -g` when you want `jhste-skills` available as a normal shell command.
+
+The default install uses Normal mode.
+
+- Installs all bundled skills: jhste core skills + vendored workflow skills.
+- Creates `.jhste/profile.yaml` when missing.
+- Adds or refreshes a marker-managed bridge block in `AGENTS.md` or `CLAUDE.md` when project guidance is enabled.
+- Installs an advisory pre-commit hook when safe.
+- Does not modify CI, target `package.json`, lockfiles, or source code.
+
+To connect another repository:
+
+```bash
+cd /path/to/another-repo
+jhste-skills connect
+```
+
+To install only the jhste core guardrail skills:
+
+```bash
+npx jhste-skills install --skill-set core
+```
+
+To run the changed-file guard manually:
+
+```bash
+jhste-skills guard --scope changed --format text --fail-on error
+```
+
+To run an optional repo-wide advisory scan:
+
+```bash
+jhste-skills deep-scan
+```
+
+To remove managed outputs:
+
+```bash
+jhste-skills uninstall --yes --repo /path/to/repo
+```
+
+`uninstall` removes managed hooks, marker-managed bridge blocks, and manifest-managed skill directories. It does not touch non-managed files. `.jhste/profile.yaml` is removed only when it still matches the generated shape; use `--force-profile` only after reviewing a modified profile.
+
+## Install modes
+
+```text
+Minimal  - installs only jhste core skills; no project files or hooks
+Normal   - recommended default; all bundled skills + project profile/bridge + advisory pre-commit hook
+Full     - all bundled skills + profile/bridge + advisory pre-commit/pre-push hooks + deep scan
+Custom   - asks effect-oriented questions so you can choose the setup
+```
+
+`Full` still follows the safety contract. It does not overwrite non-managed hooks, source files, CI, `package.json`, or lockfiles, and it does not enable strict mode. Interactive Full mode only asks how automatic checks should behave: warning-only, block at commit time, or block at commit and push time. `--yes` uses warning-only unless `--hooks blocking` is explicit.
+
+## Safety contract
+
+`jhste-skills` is safe-by-default:
+
+- repo-local `AGENTS.md`, `CLAUDE.md`, and docs remain authoritative;
+- explicit user instructions set task scope, but do not silently override verified safety, privacy, data-loss, or repo-architecture constraints;
+- default install does not modify CI;
+- default install does not modify target `package.json` or lockfiles;
+- default install does not automatically refactor source code;
+- managed hooks are advisory by default;
+- strict mode requires explicit opt-in;
+- bridge blocks use `<!-- jhste-skills:start -->` / `<!-- jhste-skills:end -->` markers;
+- guard output is review evidence, not proof by itself;
+- guard runtime/config failures must be reported separately from rule violations;
+- install/update/uninstall flows leave non-managed hooks, bridge text, and skill directories untouched.
+
+## Core jhste skills
+
+These are the jhste-authored guardrail skills. They are installed by default as part of the bundled skill set. Use `--skill-set core` to install only these core skills.
+
+| Skill | Use it when | What it helps reduce |
+|---|---|---|
+| [`setup`](skills/setup/SKILL.md)<br>A safe setup skill that prevents install/connect/update flows from overwriting existing project instructions | Installing or connecting the kit to a repository | Unsafe overwrite, unmanaged hook conflict, repo instruction replacement |
+| [`jhste-engineering-judgment`](skills/jhste-engineering-judgment/SKILL.md)<br>A pre-change judgment skill that verifies goal, premise, scope, seam, and failure path before code edits | Before non-trivial code changes | Blind agreement, scope creep, unverified assumptions, unclear seams |
+| [`jhste-code-quality`](skills/jhste-code-quality/SKILL.md)<br>A code-quality skill for input validation, observable failure handling, and secret-safe logging | Writing or reviewing application code | Unvalidated input, silent failure, secret logging, oversized files |
+| [`jhste-architecture-review`](skills/jhste-architecture-review/SKILL.md)<br>An architecture review skill for module boundaries, side-effect placement, and possible SRP violations | Changing module boundaries or app structure | Pass-through abstraction, mixed responsibility, side-effect leakage |
+| [`jhste-db-api-boundary`](skills/jhste-db-api-boundary/SKILL.md)<br>A boundary skill that checks responsibility and data contracts across API routes, services, repositories, and SQL | Touching API, controller, service, repository, SQL, or persistence code | Fat routes, unsafe SQL, missing auth/data scoping, leaky DTOs |
+| [`jhste-crawler-automation`](skills/jhste-crawler-automation/SKILL.md)<br>An automation skill for crawler/scraper/worker/scheduler producer-consumer seams and side effects | Touching crawlers, scrapers, workers, schedulers, or browser automation | Fragile automation, unclear producer/consumer boundaries, hidden side effects |
+| [`jhste-red-team-review`](skills/jhste-red-team-review/SKILL.md)<br>A read-only red-team code review skill that aggressively re-checks changed code before completion | Before declaring non-trivial code work complete | Premature “done”, missed null/auth/env/write/API/performance risks |
+
+## Bundled workflow skills
+
+Normal install also includes 14 workflow skills vendored from Matt Pocock's [`mattpocock/skills`](https://github.com/mattpocock/skills). These are useful for debugging, planning, architecture, issue workflows, prototyping, and handoffs. Use `--skill-set core` if you do not want them installed.
+
+| Skill | Use it when |
+|---|---|
+| [`diagnose`](skills/diagnose/SKILL.md)<br>A diagnosis-loop skill that forces reproduce, minimize, hypothesize, instrument, fix, and regression-check steps | Diagnosing a hard bug or performance regression systematically |
+| [`diagnosing-bugs`](skills/diagnosing-bugs/SKILL.md)<br>A debugging skill that narrows root cause around a fast pass/fail feedback loop | You need a reproduce → minimise → hypothesise → instrument → fix loop |
+| [`grill-me`](skills/grill-me/SKILL.md)<br>A skill that asks persistent questions until a plan or design has no obvious gaps | You want the agent to question your plan or design until it becomes clear |
+| [`grill-with-docs`](skills/grill-with-docs/SKILL.md)<br>A design-challenge skill that documents domain terms and decisions while questioning the plan | You want project vocabulary and docs/ADRs updated during the questioning process |
+| [`grilling`](skills/grilling/SKILL.md)<br>A general grilling skill for pressure-testing plans and designs before implementation | You need a general plan/design stress-test questioning loop |
+| [`domain-modeling`](skills/domain-modeling/SKILL.md)<br>A skill for sharpening project terminology, domain models, and architectural decisions | Refining domain terms, ubiquitous language, or architectural decisions |
+| [`codebase-design`](skills/codebase-design/SKILL.md)<br>A codebase design skill for deep modules, small interfaces, and clear seams | You need better module interface, seam, and testability vocabulary |
+| [`improve-codebase-architecture`](skills/improve-codebase-architecture/SKILL.md)<br>An architecture skill that finds shallow modules and coupling that can be improved into deeper modules | You want to find deepening opportunities and reduce architectural friction |
+| [`prototype`](skills/prototype/SKILL.md)<br>A prototyping skill for validating logic or UI direction with throwaway code before implementation | You want a throwaway logic/UI prototype before committing to an approach |
+| [`to-prd`](skills/to-prd/SKILL.md)<br>A PRD-writing skill that structures conversation context into product requirements | You want to turn conversation context into a PRD |
+| [`to-issues`](skills/to-issues/SKILL.md)<br>A skill that breaks a plan into independently workable vertical-slice issues | You want to split a plan into implementation issues that can be worked independently |
+| [`triage`](skills/triage/SKILL.md)<br>An issue triage skill that classifies issues and decides next actions through a structured workflow | You want issues handled through a structured triage workflow |
+| [`handoff`](skills/handoff/SKILL.md)<br>A handoff skill that compresses context so the next agent or session can continue | You want to hand context to another agent or session |
+| [`write-a-skill`](skills/write-a-skill/SKILL.md)<br>A skill-writing skill for creating agent skills with the right structure and progressive disclosure | You want to create or refine an agent skill |
+
+## Attribution: Matt Pocock skills
+
+This repository vendors the 14 skills listed above from Matt Pocock's [`mattpocock/skills`](https://github.com/mattpocock/skills).
+
+Those skills are vendored under the upstream MIT License. This repository preserves the required copyright/license notice and records the imported sources.
+
+- Upstream: [`mattpocock/skills`](https://github.com/mattpocock/skills)
+- License: MIT
+- Attribution: [`vendor/matt-pocock/NOTICE.md`](vendor/matt-pocock/NOTICE.md)
+- Upstream license copy: [`vendor/matt-pocock/LICENSE`](vendor/matt-pocock/LICENSE)
+- Allowlist: [`vendor/matt-pocock/allowlist.json`](vendor/matt-pocock/allowlist.json)
+- Source lock: [`vendor/matt-pocock/source-lock.json`](vendor/matt-pocock/source-lock.json)
+
+Do not add vendored skills outside the allowlist without separate review. When updating vendored copies, refresh the source lock and review the diff.
+
+## CLI commands
+
+```bash
+jhste-skills install
+jhste-skills connect
+jhste-skills guard
+jhste-skills deep-scan
+jhste-skills tune
+jhste-skills baseline
+jhste-skills sync
+jhste-skills update
+jhste-skills hooks
+jhste-skills uninstall
+```
+
+See [`docs/CLI.md`](docs/CLI.md) for detailed command behavior.
+
+## Recommended rollout
+
+1. Run the default install and dogfood the advisory workflow first.
+2. Keep advisory hooks at first. Use `--skip-hooks` if you do not want commit-time checks, and enable blocking mode only after reviewing noise and false positives.
+3. Start with the default 300-line advisory limit. Use `--line-limit-mode blocking` only when the team is ready for warning-level hook enforcement.
+4. During code changes, run `guard --scope changed --format text --fail-on error` manually.
+5. Before non-trivial code changes, use `jhste-engineering-judgment` to check scope, seam, failure path, data contract, assumptions, and each changed class/module/function's main responsibility.
+6. Before declaring non-trivial code work complete, use `jhste-red-team-review`. Skip docs-only, comment-only, formatting-only, and trivial rename-only changes.
+7. Limit fix + re-review loops to two cycles, then report remaining risks instead of looping indefinitely.
+8. Create a baseline only after reviewing existing debt. Treat the baseline as a known-issues ledger and use ratchet behavior to stop new debt, not to hide scanner failures.
+
+## Repository layout
+
+```text
+skills/                 AI-readable skill guidance
+rules/                  Stable rule metadata used by skills and scans
+packs/                  Core, web, API, database, and crawler rule bundles
+adapters/               Codex, Claude, and generic adapter notes
+cli/                    install, uninstall, deep-scan, guard, hooks, tune, and baseline commands
+vendor/matt-pocock/     Matt Pocock allowlist, source lock, license, and attribution
+examples/profile.yaml   Default advisory profile example
+```
+
+## Verification
+
+```bash
+npm test
+npm run public-safety:check
+npm run vendor:check
+npm run docs:check
+```
+
+See [`docs/ACCEPTANCE_CHECK.md`](docs/ACCEPTANCE_CHECK.md) for release acceptance notes.
+
+## Philosophy
+
+`jhste-skills` is not a tool for giving agents more authority. It is a tool for making fast agents more reliable.
+
+- Do not agree blindly.
+- Do not overwrite local project authority.
+- Keep changes scoped.
+- Name responsibility boundaries from an SRP perspective.
+- Make failures observable.
+- Treat automated guard output as evidence, not proof.
+- Run a red-team code review before calling non-trivial work complete.
+
+Fast agents need guardrails. `jhste-skills` gives them a repo-respecting engineering workflow.

package/README.zh.md

@@ -0,0 +1,254 @@
+# jhste-skills
+
+Languages: [English](README.md) · [한국어](README.ko.md) · [中文](README.zh.md) · [日本語](README.ja.md)
+
+一套可安装的工作规则工具包，帮助 AI 编程代理稳定遵循你设定的工程标准。
+
+`jhste-skills` 为 Codex、Claude Code 等 AI 编程代理提供一套共享的工程工作流。它帮助代理在修改代码前验证前提，优先遵循仓库本地说明，保持 API/database/automation 边界清晰，从 SRP（Single Responsibility Principle，单一职责原则）的角度检查每个模块是否只有一个明确职责，运行 changed-file guard，并在声明完成前执行 red-team code review。
+
+这个工具不会接管你的项目。仓库内的 `AGENTS.md`、`CLAUDE.md` 和 docs 始终是权威来源。默认设置是 advisory 模式，使用 marker-managed 方式管理变更，设计目标是低风险、容易试用。
+
+Skills 设计为在需要时由代理自动使用。例如，代理修改 API 代码时会被引导使用 API/database boundary skill；在完成前会被引导使用 red-team review skill。你也可以直接调用某个 skill，例如：`use jhste-engineering-judgment to review this change premise`，或 `run jhste-red-team-review on this diff`。
+
+## 为什么要安装？
+
+AI 编程代理很快，但经常以可预测的方式失败：
+
+- 默默接受不清晰的需求或错误前提。
+- 为了“帮忙”而扩大修改范围。
+- 把 UI、route/controller、service、database、side effect 职责混在一个地方，破坏“一个模块，一个职责”原则（SRP）。
+- 隐藏失败，或产生不安全的日志。
+- 在变更代码尚未检查前就说“完成”。
+- 当你切换机器或仓库时，忘记仓库特定规则。
+
+`jhste-skills` 为代理提供一个可重复的工作循环，减少这些失败：
+
+```text
+在 non-trivial code change 前：
+  检查目标、前提、ownership seam、data contract、failure path、SRP 职责
+
+修改过程中：
+  将 repo-local instructions 视为权威
+
+代码修改后：
+  在可用时运行快速 changed-file guard
+
+在说“完成”前：
+  运行 read-only red-team code review
+
+如果出现 warning：
+  尝试 bounded fix，重新检查，然后停止，避免无限循环
+```
+
+预期结果是更小的 diff、更清晰的 SRP 边界、更安全的 API/database 代码、更少的 silent assumption，以及更诚实的完成报告。
+
+## 谁适合安装？
+
+如果你符合以下情况，`jhste-skills` 值得安装：
+
+- 在多个仓库中使用 Codex、Claude Code 或其他 coding agent；
+- 希望代理在 non-trivial code change 前验证前提；
+- 希望现有 repo docs 继续作为权威来源；
+- 希望在提交前或声明完成前加入轻量 advisory check；
+- 重视 SRP、API/database boundary、safe logging、input validation、side effect、automation reliability；
+- 希望在不同机器和仓库之间快速恢复相同的 AI 编程工作习惯。
+
+如果你只想要一个 prompt 文件，或希望安装后立即启用 strict CI enforcement，或不想生成 `.jhste/` 文件和 bridge block，或期待这个工具自动重构代码，那它可能不适合你。
+
+## 快速开始
+
+```bash
+npx jhste-skills install
+```
+
+也可以用 npm 全局安装 CLI，然后在任意仓库中使用。
+
+```bash
+npm install -g jhste-skills
+jhste-skills install
+```
+
+如果只想临时运行一次，请使用 `npx`。如果希望把 `jhste-skills` 作为常用 shell 命令，请使用 `npm install -g`。
+
+默认安装使用 Normal mode。
+
+- 安装全部 bundled skills：jhste core skills + vendored workflow skills。
+- 如果缺失，则创建 `.jhste/profile.yaml`。
+- 启用 project guidance 时，在 `AGENTS.md` 或 `CLAUDE.md` 中添加或刷新 marker-managed bridge block。
+- 在安全时安装 advisory pre-commit hook。
+- 不修改 CI、目标仓库的 `package.json`、lockfile 或 source code。
+
+连接另一个仓库：
+
+```bash
+cd /path/to/another-repo
+jhste-skills connect
+```
+
+只安装 jhste core guardrail skills：
+
+```bash
+npx jhste-skills install --skill-set core
+```
+
+手动运行 changed-file guard：
+
+```bash
+jhste-skills guard --scope changed --format text --fail-on error
+```
+
+选择性运行 repo-wide advisory scan：
+
+```bash
+jhste-skills deep-scan
+```
+
+移除 managed outputs：
+
+```bash
+jhste-skills uninstall --yes --repo /path/to/repo
+```
+
+`uninstall` 会移除 managed hook、marker-managed bridge block 和 manifest-managed skill directory。它不会触碰 non-managed file。只有当 `.jhste/profile.yaml` 仍然匹配 generated shape 时才会删除；如果 profile 已被修改，请先审查内容，再显式使用 `--force-profile`。
+
+## 安装模式
+
+```text
+Minimal  - 只安装 jhste core skills；不创建 project file 或 hook
+Normal   - 推荐默认值；all bundled skills + project profile/bridge + advisory pre-commit hook
+Full     - all bundled skills + profile/bridge + advisory pre-commit/pre-push hooks + deep scan
+Custom   - 通过面向效果的问题自定义安装范围
+```
+
+`Full` 也遵守 safety contract。它不会覆盖 non-managed hook、source file、CI、`package.json` 或 lockfile，也不会启用 strict mode。Interactive Full mode 只询问自动检查行为：warning only、commit-time block，或 commit/push-time block。除非显式传入 `--hooks blocking`，否则 `--yes` 使用 warning-only。
+
+## Safety contract
+
+`jhste-skills` 默认安全：
+
+- repo-local `AGENTS.md`、`CLAUDE.md` 和 docs 始终是权威；
+- 用户的显式指令决定任务 scope，但不会悄悄绕过已经验证的 safety/privacy/data-loss/repo-architecture constraint；
+- 默认安装不修改 CI；
+- 默认安装不修改目标 `package.json` 或 lockfile；
+- 默认安装不会自动重构 source code；
+- managed hook 默认是 advisory；
+- strict mode 需要显式 opt-in；
+- bridge block 使用 `<!-- jhste-skills:start -->` / `<!-- jhste-skills:end -->` marker；
+- guard output 是 review evidence，不是 proof；
+- guard runtime/config failure 必须与 rule violation 分开报告；
+- install/update/uninstall flow 不触碰 non-managed hook、bridge text 或 skill directory。
+
+## Core jhste skills
+
+以下是 jhste 编写的 guardrail skills。它们默认作为 bundled skill set 的一部分安装。使用 `--skill-set core` 可以只安装这些 core skills。
+
+| Skill | 何时使用 | 帮助减少什么 |
+|---|---|---|
+| [`setup`](skills/setup/SKILL.md)<br>安全安装 skill，避免 install/connect/update 覆盖现有项目说明 | 安装 kit 或连接仓库时 | Unsafe overwrite, unmanaged hook conflict, repo instruction replacement |
+| [`jhste-engineering-judgment`](skills/jhste-engineering-judgment/SKILL.md)<br>pre-change 判断 skill，在改代码前验证目标、前提、scope、seam 和 failure path | non-trivial code change 前 | Blind agreement, scope creep, unverified assumption, unclear seam |
+| [`jhste-code-quality`](skills/jhste-code-quality/SKILL.md)<br>检查 input validation、observable failure handling、secret-safe logging 的代码质量 skill | 编写或 review application code 时 | Unvalidated input, silent failure, secret logging, oversized file |
+| [`jhste-architecture-review`](skills/jhste-architecture-review/SKILL.md)<br>检查 module boundary、side-effect placement 和 SRP 风险的架构 review skill | 修改 module boundary 或 app structure 时 | Pass-through abstraction, mixed responsibility, side-effect leakage |
+| [`jhste-db-api-boundary`](skills/jhste-db-api-boundary/SKILL.md)<br>检查 API route、service、repository、SQL 之间职责和 data contract 的 boundary skill | 修改 API、controller、service、repository、SQL、persistence code 时 | Fat route, unsafe SQL, missing auth/data scoping, leaky DTO |
+| [`jhste-crawler-automation`](skills/jhste-crawler-automation/SKILL.md)<br>检查 crawler/scraper/worker/scheduler 的 producer-consumer seam 和 side effect 的 automation skill | 修改 crawler、scraper、worker、scheduler、browser automation 时 | Fragile automation, unclear producer/consumer boundary, hidden side effect |
+| [`jhste-red-team-review`](skills/jhste-red-team-review/SKILL.md)<br>read-only red-team code review skill，在完成前主动攻击性复查变更代码 | non-trivial code work 完成声明前 | Premature “done”, missed null/auth/env/write/API/performance risk |
+
+## Bundled workflow skills
+
+Normal install 还会安装 14 个从 Matt Pocock 的 [`mattpocock/skills`](https://github.com/mattpocock/skills) vendoring 的 workflow skills。它们适用于 debugging、planning、architecture、issue workflow、prototyping 和 handoff。若不想安装它们，请使用 `--skill-set core`。
+
+| Skill | 何时使用 |
+|---|---|
+| [`diagnose`](skills/diagnose/SKILL.md)<br>强制执行 reproduce、minimize、hypothesize、instrument、fix、regression-check 的诊断循环 skill | 系统性诊断 hard bug 或 performance regression 时 |
+| [`diagnosing-bugs`](skills/diagnosing-bugs/SKILL.md)<br>围绕快速 pass/fail feedback loop 缩小 root cause 的 debugging skill | 需要 reproduce → minimise → hypothesise → instrument → fix 循环时 |
+| [`grill-me`](skills/grill-me/SKILL.md)<br>持续提问，直到计划或设计没有明显空洞的 skill | 希望 agent 持续追问计划或设计直到清晰时 |
+| [`grill-with-docs`](skills/grill-with-docs/SKILL.md)<br>在提问过程中记录 domain terms 和 decisions 的设计验证 skill | 希望在提问过程中更新 project vocabulary 和 docs/ADR 时 |
+| [`grilling`](skills/grilling/SKILL.md)<br>在实现前用压力问题验证计划和设计的通用 grilling skill | 需要通用 plan/design stress-test 问题循环时 |
+| [`domain-modeling`](skills/domain-modeling/SKILL.md)<br>让项目术语、domain model、architectural decision 更清晰的 skill | 调整 domain term、ubiquitous language、architectural decision 时 |
+| [`codebase-design`](skills/codebase-design/SKILL.md)<br>用于 deep module、小 interface、清晰 seam 的代码库设计 skill | 需要更好的 module interface、seam、testability vocabulary 时 |
+| [`improve-codebase-architecture`](skills/improve-codebase-architecture/SKILL.md)<br>发现 shallow module 和 coupling，并寻找 deepening opportunity 的架构 skill | 想寻找 deepening opportunity 并减少 architectural friction 时 |
+| [`prototype`](skills/prototype/SKILL.md)<br>在正式实现前用 throwaway code 验证 logic 或 UI 方向的 prototyping skill | 想在确定 approach 前做 throwaway logic/UI prototype 时 |
+| [`to-prd`](skills/to-prd/SKILL.md)<br>把对话 context 组织成 product requirements 的 PRD 写作 skill | 想把对话 context 转成 PRD 时 |
+| [`to-issues`](skills/to-issues/SKILL.md)<br>把计划拆成可独立处理的 vertical-slice issues 的 skill | 想把 plan 拆成可独立推进的 implementation issues 时 |
+| [`triage`](skills/triage/SKILL.md)<br>通过结构化 workflow 分类 issue 并决定下一步行动的 triage skill | 想用 structured triage workflow 处理 issue 时 |
+| [`handoff`](skills/handoff/SKILL.md)<br>压缩 context，让下一个 agent 或 session 能继续工作的 handoff skill | 想把 context 交给另一个 agent 或 session 时 |
+| [`write-a-skill`](skills/write-a-skill/SKILL.md)<br>用正确结构和 progressive disclosure 创建 agent skill 的 skill-writing skill | 想创建或改进 agent skill 时 |
+
+## Attribution: Matt Pocock skills
+
+本仓库从 Matt Pocock 的 [`mattpocock/skills`](https://github.com/mattpocock/skills) vendoring 了上面列出的 14 个 skills。
+
+这些 skills 按 upstream MIT License vendoring。本仓库保留所需 copyright/license notice，并记录导入来源。
+
+- Upstream: [`mattpocock/skills`](https://github.com/mattpocock/skills)
+- License: MIT
+- Attribution: [`vendor/matt-pocock/NOTICE.md`](vendor/matt-pocock/NOTICE.md)
+- Upstream license copy: [`vendor/matt-pocock/LICENSE`](vendor/matt-pocock/LICENSE)
+- Allowlist: [`vendor/matt-pocock/allowlist.json`](vendor/matt-pocock/allowlist.json)
+- Source lock: [`vendor/matt-pocock/source-lock.json`](vendor/matt-pocock/source-lock.json)
+
+未经单独审查，不要添加 allowlist 外的 vendored skill。更新 vendored copy 时，必须刷新 source lock 并审查 diff。
+
+## CLI commands
+
+```bash
+jhste-skills install
+jhste-skills connect
+jhste-skills guard
+jhste-skills deep-scan
+jhste-skills tune
+jhste-skills baseline
+jhste-skills sync
+jhste-skills update
+jhste-skills hooks
+jhste-skills uninstall
+```
+
+详细 command behavior 请参考 [`docs/CLI.md`](docs/CLI.md)。
+
+## 推荐 rollout
+
+1. 先运行默认安装，并 dogfood advisory workflow。
+2. 一开始保留 advisory hook。如果不想要 commit-time check，使用 `--skip-hooks`；只有在充分检查 noise 和 false positive 后才启用 blocking mode。
+3. 先使用默认 300-line advisory limit。只有团队准备接受 warning-level hook enforcement 时，才使用 `--line-limit-mode blocking`。
+4. 修改代码时，手动运行 `guard --scope changed --format text --fail-on error`。
+5. non-trivial code change 前，用 `jhste-engineering-judgment` 检查 scope、seam、failure path、data contract、assumption，以及每个 changed class/module/function 的 main responsibility。
+6. non-trivial code work 完成声明前，使用 `jhste-red-team-review`。跳过 docs-only、comment-only、formatting-only、trivial rename-only 变更。
+7. fix + re-review 最多重复两轮，然后报告剩余 risk，避免无限循环。
+8. 只有在审查 existing debt 后才创建 baseline。将 baseline 视为 known-issues ledger，用 ratchet 阻止 new debt，而不是隐藏 scanner failure。
+
+## Repository layout
+
+```text
+skills/                 AI-readable skill guidance
+rules/                  skills 和 scan 使用的 stable rule metadata
+packs/                  core、web、API、database、crawler rule bundle
+adapters/               Codex、Claude、generic adapter notes
+cli/                    install、uninstall、deep-scan、guard、hooks、tune、baseline commands
+vendor/matt-pocock/     Matt Pocock allowlist、source lock、license、attribution
+examples/profile.yaml   default advisory profile example
+```
+
+## Verification
+
+```bash
+npm test
+npm run public-safety:check
+npm run vendor:check
+npm run docs:check
+```
+
+Release acceptance notes 请参考 [`docs/ACCEPTANCE_CHECK.md`](docs/ACCEPTANCE_CHECK.md)。
+
+## 哲学
+
+`jhste-skills` 不是为了给 agent 更多权限。它是为了让快速的 agent 更可靠。
+
+- 不盲目同意。
+- 不覆盖 local project authority。
+- 保持变更范围受控。
+- 从 SRP 角度命名 responsibility boundary。
+- 让 failure observable。
+- 将 automated guard output 视为 evidence，而不是 proof。
+- 在称 non-trivial work 完成前执行 red-team code review。
+
+快速的 agent 需要 guardrail。`jhste-skills` 为它们提供 repo-respecting engineering workflow。

package/adapters/claude/README.md

@@ -0,0 +1,7 @@
+# Claude adapter
+
+The Claude adapter uses the same safe profile and can append the bridge block to `CLAUDE.md` when that file already exists and no jhste bridge is present.
+
+Default install does not overwrite existing Claude skills. If a skill name conflicts, keep the existing copy unless the user explicitly approves replacement.
+
+Explicit user instructions set task scope but do not silently override verified safety, privacy, data-loss, or repo-architecture constraints.

package/adapters/codex/README.md

@@ -0,0 +1,25 @@
+# Codex adapter
+
+The Codex adapter keeps repository instructions authoritative and uses a short bridge block in `AGENTS.md` when that file already exists.
+
+Bridge block:
+
+```md
+## Agent skills
+This repo uses jhste skills as shared guidance.
+Repo-local instructions in this file remain authoritative.
+See `.jhste/profile.yaml` for local skill preferences.
+Before non-trivial code changes, use the `jhste-engineering-judgment` skill to check scope, seams, failure paths, and assumptions.
+For changed code, name the one main responsibility of each changed class, module, and function, and reject adjacent responsibilities unless they are on the changed execution path and prevent a concrete failure.
+After code changes, run `jhste-skills guard --scope changed --format text --fail-on error` when available.
+Report guard warnings/errors; do not treat guard runtime/config failures as validation success.
+Treat guard output as review evidence, not proof by itself.
+If guard or red-team review reports new warnings on changed files, attempt a bounded fix before declaring completion, then rerun guard. Do not commit automatically.
+Before declaring non-trivial code work complete, use the `jhste-red-team-review` skill.
+Skip red-team review for docs-only, comment-only, formatting-only, or trivial rename-only changes.
+Do not enter an unbounded fix/review loop; stop after at most two fix + re-review cycles and report remaining risks.
+```
+
+Default install copies skills to a kit-managed skill directory and does not delete or rewrite existing Codex skills.
+
+Explicit user instructions set task scope but do not silently override verified safety, privacy, data-loss, or repo-architecture constraints.

package/adapters/generic/README.md

@@ -0,0 +1,7 @@
+# Generic adapter
+
+Use the generic adapter when an AI coding tool has no first-class adapter yet. Point the tool at this kit's `skills/` directory or copy selected skills into a user-managed directory.
+
+The same priority applies: explicit user instruction, repo-local instructions, profile, shared skills, then general principles.
+
+Explicit user instructions set task scope but do not silently override verified safety, privacy, data-loss, or repo-architecture constraints.

package/cli/baseline.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { confirmWriteAction, findGitRoot, parseArgs, relativeDisplay, KIT_ROOT } from './shared.mjs';
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const repoRoot = findGitRoot(args.repo || process.cwd());
+  const baselinePath = path.join(repoRoot, '.jhste', 'baseline.json');
+  console.log('Baseline is optional and does not enable strict mode by itself.');
+  console.log('Think of it as a known-issues ledger: matched findings remain visible until fixed or explicitly tracked.');
+  const shouldWrite = await confirmWriteAction(args, {
+    action: 'baseline',
+    repoRoot,
+    changedFiles: [baselinePath],
+    prompt: `Create/update ${relativeDisplay(repoRoot, baselinePath)} from guard --scope all? [y/N] `,
+  });
+  if (!shouldWrite) {
+    console.log('No baseline created.');
+    return;
+  }
+  const result = spawnSync(process.execPath, [path.join(KIT_ROOT, 'cli', 'guard.mjs'), '--repo', repoRoot, '--scope', 'all', '--baseline', 'update', '--format', 'text', '--fail-on', 'none'], {
+    cwd: repoRoot,
+    stdio: 'inherit',
+  });
+  process.exit(result.status ?? 1);
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});