mandrel 1.92.0 → 1.94.0

package/.agents/skills/core/ci-cd-and-automation/examples.md

@@ -1,211 +0,0 @@
-# CI/CD and Automation — Examples
-
-Long stack-specific snippets extracted from `SKILL.md` so the skill stays
-focused on policy and routing. The samples below assume GitHub Actions plus
-Node 22 / npm; adapt to your project's runner, package manager, and language.
-
----
-
-## GitHub Actions: Basic CI Pipeline
-
-```yaml
-# .github/workflows/ci.yml
-name: CI
-
-on:
-  pull_request:
-    branches: [main]
-  push:
-    branches: [main]
-
-jobs:
-  quality:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-          cache: 'npm'
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Lint
-        run: npm run lint
-
-      - name: Type check
-        run: npx tsc --noEmit
-
-      - name: Test
-        run: npm test -- --coverage
-
-      - name: Build
-        run: npm run build
-
-      - name: Security audit
-        run: npm audit --audit-level=high
-```
-
-## GitHub Actions: With Database Integration Tests
-
-```yaml
-integration:
-  runs-on: ubuntu-latest
-  services:
-    postgres:
-      image: postgres:16
-      env:
-        POSTGRES_DB: testdb
-        POSTGRES_USER: ci_user
-        POSTGRES_PASSWORD: ${{ secrets.CI_DB_PASSWORD }}
-      ports:
-        - 5432:5432
-      options: >-
-        --health-cmd pg_isready --health-interval 10s --health-timeout 5s
-        --health-retries 5
-
-  steps:
-    - uses: actions/checkout@v4
-    - uses: actions/setup-node@v4
-      with:
-        node-version: '22'
-        cache: 'npm'
-    - run: npm ci
-    - name: Run migrations
-      run: npx prisma migrate deploy
-      env:
-        DATABASE_URL:
-          postgresql://ci_user:${{ secrets.CI_DB_PASSWORD
-          }}@localhost:5432/testdb
-    - name: Integration tests
-      run: npm run test:integration
-      env:
-        DATABASE_URL:
-          postgresql://ci_user:${{ secrets.CI_DB_PASSWORD
-          }}@localhost:5432/testdb
-```
-
-> **Note:** Even for CI-only test databases, use GitHub Secrets for credentials
-> rather than hardcoding values. This builds good habits and prevents accidental
-> reuse of test credentials in other contexts.
-
-## GitHub Actions: E2E Tests
-
-```yaml
-e2e:
-  runs-on: ubuntu-latest
-  steps:
-    - uses: actions/checkout@v4
-    - uses: actions/setup-node@v4
-      with:
-        node-version: '22'
-        cache: 'npm'
-    - run: npm ci
-    - name: Install Playwright
-      run: npx playwright install --with-deps chromium
-    - name: Build
-      run: npm run build
-    - name: Run E2E tests
-      run: npx playwright test
-    - uses: actions/upload-artifact@v4
-      if: failure()
-      with:
-        name: playwright-report
-        path: playwright-report/
-```
-
-## Deployment: Preview on PR
-
-```yaml
-# Deploy preview on PR (Vercel/Netlify/etc.)
-deploy-preview:
-  runs-on: ubuntu-latest
-  if: github.event_name == 'pull_request'
-  steps:
-    - uses: actions/checkout@v4
-    - name: Deploy preview
-      run: npx vercel --token=${{ secrets.VERCEL_TOKEN }}
-```
-
-## Deployment: Manual Rollback Workflow
-
-```yaml
-# Manual rollback workflow
-name: Rollback
-on:
-  workflow_dispatch:
-    inputs:
-      version:
-        description: 'Version to rollback to'
-        required: true
-
-jobs:
-  rollback:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Rollback deployment
-        run: |
-          # Deploy the specified previous version
-          npx vercel rollback ${{ inputs.version }}
-```
-
-## Caching and Parallelism
-
-```yaml
-jobs:
-  lint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: '22', cache: 'npm' }
-      - run: npm ci
-      - run: npm run lint
-
-  typecheck:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: '22', cache: 'npm' }
-      - run: npm ci
-      - run: npx tsc --noEmit
-
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: '22', cache: 'npm' }
-      - run: npm ci
-      - run: npm test -- --coverage
-```
-
-## Dependency Updates: Dependabot
-
-```yaml
-# .github/dependabot.yml
-version: 2
-updates:
-  - package-ecosystem: npm
-    directory: /
-    schedule:
-      interval: weekly
-    open-pull-requests-limit: 5
-```
-
-## Feature Flag Pattern
-
-```typescript
-// Simple feature flag pattern
-if (featureFlags.isEnabled('new-checkout-flow', { userId })) {
-  return renderNewCheckout();
-}
-return renderLegacyCheckout();
-```
-
-**Flag lifecycle:** Create → Enable for testing → Canary → Full rollout →
-Remove the flag and dead code. Flags that live forever become technical debt —
-set a cleanup date when you create them.

