azcodr 1.2.2 → 1.4.0

package/.agents/hooks.json.example

@@ -0,0 +1,42 @@
+{
+  "safety-guard": {
+    "enabled": false,
+    "PreToolUse": [
+      {
+        "matcher": "run_command",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./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": "./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/skills/agentic-architect/SKILL.md

@@ -23,7 +23,7 @@ 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/`?
@@ -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

@@ -36,16 +36,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."
@@ -68,7 +81,7 @@ else
   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'."
@@ -78,6 +91,68 @@ else
   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
+
 # 2. Checking Progressive Disclosure Rules (docs/rules)
 echo ""
 echo "2. Checking Progressive Disclosure Rules..."
@@ -128,6 +203,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 +223,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 +252,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.
@@ -79,7 +79,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 an Architectural Decision Record in `memory.md` (e.g. `ADR-025: Target Technology Stack & Scaffolding Baseline` or next sequential ADR).
 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 +90,14 @@ 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):
+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):
    - *Backend:* `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.
 
 ---
 
@@ -155,3 +155,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/hexagonal_bootstrap_scaffolds.md

@@ -13,7 +13,7 @@ Regardless of language, all bootstrapped projects must follow this high-level se
 ├── .agents/skills/                   # Specialized agentic workflows (carried from azcodr template)
 ├── docs/
 │   ├── knowledge/                    # Domain knowledge & living ubiquitous language glossary
-│   └── rules/                        # 41 atomic single-responsibility domain rules
+│   └── rules/                        # 28 cohesive single-responsibility domain rules
 ├── specs/                            # Canonical contract specifications
 │   ├── protobuf/                     # gRPC service definitions (*.proto)
 │   ├── openapi/                      # OpenAPI 3.1 REST specifications (*.yaml)

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

@@ -37,7 +37,7 @@
 │   ├── contracts/                    # Consumer contract tests (Pact)
 │   └── acceptance/                   # BDD Gherkin / Cucumber features
 ├── deploy/                           # OCI Distroless Dockerfiles & Compose manifests
-├── docs/rules/                       # 41 atomic single-responsibility architectural rules
+├── docs/rules/                       # 28 cohesive single-responsibility architectural rules
 ├── memory.md                         # Master memory hub & Lightweight ADR ledger
 └── AGENTS.md                         # Lean agentic directives (< 120 lines)
 ```
@@ -74,6 +74,6 @@ cp .env.example .env
 
 ## 🏛️ Architecture Governance & Decisions
 
-This project is governed by the **41 Atomic Domain Rules** located in [`docs/rules/`](./docs/rules/) and Architectural Decision Records in [`memory.md`](./memory.md):
-- **ADR Ledger:** See [`memory.md`](./memory.md) for ADR-001 through ADR-006.
-- **Architectural Rules:** See [`docs/rules/`](./docs/rules/) for TDD, Clean Code, Multi-Tenancy, Database Integrity, and DevSecOps directives.
+This project is governed by the **28 Cohesive Domain Rules** located in `docs/rules/` and Architectural Decision Records in `memory.md`:
+- **ADR Ledger:** See `memory.md` for project-specific Architectural Decision Records.
+- **Architectural Rules:** See `docs/rules/` for TDD, Clean Code, Multi-Tenancy, Database Design, and DevSecOps directives.