jhste-skills 0.3.4 → 0.3.6

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.3.6 - 2026-06-28
+
+### Changed
+- Clarified that `jhste-long-running-work-loop` is triggered by state-loss risk rather than elapsed time alone, including same-day external wait states.
+- Updated README skill summaries to describe durable state preservation instead of implying only long-duration work.
+
+### Validation
+- `npm test` passed.
+- `jhste-skills guard --scope changed --format text --fail-on error` passed with 0 warnings/errors.
+- `git diff --check` passed.
+- `npm pack --dry-run` completed for `jhste-skills@0.3.6`.
+
+## 0.3.5 - 2026-06-28
+
+### Added
+- Added `jhste-long-running-work-loop`, a narrow orchestration skill for multi-session and long-running work that preserves goals, phases, approval boundaries, resume points, and durable-state routing without replacing code-quality, PRD, issue, triage, or handoff workflows.
+
+### Changed
+- Updated smoke-test expected skill counts now that the bundled/core skill set includes the new long-running work loop skill.
+
+### Validation
+- `npm test` passed.
+- `jhste-skills guard --scope changed --format text --fail-on error` passed with 0 warnings/errors.
+
 ## 0.3.4 - 2026-06-26
 
 ### Changed

package/README.ja.md

@@ -168,6 +168,7 @@ Custom   - 効果ベースの質問でセットアップ範囲を選択
 | [`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 boundary と 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 |
+| [`jhste-long-running-work-loop`](skills/jhste-long-running-work-loop/SKILL.md)<br>session、待ち状態、durable decision をまたいで作業状態を保つための狭い orchestration skill | 状態喪失が誤り、重複、不安全、または再開困難な作業につながるとき: 複数セッションの作業、繰り返し review、当日または複数日の外部待ち状態、複数 repo への影響、PRD→issue→implementation→review の流れ、durable decision | Lost context, stale scratchpad, unclear approval boundary, unsafe resume point |
 
 ## Bundled workflow skills
 

package/README.ko.md

@@ -171,6 +171,7 @@ Custom   - 효과 중심 질문을 통해 설치 범위를 직접 선택
 | [`jhste-db-api-boundary`](skills/jhste-db-api-boundary/SKILL.md)<br>API route, service, repository, SQL 사이의 책임 경계와 데이터 계약을 점검하는 boundary 스킬 | 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 boundary와 side effect를 점검하는 자동화 스킬 | 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 스킬 | non-trivial code work 완료 선언 전 | premature “done”, missing consumer-path proof, 놓치기 쉬운 null/auth/env/write/API/performance risk |
+| [`jhste-long-running-work-loop`](skills/jhste-long-running-work-loop/SKILL.md)<br>세션, 대기 상태, durable decision 사이의 작업 상태를 보존하는 좁은 orchestration 스킬 | 상태 손실이 잘못된 작업, 중복 작업, unsafe resume, 재개 어려움으로 이어질 수 있을 때: 여러 세션 작업, 반복 리뷰, 당일 또는 다일 외부 대기 상태, 여러 repo 영향, PRD→issue→구현→리뷰 흐름, durable decision | lost context, stale scratchpad, unclear approval boundary, unsafe resume point |
 
 ## Bundled workflow skills
 

package/README.md

@@ -171,6 +171,7 @@ These are the jhste-authored guardrail skills. They are installed by default as
 | [`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 boundaries 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”, missing consumer-path proof, missed null/auth/env/write/API/performance risks |
+| [`jhste-long-running-work-loop`](skills/jhste-long-running-work-loop/SKILL.md)<br>A narrow orchestration skill for preserving work state across sessions, wait states, and durable decisions | Losing state could make work wrong, duplicated, unsafe, or hard to resume: multi-session work, recurring reviews, same-day or multi-day external wait states, multiple repos, PRD→issue→implementation→review flows, or durable decisions | Lost context, stale scratchpads, unclear approval boundaries, unsafe resume points |
 
 ## Bundled workflow skills
 

package/README.zh.md

@@ -168,6 +168,7 @@ Custom   - 通过面向效果的问题自定义安装范围
 | [`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 boundary 和 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 |
+| [`jhste-long-running-work-loop`](skills/jhste-long-running-work-loop/SKILL.md)<br>用于在 session、等待状态和 durable decision 间保留工作状态的窄 orchestration skill | 状态丢失可能导致错误、重复、不安全或难以恢复的工作时：多会话工作、重复 review、当天或多天外部等待状态、多 repo 影响、PRD→issue→implementation→review 流程或 durable decision | Lost context, stale scratchpad, unclear approval boundary, unsafe resume point |
 
 ## Bundled workflow skills
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jhste-skills",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "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 !== 20) fail('install outside git repo did not install 20 bundled skills');
+  if (skillDirs(nonGitCwdSkills).length !== 21) fail('install outside git repo did not install 21 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 !== 20) fail('connect --install-missing did not install 20 bundled skills');
+  if (skillDirs(connectMissingSkills).length !== 21) fail('connect --install-missing did not install 21 bundled skills');
   if (!fs.existsSync(path.join(connectMissingRepo, '.jhste', 'profile.yaml'))) fail('connect --install-missing did not create profile');
 }

package/scripts/smoke/install-scenarios.mjs

@@ -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 !== 20) fail(`default install should copy 20 bundled skills, got ${defaultSkillDirs.length}`);
+  if (defaultSkillDirs.length !== 21) fail(`default install should copy 21 bundled skills, got ${defaultSkillDirs.length}`);
   if (!defaultSkillDirs.includes('improve-codebase-architecture')) fail('default install should copy vendored workflow skills');
 }
 
@@ -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 !== 20) fail(`--skill-set all should copy 20 skills, got ${allSkillDirs.length}`);
+  if (allSkillDirs.length !== 21) fail(`--skill-set all should copy 21 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

@@ -27,7 +27,7 @@ function runCustomAndMinimalScenarios({ root, tmp }) {
   fs.writeFileSync(path.join(minimalRepo, 'AGENTS.md'), '# Minimal repo\n');
   run(process.execPath, [path.join(root, 'cli/install.mjs'), '--mode', 'minimal', '--yes', '--repo', minimalRepo, '--skills-dir', minimalSkillsDir, '--skip-deep-scan'], { cwd: minimalRepo });
   const minimalSkillDirs = skillDirs(minimalSkillsDir);
-  if (minimalSkillDirs.length !== 7) fail(`--mode minimal should copy 7 core skills, got ${minimalSkillDirs.length}`);
+  if (minimalSkillDirs.length !== 8) fail(`--mode minimal should copy 8 core skills, got ${minimalSkillDirs.length}`);
   if (fs.existsSync(path.join(minimalRepo, '.jhste'))) fail('--mode minimal created .jhste');
   if (fs.existsSync(path.join(minimalRepo, '.git', 'hooks', 'pre-commit'))) fail('--mode minimal created pre-commit hook');
   if (fs.readFileSync(path.join(minimalRepo, 'AGENTS.md'), 'utf8') !== '# Minimal repo\n') fail('--mode minimal modified AGENTS.md');
@@ -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 !== 20) fail(`--mode full should copy 20 skills, got ${fullModeSkillDirs.length}`);
+  if (fullModeSkillDirs.length !== 21) fail(`--mode full should copy 21 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/skills/jhste-long-running-work-loop/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: jhste-long-running-work-loop
+description: "Coordinate durable work loops when losing state would make work unsafe or hard to resume. Use when work spans sessions, wait states, recurring reviews, multiple repos, or durable decisions; does not replace code-quality, PRD, issue, triage, or handoff skills."
+---
+
+# jhste-long-running-work-loop
+
+Use this skill when the main risk is losing important work state, not merely because the task may take a long time. Decide whether a task needs a durable work loop, then keep the loop small, reviewable, and safe. Repo-local instructions remain authoritative.
+
+This is an orchestration skill. Do not reimplement code quality review, PRD writing, issue breakdown, triage, or handoff workflows. Route to the narrower skill when that is the actual task.
+
+## Scope
+
+Use for work where losing state would likely cause wrong, unsafe, duplicated, or hard-to-resume work across time, tools, repositories, or sessions:
+
+- multi-session implementation or review work;
+- recurring review/check-in loops;
+- same-day or multi-day external waiting states such as CI, preview deploys, reviewer replies, approvals, vendor/API responses, or customer input;
+- workflows spanning PRD, issues, implementation, review, and release notes;
+- work that touches multiple repositories or external systems;
+- hard-to-reverse design decisions that need a durable decision record;
+- tasks where the next session or next agent must resume safely.
+
+Skip for:
+
+- simple Q&A;
+- typo fixes;
+- formatting-only work;
+- small README edits;
+- small single-file fixes that can finish in one session;
+- direct requests that are only PRD drafting, issue breakdown, triage, or handoff;
+- work where the changed code path can be handled by `jhste-engineering-groundwork`, guard, and `jhste-red-team-review` alone.
+
+When skipping, use the narrower workflow. If useful, briefly note that a durable loop is unnecessary.
+
+## Contract
+
+1. **Decide if a durable loop is actually warranted.**
+   If not, route to the smallest applicable skill or workflow.
+
+2. **Define the work loop before expanding scope.**  
+   Capture only:
+   - current goal;
+   - current phase;
+   - definition of done;
+   - explicit out-of-scope items;
+   - open decisions;
+   - external blockers or wait states;
+   - approval boundaries;
+   - next checkpoint;
+   - required review gates.
+
+3. **Preserve context only when it will reduce future failure.**  
+   Do not turn project docs into scratchpads. Do not persist raw thought, private reasoning, secrets, or noisy progress logs.
+
+4. **Choose the right durable surface.**
+   - Domain vocabulary or stable domain context -> `CONTEXT.md`.
+   - Hard-to-reverse design decision with real trade-offs -> ADR.
+   - Active work state, blockers, acceptance, and next action -> issue or PR notes.
+   - Next-session or next-agent continuation only -> `handoff`.
+   - Ephemeral, obvious, or soon-stale state -> do not persist.
+
+5. **Resume by verifying, not trusting.**  
+   On resume, re-check the current repo, branch, issue/PR, CI, deployment, or external state before relying on old notes. Mark stale assumptions as not checked.
+
+6. **Respect approval boundaries.**  
+   Proceed without asking for reading, searching, summarizing, planning, drafting, review notes, and issue candidates when repo-local instructions allow it.  
+   Ask before send, push, merge, deploy, delete, publish, production data changes, secret exposure, cost-bearing actions, broad tracker edits, or destructive/irreversible changes.
+
+7. **Delegate to existing skills.**
+   - Before non-trivial code changes, use `jhste-engineering-groundwork`.
+   - After non-trivial code changes, run the configured guard when available and use `jhste-red-team-review`.
+   - For PRDs, use `to-prd`.
+   - For issue breakdown, use `to-issues`.
+   - For tracker triage, use `triage`.
+   - For next-agent/session summaries, use `handoff`.
+   - For domain glossary or ADR work, use `grill-with-docs` or the repo's domain-documentation workflow.
+
+## Minimal loop note
+
+When a durable loop is warranted, keep the note compact:
+
+```md
+## Durable work loop
+
+Goal:
+- ...
+
+Current phase:
+- ...
+
+Definition of done:
+- ...
+
+Out of scope:
+- ...
+
+Open decisions:
+- ...
+
+External blockers / wait states:
+- ...
+
+Approval required before:
+- ...
+
+Durable state location:
+- ...
+
+Next checkpoint:
+- ...
+
+Review gates:
+- ...
+```
+
+Prefer referencing existing artifacts by path or URL over duplicating their contents.
+
+## Context storage rules
+
+Unless repo-local docs define another role, treat `CONTEXT.md` as stable domain context, not a work log. Use it only for glossary or domain context that future agents need to understand the project correctly.
+
+Create or update an ADR only when all are true:
+
+1. the decision is hard to reverse;
+2. future readers would wonder why it was chosen;
+3. there were real alternatives and trade-offs.
+
+Use issue or PR notes for active work state because that state naturally expires when the work closes.
+
+Use handoff for continuation context that helps the next session but does not deserve permanent repo documentation.
+
+Record nothing when the information is trivial, already obvious from code/tests/diff, likely to go stale quickly, or not useful to future work.
+
+## Output style
+
+Be brief. Report:
+
+- whether the durable loop is warranted;
+- the chosen durable surface, if any;
+- the next checkpoint;
+- any action that requires approval;
+- which narrower skill should handle the next concrete step.