@skilly-hand/skilly-hand 0.19.0 → 0.21.0

package/CHANGELOG.md

@@ -16,6 +16,42 @@ All notable changes to this project are documented in this file.
 ### Removed
 - _None._
 
+## [0.21.0] - 2026-04-11
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.21.0)
+
+### Added
+- Added portable skill `user-story-crafting` with integrated sub-agents for story writing, INVEST-based structuring, story splitting, and lightweight story mapping.
+
+### Changed
+- _None._
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
+## [0.20.0] - 2026-04-11
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.20.0)
+
+### Added
+- Added `scripts/dependency-policy-check.mjs` and `deps:policy:check` to enforce exact runtime dependency pins plus synchronized `package-lock.json`/`npm-shrinkwrap.json`.
+- Added `scripts/dependency-update-safe.mjs` and `deps:update:safe` to enforce safe dependency upgrades with full validation gates.
+- Added `npm-shrinkwrap.json` to the repository and release workflow for npm lockfile parity.
+- Added regression test coverage for dependency policy checks, safe dependency update flow, and managed git hook installation behavior.
+
+### Changed
+- Updated `verify:publish` to run dependency policy checks before security, catalog, test, and packlist gates.
+- Updated `scripts/setup-hooks.mjs` to install both managed `pre-commit` and `pre-push` hooks with safety checks for foreign hooks.
+- Updated `scripts/dependency-security-check.mjs` to recognize `npm-shrinkwrap.json` as a valid npm lockfile.
+- Updated docs with dependency update policy guidance and hook setup requirements.
+
+### Fixed
+- Expanded script JSON contract tests to cover `dependency-policy-check`.
+
+### Removed
+- _None._
+
 ## [0.19.0] - 2026-04-11
 [View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.19.0)
 

package/README.md

@@ -105,6 +105,10 @@ See [catalog/README.md](./catalog/README.md) for generated skill metadata.
 
 - `npm run security:check` runs repository secret/config checks plus strict dependency security checks.
 - `npm run security:deps` runs strict dependency audit + outdated reporting only.
+- `npm run deps:policy:check` enforces exact runtime dependency pins and lockfile sync (`package-lock.json` + `npm-shrinkwrap.json`).
+- `npm run deps:update:safe -- <pkg[@version]>` is the required dependency update path; it pins exact versions, syncs shrinkwrap, and blocks completion unless all validation gates pass.
+- Do not use raw `npm install` for dependency upgrades in this repo; use `deps:update:safe` so tests and security gates run before accepting version changes.
+- Run `npm run setup:hooks` once per clone to install `pre-commit` (fast checks) and `pre-push` (full gate) hooks.
 
 ---
 

package/catalog/README.md

@@ -18,5 +18,6 @@ Published portable skills consumed by the `skilly-hand` CLI.
 | `spec-driven-development` | Plan, execute, and verify multi-step work through versioned specs with small, testable tasks. | core, workflow, planning | all |
 | `test-driven-development` | Guide implementation using the RED → GREEN → REFACTOR TDD cycle: write a failing test first, write the minimum code to pass, then refactor while tests stay green. | testing, workflow, quality, core | all |
 | `token-optimizer` | Classify task complexity and right-size reasoning depth, context gathering, and response detail to reduce wasted tokens. | core, workflow, efficiency | all |
+| `user-story-crafting` | Create and refine user stories with structured quality gates, splitting heuristics, and lightweight story mapping for release slicing. Trigger: writing, restructuring, splitting, or sequencing user stories for delivery-ready backlog work. | product, workflow, planning, quality | all |
 
 Legacy source remains under `source/legacy/agentic-structure` and is excluded from installation.

package/catalog/catalog-index.json

@@ -12,5 +12,6 @@
   "skill-creator",
   "spec-driven-development",
   "test-driven-development",
-  "token-optimizer"
+  "token-optimizer",
+  "user-story-crafting"
 ]

package/catalog/skills/user-story-crafting/SKILL.md

