docs: Add repomap workflow automation (#23)

* Add repomap workflow automation

- Add scripts/update-repomap.sh for automated repomap management
- Add pre-commit hook to auto-update repomap on code changes
- Add CI validation to ensure repomap stays current
- Update documentation (README.md, CLAUDE.md, docs/patterns/repomap.md)
- Add scripts/README.md documenting all automation scripts

The repomap now automatically updates when committing code changes
and CI validates it's current on every push/PR.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* Replace pip with uv throughout documentation

- Update all package installation commands to use uv
- Update CI workflow to install and use uv
- Update error messages in scripts to recommend uv
- Keep pip only for bootstrapping uv in CI environments

Per project standards: always prefer uv over pip for package management.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: jeremyeder

.github/workflows/ci.yml

@@ -21,3 +21,25 @@ jobs:
           test -f docs/README.md || { echo "Error: docs/README.md missing"; exit 1; }
           test -d docs/adr || { echo "Error: docs/adr/ missing"; exit 1; }
           echo "All required documentation files present"
+
+  repomap-validation:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install repomap dependencies
+        run: |
+          pip install uv
+          uv pip install tree-sitter tree-sitter-python tree-sitter-javascript \
+                         tree-sitter-typescript tree-sitter-go tree-sitter-bash
+
+      - name: Validate repomap is current
+        run: |
+          chmod +x scripts/update-repomap.sh
+          ./scripts/update-repomap.sh --check

.pre-commit-config.yaml

@@ -1,6 +1,14 @@
 repos:
   - repo: local
     hooks:
+      - id: repomap-update
+        name: Update repository map
+        entry: scripts/update-repomap.sh
+        language: system
+        pass_filenames: false
+        files: '\.(py|js|ts|tsx|go|sh|bash)$'
+        description: Regenerate .repomap.txt when code structure changes
+
       - id: mkdocs-build
         name: mkdocs build --strict
         entry: .venv/bin/mkdocs build --strict

CLAUDE.md

@@ -135,12 +135,26 @@ cat .repomap.txt
 - Major refactoring is completed
 - Before creating PRs (ensure map is current)
 
+**Automated regeneration**:
+
+The repository includes automation for repomap management:
+
 ```bash
-# Regenerate after changes
+# Manual regeneration (recommended method)
+./scripts/update-repomap.sh
+
+# Check if repomap is current
+./scripts/update-repomap.sh --check
+
+# Legacy manual method (still works)
 python repomap.py . > .repomap.txt
 git add .repomap.txt  # Include in commits
 ```
 
+**Pre-commit hook**: The repomap is automatically regenerated when you commit changes to code files (`.py`, `.js`, `.ts`, `.tsx`, `.go`, `.sh`, `.bash`) via the pre-commit hook.
+
+**CI validation**: The CI workflow validates that the repomap is current on every push/PR.
+
 #### Integration with Development Workflow
 
 **Include repomap in commit tracking**:
@@ -383,6 +397,7 @@ Focus on "why" rather than "what".
 3. **`.github/workflows/ci.yml`** (General CI)
    - Code example linting (if any)
    - Documentation build test
+   - Repomap validation (ensures .repomap.txt is current)
    - Triggers: on push, PR
 
 4. **`.github/workflows/deploy-docs.yml`** (Documentation Deployment)
@@ -422,9 +437,15 @@ Teams can extend with:
 git clone https://github.com/yourusername/reference.git
 cd reference
 
+# Install repomap dependencies
+uv pip install -r requirements.txt
+
 # Install doc tooling
 uv pip install -r requirements-dev.txt
 
+# Install pre-commit hooks
+pre-commit install
+
 # Load repomap (session start)
 cat .repomap.txt
 

README.md

@@ -25,8 +25,12 @@ See [Quickstart](docs/README.md) for pattern overview and adoption guidance.
 ```bash
 git clone https://github.com/ambient-code/reference.git
 cd reference
-./scripts/setup.sh
-source .venv/bin/activate
+
+# Install dependencies
+uv pip install -r requirements.txt      # Repomap dependencies
+uv pip install -r requirements-dev.txt  # Doc tooling
+
+# Install pre-commit hooks (includes repomap auto-update)
 pre-commit install
 ```
 

docs/patterns/repomap.md

@@ -8,20 +8,24 @@ Generate clean, token-optimized code structure maps using tree-sitter for AI-ass
 
 ## Quick Start
 
+This repository includes **complete automation** for repomap management. The repomap is automatically updated via pre-commit hooks and validated in CI.
+
 ```bash
-# Install dependencies
-pip install -r requirements.txt
+# Install dependencies (includes tree-sitter packages)
+uv pip install -r requirements.txt
 
-# Generate map of current directory
-python repomap.py .
+# Install pre-commit hooks (includes repomap auto-update)
+pre-commit install
 
-# Save to file
-python repomap.py . > repomap.txt
+# Manual update (if needed)
+./scripts/update-repomap.sh
 
-# Map specific directory with verbose output
-python repomap.py /path/to/repo --verbose
+# Validate repomap is current
+./scripts/update-repomap.sh --check
 ```
 
+**That's it!** The repomap will auto-update when you commit code changes.
+
 ## Installation
 
 ### Requirements
@@ -32,11 +36,11 @@ python repomap.py /path/to/repo --verbose
 ### Install Dependencies
 
 ```bash
-# Using pip
-pip install tree-sitter tree-sitter-python tree-sitter-javascript tree-sitter-typescript tree-sitter-go tree-sitter-bash
-
-# Using uv (recommended)
+# Recommended method
 uv pip install -r requirements.txt
+
+# Or install individually with uv
+uv pip install tree-sitter tree-sitter-python tree-sitter-javascript tree-sitter-typescript tree-sitter-go tree-sitter-bash
 ```
 
 ## Usage
@@ -165,7 +169,9 @@ jobs:
           python-version: '3.11'
 
       - name: Install dependencies
-        run: pip install tree-sitter tree-sitter-python tree-sitter-javascript tree-sitter-typescript tree-sitter-go tree-sitter-bash
+        run: |
+          pip install uv
+          uv pip install tree-sitter tree-sitter-python tree-sitter-javascript tree-sitter-typescript tree-sitter-go tree-sitter-bash
 
       - name: Generate repomap
         run: python repomap.py . > repomap.txt
@@ -185,14 +191,87 @@ generate_repomap:
   stage: build
   image: python:3.11
   script:
-    - pip install tree-sitter tree-sitter-python tree-sitter-javascript tree-sitter-typescript tree-sitter-go tree-sitter-bash
+    - pip install uv
+    - uv pip install tree-sitter tree-sitter-python tree-sitter-javascript tree-sitter-typescript tree-sitter-go tree-sitter-bash
     - python repomap.py . > repomap.txt
   artifacts:
     paths:
       - repomap.txt
 ```
 
-### 3. Pre-commit Hook
+### 3. Automated Workflow (This Repository)
+
+This reference repository includes **complete repomap automation**:
+
+#### Pre-commit Hook
+
+The pre-commit hook automatically regenerates `.repomap.txt` when you commit changes to code files:
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: local
+    hooks:
+      - id: repomap-update
+        name: Update repository map
+        entry: scripts/update-repomap.sh
+        language: system
+        pass_filenames: false
+        files: '\.(py|js|ts|tsx|go|sh|bash)$'
+```
+
+**Triggers on**: `.py`, `.js`, `.ts`, `.tsx`, `.go`, `.sh`, `.bash` file changes
+
+**What it does**: Runs `./scripts/update-repomap.sh` to regenerate `.repomap.txt` before commit
+
+#### CI Validation
+
+GitHub Actions workflow validates repomap is current on every push/PR:
+
+```yaml
+# .github/workflows/ci.yml
+repomap-validation:
+  runs-on: ubuntu-latest
+  steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+    - name: Install repomap dependencies
+      run: |
+        pip install uv
+        uv pip install tree-sitter tree-sitter-python tree-sitter-javascript \
+                       tree-sitter-typescript tree-sitter-go tree-sitter-bash
+    - name: Validate repomap is current
+      run: ./scripts/update-repomap.sh --check
+```
+
+**What it does**: Blocks merge if `.repomap.txt` is outdated
+
+#### Automation Script
+
+The `scripts/update-repomap.sh` script provides:
+
+```bash
+# Regenerate repomap
+./scripts/update-repomap.sh
+
+# Validate repomap is current (CI usage)
+./scripts/update-repomap.sh --check
+
+# Show help
+./scripts/update-repomap.sh --help
+```
+
+**Features**:
+- Clear error messages with dependency installation hints
+- Validates repomap currency for CI/CD
+- Used by pre-commit hook for auto-updates
+
+#### Manual Pre-commit Hook (Alternative)
+
+If you prefer a simpler manual hook in other repositories:
 
 ```bash
 # .git/hooks/pre-commit
@@ -267,7 +346,7 @@ Potential improvements for future versions:
 **Solution**: Install dependencies
 
 ```bash
-pip install -r requirements.txt
+uv pip install -r requirements.txt
 ```
 
 ### Parse Errors
@@ -320,6 +399,14 @@ See LICENSE file in repository root.
 
 **Quickstart**:
 
-1. Install: `pip install -r requirements.txt`
-2. Run: `python repomap.py .`
-3. Save: `python repomap.py . > repomap.txt`
+1. Install dependencies: `uv pip install -r requirements.txt`
+2. Install pre-commit hooks: `pre-commit install`
+3. The repomap auto-updates on commits!
+
+**Manual usage** (if needed):
+
+```bash
+./scripts/update-repomap.sh          # Regenerate
+./scripts/update-repomap.sh --check  # Validate
+python repomap.py .                  # Direct generation
+```