package/.agents/skills/core/code-simplification/SKILL.md

@@ -1,389 +0,0 @@
----
-name: code-simplification
-description:
-  Simplifies code for clarity. Use when refactoring code for clarity without
-  changing behavior. Use when code works but is harder to read, maintain, or
-  extend than it should be. Use when reviewing code that has accumulated
-  unnecessary complexity.
----
-
-# Code Simplification
-
-## Policy Capsule
-
-- Preserve behaviour **exactly**: inputs, outputs, side effects, error semantics, and ordering must be identical. If you're not sure a change preserves behaviour, don't make it.
-- Every simplification MUST leave existing tests passing without modification; if tests need to change, the refactor changed behaviour and is no longer a simplification.
-- Follow project conventions (CLAUDE.md, neighbour-code patterns, import style, naming, error handling). Simplification that breaks consistency is churn, not improvement.
-- Prefer clarity over cleverness: explicit code beats compact code whenever the compact form requires a mental pause to parse.
-- Comprehend before you simplify — never refactor code you don't yet fully understand.
-- Do not simplify for its own sake: skip when code is already clean, when performance would measurably regress, or when the module is about to be rewritten.
-- Lines-of-code is **not** the goal. The metric is "would a new team member understand this faster than the original?".
-- Make each simplification an isolated commit, not a drive-by inside a feature change (see `git-workflow-and-versioning`).
-- Verify behaviourally: run the full test suite, exercise affected paths, and diff the runtime output against the original before claiming the simplification is safe.
-
-> Inspired by the
-> [Claude Code Simplifier plugin](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/code-simplifier/agents/code-simplifier.md).
-> Adapted here as a model-agnostic, process-driven skill for any AI coding
-> agent.
-
-## Overview
-
-Simplify code by reducing complexity while preserving exact behavior. The goal
-is not fewer lines — it's code that is easier to read, understand, modify, and
-debug. Every simplification must pass a simple test: "Would a new team member
-understand this faster than the original?"
-
-## When to Use
-
-- After a feature is working and tests pass, but the implementation feels
-  heavier than it needs to be
-- During code review when readability or complexity issues are flagged
-- When you encounter deeply nested logic, long functions, or unclear names
-- When refactoring code written under time pressure
-- When consolidating related logic scattered across files
-- After merging changes that introduced duplication or inconsistency
-
-**When NOT to use:**
-
-- Code is already clean and readable — don't simplify for the sake of it
-- You don't understand what the code does yet — comprehend before you simplify
-- The code is performance-critical and the "simpler" version would be measurably
-  slower
-- You're about to rewrite the module entirely — simplifying throwaway code
-  wastes effort
-
-## The Five Principles
-
-### 1. Preserve Behavior Exactly
-
-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.
-
-```text
-ASK BEFORE EVERY CHANGE:
-→ Does this produce the same output for every input?
-→ Does this maintain the same error behavior?
-→ Does this preserve the same side effects and ordering?
-→ Do all existing tests still pass without modification?
-```
-
-### 2. Follow Project Conventions
-
-Simplification means making code more consistent with the codebase, not imposing
-external preferences. Before simplifying:
-
-```text
-1. Read CLAUDE.md / project conventions
-2. Study how neighboring code handles similar patterns
-3. Match the project's style for:
-   - Import ordering and module system
-   - Function declaration style
-   - Naming conventions
-   - Error handling patterns
-   - Type annotation depth
-```
-
-Simplification that breaks project consistency is not simplification — it's
-churn.
-
-### 3. Prefer Clarity Over Cleverness
-
-Explicit code is better than compact code when the compact version requires a
-mental pause to parse.
-
-```typescript
-// UNCLEAR: Dense ternary chain
-const label = isNew
-  ? 'New'
-  : isUpdated
-    ? 'Updated'
-    : isArchived
-      ? 'Archived'
-      : 'Active';
-
-// CLEAR: Readable mapping
-function getStatusLabel(item: Item): string {
-  if (item.isNew) return 'New';
-  if (item.isUpdated) return 'Updated';
-  if (item.isArchived) return 'Archived';
-  return 'Active';
-}
-```
-
-```typescript
-// UNCLEAR: Chained reduces with inline logic
-const result = items.reduce(
-  (acc, item) => ({
-    ...acc,
-    [item.id]: { ...acc[item.id], count: (acc[item.id]?.count ?? 0) + 1 },
-  }),
-  {},
-);
-
-// CLEAR: Named intermediate step
-const countById = new Map<string, number>();
-for (const item of items) {
-  countById.set(item.id, (countById.get(item.id) ?? 0) + 1);
-}
-```
-
-### 4. Maintain Balance
-
-Simplification has a failure mode: over-simplification. Watch for these traps:
-
-- **Inlining too aggressively** — removing a helper that gave a concept a name
-  makes the call site harder to read
-- **Combining unrelated logic** — two simple functions merged into one complex
-  function is not simpler
-- **Removing "unnecessary" abstraction** — some abstractions exist for
-  extensibility or testability, not complexity
-- **Optimizing for line count** — fewer lines is not the goal; easier
-  comprehension is
-
-### 5. Scope to What Changed
-
-Default to simplifying recently modified code. Avoid drive-by refactors of
-unrelated code unless explicitly asked to broaden scope. Unscoped simplification
-creates noise in diffs and risks unintended regressions.
-
-## The Simplification Process
-
-### Step 1: Understand Before Touching (Chesterton's Fence)
-
-Before changing or removing anything, understand why it exists. This is
-Chesterton's Fence: if you see a fence across a road and don't understand why
-it's there, don't tear it down. First understand the reason, then decide if the
-reason still applies.
-
-```text
-BEFORE SIMPLIFYING, ANSWER:
-- What is this code's responsibility?
-- What calls it? What does it call?
-- What are the edge cases and error paths?
-- Are there tests that define the expected behavior?
-- Why might it have been written this way? (Performance? Platform constraint? Historical reason?)
-- Check git blame: what was the original context for this code?
-```
-
-If you can't answer these, you're not ready to simplify. Read more context
-first.
-
-### Step 2: Identify Simplification Opportunities
-
-Scan for these patterns — each one is a concrete signal, not a vague smell:
-
-**Structural complexity:**
-
-| Pattern                    | Signal                             | Simplification                                            |
-| -------------------------- | ---------------------------------- | --------------------------------------------------------- |
-| Deep nesting (3+ levels)   | Hard to follow control flow        | Extract conditions into guard clauses or helper functions |
-| Long functions (50+ lines) | Multiple responsibilities          | Split into focused functions with descriptive names       |
-| Nested ternaries           | Requires mental stack to parse     | Replace with if/else chains, switch, or lookup objects    |
-| Boolean parameter flags    | `doThing(true, false, true)`       | Replace with options objects or separate functions        |
-| Repeated conditionals      | Same `if` check in multiple places | Extract to a well-named predicate function                |
-
-**Naming and readability:**
-
-| Pattern                    | Signal                                         | Simplification                                                           |
-| -------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------ |
-| Generic names              | `data`, `result`, `temp`, `val`, `item`        | Rename to describe the content: `userProfile`, `validationErrors`        |
-| Abbreviated names          | `usr`, `cfg`, `btn`, `evt`                     | Use full words unless the abbreviation is universal (`id`, `url`, `api`) |
-| Misleading names           | Function named `get` that also mutates state   | Rename to reflect actual behavior                                        |
-| Comments explaining "what" | `// increment counter` above `count++`         | Delete the comment — the code is clear enough                            |
-| Comments explaining "why"  | `// Retry because the API is flaky under load` | Keep these — they carry intent the code can't express                    |
-
-**Redundancy:**
-
-| Pattern                   | Signal                                                       | Simplification                                            |
-| ------------------------- | ------------------------------------------------------------ | --------------------------------------------------------- |
-| Duplicated logic          | Same 5+ lines in multiple places                             | Extract to a shared function                              |
-| Dead code                 | Unreachable branches, unused variables, commented-out blocks | Remove (after confirming it's truly dead)                 |
-| Unnecessary abstractions  | Wrapper that adds no value                                   | Inline the wrapper, call the underlying function directly |
-| Over-engineered patterns  | Factory-for-a-factory, strategy-with-one-strategy            | Replace with the simple direct approach                   |
-| Redundant type assertions | Casting to a type that's already inferred                    | Remove the assertion                                      |
-
-### Step 3: Apply Changes Incrementally
-
-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.
-
-```text
-FOR EACH SIMPLIFICATION:
-1. Make the change
-2. Run the test suite
-3. If tests pass → commit (or continue to next simplification)
-4. If tests fail → revert and reconsider
-```
-
-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.
-
-### Step 4: Verify the Result
-
-After all simplifications, step back and evaluate the whole:
-
-```text
-COMPARE BEFORE AND AFTER:
-- Is the simplified version genuinely easier to understand?
-- Did you introduce any new patterns inconsistent with the codebase?
-- Is the diff clean and reviewable?
-- Would a teammate approve this change?
-```
-
-If the "simplified" version is harder to understand or review, revert. Not every
-simplification attempt succeeds.
-
-## Language-Specific Guidance
-
-### TypeScript / JavaScript
-
-```typescript
-// SIMPLIFY: Unnecessary async wrapper
-// Before
-async function getUser(id: string): Promise<User> {
-  return await userService.findById(id);
-}
-// After
-function getUser(id: string): Promise<User> {
-  return userService.findById(id);
-}
-
-// SIMPLIFY: Verbose conditional assignment
-// Before
-let displayName: string;
-if (user.nickname) {
-  displayName = user.nickname;
-} else {
-  displayName = user.fullName;
-}
-// After
-const displayName = user.nickname || user.fullName;
-
-// SIMPLIFY: Manual array building
-// Before
-const activeUsers: User[] = [];
-for (const user of users) {
-  if (user.isActive) {
-    activeUsers.push(user);
-  }
-}
-// After
-const activeUsers = users.filter((user) => user.isActive);
-
-// SIMPLIFY: Redundant boolean return
-// Before
-function isValid(input: string): boolean {
-  if (input.length > 0 && input.length < 100) {
-    return true;
-  }
-  return false;
-}
-// After
-function isValid(input: string): boolean {
-  return input.length > 0 && input.length < 100;
-}
-```
-
-### Python
-
-```python
-# SIMPLIFY: Verbose dictionary building
-# Before
-result = {}
-for item in items:
-    result[item.id] = item.name
-# After
-result = {item.id: item.name for item in items}
-
-# SIMPLIFY: Nested conditionals with early return
-# Before
-def process(data):
-    if data is not None:
-        if data.is_valid():
-            if data.has_permission():
-                return do_work(data)
-            else:
-                raise PermissionError("No permission")
-        else:
-            raise ValueError("Invalid data")
-    else:
-        raise TypeError("Data is None")
-# After
-def process(data):
-    if data is None:
-        raise TypeError("Data is None")
-    if not data.is_valid():
-        raise ValueError("Invalid data")
-    if not data.has_permission():
-        raise PermissionError("No permission")
-    return do_work(data)
-```
-
-### React / JSX
-
-```tsx
-// SIMPLIFY: Verbose conditional rendering
-// Before
-function UserBadge({ user }: Props) {
-  if (user.isAdmin) {
-    return <Badge variant="admin">Admin</Badge>;
-  } else {
-    return <Badge variant="default">User</Badge>;
-  }
-}
-// After
-function UserBadge({ user }: Props) {
-  const variant = user.isAdmin ? 'admin' : 'default';
-  const label = user.isAdmin ? 'Admin' : 'User';
-  return <Badge variant={variant}>{label}</Badge>;
-}
-
-// SIMPLIFY: Prop drilling through intermediate components
-// Before — consider whether context or composition solves this better.
-// This is a judgment call — flag it, don't auto-refactor.
-```
-
-## Common Rationalizations
-
-| Rationalization                                      | Reality                                                                                                                                               |
-| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| "It's working, no need to touch it"                  | Working code that's hard to read will be hard to fix when it breaks. Simplifying now saves time on every future change.                               |
-| "Fewer lines is always simpler"                      | A 1-line nested ternary is not simpler than a 5-line if/else. Simplicity is about comprehension speed, not line count.                                |
-| "I'll just quickly simplify this unrelated code too" | Unscoped simplification creates noisy diffs and risks regressions in code you didn't intend to change. Stay focused.                                  |
-| "The types make it self-documenting"                 | Types document structure, not intent. A well-named function explains _why_ better than a type signature explains _what_.                              |
-| "This abstraction might be useful later"             | Don't preserve speculative abstractions. If it's not used now, it's complexity without value. Remove it and re-add when needed.                       |
-| "The original author must have had a reason"         | Maybe. Check git blame — apply Chesterton's Fence. But accumulated complexity often has no reason; it's just the residue of iteration under pressure. |
-| "I'll refactor while adding this feature"            | Separate refactoring from feature work. Mixed changes are harder to review, revert, and understand in history.                                        |
-
-## Red Flags
-
-- Simplification that requires modifying tests to pass (you likely changed
-  behavior)
-- "Simplified" code that is longer and harder to follow than the original
-- Renaming things to match your preferences rather than project conventions
-- Removing error handling because "it makes the code cleaner"
-- Simplifying code you don't fully understand
-- Batching many simplifications into one large, hard-to-review commit
-- Refactoring code outside the scope of the current task without being asked
-
-## Verification
-
-After completing a simplification pass:
-
-- [ ] All existing tests pass without modification
-- [ ] Build succeeds with no new warnings
-- [ ] Linter/formatter passes (no style regressions)
-- [ ] Each simplification is a reviewable, incremental change
-- [ ] The diff is clean — no unrelated changes mixed in
-- [ ] Simplified code follows project conventions (checked against CLAUDE.md or
-      equivalent)
-- [ ] No error handling was removed or weakened
-- [ ] No dead code was left behind (unused imports, unreachable branches)
-- [ ] A teammate or review agent would approve the change as a net improvement