@@ -0,0 +1,201 @@
+---
+description: "Create and refine user stories with structured quality gates, splitting heuristics, and lightweight story mapping for release slicing. Trigger: writing, restructuring, splitting, or sequencing user stories for delivery-ready backlog work."
+skillMetadata:
+  author: "skilly-hand"
+  last-edit: "2026-04-11"
+  license: "Apache-2.0"
+  version: "1.0.0"
+  changelog: "Added new user-story-crafting skill with integrated writing, structuring, splitting, and mapping agents; improves backlog quality and delivery sequencing through a unified user-story workflow; affects catalog skills, agent routing metadata, and managed AGENTS outputs"
+  auto-invoke: "Writing, restructuring, splitting, or sequencing user stories into delivery-ready backlog items"
+  allowed-tools:
+    - "Read"
+    - "Edit"
+    - "Write"
+    - "Glob"
+    - "Grep"
+    - "Bash"
+    - "Task"
+    - "SubAgent"
+---
+# User Story Crafting Guide
+
+## When to Use
+
+Use this skill when:
+
+- A backlog item needs to be written as a user-centered story.
+- A story is unclear, too technical, or missing measurable outcomes.
+- A story is too large to estimate or deliver safely in one iteration.
+- A team needs lightweight story mapping to sequence releases around user value.
+
+Do not use this skill for:
+
+- Pure engineering chores with no user outcome.
+- Architectural RFCs or deep technical design documents.
+- Sprint capacity planning unrelated to user behavior.
+
+---
+
+## Routing Map
+
+| Step | Intent | Sub-agent |
+| --- | --- | --- |
+| 1 | Draft the baseline user story and acceptance criteria | [agents/story-writer.md](agents/story-writer.md) |
+| 2 | Validate structure and quality with INVEST + anti-pattern checks | [agents/story-structurer.md](agents/story-structurer.md) |
+| 3 (if story is too large) | Split into independent, value-first increments | [agents/story-splitter.md](agents/story-splitter.md) |
+| 4 (optional) | Map activities, tasks, and release slices | [agents/story-mapper.md](agents/story-mapper.md) |
+
+Always run step 1 and step 2. Run step 3 when any size/risk signal appears. Run step 4 when roadmap sequencing or MVP slicing is requested.
+
+---
+
+## Standard Execution Sequence
+
+1. Capture context intake: persona, goal, problem, constraints, and assumptions.
+2. Draft one baseline story in Cohn format:
+   - `As a [persona]`
+   - `I want [capability]`
+   - `So that [outcome/value]`
+3. Add testable acceptance criteria in Given/When/Then structure.
+4. Run quality checks using INVEST plus ambiguity/measurability filters.
+5. If oversized or coupled, split into smaller stories using vertical slice patterns.
+6. Optionally organize split stories into a lightweight map with release slices.
+7. Return a final artifact bundle with:
+   - Polished stories
+   - Acceptance criteria
+   - INVEST review notes
+   - Split rationale (if applied)
+   - Map-ready release structure (if applied)
+
+---
+
+## Critical Patterns
+
+### Pattern 1: User Outcome First
+
+A story is valid only when it states user value, not implementation tasks.
+
+```text
+Good: As a returning customer, I want to reuse my saved card, so that checkout is faster.
+Bad: As a developer, I want to refactor payment services, so that code is cleaner.
+```
+
+### Pattern 2: Acceptance Criteria Must Be Testable
+
+Every criterion should be observable and verifiable by behavior.
+
+```gherkin
+Given a logged-in customer with a saved card
+When they choose "Pay with saved card"
+Then the order is submitted without re-entering card details
+```
+
+### Pattern 3: INVEST Is a Gate, Not a Suggestion
+
+Before finalizing any story, verify:
+
+- Independent
+- Negotiable
+- Valuable
+- Estimable
+- Small
+- Testable
+
+If two or more INVEST checks fail, do not finalize; split or rewrite first.
+
+### Pattern 4: Split by User Value, Not by System Layer
+
+Prefer vertical slices that preserve end-to-end user outcomes.
+
+```text
+Good split: Browse -> Add -> Pay (thin end-to-end slice first)
+Bad split: Frontend -> Backend -> Database
+```
+
+### Pattern 5: Mapping Is Lightweight and Release-Oriented
+
+Story mapping is used to sequence value, not to model exhaustive edge-case detail up front.
+
+---
+
+## Decision Tree
+
+```text
+Need a new story from a request?
+  -> Draft with story-writer
+
+Story written but quality unclear?
+  -> Run story-structurer
+
+Story fails Small/Estimable/Independent?
+  -> Run story-splitter
+
+Need MVP/release sequencing?
+  -> Run story-mapper
+
+No user value is present?
+  -> Reframe as user outcome or classify as non-story technical work item
+```
+
+---
+
+## Output Contract
+
+Return results in this order:
+
+1. **Context Snapshot**: persona, problem, desired outcome, constraints.
+2. **Final Story Set**: one or more refined user stories.
+3. **Acceptance Criteria**: Given/When/Then per story.
+4. **Quality Review**: INVEST pass/fail + fixes applied.
+5. **Split + Map Notes**: split rationale and release slice proposal (when used).
+
+---
+
+## Example
+
+### Input
+
+```text
+"Users abandon onboarding because setup is confusing."
+```
+
+### Condensed Output
+
+```text
+Context Snapshot
+- Persona: New team admin
+- Problem: Setup confusion during first session
+- Outcome: Reach first successful project setup quickly
+
+Final Story Set
+- As a new team admin, I want a guided setup checklist, so that I can complete onboarding without guessing next steps.
+
+Acceptance Criteria
+- Given I created a new workspace
+  When I open the onboarding page
+  Then I see a checklist of setup steps in recommended order
+- Given I complete one setup step
+  When I return to onboarding
+  Then progress shows the completed step and next recommended action
+
+Quality Review
+- INVEST: Pass (all six checks)
+
+Split + Map Notes
+- Not required for this scope
+```
+
+---
+
+## Commands
+
+```bash
+# Validate catalog metadata/frontmatter drift
+npm run catalog:check
+
+# Apply frontmatter + README sync changes
+npm run catalog:sync
+
+# Regenerate managed AGENTS files after catalog updates
+npm run agentic:self:sync
+```

