@wbern/claude-instructions 2.8.1 → 2.9.1

package/README.md

@@ -14,7 +14,7 @@
 [![Made with Claude Code](https://img.shields.io/badge/Made%20with-Claude%20Code-blueviolet)](https://claude.ai/code)
 [![Contributors](https://img.shields.io/github/contributors/wbern/claude-instructions)](https://github.com/wbern/claude-instructions/graphs/contributors)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](https://github.com/wbern/claude-instructions/pulls)
-[![Commands](https://img.shields.io/badge/commands-27-blue)](https://github.com/wbern/claude-instructions#available-commands)
+[![Commands](https://img.shields.io/badge/commands-29-blue)](https://github.com/wbern/claude-instructions#available-commands)
 
 ```
        _==/          i     i          \==_
@@ -33,22 +33,26 @@ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 
 **TDD workflow commands for Claude Code CLI.**
 
+> "TDD helps you to pay attention to the right issues at the right time so you can make your designs cleaner, you can refine your designs as you learn." — Kent Beck
+
 Claude Code supports [custom slash commands](https://docs.anthropic.com/en/docs/claude-code/slash-commands)—type `/foo` and Claude receives the contents of `foo.md` as instructions (from `.claude/commands/` in your repo or `~/.claude/commands/` in your home directory). This repo provides ready-made commands for Test-Driven Development workflows.
 
-While custom commands themselves is really just a glorified method of copy-paste, the way they can be used to bring stability to software development is what's worth trying out.
+Custom commands are just a glorified copy-paste mechanism—but that simplicity is what makes them effective for establishing consistent development practices.
 
 Instead of explaining TDD principles each session, type `/red` to write a failing test, `/green` to make it pass, `/refactor` to clean up. The commands guide Claude through each step methodically—you focus on what to build, Claude handles the how.
 
+Want to go faster? Use `/cycle` to let Claude run the entire red-green-refactor sequence before checking in with you. For even more autonomy (your mileage may vary), `/tdd` gives Claude full discretion on when to advance between phases.
+
 Also included are commands for commits, PRs, code reviews, and other tasks that come up during day-to-day development.
 
 ## Installation
 
 ```bash
-npx @wbern/claude-instructions
-
-// or
+npx @wbern/claude-instructions    # npm
+```
 
-pnpm dlx @wbern/claude-instructions
+```bash
+pnpm dlx @wbern/claude-instructions   # pnpm
 ```
 
 The interactive installer lets you choose:
@@ -71,10 +75,10 @@ Then add a postinstall script to your `package.json`:
 ```json
 {
   "scripts": {
-    "postinstall": "npx @wbern/claude-instructions --scope=project --overwrite"
+    "postinstall": "claude-instructions --scope=project --overwrite"
   },
   "devDependencies": {
-    "@wbern/claude-instructions": "^2.8.1"
+    "@wbern/claude-instructions": "^2.9.1"
   }
 }
 ```
@@ -118,7 +122,7 @@ Other instructions here...
 </claude-commands-template>
 ```
 
-When you run `npx @wbern/claude-instructions`, the template content is appended to all generated commands.
+When you run `claude-instructions`, the template content is appended to all generated commands.
 
 ### Targeting Specific Commands
 
@@ -214,6 +218,7 @@ flowchart TB
 - `/gap` - Analyze conversation context for unaddressed items and gaps
 - `/forever` - Run autonomously until stopped or stuck
 - `/code-review` - Code review using dynamic category detection and domain-specific analysis
+- `/polish` - Review and address issues in existing code - fix problems or justify skipping
 
 ### Ship / Show / Ask
 
@@ -233,6 +238,7 @@ flowchart TB
 - `/kata` - Generate a TDD practice challenge with boilerplate test setup
 - `/research` - Research a problem in parallel via web docs, web search, codebase exploration, and deep ultrathink
 - `/commitlint-checklist-nodejs` - Audit commit hook automation for Node.js projects
+- `/upgrade-deps` - Check for dependency upgrades and assess safety before updating
 
 ## Getting Started
 

package/bin/cli.js

@@ -130,10 +130,10 @@ import {
   text
 } from "@clack/prompts";
 
-// node_modules/.pnpm/diff@8.0.2/node_modules/diff/libesm/index.js
+// node_modules/.pnpm/diff@8.0.3/node_modules/diff/libesm/index.js
 init_esm_shims();
 
-// node_modules/.pnpm/diff@8.0.2/node_modules/diff/libesm/diff/base.js
+// node_modules/.pnpm/diff@8.0.3/node_modules/diff/libesm/diff/base.js
 init_esm_shims();
 var Diff = class {
   diff(oldStr, newStr, options = {}) {
@@ -336,7 +336,7 @@ var Diff = class {
   }
 };
 
-// node_modules/.pnpm/diff@8.0.2/node_modules/diff/libesm/diff/line.js
+// node_modules/.pnpm/diff@8.0.3/node_modules/diff/libesm/diff/line.js
 init_esm_shims();
 var LineDiff = class extends Diff {
   constructor() {
@@ -541,11 +541,7 @@ var CLI_OPTIONS = [
   }
 ];
 function generateHelpText() {
-  const lines = [
-    "Usage: npx @wbern/claude-instructions [options]",
-    "",
-    "Options:"
-  ];
+  const lines = ["Usage: claude-instructions [options]", "", "Options:"];
   for (const opt of CLI_OPTIONS) {
     const suffix = opt.type === "string" ? "=<value>" : opt.type === "array" ? "=<list>" : "";
     const padding = 28 - (opt.flag.length + suffix.length);
@@ -1344,9 +1340,7 @@ async function main(args) {
   const isInteractiveMode = !args?.scope;
   let automationNote = "";
   if (isInteractiveMode) {
-    const userAgent = process.env.npm_config_user_agent || "";
-    const runCommand = userAgent.startsWith("pnpm/") ? "pnpm dlx @wbern/claude-instructions" : "npx @wbern/claude-instructions";
-    const parts = [runCommand];
+    const parts = ["claude-instructions"];
     parts.push(`--scope=${scope}`);
     if (commandPrefix) {
       parts.push(`--prefix=${commandPrefix}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wbern/claude-instructions",
-  "version": "2.8.1",
+  "version": "2.9.1",
   "description": "TDD workflow commands for Claude Code CLI",
   "type": "module",
   "bin": "./bin/cli.js",

package/src/README.md

@@ -29,22 +29,26 @@ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 
 **TDD workflow commands for Claude Code CLI.**
 
+> "TDD helps you to pay attention to the right issues at the right time so you can make your designs cleaner, you can refine your designs as you learn." — Kent Beck
+
 Claude Code supports [custom slash commands](https://docs.anthropic.com/en/docs/claude-code/slash-commands)—type `/foo` and Claude receives the contents of `foo.md` as instructions (from `.claude/commands/` in your repo or `~/.claude/commands/` in your home directory). This repo provides ready-made commands for Test-Driven Development workflows.
 
-While custom commands themselves is really just a glorified method of copy-paste, the way they can be used to bring stability to software development is what's worth trying out.
+Custom commands are just a glorified copy-paste mechanism—but that simplicity is what makes them effective for establishing consistent development practices.
 
 Instead of explaining TDD principles each session, type `/red` to write a failing test, `/green` to make it pass, `/refactor` to clean up. The commands guide Claude through each step methodically—you focus on what to build, Claude handles the how.
 
+Want to go faster? Use `/cycle` to let Claude run the entire red-green-refactor sequence before checking in with you. For even more autonomy (your mileage may vary), `/tdd` gives Claude full discretion on when to advance between phases.
+
 Also included are commands for commits, PRs, code reviews, and other tasks that come up during day-to-day development.
 
 ## Installation
 
 ```bash
-npx @wbern/claude-instructions
-
-// or
+npx @wbern/claude-instructions    # npm
+```
 
-pnpm dlx @wbern/claude-instructions
+```bash
+pnpm dlx @wbern/claude-instructions   # pnpm
 ```
 
 The interactive installer lets you choose:
@@ -67,7 +71,7 @@ Then add a postinstall script to your `package.json`:
 ```json
 {
   "scripts": {
-    "postinstall": "npx @wbern/claude-instructions --scope=project --overwrite"
+    "postinstall": "claude-instructions --scope=project --overwrite"
   },
   "devDependencies": {
     "@wbern/claude-instructions": "^<!-- docs VERSION --><!-- /docs -->"
@@ -103,7 +107,7 @@ Other instructions here...
 </claude-commands-template>
 ```
 
-When you run `npx @wbern/claude-instructions`, the template content is appended to all generated commands.
+When you run `claude-instructions`, the template content is appended to all generated commands.
 
 ### Targeting Specific Commands
 

package/src/fragments/file-categories.md

@@ -0,0 +1,10 @@
+| Category | File Patterns |
+|----------|---------------|
+| Frontend/UI | `*.tsx`, `*.jsx`, `components/`, `pages/`, `views/`, `*.vue` |
+| Frontend/Styling | `*.css`, `*.scss`, `*.less`, `styles/`, `*.tailwind*`, `*.styled.*` |
+| Backend/API | `routes/`, `api/`, `controllers/`, `services/`, `*.controller.*`, `*.service.*`, `*.resolver.*` |
+| Backend/Data | `migrations/`, `models/`, `prisma/`, `schema.*`, `*.model.*`, `*.entity.*` |
+| Tooling/Config | `scripts/`, `*.config.*`, `package.json`, `tsconfig.*`, `vite.*`, `webpack.*`, `eslint.*` |
+| CI/CD | `.github/`, `.gitlab-ci.*`, `Dockerfile`, `docker-compose.*`, `*.yml` in CI paths |
+| Tests | `*.test.*`, `*.spec.*`, `__tests__/`, `__mocks__/`, `*.stories.*` |
+| Docs | `*.md`, `docs/`, `README*`, `CHANGELOG*` |

package/src/sources/_contribute-a-command.md

@@ -17,7 +17,11 @@ _order: 99
 
 Create a new custom command in `src/sources/` following the patterns below. Assess the structure carefully using the below info but also researching the repo.
 
-Command to create: $ARGUMENTS
+**User arguments:**
+
+Contribute-a-command: $ARGUMENTS
+
+**End of user arguments**
 
 ## File Structure
 
@@ -49,9 +53,13 @@ Optional: `_requested-tools` (array), `_selectedByDefault: false`
 ### Test-Driven Development (spike, red, green, refactor, cycle)
 
 ```markdown
-[PHASE] PHASE! Apply the below to the info given by user input here:
+**User arguments:**
+
+[CommandName]: [DOLLAR]ARGUMENTS
 
-[DOLLAR]ARGUMENTS
+**End of user arguments**
+
+[PHASE] PHASE! Apply the below to the user input above.
 
 < !-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
 < !-- /docs -->
@@ -80,7 +88,13 @@ Add for red: `aaa-pattern.md`
 < !-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
 < !-- /docs -->
 
-[Description and [DOLLAR] embedded in flow]
+[Description]
+
+**User arguments:**
+
+[CommandName]: [DOLLAR]ARGUMENTS
+
+**End of user arguments**
 
 < !-- docs INCLUDE path='src/fragments/discovery-phase.md' -->
 < !-- /docs -->
@@ -100,7 +114,11 @@ Add for red: `aaa-pattern.md`
 
 [Workflow description]
 
-[DOLLAR]
+**User arguments:**
+
+[CommandName]: [DOLLAR]ARGUMENTS
+
+**End of user arguments**
 
 [Process steps]
 ```

package/src/sources/add-command.md

@@ -43,7 +43,11 @@ argument-hint: [required-arg] [optional-arg]
 
 Your command instructions here.
 
-Arguments: $ARGUMENTS
+**User arguments:**
+
+Add-command: $ARGUMENTS
+
+**End of user arguments**
 
 File reference: @path/to/file.js
 

package/src/sources/ask.md

@@ -47,7 +47,11 @@ Current branch status:
 Recent commits:
 !`git log --oneline -5`
 
-Arguments: $ARGUMENTS
+**User arguments:**
+
+Ask: $ARGUMENTS
+
+**End of user arguments**
 
 **This is the traditional Pull Request workflow**, but with explicit intent that review and approval are required.
 

package/src/sources/beepboop.md

@@ -21,7 +21,11 @@ Execute the user's requested task (e.g., posting PR comments, GitHub issue comme
 
 ## Instructions
 
-Arguments: $ARGUMENTS
+**User arguments:**
+
+Beepboop: $ARGUMENTS
+
+**End of user arguments**
 
 **IMPORTANT Communication Format:**
 

package/src/sources/busycommit.md

@@ -17,7 +17,11 @@ _order: 2
 
 Create multiple atomic git commits, committing the smallest possible logical unit at a time
 
-Include any of the following info if specified: $ARGUMENTS
+**User arguments:**
+
+Busycommit: $ARGUMENTS
+
+**End of user arguments**
 
 <!-- docs INCLUDE path='src/fragments/commit-process.md' -->
 <!-- /docs -->

package/src/sources/code-review.md

@@ -84,16 +84,8 @@ Check for CLAUDE.md - if it exists, note any project-specific review patterns.
 
 Categorize each changed file into ONE primary category based on these patterns:
 
-| Category | File Patterns |
-|----------|---------------|
-| Frontend/UI | `*.tsx`, `*.jsx`, `components/`, `pages/`, `views/`, `*.vue` |
-| Frontend/Styling | `*.css`, `*.scss`, `*.less`, `styles/`, `*.tailwind*`, `*.styled.*` |
-| Backend/API | `routes/`, `api/`, `controllers/`, `services/`, `*.controller.*`, `*.service.*`, `*.resolver.*` |
-| Backend/Data | `migrations/`, `models/`, `prisma/`, `schema.*`, `*.model.*`, `*.entity.*` |
-| Tooling/Config | `scripts/`, `*.config.*`, `package.json`, `tsconfig.*`, `vite.*`, `webpack.*`, `eslint.*` |
-| CI/CD | `.github/`, `.gitlab-ci.*`, `Dockerfile`, `docker-compose.*`, `*.yml` in CI paths |
-| Tests | `*.test.*`, `*.spec.*`, `__tests__/`, `__mocks__/`, `*.stories.*` |
-| Docs | `*.md`, `docs/`, `README*`, `CHANGELOG*` |
+<!-- docs INCLUDE path='src/fragments/file-categories.md' -->
+<!-- /docs -->
 
 Output the categorization:
 
@@ -247,4 +239,8 @@ Provide a ready-to-paste PR description:
 
 ---
 
-Review target (branch name, PR number, or PR URL - leave empty for current branch): $ARGUMENTS
+**User arguments:**
+
+Code-review: $ARGUMENTS
+
+**End of user arguments**

package/src/sources/commit.md

@@ -17,7 +17,11 @@ _order: 1
 
 Create a git commit following project standards
 
-Include any of the following info if specified: $ARGUMENTS
+**User arguments:**
+
+Commit: $ARGUMENTS
+
+**End of user arguments**
 
 <!-- docs INCLUDE path='src/fragments/commit-process.md' -->
 <!-- /docs -->

package/src/sources/commitlint-checklist-nodejs.md

@@ -16,7 +16,11 @@ _order: 25
 
 Scan the Node.js repository and report what commit automation is in place.
 
-$ARGUMENTS
+**User arguments:**
+
+Commitlint-checklist: $ARGUMENTS
+
+**End of user arguments**
 
 ## Checks to Scan
 

package/src/sources/create-issues.md

@@ -19,9 +19,11 @@ Create structured implementation plan that bridges product thinking (PRD) with t
 <!-- docs INCLUDE path='src/fragments/no-plan-files.md' featureFlag='no-plan-files' -->
 <!-- /docs -->
 
-## Input
+**User arguments:**
 
-$ARGUMENTS
+Create-issues: $ARGUMENTS
+
+**End of user arguments**
 
 (If no input provided, check conversation context<!-- docs INCLUDE path='src/fragments/create-issues-beads-context-hint.md' featureFlag='beads' -->
 <!-- /docs -->)

package/src/sources/cycle.md

@@ -6,9 +6,13 @@ _category: Test-Driven Development
 _order: 5
 ---
 
-RED+GREEN+REFACTOR (one cycle) PHASE! Apply the below to the info given by user input here:
+**User arguments:**
 
-$ARGUMENTS
+Cycle: $ARGUMENTS
+
+**End of user arguments**
+
+RED+GREEN+REFACTOR (one cycle) PHASE! Apply the below to the user input above.
 
 <!-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
 <!-- /docs -->

package/src/sources/forever.md

@@ -12,7 +12,11 @@ _order: 20
 <!-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
 <!-- /docs -->
 
-# Forever Mode: $ARGUMENTS
+**User arguments:**
+
+Forever: $ARGUMENTS
+
+**End of user arguments**
 
 Run autonomously, finding and completing work until interrupted or truly stuck.
 

package/src/sources/gap.md

@@ -37,5 +37,8 @@ Present findings as a prioritized list with:
 
 If there are no gaps, confirm that everything discussed has been addressed.
 
-Additional info:
-$ARGUMENTS
+**User arguments:**
+
+Gap: $ARGUMENTS
+
+**End of user arguments**

package/src/sources/green.md

@@ -6,9 +6,13 @@ _category: Test-Driven Development
 _order: 3
 ---
 
-GREEN PHASE! Apply the below to the info given by user input here:
+**User arguments:**
 
-$ARGUMENTS
+Green: $ARGUMENTS
+
+**End of user arguments**
+
+GREEN PHASE! Apply the below to the user input above.
 
 <!-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
 <!-- /docs -->

package/src/sources/issue.md

@@ -21,9 +21,14 @@ Process:
 
 1. Get Issue Number
 
-- Either from branch name use that issue number
-  - Patterns: issue-123, 123-feature, feature/123, fix/123
-- Or from this bullet point with custom info: $ARGUMENTS
+**User arguments:**
+
+Issue: $ARGUMENTS
+
+**End of user arguments**
+
+- Check if argument is an issue number
+- Otherwise try branch name patterns: issue-123, 123-feature, feature/123, fix/123
 - If not found: ask user
 
 2. Fetch Issue

package/src/sources/kata.md

@@ -25,9 +25,11 @@ Generate a complete TDD practice setup:
 <!-- docs INCLUDE path='src/fragments/no-plan-files.md' featureFlag='no-plan-files' -->
 <!-- /docs -->
 
-## Input
+**User arguments:**
 
-$ARGUMENTS
+Kata: $ARGUMENTS
+
+**End of user arguments**
 
 (This command is interactive - arguments are ignored)
 

package/src/sources/polish.md

@@ -0,0 +1,168 @@
+---
+description: Review and address issues in existing code - fix problems or justify skipping
+argument-hint: [branch, PR#, file, or area to polish]
+_hint: Fix or skip issues
+_category: Workflow
+_order: 36
+_requested-tools:
+  - Bash(git diff:*)
+  - Bash(git status:*)
+  - Bash(git log:*)
+  - Bash(git rev-parse:*)
+  - Bash(git merge-base:*)
+  - Bash(git branch:*)
+---
+
+<!-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/no-plan-files.md' featureFlag='no-plan-files' -->
+<!-- /docs -->
+
+# Polish
+
+Take another pass at existing work to address issues. Unlike `/code-review` which only identifies problems, `/polish` resolves each finding by either:
+
+1. **Fixing** - Implement the improvement
+2. **Skipping with justification** - Document why the issue can be deferred or ignored
+
+## Phase 0: Determine Scope
+
+Parse the argument to determine what to polish:
+
+| Input | Action |
+|-------|--------|
+| No argument | Detect divergence point, review uncommitted + committed changes |
+| Branch name | Changes from that branch to HEAD |
+| PR number (e.g., `123`) | Fetch PR diff from GitHub |
+| PR URL (e.g., `github.com/.../pull/123`) | Extract PR number and fetch diff |
+| File/path | Focus on specific file(s) |
+
+**For GitHub PRs:**
+
+1. Try GitHub MCP first: `mcp__github__pull_request_read` with `method: "get_diff"`
+2. Fall back to `gh` CLI: `gh pr diff <number>`
+3. If neither works, report error and stop
+
+**For local branches:**
+
+1. Get current branch: `git rev-parse --abbrev-ref HEAD`
+2. Detect divergence point (same logic as `/code-review`)
+3. Collect changed files from diff and uncommitted changes
+
+## Phase 1: Identify Issues
+
+Categorize files based on these patterns:
+
+<!-- docs INCLUDE path='src/fragments/file-categories.md' -->
+<!-- /docs -->
+
+For each category, identify issues at these severity levels:
+
+- **blocker** - Must fix before merge
+- **risky** - Should fix or have strong justification
+- **nit** - Nice to have, easily skippable
+
+## Phase 2: Address Each Issue
+
+For each identified issue, present it and then take action:
+
+### Format
+
+```
+### [file:line] [severity] Title
+
+**Issue:** Description of the problem
+
+**Action taken:**
+- [ ] Fixed: [what was done]
+- [ ] Skipped: [justification]
+```
+
+### Decision Guidelines
+
+**Fix when:**
+
+- Security vulnerability
+- Correctness bug
+- Missing error handling that could crash
+- Breaking API changes without migration
+- Tests that don't actually test anything
+
+**Skip with justification when:**
+
+- Stylistic preference with no functional impact
+- Optimization for unlikely hot paths
+- Refactoring that would expand scope significantly
+- Issue exists in code outside the change scope
+- Technical debt documented for future sprint
+
+### Fixing Issues
+
+When fixing:
+
+1. Make the minimal change to address the issue
+2. Ensure tests still pass (run them if needed)
+3. Don't expand scope beyond the identified issue
+
+<!-- docs INCLUDE path='src/fragments/peeping-tom-warning.md' -->
+<!-- /docs -->
+
+### Skipping Issues
+
+Valid skip justifications:
+
+- "Out of scope - exists in unchanged code"
+- "Performance optimization unnecessary - called N times per request"
+- "Tracked for future work - see issue #X"
+- "Intentional design decision - [reason]"
+- "Would require significant refactoring - defer to dedicated PR"
+
+Invalid skip justifications:
+
+- "Too hard to fix"
+- "It works fine"
+- "No time"
+
+## Phase 3: Cross-Cutting Check
+
+After addressing individual issues:
+
+<!-- docs INCLUDE path='src/fragments/consistency-check.md' -->
+<!-- /docs -->
+
+Additional cross-cutting checks:
+
+- Did fixes introduce new inconsistencies?
+- Are skip justifications consistent with each other?
+- Any patterns in what was skipped that suggest a bigger issue?
+
+## Phase 4: Summary
+
+```
+## Polish Summary
+
+### Fixed
+- [list of fixes applied]
+
+### Skipped (with justification)
+- [issue]: [justification]
+
+### Tests
+- [ ] All tests passing
+- [ ] No new warnings introduced
+
+### Remaining Work
+- [any follow-up items identified]
+```
+
+---
+
+**User arguments:**
+
+Polish: $ARGUMENTS
+
+**End of user arguments**

package/src/sources/pr.md

@@ -27,7 +27,11 @@ Current branch status:
 Recent commits:
 !`git log --oneline -5`
 
-Arguments: $ARGUMENTS
+**User arguments:**
+
+PR: $ARGUMENTS
+
+**End of user arguments**
 
 **Process:**
 

package/src/sources/red.md

@@ -6,9 +6,13 @@ _category: Test-Driven Development
 _order: 2
 ---
 
-RED PHASE! Apply the below to the info given by user input here:
+**User arguments:**
 
-$ARGUMENTS
+Red: $ARGUMENTS
+
+**End of user arguments**
+
+RED PHASE! Apply the below to the user input above.
 
 <!-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
 <!-- /docs -->

package/src/sources/refactor.md

@@ -6,7 +6,13 @@ _category: Test-Driven Development
 _order: 4
 ---
 
-Apply this document (specifically the Refactor phase), to the info given by user input here: $ARGUMENTS
+**User arguments:**
+
+Refactor: $ARGUMENTS
+
+**End of user arguments**
+
+Apply this document (specifically the Refactor phase) to the user input above.
 
 <!-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
 <!-- /docs -->

package/src/sources/research.md

@@ -12,7 +12,11 @@ _order: 20
 <!-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
 <!-- /docs -->
 
-# Research: $ARGUMENTS
+**User arguments:**
+
+Research: $ARGUMENTS
+
+**End of user arguments**
 
 Research the following problem or question thoroughly, like a senior developer would.
 

package/src/sources/ship.md

@@ -45,7 +45,11 @@ Current branch status:
 Recent commits:
 !`git log --oneline -5`
 
-Arguments: $ARGUMENTS
+**User arguments:**
+
+Ship: $ARGUMENTS
+
+**End of user arguments**
 
 **Process:**
 

package/src/sources/show.md

@@ -44,7 +44,11 @@ Current branch status:
 Recent commits:
 !`git log --oneline -5`
 
-Arguments: $ARGUMENTS
+**User arguments:**
+
+Show: $ARGUMENTS
+
+**End of user arguments**
 
 **Process:**
 

package/src/sources/simplify.md

@@ -12,7 +12,11 @@ _order: 16
 <!-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
 <!-- /docs -->
 
-# Simplify: $ARGUMENTS
+**User arguments:**
+
+Simplify: $ARGUMENTS
+
+**End of user arguments**
 
 <!-- docs INCLUDE path='src/fragments/fallback-arguments.md' -->
 <!-- /docs -->

package/src/sources/spike.md

@@ -6,9 +6,13 @@ _category: Test-Driven Development
 _order: 1
 ---
 
-SPIKE PHASE! Apply the below to the info given by user input here:
+**User arguments:**
 
-$ARGUMENTS
+Spike: $ARGUMENTS
+
+**End of user arguments**
+
+SPIKE PHASE! Apply the below to the user input above.
 
 <!-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
 <!-- /docs -->

package/src/sources/summarize.md

@@ -17,7 +17,11 @@ _order: 10
 
 Create a concise summary of the current conversation suitable for transferring context to a new conversation.
 
-Additional info: $ARGUMENTS
+**User arguments:**
+
+Summarize: $ARGUMENTS
+
+**End of user arguments**
 
 <!-- docs INCLUDE path='src/fragments/summarize-structure.md' -->
 <!-- /docs -->

package/src/sources/tdd-review.md

@@ -77,4 +77,8 @@ Output a structured report:
 
 ---
 
-Test path (leave empty for all tests): $ARGUMENTS
+**User arguments:**
+
+TDD-review: $ARGUMENTS
+
+**End of user arguments**

package/src/sources/tdd.md

@@ -22,6 +22,10 @@ _order: 1
 
 ## Continue Conversation
 
-User response to the last message: $ARGUMENTS
+**User arguments:**
 
-Please continue with TDD approach based on the above response.
+TDD: $ARGUMENTS
+
+**End of user arguments**
+
+Please continue with the user input above, applying TDD approach.

package/src/sources/upgrade-deps.md

@@ -0,0 +1,186 @@
+---
+description: Check for dependency upgrades and assess safety before updating
+argument-hint: (no arguments - interactive)
+_hint: Upgrade packages
+_category: Utilities
+_order: 50
+---
+
+<!-- docs INCLUDE path='src/fragments/universal-guidelines.md' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/beads-awareness.md' featureFlag='beads' -->
+<!-- /docs -->
+
+<!-- docs INCLUDE path='src/fragments/no-plan-files.md' featureFlag='no-plan-files' -->
+<!-- /docs -->
+
+# Upgrade Dependencies
+
+Analyze available dependency upgrades, assess codebase safety signals, and guide the user through upgrade decisions.
+
+## Phase 1: Detect Environment
+
+Scan for package manager and project setup:
+
+| Check | How |
+|-------|-----|
+| Package manager | Look for `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`, `bun.lockb` |
+| Lockfile present | Exists and tracked in git |
+| Test script | `package.json` has `test` script |
+| Test files | `*.test.*`, `*.spec.*`, `__tests__/` exist |
+| CI config | `.github/workflows/`, `.gitlab-ci.yml`, etc. |
+| Type checking | `tsconfig.json` or `jsconfig.json` present |
+
+Output:
+
+```
+## Environment
+
+Package manager: pnpm
+Lockfile: ✓ pnpm-lock.yaml (tracked)
+Test script: ✓ "vitest run"
+Test files: ✓ 16 test files found
+CI config: ✓ .github/workflows/release.yml
+Types: ✓ tsconfig.json
+```
+
+## Phase 2: List Available Upgrades
+
+Run the appropriate outdated command:
+
+| Manager | Command |
+|---------|---------|
+| pnpm | `pnpm outdated --format json` |
+| npm | `npm outdated --json` |
+| yarn | `yarn outdated --json` |
+| bun | `bun outdated` |
+
+Group results by semver level:
+
+```
+## Available Upgrades
+
+### Patch (low risk)
+| Package | Current | Latest | Age |
+|---------|---------|--------|-----|
+| lodash | 4.17.20 | 4.17.21 | 6 months |
+
+### Minor (medium risk)
+| Package | Current | Latest | Age |
+|---------|---------|--------|-----|
+| vitest | 1.5.0 | 1.6.0 | 3 weeks |
+
+### Major (review changelog)
+| Package | Current | Latest | Age |
+|---------|---------|--------|-----|
+| typescript | 4.9.5 | 5.4.2 | 8 months |
+```
+
+Note: "Age" is time since the latest version was published. Packages < 14 days old may pose supply chain risk.
+
+## Phase 3: Safety Assessment
+
+Present observable signals (not guarantees):
+
+```
+## Safety Signals
+
+✓ Test files present (16 files)
+✓ Test script configured
+✓ CI pipeline exists
+✓ Lockfile tracked in git
+✓ TypeScript for type safety
+⚠ No pre-commit hooks detected
+✗ Coverage threshold not configured
+
+──────────────────────────────────────────────────
+⚠ DISCLAIMER: This is a surface-level check based
+on file presence, not actual test quality or
+coverage. You know your codebase best.
+──────────────────────────────────────────────────
+```
+
+## Phase 4: Ask User
+
+Use `AskUserQuestion` to determine next steps:
+
+**Question: "How would you like to proceed?"** (header: "Upgrade")
+
+Options:
+1. **Patches only** - "Upgrade patch versions (X.Y.Z → X.Y.Z+1), lowest risk"
+2. **Patches + minors** - "Include minor versions (X.Y → X.Y+1), some API additions"
+3. **Interactive selection** - "Choose specific packages to upgrade"
+4. **Doctor mode** - "Test each upgrade individually, keep only working ones (slower but safest)"
+5. **Just show outdated** - "Don't upgrade, just list what's available"
+
+## Phase 5: Execute Upgrade
+
+Based on user selection:
+
+### Patches Only
+```bash
+# pnpm
+pnpm update --no-save  # updates lockfile only for patches within range
+
+# or with ncu
+npx npm-check-updates --target patch -u && pnpm install
+```
+
+### Patches + Minors
+```bash
+npx npm-check-updates --target minor -u && pnpm install
+```
+
+### Interactive Selection
+```bash
+npx npm-check-updates -i
+```
+
+### Doctor Mode
+```bash
+npx npm-check-updates --doctor -u
+```
+
+This will:
+1. Verify tests pass before starting
+2. Try upgrading all dependencies
+3. If tests fail, test each dependency individually
+4. Keep only upgrades that pass tests
+
+### After Any Upgrade
+
+1. Run tests: `pnpm test`
+2. Run type check if available: `pnpm typecheck`
+3. Run build if available: `pnpm build`
+4. Report results to user
+
+## Phase 6: Summary
+
+```
+## Upgrade Summary
+
+### Upgraded
+- lodash: 4.17.20 → 4.17.21 (patch)
+- vitest: 1.5.0 → 1.6.0 (minor)
+
+### Skipped
+- typescript: 4.9.5 → 5.4.2 (major - user opted out)
+
+### Verification
+- [x] Tests passing
+- [x] Types checking
+- [x] Build successful
+
+### Next Steps
+- Review changelog for skipped major upgrades
+- Consider running full test suite in CI before merging
+```
+
+---
+
+**User arguments:**
+
+Upgrade: $ARGUMENTS
+
+**End of user arguments**

package/src/sources/worktree-add.md

@@ -17,7 +17,11 @@ _order: 1
 <!-- docs INCLUDE path='src/fragments/no-plan-files.md' featureFlag='no-plan-files' -->
 <!-- /docs -->
 
-Create a new git worktree for branch: $ARGUMENTS
+**User arguments:**
+
+Worktree-add: $ARGUMENTS
+
+**End of user arguments**
 
 <current_state>
 Current branch: `git branch --show-current`

package/src/sources/worktree-cleanup.md

@@ -19,7 +19,11 @@ _order: 2
 
 Clean up merged worktrees by finding the oldest merged branch, consolidating settings, and removing stale worktrees.
 
-Additional info: $ARGUMENTS
+**User arguments:**
+
+Worktree-cleanup: $ARGUMENTS
+
+**End of user arguments**
 
 <current_state>
 Current branch: `git branch --show-current`