Soften prescriptive language for Claude 4.6 compatibility

Anthropic's Claude 4 prompting best practices document warns that
newer models overtrigger on strong directive language (Never/Always/MUST)
that was necessary for older models. This replaces aggressive directives
with natural phrasing across skills and agents while preserving all
security-critical rules (OWASP, prompt injection, secrets) unchanged.

Also reframes trunk-based development as "Recommended" with a note
acknowledging alternative branching strategies like gitflow.

agents/code-reviewer.md

@@ -83,9 +83,9 @@ Categorize every finding:
 
 ## Rules
 
-1. Always review the tests first — they reveal intent and coverage
+1. Review the tests first — they reveal intent and coverage
 2. Read the spec or task description before reviewing code
-3. Every Critical and Important finding must include a specific fix recommendation
-4. Never approve code with Critical issues
-5. Always acknowledge what's done well — specific praise motivates good practices
+3. Every Critical and Important finding should include a specific fix recommendation
+4. Don't approve code with Critical issues
+5. Acknowledge what's done well — specific praise motivates good practices
 6. If you're uncertain about something, say so and suggest investigation rather than guessing

agents/test-engineer.md

@@ -25,7 +25,7 @@ Crosses a boundary          → Integration test
 Critical user flow          → E2E test
 ```
 
-Always test at the lowest level that captures the behavior. Don't write E2E tests for things unit tests can cover.
+Test at the lowest level that captures the behavior. Don't write E2E tests for things unit tests can cover.
 
 ### 3. Follow the Prove-It Pattern for Bugs
 

skills/api-and-interface-design/SKILL.md

@@ -32,7 +32,7 @@ This means: every public behavior — including undocumented quirks, error messa
 
 ### The One-Version Rule
 
-Never force consumers to choose between multiple versions of the same dependency or API. Diamond dependency problems arise when different consumers need different versions of the same thing. Design for a world where only one version exists at a time — extend rather than fork.
+Avoid forcing consumers to choose between multiple versions of the same dependency or API. Diamond dependency problems arise when different consumers need different versions of the same thing. Design for a world where only one version exists at a time — extend rather than fork.
 
 ### 1. Contract First
 
@@ -170,7 +170,7 @@ POST   /api/tasks/:id/comments → Add a comment to a task
 
 ### Pagination
 
-Always paginate list endpoints:
+Paginate list endpoints:
 
 ```typescript
 // Request

skills/code-review-and-quality/SKILL.md

@@ -103,7 +103,7 @@ Small, focused changes are easier to review, faster to merge, and safer to deplo
 
 **When large changes are acceptable:** Complete file deletions and automated refactoring where the reviewer only needs to verify intent, not every line.
 
-**Always separate refactoring from feature work.** A change that refactors existing code and adds new behavior is two changes — submit them separately. Small cleanups (variable renaming) can be included at reviewer discretion.
+**Separate refactoring from feature work.** A change that refactors existing code and adds new behavior is two changes — submit them separately. Small cleanups (variable renaming) can be included at reviewer discretion.
 
 ## Change Descriptions
 
@@ -240,7 +240,7 @@ When resolving review disputes, apply this hierarchy:
 3. **Software design** must be evaluated on engineering principles, not personal preference
 4. **Codebase consistency** is acceptable if it doesn't degrade overall health
 
-**Never accept "I'll clean it up later."** Experience shows deferred cleanup rarely happens. Require cleanup before submission unless it's a genuine emergency. If surrounding issues can't be addressed in this change, require filing a bug with self-assignment.
+**Don't accept "I'll clean it up later."** Experience shows deferred cleanup rarely happens. Require cleanup before submission unless it's a genuine emergency. If surrounding issues can't be addressed in this change, require filing a bug with self-assignment.
 
 ## Honesty in Review
 

skills/code-simplification/SKILL.md

@@ -31,7 +31,7 @@ Simplify code by reducing complexity while preserving exact behavior. The goal i
 
 ### 1. Preserve Behavior Exactly
 
-Never change what the code does — only how it expresses it. All inputs, outputs, side effects, error behavior, and edge cases must remain identical. If you're not sure a simplification preserves behavior, don't make it.
+Don't change what the code does — only how it expresses it. All inputs, outputs, side effects, error behavior, and edge cases must remain identical. If you're not sure a simplification preserves behavior, don't make it.
 
 ```
 ASK BEFORE EVERY CHANGE:
@@ -156,7 +156,7 @@ Scan for these patterns — each one is a concrete signal, not a vague smell:
 
 ### Step 3: Apply Changes Incrementally
 
-Make one simplification at a time. Run tests after each change. **Always submit refactoring changes separately from feature or bug fix changes.** A PR that refactors and adds a feature is two PRs — split them.
+Make one simplification at a time. Run tests after each change. **Submit refactoring changes separately from feature or bug fix changes.** A PR that refactors and adds a feature is two PRs — split them.
 
 ```
 FOR EACH SIMPLIFICATION:
@@ -166,7 +166,7 @@ FOR EACH SIMPLIFICATION:
 4. If tests fail → revert and reconsider
 ```
 
-Never batch multiple simplifications into a single untested change. If something breaks, you need to know which simplification caused it.
+Avoid batching multiple simplifications into a single untested change. If something breaks, you need to know which simplification caused it.
 
 **The Rule of 500:** If a refactoring would touch more than 500 lines, invest in automation (codemods, sed scripts, AST transforms) rather than making the changes by hand. Manual edits at that scale are error-prone and exhausting to review.
 

skills/context-engineering/SKILL.md

@@ -221,7 +221,7 @@ If the spec doesn't cover a case you need to implement:
 
 1. Check existing code for precedent
 2. If no precedent exists, **stop and ask**
-3. Never invent requirements — that's the human's job
+3. Don't invent requirements — that's the human's job
 
 ```
 MISSING REQUIREMENT:
@@ -257,7 +257,7 @@ This catches wrong directions before you've built on them. It's a 30-second inve
 | Context starvation | Agent invents APIs, ignores conventions | Load rules file + relevant source files before each task |
 | Context flooding | Agent loses focus when loaded with >5,000 lines of non-task-specific context. More files does not mean better output. | Include only what is relevant to the current task. Aim for <2,000 lines of focused context per task. |
 | Stale context | Agent references outdated patterns or deleted code | Start fresh sessions when context drifts |
-| Missing examples | Agent invents a new style instead of following yours | Always include one example of the pattern to follow |
+| Missing examples | Agent invents a new style instead of following yours | Include one example of the pattern to follow |
 | Implicit knowledge | Agent doesn't know project-specific rules | Write it down in rules files — if it's not written, it doesn't exist |
 | Silent confusion | Agent guesses when it should ask | Surface ambiguity explicitly using the confusion management patterns above |
 

skills/debugging-and-error-recovery/SKILL.md

@@ -31,7 +31,7 @@ When anything unexpected happens:
 6. RESUME only after verification passes
 ```
 
-**Never push past a failing test or broken build to work on the next feature.** Errors compound. A bug in Step 3 that goes unfixed makes Steps 4-10 wrong.
+**Don't push past a failing test or broken build to work on the next feature.** Errors compound. A bug in Step 3 that goes unfixed makes Steps 4-10 wrong.
 
 ## The Triage Checklist
 

skills/deprecation-and-migration/SKILL.md

@@ -46,7 +46,7 @@ Before deprecating anything, answer these questions:
    → Quantify the migration scope.
 
 3. Does a replacement exist?
-   → If no, build the replacement first. Never deprecate without an alternative.
+   → If no, build the replacement first. Don't deprecate without an alternative.
 
 4. What's the migration cost for each consumer?
    → If trivially automated, do it. If manual and high-effort, weigh against maintenance cost.
@@ -68,7 +68,7 @@ Before deprecating anything, answer these questions:
 
 ### Step 1: Build the Replacement
 
-Never deprecate without a working alternative. The replacement must:
+Don't deprecate without a working alternative. The replacement must:
 
 - Cover all critical use cases of the old system
 - Have documentation and migration guides

skills/documentation-and-adrs/SKILL.md

@@ -86,7 +86,7 @@ Use PostgreSQL with Prisma ORM.
 PROPOSED → ACCEPTED → (SUPERSEDED or DEPRECATED)
 ```
 
-- **Never delete old ADRs.** They capture historical context.
+- **Don't delete old ADRs.** They capture historical context.
 - When a decision changes, write a new ADR that references and supersedes the old one.
 
 ## Inline Documentation

skills/git-workflow-and-versioning/SKILL.md

@@ -15,7 +15,7 @@ Always. Every code change flows through git.
 
 ## Core Principles
 
-### Trunk-Based Development
+### Trunk-Based Development (Recommended)
 
 Keep `main` always deployable. Work in short-lived feature branches that merge back within 1-3 days. Long-lived development branches are hidden costs — they diverge, create merge conflicts, and delay integration. DORA research consistently shows trunk-based development correlates with high-performing engineering teams.
 
