azcodr 1.0.0

package/.agents/skills/agentic-architect/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: agentic-architect
+description: Use when creating, modularizing, auditing, or updating agentic configuration files, including AGENTS.md, CLAUDE.md, rule documentation files, or skills under .agents/skills/ following the progressive disclosure architecture. Do not use for writing application business logic.
+---
+
+# Agentic Architect Skill
+
+> **Core Philosophy:** Eliminate context bloat and model degradation through progressive disclosure, lean entrypoints, strict skill front matter, automated symlink parity, and relentless questioning during skill architecture.
+
+---
+
+## 1. When to Use This Skill
+- Auditing existing `AGENTS.md` or `CLAUDE.md` files for token bloat or giant bullet lists.
+- Decoupling large domain sections (testing, database, auth, UI) into modular rule files.
+- Authoring new specialized skills under `.agents/skills/` using relentless questioning.
+- Establishing harness parity across different AI coding environments via symlinks.
+- Implementing the continuous refinement loop to update skills based on AI mistakes.
+
+---
+
+## 2. Step-by-Step Execution Workflow
+
+### Step 1: Relentless Skill Architecture Inquiry (Question Everything)
+Before writing a single line of a skill or rule, execute the **7 Core Inquiry Branches**:
+1. **Placement & Scope:** Does this belong in root `AGENTS.md` (all prompts), nested `AGENTS.md` (one package), a continuous rule in `docs/rules/`, or an on-demand skill in `.agents/skills/`?
+2. **Trigger Boundaries:** What is the exact user intent? What is the explicit imperative trigger (`Use when...`) and the anti-triggers (`Do NOT use for...`)?
+3. **Domain Ground Truth:** Have all generic textbook tutorials been purged? Is this grounded in verified codebase evidence?
+4. **Gotchas & Anti-Patterns:** What exact mistakes has the AI repeatedly made in this domain that must be forbidden?
+5. **Determinism vs. LLM:** Can brittle tasks be converted into deterministic scripts under `scripts/`?
+6. **Progressive Bloat:** Is `SKILL.md` strictly under 500 lines, offloading deep manuals to `references/` and templates to `assets/`?
+7. **Verification & Proof:** What structured response template and self-validation checklist will prove success?
+*Rule:* If any branch is unanswered or ambiguous, **STOP and ask the user** (or inspect workspace files). Never fill gaps with assumptions.
+
+### Step 2: Audit Existing Agent Configuration
+Inspect current agent files and measure their token and line footprint:
+- File length > 120–150 lines in root `AGENTS.md`.
+- Giant bullet lists accumulated from past one-off bugs.
+- Human onboarding guides (cloning instructions, dev machine setup).
+- Framework-specific deep tutorials that only apply to a minority of tasks.
+- Deep, fragile file paths that rot over time.
+
+### Step 3: Decouple Domain Directives into Modular Rules
+Extract continuous technical requirements into dedicated markdown files under `docs/rules/`:
+- `docs/rules/clean_code.md` (Clean Code, Pragmatic Programmer, CQS, SLAP)
+- `docs/rules/cloud_native.md` (12-Factor 2026, OpenTelemetry, API-first)
+- `docs/rules/compliance.md` (SOC 2 Type II, ISO 27001, GDPR)
+- `docs/rules/continuous_integration.md` (Shift-left pipelines, trunk-based CI)
+- `docs/rules/requirements_engineering.md` (INVEST user stories, Gherkin criteria)
+
+### Step 4: Streamline Root AGENTS.md
+Refactor root `AGENTS.md` to be strictly bounded:
+1. **Mission Statement & Open-Source Mandate:** 1–2 sentences defining project domain, purpose, and 100% open-source requirement.
+2. **Runtime & Scripts:** Declared package manager (Node 24 / npm 11) and core scripts.
+3. **Core Operating Framework:** Zero-Assumption Rule, Relentless Questioning Loop, 5-stage lifecycle, action boundaries.
+4. **Progressive Disclosure Index:** Markdown table mapping each domain to its `docs/rules/*.md` file.
+
+### Step 5: Author Specialized Skills via Progressive Disclosure
+When a task is complex, multi-step, or specialized, encapsulate it into `.agents/skills/<skill-name>/`:
+1. **Front Matter:**
+   - `name`: kebab-case identifier.
+   - `description`: < 1024 characters. Must start with imperative `Use when...` defining exact trigger conditions and when NOT to use.
+2. **Body:**
+   - Keep under 500 lines.
+   - Ground in verified project experience, not general documentation the AI already knows.
+   - Include a mandatory **"Gotchas & What NOT to Do"** section.
+   - Provide structured output templates.
+3. **Progressive Subdirectories:**
+   - `references/`: Reference docs loaded only on demand.
+   - `scripts/`: Deterministic code (bash/node) to prevent stochastic AI divergence.
+   - `assets/`: Static templates, lookup tables, and schemas.
+
+### Step 6: Enforce Harness Parity via Symlinks
+Prevent divergence between Claude Code, standard AGENTS.md, and legacy tooling:
+```bash
+ln -sf AGENTS.md CLAUDE.md
+ln -sf AGENTS.md agents.md
+```
+
+### Step 7: Apply the Continuous Refinement Loop
+1. Save the initial raw AI output draft.
+2. Produce the human-adjusted gold standard version.
+3. Diff the two versions to identify repeated flaws or stylistic divergence.
+4. Update the skill's "What NOT to Do" section with concrete negative examples.
+
+---
+
+## 3. Gotchas & What NOT to Do
+
+- **DO NOT** guess what a skill should do. Run the Relentless Skill Architecture Inquiry first.
+- **DO NOT** let root `AGENTS.md` exceed 120–150 lines. Every extra token degrades LLM attention.
+- **DO NOT** write passive skill descriptions like `"Tanstack query documentation"`. Use `"Use when implementing Tanstack Query caches..."`.
+- **DO NOT** include human "Getting Started" guides. Agents already have the workspace open.
+- **DO NOT** hardcode individual file paths that change frequently. Reference architectural layers instead.
+- **DO NOT** duplicate content across `CLAUDE.md` and `AGENTS.md`. Always use symbolic links.
+- **DO NOT** add preemptive rules before the agent has actually made the mistake. Ground additions in real experience.
+
+---
+
+## 4. Verification Checklist
+
+Before finalizing any agent configuration update, verify:
+- [ ] Relentless Skill Architecture Inquiry completed for all 7 branches.
+- [ ] Root `AGENTS.md` is under 120 lines and loads within minimal tokens.
+- [ ] Specialized domain instructions are decoupled into `docs/rules/`.
+- [ ] Progressive disclosure table in `AGENTS.md` contains valid, clickable markdown links.
+- [ ] All skills have front matter with `name` and imperative `description` starting with `Use when...`.
+- [ ] All skills are under 500 lines or offload sub-content to `references/`.
+- [ ] Every skill contains a "Gotchas & What NOT to Do" section.
+- [ ] Symlinks (`CLAUDE.md`, `agents.md`) resolve to `AGENTS.md`.
+
+---
+
+## 5. Subdirectories & Progressive Resources
+- [references/skill_architecture_inquiry.md](./references/skill_architecture_inquiry.md): The interactive 7-branch relentless questioning guide for skills.
+- [references/agents_md_template.md](./references/agents_md_template.md): Boilerplate template for lean root and nested `AGENTS.md` files.
+- [references/skill_template.md](./references/skill_template.md): Boilerplate template for authoring production-grade `SKILL.md` files.
+- [references/refinement_workflow.md](./references/refinement_workflow.md): Step-by-step guide for capturing AI draft diffs against human edits to update skills.
+- [scripts/validate_agentic_configs.sh](./scripts/validate_agentic_configs.sh): Deterministic Bash script validating front matter, line ceilings, link health, and symlink parity.

