azcodr 1.3.0 → 1.5.0

package/.agents/hooks.json.example

@@ -0,0 +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
+      }
+    ]
+  }
+}

package/.agents/mcp_config.json.example

@@ -0,0 +1,24 @@
+{
+  "mcpServers": {
+    "sqlite": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-sqlite",
+        "--db-path",
+        "./data/app.db"
+      ]
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "./docs"
+      ]
+    },
+    "remote-service": {
+      "serverUrl": "https://mcp.example.com/sse"
+    }
+  }
+}

package/.agents/scripts/safety_guard.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# safety_guard.sh
+# Example PreToolUse hook for agent commands
+# ==============================================================================
+set -euo pipefail
+
+COMMAND="${1:-}"
+
+# Reject destructive system commands targeting root or home
+if [[ "${COMMAND}" =~ (rm[[:space:]]+-[rf]{1,2}[[:space:]]+(/|\$HOME|~)) ]]; then
+  echo "🚨 Safety Guard: Destructive command rejected: ${COMMAND}" >&2
+  exit 1
+fi
+
+exit 0

package/.agents/scripts/verify_completion.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# verify_completion.sh
+# Example Stop hook ensuring tests and validation pass before agent exit
+# ==============================================================================
+set -euo pipefail
+
+# Run project validation script if configured in package.json
+if [[ -f "package.json" ]] && grep -q '"validate"' "package.json"; then
+  npm run validate
+fi
+
+exit 0

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

@@ -23,11 +23,11 @@ description: Use when creating, modularizing, auditing, or updating agentic conf
 ### 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...`)?
+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 `assets/`?
+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.
 
@@ -43,8 +43,8 @@ Inspect current agent files and measure their token and line footprint:
 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/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
@@ -65,15 +65,19 @@ When a task is complex, multi-step, or specialized, encapsulate it into `.agents
    - Include a mandatory **"Gotchas & What NOT to Do"** section.
    - Provide structured output templates.
 3. **Progressive Subdirectories:**
-   - `references/`: Reference docs loaded only on demand.
+   - `references/`: Reference manuals loaded only on demand.
    - `scripts/`: Deterministic code (bash/node) to prevent stochastic AI divergence.
-   - `assets/`: Static templates, lookup tables, and schemas.
+   - `resources/`: Static templates, lookup tables, and schemas.
+   - `examples/`: Reference implementations and code patterns.
 
 ### Step 6: Enforce Harness Parity via Symlinks
-Prevent divergence between Claude Code, standard AGENTS.md, and legacy tooling:
+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
@@ -87,6 +91,8 @@ ln -sf AGENTS.md agents.md
 ## 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.
@@ -100,13 +106,14 @@ ln -sf AGENTS.md agents.md
 
 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`) resolve to `AGENTS.md`.
+- [ ] Symlinks (`CLAUDE.md`, `agents.md`, `GEMINI.md`, `.cursorrules`, `.windsurfrules`) resolve to `AGENTS.md`.
 
 ---
 

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

@@ -45,15 +45,18 @@ 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. |
+| **Multi-Tenancy** | [docs/rules/multitenancy_architecture.md](../../../../docs/rules/multitenancy_architecture.md) | Tenant context resolution, PostgreSQL RLS. |
+| **Database** | [docs/rules/database_design.md](../../../../docs/rules/database_design.md) | Relational integrity, ACID transactions, outbox pattern. |
 
 ---
 
 ## 4. Harness Parity