@@ -25,9 +25,11 @@ main ──●──●──●──●──●──●──●──●─
          ●──●─╱    ●──╱    ← short-lived feature branches (1-3 days)
 ```
 
+This is the recommended default. Teams using gitflow or long-lived branches can adapt the principles (atomic commits, small changes, descriptive messages) to their branching model — the commit discipline matters more than the specific branching strategy.
+
 - **Dev branches are costs.** Every day a branch lives, it accumulates merge risk.
 - **Release branches are acceptable.** When you need to stabilize a release while main moves forward.
-- **Feature flags > long branches.** Deploy incomplete work behind flags rather than keeping it on a branch for weeks.
+- **Feature flags > long branches.** Prefer deploying incomplete work behind flags rather than keeping it on a branch for weeks.
 
 ### 1. Commit Early, Commit Often
 
@@ -91,7 +93,7 @@ update auth.ts
 - `docs` — Documentation only
 - `chore` — Tooling, dependencies, config
 
-### 4. Never Mix Concerns
+### 4. Keep Concerns Separate
 
 Don't combine formatting changes with behavior changes. Don't combine refactors with features. Each type of change should be a separate commit — and ideally a separate PR:
 
@@ -104,7 +106,7 @@ git commit -m "feat: add phone number validation to registration"
 git commit -m "refactor validation and add phone number field"
 ```
 
-**Always separate refactoring from feature work.** A refactoring change and a feature change are two different changes — submit them separately. This makes each change easier to review, revert, and understand in history. Small cleanups (renaming a variable) can be included in a feature commit at reviewer discretion.
+**Separate refactoring from feature work.** A refactoring change and a feature change are two different changes — submit them separately. This makes each change easier to review, revert, and understand in history. Small cleanups (renaming a variable) can be included in a feature commit at reviewer discretion.
 
 ### 5. Size Your Changes
 
@@ -243,7 +245,7 @@ Automate this with git hooks:
 
 - **Commit generated files** only if the project expects them (e.g., `package-lock.json`, Prisma migrations)
 - **Don't commit** build output (`dist/`, `.next/`), environment files (`.env`), or IDE config (`.vscode/settings.json` unless shared)
-- **Always have a `.gitignore`** that covers: `node_modules/`, `dist/`, `.env`, `.env.local`, `*.pem`
+- **Have a `.gitignore`** that covers: `node_modules/`, `dist/`, `.env`, `.env.local`, `*.pem`
 
 ## Using Git for Debugging
 

skills/incremental-implementation/SKILL.md

@@ -7,7 +7,7 @@ description: Use when implementing any feature or change that touches more than
 
 ## Overview
 
-Build in thin vertical slices — implement one piece, test it, verify it, then expand. Never attempt to implement an entire feature in one pass. Each increment should leave the system in a working, testable state. This is the execution discipline that makes large features manageable.
+Build in thin vertical slices — implement one piece, test it, verify it, then expand. Avoid implementing an entire feature in one pass. Each increment should leave the system in a working, testable state. This is the execution discipline that makes large features manageable.
 
 ## When to Use
 
@@ -140,9 +140,9 @@ Each increment changes one logical thing. Don't mix concerns:
 
 **Good:** Three separate commits — one for each change.
 
-### Rule 2: Always Compilable
+### Rule 2: Keep It Compilable
 
-After each increment, the project must build and existing tests must pass. Never leave the codebase in a broken state between slices.
+After each increment, the project must build and existing tests must pass. Don't leave the codebase in a broken state between slices.
 
 ### Rule 3: Feature Flags for Incomplete Features
 
@@ -178,7 +178,7 @@ Each increment should be independently revertable:
 - Additive changes (new files, new functions) are easy to revert
 - Modifications to existing code should be minimal and focused
 - Database migrations should have corresponding rollback migrations
-- Never delete something in one commit and replace it in the same commit — separate them
+- Avoid deleting something in one commit and replacing it in the same commit — separate them
 
 ## Working with Agents
 

skills/spec-driven-development/SKILL.md

@@ -46,7 +46,7 @@ ASSUMPTIONS I'M MAKING:
 → Correct me now or I'll proceed with these.
 ```
 
-Never silently fill in ambiguous requirements. The spec's entire purpose is to surface misunderstandings *before* code gets written — assumptions are the most dangerous form of misunderstanding.
+Don't silently fill in ambiguous requirements. The spec's entire purpose is to surface misunderstandings *before* code gets written — assumptions are the most dangerous form of misunderstanding.
 
 **Write a spec document covering these six core areas:**
 

skills/using-agent-skills/SKILL.md

@@ -51,7 +51,7 @@ ASSUMPTIONS I'M MAKING:
 → Correct me now or I'll proceed with these.
 ```
 
-Never silently fill in ambiguous requirements. The most common failure mode is making wrong assumptions and running with them unchecked. Surface uncertainty early — it's cheaper than rework.
+Don't silently fill in ambiguous requirements. The most common failure mode is making wrong assumptions and running with them unchecked. Surface uncertainty early — it's cheaper than rework.
 
 ### 2. Manage Confusion Actively
 
@@ -121,7 +121,7 @@ These are the subtle errors that look like productivity but create problems:
 
 ## Skill Rules
 
-1. **Always check for an applicable skill before starting work.** Skills encode processes that prevent common mistakes.
+1. **Check for an applicable skill before starting work.** Skills encode processes that prevent common mistakes.
 
 2. **Skills are workflows, not suggestions.** Follow the steps in order. Don't skip verification steps.