package/catalog/skills/user-story-crafting/agents/story-mapper.md

@@ -0,0 +1,73 @@
+# Story Mapper
+
+## Goal
+
+Arrange stories into a lightweight map that supports release slicing and MVP sequencing around user behavior.
+
+---
+
+## When to Use
+
+Use this agent when teams need planning visibility across activities, tasks, and release increments.
+
+Do not use this agent to replace detailed implementation planning.
+
+---
+
+## Mapping Structure
+
+Build map with three layers:
+
+1. **Backbone activities** (horizontal): major user journey stages.
+2. **User tasks/stories** (vertical under each activity).
+3. **Release slices** (horizontal cuts): walking skeleton first, then enhancements.
+
+---
+
+## Backbone Rules
+
+- Backbone must be user workflow language, not technical architecture.
+- Each activity should represent a meaningful step in user progress.
+- Keep activity count focused (typically 4-8 for first pass).
+
+---
+
+## Release Slicing Rules
+
+- **Release 1** should be a walking skeleton across all core activities.
+- Later releases add depth, alternatives, and optimization.
+- Every release must preserve end-to-end user value.
+
+---
+
+## Output Template
+
+```text
+Backbone Activities
+- Activity A -> Activity B -> Activity C
+
+Story Map
+Activity A
+- Story A1
+- Story A2
+
+Activity B
+- Story B1
+- Story B2
+
+Release Slices
+- Release 1 (Walking Skeleton): A1 + B1 + C1
+- Release 2: A2 + B2 + C2
+- Release 3: advanced variants
+
+Mapping Notes
+- Risks, assumptions, and unresolved questions
+```
+
+---
+
+## Anti-Patterns
+
+- Backbone modeled as "Frontend -> Backend -> Database".
+- Release 1 defined as feature-complete for only one activity.
+- Excessive edge-case detail before core flow is aligned.

package/catalog/skills/user-story-crafting/agents/story-splitter.md

@@ -0,0 +1,72 @@
+# Story Splitter
+
+## Goal
+
+Break oversized stories into smaller, independently valuable slices that can be estimated and released incrementally.
+
+---
+
+## When to Use
+
+Use this agent when a story fails Small/Estimable/Independent checks, or bundles multiple outcomes.
+
+---
+
+## Split Signals
+
+Split when any of the following are true:
+
+- More than one user outcome exists in a single story.
+- Acceptance criteria represent multiple distinct flows.
+- Cross-team dependencies block completion as one unit.
+- The story cannot fit in one iteration.
+
+---
+
+## Split Heuristics
+
+Prefer these patterns:
+
+1. **Workflow step split**: separate sequential steps in the user journey.
+2. **Operation split**: create/read/update/delete separated when value is independent.
+3. **Business rule split**: start with core rule, defer advanced policies.
+4. **Data variation split**: start with most common scenario, add variants later.
+5. **Interface split**: core interaction first, advanced controls later.
+6. **Error/edge split**: deliver happy path first if safe, then harden.
+
+Never split by technical architecture layers.
+
+---
+
+## Vertical Slice Rule
+
+Each split story should:
+
+- Preserve user-visible value.
+- Be releasable without hidden prerequisites where possible.
+- Keep clear acceptance criteria and ownership.
+
+If a candidate split has no user value, classify it as technical work and detach from story set.
+
+---
+
+## Output Template
+
+```text
+Original Story Risk
+- Why story is too large/coupled
+
+Split Strategy Chosen
+- Pattern used and rationale
+
+Split Story Set
+1. As a ... I want ... So that ...
+2. As a ... I want ... So that ...
+
+Acceptance Criteria per Story
+- Story 1: Given ... When ... Then ...
+- Story 2: Given ... When ... Then ...
+
+Sequencing Notes
+- Story order and dependency notes
+```

