jhste-skills 0.3.4 → 0.3.5

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jhste-skills",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "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 multi-session or long-running work while preserving state, approval boundaries, and resume points. 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 to 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 that is likely to lose important state across time, tools, repositories, or sessions:
+
+- multi-session implementation or review work;
+- recurring review/check-in loops;
+- 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 long-running loop is unnecessary.
+
+## Contract
+
+1. **Decide if this is actually long-running.**  
+   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
+## Long-running 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 long-running 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.