package/.agents/skills/agentic-architect/references/agents_md_template.md

@@ -0,0 +1,59 @@
+# Root & Nested AGENTS.md Template
+
+Use this template when bootstrapping or restructuring an `AGENTS.md` file according to the progressive disclosure architecture.
+
+---
+
+```markdown
+# AGENTS.md
+
+> **[Workspace / Package Name] Directives**  
+> **Rule Zero:** Assume nothing. Every action must be grounded in verified evidence from this workspace or direct instructions from the user.
+
+---
+
+## 1. Project Overview & Environment
+- **Purpose:** [1–2 sentences explaining what this project does and its core domain].
+- **Runtime & Tools:** [e.g. Node 24 / npm 11, package manager, key global scripts].
+- **High-Level Layout:**
+  - `apps/` — [High-level package boundaries].
+  - `packages/` — [Shared libraries/utilities].
+  - `docs/rules/` — [Modular progressive disclosure rules].
+
+---
+
+## 2. Core Operating Framework
+- **Ground Truth Only:** A statement is only true if proven by a file, command output, or direct user instruction.
+- **Relentless Questioning Loop:** Before acting, answer:
+  1. What is current state?
+  2. What is exact goal?
+  3. What tools are available?
+  4. What could break?
+  5. How will we prove it works?
+- **Execution Stages:** `DISCOVER` ➔ `INTERROGATE` ➔ `PLAN` ➔ `EXECUTE` ➔ `VERIFY`.
+- **Action Boundaries:**
+  - **ALWAYS:** Read before editing; verify commands before running; verify results with evidence.
+  - **ASK FIRST:** Adding dependencies, deleting files, modifying DB schemas or existing tests.
+  - **NEVER:** Guess paths or flags; silently ignore errors; import external assumptions.
+
+---
+
+## 3. Progressive Disclosure Rules
+
+Read these specialized rule files on demand when performing relevant tasks:
+
+| Domain | Rule Reference File | When to Consult |
+|---|---|---|
+| **Testing** | [docs/rules/test_driven_development.md](../../../../docs/rules/test_driven_development.md) | Writing acceptance/unit tests, coverage checks. |
+| **Multi-Tenancy** | [docs/rules/multitenancy_isolation.md](../../../../docs/rules/multitenancy_isolation.md) | Tenant context resolution, PostgreSQL RLS. |
+| **Database** | [docs/rules/database_transactions.md](../../../../docs/rules/database_transactions.md) | ACID transactions, outbox pattern, atomicity. |
+
+---
+
+## 4. Harness Parity
+Keep `AGENTS.md`, `CLAUDE.md`, and `agents.md` in sync via filesystem symlinks:
+```bash
+ln -sf AGENTS.md CLAUDE.md
+ln -sf AGENTS.md agents.md
+```
+```

