@jaguilar87/gaia-ops 2.2.3 → 2.3.1

package/CHANGELOG.md

@@ -5,6 +5,54 @@ All notable changes to the CLAUDE.md orchestrator instructions are documented in
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.0] - 2025-11-11
+
+### Added - Phase 0 Clarification Module
+- **NEW:** `tools/clarification/` module for intelligent ambiguity detection before routing
+  - `clarification/engine.py`: Core clarification engine (refactored from clarify_engine.py)
+  - `clarification/patterns.py`: Ambiguity detection patterns (ServiceAmbiguityPattern, NamespaceAmbiguityPattern, etc.)
+  - `clarification/workflow.py`: High-level helper functions for orchestrators (`execute_workflow()`)
+  - `clarification/__init__.py`: Clean public API
+- **Protocol G** in `agents/gaia.md`: Clarification system analysis and troubleshooting guide
+- **Rule 5.0.1** in `templates/CLAUDE.template.md`: Phase 0 implementation guide with code examples
+- **Phase 0 integration** in `/speckit.specify` command
+- **Regression tests** in `tests/integration/test_phase_0_regression.py`
+- **Clarification metrics** to Key System Metrics (target: 20-30% clarification rate)
+
+### Changed - Module Restructuring (BREAKING)
+- **BREAKING:** `clarify_engine.py` and `clarify_patterns.py` moved to `clarification/` module
+  - **Old imports:** `from clarify_engine import request_clarification`
+  - **New imports:** `from clarification import execute_workflow, request_clarification`
+- Updated `application_services` structure in project-context.json:
+  - Added `tech_stack` field (replaces `technology`)
+  - Added `namespace` field for service location
+  - **Removed** `status` field (dynamic state must be verified in real-time, not stored in SSOT)
+- Service metadata now shows only static information: `tech_stack | namespace | port`
+
+### Fixed
+- Import paths in `tests/tools/test_clarify_engine.py` updated to new module structure
+- Service metadata test updated to reflect removal of dynamic status field
+- All 20 unit tests passing with new module structure
+
+### Documentation
+- Added comprehensive Phase 0 implementation guide
+- Added troubleshooting guide for clarification system
+- Updated speckit.specify.md with Phase 0 workflow integration
+- Added Protocol G diagnostic steps in gaia.md
+
+### Migration Guide for v2.3.0
+```python
+# Before (v2.2.x)
+from clarify_engine import request_clarification, process_clarification
+
+# After (v2.3.0)
+from clarification import execute_workflow
+
+# Simple usage
+result = execute_workflow(user_prompt)
+enriched_prompt = result["enriched_prompt"]
+```
+
 ## [2.2.3] - 2025-11-11
 
 ### Fixed - Deterministic Project Context Location

package/README.md

@@ -17,7 +17,8 @@ Sistema de orquestación multi-agente para Claude Code - Toolkit de automatizaci
 - **Soporte multi-cloud** - Funciona con GCP, AWS, y listo para Azure
 - **6 agentes especialistas** (terraform-architect, gitops-operator, gcp-troubleshooter, aws-troubleshooter, devops-developer, Gaia)
 - **3 meta-agentes** (Explore, Plan, Gaia)
-- **Motor de clarificación** para detección de ambigüedades
+- **Sistema de clarificación genérico** (Phase 0) - Detección automática de ambigüedades desde project-context.json con preguntas dinámicas y multi-tab
+- **Helper AskUserQuestion** - Función `ask()` para forzar UX consistente (SIEMPRE preguntas, nunca texto plano)
 - **Puertas de aprobación** para operaciones T3 (terraform apply, kubectl apply, etc.)
 - **Validación de commits Git** con Conventional Commits
 - **Sistema de provisión de contexto** para ruteo inteligente de agentes

package/agents/gaia.md

@@ -16,15 +16,15 @@ You are Gaia, the senior system architect and AI agent systems specialist for th
 3. **Analyze & Respond:** Provide comprehensive answer with evidence, examples, and actionable recommendations.
 
 **Where Everything Lives (Package + Symlink Layout):**
