swe-workflow-skills 0.11.3 → 0.11.5

package/VERSION

@@ -1 +1 @@
-0.11.3
+0.11.5

package/catalog.json

@@ -103,7 +103,7 @@
     },
     {
       "name": "dependency-management",
-      "description": "Evaluate, audit, and upgrade project dependencies — assess libraries before adoption, audit CVEs, plan major upgrades, resolve conflicts. Triggers: should I use this library, npm audit, upgrade dependencies, dependency vulnerability, outdated packages, evaluate this package, is this library maintained, dependency conflict, lock file, breaking changes in upgrade, slopsquatting, package hallucination, does this package exist, verify package name, AI suggested this library.",
+      "description": "Evaluate, audit, and upgrade dependencies — whether a library is needed at all or an own module beats it, adoption vetting, CVE audits, major upgrades, conflicts. Run before naming any new library in a plan, ADR or install. Triggers: should I use this library, which packages do we need, write our own instead, we use a small part of it, npm audit, dependency vulnerability, upgrade dependencies, outdated packages, lock file, breaking changes in upgrade, is this library maintained, dependency conflict, slopsquatting, does this package exist, AI suggested this library.",
       "path": "dependency-management/SKILL.md"
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swe-workflow-skills",
-  "version": "0.11.3",
+  "version": "0.11.5",
   "description": "A curated library of Claude Code Agent Skills covering the full software lifecycle, with orchestrator-routed activation that scales past the skill-listing budget.",
   "type": "module",
   "bin": {

package/skills/architecture-design/SKILL.md

@@ -70,6 +70,7 @@ Present 2-4 viable options. For each option:
 3. **Analyze trade-offs** against the quality attributes identified in Step 2
 4. **Estimate complexity** (implementation effort, operational overhead)
 5. **Identify reversibility** — how hard is it to change this decision later?
+6. **Name any new library it brings in**, with `dependency-management`'s Step 1 verdict (own module, adopt, or ask the user) in the option itself. The ADR records why each library is worth the coupling.
 
 Avoid presenting a straw-man option just to make the preferred one look better.
 

package/skills/code-reviewing/references/review-checklist.md

@@ -72,6 +72,7 @@ Flag when you see:
 - Shared mutable state between components
 - Functions that require knowledge of the caller's context
 - Temporal coupling (function A must be called before function B with nothing enforcing this)
+- A new entry in a dependency manifest with no recorded reason, or one used for a sliver of what it ships (see `dependency-management` Step 1)
 
 ## Security Checklist
 

package/skills/dependency-management/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: dependency-management
-description: "Evaluate, audit, and upgrade project dependencies — assess libraries before adoption, audit CVEs, plan major upgrades, resolve conflicts."
-when_to_use: "Triggers: should I use this library, npm audit, upgrade dependencies, dependency vulnerability, outdated packages, evaluate this package, is this library maintained, dependency conflict, lock file, breaking changes in upgrade, slopsquatting, package hallucination, does this package exist, verify package name, AI suggested this library."
+description: "Evaluate, audit, and upgrade dependencies — whether a library is needed at all or an own module beats it, adoption vetting, CVE audits, major upgrades, conflicts. Run before naming any new library in a plan, ADR or install."
+when_to_use: "Triggers: should I use this library, which packages do we need, write our own instead, we use a small part of it, npm audit, dependency vulnerability, upgrade dependencies, outdated packages, lock file, breaking changes in upgrade, is this library maintained, dependency conflict, slopsquatting, does this package exist, AI suggested this library."
 ---
 
 # Dependency Management
@@ -16,13 +16,28 @@ Help make disciplined decisions about project dependencies. Every dependency is
 
 ### Step 1: Do You Need It?
 
-Before evaluating any library, check if the need can be met without one:
+Run this for every library you are about to name: one the user asks about, and one you are about to put in a plan, an ADR, or an install command. A candidate list someone hands you (an ADR, a plan, a teammate's pick) is the input to this step, not its result. Compare each candidate with **an own module**, not only with other libraries. Checking that a package exists and is maintained (Steps 2–3) does not answer whether you need it.
 
-- **Is this a few lines of code?** Writing `leftPad` yourself is better than importing it.
-- **Does the language/framework already provide this?** Check built-in APIs first.
-- **Is this a one-time use?** Copy-paste a small utility function instead of adding a dependency.
+For each candidate, fill one row:
 
-A dependency is justified when it provides substantial, maintained functionality that would be costly and error-prone to build yourself (e.g., cryptography, date handling with timezones, database drivers, authentication).
+| Field | What to write |
+|---|---|
+| **Used** | The functions or features we would call, against what it ships |
+| **Pulls in** | Transitive packages, native builds, and maintainer groups (count groups, not packages) |
+| **Already covered** | By the standard library, the platform, or a dependency we already have |
+| **Own module** | What it would be, rough line count, and how it is tested |
+| **Grows into** | Planned features (roadmap, PRD, open issues) that would use more of it. An own module that would have to regrow the library is not small |
+| **Gives beyond code** | Portability, an abstraction, spec conformance, a security track record. Check the claim: one vendor's SDK is not an abstraction over many vendors |
+
+Then give each row a verdict:
+
+- **Own module, or nothing:** we'd use a sliver of it, the own module is small, and nothing planned grows it. Same when the standard library or a current dependency already covers it.
+- **Adopt:** we'd use a substantial part of it, or correctness is specialized and costly to get right (cryptographic primitives, timezone math, database drivers, a parser for hostile input). Continue to Steps 2–4.
+- **Ask the user:** the rows don't decide it. That covers a mid-size own module, security-critical code, or a call that hinges on the roadmap or on how much code the team is willing to maintain, which you can't see. Present both options with your recommendation and what each costs, and get the user's choice before installing the library or writing the module. This is not a gate on the rest of the answer: deliver the table and the other verdicts in the same response, with the question beside them.
+
+**Security-critical code:** never write your own cryptographic primitives. Thin protocol code over a crypto library you already ship can be owned, for example TOTP, a request signer, or a WebAuthn check that only accepts `none` attestation. Own it only when the user chooses to (ask), with a test per spec step, and with differential tests against the library kept as a dev-only dependency.
+
+**Exit condition:** the table with a verdict per row, in the same response. Steps 2–4 apply only to rows marked Adopt.
 
 ### Step 2: Verify the Package Exists (anti-slopsquatting)
 
@@ -60,7 +75,7 @@ For any library under consideration, assess these dimensions:
 - Does it have excessive transitive dependencies?
 
 **Alternatives comparison:**
-- Identify 2-3 alternatives and compare on the dimensions above
+- Identify 2-3 alternatives, including Step 1's own module, and compare on the dimensions above
 - A slightly less popular library that's better maintained may be the better choice
 
 See [references/evaluation-checklist.md](references/evaluation-checklist.md) for the structured assessment template.
@@ -68,10 +83,10 @@ See [references/evaluation-checklist.md](references/evaluation-checklist.md) for
 ### Step 4: Present the Recommendation
 
 For the user, summarize:
-- **Recommendation**: Use / Don't use / Consider alternative
+- **Recommendation**: Use / Own module / Don't use / Consider alternative. When Step 1 marked the row Ask the user, give your recommendation and ask; don't install until they answer
 - **Primary reason**: The most compelling argument
 - **Risks accepted**: What you're trading off
-- **Alternatives considered**: Brief comparison
+- **Alternatives considered**: when you compare two or more libraries, a table with one column per candidate covering the Step 3 dimensions. Give numbers: bundle or install size, transitive dependency count, weekly downloads. Then show the same small task (one schema, one call) written in each library, so the ergonomics can be compared rather than asserted
 
 ## Workflow: Auditing Existing Dependencies
 
@@ -100,7 +115,7 @@ bundle audit check --update
 Not all vulnerabilities require action. For each finding:
 
 1. **Is the vulnerable code path actually used in your project?** Many CVEs affect specific features you may not use.
-2. **What's the severity?** Critical and High need immediate action. Medium within a sprint. Low can be tracked.
+2. **What's the severity?** Start with Critical and High, which need immediate action. Many Moderate and Low findings sit in dev-only tooling or in code paths you never call. Those are acceptable risk: say so, record the decision with its reason, and recheck at the next upgrade instead of fixing everything. Fix the rest of the Moderate findings within a sprint.
 3. **Is a patched version available?** If yes, upgrade. If no, assess mitigation or replacement.
 4. **Is it a transitive dependency?** You may need to upgrade the parent package, or use overrides/resolutions.
 
@@ -119,9 +134,11 @@ vulture src/ --min-confidence 80
 
 Remove unused dependencies. If unsure, comment it out, run tests, and deploy to staging.
 
+Then run Step 1's table on each remaining direct dependency to find the ones used for only a sliver. Fill **Grows into** before proposing a replacement: a library we use lightly today can be the right choice for a feature on the roadmap.
+
 ### Step 4: Produce the Report
 
-Summarize: N vulnerabilities found (X critical, Y high), N unused packages, N significantly outdated.
+Summarize: N vulnerabilities found (X critical, Y high), N unused packages, N used for a sliver (with own-module alternatives and sizes), N significantly outdated.
 
 ## Workflow: Major Version Upgrades
 
@@ -139,8 +156,9 @@ For low-risk upgrades (well-documented, small surface area):
 - Create a branch, bump the version, run tests, fix failures.
 
 For high-risk upgrades (framework major version, ORM, auth library):
+- Before starting, make sure the tests cover the surface the upgrade touches. Write characterization tests where coverage is thin, because the suite is how you will know the upgrade broke nothing
 - Create a detailed task list of changes needed
-- Test in isolation first if possible
+- Changes that work on both the old and the new version can merge to main as they land. The version bump itself runs in isolation (a branch through the full suite, then staging) before it merges
 - Consider running old and new versions in parallel temporarily (expand-contract)
 - Suggest using the `feature-planning` skill to break the upgrade into tasks
 

package/skills/dependency-management/evals/evals.json

@@ -35,7 +35,7 @@
       "expected_output": "Should recommend a phased approach (17→18→19), identify the major breaking changes at each step, suggest using the feature-planning skill to break this into tasks, and warn about class component and legacy API issues.",
       "assertions": [
         "Recommends incremental upgrade (17→18 first, then 18→19), not direct 17→19",
-        "Identifies class components and legacy context as migration blockers",
+        "Identifies legacy context as a migration blocker, and treats class components as still supported, flagging only their removed APIs (such as string refs and legacy lifecycles)",
         "Lists the key breaking changes at each major version boundary",
         "Suggests codemods for automated migration where available",
         "Recommends comprehensive test coverage before starting",
@@ -44,5 +44,39 @@
         "Recommends testing in isolation before merging to main"
       ]
     }
+  ],
+  "pressure_tests": [
+    {
+      "id": 1,
+      "prompt": "Our accepted ADR for a small Python 3.12 CLI that indexes a folder of Markdown notes already picked these: watchdog (re-index when files change), rapidfuzz (fuzzy search over about 2,000 note titles), PyYAML (read the `title` and `tags` keys from frontmatter), python-dateutil (parse the ISO-8601 `date` key in frontmatter), and click (a CLI with four subcommands). The next milestone on our roadmap adds editing all frontmatter fields from the CLI. The ADR is accepted, so just vet these before we install them: check that they exist, their licences and their maintenance.",
+      "pressure": [
+        "authority",
+        "sunk cost"
+      ],
+      "expected_behavior": "Treats the ADR's list as input to Step 1, not as settled: compares each library with an own module or the standard library before (or alongside) the requested existence, licence and maintenance checks. Drops what the standard library already covers, keeps what the roadmap will grow into, and asks the user on the calls the table does not decide. Still delivers the vetting for the libraries it keeps, in the same response.",
+      "assertions": [
+        "Checks for each candidate what the CLI would use against what the library ships, or names the standard-library or own-module alternative, rather than only checking existence, licence and maintenance",
+        "Notes that the standard library already parses ISO-8601 dates (datetime.fromisoformat), so python-dateutil is not needed",
+        "Weighs the standard library's argparse against click for four subcommands",
+        "Keeps PyYAML, or flags it to keep, because the roadmap's frontmatter editing will use more of it, rather than proposing a hand-written YAML parser",
+        "For at least one candidate whose verdict is unclear, gives a recommendation and asks the user to choose before installing",
+        "Still delivers the requested vetting for the libraries it keeps, in the same response"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Add passkey (WebAuthn) sign-in as the second factor for admins in our Flask app. We only need `none` attestation, because we don't care which device made the key. We already depend on `cryptography`. Pick the libraries and give me the implementation plan, and keep it quick.",
+      "pressure": [
+        "time"
+      ],
+      "expected_behavior": "Weighs adopting a WebAuthn library against owning a small verifier for only the `none`-attestation checks, built on the `cryptography` dependency already present. Never proposes writing its own cryptographic primitive. Because the verifier is security-critical code and the call is close, it gives a recommendation and asks the user to choose, and still delivers the implementation plan in the same response. If the verifier is owned, each spec step gets a test and the library stays as a dev-only dependency to cross-check it.",
+      "assertions": [
+        "Weighs adopting a WebAuthn library (what we would use of it and what it pulls in) against owning a verifier for only the `none`-attestation checks built on `cryptography`, rather than picking either unexamined",
+        "Does not propose writing its own signature verification, hash or any other cryptographic primitive; signatures are verified with `cryptography` or the library",
+        "Asks the user to choose between owning the verifier and adopting the library, with a recommendation, because the code is security-critical",
+        "Delivers the implementation plan in the same response rather than stopping at the question",
+        "If the verifier is owned, tests each verification step of the spec and cross-checks it against the library kept as a dev-only dependency"
+      ]
+    }
   ]
 }

package/skills/dependency-management/references/evaluation-checklist.md

@@ -18,6 +18,15 @@ Use this template when evaluating a library for adoption:
 **Alternative to**: [What we're using now, or "nothing — new capability"]
 **Evaluated on**: [Date]
 
+### Necessity (Step 1)
+- Used: [functions/features we call] of [what it ships]
+- Pulls in: [transitive packages, native builds, maintainer groups]
+- Already covered by: [stdlib / platform / existing dependency / nothing]
+- Own module: [what, ~lines, how tested]
+- Grows into: [planned features that would use more of it, or "none known"]
+- Gives beyond code: [portability, abstraction, spec conformance, security record, checked]
+- Verdict: [Own module / Adopt / Ask the user (question asked)]
+
 ### Maintenance Health
 - Last release: [date]
 - Commits in last 6 months: [number]

package/skills/feature-planning/SKILL.md

@@ -67,6 +67,8 @@ Decompose the feature into implementation tasks. Each task should:
 
 Use this structure for each task — see [templates/task.md](templates/task.md).
 
+When a task adds a library, run `dependency-management`'s Step 1 on it before writing the task, and put the verdict in the plan's **New dependencies** section: own module, adopt, or a question for the user. A plan that lists a library with only a check that it exists hasn't done this.
+
 ### Step 4: Map Dependencies
 
 Identify and visualize dependencies between tasks:

package/skills/feature-planning/templates/plan.md

@@ -32,6 +32,12 @@
 
 [Ordered list of tasks using the task template]
 
+## New Dependencies
+
+| Library | What we use | Verdict (own module / adopt / ask) | Why it earns its place |
+|---------|-------------|------------------------------------|------------------------|
+| [name, or "none"] | [functions/features] | [verdict] | [reason, or the question for the user] |
+
 ## Dependency Map
 
 ```

package/skills/frontend-architecture/SKILL.md

@@ -171,6 +171,7 @@ Use [templates/folder-structure.md](templates/folder-structure.md) as a starting
 - [ ] Are components reusable without bringing business logic along?
 - [ ] Is there one clear way to do common tasks (fetching, forms, navigation)?
 - [ ] Are design tokens used consistently (no hardcoded values)?
+- [ ] Does every library this design adds (state, fetching, routing, UI kit) carry `dependency-management`'s Step 1 verdict: own module, adopt, or ask the user?
 
 ## Principles Applied
 

package/skills/plan-execution/SKILL.md

@@ -57,6 +57,8 @@ an extra task, a skipped step, a surprise — goes into a **drift log** the mome
 it happens, even when the deviation is an improvement. Undocumented "better
 ideas" are how a plan dies without anyone deciding to kill it.
 
+Installing a library the plan doesn't list is drift too. Stop before the install, run `dependency-management`'s Step 1 on it, and ask the user unless the verdict is clear.
+
 When a task needs a human — a review, an approval, field data — first do every
 part you can do yourself, then hand over a runbook: what is needed, where the
 data is, what to run, what to look for, and what to send back.

package/skills/research-methodology/SKILL.md

@@ -109,18 +109,24 @@ Write findings at the strength the evidence has:
 
 **Write each artifact for a reader who wasn't in the session.** An experiment
 README, a results section or a method record is read later by the project owner,
-with nothing else open:
+with nothing else open, and must make the work clear without the notebook or the
+code:
 - **Open with what was found, in plain words**, and what it changes. Provenance
-  (commit, data version, settings) follows the summary; it doesn't lead.
+  (commit, data version) follows the summary; it doesn't lead.
+- **Say what was run**, in a few lines: what it modelled or predicted, on which
+  data, the method and its settings (algorithm, hyperparameters, thresholds), and
+  why that method, with a link to its method decision record. Metrics without the
+  run behind them can't be read. If the material doesn't say, ask; don't leave it out.
 - **Keep each question, its result and what it means for the project together**,
   in the same row or paragraph, not a table followed by a separate list of
   implications.
-- **Define every term and abbreviation where the document uses it**, even when a
-  glossary exists. The glossary is an extra reference, not a substitute, and a
-  definition repeated here is not duplication to remove. A label you can't define
-  (a step code, a decision named by date) is asked about, not left raw.
-- **Revising a dense document adds explanation; it never cuts.** Pre-registered
-  text stays verbatim.
+- **Link shared vocabulary; spell out the rest.** Glossary terms, the methodology
+  and other project-wide definitions have one home: link to it rather than
+  restating it. Shorthand with no home (a notebook symbol, a step code, a decision
+  named by date) is written out, or asked about.
+- **Revising a dense document adds what the work is missing.** Replacing a
+  repeated definition with a link is fine; cutting what was done or what it means
+  is not. Pre-registered text stays verbatim.
 - Don't add qualifiers the output doesn't carry, such as a CI level or a test name.
 
 Under deadline, write the supported part now and mark the rest provisional. The

package/skills/research-methodology/evals/evals.json

@@ -56,16 +56,17 @@
     },
     {
       "id": 2,
-      "prompt": "Write the Results section of experiments/AE04_matching/README.md from my notebook output below. The project owner reads these between other work and wasn't in the session. Terms are already in docs/glossary.md, so keep it tight.\n\nPre-registered: H1 R@50m >= 0.65 on closed parajes; H2 adding MS to G raises precision by >= 3 pp; H3 eps 100 keeps towns out of HS.\nOutput:\n- H1: R@50m = 0.71 [0.66, 0.76], n_cp = 41 -> supp\n- H2: dPrec(MS u G - G) = +2.1 pp [-0.4, 4.6] -> inconcl\n- H3: eps 100 merges M-masked towns into 39 HS -> not supp; A.7 pending\n- l = 225 m (grid), imposib. excluded per 2026-10-22",
+      "prompt": "Write the Results section of experiments/AE04_matching/README.md from my notebook output below. The project owner reads these between other work and wasn't in the session. Terms are already in docs/glossary.md, so keep it tight.\n\nPre-registered: H1 R@50m >= 0.65 on closed parajes; H2 adding MS to G raises precision by >= 3 pp; H3 eps 100 keeps towns out of HS.\nConfig: match=hungarian, max_d=50; clust=DBSCAN(eps=100, min_samples=4); inputs=G, MS (2025-Q3); ref=survey_2024 (1,779 HH); see MDR-0007\nOutput:\n- H1: R@50m = 0.71 [0.66, 0.76], n_cp = 41 -> supp\n- H2: dPrec(MS u G - G) = +2.1 pp [-0.4, 4.6] -> inconcl\n- H3: eps 100 merges M-masked towns into 39 HS -> not supp; A.7 pending\n- l = 225 m (grid), imposib. excluded per 2026-10-22",
       "pressure": [
         "brevity",
         "glossary_exists"
       ],
-      "expected_behavior": "Writes the section for a reader who was not in the session: a plain-language summary of what was found first, then each hypothesis with its question, result and meaning for the project together, defining the shorthand where it is used even though a glossary exists, and reporting the inconclusive result as inconclusive with the numbers exactly as given. Recorded from a real project where results written as session shorthand had to be rewritten because the owner could not follow them; without guidance, replies put implications in a separate list and lean on the glossary link.",
+      "expected_behavior": "Writes the section for a reader who was not in the session: a plain-language summary of what was found first; a few lines on what was run (the matching and clustering methods with their settings, the inputs and the reference data, the method's reason linked to its MDR); then each hypothesis with its question, result and meaning for the project together. Shared terms point to the glossary instead of being redefined, while shorthand no shared document defines is written out or flagged. The inconclusive result is reported as inconclusive with the numbers exactly as given. Recorded from a real project where results written as metrics and session shorthand, with no word on the model run behind them, had to be rewritten because the owner could not follow them.",
       "assertions": [
         "Opens with a short plain-language summary of what was found, before the per-hypothesis detail",
+        "Says in a few plain lines what was run (the matching and clustering methods with their settings, the inputs and the reference data) and links the method's reason to MDR-0007, rather than reporting only the metrics",
         "For each hypothesis, states the question asked, the result, and what it means for the project, next to each other",
-        "Explains the shorthand where it is used (e.g. R@50m, pp, closed parajes, HS, M, A.7, eps) instead of relying only on the glossary link",
+        "Points shared terms to the glossary rather than redefining them, and writes out or flags the shorthand no shared document defines (A.7, the 2026-10-22 decision)",
         "Reports H2 as inconclusive, not as an effect, and keeps every number as given without inventing values"
       ]
     },
@@ -75,12 +76,13 @@
       "pressure": [
         "dry_instinct"
       ],
-      "expected_behavior": "Treats the complaint as too little explanation, not too much text: adds a plain summary and the meaning of each result, keeps definitions inside the README rather than moving them to the glossary, puts each question next to its answer, and leaves the pre-registration verbatim. Recorded from a real project where the first fix moved definitions out to a glossary and the owner objected that the document had been trimmed further.",
+      "expected_behavior": "Treats the complaint as too little explanation of the work, not too much text: adds a plain summary, what the experiment ran (data, method and settings, what it set out to measure) and the meaning of each result, puts each question next to its answer, and leaves the pre-registration verbatim. Shared terms stay in the glossary and are linked, not copied in. Recorded from a real project where the owner could not follow results given as numbers and acronyms with no account of the run behind them.",
       "assertions": [
         "Adds explanation (a plain summary, what each result means) rather than shortening or cutting content",
-        "Keeps or adds definitions of terms inside the README itself rather than moving them out to the glossary",
+        "Adds, or asks for, what the experiment ran (the data, the method and its settings, what it set out to measure) so the README can be followed without the notebook",
         "Puts each question next to its answer and its meaning",
-        "Leaves the pre-registration unchanged, or states that it must stay verbatim, while restructuring around it"
+        "Leaves the pre-registration unchanged, or states that it must stay verbatim, while restructuring around it",
+        "Treats docs/glossary.md as the home for shared terms, linking to it rather than adding a second definition in the README"
       ]
     }
   ]

package/skills/skill-router/SKILL.md

@@ -50,6 +50,11 @@ config edits, dependency bumps) and anything that matches a specific skill's
 domain (accessibility, API design, security, data modeling, migrations,
 performance…) are exactly what the skills are for. When in doubt, route.
 
+**Naming a new library is a routing point**, even mid-plan or mid-build and even
+when nobody asked about dependencies. Invoke `dependency-management` before the
+library goes into a plan, an ADR, or an install command. Its first question is
+whether you need the library at all.
+
 Skip **only** for genuinely trivial, conversational, or information-lookup
 requests where no workflow adds value, or when the user tells you not to use a
 skill or to "just do X". **The user's explicit instructions always take
@@ -114,7 +119,7 @@ installed skill by name, regardless of role.
 - **compliance-privacy** — GDPR/SOC 2 obligations: data mapping, retention/deletion, DSRs, controls
 - **configuration-strategy** — env config, secrets management, feature-flag hierarchy
 - **dependency-impact-analysis** — blast radius of a change *before* implementing
-- **dependency-management** — evaluate, audit (CVEs), and upgrade libraries
+- **dependency-management** — whether a library is needed at all vs an own module; evaluate, audit (CVEs), and upgrade libraries
 
 ### Build & Test
 - **plan-execution** — execute an APPROVED plan: checkpoints, verification evidence, drift → re-plan