package/.agents/skills/agentic-architect/references/refinement_workflow.md

@@ -0,0 +1,32 @@
+# Continuous Skill & Rule Refinement Workflow
+
+> **Purpose:** Iteratively improve AI code output by harvesting manual developer edits and converting recurring mistakes into explicit skill rules.
+
+---
+
+## The 4-Step Refinement Loop
+
+```
+1. AI Draft Generated ──► 2. Human Manual Edit ──► 3. Extract Gaps & Anti-Patterns ──► 4. Update Skill
+```
+
+### 1. Capture Raw Output
+When prompting the AI to execute a complex task (e.g. drafting an article, building a complex form, scaffolding an endpoint), retain the raw generated output before making edits.
+
+### 2. Perform Gold-Standard Edits
+Manually modify the generated file to match production quality:
+- Adjust architectural choices.
+- Fix styling, accessibility, or type annotations.
+- Correct API response shapes or error handling.
+
+### 3. Analyze the Diff
+Compare the initial AI draft against the final human version:
+- What did the AI assume that was incorrect?
+- What repetitive boilerplate did the AI miss?
+- What unnecessary packages, methods, or complex patterns did it introduce?
+
+### 4. Feed Back into the Skill
+Update the relevant skill or rule file:
+- Add positive examples under the workflow section.
+- **Crucial:** Add explicit negative rules in the **"Gotchas & What NOT to Do"** section (e.g. *"DO NOT use window.confirm; use @radix-ui/react-alert-dialog"*).
+- If a step failed due to non-deterministic CLI flags, write an executable helper script under `scripts/`.

package/.agents/skills/agentic-architect/references/skill_architecture_inquiry.md

