tirthbodawala · Nov 5, 2025 · Nov 5, 2025 · Nov 5, 2025 · Nov 5, 2025
diff --git a/.ai-context/LAST_SESSION_SUMMARY.md b/.ai-context/LAST_SESSION_SUMMARY.md
@@ -31,7 +31,7 @@ Reviewed all template/docs files for relevance. All files are relevant. Converte
 
 ## Files Changed
 
-- No files tracked
+- `validate_ai_docs_sync.py`
 
 ---
 

diff --git a/AGENTS.md b/AGENTS.md
@@ -251,7 +251,7 @@ Before committing code, ensure:
 7. ✅ **Type hints everywhere**: mypy strict mode
 8. ✅ **No security issues**: CI runs Bandit + Safety
 9. ✅ **AI documentation synchronized** (MANDATORY)
-   - Run: `uv run python src/python_modern_template/validate_ai_docs_sync.py`
+   - Run: `uv run ai-validate-docs`
    - Update manual sync files if AI_DOCS changed
    - Update .claude/skills or .claude/agents if relevant
    - Update template files if changes apply to new projects

diff --git a/AI_DOCS/documentation-sync-rules.md b/AI_DOCS/documentation-sync-rules.md
@@ -65,7 +65,7 @@ For agents that **support references** (Claude, Cursor, Aider, Gemini/AGENTS.md)
 - [ ] Ensure references point to correct files
 - [ ] Validate no broken references
 
-**Script:** `uv run python src/python_modern_template/validate_ai_docs_sync.py`
+**Script:** `uv run ai-validate-docs`
 
 ### Step 3: Update Non-Supporting Agents
 
@@ -114,7 +114,7 @@ For agents that **don't support references** (Gemini/styleguide, Copilot):
 
 **Run validation script:**
 ```bash
-uv run python src/python_modern_template/validate_ai_docs_sync.py
+uv run ai-validate-docs
 ```
 
 **Should report:**
@@ -191,7 +191,7 @@ uv run python src/python_modern_template/validate_ai_docs_sync.py
 
 ## Validation Script
 
-**Location:** `src/python_modern_template/validate_ai_docs_sync.py`
+**Location:** `scripts/ai_tools/validate_ai_docs_sync.py`
 
 **What it checks:**
 1. All `@AI_DOCS/` references point to existing files