-- 🏗️ Package root: `/home/jaguilar/aaxis/rnd/repositories/gaia-ops/` → mirrors `node_modules/@jaguilar87/gaia-ops/` when installed
-- 📋 Orchestrator: `CLAUDE.md` at the package root (templated into consuming repos)
-- 🤖 Agents: `agents/*.md` (6 specialists: terraform-architect, gitops-operator, gcp-troubleshooter, aws-troubleshooter, devops-developer, gaia)
-- 🛠️ Tools: `tools/` (context_provider.py, agent_router.py, clarify_engine.py, approval_gate.py, commit_validator.py, task_manager.py)
-- 📚 Config docs: `config/` (AGENTS, orchestration-workflow, git-standards, context-contracts, agent-catalog)
-- 🗂️ Commands: `commands/*.md` (`/gaia`, `/save-session`, `/session-status`, `/speckit.*`)
-- 🎯 Spec-Kit assets: `speckit/README*.md`, `speckit/templates/`, `speckit/scripts/`, `speckit/governance.md`, `speckit/decisions/`
-- 🔧 Reference stacks: `terraform/`, `gitops/`, `app-services/` illustrate how agents interact with user IaC/App repos
-- 💾 Project data: consuming repos host `.claude/project-context.json`, `.claude/logs/`, `.claude/tests/`, while `ops/` carries shared symlink helpers
+- 🏗️ Package root: `$GAIA_OPS_ROOT` (or `node_modules/@jaguilar87/gaia-ops/` when installed)
+- 📋 Orchestrator: `$PROJECT_ROOT/CLAUDE.md` (templated into consuming repos)
+- 🤖 Agents: `$GAIA_OPS_ROOT/agents/*.md` (6 specialists: terraform-architect, gitops-operator, gcp-troubleshooter, aws-troubleshooter, devops-developer, gaia)
+- 🛠️ Tools: `$GAIA_OPS_ROOT/tools/` (context_provider.py, agent_router.py, clarify_engine.py, approval_gate.py, commit_validator.py, task_manager.py)
+- 📚 Config docs: `$GAIA_OPS_ROOT/config/` (AGENTS, orchestration-workflow, git-standards, context-contracts, agent-catalog)
+- 🗂️ Commands: `$GAIA_OPS_ROOT/commands/*.md` (`/gaia`, `/save-session`, `/session-status`, `/speckit.*`)
+- 🎯 Spec-Kit assets: `$GAIA_OPS_ROOT/speckit/README*.md`, `speckit/templates/`, `speckit/scripts/`, `speckit/governance.md`, `speckit/decisions/`
+- 🔧 Reference stacks: `$GAIA_OPS_ROOT/terraform/`, `gitops/`, `app-services/` illustrate how agents interact with user IaC/App repos
+- 💾 Project data: consuming repos host `$PROJECT_ROOT/.claude/project-context.json`, `.claude/logs/`, `.claude/tests/`, while `ops/` carries shared symlink helpers
 
 **Your Superpowers:**
 - ✅ You understand the ENTIRE system (no one else does)
@@ -113,6 +113,8 @@ When `npx @jaguilar87/gaia-ops init` (or `gaia-init` after a global install) run
 ### Key System Metrics (What to Track)
 
 - **Routing Accuracy:** Target 92.7% (from tests)
+- **Clarification Rate:** Target 20-30% (Phase 0 effectiveness)
+- **Clarification Effectiveness:** Routing accuracy improvement post-enrichment
 - **Context Efficiency:** 79-85% token savings (via context_provider.py)
 - **Test Coverage:** 55+ tests, 100% pass rate
 - **Production Uptime:** Track via logs/
@@ -472,6 +474,88 @@ You:
 
 **Output:** Feature RFC (Request for Comments)
 