@@ -0,0 +1,63 @@
+# Relentless Skill Architecture Inquiry Guide
+
+> **Core Rule:** Never assume what a skill needs. Relentlessly interrogate all 7 branches before authoring or modifying any `SKILL.md`.
+
+---
+
+## The 7 Core Inquiry Branches
+
+```
+[Skill Request / Idea]
+       │
+       ▼
+[Branch 1: Placement & Scope]
+       ├─ All prompts repository-wide? ─────────► Root AGENTS.md
+       ├─ One monorepo package only? ──────────► Nested package AGENTS.md
+       ├─ Continuous domain coding rule? ──────► docs/rules/*.md
+       └─ Specialized on-demand workflow? ─────► .agents/skills/<name>/
+       │
+       ▼
+[Branch 2: Trigger Intent & Anti-Triggers]
+       ├─ What explicit user request triggers this?
+       ├─ Imperative phrasing: 'Use when the user wants to...' (< 1024 chars)
+       └─ Negative boundaries: 'Do NOT use for...'
+       │
+       ▼
+[Branch 3: Domain Ground Truth (Purge Fluff)]
+       ├─ What does the LLM already know from pre-training? (PURGE)
+       └─ What is strictly proprietary/unique to this repository? (KEEP)
+       │
+       ▼
+[Branch 4: Anti-Patterns & Gotchas (What NOT to Do)]
+       ├─ What mistakes has the AI actually made in past attempts?
+       └─ Formulate 3–5 explicit negative constraints ('DO NOT...')
+       │
+       ▼
+[Branch 5: Determinism vs. Stochastic LLM]
+       ├─ Are there brittle command lines or JSON formatting steps?
+       └─ Should these be deterministic helper scripts in scripts/?
+       │
+       ▼
+[Branch 6: Progressive Disclosure (< 500 Lines)]
+       ├─ Is SKILL.md under 500 lines?
+       ├─ Are deep manuals offloaded to references/?
+       └─ Are static schemas or templates offloaded to assets/?
+       │
+       ▼
+[Branch 7: Verification & Feedback Loop]
+       ├─ What structured output format proves success?
+       ├─ What self-validation checklist must be satisfied?
+       └─ How will diffs between AI drafts and human edits be harvested?
+```
+
+---
+
+## Inquiry Interview Template
+
+When asking the user or interrogating the workspace, use this questionnaire:
+
+1. **Scope:** Is this workflow continuous (applies whenever writing code in this domain) or episodic (triggered only on explicit request)?
+2. **Triggers:** When should the AI automatically reach for this skill? What tasks should it actively *refuse* to use this skill for?
+3. **Pitfalls:** What has the AI historically messed up when doing this task (e.g. hallucinating dependencies, using wrong flags, creating leaky abstractions)?
+4. **Determinism:** Are there shell commands or formatting rules that should be guaranteed with a script rather than left to LLM chance?
+5. **Output Standard:** What does the ideal, gold-standard output look like?

package/.agents/skills/agentic-architect/references/skill_template.md

@@ -0,0 +1,55 @@
+# Progressive Disclosure Skill Template
+
+Use this template when creating new skills under `.agents/skills/<skill-name>/SKILL.md`.
+
+---
+
+```markdown
+---
+name: <skill-name>
+description: Use when [clear trigger conditions, e.g. implementing authentication, generating emails, running migrations]. Do not use for [explicit boundaries, e.g. general bug fixes or frontend styling].
+---
+
+# [Skill Title]
+
+> **Purpose:** [Brief 1–2 sentence summary of what this skill achieves].
+
+---
+
+## 1. Trigger Conditions
+- When the user explicitly requests: `[Examples]`
+- When performing tasks involving: `[File patterns or domains]`
+- **Do NOT trigger when:** `[Negative conditions]`
+
+---
+
+## 2. Core Workflow Steps
+1. **[Step 1: Discover & Validate]**: Inspect current state before modifying code.
+2. **[Step 2: Execute Core Logic]**: Follow established patterns.
+3. **[Step 3: Self-Check & Verify]**: Run test commands or validation scripts.
+
+---
+
+## 3. Gotchas & What NOT to Do
+- **DO NOT** [Specific common AI mistake #1].
+- **DO NOT** [Specific common AI mistake #2].
+- **DO NOT** [Specific common AI mistake #3].
+
+---
+
+## 4. Structured Output Template
+Provide consistent formatting for results:
+```markdown
+### Summary of Changes
+- **Action**: ...
+- **Files Affected**: ...
+- **Verification Evidence**: ...
+```
+
+---
+
+## 5. Subdirectories & Progressive Resources
+- Deep reference documentation: `references/`
+- Deterministic helper scripts: `scripts/`
+- Static schemas or mock assets: `assets/`
+```