-Keep `AGENTS.md`, `CLAUDE.md`, and `agents.md` in sync via filesystem symlinks:
+Keep `AGENTS.md`, `CLAUDE.md`, `agents.md`, `GEMINI.md`, `.cursorrules`, and `.windsurfrules` in sync via filesystem symlinks:
 ```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
 ```
 ```

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

@@ -41,7 +41,7 @@
 [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/?
+       └─ Are static schemas or templates offloaded to resources/?
        │
        ▼
 [Branch 7: Verification & Feedback Loop]

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

@@ -51,5 +51,6 @@ Provide consistent formatting for results:
 ## 5. Subdirectories & Progressive Resources
 - Deep reference documentation: `references/`
 - Deterministic helper scripts: `scripts/`
-- Static schemas or mock assets: `assets/`
+- Static schemas, templates, or mock data: `resources/`
+- Reference implementations and patterns: `examples/`
 ```

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

@@ -6,7 +6,21 @@
 
 set -euo pipefail
 
-WORKSPACE_ROOT="${1:-$(pwd)}"
+WORKSPACE_ROOT=""
+FIX_MODE=false
+
+for arg in "$@"; do
+  if [[ "${arg}" == "--fix" ]]; then
+    FIX_MODE=true
+  elif [[ -z "${WORKSPACE_ROOT}" ]]; then
+    WORKSPACE_ROOT="${arg}"
+  fi
+done
+
+if [[ -z "${WORKSPACE_ROOT}" ]]; then
+  WORKSPACE_ROOT="$(pwd)"
+fi
+
 ERRORS=0
 WARNINGS=0
 
@@ -36,16 +50,29 @@ else
   fi
 fi
 
+# Helper to check if symlink target resolves to AGENTS.md
+is_valid_agents_target() {
+  local target="$1"
+  [[ "${target}" == "AGENTS.md" || "${target}" == "./AGENTS.md" || "${target}" == "${WORKSPACE_ROOT}/AGENTS.md" ]]
+}
+
+is_valid_text_pointer() {
+  local file="$1"
+  local content
+  content=$(< "${file}")
+  [[ "${content}" == "AGENTS.md" || "${content}" == "./AGENTS.md" || "${content}" == "${WORKSPACE_ROOT}/AGENTS.md" ]]
+}
+
 # Check CLAUDE.md symlink
 CLAUDE_FILE="${WORKSPACE_ROOT}/CLAUDE.md"
 if [[ -L "${CLAUDE_FILE}" ]]; then
   TARGET=$(readlink "${CLAUDE_FILE}")
-  if [[ "${TARGET}" == "AGENTS.md" ]]; then
+  if is_valid_agents_target "${TARGET}"; 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
-elif [[ -f "${CLAUDE_FILE}" ]] && [[ "$(< "${CLAUDE_FILE}")" == "AGENTS.md" ]]; then
+elif [[ -f "${CLAUDE_FILE}" ]] && is_valid_text_pointer "${CLAUDE_FILE}"; then
   log_pass "CLAUDE.md is a text pointer to AGENTS.md (symlink fallback)."
 else
   log_fail "CLAUDE.md is not a symbolic link."
@@ -64,20 +91,99 @@ if [[ "${IS_CASE_INSENSITIVE}" == "true" ]]; then
   log_pass "agents.md is satisfied natively by AGENTS.md (case-insensitive filesystem)."
 else
   if [[ ! -L "${AGENTS_LOWER}" ]] && [[ ! -e "${AGENTS_LOWER}" ]] && [[ -f "${AGENTS_FILE}" ]]; then
-    ln -sf "AGENTS.md" "${AGENTS_LOWER}"
+    if [[ "${FIX_MODE}" == "true" ]]; then
+      ln -sf "AGENTS.md" "${AGENTS_LOWER}"
+      log_pass "Created agents.md symlink to AGENTS.md (--fix mode)."
+    else
+      log_fail "agents.md is missing. Run with --fix to automatically repair symlinks."
+    fi
   fi
   if [[ -L "${AGENTS_LOWER}" ]]; then
     TARGET=$(readlink "${AGENTS_LOWER}")
