worclaude 2.8.0 → 2.9.0

package/templates/agents/optional/data/data-pipeline-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: data-pipeline-reviewer
-description: "Reviews data pipeline correctness"
+description: Reviews data pipeline correctness
 model: sonnet
 isolation: none
 disallowedTools:
@@ -9,6 +9,12 @@ disallowedTools:
   - NotebookEdit
   - Agent
 maxTurns: 30
+category: data
+triggerType: manual
+whenToUse: New data pipeline created. ETL logic changed. Data transformation modified. Schema compatibility concerns.
+whatItDoes: Reviews data flows, validates transformations, checks for data loss, validates schema compatibility.
+expectBack: Pipeline review with data integrity concerns.
+situationLabel: Created or changed a data pipeline
 ---
 
 You are a data engineering specialist who reviews data pipeline code

package/templates/agents/optional/data/ml-experiment-tracker.md

@@ -1,6 +1,6 @@
 ---
 name: ml-experiment-tracker
-description: "Reviews ML experiment reproducibility"
+description: Reviews ML experiment reproducibility
 model: sonnet
 isolation: none
 disallowedTools:
@@ -9,6 +9,12 @@ disallowedTools:
   - NotebookEdit
   - Agent
 maxTurns: 30
+category: data
+triggerType: manual
+whenToUse: Running ML experiments. Comparing model performance. Hyperparameter tuning. Model selection.
+whatItDoes: Tracks ML experiments, compares metrics across runs, documents hyperparameters and results.
+expectBack: Experiment comparison report with recommendations.
+situationLabel: Running or comparing ML experiments
 ---
 
 You are an ML engineering specialist who reviews experiment code for

package/templates/agents/optional/data/prompt-engineer.md

@@ -1,9 +1,15 @@
 ---
 name: prompt-engineer
-description: "Reviews and improves LLM prompts"
+description: Reviews and improves LLM prompts
 model: opus
 isolation: none
 maxTurns: 30
+category: data
+triggerType: manual
+whenToUse: Writing LLM prompts. Optimizing prompt performance. Building prompt chains. Testing prompt variations.
+whatItDoes: Reviews and optimizes LLM prompts and chains. Tests prompt variations, measures output quality.
+expectBack: Optimized prompts with test results and quality comparison.
+situationLabel: Writing or optimizing LLM prompts
 ---
 
 You are an LLM prompt engineering specialist who reviews and improves

package/templates/agents/optional/devops/ci-fixer.md

@@ -1,9 +1,15 @@
 ---
 name: ci-fixer
-description: "Diagnoses and fixes CI/CD failures"
+description: Diagnoses and fixes CI/CD failures
 model: sonnet
 isolation: worktree
 maxTurns: 40
+category: devops
+triggerType: manual
+whenToUse: CI pipeline fails. Build errors in GitHub Actions/CI. Flaky tests blocking merges.
+whatItDoes: Reads CI logs, identifies root cause, implements fix in worktree isolation.
+expectBack: Fix committed to worktree branch with CI passing.
+situationLabel: CI pipeline is failing
 ---
 
 You are a CI/CD specialist who diagnoses and fixes pipeline failures.

package/templates/agents/optional/devops/dependency-manager.md

@@ -1,6 +1,6 @@
 ---
 name: dependency-manager
-description: "Reviews dependency health and updates"
+description: Reviews dependency health and updates
 model: haiku
 isolation: none
 disallowedTools:
@@ -9,6 +9,12 @@ disallowedTools:
   - NotebookEdit
   - Agent
 maxTurns: 20
+category: devops
+triggerType: manual
+whenToUse: After adding new packages. During regular maintenance. When security advisories are published.
+whatItDoes: Audits, updates, and resolves dependency issues. Checks for security vulnerabilities in packages.
+expectBack: Dependency audit report with update recommendations.
+situationLabel: Added new dependencies or running maintenance
 ---
 
 You are a dependency health analyst. You review the project's

package/templates/agents/optional/devops/deploy-validator.md

@@ -1,6 +1,6 @@
 ---
 name: deploy-validator
-description: "Validates deployment readiness"
+description: Validates deployment readiness
 model: sonnet
 isolation: none
 disallowedTools:
@@ -9,6 +9,12 @@ disallowedTools:
   - NotebookEdit
   - Agent
 maxTurns: 20
