azcodr 1.5.0 → 1.5.1

package/.agents/hooks.json

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

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/mcp_config.json.example

@@ -1,4 +1,9 @@
 {
+  "_notes": [
+    "Copy to .agents/mcp_config.json and replace placeholders before use.",
+    "Create ./data/ (shipped with .gitkeep) before starting the sqlite server.",
+    "Replace remote-service.url with your deployment; example.com is intentionally non-functional."
+  ],
   "mcpServers": {
     "sqlite": {
       "command": "npx",
@@ -18,7 +23,7 @@
       ]
     },
     "remote-service": {
-      "serverUrl": "https://mcp.example.com/sse"
+      "url": "https://mcp.example.com/sse"
     }
   }
 }

package/.agents/scripts/safety_guard.sh

@@ -1,16 +1,34 @@
-#!/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
+#!/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

package/.agents/scripts/verify_completion.sh

@@ -1,13 +1,27 @@
-#!/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
+#!/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

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 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 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.

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

@@ -1,62 +1,62 @@
-# 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_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`, `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
-```
-```
+# 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_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`, `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
+```
+```