-    if [[ "${TARGET}" == "AGENTS.md" ]]; then
+    if is_valid_agents_target "${TARGET}"; 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
+  elif [[ -f "${AGENTS_LOWER}" ]] && is_valid_text_pointer "${AGENTS_LOWER}"; then
+    log_pass "agents.md is a text pointer to AGENTS.md (symlink fallback)."
+  elif [[ ! -e "${AGENTS_LOWER}" ]] && [[ "${FIX_MODE}" == "true" ]]; then
+    : # Handled above
   else
     log_fail "agents.md is not a symbolic link."
   fi
 fi
 
+# Check GEMINI.md symlink
+GEMINI_FILE="${WORKSPACE_ROOT}/GEMINI.md"
+if [[ -L "${GEMINI_FILE}" ]]; then
+  TARGET=$(readlink "${GEMINI_FILE}")
+  if is_valid_agents_target "${TARGET}"; then
+    log_pass "GEMINI.md is a valid symlink to AGENTS.md."
+  else
+    log_fail "GEMINI.md points to '${TARGET}' instead of 'AGENTS.md'."
+  fi
+elif [[ -f "${GEMINI_FILE}" ]] && is_valid_text_pointer "${GEMINI_FILE}"; then
+  log_pass "GEMINI.md is a text pointer to AGENTS.md (symlink fallback)."
+else
+  log_fail "GEMINI.md is not a symbolic link."
+fi
+
+# Check .cursorrules symlink
+CURSOR_FILE="${WORKSPACE_ROOT}/.cursorrules"
+if [[ -L "${CURSOR_FILE}" ]]; then
+  TARGET=$(readlink "${CURSOR_FILE}")
+  if is_valid_agents_target "${TARGET}"; then
+    log_pass ".cursorrules is a valid symlink to AGENTS.md."
+  else
+    log_fail ".cursorrules points to '${TARGET}' instead of 'AGENTS.md'."
+  fi
+elif [[ -f "${CURSOR_FILE}" ]] && is_valid_text_pointer "${CURSOR_FILE}"; then
+  log_pass ".cursorrules is a text pointer to AGENTS.md (symlink fallback)."
+else
+  log_fail ".cursorrules is not a symbolic link."
+fi
+
+# Check .windsurfrules symlink
+WINDSURF_FILE="${WORKSPACE_ROOT}/.windsurfrules"
+if [[ -L "${WINDSURF_FILE}" ]]; then
+  TARGET=$(readlink "${WINDSURF_FILE}")
+  if is_valid_agents_target "${TARGET}"; then
+    log_pass ".windsurfrules is a valid symlink to AGENTS.md."
+  else
+    log_fail ".windsurfrules points to '${TARGET}' instead of 'AGENTS.md'."
+  fi
+elif [[ -f "${WINDSURF_FILE}" ]] && is_valid_text_pointer "${WINDSURF_FILE}"; then
+  log_pass ".windsurfrules is a text pointer to AGENTS.md (symlink fallback)."
+else
+  log_fail ".windsurfrules is not a symbolic link."
+fi
+
+# Check .github/copilot-instructions.md symlink (if .github directory exists)
+COPILOT_FILE="${WORKSPACE_ROOT}/.github/copilot-instructions.md"
+if [[ -d "${WORKSPACE_ROOT}/.github" ]]; then
+  if [[ -L "${COPILOT_FILE}" ]]; then
+    TARGET=$(readlink "${COPILOT_FILE}")
+    if [[ "${TARGET}" == "../AGENTS.md" || "${TARGET}" == "${WORKSPACE_ROOT}/AGENTS.md" || "${TARGET}" == "AGENTS.md" ]]; then
+      log_pass ".github/copilot-instructions.md is a valid symlink to AGENTS.md."
+    else
+      log_fail ".github/copilot-instructions.md points to '${TARGET}' instead of '../AGENTS.md'."
+    fi
+  elif [[ -f "${COPILOT_FILE}" ]] && [[ "$(< "${COPILOT_FILE}")" == *"AGENTS.md"* ]]; then
+    log_pass ".github/copilot-instructions.md references AGENTS.md (symlink fallback)."
+  elif [[ -f "${COPILOT_FILE}" ]]; then
+    log_warn ".github/copilot-instructions.md exists but is neither a symlink to ../AGENTS.md nor references AGENTS.md."
+  fi
+fi
+
+# Check .gitignore exists
+GITIGNORE_FILE="${WORKSPACE_ROOT}/.gitignore"
+if [[ -f "${GITIGNORE_FILE}" ]]; then
+  log_pass ".gitignore exists."
+else
+  log_fail "Missing .gitignore at ${GITIGNORE_FILE}"
+fi
+
 # 2. Checking Progressive Disclosure Rules (docs/rules)
 echo ""
 echo "2. Checking Progressive Disclosure Rules..."
