@jaguilar87/gaia-ops 2.2.0 → 2.2.1

package/CHANGELOG.md

@@ -7,6 +7,68 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [2.2.1] - 2025-11-10
+
+### Fixed - Documentation Consistency
+- **README.md & README.en.md:**
+  - Updated version numbers from 2.1.0 → 2.2.0
+  - Corrected package structure (hooks/, templates/, commands/)
+  - Fixed hooks/ listing: now shows actual Python files (pre_tool_use.py, post_tool_use.py, etc.) instead of non-existent pre-commit
+  - Fixed templates/ listing: removed non-existent code-examples/, listed actual files (CLAUDE.template.md, settings.template.json)
+  - Added context-contracts.gcp.json and context-contracts.aws.json to config/ section
+  - Removed CLAUDE.md and AGENTS.md from package root (only templates exist)
+  - Added speckit/ directory to structure
+
+- **config/AGENTS.md:**
+  - Updated all references: `.claude/docs/` → `.claude/config/`
+  - Fixed quick links and support documentation paths
+
+- **config/agent-catalog.md:**
+  - Updated all 5 context contract references: `.claude/docs/` → `.claude/config/`
+
+- **index.js:**
+  - Deprecated `getDocPath()` function with console warning
+  - Function now redirects to `config/` directory instead of non-existent `docs/`
+  - Added JSDoc @deprecated annotation
+
+- **README.en.md (Documentation section):**
+  - Removed broken reference to `./CLAUDE.md` (file not in package)
+  - Fixed all documentation links: `./docs/` → `./config/`
+  - Updated to match actual config/ directory structure
+
+- **speckit/README.en.md:**
+  - Removed 3 non-existent commands: speckit.clarify, speckit.analyze-plan, speckit.constitution
+  - Updated command count: 9 → 7 actual commands
+  - Removed references to non-existent tasks-richer.py tool
+  - Removed entire sections for non-existent templates (data-model-template.md, contracts-template.md)
+  - Updated tool files list with actual tools (task_manager.py, clarify_engine.py, context_provider.py)
+  - Fixed all code examples to use only existing commands
+
+- **tools/context_provider.py:**
+  - Added auto-detection for project-context.json location
+  - Honors GAIA_CONTEXT_PATH environment variable
+  - Falls back through common locations (.claude/project-context.json, .claude/project-context/project-context.json)
+  - Fixes agent routing failures when project-context.json is in non-legacy location
+
+- **package.json:**
+  - Fixed `npm test` script (was calling non-existent pytest tests)
+  - Now echoes informative message about fixture availability
+
+- **Agent Branding Unification:**
+  - Renamed `agents/claude-architect.md` → `agents/gaia.md` (aligns with gaia-ops package name)
+  - Renamed `commands/gaina.md` → `commands/gaia.md` (unified as `/gaia` command)
+  - Updated all references in README.md, README.en.md, and agents/gaia.md
+  - Complete branding consistency: package name, agent name, and command name all use "gaia"
+
+### Benefits
+- ✅ **Accurate documentation:** All paths and structures match actual package contents
+- ✅ **No broken links:** References point to existing files
+- ✅ **Clear API:** Deprecated functions clearly marked
+- ✅ **User trust:** Documentation matches reality
+- ✅ **npm test passes:** No false failures
+
+---
+
 ## [2.2.0] - 2025-11-10
 
 ### Added - Unified Settings Template & Auto-Installation
@@ -46,7 +108,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Updated header and JSDoc comments with new package name
   - Updated example usage
 
-- **agents/claude-architect.md:**
+- **agents/gaia.md:**
   - Updated system paths to reflect gaia-ops package structure
   - Clarified symlink architecture and layout
 

package/README.en.md

@@ -15,8 +15,8 @@ Multi-agent orchestration system for Claude Code - DevOps automation toolkit.
 ### Features
 
 - **Multi-cloud support** - Works with GCP, AWS, and ready for Azure
-- **6 specialist agents** (terraform-architect, gitops-operator, gcp-troubleshooter, aws-troubleshooter, devops-developer, claude-architect)
-- **3 meta-agents** (Explore, Plan, claude-architect)
+- **6 specialist agents** (terraform-architect, gitops-operator, gcp-troubleshooter, aws-troubleshooter, devops-developer, Gaia)
+- **3 meta-agents** (Explore, Plan, Gaia)
 - **Clarification engine** for ambiguity detection
 - **Approval gates** for T3 operations (terraform apply, kubectl apply, etc.)
 - **Git commit validation** with Conventional Commits
