jhste-skills 0.3.6 → 0.3.7

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.3.7 - 2026-06-30
+
+### Added
+- Added `implement`, a jhste-compatible implementation workflow skill for scoped PRD/issue/spec work.
+- Added `writing-great-skills`, replacing the legacy `write-a-skill` skill with upstream skill-writing guidance.
+
+### Changed
+- Refreshed Matt Pocock vendored workflow skills against upstream `43ea088`, excluding `tdd` and `resolving-merge-conflicts`.
+- Updated `triage` to cover external PRs as a triage surface, including PR diff verification and PR-specific agent briefs.
+- Slimmed duplicated architecture/grilling docs by routing shared vocabulary through `codebase-design`, `grilling`, and `domain-modeling`.
+- Updated issue slicing to prefer prefactoring slices where they make later implementation easier and to represent human decisions as blockers rather than a separate HITL/AFK field.
+- Removed managed legacy `write-a-skill` installs during sync/update; `writing-great-skills` is the replacement skill going forward.
+
+### Validation
+- `npm test` passed.
+- `jhste-skills guard --scope changed --format text --fail-on error` passed with 0 warnings/errors.
+- `git diff --check` passed.
 ## 0.3.6 - 2026-06-28
 
 ### Changed

package/README.ja.md

@@ -172,7 +172,7 @@ Custom   - 効果ベースの質問でセットアップ範囲を選択
 
 ## Bundled workflow skills
 