@@ -128,6 +234,11 @@ else
       log_fail "Skill '${SKILL_NAME}' missing opening front matter delimiter (---)"
       continue
     fi
+
+    # Check closing front matter delimiter
+    if ! awk 'NR > 1 && /^---[[:space:]]*$/ { found=1; exit } END { exit !found }' "${SKILL_FILE}"; then
+      log_fail "Skill '${SKILL_NAME}' missing closing front matter delimiter (---)"
+    fi
     
     # Check name field in front matter
     if ! grep -E "^name:[[:space:]]*${SKILL_NAME}" "${SKILL_FILE}" > /dev/null; then
@@ -143,6 +254,11 @@ else
       if [[ ! "${DESC}" =~ ^Use[[:space:]]when ]]; then
         log_warn "Skill '${SKILL_NAME}' description should start with imperative 'Use when...'"
       fi
+
+      # Check negative boundary phrasing (Do not use / Do NOT use)
+      if ! echo "${DESC}" | grep -qiE "(do not use|do NOT use)"; then
+        log_warn "Skill '${SKILL_NAME}' description should specify negative boundaries ('Do not use for...')"
+      fi
       
       # Check character length (< 1024)
       CHAR_LEN=${#DESC}
@@ -167,7 +283,74 @@ else
   log_pass "Validated ${SKILL_COUNT} skills in .agents/skills/."
 fi
 
-# 4. Summary Output
+# 4. Checking Markdown Internal Links & Cross-References
+echo ""
+echo "4. Checking Markdown Internal Links & Cross-References..."
+LINK_CHECK_RAW=$(node -e '
+const fs = require("fs");
+const path = require("path");
+
+const root = process.argv[1];
+const broken = [];
+let totalLinks = 0;
+
+function walk(dir) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name === ".git" || entry.name === "node_modules") continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walk(full);
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      checkFile(full);
+    }
+  }
+}
+
+function checkFile(filePath) {
+  const content = fs.readFileSync(filePath, "utf8");
+  const dir = path.dirname(filePath);
+  const regex = /\[([^\]]+)\]\(([^)]+)\)/g;
+  let match;
+  while ((match = regex.exec(content)) !== null) {
+    const target = match[2].trim();
+    if (target.startsWith("http://") || target.startsWith("https://") || target.startsWith("mailto:") || target.startsWith("#") || target.startsWith("conversation://") || target.startsWith("file://")) {
+      continue;
+    }
+    const cleanTarget = target.split("#")[0];
+    if (!cleanTarget) continue;
+    totalLinks++;
+    const resolved = path.normalize(path.join(dir, cleanTarget));
+    if (!fs.existsSync(resolved)) {
+      broken.push(`${path.relative(root, filePath)} -> ${target}`);
+    }
+  }
+}
+
+walk(root);
+if (broken.length > 0) {
+  console.log("BROKEN:" + broken.join("|"));
+  process.exit(1);
+} else {
+  console.log("OK:" + totalLinks);
+  process.exit(0);
+}
+' "${WORKSPACE_ROOT}" 2>&1) || true
+
+if [[ "${LINK_CHECK_RAW}" =~ ^OK:([0-9]+) ]]; then
+  TOTAL_LINKS="${BASH_REMATCH[1]}"
+  log_pass "Validated ${TOTAL_LINKS} internal links across workspace (0 broken links)."
+elif [[ "${LINK_CHECK_RAW}" =~ ^BROKEN:(.*) ]]; then
+  BROKEN_LIST="${BASH_REMATCH[1]}"
+  IFS='|' read -ra BROKEN_ITEMS <<< "${BROKEN_LIST}"
+  for item in "${BROKEN_ITEMS[@]}"; do
+    log_fail "Broken markdown link: ${item}"
+  done
+else
+  log_fail "Markdown link validation failed unexpectedly: ${LINK_CHECK_RAW}"
+fi
+
+# 5. Summary Output
 echo ""
 echo "--------------------------------------------------------------"
 if [[ ${ERRORS} -eq 0 ]]; then

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