+category: devops
+triggerType: manual
+whenToUse: Before deploying to staging or production. After infrastructure changes. New environment setup.
+whatItDoes: Validates deployment readiness — environment configs, secrets management, health checks, rollback strategy.
+expectBack: Deployment readiness checklist with pass/fail.
+situationLabel: Preparing for deployment
 ---
 
 You are a deployment readiness specialist who validates that an

package/templates/agents/optional/devops/docker-helper.md

@@ -1,9 +1,15 @@
 ---
 name: docker-helper
-description: "Reviews Docker configs for best practices"
+description: Reviews Docker configs for best practices
 model: sonnet
 isolation: none
 maxTurns: 30
+category: devops
+triggerType: manual
+whenToUse: Creating or modifying Dockerfiles. Compose file changes. Multi-stage build optimization. Container debugging.
+whatItDoes: Manages containerization, Dockerfile optimization, compose file configuration, multi-stage builds.
+expectBack: Optimized Docker configuration with size/performance improvements.
+situationLabel: Working with Docker or containers
 ---
 
 You are a Docker and containerization specialist who reviews

package/templates/agents/optional/docs/changelog-generator.md

@@ -1,14 +1,22 @@
 ---
 name: changelog-generator
-description: "Generates changelog from commits"
+description: Generates changelog from commits
 model: haiku
 isolation: none
 disallowedTools:
   - Edit
+  - Write
   - NotebookEdit
   - Agent
 maxTurns: 15
 omitClaudeMd: true
+criticalSystemReminder: "CRITICAL: You CANNOT edit files. Generate changelog text and report it back only."
+category: documentation
+triggerType: manual
+whenToUse: Before releasing a new version. After merging a batch of PRs. When preparing release notes.
+whatItDoes: Generates changelogs from git history, PR descriptions, and commit messages. Formats for release notes.
+expectBack: Formatted changelog entry for the release.
+situationLabel: Preparing a release
 ---
 
 You are a changelog generator that creates clear, well-organized

package/templates/agents/optional/docs/doc-writer.md

@@ -1,10 +1,16 @@
 ---
 name: doc-writer
-description: "Writes and updates documentation"
+description: Writes and updates documentation
 model: sonnet
 isolation: worktree
 maxTurns: 40
 memory: project
+category: documentation
+triggerType: manual
+whenToUse: After implementing new features. After API changes. When README is outdated. Before release.
+whatItDoes: Updates documentation, README, API docs from code changes. Keeps docs in sync with implementation.
+expectBack: Updated docs committed to worktree branch.
+situationLabel: Need docs updated after implementation
 ---
 
 You are a technical writer who creates and maintains project

package/templates/agents/optional/frontend/style-enforcer.md

@@ -1,9 +1,15 @@
 ---
 name: style-enforcer
-description: "Ensures design system compliance"
+description: Ensures design system compliance
 model: haiku
 isolation: none
 maxTurns: 30
+category: frontend
+triggerType: manual
+whenToUse: After CSS/styling changes. When new components are added. During theme updates.
+whatItDoes: Ensures design system compliance, catches CSS/styling drift, validates consistent spacing/colors/typography.
+expectBack: List of design system violations with fix suggestions.
+situationLabel: Made styling or CSS changes
 ---
 
 You are a design system compliance checker. Your job is to scan the

package/templates/agents/optional/frontend/ui-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: ui-reviewer
-description: "Reviews UI for consistency and accessibility"
+description: Reviews UI for consistency and accessibility
 model: sonnet
 isolation: none
 disallowedTools:
@@ -9,6 +9,12 @@ disallowedTools:
   - NotebookEdit
   - Agent
 maxTurns: 30
+category: frontend
+triggerType: manual
+whenToUse: After implementing or modifying UI components. When adding new pages or layouts. During design system changes.
+whatItDoes: Reviews UI components for consistency, accessibility, responsiveness. Checks component hierarchy and prop patterns.
+expectBack: UI review report with specific issues and accessibility findings.
+situationLabel: Implemented or changed UI components
 ---
 
 You are a senior UI/UX engineer who reviews frontend components for

package/templates/agents/optional/quality/bug-fixer.md

@@ -1,9 +1,15 @@
 ---
 name: bug-fixer
-description: "Diagnoses and fixes bugs"
+description: Diagnoses and fixes bugs
 model: sonnet
 isolation: worktree
 maxTurns: 50
+category: quality
+triggerType: manual
+whenToUse: Bug reported. Test failing. Error in logs. Something broke but you don't want to derail current work.
+whatItDoes: Investigates the bug in isolation. Reads logs, reproduces, finds root cause, implements fix, writes regression test.
+expectBack: Fix committed to worktree branch with regression test.
+situationLabel: Got a bug report mid-task
 ---
 
 ## Worktree freshness preamble