+### Protocol G: Clarification System Analysis
+
+**Trigger:** "¿Por qué no se activó clarificación?" or "Ambiguity detection issues" or "Analyze Phase 0"
+
+**Steps:**
+1. Review clarification logs:
+   ```bash
+   cat .claude/logs/clarifications.jsonl | jq .
+   ```
+
+2. Check configuration:
+   ```bash
+   cat .claude/config/clarification_rules.json
+   jq '.global_settings' .claude/config/clarification_rules.json
+   ```
+
+3. Test detection manually:
+   ```python
+   import sys
+   sys.path.insert(0, '.claude/tools')
+   from clarification import execute_workflow, request_clarification
+
+   result = request_clarification("Check the API")
+   print(f"Needs clarification: {result['needs_clarification']}")
+   print(f"Ambiguity score: {result.get('ambiguity_score', 0)}")
+   print(f"Patterns detected: {[a['pattern'] for a in result.get('ambiguity_points', [])]}")
+   ```
+
+4. Review pattern definitions:
+   ```bash
+   cat .claude/tools/clarification/patterns.py
+   ```
+
+5. Analyze recent clarifications:
+   ```bash
+   cat .claude/logs/clarifications.jsonl | \
+     jq -r '[.timestamp, .ambiguity_score, .original_prompt] | @csv' | \
+     tail -20
+   ```
+
+6. Benchmark effectiveness:
+   - **Clarification rate:** Target 20-30%
+   - **User satisfaction:** No complaints about "too many questions"
+   - **Routing accuracy improvement:** Measure before/after enrichment
+
+7. Check module structure:
+   ```bash
+   ls -la .claude/tools/clarification/
+   # Should show: __init__.py, engine.py, patterns.py, workflow.py
+   ```
+
+**Output:** Clarification effectiveness report + tuning recommendations
+
+**Common Issues:**
+
+| Issue | Symptom | Fix |
+|-------|---------|-----|
+| Threshold too high | Ambiguity not detected | Lower from 30 to 20 in `clarification_rules.json` |
+| Threshold too low | Too many questions | Raise from 30 to 40 |
+| Missing patterns | New ambiguous terms not caught | Add to `patterns.py` (ServiceAmbiguityPattern.keywords) |
+| Spanish keywords missing | Spanish prompts not detected | Add to keywords list in patterns |
+| Import errors | Module not found | Check symlinks to gaia-ops package |
+| No services found | Tests failing | Verify `project-context.json` has `application_services` section |
+
+**Metrics to Track:**
+
+```python
+# Calculate clarification rate
+import json
+
+with open('.claude/logs/clarifications.jsonl') as f:
+    logs = [json.loads(line) for line in f]
+
+total_requests = len(logs)
+clarified = sum(1 for log in logs if log.get('ambiguity_score', 0) > 30)
+rate = (clarified / total_requests * 100) if total_requests > 0 else 0
+
+print(f"Clarification rate: {rate:.1f}%")
+print(f"Target: 20-30%")
+print(f"Status: {'✅ Good' if 20 <= rate <= 30 else '⚠️ Needs tuning'}")
+```
+
 ## Research Guidelines (WebSearch Usage)
 
 When researching, follow this pattern:

package/commands/gaia.md