package/catalog/skills/user-story-crafting/agents/story-structurer.md

@@ -0,0 +1,77 @@
+# Story Structurer
+
+## Goal
+
+Apply consistent quality gates so stories are clear, testable, and ready for estimation.
+
+---
+
+## When to Use
+
+Use this agent after `story-writer` drafts a story, or when reviewing existing stories for quality.
+
+---
+
+## INVEST Gate
+
+Score each story against:
+
+- **Independent**: Can it be delivered without hidden coupling?
+- **Negotiable**: Is solution space still open?
+- **Valuable**: Is user/business value explicit?
+- **Estimable**: Is scope concrete enough to size?
+- **Small**: Can it be completed inside one iteration?
+- **Testable**: Do acceptance criteria prove completion?
+
+Mark each as `Pass`, `Needs Revision`, or `Fail`.
+
+If `Small`, `Estimable`, or `Independent` fails, route to `story-splitter`.
+
+---
+
+## Quality Filters
+
+Run these checks in addition to INVEST:
+
+1. **Ambiguity filter**: remove vague terms (`easy`, `quick`, `improved`, `optimized`) unless defined.
+2. **Outcome filter**: ensure the "So that" clause names real value.
+3. **Criteria filter**: ensure each criterion has observable outcomes.
+4. **Dependency filter**: list external dependencies and whether they block release.
+
+---
+
+## Rewrite Rules
+
+When quality fails, rewrite with minimal drift:
+
+- Keep the original user intent.
+- Replace implementation-heavy wording with user behavior language.
+- Keep acceptance criteria concise and verifiable.
+
+---
+
+## Output Template
+
+```text
+INVEST Review
+- Independent: Pass | Needs Revision | Fail
+- Negotiable: Pass | Needs Revision | Fail
+- Valuable: Pass | Needs Revision | Fail
+- Estimable: Pass | Needs Revision | Fail
+- Small: Pass | Needs Revision | Fail
+- Testable: Pass | Needs Revision | Fail
+
+Quality Findings
+- ...
+
+Revised Story
+- As a ...
+- I want ...
+- So that ...
+
+Revised Acceptance Criteria
+- Given ... When ... Then ...
+
+Routing Decision
+- Keep as-is | Revise only | Split required
+```

package/catalog/skills/user-story-crafting/agents/story-writer.md

@@ -0,0 +1,91 @@
+# Story Writer
+
+## Goal
+
+Convert rough requests into clear, user-centered stories with testable acceptance criteria.
+
+---
+
+## When to Use
+
+Use this agent when:
+
+- The input is a feature idea, request, bug narrative, or vague backlog note.
+- A story must be drafted in a standard format for engineering handoff.
+
+Do not use this agent when:
+
+- The work item has no user outcome and should remain a technical task.
+- The story is already fully formed and only needs quality review.
+
+---
+
+## Story Format
+
+Always draft in this structure:
+
+```text
+As a [specific persona]
+I want [capability/action]
+So that [measurable user or business outcome]
+```
+
+Rules:
+
+- Persona must be concrete (role + context), not "user" unless truly broad.
+- "I want" states behavior or capability, not implementation details.
+- "So that" states value/outcome, not vague intent.
+
+---
+
+## Acceptance Criteria Protocol
+
+Produce 3-7 criteria using Given/When/Then.
+
+```gherkin
+Given [starting context]
+When [trigger/action]
+Then [observable result]
+```
+
+Quality checks:
+
+- Each Then is objectively verifiable.
+- Avoid words like "better", "faster", "intuitive" without measurable definition.
+- Include negative/error path criteria when risk is material.
+
+---
+
+## Drafting Procedure
+
+1. Extract context: persona, goal, pain, constraints.
+2. Write one baseline story.
+3. Draft acceptance criteria that cover happy path + key edge behavior.
+4. Flag any missing context assumptions explicitly.
+5. Hand off to `story-structurer` for quality gates.
+
+---
+
+## Output Template
+
+```text
+Story
+- As a ...
+- I want ...
+- So that ...
+
+Acceptance Criteria
+- Given ... When ... Then ...
+- Given ... When ... Then ...
+
+Assumptions
+- ...
+```
+
+---
+
+## Anti-Patterns
+
+- "As a developer..." used to hide technical tasks as user stories.
+- Acceptance criteria as implementation checklists.
+- Story value that cannot be observed or measured.