package/.agents/skills/agentic-architect/scripts/validate_agentic_configs.sh

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# validate_agentic_configs.sh
+# Deterministic Validator for Agentic Files, Rules, and Skills
+# ==============================================================================
+
+set -euo pipefail
+
+WORKSPACE_ROOT="${1:-$(pwd)}"
+ERRORS=0
+WARNINGS=0
+
+echo "🔍 Validating Agentic Architecture in: ${WORKSPACE_ROOT}"
+echo "--------------------------------------------------------------"
+
+# Helper print functions
+log_pass() { echo "  ✅ $1"; }
+log_warn() { echo "  ⚠️  $1"; WARNINGS=$((WARNINGS + 1)); }
+log_fail() { echo "  ❌ $1"; ERRORS=$((ERRORS + 1)); }
+
+# 1. Root AGENTS.md & Symlinks Verification
+echo "1. Checking Root Configuration & Symlinks..."
+AGENTS_FILE="${WORKSPACE_ROOT}/AGENTS.md"
+if [[ ! -f "${AGENTS_FILE}" ]]; then
+  log_fail "Missing root AGENTS.md at ${AGENTS_FILE}"
+else
+  log_pass "AGENTS.md exists."
+  
+  LINE_COUNT=$(wc -l < "${AGENTS_FILE}")
+  if [[ ${LINE_COUNT} -le 120 ]]; then
+    log_pass "AGENTS.md line count is lean: ${LINE_COUNT} lines (<= 120)."
+  elif [[ ${LINE_COUNT} -le 150 ]]; then
+    log_warn "AGENTS.md line count is getting large: ${LINE_COUNT} lines (warn > 120)."
+  else
+    log_fail "AGENTS.md exceeds maximum line limit: ${LINE_COUNT} lines (max 150)."
+  fi
+fi
+
+# Check CLAUDE.md symlink
+CLAUDE_FILE="${WORKSPACE_ROOT}/CLAUDE.md"
+if [[ -L "${CLAUDE_FILE}" ]]; then
+  TARGET=$(readlink "${CLAUDE_FILE}")
+  if [[ "${TARGET}" == "AGENTS.md" ]]; then
+    log_pass "CLAUDE.md is a valid symlink to AGENTS.md."
+  else
+    log_fail "CLAUDE.md points to '${TARGET}' instead of 'AGENTS.md'."
+  fi
+else
+  log_fail "CLAUDE.md is not a symbolic link."
+fi
+
+# Check agents.md symlink
+AGENTS_LOWER="${WORKSPACE_ROOT}/agents.md"
+if [[ -L "${AGENTS_LOWER}" ]]; then
+  TARGET=$(readlink "${AGENTS_LOWER}")
+  if [[ "${TARGET}" == "AGENTS.md" ]]; then
+    log_pass "agents.md is a valid symlink to AGENTS.md."
+  else
+    log_fail "agents.md points to '${TARGET}' instead of 'AGENTS.md'."
+  fi
+else
+  log_fail "agents.md is not a symbolic link."
+fi
+
+# 2. Checking Progressive Disclosure Rules (docs/rules)
+echo ""
+echo "2. Checking Progressive Disclosure Rules..."
+RULES_DIR="${WORKSPACE_ROOT}/docs/rules"
+if [[ ! -d "${RULES_DIR}" ]]; then
+  log_fail "Missing docs/rules directory at ${RULES_DIR}"
+else
+  RULE_COUNT=0
+  for rule_file in "${RULES_DIR}"/*.md; do
+    [[ -e "${rule_file}" ]] || continue
+    RULE_COUNT=$((RULE_COUNT + 1))
+    RULE_NAME=$(basename "${rule_file}")
+    
+    # Check for title
+    if ! grep -q "^# " "${rule_file}"; then
+      log_fail "Rule ${RULE_NAME} missing H1 header (# Title)"
+    fi
+    
+    # Check for Core Mandate blockquote
+    if ! grep -q "^> \*\*Core Mandate:\*\*" "${rule_file}"; then
+      log_warn "Rule ${RULE_NAME} missing standardized '> **Core Mandate:**' summary"
+    fi
+  done
+  log_pass "Validated ${RULE_COUNT} modular rule files in docs/rules/."
+fi
+
+# 3. Checking Skills Architecture (.agents/skills)
+echo ""
+echo "3. Checking Specialized Skills (.agents/skills)..."
+SKILLS_DIR="${WORKSPACE_ROOT}/.agents/skills"
+if [[ ! -d "${SKILLS_DIR}" ]]; then
+  log_fail "Missing .agents/skills directory at ${SKILLS_DIR}"
+else
+  SKILL_COUNT=0
+  for skill_folder in "${SKILLS_DIR}"/*; do
+    [[ -d "${skill_folder}" ]] || continue
+    SKILL_NAME=$(basename "${skill_folder}")
+    SKILL_FILE="${skill_folder}/SKILL.md"
+    SKILL_COUNT=$((SKILL_COUNT + 1))
+    
+    if [[ ! -f "${SKILL_FILE}" ]]; then
+      log_fail "Skill '${SKILL_NAME}' missing SKILL.md"
+      continue
+    fi
+    
+    # Check front matter existence
+    if ! head -n 1 "${SKILL_FILE}" | grep -q "^---"; then
+      log_fail "Skill '${SKILL_NAME}' missing opening front matter delimiter (---)"
+      continue
+    fi
+    
+    # Check name field in front matter
+    if ! grep -E "^name:[[:space:]]*${SKILL_NAME}" "${SKILL_FILE}" > /dev/null; then
+      log_fail "Skill '${SKILL_NAME}' front matter 'name:' does not match directory name"
+    fi
+    
+    # Check description
+    DESC=$(grep -E "^description:" "${SKILL_FILE}" | sed -E 's/^description:[[:space:]]*//' || true)
+    if [[ -z "${DESC}" ]]; then
+      log_fail "Skill '${SKILL_NAME}' missing front matter 'description:'"
+    else
+      # Check imperative phrasing
+      if [[ ! "${DESC}" =~ ^Use[[:space:]]when ]]; then
+        log_warn "Skill '${SKILL_NAME}' description should start with imperative 'Use when...'"
+      fi
+      
+      # Check character length (< 1024)
+      CHAR_LEN=${#DESC}
+      if [[ ${CHAR_LEN} -gt 1024 ]]; then
+        log_fail "Skill '${SKILL_NAME}' description exceeds 1024 chars (${CHAR_LEN} chars)"
+      fi
+    fi
+    
+    # Check body length (< 500 lines)
+    SKILL_LINES=$(wc -l < "${SKILL_FILE}")
+    if [[ ${SKILL_LINES} -gt 500 ]]; then
+      log_warn "Skill '${SKILL_NAME}' exceeds 500 lines (${SKILL_LINES} lines). Offload details to references/."
+    else
+      log_pass "Skill '${SKILL_NAME}': ${SKILL_LINES} lines, description valid (${#DESC} chars)."
+    fi
+    
+    # Check for Gotchas / What NOT to do section
+    if ! grep -qi "What NOT to do" "${SKILL_FILE}" && ! grep -qi "Gotchas" "${SKILL_FILE}"; then
+      log_warn "Skill '${SKILL_NAME}' missing mandatory 'Gotchas & What NOT to Do' section"
+    fi
+  done
+  log_pass "Validated ${SKILL_COUNT} skills in .agents/skills/."
+fi
+
+# 4. Summary Output
+echo ""
+echo "--------------------------------------------------------------"
+if [[ ${ERRORS} -eq 0 ]]; then
+  echo "🎉 SUCCESS: All agentic configurations are valid and healthy! (${WARNINGS} warnings)"
+  exit 0
+else
+  echo "🚨 FAILURE: Found ${ERRORS} error(s) and ${WARNINGS} warning(s) in agentic configurations."
+  exit 1
+fi

package/.agents/skills/clean-code-refactor/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: clean-code-refactor
+description: Use when refactoring existing code to comply with Clean Code, SOLID principles, Pragmatic Programmer practices, or modern design patterns (Strategy, Adapter, Repository, Result pattern). Do not use when merely creating a new feature from scratch, fixing a minor typo, or writing initial tests.
+---
+
+# Clean Code & Design Patterns Refactoring Skill
+
+> **Core Purpose:** Transform messy, coupled, or rigid code into clean, expressive, and maintainable TypeScript implementations adhering to Robert C. Martin's Clean Code, The Pragmatic Programmer, and modern Gang of Four patterns without altering external behavior.
+
+---
+
+## 1. When to Use This Skill
+- During the **REFACTOR** stage of the Outside-In TDD double loop (after tests are green).
+- Resolving code smells: long functions (> 30 lines), large classes, excessive parameter lists (> 3 args), primitive obsession, duplicate domain knowledge.
+- Decoupling 3rd-party dependencies using the **Adapter Pattern**.
+- Replacing complex conditional logic (`switch`/`if-else` cascades) with the **Strategy Pattern**.
+- Eliminating untyped exception throwing with the **Result / Either Pattern**.
+- Removing dead or commented-out code to restore readability.
+
+---
+
+## 2. Step-by-Step Refactoring Workflow
+
+```
+1. Verify Green Tests ──► 2. Identify Code Smells ──► 3. Select Design Pattern ──► 4. Atomic Surgical Edit ──► 5. Verify 100% Green
+```
+
+### Step 1: Establish the Test Safety Net
+- Never refactor without passing tests.
+- Confirm all existing unit and acceptance tests pass: `npm run test` or `npm run coverage`.
+- If coverage is missing or incomplete, write tests *before* touching production code.
+
+### Step 2: Identify Specific Code Smells
+Target concrete flaws:
+- **Long Method / Violating Single Responsibility**: Extract smaller private helper functions (SLAP principle).
+- **Coupling to 3rd-Party SDK**: Wrap SDK calls inside an application-owned interface (Adapter pattern).
+- **Duplicated Domain Rules**: Consolidate business logic into a single authoritative value object or service (DRY).
+- **Leaky Exceptions**: Convert error throwing across controller/service boundaries into typed `Result<T, E>` unions.
+
+### Step 3: Apply the Appropriate Pattern
+- **Adapter**: Define an interface `IEmailAdapter` or `IPaymentAdapter`. Create an implementation wrapping the open-source library.
+- **Strategy**: Define a strategy interface `ITenantPolicy`. Inject the appropriate strategy based on tenant configuration.
+- **Factory**: Centralize instantiation of complex collaborator graphs.
+- **Repository / Data Mapper**: Decouple domain entities from direct ORM queries.
+
+### Step 4: Execute Atomic Surgical Edits
+- Make one micro-refactor at a time (e.g. rename a method, extract a class).
+- Maintain existing naming conventions and strict TypeScript types.
+- Ensure zero lint or type errors: `npm run lint && npm run typecheck`.
+
+### Step 5: Verify Continuous Green State
+- Run tests after every single atomic change: `npm run coverage`.
+- Ensure coverage remains at **100.00%**.
+
+---
+
+## 3. Gotchas & What NOT to Do
+
+- **DO NOT** change external functional behavior while refactoring. Refactoring is strictly structural.
+- **DO NOT** refactor without automated tests. A green test suite is non-negotiable.
+- **DO NOT** introduce over-engineering or speculative design patterns for simple, stable code (YAGNI).
+- **DO NOT** mock external 3rd-party types directly in tests; always mock application-owned adapter interfaces.
+- **DO NOT** leave commented-out blocks of old code behind. Clean up completely.
+
+---
+
+## 4. Structured Output Template
+
+```markdown
+### Clean Code Refactoring Summary: [Module / Class Name]
+
+1. **Code Smells Identified**:
+   - [Smell 1: e.g. Long method in UserController violating Single Responsibility]
+   - [Smell 2: e.g. Direct coupling to external Stripe SDK in domain service]
+
+2. **Refactoring Steps & Patterns Applied**:
+   - Applied **Adapter Pattern**: Extracted `IPaymentAdapter` to isolate Stripe SDK.
+   - Applied **SLAP & Extract Function**: Decomposed 60-line handler into three 15-line functions.
+   - Applied **Result Pattern**: Replaced generic `throw Error` with typed `Result<Order, OrderError>`.
+
+3. **Verification Evidence**:
+   - Tests Status: PASS (100.00% statement, branch, and function coverage preserved)
+   - Linter Status: PASS (0 ESLint warnings)
+   - Typecheck: PASS (0 TypeScript errors)
+```
+
+---
+
+## 5. Subdirectories & Progressive Resources
+- [references/clean_code_smells.md](./references/clean_code_smells.md): Catalog of code smells and their refactoring cures.
+- [references/design_patterns_ts.md](./references/design_patterns_ts.md): Production TypeScript implementations of Adapter, Strategy, and Result patterns.

package/.agents/skills/clean-code-refactor/references/clean_code_smells.md

@@ -0,0 +1,27 @@
+# Code Smells & Refactoring Cures Reference
+
+Catalog of common code smells and their remedies in modern TypeScript codebases.
+
+---
+
+## 1. Bloated Functions (> 25–30 Lines)
+- **Smell**: A single function performs input parsing, business calculation, database persistence, and response formatting.
+- **Cure**: Apply *Extract Function* and *Single Level of Abstraction (SLAP)*. Group lower-level details into descriptive helper functions.
+
+---
+
+## 2. Deep Conditional Nesting (Arrow Anti-Pattern)
+- **Smell**: 3+ levels of nested `if / else` blocks checking permissions, status, and input validity.
+- **Cure**: Apply *Guard Clauses* (Return Early) or the *Strategy Pattern* for polymorphic behavior.
+
+---
+
+## 3. Direct 3rd-Party Coupling
+- **Smell**: Domain controllers directly importing external SDKs (e.g. `import Stripe from 'stripe'`).
+- **Cure**: Apply the *Adapter Pattern*. Define an interface `IPaymentGateway` owned by the domain. Create an infrastructure adapter implementing the interface.
+
+---
+
+## 4. Primitive Obsession & Long Parameter Lists (> 3 Parameters)
+- **Smell**: Methods taking 6 primitive strings and numbers (`createUser(first, last, email, role, phone, tenantId)`).
+- **Cure**: Bundle related fields into a strongly typed DTO or Zod schema (`CreateUserInput`).

package/.agents/skills/clean-code-refactor/references/design_patterns_ts.md

@@ -0,0 +1,65 @@
+# Modern Design Patterns in TypeScript Reference
+
+Production implementations of essential design patterns in full-stack TypeScript.
+
+---
+
+## 1. Adapter Pattern (Dependency Isolation)
+
+```typescript
+// 1. Domain Interface (Owned by the application)
+export interface IEmailAdapter {
+  send(to: string, subject: string, html: string): Promise<Result<void, Error>>;
+}
+
+// 2. Open-Source Infrastructure Implementation (e.g. Mailpit/Nodemailer)
+export class NodemailerEmailAdapter implements IEmailAdapter {
+  constructor(private readonly transporter: nodemailer.Transporter) {}
+
+  async send(to: string, subject: string, html: string): Promise<Result<void, Error>> {
+    try {
+      await this.transporter.sendMail({ to, subject, html });
+      return { success: true, value: undefined };
+    } catch (error) {
+      return { success: false, error: error as Error };
+    }
+  }
+}
+```
+
+---
+
+## 2. Strategy Pattern (Runtime Policy Swapping)
+
+```typescript
+// 1. Strategy Contract
+export interface ITenantPricingStrategy {
+  calculateMonthlyRate(activeSeats: number): number;
+}
+
+// 2. Concrete Strategies
+export class StandardPricingStrategy implements ITenantPricingStrategy {
+  calculateMonthlyRate(activeSeats: number): number {
+    return activeSeats * 15;
+  }
+}
+
+export class EnterprisePricingStrategy implements ITenantPricingStrategy {
+  calculateMonthlyRate(activeSeats: number): number {
+    return activeSeats * 10 + 500; // Flat base fee
+  }
+}
+```
+
+---
+
+## 3. Result / Either Pattern (Type-Safe Errors)
+
+```typescript
+export type Result<T, E = Error> =
+  | { success: true; value: T }
+  | { success: false; error: E };
+
+export const Ok = <T>(value: T): Result<T, never> => ({ success: true, value });
+export const Err = <E>(error: E): Result<never, E> => ({ success: false, error });
+```