package/templates/agents/optional/quality/build-fixer.md

@@ -1,9 +1,15 @@
 ---
 name: build-fixer
-description: "Diagnoses and fixes build failures"
+description: Diagnoses and fixes build failures
 model: sonnet
 isolation: worktree
 maxTurns: 40
+category: quality
+triggerType: manual
+whenToUse: Build is broken. Tests failing. Lint errors blocking commit. Type errors after a merge or dependency update.
+whatItDoes: Reads error output, categorizes failures (build/test/lint/type), fixes in priority order, verifies each fix. Works in worktree isolation.
+expectBack: All checks passing, with a summary of what was fixed and why.
+situationLabel: Build or tests are broken
 ---
 
 You are a build error specialist. When the build is broken — tests

package/templates/agents/optional/quality/performance-auditor.md

@@ -1,6 +1,6 @@
 ---
 name: performance-auditor
-description: "Analyzes code for performance issues"
+description: Analyzes code for performance issues
 model: sonnet
 isolation: none
 disallowedTools:
@@ -10,6 +10,13 @@ disallowedTools:
   - Agent
 maxTurns: 30
 omitClaudeMd: true
+criticalSystemReminder: "CRITICAL: You CANNOT edit files. Review and report findings only."
+category: quality
+triggerType: manual
+whenToUse: Performance concern raised. Slow endpoint discovered. Before releasing to production. After major changes.
+whatItDoes: Profiles code, identifies bottlenecks, checks database query efficiency, measures response times, suggests optimizations.
+expectBack: Performance report with benchmarks and recommendations.
+situationLabel: Suspect performance issues
 ---
 
 You are a performance engineer who reviews code for efficiency

package/templates/agents/optional/quality/refactorer.md

@@ -1,9 +1,15 @@
 ---
 name: refactorer
-description: "Refactors code to improve maintainability"
+description: Refactors code to improve maintainability
 model: sonnet
 isolation: worktree
 maxTurns: 50
+category: quality
+triggerType: manual
+whenToUse: Large-scale renames. Architectural pattern changes. Library migrations. Moving code between modules.
+whatItDoes: Handles large-scale refactoring in worktree isolation. Renames, architectural changes, pattern migrations with full test verification.
+expectBack: Refactored code on worktree branch with all tests passing.
+situationLabel: Need large-scale refactoring
 ---
 
 You are a refactoring specialist. You improve code structure and

package/templates/agents/optional/quality/security-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: security-reviewer
-description: "Reviews code for security vulnerabilities"
+description: Reviews code for security vulnerabilities
 model: opus
 isolation: none
 disallowedTools:
@@ -14,6 +14,12 @@ memory: project
 skills:
   - security-checklist
 criticalSystemReminder: "CRITICAL: You CANNOT edit files. Report vulnerabilities with remediation guidance only."
+category: quality
+triggerType: manual
+whenToUse: Auth changes. User input handling. New API endpoints exposed to external users. Dependency updates.
+whatItDoes: Scans for injection vulnerabilities, auth bypasses, data exposure, insecure defaults, dependency vulnerabilities.
+expectBack: Security report with severity ratings.
+situationLabel: Made security-sensitive changes
 ---
 
 You are a senior application security engineer performing a code

package/templates/agents/universal/build-validator.md

@@ -1,10 +1,16 @@
 ---
 name: build-validator
-description: "Validates that the project builds and all tests pass"
+description: Validates that the project builds and all tests pass
 model: haiku
 isolation: none
 background: true
 maxTurns: 20
+category: universal
+triggerType: automatic
+whenToUse: Before every commit. After merging worktree branches.
+whatItDoes: Quick validation — tests pass, build succeeds, lint clean. Fast and cheap (Haiku model).
+expectBack: Pass/fail with specific errors if failed.
+situationLabel: Are about to commit
 ---
 
 You are a build validation specialist. You run all project checks

package/templates/agents/universal/code-simplifier.md

@@ -1,9 +1,16 @@
 ---
 name: code-simplifier
-description: "Reviews changed code and simplifies overly complex implementations"
+description: Reviews changed code and simplifies overly complex implementations
 model: sonnet
 isolation: worktree
 maxTurns: 50