@@ -91,7 +91,7 @@ node_modules/@jaguilar87/gaia-ops/
 │   ├── gcp-troubleshooter.md
 │   ├── aws-troubleshooter.md
 │   ├── devops-developer.md
-│   └── claude-architect.md
+│   └── gaia.md
 ├── tools/               # Orchestration tools
 │   ├── context_provider.py
 │   ├── agent_router.py
@@ -99,28 +99,35 @@ node_modules/@jaguilar87/gaia-ops/
 │   ├── approval_gate.py
 │   ├── commit_validator.py
 │   └── task_manager.py
-├── hooks/               # Git hooks
-│   └── pre-commit
+├── hooks/               # Claude Code hooks (Python)
+│   ├── pre_tool_use.py
+│   ├── post_tool_use.py
+│   ├── subagent_stop.py
+│   ├── session_start.py
+│   └── pre_kubectl_security.py
 ├── commands/            # Slash commands
-│   ├── architect.md
-│   └── speckit.*.md
+│   ├── gaia.md
+│   ├── save-session.md
+│   ├── restore-session.md
+│   ├── session-status.md
+│   └── speckit.*.md (7 commands)
 ├── config/              # Configuration & documentation
 │   ├── AGENTS.md
 │   ├── orchestration-workflow.md
 │   ├── git-standards.md
 │   ├── context-contracts.md
+│   ├── context-contracts.gcp.json
+│   ├── context-contracts.aws.json
 │   ├── agent-catalog.md
 │   └── git_standards.json
-├── templates/           # Code templates
+├── templates/           # Installation templates
 │   ├── CLAUDE.template.md
-│   └── code-examples/
-│       ├── commit_validation.py
-│       ├── clarification_workflow.py
-│       └── approval_gate_workflow.py
-├── config/              # Configuration
-│   └── git_standards.json
-├── CLAUDE.md            # Core orchestrator instructions
-├── AGENTS.md            # System overview
+│   └── settings.template.json
+├── speckit/             # Spec-Kit methodology
+│   ├── README.md
+│   ├── templates/
+│   ├── scripts/
+│   └── governance.md
 ├── CHANGELOG.md         # Version history
 ├── package.json
 └── index.js             # Helper functions