@@ -5,7 +5,7 @@ description: Use when refactoring existing code to comply with Clean Code, SOLID
 
 # 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.
+> **Core Purpose:** Transform messy, coupled, or rigid code into clean, expressive, and maintainable implementations adhering to Robert C. Martin's Clean Code, The Pragmatic Programmer, and modern Gang of Four patterns without altering external behavior.
 
 ---
 
@@ -27,7 +27,7 @@ description: Use when refactoring existing code to comply with Clean Code, SOLID
 
 ### 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`.
+- Confirm all existing unit and acceptance tests pass: workspace test command (e.g. `npm test`, `cargo test`, `go test ./...`, `pytest`).
 - If coverage is missing or incomplete, write tests *before* touching production code.
 
 ### Step 2: Identify Specific Code Smells
@@ -45,8 +45,8 @@ Target concrete flaws:
 
 ### 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`.
+- Maintain existing naming conventions and idiomatic type safety.
+- Ensure zero lint or type errors: workspace linter and compiler (e.g. `npm run lint && npm run typecheck`, `cargo clippy`, `golangci-lint`, `mypy`).
 
 ### Step 5: Verify Continuous Green State
 - Run tests after every single atomic change: `npm run coverage`.
@@ -81,11 +81,11 @@ Target concrete flaws:
 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)
