swe-workflow-skills 0.11.4 → 0.11.6

package/VERSION

@@ -1 +1 @@
-0.11.4
+0.11.6

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.4",
+  "version": "0.11.6",
   "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-impact-analysis/SKILL.md

@@ -116,6 +116,8 @@ For each breaking change, define the coordination plan:
 - What is the migration deadline?
 - Is there a deprecation period?
 
+**Exit condition:** the dependents with their Step 3 classification, and the propagation plan, written in your reply before any design question or code. This is not a gate on delivering: when a design choice is open, give the map under your recommended option and put the question beside it. A choice dialog shows only its own text, so a question asked instead of the map hides it.
+
 ## Principles Applied
 
 - **Functional independence**: Minimize blast radius — prefer additive changes over breaking changes when both achieve the same goal

package/skills/dependency-impact-analysis/evals/evals.json

@@ -4,13 +4,13 @@
     {
       "id": 1,
       "prompt": "I want to rename the 'user_id' field to 'account_id' in our REST API response for GET /api/users. We have a mobile app, a web app, and two internal microservices that call this endpoint. What's the impact?",
-      "expected_output": "Dependency impact analysis identifying all four consumers, classifying the rename as breaking for all of them, recommending a versioning strategy, and producing a migration plan with coordination steps",
+      "expected_output": "Dependency impact analysis identifying all four consumers, classifying the rename as breaking for all of them, recommending a transition that keeps user_id working for old mobile app versions (expand-contract dual fields or a versioned endpoint), and producing a migration plan with coordination steps",
       "assertions": [
         "Identifies all four consumers (mobile app, web app, two microservices) as affected",
         "Classifies this as a breaking change for all consumers (field rename, not additive)",
         "Flags mobile app as highest risk (users may not update; old app versions still call the API)",
-        "Recommends API versioning (v1 keeps user_id, v2 uses account_id) for the mobile app case",
-        "Produces a migration sequence: add v2, migrate internal consumers, migrate web, sunset v1 after mobile migration window",
+        "Recommends a transition that keeps user_id working for old mobile app versions while account_id is introduced: both fields in the response (expand-contract) or a versioned endpoint (v1 keeps user_id, v2 uses account_id)",
+        "Produces a migration sequence: introduce account_id alongside user_id (or a v2), migrate the internal consumers and the web app, and remove user_id (or sunset v1) only after the mobile migration window",
         "Does not suggest a simultaneous big-bang rename as the only option"
       ]
     },
@@ -23,7 +23,7 @@
         "Notes that existing code ignores the new column and remains safe",
         "Flags that code selecting whole rows — ORM models, serializers — will start returning the new column",
         "Does not require complex coordination or versioning",
-        "Gives a clear 'safe to proceed' verdict with any minor caveats"
+        "Leads with a verdict, either safe to deploy or safe once named checks pass (such as positional SELECT * mapping or DTOs that reject unknown fields), rather than declining to answer without more information"
       ]
     },
     {

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,32 @@ 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, written in your reply, in the same response. Steps 2–4 apply only to rows marked Adopt.
+
+- **The table goes in the message, not in a question.** A choice dialog shows only its own text, so a question whose option labels carry the comparison hides the table. Write the table and your recommendation first; the question that follows only names the options.
+- **A registry page fills no row.** The package existing, its licence and its last release are Steps 2–3. A verdict reached from them has skipped this step.
+- **Size the own module with the hard part in it.** If our version would have to rebuild what makes the library worth having (its typing, its protocol or OAuth flow, its parser), count that part, or the own module looks smaller than it is.
 
 ### Step 2: Verify the Package Exists (anti-slopsquatting)
 
@@ -60,7 +79,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 +87,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 +119,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 +138,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 +160,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,53 @@
         "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"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "We're adding a small MCP server in Python 3.12 in front of our existing REST API, so Claude's scheduled tasks can call five tools over Streamable HTTP. People sign in with Google Workspace accounts limited to our domain, and Claude's connectors need OAuth with refresh tokens so unattended runs keep working. I'm leaning towards FastMCP; the other option is the official `mcp` SDK plus our own OAuth authorization server. FastMCP is on PyPI, Apache-2.0, and had a release last week, so it's probably fine. Check it before we add it.",
+      "pressure": [
+        "authority"
+      ],
+      "expected_behavior": "Runs Step 1 rather than stopping at the facts the user offered: compares FastMCP with the official SDK plus an own OAuth server on what each covers, what FastMCP pulls in, and how big and how risky the own side is. The own side is mostly an OAuth authorization server delegating to Google, which is security-critical. The comparison and the recommendation are written out in the reply, not compressed into a one-line verdict or a bare question.",
+      "assertions": [
+        "Compares FastMCP with the official `mcp` SDK plus an own OAuth server on what each covers here (the MCP transport, the OAuth flow delegating to Google, refresh tokens, token storage), rather than concluding from the PyPI listing, licence and release date",
+        "Gives a rough size for the own-module side and says its bulk is the OAuth authorization server, which is security-critical code",
+        "Says what FastMCP pulls in (transitive packages, install size or maintainer groups), or says it must be checked",
+        "Writes the comparison out in the reply with a recommendation, its primary reason and the risks accepted, rather than a one-line verdict or only a question"
+      ]
+    }
   ]
 }

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, including a library an RFC, ADR or issue already names, 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, and neither has one that schedules the check as a later task.
+
 ### 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/skill-router/SKILL.md

@@ -50,6 +50,14 @@ 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. A library an RFC, ADR, issue or earlier plan
+already names is a candidate, not a decision. Writing "run
+`dependency-management`" as a later step of the plan doesn't count: the plan
+names the library only after the check has run.
+
 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 +122,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