@jaguilar87/gaia-ops 2.2.2 → 2.2.3

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.2.3] - 2025-11-11
+
+### Fixed - Deterministic Project Context Location
+- **context_provider.py**
+  - Always reads `.claude/project-context/project-context.json` (no fallback to legacy paths)
+  - Removed legacy auto-detection logic and unused imports
+  - Prevents “Context file not found” errors when projects only use the new structure
+- **templates/CLAUDE.template.md**
+  - Rule 1 clarifies when to delegate vs. self-execute
+  - Rule 2 explicitly documents the `context_provider.py --context-file .claude/project-context/project-context.json …` invocation
+  - Workflow summary now references orchestration docs after the table (cleaner render)
+
+### Changed - CLI Documentation & Version Alignment
+- **README.md / README.en.md**
+  - Documented the exact `npx` commands (`npx gaia-init` / `npx @jaguilar87/gaia-ops`) and clarified installation steps
+  - Updated “Current version” badges to **2.2.3**
+- **package.json**
+  - Bumped package version to `2.2.3`
+
+### Benefits
+- ✅ No manual tweaks needed to point `context_provider.py` at the correct project context
+- ✅ CLAUDE template now tells the orchestrator exactly how to invoke the context provider
+- ✅ README instructions reflect the real CLI entry points, reducing confusion for new installs
+
 ---
 
 ## [2.2.2] - 2025-11-11
@@ -591,9 +615,9 @@ contract_keys = contracts["agents"][agent_name]["required"]  # Provider-specific
 
 **Recommended:**
 
-- Read `.claude/docs/orchestration-workflow.md` to understand full Phase 0-6 workflow
-- Review `.claude/docs/git-standards.md` for complete commit standards
-- Check `.claude/docs/agent-catalog.md` for detailed agent capabilities
+- Read `.claude/config/orchestration-workflow.md` to understand full Phase 0-6 workflow
+- Review `.claude/config/git-standards.md` for complete commit standards
+- Check `.claude/config/agent-catalog.md` for detailed agent capabilities
 
 ---
 
@@ -624,8 +648,8 @@ contract_keys = contracts["agents"][agent_name]["required"]  # Provider-specific
    - Add entry to this CHANGELOG under "Unreleased"
 
 2. **For new sections or features:**
-   - Decide if belongs in `CLAUDE.md` (core instructions) or `.claude/docs/*.md` (details)
-   - If modular doc, create/update appropriate file in `.claude/docs/`
+   - Decide if belongs in `CLAUDE.md` (core instructions) or `.claude/config/*.md` (details)
+   - If modular doc, create/update appropriate file in `.claude/config/`
    - If core instruction, update `CLAUDE.md` and add reference to modular doc
    - Increment MINOR version in frontmatter
    - Add entry to this CHANGELOG under "Unreleased"

package/README.en.md

@@ -30,7 +30,11 @@ Multi-agent orchestration system for Claude Code - DevOps automation toolkit.
 Use the built-in interactive installer to set up Gaia-Ops in any project:
 
 ```bash
-npx @jaguilar87/gaia-ops init
+# Option 1: run the binary directly via npx
+npx gaia-init
+
+# Option 2: specify the npm package explicitly
+npx @jaguilar87/gaia-ops
 ```
 
 Or if installed globally:
@@ -189,7 +193,7 @@ This package follows [Semantic Versioning](https://semver.org/):
 - **MINOR:** New features, agents, or improvements
 - **PATCH:** Bug fixes, clarifications, typos
 
-Current version: **2.2.0**
+Current version: **2.2.3**
 
 See [CHANGELOG.md](./CHANGELOG.md) for version history.
 

package/README.md

@@ -30,7 +30,11 @@ Sistema de orquestación multi-agente para Claude Code - Toolkit de automatizaci
 Usa el instalador interactivo integrado para configurar Gaia-Ops en cualquier proyecto:
 
 ```bash
-npx @jaguilar87/gaia-ops init
+# Opción 1: Ejecutar directamente con npx
+npx gaia-init
+
+# Opción 2: Si prefieres especificar el paquete completo
+npx @jaguilar87/gaia-ops
 ```
 
 O si lo instalas globalmente:
@@ -185,11 +189,11 @@ const configPath = getConfigPath('orchestration-workflow.md');
 
 Este paquete sigue [Versionamiento Semántico](https://semver.org/):
 
-- **MAJOR:** Cambios que rompen compatibilidad en el comportamiento del orquestador
-- **MINOR:** Nuevas características, agentes o mejoras
-- **PATCH:** Correcciones de bugs, clarificaciones, errores tipográficos
+    - **MAJOR:** Cambios que rompen compatibilidad en el comportamiento del orquestador
+    - **MINOR:** Nuevas características, agentes o mejoras
+    - **PATCH:** Correcciones de bugs, clarificaciones, errores tipográficos
 
-Versión actual: **2.2.0**
+    Versión actual: **2.2.3**
 
 Ver [CHANGELOG.md](./CHANGELOG.md) para el historial de versiones.
 

package/config/AGENTS.md

@@ -80,7 +80,7 @@ Claude Code (Orchestrator)
 - Route user requests to specialist agents
 - Provision context via `context_provider.py`
 - Enforce approval gates for T3 operations
-- Update system SSOTs (project-context.json, tasks.md)
+- Update system SSOTs (.claude/project-context/project-context.json, tasks.md)
 - Handle simple operations directly (ad-hoc commits, queries)
 
 **Agent responsibilities:**
@@ -94,12 +94,12 @@ Claude Code (Orchestrator)
 ## Documentation Structure
 
 ```
-/home/jaguilar/aaxis/rnd/repositories/
+<project-root>/
 ├── CLAUDE.md (core orchestrator instructions, 196 lines)
 ├── AGENTS.md (this file, compatibility layer)
 ├── .claude/
 │   ├── CHANGELOG.md (version history)
-│   ├── docs/
+│   ├── config/
 │   │   ├── orchestration-workflow.md (Phase 0-6 details)
 │   │   ├── git-standards.md (commit standards)
 │   │   ├── context-contracts.md (agent context requirements)
@@ -107,8 +107,9 @@ Claude Code (Orchestrator)
 │   ├── agents/ (agent definitions)
 │   ├── tools/ (context_provider.py, agent_router.py, etc.)
 │   ├── logs/ (audit trail, metrics)
-│   └── tests/ (test suite)
-└── .claude/project-context.json (SSOT for infrastructure state)
+│   ├── tests/ (test suite)
+│   └── project-context/
+│       └── project-context.json (SSOT for infrastructure state)
 ```
 
 ---
@@ -117,7 +118,7 @@ Claude Code (Orchestrator)
 
 1. **Read CLAUDE.md** (5 min) - Understand core principles and workflow
 2. **Review agent catalog** (10 min) - See available agents and capabilities
-3. **Check project context** (5 min) - Review `.claude/project-context.json` for current infrastructure state
+3. **Check project context** (5 min) - Review `.claude/project-context/project-context.json` for current infrastructure state
 4. **Run sample workflow** (15 min) - Test orchestrator with a simple task
 
 **Sample workflow:**
@@ -145,7 +146,7 @@ See `CLAUDE.md` and `.claude/CHANGELOG.md` for contribution guidelines.
 **Key rules:**
 - All commits MUST follow Conventional Commits (enforced by `commit_validator.py`)
 - Changes to infrastructure/deployments require approval gate (Phase 4)
-- Update SSOTs after realization (project-context.json, tasks.md)
+- Update SSOTs after realization (.claude/project-context/project-context.json, tasks.md)
 
 ---
 

package/index.js

@@ -54,17 +54,6 @@ export function getCommandPath(commandName) {
   return join(PACKAGE_ROOT, 'commands', commandName);
 }
 
-/**
- * Get absolute path to documentation
- * @deprecated Use getConfigPath() instead. Documentation moved from docs/ to config/ in v2.0.0
- * @param {string} docName - Name of the doc (e.g., 'orchestration-workflow.md')
- * @returns {string} Absolute path to doc file
- */
-export function getDocPath(docName) {
-  console.warn('getDocPath() is deprecated. Use getConfigPath() instead. Documentation is now in config/ directory.');
-  return join(PACKAGE_ROOT, 'config', docName);
-}
-
 /**
  * Get absolute path to a template
  * @param {string} templateName - Name of the template (e.g., 'CLAUDE.template.md')
@@ -89,7 +78,6 @@ export default {
   getToolPath,
   getHookPath,
   getCommandPath,
-  getDocPath,
   getTemplatePath,
   getConfigPath
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaguilar87/gaia-ops",
-  "version": "2.2.2",
+  "version": "2.2.3",
   "description": "Multi-agent orchestration system for Claude Code - DevOps automation toolkit",
   "main": "index.js",
   "type": "module",

package/templates/CLAUDE.template.md

@@ -1,21 +1,14 @@
-# CLAUDE.md
-
-Guidance for Claude Code orchestrator working in this repository.
-
-## Language Policy
-
-- **Technical Documentation:** All code, commits, technical documentation, and system artifacts MUST be in English.
-- **Chat Interactions:** Always respond to users in the same language used during chat conversations.
-
 ## Core Operating Principles
 
-### Rule 1.0 [P0]: Selective Delegation
-- **COMPLEX workflows** (investiogatiops, multi-step, infrastructure, deployments) → Delegate to specialist agents
-- **SIMPLE operations** (atomic commits, file edits) → Execute directly
-- **Default:** When in doubt, delegate (safer)
+### Rule 1.0 [P0]: Delegate Anything Non-Atomic
+- **Always delegate** investigations, multi-file edits, Terraform/Helm/K8s/GitOps actions, or anything needing approval / T2-T3 access.
+- **Only execute yourself** when it’s a truly atomic, low-risk step (single-file edit, log read, simple status query).
+- If you choose not to delegate, say why it is safe to keep it local.
+
+❌ Never self-execute chained workflows or infrastructure-impacting changes.
 
 ### Rule 2.0 [P0]: Context Provisioning
-- Use `context_provider.py` to build agent payload (ONLY for project agents)
+- Project agents must receive `context_provider.py --context-file .claude/project-context/project-context.json …`
 - Meta-agents receive manual context in prompt
 
 ### Rule 3.0 [P0]: Two-Phase Workflow for Infrastructure
@@ -30,8 +23,6 @@ Guidance for Claude Code orchestrator working in this repository.
 
 ## Orchestrator Workflow
 
-**See:** `.claude/config/orchestration-workflow.md` for complete details.
-
 ### Rule 5.0 [P0]: Six-Phase Workflow
 
 | Phase | Action | Tool | Mandatory |
@@ -44,6 +35,8 @@ Guidance for Claude Code orchestrator working in this repository.
 | 5 | Realization | `Task` tool (re-invoke) | Yes |
 | 6 | Update SSOT | Edit `project-context.json`, `tasks.md` | Yes |
 
+**See:** `.claude/config/orchestration-workflow.md` for complete details.
+
 ### Rule 5.1 [P0]: Approval Gate Enforcement
 - Phase 4 CANNOT be skipped for T3 operations
 - Phase 5 requires `validation["approved"] == True`
@@ -154,3 +147,10 @@ Guidance for Claude Code orchestrator working in this repository.
 - **Context contracts:** `.claude/config/context-contracts.md`
 - **Agent catalog:** `.claude/config/agent-catalog.md`
 - **Package source:** `@jaguilar87/gaia-ops` (npm package)
+
+## Language Policy
+
+- **Technical Documentation:** All code, commits, technical documentation, and system artifacts MUST be in English.
+- **Chat Interactions:** Always respond to users in the same language used during chat conversations.
+
+

package/tools/context_provider.py

@@ -1,35 +1,12 @@
 import json
 import argparse
 import sys
-import os
 from pathlib import Path
 from typing import Dict, List, Any, Optional
 
 # This script is expected to be run from the root of the repository.
-# Historically the project context lived at `.claude/project-context.json`, but
-# newer installs keep it under `.claude/project-context/project-context.json`.
-# We auto-detect the most common locations (and honor GAIA_CONTEXT_PATH) so agent
-# routing never breaks if the file isn't symlinked to the legacy path.
-def get_default_context_path() -> Path:
-    """Detects the project-context.json location, honoring GAIA_CONTEXT_PATH."""
-    env_override = os.environ.get("GAIA_CONTEXT_PATH")
-    if env_override:
-        return Path(env_override).expanduser()
-
-    candidates = [
-        Path(".claude/project-context.json"),
-        Path(".claude/project-context/project-context.json"),
-        Path("project-context.json"),
-    ]
-
-    for candidate in candidates:
-        if candidate.is_file():
-            return candidate
-
-    # Fall back to the legacy expectation; load_project_context will surface error
-    return candidates[0]
-
-DEFAULT_CONTEXT_PATH = get_default_context_path()
+# Project context is always stored at `.claude/project-context/project-context.json`.
+DEFAULT_CONTEXT_PATH = Path(".claude/project-context/project-context.json")
 
 # Path to provider-specific contract files
 # When running from installed project: .claude/config (symlinked)