+   - Typecheck / Compiler: PASS (0 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.
+- [references/design_patterns_ts.md](./references/design_patterns_ts.md): Reference implementations of Adapter, Strategy, and Result patterns (illustrated in TypeScript).

package/.agents/skills/compliance-audit/SKILL.md

@@ -102,7 +102,7 @@ Audit architectural implementation against compliance baselines:
 ## 3. Compliance Control Evaluation Matrix
 | Framework | Control ID | Control Description | Status | Evidence / Notes |
 |---|---|---|---|---|
-| **SOC 2** | CC6.1 | Least-privilege RBAC & tenant isolation | PASS | Scoped queries in Prisma |
+| **SOC 2** | CC6.1 | Least-privilege RBAC & tenant isolation | PASS | Scoped database queries / RLS |
 | **SOC 2** | CC7.2 | Tamper-evident mutation audit logging | PASS | Audit table with actor tracing |
 | **ISO 27001** | A.10.1 | Cryptographic controls (AES-256, TLS 1.3) | PASS | TLS 1.3 configured, Argon2id auth |
 | **OWASP** | A01 | Broken Access Control checks | PASS | Server-side guards on all routes |

package/.agents/skills/lets-build/SKILL.md

@@ -13,7 +13,7 @@ description: Use when initializing or bootstrapping a new project from this temp
 
 - When the user starts a fresh project by copying this workspace into a new directory.
 - When the user explicitly invokes `/lets-build` or asks to initialize/scaffold a new application.
-- When transforming or re-architecting an existing project to adhere to the 41 atomic domain rules.
+- When transforming or re-architecting an existing project to adhere to the 28 cohesive domain rules.
 - **Do NOT use for**:
   - Routine bug fixes or minor edits on an already bootstrapped codebase.
   - Adding a single endpoint or modifying an existing domain model.
@@ -45,7 +45,7 @@ Do NOT guess or assume any technology or stack choice. Execute the relentless in
 #### Batch 1: Problem Space & System Topology
 1. **Domain & Problem Statement:** What real-world problem or capability does this system solve? What data moves, and what transformations occur?
 2. **System Topology Classification:** Which topology best matches the execution target?
-   - Topology A: Web SaaS / Cloud Microservices
+   - Topology A: Web SaaS / Cloud Applications (Fullstack Web App vs Headless API)
    - Topology B: Browser Extension (Manifest V3)
    - Topology C: Game Engine / High-Performance Simulator (Bare metal, GPU)
    - Topology D: Browser / Canvas Game (HTML5 Canvas / WebGL / WebGPU)
@@ -70,7 +70,10 @@ Do NOT guess or assume any technology or stack choice. Execute the relentless in
 
 #### Batch 4: Targeted Invariants (Topology-Scoped, 100% YAGNI)
 Inquire *only* into the dimensions relevant to the selected topology:
-- *If Web SaaS / Backend:* API protocol (REST/gRPC), DB migration engine (Atlas/Flyway), tenancy isolation model, authentication, and OCI distroless containers.
+- *If Web SaaS / Cloud Application:*
+  - **Interface Scope:** Headless API service only vs Fullstack Web Application (API + Web Frontend).
+  - **If Fullstack Web Application:** Frontend framework & build tool (React + Vite, Vue 3, Svelte 5), styling & accessible headless component primitives (Tailwind CSS, Radix UI / shadcn/ui per [`frontend_architecture.md`](../../../docs/rules/frontend_architecture.md)), client directory structure (`client/` + `src/` backend), and persistent app shell layout per [`ui_ux_architecture.md`](../../../docs/rules/ui_ux_architecture.md).
+  - **Backend & Data:** API protocol (REST/OpenAPI 3.1 vs gRPC), DB migration engine (Atlas/Flyway), tenancy isolation model, authentication, and OCI distroless containers.
 - *If Browser Extension:* MV3 content script isolation (IIFE bundle), `chrome.storage.sync` flow, permissions. (Zero Docker/K8s/OpenAPI!).
 - *If Game Engine:* Graphics backend (Vulkan/DirectX/wgpu), memory allocators (arena/frame), ECS archetype model. (Zero Docker/SQL!).
 - *If CLI:* Arg parsing library, POSIX exit codes, streaming I/O, `--json` formatting. (Zero Docker/SQL!).
@@ -79,7 +82,7 @@ Inquire *only* into the dimensions relevant to the selected topology:
 
 ### Phase 3: Synthesize (Architecture Blueprint & User Sign-Off)
 1. Consolidate the user's answers into a formal **Consolidated Architectural Blueprint** (using Section 4 template).
-2. Author an Architectural Decision Record in `memory.md` (e.g. `ADR-006: Target Technology Stack & Scaffolding Baseline`).
+2. Author the project's foundational Architectural Decision Record in `memory.md`, strictly starting with **`ADR-001: Target Technology Stack & Scaffolding Baseline`**. For a freshly initialized or bootstrapped project, `memory.md` must be a clean slate (zero prior decisions). If `memory.md` contains any legacy template ADRs from `azcodr`, sanitize and reset them so the new project starts from `ADR-001`.
 3. **STOP AND ASK FOR EXPLICIT CONFIRMATION**: Present the blueprint and ADR to the user. Do NOT write scaffolding code until the user approves the blueprint.
 
 ---
@@ -90,14 +93,15 @@ Upon user confirmation:
    ```bash
    bash .agents/skills/lets-build/scripts/bootstrap_workspace.sh . <topology> <language>
    ```
-2. Generate base infrastructure strictly for the selected topology (zero speculative bloat):
-   - *Backend:* `specs/openapi/v1/openapi.yaml`, `specs/tokens/tokens.json`, `deploy/docker`, `deploy/compose`.
+2. Generate base infrastructure strictly for the selected topology (zero speculative bloat) using layouts from [references/hexagonal_bootstrap_scaffolds.md](./references/hexagonal_bootstrap_scaffolds.md):
+   - *Fullstack Web SaaS:* Backend in `src/`, Web Client in `client/` (`client/src/components/layout`, `client/src/components/ui`, `client/src/pages`, `client/src/hooks`, `client/src/services`), `specs/openapi/v1/openapi.yaml`, `specs/tokens/tokens.json`, `deploy/docker`, `deploy/compose`.
+   - *Headless Backend:* `src/domain/`, `src/ports/`, `src/adapters/`, `specs/openapi/v1/openapi.yaml`, `specs/tokens/tokens.json`, `deploy/docker`, `deploy/compose`.
    - *Extension:* `manifest.json`, `src/background/index.ts`, `src/content/index.ts`, `src/popup/index.html`.
    - *Game / Engine:* `src/core/`, `src/ecs/`, asset manifest, frame loop entrypoint.
    - *CLI:* `src/cmd/`, `src/core/`, CLI entrypoint with exit code handling.
 3. Generate build manifests (`Cargo.toml`, `package.json`, `go.mod`, `pyproject.toml`), linter configurations, and boundary smoke test (`scripts/smoke_test.sh`).
 4. **Replace Starter README with Project-Specific README**:
-   Generate a clean, project-specific `README.md` completely replacing meta-template content with the project's actual name, mission, stack highlights, quickstart commands, and directory tree.
+   Generate a clean, project-specific `README.md` using [references/project_readme_template.md](./references/project_readme_template.md), completely replacing meta-template content with the project's actual name, mission, stack highlights, quickstart commands, and directory tree.
 
 ---
 
@@ -113,11 +117,14 @@ Upon user confirmation:
    - **`lets-build` IS NOW COMPLETE.** Do NOT proceed to write domain business entities, repositories, or application features.
    - Present the bootstrapped technical skeleton to the user.
    - Instruct the user to invoke `product-analyst` and `relentless-questioner` to initiate the **Domain Discovery & Requirements Engineering Phase** (Ubiquitous Language, Bounded Contexts, Aggregate Boundaries, INVEST User Stories, and Gherkin Acceptance Criteria) before any domain feature code is written.
+   - For applications with a user interface (Fullstack Web SaaS, Extensions, Desktop), the handover must explicitly instruct the user and agent to execute the **7-Pillar Design Architecture Triage Gate** ([`ui_ux_architecture.md`](../../../docs/rules/ui_ux_architecture.md)) to define user personas, persistent app shell navigation, and user journeys.
 
 ---
 
 ## 3. Gotchas & What NOT to Do
 
+- **MAJOR DONT: NEVER carry over template-internal ADRs from azcodr into a new project.** When scaffolding or bootstrapping a new project, `memory.md` must be a clean slate and start at `ADR-001`. Do NOT number the first architecture decision as ADR-025 or ADR-028 based on azcodr's template development history.
+- **MAJOR DONT: NEVER silently drop the frontend or treat Fullstack Web SaaS as a headless backend API!** If the user selects a Fullstack Web application with a UI, you MUST scaffold both the client (`client/`) and backend (`src/`) baselines, configure build manifests for both, execute the 7-Pillar Design Architecture Triage Gate, and ensure user stories slice vertically across both UI and API layers.
 - **MAJOR DONT: DO NOT invent, assume, or scaffold application domain entities, business logic, or feature pages during `/lets-build`.** The `lets-build` skill is strictly an infrastructure and technical stack bootstrapper. Fabricating business domain features without dedicated domain analysis and relentless questioning of the user is a fatal architectural defect.
 - **DO NOT** assume the stack. Never start writing Go, Rust, Python, or TypeScript before asking the user.
 - **DO NOT** scaffold universal web boilerplate (Docker, Kubernetes, OpenAPI, Postgres migrations) for non-backend projects (Browser Extensions, CLIs, Game Engines, Desktop apps).
@@ -155,3 +162,11 @@ Upon user confirmation:
 - **Code Health Gates:** 100.00% test coverage gate, zero lint errors
 - **DevSecOps:** <Semgrep / Trivy / Gitleaks / None>
 ```
+
+---
+
+## 5. Subdirectories & Progressive Resources
+- [references/architecture_interview_matrix.md](./references/architecture_interview_matrix.md): Exhaustive 5-tier problem-first architecture interview questions and branch logic.
+- [references/hexagonal_bootstrap_scaffolds.md](./references/hexagonal_bootstrap_scaffolds.md): Standardized directory trees and foundational templates across Go, Rust, Python, and TypeScript.
+- [references/project_readme_template.md](./references/project_readme_template.md): Boilerplate template for replacing starter documentation with project-specific README.
+- [scripts/bootstrap_workspace.sh](./scripts/bootstrap_workspace.sh): Topology-aware deterministic workspace initialization script.

package/.agents/skills/lets-build/references/architecture_interview_matrix.md

@@ -16,7 +16,7 @@
 
 ### Dimension 2: System Topology Classification
 Classify the system into its primary operational topology:
-1. **Topology A — Web SaaS / Cloud Microservices:** Network-facing HTTP/gRPC services with multi-tenant data persistence and web/mobile clients.
+1. **Topology A — Web SaaS / Cloud Applications:** Network-facing systems with multi-tenant data persistence, ranging from Fullstack Web Applications (API Backend + Web Frontend) to Headless Microservices (API-only).
 2. **Topology B — Browser Extension:** Client-side sandboxed extension (Chrome/Firefox MV3) orchestrating content scripts, background service workers, and popup UI.
 3. **Topology C — Game Engine / High-Performance Simulator:** Low-level, frame-budgeted application directly interfacing with GPU APIs (Vulkan, DirectX, Metal) and system memory.
 4. **Topology D — Browser / Canvas Game:** Sandboxed web game running inside the browser DOM/Canvas via Canvas2D, WebGL, or WebGPU.
@@ -86,7 +86,13 @@ Derive the programming language, runtime, and package manager strictly from the
 
 Inquire *only* into the dimensions relevant to the selected topology. **Never ask non-backend projects about databases, containers, or API versioning!**
 
-### For Web SaaS & Enterprise Backends ONLY:
+### For Web SaaS & Enterprise Cloud Applications ONLY:
+- **Application Interface Scope:** Headless API service (no UI) vs Fullstack Web Application (API Backend + Web Frontend Client).
+- **Frontend UI Stack (If Fullstack Web Application):**
+  - **Framework & Runtime:** React + Vite, Vue 3, Svelte 5, Next.js.
+  - **Component Primitives & Styling:** Tailwind CSS + Accessible Headless Primitives (Radix UI / shadcn/ui) per [docs/rules/frontend_architecture.md](../../../../docs/rules/frontend_architecture.md).
+  - **Client Structure:** Paired Client (`client/` + `src/` backend) vs Monorepo (`apps/web` + `apps/api`).
+  - **Design Triage & App Shell:** Persistent App Shell (collapsible sidebar, global header) vs Dynamic Canvas per [docs/rules/ui_ux_architecture.md](../../../../docs/rules/ui_ux_architecture.md).
 - **API Protocols:** REST (OpenAPI 3.1) vs gRPC (Protobuf v3 via Buf) vs GraphQL.
 - **Database Migrations:** Declarative (Atlas) vs Versioned SQL (Flyway, Goose).
 - **Multi-Tenancy Isolation:** AST Query Interceptor vs Database RLS vs Schema-per-tenant.