+category: universal
+triggerType: automatic
+triggerCommand: /simplify
+whenToUse: After a feature is implemented and tests pass. Also when you notice growing complexity or duplication.
+whatItDoes: Reviews code for duplication, unnecessary abstraction, missed reuse opportunities. Simplifies without changing behavior.
+expectBack: Cleanup commits on worktree branch. Diff review before merge.
+situationLabel: Notice code getting complex
 ---
 
 You are a code quality specialist. You review recently changed code and

package/templates/agents/universal/plan-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: plan-reviewer
-description: "Reviews implementation plans for specificity, gaps, and executability"
+description: Reviews implementation plans for specificity, gaps, and executability
 model: opus
 isolation: none
 disallowedTools:
@@ -11,6 +11,13 @@ disallowedTools:
 maxTurns: 30
 omitClaudeMd: true
 criticalSystemReminder: "CRITICAL: You CANNOT edit files. Review and report findings only."
+category: universal
+triggerType: manual
+triggerCommand: /review-plan
+whenToUse: Before executing any implementation prompt. Always.
+whatItDoes: Reviews implementation plans as a senior staff engineer. Challenges assumptions, finds ambiguity, checks verification strategy, identifies missing edge cases.
+expectBack: Refined plan with concerns addressed, or list of blocking questions.
+situationLabel: Got an implementation prompt
 ---
 
 You are a senior staff engineer reviewing an implementation plan.

package/templates/agents/universal/test-writer.md

@@ -1,12 +1,18 @@
 ---
 name: test-writer
-description: "Writes comprehensive, meaningful tests for recently changed code"
+description: Writes comprehensive, meaningful tests for recently changed code
 model: sonnet
 isolation: worktree
 maxTurns: 50
 memory: project
 skills:
   - testing
+category: universal
+triggerType: automatic
+whenToUse: After completing implementation of any feature or module.
+whatItDoes: Writes unit tests, integration tests, edge case tests. Covers happy path, error cases, boundary conditions.
+expectBack: Test files committed to worktree branch. Merge when reviewed.
+situationLabel: Finished implementing a feature
 ---
 
 ## Worktree freshness preamble

package/templates/agents/universal/upstream-watcher.md

@@ -1,6 +1,6 @@
 ---
 name: upstream-watcher
-description: "Cross-references new Anthropic upstream changes against the current project's scaffolded infrastructure and produces an impact report"
+description: Cross-references new Anthropic upstream changes against the current project's scaffolded infrastructure and produces an impact report
 model: sonnet
 isolation: none
 memory: project
@@ -10,6 +10,13 @@ disallowedTools:
   - NotebookEdit
 maxTurns: 30
 criticalSystemReminder: "CRITICAL: You CANNOT edit files. Report findings only. Suggest actions but do not implement them."
+category: universal
+triggerType: manual
+status: reserved
+whenToUse: Reserved for future revival. The /upstream-check slash command was retired in Phase 2 (2026-04); the agent definition is preserved so the scheduled GitHub Actions workflow (.github/workflows/upstream-check.yml) and any future on-demand variant have an established contract to revive.
+whatItDoes: Fetches anthropic-watch feeds, cross-references upstream changes against the project's scaffolded agents/commands/hooks/skills, and produces an impact report.
+expectBack: "Impact report: which upstream changes affect this project, which are informational, and recommended actions."
+situationLabel: Reserved — no in-session command currently invokes this agent
 ---
 
 You are an upstream-awareness specialist. You fetch the anthropic-watch feeds,

package/templates/agents/universal/verify-app.md

@@ -1,12 +1,19 @@
 ---
 name: verify-app
-description: "Verifies the running application end-to-end — tests actual behavior, not just code reading"
+description: Verifies the running application end-to-end — tests actual behavior, not just code reading
 model: sonnet
 isolation: worktree
 background: true
 maxTurns: 50
-initialPrompt: "/start"
+initialPrompt: /start
 criticalSystemReminder: "CRITICAL: You are verification-only. Do NOT edit or fix code. Report findings with exact reproduction steps."
+category: universal
+triggerType: manual
+triggerCommand: /verify
+whenToUse: Before creating a PR. After major changes.
+whatItDoes: Full end-to-end verification. Runs the app, tests all major flows, checks for regressions. More thorough than build-validator.
+expectBack: Detailed verification report. Blocking issues listed.
+situationLabel: Finished a task, ready for PR
 ---
 
 ## Worktree freshness preamble
@@ -27,6 +34,29 @@ end-to-end. Unit tests passing is not enough — you verify the real
 user experience. You work in a worktree to keep verification
 artifacts isolated.
 