@@ -182,18 +189,17 @@ This package follows [Semantic Versioning](https://semver.org/):
 - **MINOR:** New features, agents, or improvements
 - **PATCH:** Bug fixes, clarifications, typos
 
-Current version: **2.1.0**
+Current version: **2.2.0**
 
 See [CHANGELOG.md](./CHANGELOG.md) for version history.
 
 ## Documentation
 
-- **Core Instructions:** [CLAUDE.md](./CLAUDE.md) (154 lines)
-- **System Overview:** [AGENTS.md](./AGENTS.md) (95 lines)
-- **Orchestration Workflow:** [docs/orchestration-workflow.md](./docs/orchestration-workflow.md) (735 lines)
-- **Git Standards:** [docs/git-standards.md](./docs/git-standards.md) (682 lines)
-- **Context Contracts:** [docs/context-contracts.md](./docs/context-contracts.md) (673 lines)
-- **Agent Catalog:** [docs/agent-catalog.md](./docs/agent-catalog.md) (603 lines)
+- **System Overview:** [config/AGENTS.md](./config/AGENTS.md) (95 lines)
+- **Orchestration Workflow:** [config/orchestration-workflow.md](./config/orchestration-workflow.md) (735 lines)
+- **Git Standards:** [config/git-standards.md](./config/git-standards.md) (682 lines)
+- **Context Contracts:** [config/context-contracts.md](./config/context-contracts.md) (673 lines)
+- **Agent Catalog:** [config/agent-catalog.md](./config/agent-catalog.md) (603 lines)
 
 ## Requirements
 

package/README.md

@@ -15,8 +15,8 @@ Sistema de orquestación multi-agente para Claude Code - Toolkit de automatizaci
 ### Características
 
 - **Soporte multi-cloud** - Funciona con GCP, AWS, y listo para Azure
-- **6 agentes especialistas** (terraform-architect, gitops-operator, gcp-troubleshooter, aws-troubleshooter, devops-developer, claude-architect)
-- **3 meta-agentes** (Explore, Plan, claude-architect)
+- **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
 - **Puertas de aprobación** para operaciones T3 (terraform apply, kubectl apply, etc.)
 - **Validación de commits Git** con Conventional Commits
@@ -91,7 +91,7 @@ node_modules/@jaguilar87/gaia-ops/
 │   ├── gcp-troubleshooter.md
 │   ├── aws-troubleshooter.md
 │   ├── devops-developer.md
-│   └── claude-architect.md
+│   └── gaia.md
 ├── tools/               # Herramientas de orquestación
 │   ├── context_provider.py
 │   ├── agent_router.py
@@ -99,28 +99,35 @@ node_modules/@jaguilar87/gaia-ops/
 │   ├── approval_gate.py
 │   ├── commit_validator.py
 │   └── task_manager.py
-├── hooks/               # Git hooks
-│   └── pre-commit
+├── hooks/               # Hooks de Claude Code (Python)
+│   ├── pre_tool_use.py
+│   ├── post_tool_use.py
+│   ├── subagent_stop.py
+│   ├── session_start.py
+│   └── pre_kubectl_security.py
 ├── commands/            # Comandos slash
-│   ├── architect.md
-│   └── speckit.*.md
+│   ├── gaia.md
+│   ├── save-session.md
+│   ├── restore-session.md
+│   ├── session-status.md
+│   └── speckit.*.md (7 comandos)
 ├── config/              # Configuración y documentación
 │   ├── AGENTS.md
 │   ├── orchestration-workflow.md
 │   ├── git-standards.md
 │   ├── context-contracts.md
+│   ├── context-contracts.gcp.json
+│   ├── context-contracts.aws.json
 │   ├── agent-catalog.md
 │   └── git_standards.json
-├── templates/           # Plantillas de código
+├── templates/           # Templates de instalación
 │   ├── CLAUDE.template.md
-│   └── code-examples/
-│       ├── commit_validation.py
-│       ├── clarification_workflow.py
-│       └── approval_gate_workflow.py
-├── config/              # Configuración
-│   └── git_standards.json
-├── CLAUDE.md            # Instrucciones del orquestador principal
-├── AGENTS.md            # Vista general del sistema
+│   └── settings.template.json
+├── speckit/             # Metodología Spec-Kit
+│   ├── README.md
+│   ├── templates/
+│   ├── scripts/
+│   └── governance.md
 ├── CHANGELOG.md         # Historial de versiones
 ├── package.json
 └── index.js             # Funciones auxiliares
@@ -182,7 +189,7 @@ Este paquete sigue [Versionamiento Semántico](https://semver.org/):
 - **MINOR:** Nuevas características, agentes o mejoras
 - **PATCH:** Correcciones de bugs, clarificaciones, errores tipográficos
 
-Versión actual: **2.1.0**
+Versión actual: **2.2.0**
 
 Ver [CHANGELOG.md](./CHANGELOG.md) para el historial de versiones.
 

package/agents/{claude-architect.md → gaia.md}

@@ -1,11 +1,11 @@
 ---
-name: claude-architect
-description: A meta-agent specialized in analyzing, diagnosing, and optimizing the intelligent agent orchestration system itself. It understands the system architecture, analyzes logs/metrics, researches best practices, and proposes improvements.
+name: gaia
+description: Gaia is the meta-agent for the gaia-ops ecosystem—its purpose is to understand, document, and continuously optimize every component of the orchestrator, agents, commands, templates, sample stacks, and documentation that ship in this package and the consuming projects that symlink to it.
 tools: Read, Glob, Grep, Bash, Task, WebSearch, Python
 model: inherit
 ---
 
-You are a senior system architect and AI agent systems specialist. Your unique purpose is to **analyze and optimize the intelligent agent orchestration system itself** - acting as a meta-layer that understands how the orchestrator, agents, router, context provider, and all system components work together.
+You are Gaia, the senior system architect and AI agent systems specialist for the gaia-ops stack. Your unique purpose is to **analyze and optimize Gaia’s intelligent agent orchestration system end-to-end**—acting as a meta-layer that understands how the orchestrator, agents, commands, router, context provider, Spec-Kit assets, and all system components work together across repositories (package root, downstream project `.claude/`, ops symlinks).
 
 ## ⚡ QUICK START - Read This First
 
@@ -18,10 +18,10 @@ You are a senior system architect and AI agent systems specialist. Your unique p
 **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, claude-architect)
+- 🤖 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` (`/architect`, `/save-session`, `/session-status`, `/speckit.*`)
+- 🗂️ 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
@@ -73,7 +73,7 @@ gaia-ops/  (mirrors node_modules/@jaguilar87/gaia-ops/ and symlinks into project
 │   ├── gcp-troubleshooter.md
 │   ├── aws-troubleshooter.md
 │   ├── devops-developer.md
-│   └── claude-architect.md
+│   └── gaia.md (this file)
 ├── tools/                          # System intelligence + automation
 │   ├── context_provider.py         # Deterministic context generation
 │   ├── agent_router.py             # Semantic routing (92.7% target accuracy)

package/commands/{architect.md → gaia.md}

@@ -1,13 +1,13 @@
 ---
-description: Invoke claude-architect to analyze system architecture, diagnose issues, or propose improvements
+description: Invoke Gaia to analyze system architecture, diagnose issues, or propose improvements
 scope: project
 ---
 
-You are invoking the **claude-architect** meta-agent to analyze the agent orchestration system itself.
+You are invoking **Gaia**, the gaia-ops meta-agent that analyzes the agent orchestration system itself.
 
 ## Context: System Expert Agent
 
-claude-architect is a specialized agent that understands:
+Gaia is a specialized agent that understands:
 - The entire agent system architecture (.claude/, CLAUDE.md, agents, tools, hooks)
 - Spec-Kit workflows (specify, plan, tasks, implement, add-task, analyze-task)
 - Session management (save, restore, bundles)
@@ -18,7 +18,7 @@ claude-architect is a specialized agent that understands:
 
 ## Your Task
 
-Invoke the claude-architect agent with the user's request. The agent will proactively read system files, analyze logs, research best practices, and provide comprehensive analysis with actionable recommendations.
+Invoke Gaia with the user's request. The agent will proactively read system files, analyze logs, research best practices, and provide comprehensive analysis with actionable recommendations tied to gaia-ops.
 
 **IMPORTANT:** Pass the user's exact question/request to the agent. Examples:
 - "Analiza este log y dime qué pasó"
@@ -29,11 +29,11 @@ Invoke the claude-architect agent with the user's request. The agent will proact
 
 ## Invocation
 
-Use the Task tool to invoke claude-architect with this structure:
+Use the Task tool to invoke Gaia with this structure:
 
 ```
 Task(
-    subagent_type="claude-architect",
+    subagent_type="gaia",
     description="[Brief 3-5 word description]",
     prompt="""
 ## System Context (Auto-provided)

package/config/AGENTS.md

@@ -8,9 +8,9 @@ See `CLAUDE.md` for complete orchestrator instructions.
 
 **Quick links:**
 - Core principles: `CLAUDE.md` (lines 18-36)
-- Workflow: `.claude/docs/orchestration-workflow.md`
-- Git standards: `.claude/docs/git-standards.md`
-- Agent catalog: `.claude/docs/agent-catalog.md`
+- Workflow: `.claude/config/orchestration-workflow.md`
+- Git standards: `.claude/config/git-standards.md`
+- Agent catalog: `.claude/config/agent-catalog.md`
 
 ---
 
@@ -71,7 +71,7 @@ Claude Code (Orchestrator)
     ├── gcp-troubleshooter (GCP diagnostics)
     ├── aws-troubleshooter (AWS diagnostics)
     ├── devops-developer (Application build/test)
-    ├── claude-architect (System optimization)
+    ├── Gaia (System optimization)
     ├── Explore (Codebase exploration)
     └── Plan (Implementation planning)
 ```
@@ -153,7 +153,7 @@ See `CLAUDE.md` and `.claude/CHANGELOG.md` for contribution guidelines.
 
 - **Issues:** Create issue in GitHub repository
 - **Questions:** Contact Jorge Aguilar (jaguilar@aaxis.com)
-- **Documentation:** See `.claude/docs/*.md`
+- **Documentation:** See `.claude/config/*.md`
 
 ---
 

package/config/agent-catalog.md

@@ -30,7 +30,7 @@ These agents work on **CLAUDE CODE SYSTEM ITSELF** (agent orchestration, tooling
 
 | Agent | Primary Role | Context Type | Model |
 |-------|--------------|--------------|-------|
-| **claude-architect** | System analysis & optimization | Manual (logs, .claude/, tests) | inherit |
+| **Gaia** | System analysis & optimization | Manual (gaia-ops package, .claude/, tests) | inherit |
 | **Explore** | Codebase exploration for understanding | Automatic (file patterns) | haiku |
 | **Plan** | Planning mode for implementation design | Automatic (user prompt) | inherit |
 
@@ -82,7 +82,7 @@ These agents work on **CLAUDE CODE SYSTEM ITSELF** (agent orchestration, tooling
 - T2: `terraform plan`
 - T3: `terragrunt apply` (requires approval)
 
-**Context Contract:** See `.claude/docs/context-contracts.md#terraform-architect`
+**Context Contract:** See `.claude/config/context-contracts.md#terraform-architect`
 
 **Use Cases:**
 - "Create a CloudSQL instance with Terraform"
@@ -148,7 +148,7 @@ Task(
 - T2: `git push` to feature branch, `flux reconcile`
 - T3: `kubectl apply`, `git push` to main (requires approval)
 
-**Context Contract:** See `.claude/docs/context-contracts.md#gitops-operator`
+**Context Contract:** See `.claude/config/context-contracts.md#gitops-operator`
 
 **Use Cases:**
 - "Deploy tcm-api service to non-prod cluster"
@@ -214,7 +214,7 @@ Task(
 - T2: `gcloud compute ssh` (for VM diagnostics)
 - T3: None (diagnostic agent, no destructive operations)
 
-**Context Contract:** See `.claude/docs/context-contracts.md#gcp-troubleshooter`
+**Context Contract:** See `.claude/config/context-contracts.md#gcp-troubleshooter`
 
 **Use Cases:**
 - "Why is tcm-api pod crashing with database connection error?"
@@ -270,7 +270,7 @@ Task(
 - T2: `aws ec2 ssh` (for EC2 diagnostics)
 - T3: None (diagnostic agent, no destructive operations)
 
-**Context Contract:** See `.claude/docs/context-contracts.md#aws-troubleshooter`
+**Context Contract:** See `.claude/config/context-contracts.md#aws-troubleshooter`
 
 **Use Cases:**
 - "Why is EKS pod failing with IAM permission error?"
@@ -308,7 +308,7 @@ Task(
 - T2: `git push` to feature branch, `npm publish` (to test registry)
 - T3: `git push` to main (requires approval)
 
-**Context Contract:** See `.claude/docs/context-contracts.md#devops-developer`
+**Context Contract:** See `.claude/config/context-contracts.md#devops-developer`
 
 **Use Cases:**
 - "Run tests and fix failures"
@@ -331,7 +331,7 @@ Task(
 
 ## Meta-Agents: Detailed Catalog
 
-### claude-architect
+### Gaia
 
 **Full Name:** Claude Code System Architect
 
@@ -363,7 +363,7 @@ Task(
 ```python
 # Orchestrator provides manual context in prompt
 Task(
-    subagent_type="claude-architect",
+    subagent_type="gaia",
     description="Analyze routing accuracy",
     prompt="""
 ## System Context
@@ -471,7 +471,7 @@ User Request
 │  └─ YES → devops-developer
 │
 ├─ System/agent analysis?
-│  └─ YES → claude-architect
+│  └─ YES → Gaia
 │
 ├─ Codebase exploration/understanding?
 │  └─ YES → Explore
@@ -488,8 +488,8 @@ User Request
 
 ```python
 # WRONG
-context = context_provider.py("claude-architect", "analyze logs")
-Task(subagent_type="claude-architect", prompt=context)
+context = context_provider.py("gaia", "analyze logs")
+Task(subagent_type="gaia", prompt=context)
 ```
 
 **Why:** Meta-agents work on the SYSTEM, not projects. They need system paths, not project context.
@@ -497,7 +497,7 @@ Task(subagent_type="claude-architect", prompt=context)
 **Correct:**
 ```python
 Task(
-    subagent_type="claude-architect",
+    subagent_type="gaia",
     prompt=f"System path: {system_path}\n\nTask: analyze logs"
 )
 ```
@@ -576,7 +576,7 @@ Track in `.claude/logs/agent-metrics.jsonl`:
 | gcp-troubleshooter | 123 | 98% | 28s | N/A |
 | aws-troubleshooter | 45 | 96% | 31s | N/A |
 | devops-developer | 189 | 92% | 18s | 15% |
-| claude-architect | 34 | 100% | 120s | N/A |
+| Gaia | 34 | 100% | 120s | N/A |
 | Explore | 456 | 99% | 8s | N/A |
 | Plan | 78 | 95% | 22s | N/A |
 
@@ -601,4 +601,4 @@ Track in `.claude/logs/agent-metrics.jsonl`:
 
 ### 1.x (Historical)
 - Embedded in CLAUDE.md
-- Basic agent list with roles
+- Basic agent list with roles

package/config/context-contracts.md

@@ -526,7 +526,7 @@ devops-developer:
 
 ---
 
-## claude-architect (Meta-Agent)
+## Gaia (Meta-Agent)
 
 **Purpose:** Analyzes, diagnoses, and optimizes the agent orchestration system itself
 
@@ -535,7 +535,7 @@ devops-developer:
 ### Manual Context Structure
 
 ```yaml
-claude-architect:
+gaia:
   context_type: "manual"
 
   provided_in_prompt:
@@ -561,7 +561,7 @@ claude-architect:
 
 ```python
 Task(
-    subagent_type="claude-architect",
+    subagent_type="gaia",
     description="Analyze routing accuracy",
     prompt="""
 ## System Context
@@ -714,7 +714,7 @@ if agent_contract_version == "1.0":
 | gcp-troubleshooter | project_details, terraform_infrastructure, gitops_configuration | application_services, issue_context | GCP diagnostics |
 | aws-troubleshooter | project_details, terraform_infrastructure, gitops_configuration | application_services, issue_context | AWS diagnostics |
 | devops-developer | project_details, operational_guidelines | application_services, development_context | App build/test/debug |
-| claude-architect | (manual context in prompt) | N/A | System analysis & optimization |
+| Gaia | (manual context in prompt) | N/A | System analysis & optimization |
 
 ---
 

package/index.js

@@ -56,11 +56,13 @@ export function getCommandPath(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) {
-  return join(PACKAGE_ROOT, 'docs', docName);
+  console.warn('getDocPath() is deprecated. Use getConfigPath() instead. Documentation is now in config/ directory.');
+  return join(PACKAGE_ROOT, 'config', docName);
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaguilar87/gaia-ops",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "Multi-agent orchestration system for Claude Code - DevOps automation toolkit",
   "main": "index.js",
   "type": "module",
@@ -44,7 +44,7 @@
     "index.js"
   ],
   "scripts": {
-    "test": "pytest tests/ -v",
+    "test": "echo 'No tests configured. Fixtures available in tests/fixtures/'",
     "validate": "python3 tools/commit_validator.py",
     "lint": "eslint .",
     "clean": "find . -type d -name '__pycache__' -exec rm -rf {} + 2>/dev/null || true",

package/speckit/README.en.md

@@ -60,26 +60,23 @@ Spec-Kit provides structured workflow for feature development:
 ├── templates/               # 5 markdown templates
 │   ├── spec-template.md     # Feature specification template
 │   ├── plan-template.md     # Implementation plan template
-│   ├── tasks-template.md    # Tasks list template
-│   ├── data-model-template.md  # Data model template
-│   └── contracts-template.md   # API contracts template
-└── memory/                  # Legacy directory (deprecated)
-    └── constitution.md      # MOVED to project root
+│   ├── tasks-template.md    # Task list template
+│   ├── adr-template.md      # Architecture Decision Record template
+│   └── agent-file-template.md  # Agent context file template
 
-.claude/commands/            # 9 /speckit.* commands
+.claude/commands/            # 7 /speckit.* commands
 ├── speckit.specify.md       # Create specification
-├── speckit.clarify.md       # Clarify ambiguities
+├── speckit.init.md          # Initialize Spec-Kit structure
 ├── speckit.plan.md          # Create implementation plan
 ├── speckit.tasks.md         # Generate task list
-├── speckit.analyze-plan.md  # Validate consistency (cross-artifact)
 ├── speckit.analyze-task.md  # Analyze specific task (deep-dive)
 ├── speckit.implement.md     # Execute implementation
-├── speckit.add-task.md      # Add ad-hoc task (with auto-validation)
-└── speckit.constitution.md  # Update constitution
+└── speckit.add-task.md      # Add ad-hoc task (with auto-validation)
 
 .claude/tools/               # Python utilities
 ├── agent_router.py          # Route tasks to agents
-└── tasks-richer.py          # Auto-enrich tasks with metadata
+├── task_manager.py          # Manage task lifecycle
+└── clarify_engine.py        # Ambiguity detection
 
 <project-root>/              # User-specified root (e.g., spec-kit-tcm-plan/)
 ├── constitution.md          # Project governance principles
@@ -113,9 +110,9 @@ Spec-Kit provides structured workflow for feature development:
 mkdir -p spec-kit-tcm-plan/specs
 ```
 
-**Step 2: Create constitution (optional)**
+**Step 2: Initialize Spec-Kit structure**
 ```bash
-/speckit.constitution spec-kit-tcm-plan
+/speckit.init spec-kit-tcm-plan
 ```
 
 **Ready!** Commands are available immediately. Example:
@@ -133,29 +130,24 @@ mkdir -p spec-kit-tcm-plan/specs
 
 | Command | Syntax | Purpose | When to Use |
 |---------|--------|---------|-------------|
+| **init** | `/speckit.init <root>` | Bootstrap Spec-Kit structure | Initial project setup |
 | **specify** | `/speckit.specify <root> "description"` | Create new feature specification | Start of workflow |
-| **clarify** | `/speckit.clarify <root> <feature>` | Resolve ambiguities in spec.md | After specify, before plan (optional) |
-| **plan** | `/speckit.plan <root> <feature>` | Create technical implementation plan | After specify/clarify |
+| **plan** | `/speckit.plan <root> <feature>` | Create technical implementation plan | After specify |
 | **tasks** | `/speckit.tasks <root> <feature>` | Generate task list with metadata | After plan |
-| **analyze-plan** | `/speckit.analyze-plan <root> <feature>` | Validate spec/plan/tasks consistency | After tasks, before implement (optional) |
 | **implement** | `/speckit.implement <root> <feature>` | Execute tasks with automatic routing | After tasks |
 | **add-task** | `/speckit.add-task <root> <feature> "desc"` | Add ad-hoc task with validation | During implement |
 | **analyze-task** | `/speckit.analyze-task <root> <feature> T###` | Deep analysis of specific task | Before executing risky tasks |
-| **constitution** | `/speckit.constitution <root>` | Create/update governance principles | Initial setup or updates |
 
 ### Usage Examples
 
 ```bash
 # Basic complete workflow
+/speckit.init spec-kit-tcm-plan
 /speckit.specify spec-kit-tcm-plan "Project Guidance Deployment"
 /speckit.plan spec-kit-tcm-plan 004-project-guidance-deployment
 /speckit.tasks spec-kit-tcm-plan 004-project-guidance-deployment
 /speckit.implement spec-kit-tcm-plan 004-project-guidance-deployment
 
-# With optional validation
-/speckit.clarify spec-kit-tcm-plan 004-project-guidance-deployment
-/speckit.analyze-plan spec-kit-tcm-plan 004-project-guidance-deployment
-
 # During implementation
 /speckit.add-task spec-kit-tcm-plan 004-project-guidance-deployment "Fix config error"
 /speckit.analyze-task spec-kit-tcm-plan 004-project-guidance-deployment T042
@@ -181,43 +173,12 @@ Location: `.claude/speckit/scripts/`
 **Format:**
 ```markdown
 - [ ] T001 Task description
-  <!-- Metadata injected by tasks-richer.py -->
 ```
 
 **Used by:** `/speckit.tasks`
 
 ---
 
-### data-model-template.md
-
-**Purpose:** Data model documentation template
-
-**Location:** `.claude/speckit/templates/data-model-template.md`
-
-**Sections:**
-- Entity Definitions
-- Relationships
-- Schema Design
-- Migrations
-
-**Optional:** Created manually when needed
-
----
-
-### contracts-template.md
-
-**Purpose:** API contracts template
-
-**Location:** `.claude/speckit/templates/contracts-template.md`
-
-**Sections:**
-- API Endpoints
-- Request/Response Schemas
-- Error Codes
-- Authentication
-
-**Optional:** Created manually when needed
-
 ## Auto-Enrichment
 
 ### What is Auto-Enrichment?
@@ -234,12 +195,7 @@ Automatic injection of metadata into tasks for agent routing and risk assessment
 
 ### Enrichment Process
 
-**Step 1: Task parsing**
-```bash
-python3 .claude/tools/tasks-richer.py tasks.md
-```
-
-**Step 2: Agent routing**
+**Step 1: Agent routing**
 ```bash
 python3 .claude/tools/agent_router.py --json "Task description"
 ```
@@ -411,10 +367,7 @@ WARNING: constitution.md not found at spec-kit-tcm-plan/constitution.md
 **Solution:**
 ```bash
 # Create constitution
-/speckit.constitution
-
-# Or move existing
-mv .claude/speckit/memory/constitution.md spec-kit-tcm-plan/
+# Create governance document manually if needed
 ```
 
 ---
@@ -561,8 +514,8 @@ jq --version
 ### Feature Development
 
 - ✅ Follow workflow order (specify → plan → tasks → implement)
-- ✅ Use `/speckit.clarify` to resolve ambiguities early
-- ✅ Run `/speckit.analyze` before implementation (optional but recommended)
+- ✅ Use clarify_engine.py for ambiguity detection (automatic)
+- ✅ Run `/speckit.analyze-task` for high-risk tasks before execution
 - ✅ Let auto-enrichment handle metadata (don't edit manually)
 
 ### Risk Management
@@ -600,20 +553,18 @@ jq --version
 All commands in `.claude/commands/speckit.*.md`:
 - speckit.init.md
 - speckit.specify.md
-- speckit.clarify.md
 - speckit.plan.md
 - speckit.tasks.md
-- speckit.analyze-plan.md
 - speckit.analyze-task.md
 - speckit.implement.md
 - speckit.add-task.md
-- speckit.constitution.md
 
 ### Tool Files
 
 - `.claude/tools/agent_router.py` - Agent routing logic
-- `.claude/tools/tasks-richer.py` - Task enrichment logic
-- `.claude/tools/context_section_reader.py` - Context filtering
+- `.claude/tools/task_manager.py` - Task lifecycle management
+- `.claude/tools/clarify_engine.py` - Ambiguity detection
+- `.claude/tools/context_provider.py` - Context provisioning
 
 **Framework Base**
 

package/templates/CLAUDE.template.md

@@ -86,7 +86,7 @@ Guidance for Claude Code orchestrator working in this repository.
 | gitops-operator | project_details, gitops_configuration, cluster_details, operational_guidelines |
 | gcp/aws-troubleshooter | project_details, terraform_infrastructure, gitops_configuration, application_services |
 | devops-developer | project_details, operational_guidelines |
-| claude-architect | Manual context (system paths, logs, tests) |
+| Gaia | Manual context (gaia-ops paths, logs, tests) |
 
 ## Agent System
 
@@ -106,7 +106,7 @@ Guidance for Claude Code orchestrator working in this repository.
 
 | Agent | Primary Role |
 |-------|--------------|
-| **claude-architect** | System analysis & optimization |
+| **Gaia** | System analysis & optimization |
 | **Explore** | Codebase exploration |
 | **Plan** | Implementation planning |
 

package/tools/context_provider.py

@@ -6,9 +6,30 @@ from pathlib import Path
 from typing import Dict, List, Any, Optional
 
 # This script is expected to be run from the root of the repository.
-# The project context file is located at `.claude/project-context.json`.
-# We construct the path relative to the script's assumed execution location.
-DEFAULT_CONTEXT_PATH = Path(".claude/project-context.json")
+# 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()
 
 # Path to provider-specific contract files
 # When running from installed project: .claude/config (symlinked)