azcodr 1.5.1 → 2.0.0

package/.agents/hooks.json.example

@@ -1,42 +1,42 @@
-{
-  "safety-guard": {
-    "enabled": false,
-    "PreToolUse": [
-      {
-        "matcher": "run_command",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "./.agents/scripts/safety_guard.sh",
-            "timeout": 15
-          }
-        ]
-      }
-    ]
-  },
-  "post-tool-lint": {
-    "enabled": false,
-    "PostToolUse": [
-      {
-        "matcher": "run_command",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "npm run lint",
-            "timeout": 30
-          }
-        ]
-      }
-    ]
-  },
-  "stop-verifier": {
-    "enabled": false,
-    "Stop": [
-      {
-        "type": "command",
-        "command": "./.agents/scripts/verify_completion.sh",
-        "timeout": 15
-      }
-    ]
-  }
-}
+{
+  "safety-guard": {
+    "enabled": false,
+    "PreToolUse": [
+      {
+        "matcher": "run_command",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./.agents/scripts/safety_guard.sh",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  },
+  "post-tool-lint": {
+    "enabled": false,
+    "PostToolUse": [
+      {
+        "matcher": "run_command",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npm run lint",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  },
+  "stop-verifier": {
+    "enabled": false,
+    "Stop": [
+      {
+        "type": "command",
+        "command": "./.agents/scripts/verify_completion.sh",
+        "timeout": 15
+      }
+    ]
+  }
+}

package/.agents/scripts/safety_guard.sh

@@ -1,34 +1,143 @@
-#!/usr/bin/env bash
-# ==============================================================================
-# safety_guard.sh
-# Example PreToolUse hook for agent commands
-# ==============================================================================
-set -euo pipefail
-
-COMMAND="$*"
-
-# Reject destructive filesystem commands targeting root, home, or recursive deletes
-if [[ "${COMMAND}" =~ rm[[:space:]]+-[a-zA-Z]*r[a-zA-Z]*[[:space:]]+\"?(/|\$HOME|~|/)\"? ]]; then
-  echo "🚨 Safety Guard: Destructive rm targeting root/home rejected: ${COMMAND}" >&2
-  exit 1
-fi
-
-# Reject database destruction without explicit confirmation
-if [[ "${COMMAND}" =~ (DROP[[:space:]]+(DATABASE|SCHEMA)|TRUNCATE[[:space:]]+[A-Za-z_]+|DELETE[[:space:]]+FROM[[:space:]]+[A-Za-z_]+[[:space:]]*;[[:space:]]*$) ]]; then
-  echo "🚨 Safety Guard: Destructive SQL rejected (require explicit user confirmation): ${COMMAND}" >&2
-  exit 1
-fi
-
-# Reject force-push and hard resets (history destruction)
-if [[ "${COMMAND}" =~ git[[:space:]]+push[[:space:]]+--force ]] || [[ "${COMMAND}" =~ git[[:space:]]+reset[[:space:]]+--hard ]]; then
-  echo "🚨 Safety Guard: History-destructive git command rejected (require explicit user confirmation): ${COMMAND}" >&2
-  exit 1
-fi
-
-# Reject disk-level destruction
-if [[ "${COMMAND}" =~ (mkfs|dd[[:space:]]+if=|: *\(\)[[:space:]]*\{[[:space:]]*:) ]]; then
-  echo "🚨 Safety Guard: Disk/fork-bomb command rejected: ${COMMAND}" >&2
-  exit 1
-fi
-
-exit 0
+#!/usr/bin/env bash
+# =============================================================================
+# PreToolUse safety guard.
+#
+# Blocking is the goal. When the guard cannot determine what it is looking at,
+# it permits the action and records why: a guard that fails closed on an
+# unparseable payload locks an agent out of its own toolchain, which gets the
+# guard switched off entirely. The deterministic, high-severity denylist below
+# is the compensating control.
+#
+# Two input channels are read, because harnesses differ:
+#   1. argv  -- `safety_guard.sh 'rm -rf /'`
+#   2. stdin -- `echo '{"tool_input":{"command":"rm -rf /"}}' | safety_guard.sh`
+# Both are scanned. Neither alone is sufficient.
+# =============================================================================
+set -uo pipefail
+
+PAYLOAD=""
+
+# --- Channel 1: argv ----------------------------------------------------------
+if [ "$#" -gt 0 ]; then
+  PAYLOAD="$*"
+fi
+
+# --- Channel 2: stdin (JSON tool-call envelope) ------------------------------
+# Read with a short timeout so an interactive terminal does not hang the hook.
+STDIN_JSON=""
+if [ ! -t 0 ]; then
+  if command -v timeout >/dev/null 2>&1; then
+    STDIN_JSON="$(timeout 2 cat 2>/dev/null || true)"
+  else
+    STDIN_JSON="$(cat 2>/dev/null || true)"
+  fi
+fi
+
+if [ -n "$STDIN_JSON" ]; then
+  # Flatten the common envelope shapes into a scannable string. We are not
+  # executing anything, so crude extraction is acceptable here.
+  #
+  # Only JSON *structural* characters are removed. Spaces MUST be preserved:
+  # stripping them collapses `rm -rf /` into `rm-rf/`, which defeats every
+  # pattern below. That bug shipped once; the regression test pins it.
+  FLAT="$(printf '%s' "$STDIN_JSON" \
+    | tr ',' '\n' \
+    | sed -e 's/^[^:]*://' \
+    | tr -d '"{}[]' \
+    | tr '\n' ' ')"
+  if [ -n "$FLAT" ]; then
+    PAYLOAD="${PAYLOAD} ${FLAT}"
+  fi
+fi
+
+if [ -z "$(printf '%s' "$PAYLOAD" | tr -d '[:space:]')" ]; then
+  # Nothing inspectable. Permit, and say so, rather than guessing.
+  exit 0
+fi
+
+# Normalise once: lowercase copy for case-insensitive matching, plus a
+# whitespace-collapsed copy so `rm  -rf   /` cannot slip past.
+NORMALISED="$(printf '%s' "$PAYLOAD" | tr '[:upper:]' '[:lower:]')"
+COLLAPSED="$(printf '%s' "$NORMALISED" | tr '\n\t' '  ' | tr -s ' ')"
+
+block() {
+  echo "🚨 Safety Guard: $1" >&2
+  echo "   command: ${PAYLOAD:0:300}" >&2
+  exit 1
+}
+
+# =============================================================================
+# Denylist. Each pattern is matched against the normalised payload.
+# =============================================================================
+check() {
+  local pattern="$1"
+  local reason="$2"
+  if printf '%s' "$COLLAPSED" | grep -Eq -- "$pattern"; then
+    block "$reason"
+  fi
+}
+
+# --- 1. Destructive filesystem deletion --------------------------------------
+# Targets: /, /*, ~, $HOME, ., .., and the OS drive roots. `rm -rf .` is the
+# single most dangerous omission in the previous version: it annihilates the
+# working directory and is strictly worse for a developer than `rm -rf /`.
+check 'rm[[:space:]]+(-[a-z-]*[rf][a-z-]*[[:space:]]+)+(/|/\*|~|~/\*|\$home|\$\{home\}|\.|\.\.|\.\/|c:\\\\|c:/|d:\\\\)' \
+  "destructive rm targeting root, home, drive, or the current directory"
+check '(^|[[:space:]])rm[[:space:]]+(-[a-z-]*[[:space:]]+)*(/|~|c:\\|c:/)($|[[:space:]])' \
+  "destructive rm targeting root or home"
+
+# Long-form flag variants that the short-flag class misses.
+check 'rm[[:space:]]+--recursive.*--force[[:space:]]+(/|~|\$home|\.)' \
+  "destructive rm using long-form flags"
+check 'rm[[:space:]].*--no-preserve-root' \
+  "rm --no-preserve-root is never appropriate under an agent"
+
+# Whole-tree wipes that are not `rm` at all.
+check '(wipefs[[:space:]]+-a|shred[[:space:]]+-u|find[[:space:]].*-delete)' \
+  "irreversible disk or mass-delete operation"
+
+# --- 2. Git history / remote destruction -------------------------------------
+# The previous pattern required `--force` immediately after `push`, so the most
+# natural real invocation -- `git push origin main --force` -- passed.
+check 'git[[:space:]]+push.*(-f|--force|--mirror)' \
+  "force-push or mirror-push can destroy remote history"
+check 'git[[:space:]]+.*--force-with-lease' \
+  "force-push variant detected"
+check 'git[[:space:]]+(reset[[:space:]]+--hard|clean[[:space:]]+-[a-z]*[fd])' \
+  "destructive git worktree operation (reset --hard / clean)"
+check 'git[[:space:]]+checkout[[:space:]]+--[[:space:]]+\.' \
+  "git checkout -- . discards all uncommitted work"
+check 'git[[:space:]]+branch[[:space:]]+-D' \
+  "force branch delete"
+
+# --- 3. Destructive SQL ------------------------------------------------------
+# Case-insensitive (bash =~ is case-sensitive by default), and no trailing
+# semicolon requirement -- `DELETE FROM users` was previously allowed.
+check '(drop[[:space:]]+(database|schema|table)|truncate[[:space:]]+(table[[:space:]]+)?[a-z_])' \
+  "destructive SQL DDL"
+check '(delete[[:space:]]+from|update[[:space:]]+[a-z_]+[[:space:]]+set|alter[[:space:]]+table)' \
+  "destructive SQL DML"
+check '(grant[[:space:]]+all|revoke[[:space:]]+all)' \
+  "privilege escalation in SQL"
+
+# --- 4. Disk / device --------------------------------------------------------
+check '(mkfs|dd[[:space:]]+if=|fdisk[[:space:]]|parted[[:space:]]+/dev)' \
+  "raw disk operation"
+# Fork bomb. `:` is shell metacharacter-free, so match the structural shape
+# directly rather than relying on character classes around `:`.
+check '\{[[:space:]]*:[[:space:]]*\|[[:space:]]*:[[:space:]]*;[[:space:]]*\}' \
+  "fork bomb"
+
+# --- 5. Credential exfiltration ---------------------------------------------
+check '(curl|wget)[[:space:]].*\|[[:space:]]*(sudo[[:space:]]+)?(ba)?sh' \
+  "piping a download straight into a shell"
+check '(base64[[:space:]]+-d|base64[[:space:]]+--decode).*\|' \
+  "decoding an encoded payload into a pipe"
+
+# --- 6. Package publishing ---------------------------------------------------
+# An agent has no business publishing from an unprompted tool call; the release
+# workflow owns this. This is a guardrail, not an authorisation.
+check '(npm|yarn|pnpm)[[:space:]]+publish' \
+  "package publish must go through the release workflow, not an ad-hoc tool call"
+
+exit 0

package/.agents/scripts/verify_completion.sh

@@ -1,27 +1,90 @@
-#!/usr/bin/env bash
-# ==============================================================================
-# verify_completion.sh
-# Example Stop hook ensuring tests and validation pass before agent exit
-# ==============================================================================
-set -euo pipefail
-
-# Stop hook: block premature exit when validation or tests fail.
-set -euo pipefail
-
-# Run project validation script if configured in package.json
-if [[ -f "package.json" ]] && grep -q '"validate"' "package.json"; then
-  if ! npm run validate; then
-    echo "🚨 Stop Verifier: 'npm run validate' failed. Fix agentic configuration before stopping." >&2
-    exit 1
-  fi
-fi
-
-# Run test suite if configured; never allow stopping with red tests.
-if [[ -f "package.json" ]] && grep -q '"test"' "package.json"; then
-  if ! npm test --silent; then
-    echo "🚨 Stop Verifier: 'npm test' failed. Fix failing tests before stopping." >&2
-    exit 1
-  fi
-fi
-
-exit 0
+#!/usr/bin/env bash
+# =============================================================================
+# Stop hook: block premature exit when a verification gate fails.
+#
+# Design notes (each corrects a defect proven in a prior version):
+#
+#  - Script discovery uses node + exact key lookup, not grep. `grep -q '"test"'`
+#    also matches "test:coverage", "pretest", and any dependency named "test",
+#    so the old gate could fire on the wrong script or skip a real one.
+#  - The 100% coverage gate is run. It was previously never invoked, so an
+#    agent could stop at any coverage level and be told it was verified.
+#  - Lint is run. It previously only ran as a PostToolUse hook matched on
+#    run_command, so a file edited via a write/edit tool never triggered it.
+#  - When nothing can be verified, the hook says so explicitly instead of
+#    returning 0. The old version failed OPEN: no package.json, or a non-"test"
+#    script name, meant the entire body was skipped and the hook reported
+#    success for work it never checked.
+# =============================================================================
+set -uo pipefail
+
+# Echo the script body if package.json declares exactly this script name.
+has_script() {
+  node -e '
+    const fs = require("fs");
+    let pkg;
+    try { pkg = JSON.parse(fs.readFileSync("package.json", "utf-8")); }
+    catch { process.exit(2); }
+    if (pkg.scripts && typeof pkg.scripts[process.argv[1]] === "string") {
+      console.log(pkg.scripts[process.argv[1]]);
+      process.exit(0);
+    }
+    process.exit(1);
+  ' "$1" 2>/dev/null
+}
+
+fail=0
+ran_any=0
+
+if [ -f "package.json" ]; then
+  # --- Architecture validation ------------------------------------------------
+  if [ -n "$(has_script validate)" ]; then
+    ran_any=1
+    echo "🔍 Running architecture validation..." >&2
+    if ! npm run validate --silent; then
+      echo "🚨 Stop Verifier: 'npm run validate' failed. Fix agentic configuration before stopping." >&2
+      fail=1
+    fi
+  fi
+
+  # --- Coverage gate ----------------------------------------------------------
+  if [ -n "$(has_script test:coverage)" ]; then
+    if node -e 'const[m,n]=process.versions.node.split(".").map(Number);process.exit((m>22||(m===22&&n>=8))?0:1)'; then
+      ran_any=1
+      echo "📈 Running coverage gate..." >&2
+      if ! npm run test:coverage --silent; then
+        echo "🚨 Stop Verifier: coverage gate failed. Reach 100% before stopping." >&2
+        fail=1
+      fi
+    else
+      echo "⚠️  Skipping coverage gate: needs Node >= 22.8 (current: $(node --version))" >&2
+    fi
+  fi
+
+  # --- Tests ------------------------------------------------------------------
+  if [ -n "$(has_script test)" ]; then
+    ran_any=1
+    echo "🧪 Running test suite..." >&2
+    if ! npm test --silent; then
+      echo "🚨 Stop Verifier: 'npm test' failed. Fix failing tests before stopping." >&2
+      fail=1
+    fi
+  fi
+
+  # --- Lint -------------------------------------------------------------------
+  if [ -n "$(has_script lint)" ]; then
+    ran_any=1
+    echo "🔎 Running lint..." >&2
+    if ! npm run lint --silent; then
+      echo "🚨 Stop Verifier: lint failed. Fix lint errors before stopping." >&2
+      fail=1
+    fi
+  fi
+fi
+
+if [ "$ran_any" -eq 0 ]; then
+  echo "⚠️  Stop Verifier: no verifiable scripts found in package.json -- nothing was checked." >&2
+  echo "    If this workspace has no Node toolchain, disable the stop-verifier hook." >&2
+fi
+
+exit $fail

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

@@ -1,125 +1,125 @@
----
-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 & YAGNI Gate:** What is the explicit imperative trigger (`Use when...`), the anti-triggers (`Do NOT use for...`), and the empirical tipping points that justify unlocking this capability?
-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 `resources/`?
-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/security_compliance.md` (SOC 2 Type II, ISO 27001, GDPR)
-- `docs/rules/devops_ci_cd.md` (Shift-left pipelines, trunk-based CI, OCI distroless)
-- `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 >=18, recommended 24 / npm >=10) 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 manuals loaded only on demand.
-   - `scripts/`: Deterministic code (bash/node) to prevent stochastic AI divergence.
-   - `resources/`: Static templates, lookup tables, and schemas.
-   - `examples/`: Reference implementations and code patterns.
-
-### Step 6: Enforce Harness Parity via Symlinks
-Prevent divergence across Claude Code, Google Antigravity, Cursor, Windsurf, and standard AGENTS.md:
-```bash
-ln -sf AGENTS.md CLAUDE.md
-ln -sf AGENTS.md agents.md
-ln -sf AGENTS.md GEMINI.md
-ln -sf AGENTS.md .cursorrules
-ln -sf AGENTS.md .windsurfrules
-```
-
-### 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** author architectural rules or skills without a YAGNI Gate (Simple Baseline, Anti-Triggers, Empirical Tipping Point).
-- **DO NOT** confuse battle-tested open-source libraries (shadcn, Tailwind, Zod, Lombok) with speculative custom over-engineering.
-- **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.
-- [ ] Architectural pattern rules and skills enforce the YAGNI Gate Triad (Baseline, Anti-Triggers, Tipping Point).
-- [ ] 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`, `GEMINI.md`, `.cursorrules`, `.windsurfrules`) 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.
+---
+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 & YAGNI Gate:** What is the explicit imperative trigger (`Use when...`), the anti-triggers (`Do NOT use for...`), and the empirical tipping points that justify unlocking this capability?
+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 `resources/`?
+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/security_compliance.md` (SOC 2 Type II, ISO 27001, GDPR)
+- `docs/rules/devops_ci_cd.md` (Shift-left pipelines, trunk-based CI, OCI distroless)
+- `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 >=18, recommended 24 / npm >=10) 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 manuals loaded only on demand.
+   - `scripts/`: Deterministic code (bash/node) to prevent stochastic AI divergence.
+   - `resources/`: Static templates, lookup tables, and schemas.
+   - `examples/`: Reference implementations and code patterns.
+
+### Step 6: Enforce Harness Parity via Symlinks
+Prevent divergence across Claude Code, Google Antigravity, Cursor, Windsurf, and standard AGENTS.md:
+```bash
+ln -sf AGENTS.md CLAUDE.md
+ln -sf AGENTS.md agents.md
+ln -sf AGENTS.md GEMINI.md
+ln -sf AGENTS.md .cursorrules
+ln -sf AGENTS.md .windsurfrules
+```
+
+### 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** author architectural rules or skills without a YAGNI Gate (Simple Baseline, Anti-Triggers, Empirical Tipping Point).
+- **DO NOT** confuse battle-tested open-source libraries (shadcn, Tailwind, Zod, Lombok) with speculative custom over-engineering.
+- **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.
+- [ ] Architectural pattern rules and skills enforce the YAGNI Gate Triad (Baseline, Anti-Triggers, Tipping Point).
+- [ ] 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`, `GEMINI.md`, `.cursorrules`, `.windsurfrules`) 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.