package/catalog/skills/user-story-crafting/manifest.json

@@ -0,0 +1,29 @@
+{
+  "id": "user-story-crafting",
+  "title": "User Story Crafting",
+  "description": "Create and refine user stories with structured quality gates, splitting heuristics, and lightweight story mapping for release slicing. Trigger: writing, restructuring, splitting, or sequencing user stories for delivery-ready backlog work.",
+  "portable": true,
+  "tags": ["product", "workflow", "planning", "quality"],
+  "detectors": ["always"],
+  "detectionTriggers": ["always"],
+  "installsFor": ["all"],
+  "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot", "antigravity", "windsurf", "trae"],
+  "skillMetadata": {
+    "author": "skilly-hand",
+    "last-edit": "2026-04-11",
+    "license": "Apache-2.0",
+    "version": "1.0.0",
+    "changelog": "Added new user-story-crafting skill with integrated writing, structuring, splitting, and mapping agents; improves backlog quality and delivery sequencing through a unified user-story workflow; affects catalog skills, agent routing metadata, and managed AGENTS outputs",
+    "auto-invoke": "Writing, restructuring, splitting, or sequencing user stories into delivery-ready backlog items",
+    "allowed-modes": ["story-writer", "story-structurer", "story-splitter", "story-mapper"],
+    "allowed-tools": ["Read", "Edit", "Write", "Glob", "Grep", "Bash", "Task", "SubAgent"]
+  },
+  "files": [
+    { "path": "SKILL.md", "kind": "instruction" },
+    { "path": "agents/story-writer.md", "kind": "instruction" },
+    { "path": "agents/story-structurer.md", "kind": "instruction" },
+    { "path": "agents/story-splitter.md", "kind": "instruction" },
+    { "path": "agents/story-mapper.md", "kind": "instruction" }
+  ],
+  "dependencies": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/skilly-hand",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "license": "CC-BY-NC-4.0",
   "type": "module",
   "publishConfig": {
@@ -29,11 +29,13 @@
     "catalog:sync": "node ./scripts/sync-catalog.mjs",
     "agentic:self:sync": "node ./scripts/sync-self-agentic.mjs",
     "test": "node --test tests/*.test.js && node ./scripts/test-in-sandbox.mjs",
+    "deps:policy:check": "node ./scripts/dependency-policy-check.mjs",
+    "deps:update:safe": "node ./scripts/dependency-update-safe.mjs",
     "security:deps": "node ./scripts/dependency-security-check.mjs --strict",
     "security:check": "node ./scripts/security-check.mjs --strict-deps",
     "verify:packlist": "node ./scripts/verify-packlist.mjs",
     "verify:versions": "node ./scripts/verify-versions.mjs",
-    "verify:publish": "npm run verify:versions && npm run security:check && npm run catalog:check && npm test && npm run verify:packlist",
+    "verify:publish": "npm run verify:versions && npm run deps:policy:check && npm run security:check && npm run catalog:check && npm test && npm run verify:packlist",
     "publish:prepare": "npm run verify:publish && npm pack --dry-run --json",
     "publish:otp": "node ./scripts/publish-with-otp.mjs",
     "publish:next": "node ./scripts/publish-with-otp.mjs --tag next",
@@ -47,7 +49,7 @@
     "doctor": "node ./packages/cli/src/bin.js doctor"
   },
   "dependencies": {
-    "ink": "^5.2.1",
-    "react": "^18.3.1"
+    "ink": "5.2.1",
+    "react": "18.3.1"
   }
 }

package/packages/catalog/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/catalog",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "private": true,
   "type": "module"
 }

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/cli",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "private": true,
   "type": "module",
   "bin": {

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/core",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "private": true,
   "type": "module"
 }

package/packages/detectors/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/detectors",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "private": true,
   "type": "module"
 }