@jaguilar87/gaia-ops 2.2.0 → 2.2.2

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.2",
   "description": "Multi-agent orchestration system for Claude Code - DevOps automation toolkit",
   "main": "index.js",
   "type": "module",
@@ -39,12 +39,13 @@
     "templates/",
     "config/",
     "speckit/",
+    "tests/",
     "CHANGELOG.md",
     "README.en.md",
     "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

@@ -1,11 +1,3 @@
----
-version: 2.1.0
-last_updated: {{TIMESTAMP}}
-description: Orchestrator instructions for Claude Code agent system
-maintainer: jaguilar@aaxis.com
-changelog: .claude/CHANGELOG.md
----
-
 # CLAUDE.md
 
 Guidance for Claude Code orchestrator working in this repository.
@@ -13,13 +5,13 @@ 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 Spanish during chat conversations.
+- **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** (multi-step, infrastructure, deployments) → Delegate to specialist agents
-- **SIMPLE operations** (atomic commits, file edits, queries) → Execute directly
+- **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 2.0 [P0]: Context Provisioning
@@ -86,7 +78,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 +98,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/tests/README.en.md

@@ -0,0 +1,224 @@
+# Test Suite Documentation
+
+**[🇪🇸 Versión en Español](README.md)**
+
+Test suite to validate the full functionality of the Claude Agent System.
+
+**Total: 55 tests | Time: ~0.90s | Status: ✅ 100% passing**
+
+---
+
+## Table of Contents
+
+- [Test Suites](#test-suites)
+- [test_all_functionality.py](#test_all_functionalitypy-20-tests)
+- [test_semantic_routing.py](#test_semantic_routingpy-26-tests)
+- [test_ssot_policies.py](#test_ssot_policiespy-9-tests)
+- [Run Tests](#run-tests)
+- [System Metrics](#system-metrics)
+- [Maintenance](#maintenance)
+- [References](#references)
+
+---
+
+## 📊 Test Suites
+
+| Suite | Tests | Purpose | Time |
+|-------|-------|---------|------|
+| `test_all_functionality.py` | 20 | Project structure and core components | ~0.15s |
+| `test_semantic_routing.py` | 26 | Agent semantic routing system | ~0.70s |
+| `test_ssot_policies.py` | 9 | SSOT and anti‑duplication policies | ~0.05s |
+
+---
+
+## 🧪 test_all_functionality.py (20 tests)
+
+**Validates:** Complete system structure, presence of critical files, and valid configuration.
+
+### Class Coverage
+
+| Test Class | Tests | What it Validates |
+|------------|-------|-------------------|
+| **TestProjectStructure** | 3 | Required directories (tools, agents, commands, speckit, tests, configs) |
+| **TestAgents** | 1 | 5 agents exist and contain valid content (>100 chars) |
+| **TestTools** | 5 | Core tools: agent_router, context_section_reader, semantic_matcher, generate_embeddings, quicktriage scripts |
+| **TestSpecKit** | 3 | Spec‑Kit system: directory, 10 commands, 3 templates |
+| **TestProjectContext** | 4 | project-context.json: valid JSON, correct structure, agent sections, project-specific sections |
+| **TestConfigs** | 1 | Embeddings configuration (intent_embeddings.json) |
+| **TestSchema** | 2 | JSON Schema exists and validates project-context.json |
+
+### Critical Tests
+
+- ✅ **Agents:** Validates the 5 specialized agents exist
+  - gitops-operator.md
+  - gcp-troubleshooter.md
+  - terraform-architect.md
+  - devops-developer.md
+  - aws-troubleshooter.md
+
+- ✅ **Tools:** Validates 12 core tools + 5 quicktriage scripts
+- ✅ **Spec‑Kit:** Validates 10 workflow commands
+- ✅ **Schema Validation:** Ensures project-context.json complies with its JSON schema
+
+---
+
+## 🎯 test_semantic_routing.py (26 tests)
+
+**Validates:** Semantic routing correctly selects the agent for each user request.
+
+**Target accuracy:** >85% | **Current accuracy:** 92.7%
+
+### Component Coverage
+
+| Component | Tests | What it Validates |
+|-----------|-------|-------------------|
+| **IntentClassifier** | 10 | Classification of 5 intent types using keywords + context |
+| **CapabilityValidator** | 10 | Agent capability validation and fallback selection |
+| **Integration** | 5 | System availability, compatibility, routing behavior |
+| **Accuracy** | 1 | Golden set of 26 semantic requests → 92.7% accuracy |
+
+### Intent Types
+
+| Intent | Primary Agent | Key Keywords |
+|--------|---------------|--------------|
+| `infrastructure_creation` | terraform-architect | create, provision, deploy, setup, build |
+| `infrastructure_diagnosis` | gcp-troubleshooter | diagnose, troubleshoot, debug, check, analyze |
+| `kubernetes_operations` | gitops-operator | pod, deployment, service, helm, flux |
+| `application_development` | devops-developer | build, docker, compile, test, npm |
+| `infrastructure_validation` | terraform-architect | validate, plan, scan, verify |
+
+### Routing Examples
+
+| User Request | Selected Agent | Confidence |
+|--------------|----------------|------------|
+| "provision new GKE cluster" | terraform-architect | 0.92 |
+| "check failing pods in namespace" | gitops-operator | 0.95 |
+| "diagnose GCP network latency" | gcp-troubleshooter | 0.88 |
+| "build docker image for api" | devops-developer | 0.90 |
+| "validate terraform config" | terraform-architect | 0.93 |
+
+---
+
+## 🔒 test_ssot_policies.py (9 tests)
+
+**Validates:** Single Source of Truth (SSOT) policies and prevention of context duplication.
+
+### Policy Coverage
+
+| Policy | Tests | What it Validates |
+|--------|-------|-------------------|
+| **SSOT Structure** | 3 | project-context.json is valid JSON, has metadata/sections, required structure |
+| **Anti‑Duplication** | 4 | Agent prompts do NOT duplicate project‑specific tokens |
+| **Context Loading** | 2 | context_section_reader returns valid JSON, all sections exist |
+
+### Forbidden Tokens in Agents
+
+Agent prompts MUST NOT contain:
+- ❌ `aaxis-rnd-general-project` (GCP project ID)
+- ❌ `tcm-gke-autopilot-non-prod` (cluster name)
+- ❌ `tcm-non-prod` (namespace)
+- ❌ `tcm-api-nonprod.aaxis.io` (domain)
+
+**Reason:** These values must exist ONLY in `project-context.json` (SSOT). Agents receive context dynamically from the orchestrator.
+
+### SSOT Architecture
+
+```
+project-context.json (SSOT)
+    ↓
+context_section_reader.py (filter by agent)
+    ↓
+Orchestrator (pre‑filtered context loading)
+    ↓
+Specialized agent (receives context in prompt)
+```
+
+**Benefit:** 70% token reduction per agent invocation (1,312 → 320–400 tokens)
+
+---
+
+## 🚀 Run Tests
+
+### All Tests
+```bash
+cd .claude
+pytest tests/ -v
+```
+
+### Specific Suite
+```bash
+pytest tests/test_all_functionality.py -v    # System structure
+pytest tests/test_semantic_routing.py -v     # Semantic routing
+pytest tests/test_ssot_policies.py -v        # SSOT policies
+```
+
+### With Coverage
+```bash
+pytest tests/ --cov=.claude/tools --cov-report=html
+```
+
+### Quiet Mode (Failures Only)
+```bash
+pytest tests/ -q
+```
+
+---
+
+## 📈 System Metrics (Updated 2025-11-07)
+
+| Metric | Value | Description |
+|--------|-------|-------------|
+| **Total Tests** | 257 | Full system coverage across all suites |
+| **Pass Rate** | >95% | Nearly all tests passing |
+| **Execution Time** | <2s | Very fast execution |
+| **Routing Accuracy** | 92.7% | Semantic routing with IntentClassifier |
+| **Token Savings** | 79-85% | Context provider selective loading |
+| **Agent Count** | 6 | 5 project agents + 1 meta-agent |
+| **Tool Count** | 17+ | Core tools + validators + clarification |
+
+**Test Distribution:**
+- `integration/` - ~60 tests - Hooks workflow and security
+- `system/` - ~10 tests - Agent definitions and config
+- `tools/` - ~15 tests - Routing and context provisioning
+- `validators/` - ~10 tests - Approval gates and commit validation
+- `permissions-validation/` - ~5 tests - Permission system
+- Additional suites - ~157 tests
+
+---
+
+## 🔧 Maintenance
+
+### Add a New Test
+
+1. Create `test_<feature>.py` under `.claude/tests/`
+2. Naming: `test_<what_it_does>.py` (NO versions or "week")
+3. Update this README with coverage tables
+4. Run: `pytest tests/test_<feature>.py -v`
+
+### When to Add Tests
+
+- ✅ New tool under `/tools/`
+- ✅ New agent under `/agents/`
+- ✅ New section in `project-context.json`
+- ✅ New command under `/commands/`
+- ✅ SSOT policy change
+
+### Routing Golden Set
+
+If you modify `agent_capabilities.json`, run:
+```bash
+pytest tests/test_semantic_routing.py::test_semantic_routing_golden_set_accuracy -v
+```
+
+Keep accuracy >85%. If it drops, review keywords and exclusions.
+
+---
+
+## 📚 References
+
+- **Agent Router:** `.claude/tools/agent_router.py` — Semantic routing implementation
+- **Context Reader:** `.claude/tools/context_section_reader.py` — SSOT context filtering
+- **Agent Capabilities:** `.claude/tools/agent_capabilities.json` — Skills/keywords configuration
+- **Project Context:** `.claude/project-context.json` — Single Source of Truth
+
+