@@ -203,7 +203,7 @@ uv run python src/python_modern_template/validate_ai_docs_sync.py
 **Usage:**
 ```bash
 # Run validation
-uv run python src/python_modern_template/validate_ai_docs_sync.py
+uv run ai-validate-docs
 
 # Expected output (all passing):
 ✅ All AI_DOCS files found
@@ -232,8 +232,7 @@ uv run python src/python_modern_template/validate_ai_docs_sync.py
 - Quality tests (5 files): `tests/quality/*.py` → `template/tests/quality/*.py.jinja`
 - Project tests (4 files): `tests/test_*.py` → `template/tests/test_*.py.jinja`
 - Quality scripts (6 files): `scripts/quality/*.py` → `template/scripts/quality/*.py.jinja`
-- AI tools scripts (11 files): `scripts/ai_tools/*.py` → `template/scripts/ai_tools/*.py.jinja`
-- Source modules (1 file): `src/{{ package_name }}/validate_ai_docs_sync.py.jinja`
+- AI tools scripts (12 files): `scripts/ai_tools/*.py` → `template/scripts/ai_tools/*.py.jinja`
 
 **Note:** AI tools tests are NOT synced to the template. They remain in the template repository only, as they test template infrastructure that users typically won't modify.
 
@@ -253,8 +252,7 @@ python sync_template.py
 **When to run:**
 1. After modifying any test files in `tests/`
 2. After modifying any scripts in `scripts/quality/` or `scripts/ai_tools/`
-3. After modifying `src/{{ package_name }}/validate_ai_docs_sync.py`
-4. Before releasing a new template version
+3. Before releasing a new template version
 
 **What it doesn't sync (intentionally):**
 - AI_DOCS/*.md files (already synced via separate workflow)
@@ -306,15 +304,15 @@ In `AI_DOCS/code-conventions.md` and all agent configs, add:
 - [ ] `make lint` passes
 - [ ] `make check` passes
 - [ ] **AI documentation synchronized** ⭐ NEW
-  - [ ] Validated with `validate_ai_docs_sync.py`
+  - [ ] Validated with `uv run ai-validate-docs`
   - [ ] Updated manual sync files if needed
   - [ ] Updated .claude/skills or .claude/agents if needed
   - [ ] Updated template files if needed
 
 ### Integration with ai-finish-task
 
 Before `ai-finish-task` completes, it should:
-1. Run `validate_ai_docs_sync.py`
+1. Run `uv run ai-validate-docs`
 2. If validation fails, prompt to fix or continue with `--yes`
 3. Log validation results to EXECUTION file
 
@@ -363,8 +361,8 @@ project/
 │       ├── project-context.md.jinja
 │       └── documentation-sync-rules.md.jinja
 │
-└── src/python_modern_template/
-    └── validate_ai_docs_sync.py       # Validation script
+└── scripts/ai_tools/
+    └── validate_ai_docs_sync.py       # Validation script (CLI: ai-validate-docs)
 ```
 
 ---
@@ -411,7 +409,7 @@ project/
 1. **Use the validation script**
    ```bash
    # After any doc change
-   uv run python src/python_modern_template/validate_ai_docs_sync.py
+   uv run ai-validate-docs
    ```
 
 2. **Reference, don't duplicate**
@@ -437,7 +435,7 @@ project/
    # Correct: Update both
    vim AI_DOCS/code-conventions.md
    vim template/AI_DOCS/code-conventions.md.jinja
-   uv run python src/python_modern_template/validate_ai_docs_sync.py
+   uv run ai-validate-docs
    ```
 
 ---
@@ -448,7 +446,7 @@ project/
 
 **Quick Checklist:**
 1. ✅ Update the changed file
-2. ✅ Run `validate_ai_docs_sync.py`
+2. ✅ Run `uv run ai-validate-docs`
 3. ⚠️ Update manual sync files if needed (Gemini/Copilot)
 4. ✅ Update .claude/skills or .claude/agents if relevant
 5. ✅ Update template files

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -302,7 +302,7 @@ Before completing any task:
 - [ ] Formatter harmony check (Black vs Ruff) — adjust code (e.g., use message variables)
       if tools disagree
 - [ ] **AI documentation synchronized** (MANDATORY)
-  - [ ] Run `uv run python src/python_modern_template/validate_ai_docs_sync.py`
+  - [ ] Run `uv run ai-validate-docs`
   - [ ] Update `.gemini/styleguide.md` if AI_DOCS changed (add sync date)
   - [ ] Update `.github/copilot-instructions.md` if AI_DOCS changed (add sync date)
   - [ ] Update `.claude/skills/` or `.claude/agents/` if relevant

diff --git a/pyproject.toml b/pyproject.toml
@@ -40,6 +40,7 @@ ai-context-summary = "scripts.ai_tools.context_summary:main"
 ai-check-conflicts = "scripts.ai_tools.check_conflicts:main"
 ai-add-decision = "scripts.ai_tools.add_decision:main"
 ai-add-convention = "scripts.ai_tools.add_convention:main"
+ai-validate-docs = "scripts.ai_tools.validate_ai_docs_sync:main"
 
 # Quality Tools - Single source of truth for quality checks
 quality-format = "scripts.quality.format:main"

diff --git a/..._modern_template/validate_ai_docs_sync.py → scripts/ai_tools/validate_ai_docs_sync.py b/..._modern_template/validate_ai_docs_sync.py → scripts/ai_tools/validate_ai_docs_sync.py
@@ -271,7 +271,7 @@ def generate_sync_report(issues: list[dict[str, str]]) -> str:
 
 3. **Verify fixes:**
    ```bash
-   python -m python_modern_template.validate_ai_docs_sync
+   uv run ai-validate-docs
    ```
 """
 

diff --git a/sync_template.py b/sync_template.py
@@ -171,6 +171,7 @@ def main() -> None:
             "template_loader.py",
             "update_plan.py",
             "utils.py",
+            "validate_ai_docs_sync.py",
         ],
         PROJECT_ROOT / "scripts" / "ai_tools",
         TEMPLATE_ROOT / "scripts" / "ai_tools",
@@ -185,14 +186,6 @@ def main() -> None:
         sync_file(scripts_init_src, scripts_init_dst, add_jinja_ext=False)
         total += 1
 
-    # Sync src module files
-    total += sync_file_list(
-        ["validate_ai_docs_sync.py"],
-        PROJECT_ROOT / "src" / "python_modern_template",
-        TEMPLATE_ROOT / "src" / "{{ package_name }}",
-        "📦 Syncing src module files...",
-    )
-
     print("\n" + "=" * 70)
     print(f"✅ SYNC COMPLETE: {total} files synced")
     print("=" * 70)

diff --git a/template/AI_DOCS/documentation-sync-rules.md.jinja b/template/AI_DOCS/documentation-sync-rules.md.jinja
@@ -65,7 +65,7 @@ For agents that **support references** (Claude, Cursor, Aider, Gemini/AGENTS.md)
 - [ ] Ensure references point to correct files
 - [ ] Validate no broken references
 
-**Script:** `uv run python src/{{ package_name }}/validate_ai_docs_sync.py`
+**Script:** `uv run ai-validate-docs`
 
 ### Step 3: Update Non-Supporting Agents
 
@@ -114,7 +114,7 @@ For agents that **don't support references** (Gemini/styleguide, Copilot):
 
 **Run validation script:**
 ```bash
-uv run python src/{{ package_name }}/validate_ai_docs_sync.py
+uv run ai-validate-docs
 ```
 
 **Should report:**
@@ -191,7 +191,7 @@ uv run python src/{{ package_name }}/validate_ai_docs_sync.py
 
 ## Validation Script
 
-**Location:** `src/{{ package_name }}/validate_ai_docs_sync.py`
+**Location:** `scripts/ai_tools/validate_ai_docs_sync.py`
 
 **What it checks:**
 1. All `@AI_DOCS/` references point to existing files
@@ -203,7 +203,7 @@ uv run python src/{{ package_name }}/validate_ai_docs_sync.py
 **Usage:**
 ```bash
 # Run validation
-uv run python src/{{ package_name }}/validate_ai_docs_sync.py
+uv run ai-validate-docs
 
 # Expected output (all passing):
 ✅ All AI_DOCS files found
@@ -232,8 +232,7 @@ uv run python src/{{ package_name }}/validate_ai_docs_sync.py
 - Quality tests (5 files): `tests/quality/*.py` → `template/tests/quality/*.py.jinja`
 - Project tests (4 files): `tests/test_*.py` → `template/tests/test_*.py.jinja`
 - Quality scripts (6 files): `scripts/quality/*.py` → `template/scripts/quality/*.py.jinja`
-- AI tools scripts (11 files): `scripts/ai_tools/*.py` → `template/scripts/ai_tools/*.py.jinja`
-- Source modules (1 file): `src/{{ package_name }}/validate_ai_docs_sync.py.jinja`
+- AI tools scripts (12 files): `scripts/ai_tools/*.py` → `template/scripts/ai_tools/*.py.jinja`
 
 **Note:** AI tools tests are NOT synced to the template. They remain in the template repository only, as they test template infrastructure that users typically won't modify.
 
@@ -253,7 +252,7 @@ python sync_template.py
 **When to run:**
 1. After modifying any test files in `tests/`
 2. After modifying any scripts in `scripts/quality/` or `scripts/ai_tools/`
-3. After modifying `src/{{ package_name }}/validate_ai_docs_sync.py`
+3. After modifying `scripts/ai_tools/validate_ai_docs_sync.py`
 4. Before releasing a new template version
 
 **What it doesn't sync (intentionally):**
@@ -306,15 +305,15 @@ In `AI_DOCS/code-conventions.md` and all agent configs, add:
 - [ ] `make lint` passes
 - [ ] `make check` passes
 - [ ] **AI documentation synchronized** ⭐ NEW
-  - [ ] Validated with `validate_ai_docs_sync.py`
+  - [ ] Validated with `uv run ai-validate-docs`
   - [ ] Updated manual sync files if needed
   - [ ] Updated .claude/skills or .claude/agents if needed
   - [ ] Updated template files if needed
 
 ### Integration with ai-finish-task
 
 Before `ai-finish-task` completes, it should:
-1. Run `validate_ai_docs_sync.py`
+1. Run `uv run ai-validate-docs`
 2. If validation fails, prompt to fix or continue with `--yes`
 3. Log validation results to EXECUTION file
 
@@ -363,8 +362,8 @@ project/
 │       ├── project-context.md.jinja
 │       └── documentation-sync-rules.md.jinja
 │
-└── src/{{ package_name }}/
-    └── validate_ai_docs_sync.py       # Validation script
+└── scripts/ai_tools/
+    └── validate_ai_docs_sync.py       # Validation script (CLI: ai-validate-docs)
 ```
 
 ---
@@ -411,7 +410,7 @@ project/
 1. **Use the validation script**
    ```bash
    # After any doc change
-   uv run python src/{{ package_name }}/validate_ai_docs_sync.py
+   uv run ai-validate-docs
    ```
 
 2. **Reference, don't duplicate**
@@ -437,7 +436,7 @@ project/
    # Correct: Update both
    vim AI_DOCS/code-conventions.md
    vim template/AI_DOCS/code-conventions.md.jinja
-   uv run python src/{{ package_name }}/validate_ai_docs_sync.py
+   uv run ai-validate-docs
    ```
 
 ---
@@ -448,7 +447,7 @@ project/
 
 **Quick Checklist:**
 1. ✅ Update the changed file
-2. ✅ Run `validate_ai_docs_sync.py`
+2. ✅ Run `uv run ai-validate-docs`
 3. ⚠️ Update manual sync files if needed (Gemini/Copilot)
 4. ✅ Update .claude/skills or .claude/agents if relevant
 5. ✅ Update template files

diff --git a/...ge_name }}/validate_ai_docs_sync.py.jinja → ...s/ai_tools/validate_ai_docs_sync.py.jinja b/...ge_name }}/validate_ai_docs_sync.py.jinja → ...s/ai_tools/validate_ai_docs_sync.py.jinja
@@ -271,7 +271,7 @@ Everything is synchronized! 🎉
 
 3. **Verify fixes:**
    ```bash
-   python -m {{ package_name }}.validate_ai_docs_sync
+   uv run ai-validate-docs
    ```
 """
-Original file line number
+Diff line change
@@ Expand Up @@
     ## Files Changed
-    - No files tracked
+    - `validate_ai_docs_sync.py`
     ---
@@ Expand Down @@