@@ -39,16 +39,16 @@ Task(
 ## System Context (Auto-provided)
 
 **System Paths:**
-- Agent system: /home/jaguilar/aaxis/rnd/repositories/.claude/
-- Orchestrator logic: /home/jaguilar/aaxis/rnd/repositories/CLAUDE.md
-- Logs: /home/jaguilar/aaxis/rnd/repositories/.claude/logs/
-- Tests: /home/jaguilar/aaxis/rnd/repositories/.claude/tests/
-- Tools: /home/jaguilar/aaxis/rnd/repositories/.claude/tools/
-- Agents: /home/jaguilar/aaxis/rnd/repositories/.claude/agents/
-- Commands: /home/jaguilar/aaxis/rnd/repositories/.claude/commands/
-- Sessions: /home/jaguilar/aaxis/rnd/repositories/.claude/session/
-- Ops repository: /home/jaguilar/aaxis/rnd/repositories/ops/
-- Project context: /home/jaguilar/aaxis/rnd/repositories/.claude/project-context.json
+- Agent system: $PROJECT_ROOT/.claude/
+- Orchestrator logic: $PROJECT_ROOT/CLAUDE.md
+- Logs: $PROJECT_ROOT/.claude/logs/
+- Tests: $PROJECT_ROOT/.claude/tests/
+- Tools: $PROJECT_ROOT/.claude/tools/
+- Agents: $PROJECT_ROOT/.claude/agents/
+- Commands: $PROJECT_ROOT/.claude/commands/
+- Sessions: $PROJECT_ROOT/.claude/session/
+- Ops repository: $PROJECT_ROOT/../ops/
+- Project context: $PROJECT_ROOT/.claude/project-context.json
 
 **Spec-Kit Commands:**
 - /speckit.specify - Create/update feature specification

package/commands/restore-session.md

@@ -6,37 +6,37 @@ This command provides intelligent session restoration with context loading for b
 
 ## Quick command (restore latest relevant)
 ```bash
-python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/session_startup_check.py
+python3 $PROJECT_ROOT/.claude/session/scripts/session_startup_check.py
 ```
 
 Shows the most relevant recent session with restoration suggestions.
 
 ## Restore specific session
 ```bash
-python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/restore_session.py <bundle-id>
+python3 $PROJECT_ROOT/.claude/session/scripts/restore_session.py <bundle-id>
 ```
 
 Restores complete session context from the specified bundle.
 
 ## List available sessions
 ```bash
-python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/restore_session.py --list
+python3 $PROJECT_ROOT/.claude/session/scripts/restore_session.py --list
 ```
 
 Shows all available session bundles with descriptions and timestamps.
 
 ## View session details (without restoring)
 ```bash
-python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/restore_session.py <bundle-id> --show
+python3 $PROJECT_ROOT/.claude/session/scripts/restore_session.py <bundle-id> --show
 ```
 
 Display detailed information about a session bundle without loading it.
 
 ## Agent-specific context extraction
 ```bash
-python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/restore_session.py <bundle-id> --agent terraform-architect
-python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/restore_session.py <bundle-id> --agent gitops-operator
-python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/restore_session.py <bundle-id> --agent devops-developer
+python3 $PROJECT_ROOT/.claude/session/scripts/restore_session.py <bundle-id> --agent terraform-architect
+python3 $PROJECT_ROOT/.claude/session/scripts/restore_session.py <bundle-id> --agent gitops-operator
+python3 $PROJECT_ROOT/.claude/session/scripts/restore_session.py <bundle-id> --agent devops-developer
 ```
 
 Extract context specific to a particular agent type for on-demand loading.

package/commands/save-session.md

@@ -8,14 +8,14 @@ This command saves the complete current session into a new bundle with all conte
 
 ### Default session bundle
 ```bash
-python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/create_current_session_bundle.py
+python3 $PROJECT_ROOT/.claude/session/scripts/create_current_session_bundle.py
 ```
 
 Creates: `2025-10-16-session-163244-abc12345`
 
 ### Custom labeled bundle
 ```bash
-python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/create_current_session_bundle.py --label agent-upgrades
+python3 $PROJECT_ROOT/.claude/session/scripts/create_current_session_bundle.py --label agent-upgrades
 ```
 
 Creates: `2025-10-16-agent-upgrades-163244-abc12345`
@@ -46,11 +46,11 @@ After creating a bundle, **manually update** the `summary.md` file to capture:
 - Relevant next steps
 
 The auto-generated summary is a template. For accurate session documentation,
-edit: `.claude/session/bundles/<bundle-id>/summary.md`
+edit: `$PROJECT_ROOT/.claude/session/bundles/<bundle-id>/summary.md`
 
 ## Alternative: Legacy snapshot (updates existing bundle)
 ```bash
-python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/save_session_snapshot.py
+python3 $PROJECT_ROOT/.claude/session/scripts/save_session_snapshot.py
 ```
 
 - Updates an existing bundle with current active context only
@@ -59,23 +59,23 @@ python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/save_sessi
 ## Flujo detallado (opcional)
 Si prefieres hacerlo paso a paso o necesitas crear un nuevo bundle antes de guardar:
 
-1. **Crear/actualizar bundle**  
+1. **Crear/actualizar bundle**
    Ejecuta cualquier comando del agente (p.ej. `/analizer T010`) para que el hook `subagent_stop` genere un bundle fresco.
 
 2. **Inspeccionar bundles disponibles**
    ```bash
-   python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/session-manager.py list
+   python3 $PROJECT_ROOT/.claude/session/scripts/session-manager.py list
    ```
 
 3. **Copiar contexto activo al bundle deseado**
    ```bash
-   python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/save_session_snapshot.py --bundle-id <bundle-id>
+   python3 $PROJECT_ROOT/.claude/session/scripts/save_session_snapshot.py --bundle-id <bundle-id>
    ```
 
 4. **(Opcional) Empaquetar para compartir**
    ```bash
-   tar -czf /home/jaguilar/aaxis/rnd/repositories/.claude/session/bundles/<bundle-id>.tar.gz \
-     -C /home/jaguilar/aaxis/rnd/repositories/.claude/session/bundles/<bundle-id> .
+   tar -czf $PROJECT_ROOT/.claude/session/bundles/<bundle-id>.tar.gz \
+     -C $PROJECT_ROOT/.claude/session/bundles/<bundle-id> .
    ```
 
 ## Notes

package/commands/session-status.md

@@ -6,7 +6,7 @@ This command provides an intelligent overview of your current session state and
 
 ## Quick status check
 ```bash
-python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/session_startup_check.py
+python3 $PROJECT_ROOT/.claude/session/scripts/session_startup_check.py
 ```
 
 Shows:

package/commands/speckit.specify.md

@@ -31,32 +31,23 @@ Given those arguments, do this:
 
    ```python
    import sys
-   sys.path.insert(0, '/home/jaguilar/aaxis/rnd/repositories/.claude/tools')
-   from clarify_engine import request_clarification, process_clarification
+   sys.path.insert(0, '.claude/tools')
+   from clarification import execute_workflow
 
-   # Detect ambiguity in feature description
-   clarification_data = request_clarification(
+   # Detect and resolve ambiguity in feature description
+   result = execute_workflow(
        user_prompt=feature_description,
-       command_context={"command": "speckit.specify"}
+       command_context={"command": "speckit.specify"},
+       ask_user_question_func=AskUserQuestion  # Claude Code tool
    )
 
-   if clarification_data["needs_clarification"]:
-       # Present summary
-       print(clarification_data["summary"])
+   # Use enriched description for remaining steps
+   feature_description = result["enriched_prompt"]
 
-       # Ask questions (AskUserQuestion tool)
-       response = AskUserQuestion(**clarification_data["question_config"])
-
-       # Enrich feature description
-       result = process_clarification(
-           clarification_data["engine_instance"],
-           feature_description,
-           response["answers"],
-           clarification_data["clarification_context"]
-       )
-
-       # Use enriched description for remaining steps
-       feature_description = result["enriched_prompt"]
+   # Log clarification if it occurred
+   if result["clarification_occurred"]:
+       from clarification import get_clarification_summary
+       print(get_clarification_summary(result["clarification_data"]))
    ```
 
    **What gets clarified**:

package/config/agent-catalog.md

@@ -367,9 +367,9 @@ Task(
     description="Analyze routing accuracy",
     prompt="""
 ## System Context
-- Agent system: /home/jaguilar/aaxis/rnd/repositories/.claude/
-- Logs: /home/jaguilar/aaxis/rnd/repositories/.claude/logs/
-- Tools: /home/jaguilar/aaxis/rnd/repositories/.claude/tools/
+- Agent system: $PROJECT_ROOT/.claude/
+- Logs: $PROJECT_ROOT/.claude/logs/
+- Tools: $PROJECT_ROOT/.claude/tools/
 
 ## Task
 Analyze routing accuracy over last 100 invocations. Propose improvements.

package/config/clarification_rules.json

@@ -0,0 +1,152 @@
+{
+  "version": "1.1.0",
+  "description": "Clarification system configuration for generic ambiguity detection",
+
+  "global_settings": {
+    "enabled": true,
+    "ambiguity_threshold": 30,
+    "max_questions_per_clarification": 5,
+    "skip_readonly_threshold": 50,
+    "cache_results": true,
+    "cache_ttl_seconds": 300
+  },
+
+  "entity_types": {
+    "service": {
+      "enabled": true,
+      "weight": 80,
+      "keywords": [
+        "the api",
+        "el api",
+        "la api",
+        "api service",
+        "the service",
+        "el servicio",
+        "la aplicación",
+        "the app",
+        "la app",
+        "the web",
+        "web service",
+        "the bot",
+        "el bot"
+      ]
+    },
+    "namespace": {
+      "enabled": true,
+      "weight": 60,
+      "keywords": [
+        "namespace",
+        "deploy to",
+        "desplegar en",
+        "in namespace",
+        "en el namespace",
+        "en el namespace",
+        "in the namespace"
+      ]
+    },
+    "cluster": {
+      "enabled": true,
+      "weight": 70,
+      "keywords": [
+        "cluster",
+        "clúster",
+        "in cluster",
+        "to cluster"
+      ]
+    },
+    "environment": {
+      "enabled": true,
+      "weight": 90,
+      "keywords": [
+        "production",
+        "prod",
+        "producción",
+        "staging",
+        "dev",
+        "development"
+      ]
+    },
+    "resource": {
+      "enabled": true,
+      "weight": 70,
+      "keywords": [
+        "the redis",
+        "el redis",
+        "redis instance",
+        "the database",
+        "la database",
+        "la base de datos",
+        "the postgres",
+        "el postgres",
+        "database"
+      ]
+    }
+  },
+
+  "skip_clarification": {
+    "if_command_is_slash": true,
+    "if_high_specificity": true,
+    "specificity_threshold": 0.8,
+    "if_readonly_and_low_ambiguity": true
+  },
+
+  "emoji_map": {
+    "service": "📦",
+    "namespace": "🎯",
+    "cluster": "🏢",
+    "environment": "⚠️",
+    "resource": "🔧",
+    "all": "🌐",
+    "database": "🗄️",
+    "production": "🔴",
+    "staging": "🟡",
+    "development": "🟢"
+  },
+
+  "question_templates": {
+    "service": "¿Qué servicio quieres usar?",
+    "namespace": "¿En qué namespace?",
+    "cluster": "¿En qué cluster?",
+    "environment": "¿En qué entorno?",
+    "resource": "¿Qué recurso?"
+  },
+
+  "header_templates": {
+    "service": "Servicio",
+    "namespace": "Namespace",
+    "cluster": "Cluster",
+    "environment": "Entorno",
+    "resource": "Recurso"
+  },
+
+  "default_option": {
+    "label_all": "Todos",
+    "description_template": "Aplicar a todos ({count} total)",
+    "apply_to_entities": [
+      "service",
+      "namespace",
+      "cluster"
+    ]
+  },
+
+  "performance": {
+    "max_analysis_time_ms": 150,
+    "max_context_search_time_ms": 100,
+    "max_question_generation_time_ms": 100,
+    "parallel_search": false
+  },
+
+  "logging": {
+    "enabled": true,
+    "log_file": ".claude/logs/clarifications.jsonl",
+    "log_level": "info",
+    "log_format": "jsonl"
+  },
+
+  "notes": {
+    "project_context_path": ".claude/project-context/project-context.json",
+    "search_strategy": "project-context-only",
+    "filesystem_search": false,
+    "filesystem_fallback": false
+  }
+}

package/config/context-contracts.md

@@ -164,19 +164,19 @@ terraform-architect:
     },
     "terraform_infrastructure": {
       "layout": {
-        "base_path": "/home/jaguilar/aaxis/rnd/repositories/ops/terraform",
-        "modules_path": "/home/jaguilar/aaxis/rnd/repositories/ops/terraform/modules",
-        "environments_path": "/home/jaguilar/aaxis/rnd/repositories/ops/terraform/environments"
+        "base_path": "$PROJECT_ROOT/ops/terraform",
+        "modules_path": "$PROJECT_ROOT/ops/terraform/modules",
+        "environments_path": "$PROJECT_ROOT/ops/terraform/environments"
       },
       "provider_credentials": {
-        "gcp_credentials_path": "/home/jaguilar/.config/gcloud/aaxis-rnd-terraform-sa.json"
+        "gcp_credentials_path": "$HOME/.config/gcloud/aaxis-rnd-terraform-sa.json"
       }
     },
     "operational_guidelines": {
       "commit_standards": {
         "validation_required": true,
-        "validator_path": "/home/jaguilar/aaxis/rnd/repositories/.claude/tools/commit_validator.py",
-        "config_path": "/home/jaguilar/aaxis/rnd/repositories/.claude/config/git_standards.json"
+        "validator_path": "$PROJECT_ROOT/.claude/tools/commit_validator.py",
+        "config_path": "$PROJECT_ROOT/.claude/config/git_standards.json"
       }
     }
   },
@@ -267,7 +267,7 @@ gitops-operator:
     },
     "gitops_configuration": {
       "repository": {
-        "path": "/home/jaguilar/aaxis/rnd/repositories/gitops/non-prod-rnd-gke-gitops",
+        "path": "$PROJECT_ROOT/gitops/non-prod-rnd-gke-gitops",
         "remote_url": "git@github.com:aaxis/non-prod-rnd-gke-gitops.git",
         "branch": "main"
       },
@@ -283,8 +283,8 @@ gitops-operator:
     "operational_guidelines": {
       "commit_standards": {
         "validation_required": true,
-        "validator_path": "/home/jaguilar/aaxis/rnd/repositories/.claude/tools/commit_validator.py",
-        "config_path": "/home/jaguilar/aaxis/rnd/repositories/.claude/config/git_standards.json"
+        "validator_path": "$PROJECT_ROOT/.claude/tools/commit_validator.py",
+        "config_path": "$PROJECT_ROOT/.claude/config/git_standards.json"
       }
     }
   },
@@ -376,12 +376,12 @@ gcp-troubleshooter:
     },
     "terraform_infrastructure": {
       "layout": {
-        "base_path": "/home/jaguilar/aaxis/rnd/repositories/ops/terraform"
+        "base_path": "$PROJECT_ROOT/ops/terraform"
       }
     },
     "gitops_configuration": {
       "repository": {
-        "path": "/home/jaguilar/aaxis/rnd/repositories/gitops/non-prod-rnd-gke-gitops"
+        "path": "$PROJECT_ROOT/gitops/non-prod-rnd-gke-gitops"
       }
     }
   },
@@ -500,8 +500,8 @@ devops-developer:
     "operational_guidelines": {
       "commit_standards": {
         "validation_required": true,
-        "validator_path": "/home/jaguilar/aaxis/rnd/repositories/.claude/tools/commit_validator.py",
-        "config_path": "/home/jaguilar/aaxis/rnd/repositories/.claude/config/git_standards.json"
+        "validator_path": "$PROJECT_ROOT/.claude/tools/commit_validator.py",
+        "config_path": "$PROJECT_ROOT/.claude/config/git_standards.json"
       }
     }
   },
@@ -567,11 +567,11 @@ Task(
 ## System Context
 
 **System Paths:**
-- Agent system: /home/jaguilar/aaxis/rnd/repositories/.claude/
-- Orchestrator: /home/jaguilar/aaxis/rnd/repositories/CLAUDE.md
-- Logs: /home/jaguilar/aaxis/rnd/repositories/.claude/logs/
-- Tools: /home/jaguilar/aaxis/rnd/repositories/.claude/tools/
-- Tests: /home/jaguilar/aaxis/rnd/repositories/.claude/tests/
+- Agent system: $PROJECT_ROOT/.claude/
+- Orchestrator: $PROJECT_ROOT/CLAUDE.md
+- Logs: $PROJECT_ROOT/.claude/logs/
+- Tools: $PROJECT_ROOT/.claude/tools/
+- Tests: $PROJECT_ROOT/.claude/tests/
 
 **System Knowledge:**
 - 5 specialist agents: terraform-architect, gitops-operator, gcp-troubleshooter, aws-troubleshooter, devops-developer

package/config/git-standards.md

@@ -17,7 +17,7 @@ This document defines the universal commit message standards for this repository
 
 ```python
 import sys
-sys.path.insert(0, '/home/jaguilar/aaxis/rnd/repositories/.claude/tools')
+sys.path.insert(0, '$PROJECT_ROOT/.claude/tools')
 from commit_validator import safe_validate_before_commit
 
 # Validate commit message
@@ -463,7 +463,7 @@ Specialist agents perform git commits for:
 
 ### commit_validator.py
 
-Located at: `/home/jaguilar/aaxis/rnd/repositories/.claude/tools/commit_validator.py`
+Located at: `$PROJECT_ROOT/.claude/tools/commit_validator.py`
 
 **Functions:**