+## Worktree boundaries
+
+You operate inside a worktree at the current working directory. Every
+filesystem write you make MUST stay inside the worktree. The host's
+sandbox blocks paths outside it; commands that try to write to absolute
+paths like `/tmp/...`, `/home/...`, or `~/...` will fail or be denied.
+
+- **Need scratch space?** Use `mktemp -d -p .` (creates a temporary
+  directory inside the worktree root) or `mkdir -p .scratch && cd
+  .scratch`. Never use `/tmp/...` directly.
+- **Project docs describe scenarios with absolute paths** (e.g., a
+  CLAUDE.md that says `rm -rf /tmp/test-fresh && mkdir /tmp/test-fresh
+  && ...`)? **Translate** to a worktree-local equivalent before running.
+  The intent — "spawn the CLI in a fresh empty directory" — is what
+  matters; the literal `/tmp` path is not.
+- **Never `rm -rf` a path outside the worktree.** If a verification
+  step seems to require it, that step belongs to the human running
+  outside the worktree, not to you.
+- **If a verification approach is genuinely impossible inside the
+  worktree** (requires real network DNS, an OS-level service, hardware,
+  etc.), report `VERDICT: PARTIAL` with the specific limitation rather
+  than fabricating a workaround.
+
 ## Verification Process
 
 ### 1. Understand What Changed
@@ -120,7 +150,7 @@ You will feel the urge to skip checks. These are the excuses — recognize them:
 
 - **Frontend**: start dev server → navigate to affected page → check console errors → test responsive
 - **Backend/API**: start server → curl endpoints → verify response shapes → test error handling
-- **CLI**: run with typical args → run with edge cases → verify exit codes → test piping
+- **CLI**: spawn from a worktree-local scratch directory (`mktemp -d -p .`) → run with typical args → run with edge cases → verify exit codes → test piping. Do NOT spawn into `/tmp` or absolute paths outside the worktree.
 - **Config/Infrastructure**: validate syntax → dry-run where possible → check env vars
 - **Bug fixes**: reproduce original bug → verify fix → run regression tests
 - **Refactoring**: existing test suite must pass unchanged → diff public API surface

package/templates/commands/build-fix.md

@@ -7,12 +7,11 @@ for diagnosis and resolution.
 
 ## Process
 
-1. Run the full validation suite first to capture all errors:
-   - Build command
-   - Test suite
-   - Linter
-   - Type checker (if applicable)
-   - Formatter check
+1. **Run /verify** to capture test + lint failures (delegate; do not
+   open-code the same checks). Then run the project's **build command**
+   and **type checker** separately to capture compilation errors —
+   these are intentionally outside /verify's read-only-fast contract,
+   so /build-fix discovers them as part of the fix loop.
 
 2. Read the error output carefully. Categorize:
    - Build/compilation errors → fix first (nothing else works)
@@ -20,18 +19,38 @@ for diagnosis and resolution.
    - Test failures → fix third (read test intent before changing)
    - Lint/format → fix last (auto-fix what you can)
 
-3. Fix one category at a time. Re-run checks after each fix.
+3. Fix one category at a time. Re-run /verify (and the build/type
+   commands as relevant) after each fix.
 
-4. After all fixes, run the FULL suite one more time to confirm
-   everything passes.
+4. After all fixes, run /verify one more time plus the build to
+   confirm everything passes.
+
+## Escalation: 3-attempt rule
+
+If you make **3 unsuccessful fix attempts on the same error category**,
+delegate that category to the `bug-fixer` agent (worktree-isolated).
+
+```
+Agent({
+  subagent_type: "bug-fixer",
+  description: "Diagnose stuck <category> errors",
+  prompt: "build-fix has failed 3 times on <category>: <error summary>.
+           Investigate root cause, propose fix, write regression test."
+})
+```
+
+The user is the **last resort, not the third**. Hand off to bug-fixer
+before asking the human — it has the worktree isolation to safely
+explore root causes, can run scoped tests, and frees the main session
+to keep moving on other fixable errors.
 
 ## Rules
 - Never silence a test by deleting it or adding .skip
 - Never weaken lint rules to make errors disappear — fix the code
 - If a test is genuinely wrong (tests old behavior that was
   intentionally changed), update it with a clear commit message
-- If you cannot fix an error after 3 attempts, report it as
-  unresolvable with your diagnosis
+- After 3 failed attempts on the same error category, delegate to
+  `bug-fixer` (see Escalation above). Do not loop forever.
 
 ## When to Use
 - Build is broken after a merge or rebase