-Normal install では、Matt Pocock の [`mattpocock/skills`](https://github.com/mattpocock/skills) から vendoring した 13 個の workflow skills もインストールします。これらは debugging、planning、architecture、issue workflow、prototyping、handoff に役立ちます。インストールしたくない場合は `--skill-set core` を使ってください。
+Normal install では、Matt Pocock の [`mattpocock/skills`](https://github.com/mattpocock/skills) から vendoring した 14 個の workflow skills もインストールします。これらは implementation、debugging、planning、architecture、issue workflow、prototyping、handoff、skill-writing guidance に役立ちます。インストールしたくない場合は `--skill-set core` を使ってください。
 
 | Skill | いつ使うか |
 |---|---|
@@ -188,11 +188,12 @@ Normal install では、Matt Pocock の [`mattpocock/skills`](https://github.com
 | [`to-issues`](skills/to-issues/SKILL.md)<br>計画を issue-ready vertical slices に分解する skill | implementation tickets/work breakdown が必要なとき; tracker creation は直接依頼または repo approval がある場合 |
 | [`triage`](skills/triage/SKILL.md)<br>issue を分類し次の action を計画する triage skill | issue classification、next-action planning、repo-approved triage writes が必要なとき |
 | [`handoff`](skills/handoff/SKILL.md)<br>次の agent や session が続けられるよう context を圧縮する handoff skill | handoff、session summary、continuation brief、next-agent context の依頼時 |
-| [`write-a-skill`](skills/write-a-skill/SKILL.md)<br>正しい構造と progressive disclosure で agent skill を作成する skill-writing skill | agent skill を作成または改善したいとき |
+| [`implement`](skills/implement/SKILL.md)<br>jhste groundwork、verification、guard、review を使う scoped PRD/issue/spec implementation workflow skill | PRD、issue、spec、handoff から focused work を実装したいとき |
+| [`writing-great-skills`](skills/writing-great-skills/SKILL.md)<br>predictable invocation、progressive disclosure、context load control、pruning の skill-writing reference | agent skill を作成、置換、改善したいとき |
 
 ## Attribution: Matt Pocock skills
 
-このリポジトリは、上記 13 個の skills を Matt Pocock の [`mattpocock/skills`](https://github.com/mattpocock/skills) から vendoring しています。
+このリポジトリは、上記 14 個の skills を Matt Pocock の [`mattpocock/skills`](https://github.com/mattpocock/skills) から vendoring しています。
 
 これらの skills は upstream MIT License に基づいて vendoring されています。このリポジトリは必要な copyright/license notice を保持し、インポート元を記録しています。
 

package/README.ko.md

@@ -175,7 +175,7 @@ Custom   - 효과 중심 질문을 통해 설치 범위를 직접 선택
 
 ## Bundled workflow skills
 
-Normal install은 Matt Pocock의 [`mattpocock/skills`](https://github.com/mattpocock/skills)에서 vendoring한 workflow skills 13개도 함께 설치합니다. 이 스킬들은 debugging, planning, architecture, issue workflow, prototyping, handoff 작업에 유용합니다. 설치하고 싶지 않다면 `--skill-set core`를 사용하세요.
+Normal install은 Matt Pocock의 [`mattpocock/skills`](https://github.com/mattpocock/skills)에서 vendoring한 workflow skills 14개도 함께 설치합니다. 이 스킬들은 implementation, debugging, planning, architecture, issue workflow, prototyping, handoff, skill-writing guidance 작업에 유용합니다. 설치하고 싶지 않다면 `--skill-set core`를 사용하세요.
 
 | Skill | 언제 쓰나 |
 |---|---|
@@ -191,7 +191,8 @@ Normal install은 Matt Pocock의 [`mattpocock/skills`](https://github.com/mattpo
 | [`to-issues`](skills/to-issues/SKILL.md)<br>계획을 issue-ready vertical slice로 나누는 스킬 | implementation ticket/work breakdown이 필요할 때; tracker creation은 직접 요청이나 repo approval이 있을 때 |
 | [`triage`](skills/triage/SKILL.md)<br>issue를 분류하고 다음 행동을 계획하는 triage 스킬 | issue classification, next-action planning, repo-approved triage write가 필요할 때 |
 | [`handoff`](skills/handoff/SKILL.md)<br>다음 agent나 session이 이어받을 수 있도록 context를 압축하는 handoff 스킬 | handoff, session summary, continuation brief, next-agent context 요청 시 |
-| [`write-a-skill`](skills/write-a-skill/SKILL.md)<br>새로운 agent skill을 올바른 구조와 progressive disclosure 방식으로 작성하는 스킬 | agent skill을 새로 만들거나 다듬고 싶을 때 |
+| [`implement`](skills/implement/SKILL.md)<br>jhste groundwork, verification, guard, review를 사용하는 scoped PRD/issue/spec 구현 workflow 스킬 | PRD, issue, spec, handoff에서 focused work를 구현하고 싶을 때 |
+| [`writing-great-skills`](skills/writing-great-skills/SKILL.md)<br>predictable invocation, progressive disclosure, context load control, pruning을 다루는 skill-writing reference | agent skill을 만들거나, 교체하거나, 다듬고 싶을 때 |
 
 ## Attribution: Matt Pocock skills
 

package/README.md

@@ -175,7 +175,7 @@ These are the jhste-authored guardrail skills. They are installed by default as
 
 ## Bundled workflow skills
 
-Normal install also includes 13 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.
+Normal install also includes 14 workflow skills vendored from Matt Pocock's [`mattpocock/skills`](https://github.com/mattpocock/skills). These are useful for implementation, debugging, planning, architecture, issue workflows, prototyping, handoffs, and skill-writing guidance. Use `--skill-set core` if you do not want them installed.
 
 | Skill | Use it when |
 |---|---|
@@ -191,11 +191,12 @@ Normal install also includes 13 workflow skills vendored from Matt Pocock's [`ma
 | [`to-issues`](skills/to-issues/SKILL.md)<br>A skill that breaks a plan into issue-ready vertical slices | You want implementation tickets or work breakdown; tracker creation follows direct request or repo approval |
 | [`triage`](skills/triage/SKILL.md)<br>An issue triage skill that classifies issues and plans next actions through a structured workflow | You want issue classification, next-action planning, or repo-approved triage writes |
 | [`handoff`](skills/handoff/SKILL.md)<br>A handoff skill that compresses context so the next agent or session can continue | You ask for a handoff, session summary, continuation brief, or next-agent context |
-| [`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 |
+| [`implement`](skills/implement/SKILL.md)<br>An implementation workflow skill for scoped PRD/issue/spec work using jhste groundwork, verification, guard, and review | You want an agent to implement focused work from a PRD, issue, spec, or handoff |
+| [`writing-great-skills`](skills/writing-great-skills/SKILL.md)<br>A skill-writing reference for predictable invocation, progressive disclosure, context load control, and pruning | You want to create, replace, or refine an agent skill |
 
 ## Attribution: Matt Pocock skills
 
-This repository vendors the 13 skills listed above from Matt Pocock's [`mattpocock/skills`](https://github.com/mattpocock/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.
 
@@ -273,4 +274,4 @@ See [`docs/ACCEPTANCE_CHECK.md`](docs/ACCEPTANCE_CHECK.md) for release acceptanc
 
 Fast agents need guardrails. `jhste-skills` gives them a repo-respecting engineering workflow.
 
-Installed skill directories are tracked with `.jhste-skills-manifest.json`. `--force` refreshes manifest-managed skill copies and generated/managed profiles; modified profiles need `--force --allow-profile-overwrite`; overwriting unmanaged differing skill directories still requires the separate `--allow-unmanaged-skill-overwrite` flag after review. `sync` and `update` can also adopt additional known jhste skills into an already managed skills directory so older mixed installs can be reconciled without a manual overwrite flag. Legacy managed renames are also reconciled during `sync` and `update`, so older managed installs that still have `diagnose` or `jhste-engineering-judgment` are migrated to `diagnosing-bugs` or `jhste-engineering-groundwork` without leaving duplicate skill directories.
+Installed skill directories are tracked with `.jhste-skills-manifest.json`. `--force` refreshes manifest-managed skill copies and generated/managed profiles; modified profiles need `--force --allow-profile-overwrite`; overwriting unmanaged differing skill directories still requires the separate `--allow-unmanaged-skill-overwrite` flag after review. `sync` and `update` can also adopt additional known jhste skills into an already managed skills directory so older mixed installs can be reconciled without a manual overwrite flag. Legacy managed renames are also reconciled during `sync` and `update`, so older managed installs that still have `diagnose` or `jhste-engineering-judgment` are migrated to `diagnosing-bugs` or `jhste-engineering-groundwork`. Managed copies of retired `write-a-skill` are removed rather than kept as a compatibility fallback.

package/README.zh.md

@@ -172,7 +172,7 @@ Custom   - 通过面向效果的问题自定义安装范围
 
 ## Bundled workflow skills
 
-Normal install 还会安装 13 个从 Matt Pocock 的 [`mattpocock/skills`](https://github.com/mattpocock/skills) vendoring 的 workflow skills。它们适用于 debugging、planning、architecture、issue workflow、prototyping 和 handoff。若不想安装它们，请使用 `--skill-set core`。
+Normal install 还会安装 14 个从 Matt Pocock 的 [`mattpocock/skills`](https://github.com/mattpocock/skills) vendoring 的 workflow skills。它们适用于 implementation、debugging、planning、architecture、issue workflow、prototyping、handoff 和 skill-writing guidance。若不想安装它们，请使用 `--skill-set core`。
 
 | Skill | 何时使用 |
 |---|---|
@@ -188,11 +188,12 @@ Normal install 还会安装 13 个从 Matt Pocock 的 [`mattpocock/skills`](http
 | [`to-issues`](skills/to-issues/SKILL.md)<br>把计划拆成 issue-ready vertical slices 的 skill | 需要 implementation tickets/work breakdown；tracker creation 需直接请求或 repo approval |
 | [`triage`](skills/triage/SKILL.md)<br>分类 issue 并规划下一步行动的 triage skill | 需要 issue classification、next-action planning 或 repo-approved triage writes 时 |
 | [`handoff`](skills/handoff/SKILL.md)<br>压缩 context，让下一个 agent 或 session 能继续工作的 handoff skill | 请求 handoff、session summary、continuation brief 或 next-agent context 时 |
-| [`write-a-skill`](skills/write-a-skill/SKILL.md)<br>用正确结构和 progressive disclosure 创建 agent skill 的 skill-writing skill | 想创建或改进 agent skill 时 |
+| [`implement`](skills/implement/SKILL.md)<br>使用 jhste groundwork、verification、guard、review 的 scoped PRD/issue/spec implementation workflow skill | 想从 PRD、issue、spec 或 handoff 实现 focused work 时 |
+| [`writing-great-skills`](skills/writing-great-skills/SKILL.md)<br>关于 predictable invocation、progressive disclosure、context load control、pruning 的 skill-writing reference | 想创建、替换或改进 agent skill 时 |
 
 ## Attribution: Matt Pocock skills
 
-本仓库从 Matt Pocock 的 [`mattpocock/skills`](https://github.com/mattpocock/skills) vendoring 了上面列出的 13 个 skills。
+本仓库从 Matt Pocock 的 [`mattpocock/skills`](https://github.com/mattpocock/skills) vendoring 了上面列出的 14 个 skills。
 
 这些 skills 按 upstream MIT License vendoring。本仓库保留所需 copyright/license notice，并记录导入来源。
 

package/cli/install-actions/skills.mjs

@@ -10,6 +10,8 @@ export const LEGACY_SKILL_RENAMES = Object.freeze({
   'jhste-engineering-judgment': 'jhste-engineering-groundwork',
 });
 
+export const DELETED_MANAGED_SKILLS = Object.freeze(['write-a-skill']);
+
 export function canonicalSkillName(name) {
   return LEGACY_SKILL_RENAMES[name] || name;
 }
@@ -101,6 +103,19 @@ function removeLegacySkillDirectories(skillsDir, selected, currentManifest, next
   return results;
 }
 
+function removeDeletedManagedSkillDirectories(skillsDir, currentManifest, nextManifest) {
+  const results = [];
+  for (const deletedName of DELETED_MANAGED_SKILLS) {
+    const wasManaged = Boolean(currentManifest?.skills?.[deletedName]);
+    delete nextManifest.skills[deletedName];
+    const deletedPath = path.join(skillsDir, deletedName);
+    if (!wasManaged || !fs.existsSync(deletedPath)) continue;
+    fs.rmSync(deletedPath, { recursive: true, force: true });
+    results.push({ status: 'removed-deleted-managed-skill', source: deletedPath, destination: '', deletedName });
+  }
+  return results;
+}
+
 function copyManagedSkill(source, destination, name, {
   force = false,
   allowUnmanagedOverwrite = false,
@@ -201,6 +216,7 @@ export function installSkills(skillsDir, {
     allowUnmanagedOverwrite,
     adoptKnownSkills,
   });
+  const deletedResults = removeDeletedManagedSkillDirectories(skillsDir, currentManifest, nextManifest);
   const results = selected.map((name) => copyManagedSkill(path.join(sourceRoot, name), path.join(skillsDir, name), name, {
     force,
     allowUnmanagedOverwrite,
@@ -209,5 +225,5 @@ export function installSkills(skillsDir, {
     nextManifest,
   }));
   writeSkillsManifest(skillsDir, nextManifest);
-  return [...legacyResults, ...results];
+  return [...legacyResults, ...deletedResults, ...results];
 }

package/docs/ACCEPTANCE_CHECK.md

@@ -64,7 +64,7 @@ Record actual command output in release notes before publishing a release.
 
 Release gates include dependency-free syntax checking, a first-run `install -> deep-scan -> tune --yes -> guard` smoke flow, `npm pack --dry-run` contents checks, and packed-tarball bin execution in a fresh temp consumer. These gates are not part of commit-time hooks.
 
-- Verify `sync`/`update` migrates older managed renames without leaving duplicate directories, including `diagnose` → `diagnosing-bugs` and `jhste-engineering-judgment` → `jhste-engineering-groundwork`.
+- Verify `sync`/`update` migrates older managed renames without leaving duplicate directories, including `diagnose` → `diagnosing-bugs`, `jhste-engineering-judgment` → `jhste-engineering-groundwork`, and managed removal of retired `write-a-skill`.
 
 ## npm trusted publishing
 

package/docs/CONFLICT_RESOLUTION.md

@@ -61,4 +61,4 @@ If a similar section exists, the installer prints the snippet instead of editing
 
 Managed hooks are identified by the jhste-skills hook markers. Existing non-managed hooks are never overwritten, including in `Full` mode and with `--force`. Full may install multiple hook targets, but each target is reported separately as installed, refreshed, skipped because non-managed, or failed.
 
-Legacy managed renames are treated differently from unmanaged conflicts. During `sync` and `update`, older managed `diagnose` and `jhste-engineering-judgment` installs are migrated to `diagnosing-bugs` and `jhste-engineering-groundwork` automatically so the skills directory does not keep both names.
+Legacy managed renames are treated differently from unmanaged conflicts. During `sync` and `update`, older managed `diagnose` and `jhste-engineering-judgment` installs are migrated to `diagnosing-bugs` and `jhste-engineering-groundwork` automatically, and managed copies of retired `write-a-skill` are removed, so the skills directory does not keep duplicate or removed names.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jhste-skills",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "Installable engineering guardrails and workflow skills for AI coding agents.",
   "type": "module",
   "license": "MIT",

package/scripts/smoke/connect-scenarios.mjs

@@ -13,7 +13,7 @@ export function runConnectScenarios({ root, tmp, skillsDir }) {
   fs.mkdirSync(nonGitCwd, { recursive: true });
   run(process.execPath, [path.join(root, 'cli/install.mjs'), '--yes', '--skills-dir', nonGitCwdSkills, '--skip-deep-scan'], { cwd: nonGitCwd });
   if (fs.existsSync(path.join(nonGitCwd, '.jhste'))) fail('install outside git repo created .jhste');
-  if (skillDirs(nonGitCwdSkills).length !== 21) fail('install outside git repo did not install 21 bundled skills');
+  if (skillDirs(nonGitCwdSkills).length !== 22) fail('install outside git repo did not install 22 bundled skills');
 
   const explicitNonGitRepo = path.join(tmp, 'explicit-non-git-repo');
   const explicitNonGitSkills = path.join(tmp, 'explicit-non-git-skills');
@@ -42,6 +42,6 @@ export function runConnectScenarios({ root, tmp, skillsDir }) {
   if (connectMissing.status !== 3) fail(`connect missing skills should exit 3, got ${connectMissing.status}`);
   if (fs.existsSync(path.join(connectMissingRepo, '.jhste'))) fail('connect missing skills created .jhste');
   run(process.execPath, [path.join(root, 'cli/connect.mjs'), '--mode', 'normal', '--yes', '--repo', connectMissingRepo, '--skills-dir', connectMissingSkills, '--skip-deep-scan', '--install-missing'], { cwd: connectMissingRepo });
-  if (skillDirs(connectMissingSkills).length !== 21) fail('connect --install-missing did not install 21 bundled skills');
+  if (skillDirs(connectMissingSkills).length !== 22) fail('connect --install-missing did not install 22 bundled skills');
   if (!fs.existsSync(path.join(connectMissingRepo, '.jhste', 'profile.yaml'))) fail('connect --install-missing did not create profile');
 }

package/scripts/smoke/helpers.mjs

@@ -76,6 +76,21 @@ export function assertLegacySkillRenameMigration({ root, repo, skillsDir, manife
   return migratedManifest;
 }
 
+export function assertManagedDeletedSkillRemoval({ root, repo, skillsDir, manifest, deletedName, digest }) {
+  const deletedDir = path.join(skillsDir, deletedName);
+  fs.mkdirSync(deletedDir, { recursive: true });
+  fs.writeFileSync(path.join(deletedDir, 'SKILL.md'), '# stale deleted skill copy\n');
+  manifest.skills[deletedName] = { digest };
+  fs.writeFileSync(path.join(skillsDir, '.jhste-skills-manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+
+  run(process.execPath, [path.join(root, 'cli/update.mjs'), '--yes', '--repo', repo, '--skills-dir', skillsDir], { cwd: repo });
+
+  if (fs.existsSync(deletedDir)) fail(`update did not remove deleted managed ${deletedName} skill directory`);
+  const updatedManifest = readManagedSkillsManifest(skillsDir);
+  if (updatedManifest.skills?.[deletedName]) fail(`update left deleted ${deletedName} entry in manifest`);
+  return updatedManifest;
+}
+
 export function assertNoInstallSideEffects({ repo, skillsDir, agentsBefore, label }) {
   if (fs.existsSync(path.join(repo, '.jhste'))) fail(`${label} created .jhste`);
   if (fs.existsSync(skillsDir)) fail(`${label} touched skills directory`);

package/scripts/smoke/install-scenarios.mjs

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import {
-  assertLegacySkillRenameMigration,
+  assertLegacySkillRenameMigration, assertManagedDeletedSkillRemoval,
   assertNoInstallSideEffects,
   fail,
   hashFile,
@@ -112,7 +112,7 @@ function runDefaultInstall(ctx) {
   const manifest = readManagedSkillsManifest(skillsDir);
   if (manifest.managed_by !== 'jhste-skills' || !manifest.skills?.['jhste-red-team-review']?.digest) fail('skills manifest missing managed skill digest');
   const defaultSkillDirs = skillDirs(skillsDir);
-  if (defaultSkillDirs.length !== 21) fail(`default install should copy 21 bundled skills, got ${defaultSkillDirs.length}`);
+  if (defaultSkillDirs.length !== 22) fail(`default install should copy 22 bundled skills, got ${defaultSkillDirs.length}`);
   if (!defaultSkillDirs.includes('improve-codebase-architecture')) fail('default install should copy vendored workflow skills');
 }
 
@@ -204,7 +204,7 @@ run_jhste_skills guard --scope staged --format text --fail-on warning
   migratedManifest = assertLegacySkillRenameMigration({
     root, repo, skillsDir, manifest: migratedManifest, legacyName: 'jhste-engineering-judgment', canonicalName: 'jhste-engineering-groundwork', digest: 'legacy-groundwork-digest',
   });
-
+  migratedManifest = assertManagedDeletedSkillRemoval({ root, repo, skillsDir, manifest: migratedManifest, deletedName: 'write-a-skill', digest: 'legacy-write-skill-digest' });
   const unmanagedSkills = path.join(path.dirname(skillsDir), 'unmanaged-skills');
   fs.mkdirSync(path.join(unmanagedSkills, 'jhste-code-quality'), { recursive: true });
   fs.writeFileSync(path.join(unmanagedSkills, 'jhste-code-quality', 'SKILL.md'), '# unmanaged local copy\n');
@@ -258,7 +258,7 @@ function runSkillSetScenarios({ root, tmp }) {
   fs.writeFileSync(path.join(vendorRepo, 'AGENTS.md'), '# Vendor skill repo\n');
   run(process.execPath, [path.join(root, 'cli/install.mjs'), '--yes', '--repo', vendorRepo, '--skills-dir', vendorSkillsDir, '--skip-deep-scan', '--skip-hooks', '--skill-set', 'vendor'], { cwd: vendorRepo });
   const vendorSkillDirs = skillDirs(vendorSkillsDir);
-  if (vendorSkillDirs.length !== 13) fail(`--skill-set vendor should copy 13 skills, got ${vendorSkillDirs.length}`);
+  if (vendorSkillDirs.length !== 14) fail(`--skill-set vendor should copy 14 skills, got ${vendorSkillDirs.length}`);
   if (!vendorSkillDirs.includes('improve-codebase-architecture')) fail('--skill-set vendor did not copy expected vendored skill');
   if (vendorSkillDirs.includes('jhste-red-team-review')) fail('--skill-set vendor copied core skill');
 
@@ -268,7 +268,7 @@ function runSkillSetScenarios({ root, tmp }) {
   fs.writeFileSync(path.join(allRepo, 'AGENTS.md'), '# All skill repo\n');
   run(process.execPath, [path.join(root, 'cli/install.mjs'), '--yes', '--repo', allRepo, '--skills-dir', allSkillsDir, '--skip-deep-scan', '--skip-hooks', '--skill-set', 'all'], { cwd: allRepo });
   const allSkillDirs = skillDirs(allSkillsDir);
-  if (allSkillDirs.length !== 21) fail(`--skill-set all should copy 21 skills, got ${allSkillDirs.length}`);
+  if (allSkillDirs.length !== 22) fail(`--skill-set all should copy 22 skills, got ${allSkillDirs.length}`);
   if (!allSkillDirs.includes('jhste-red-team-review') || !allSkillDirs.includes('improve-codebase-architecture')) fail('--skill-set all missing core or vendored skill');
 }
 

package/scripts/smoke/mode-scenarios.mjs

@@ -47,7 +47,7 @@ function runFullModeScenarios({ root, tmp }) {
   fs.writeFileSync(path.join(fullModeRepo, 'AGENTS.md'), '# Full mode repo\n');
   run(process.execPath, [path.join(root, 'cli/install.mjs'), '--mode', 'full', '--yes', '--repo', fullModeRepo, '--skills-dir', fullModeSkillsDir, '--skip-deep-scan'], { cwd: fullModeRepo });
   const fullModeSkillDirs = skillDirs(fullModeSkillsDir);
-  if (fullModeSkillDirs.length !== 21) fail(`--mode full should copy 21 skills, got ${fullModeSkillDirs.length}`);
+  if (fullModeSkillDirs.length !== 22) fail(`--mode full should copy 22 skills, got ${fullModeSkillDirs.length}`);
   const fullPreCommit = path.join(fullModeRepo, '.git', 'hooks', 'pre-commit');
   const fullPrePush = path.join(fullModeRepo, '.git', 'hooks', 'pre-push');
   if (!fs.existsSync(fullPreCommit) || !fs.existsSync(fullPrePush)) fail('--mode full did not install pre-commit and pre-push');

package/scripts/vendor-check.mjs

@@ -14,7 +14,8 @@ const expected = [
   'prototype',
   'grill-me',
   'handoff',
-  'write-a-skill',
+  'writing-great-skills',
+  'implement',
   'codebase-design',
   'diagnosing-bugs',
   'domain-modeling',
@@ -38,12 +39,12 @@ function readJson(file) {
 
 const allowlist = readJson('vendor/matt-pocock/allowlist.json');
 if (JSON.stringify(allowlist) !== JSON.stringify(expected)) {
-  fail('allowlist does not match the exact 13 selected skills');
+  fail('allowlist does not match the exact 14 selected skills');
 }
 
 const sourceLock = readJson('vendor/matt-pocock/source-lock.json');
 if (!Array.isArray(sourceLock.skills) || sourceLock.skills.length !== expected.length) {
-  fail('source-lock must contain exactly 13 skills');
+  fail('source-lock must contain exactly 14 skills');
 }
 
 const seen = new Set();

package/skills/grill-me/SKILL.md

@@ -11,9 +11,6 @@ description: Direct red-team interrogation of the user's own plan or reasoning.
 - This skill is read-only by default. Do not create or modify files, issues, PRs, commands, or repo state during grilling.
 - If the user wants documentation updates, ADRs, glossary changes, issue creation, or other side effects, switch to the appropriate writing workflow such as `grill-with-docs`, `domain-modeling`, `to-issues`, or `triage`.
 
+# Grill Me
 
-Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
-
-Ask the questions one at a time.
-
-If a question can be answered by exploring the codebase, explore the codebase instead.
+Run the `grilling` workflow for a personal, read-only pressure test. Keep the interaction one question at a time, include your recommended answer with each question, and explore the codebase instead of asking when the answer is discoverable locally.

package/skills/grill-with-docs/ADR-FORMAT.md

@@ -1,47 +1,5 @@
 # ADR Format
 
-ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+This compatibility file is retained for older links. The maintained ADR format lives in [`../domain-modeling/ADR-FORMAT.md`](../domain-modeling/ADR-FORMAT.md).
 
-Create the `docs/adr/` directory lazily — only when the first ADR is needed.
-
-## Template
-
-```md
-# {Short title of the decision}
-
-{1-3 sentences: what's the context, what did we decide, and why.}
-```
-
-That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections.
-
-## Optional sections
-
-Only include these when they add genuine value. Most ADRs won't need them.
-
-- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited
-- **Considered Options** — only when the rejected alternatives are worth remembering
-- **Consequences** — only when non-obvious downstream effects need to be called out
-
-## Numbering
-
-Scan `docs/adr/` for the highest existing number and increment by one.
-
-## When to offer an ADR
-
-All three of these must be true:
-
-1. **Hard to reverse** — the cost of changing your mind later is meaningful
-2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?"
-3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
-
-If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
-
-### What qualifies
-
-- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
-- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
-- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out.
-- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
-- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
-- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
-- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months.
+Repo-local instructions remain authoritative; use repo-local ADR conventions when they exist.

package/skills/grill-with-docs/CONTEXT-FORMAT.md

@@ -1,60 +1,5 @@
 # CONTEXT.md Format
 
-## Structure
+This compatibility file is retained for older links. The maintained context/glossary format lives in [`../domain-modeling/CONTEXT-FORMAT.md`](../domain-modeling/CONTEXT-FORMAT.md).
 
-```md
-# {Context Name}
-
-{One or two sentence description of what this context is and why it exists.}
-
-## Language
-
-**Order**:
-{A one or two sentence description of the term}
-_Avoid_: Purchase, transaction
-
-**Invoice**:
-A request for payment sent to a customer after delivery.
-_Avoid_: Bill, payment request
-
-**Customer**:
-A person or organization that places orders.
-_Avoid_: Client, buyer, account
-```
-
-## Rules
-
-- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
-- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
-- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
-- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
-
-## Single vs multi-context repos
-
-**Single context (most repos):** One `CONTEXT.md` at the repo root.
-
-**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
-
-```md
-# Context Map
-
-## Contexts
-
-- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
-- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
-- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
-
-## Relationships
-
-- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
-- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
-- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
-```
-
-The skill infers which structure applies:
-
-- If `CONTEXT-MAP.md` exists, read it to find contexts
-- If only a root `CONTEXT.md` exists, single context
-- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
-
-When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.
+Repo-local instructions remain authoritative; use repo-local glossary conventions when they exist.

package/skills/grill-with-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: grill-with-docs
-description: Red-team questioning of a plan against project domain language, then recording resulting decisions in CONTEXT.md or ADRs. Use when the user wants grilling plus documentation, ADR, glossary, or CONTEXT updates. Not for reviewing an already-changed code diff; use jhste-red-team-review for that.
+description: Stress-test a plan against project domain language and record resulting decisions in CONTEXT.md or ADRs. Use when the user wants grilling plus documentation, ADR, glossary, or CONTEXT updates.
 ---
 
 ## jhste compatibility
@@ -10,89 +10,17 @@ description: Red-team questioning of a plan against project domain language, the
 - Vocabulary in this vendored skill is advisory unless adopted by repo-local docs; do not rename established repo concepts only to match this skill.
 - File, repo, command, issue, PR, or other external side effects are allowed when the user directly requested that workflow or repo-local standing approval covers it. Ask for destructive, irreversible, ambiguous, production, secret, cost-bearing, broad existing-item, or out-of-scope changes.
 
+# Grill With Docs
 
-<what-to-do>
+Run `grilling` and `domain-modeling` together: interrogate the plan one question at a time, and update the project glossary or ADRs as terms and durable decisions crystallize.
 
-Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+## Process
 
-Ask the questions one at a time, waiting for feedback on each question before continuing.
+1. **Load domain context.** Read `CONTEXT.md` or `CONTEXT-MAP.md` when present, plus relevant ADRs. If the answer to a question is discoverable from code, inspect the code instead of asking.
+2. **Grill one branch at a time.** Ask one question, include your recommended answer, and wait for the user's correction before moving on.
+3. **Update docs inline when requested.** If the user asked for docs, ADR, glossary, or CONTEXT updates, treat that as approval for bounded documentation edits during the session. If the user only asked for stress-testing, stay read-only until they ask for writes.
+4. **Use domain-modeling as the docs SSOT.** For glossary and ADR structure, follow `../domain-modeling/CONTEXT-FORMAT.md` and `../domain-modeling/ADR-FORMAT.md`.
 
-If a question can be answered by exploring the codebase, explore the codebase instead.
+## ADR threshold
 
-When the user requests documentation, ADR, glossary, or CONTEXT updates as part of the grilling workflow, treat that as standing approval to update the relevant docs during the session. Do not ask before every doc edit. If the user only asked for stress-testing, run read-only grilling and do not write docs unless the user later asks for it.
-
-</what-to-do>
-
-<supporting-info>
-
-## Domain awareness
-
-During codebase exploration, also look for existing documentation:
-
-### File structure
-
-Most repos have a single context:
-
-```
-/
-├── CONTEXT.md
-├── docs/
-│   └── adr/
-│       ├── 0001-event-sourced-orders.md
-│       └── 0002-postgres-for-write-model.md
-└── src/
-```
-
-If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
-
-```
-/
-├── CONTEXT-MAP.md
-├── docs/
-│   └── adr/                          ← system-wide decisions
-├── src/
-│   ├── ordering/
-│   │   ├── CONTEXT.md
-│   │   └── docs/adr/                 ← context-specific decisions
-│   └── billing/
-│       ├── CONTEXT.md
-│       └── docs/adr/
-```
-
-Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
-
-## During the session
-
-### Challenge against the glossary
-
-When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
-
-### Sharpen fuzzy language
-
-When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
-
-### Discuss concrete scenarios
-
-When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
-
-### Cross-reference with code
-
-When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
-
-### Update CONTEXT.md inline
-
-In docs-writing mode, when a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md). In read-only grilling mode, propose the wording instead of writing it.
-
-`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
-
-### Offer ADRs sparingly
-
-Only offer to create an ADR when all three are true:
-
-1. **Hard to reverse** — the cost of changing your mind later is meaningful
-2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
-3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
-
-If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).
-
-</supporting-info>
+Offer an ADR only when the decision is hard to reverse, surprising without context, and the result of a real trade-off. Otherwise keep the conclusion in the conversation or glossary only.

package/skills/implement/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: implement
+description: Implement focused work from a PRD, issue, or explicit user request using jhste groundwork, bounded edits, verification, and completion review. Use when the user asks to implement from a PRD/issue/spec or continue a scoped build task.
+---
+
+## jhste compatibility
+
+- Repo-local instructions remain authoritative.
+- Use `jhste-engineering-groundwork` for scope, boundaries, assumptions, and failure paths when it applies.
+- Vocabulary in this vendored skill is advisory unless adopted by repo-local docs; do not rename established repo concepts only to match this skill.
+- File, repo, command, issue, PR, or other external side effects are allowed when the user directly requested that workflow or repo-local standing approval covers it. Ask for destructive, irreversible, ambiguous, production, secret, cost-bearing, broad existing-item, or out-of-scope changes.
+
+# Implement
+
+Implement the work described by the user, PRD, issue, or handoff while preserving repo-local workflow rules.
+
+## Workflow
+
+1. **Resolve scope.** Read the referenced PRD, issue, handoff, or prompt. Identify the smallest changed execution path and reject adjacent scope unless leaving it out creates a concrete failure mode.
+2. **Run groundwork.** For non-trivial code work, use `jhste-engineering-groundwork` before editing. Capture the final behavior predicates, data contracts, failure paths, and verification boundary.
+3. **Make the bounded change.** Edit the owning module(s) only. Do not introduce broad architecture, schema, dependency, or public API changes unless the source material explicitly asks for them and repo-local instructions allow them.
+4. **Verify along the consumer path.** Prefer the highest existing boundary that proves the requested behavior. Run targeted tests or smoke checks while iterating, then the relevant broader check before completion.
+5. **Run jhste completion checks.** When available, run `jhste-skills guard --scope changed --format text --fail-on error`. For non-trivial code changes, use `jhste-red-team-review` before declaring completion.
+6. **Report evidence.** Summarize changed files, commands/results, skipped checks, consumer-path proof, and residual risk.
+
+## Side effects
+
+- Do not commit, push, tag, release, publish, deploy, or mutate tracker items unless the user directly requested that exact side effect or repo-local workflow explicitly covers it.
+- If the requested implementation needs secrets, production data, live migrations, cost-bearing resources, or destructive operations, pause for explicit confirmation before that step.
+- Keep generated or throwaway artifacts clearly named and local unless the source material asks for persistent outputs.