@jaguilar87/gaia 5.0.0-rc1

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,11 @@
+# Code of Conduct
+
+This project follows the [Contributor Covenant Code of Conduct v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+Please read the full text at the link above. All contributors, maintainers, and participants are expected to uphold these standards.
+
+## Reporting
+
+Report unacceptable behavior to jorge.aguilar87@gmail.com.
+
+Reports will be reviewed and investigated promptly and fairly.

package/CONTRIBUTING.md

@@ -0,0 +1,146 @@
+# Contributing to Gaia
+
+Thank you for your interest in contributing to Gaia. This guide covers how to set up your development environment, run tests, and submit changes.
+
+## Development Setup
+
+### Prerequisites
+
+- **Node.js** >= 18.0.0
+- **Python** >= 3.9
+- **Git** >= 2.30
+- **Claude Code** (latest version, for end-to-end testing)
+
+### Clone and Install
+
+```bash
+git clone https://github.com/metraton/gaia.git
+cd gaia
+npm install
+```
+
+Python test dependencies:
+
+```bash
+pip install pytest
+```
+
+## Running Tests
+
+The test suite is organized in layers:
+
+```bash
+# Layer 1 (fast, deterministic) - run these before every PR
+npm test
+
+# Equivalent:
+npm run test:layer1
+
+# Layer 2 (LLM evaluation) - requires Claude Code access
+npm run test:layer2
+
+# Layer 3 (end-to-end)
+npm run test:layer3
+
+# All layers
+npm run test:all
+
+# Run pytest directly with stop-on-first-failure
+python -m pytest tests/ -x
+
+# Linting
+npm run lint
+```
+
+Always ensure Layer 1 tests pass before submitting a PR.
+
+## Project Structure
+
+See [README.md](./README.md) for the full directory tree. Key areas for contributors:
+
+| Directory | What it contains |
+|-----------|-----------------|
+| `agents/` | Agent definition files (`.md`) - identity, scope, routing |
+| `skills/` | Skill modules (`SKILL.md` files) - injected procedural knowledge |
+| `hooks/` | Runtime validators (`pre_tool_use.py`, `post_tool_use.py`, `subagent_stop.py`) |
+| `hooks/modules/` | Modular hook components (blocked commands, safe commands, dangerous verbs) |
+| `tools/` | Orchestration tools (context provider, memory, validation) |
+| `config/` | Configuration files (contracts, git standards, rules) |
+| `tests/` | Test suite organized by layer |
+| `bin/` | CLI utilities (`gaia-scan`, `gaia-doctor`, etc.) |
+
+## Coding Standards
+
+### Python
+
+- Follow the existing code style in the repository.
+- Use [ruff](https://github.com/astral-sh/ruff) for linting and formatting.
+- Type hints are encouraged but not strictly required.
+- Keep functions focused and testable.
+
+### JavaScript / Node.js
+
+- ES modules (`import`/`export`), not CommonJS.
+- Follow the existing patterns in `bin/` and `index.js`.
+
+### Commit Messages
+
+All commits must follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+type(scope): short description
+```
+
+Allowed types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `ci`, `perf`, `style`, `build`
+
+Examples:
+- `feat(hooks): add timeout protection to bash validator`
+- `fix(skills): correct token budget in agent-protocol`
+- `docs(readme): update installation instructions`
+
+## PR Process
+
+1. **Fork** the repository and create a feature branch from `main`.
+2. **Make your changes** following the coding standards above.
+3. **Write tests** for new functionality. Changes to `hooks/` always need tests.
+4. **Run the test suite**: `npm test` must pass.
+5. **Commit** using Conventional Commits format.
+6. **Open a PR** against `main` with a clear description of what changed and why.
+
+PRs are reviewed for correctness, test coverage, and consistency with existing patterns.
+
+## Hooks Development
+
+The `hooks/` directory contains runtime validators that enforce security and workflow policies in Claude Code. These are critical-path code.
+
+- `pre_tool_use.py` - Main entry point; validates every tool call before execution.
+- `post_tool_use.py` - Audit and metrics after tool execution.
+- `hooks/modules/` - Individual validation modules (e.g., `blocked_commands.py`, `mutative_verbs.py`).
+
+**Key rules for hook changes:**
+- Every change to a hook module must have a corresponding test in `tests/`.
+- Hook modules must be deterministic -- no network calls, no randomness.
+- Test both the allow and deny paths for any new validation rule.
+
+## Skills Development
+
+Skills live in `skills/` as directories, each containing a `SKILL.md` file:
+
+```
+skills/
+  skill-name/
+    SKILL.md          # Main content (injected into agents)
+    reference.md      # Heavy reference material (read on-demand)
+    examples.md       # Concrete examples (optional)
+    scripts/          # Executable tools (optional)
+```
+
+- `SKILL.md` must stay under 100 lines (it is injected on every agent call).
+- Heavy content goes in `reference.md` (loaded on-demand).
+- Skills define process; agents define identity. Do not duplicate between them.
+
+For detailed guidance, see `skills/skill-creation/SKILL.md`.
+
+## Questions?
+
+Open an issue on [GitHub](https://github.com/metraton/gaia/issues) or contact the maintainer at jorge.aguilar87@gmail.com.

package/INSTALL.md

@@ -0,0 +1,436 @@
+# Gaia Installation Guide
+
+This guide will help you install and configure Gaia in your project. The process is automatic and takes less than 5 minutes.
+
+## 🎯 What is Gaia?
+
+Gaia is a system of specialized AI agents that automate DevOps tasks. Think of it as having a team of experts (Terraform, Kubernetes, GCP, AWS) working together, coordinated by an intelligent orchestrator.
+
+The `gaia-ops` sub-plugin ships the full orchestrator and all agents; `gaia-security` ships security hooks only. Both are distributed via the `@jaguilar87/gaia` npm package.
+
+---
+
+## 🚀 Quick Installation (Recommended)
+
+### Option 1: Interactive Installation
+
+The easiest way - the installer will guide you step by step:
+
+```bash
+npx gaia-scan
+```
+
+It will ask questions like:
+- Where are your GitOps files?
+- Where is your Terraform code?
+- What is your GCP project?
+
+### Option 2: Non-Interactive Installation
+
+For CI/CD scripts or if you already know the values:
+
+```bash
+npx gaia-scan --non-interactive \
+  --gitops ./gitops \
+  --terraform ./terraform \
+  --app-services ./app-services \
+  --project-id my-gcp-project \
+  --cluster my-gke-cluster
+```
+
+---
+
+## 🔄 How Installation Works
+
+### Installation Flow
+
+```
+User runs: npx gaia-scan
+        ↓
+[Detector] scans your project
+        ↓
+   Finds automatically:
+   - GitOps directory
+   - Terraform directory
+   - Apps directory
+        ↓
+[Installer] asks for missing data:
+   - GCP Project ID
+   - Region
+   - Cluster name
+        ↓
+[Installer] checks Claude Code
+        ↓
+    Already installed?
+    ┌────┴────┐
+    ↓         ↓
+  YES        NO
+    ↓         ↓
+  Use     Install
+ existing    new
+    ↓         ↓
+    └────┬────┘
+         ↓
+Creates .claude/ structure
+         ↓
+Creates symlinks to gaia package:
+  .claude/agents → node_modules/.../agents
+  .claude/tools → node_modules/.../tools
+  .claude/hooks → node_modules/.../hooks
+  .claude/commands → node_modules/.../commands
+  .claude/config → node_modules/.../config
+  .claude/skills → node_modules/.../skills
+  .claude/templates → node_modules/.../templates
+         ↓
+Generates config files:
+  - project-context.json
+  - settings.json
+         ↓
+Validates installation:
+  ✅ Symlinks correct
+  ✅ Claude Code available
+  ✅ Valid configuration
+         ↓
+Ready! You can use: claude
+```
+
+### Real Installation Example
+
+```
+Example: Installation in project with GitOps and Terraform
+
+1. User: npx gaia-scan
+   ↓
+2. Detector finds:
+   ✅ ./gitops (52 YAML files detected)
+   ✅ ./terraform (15 .tf files detected)
+   ❌ ./app-services (not found)
+   ↓
+3. Installer asks:
+   ? GCP Project ID: → my-gcp-project
+   ? Primary region: → us-central1
+   ? Cluster name: → my-gke-cluster
+   ↓
+4. Checks Claude Code:
+   ✅ Claude Code already installed at /usr/local/bin/claude
+   ⏭️  Skipping reinstall
+   ↓
+5. Creates structure:
+   ✅ .claude/ created
+   ✅ 8 symlinks created
+   ✅ project-context.json created
+   ✅ settings.json created
+   ↓
+6. Result:
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   ✅ Gaia installed successfully!
+   
+   📚 Documentation available:
+   - .claude/agents/README.md
+   - .claude/config/README.md
+   - .claude/commands/README.md
+   
+   🚀 Next steps:
+   1. Run: claude
+   2. Ask: "Show me GKE clusters"
+   3. Or use: /scan-project to detect your project stack
+```
+
+---
+
+## ⚙️ Installation Options
+
+### Environment Variables
+
+Configure before installing to avoid questions:
+
+```bash
+# Configure paths
+export CLAUDE_GITOPS_DIR="./gitops"
+export CLAUDE_TERRAFORM_DIR="./terraform"
+export CLAUDE_APP_SERVICES_DIR="./app-services"
+
+# Configure project
+export CLAUDE_PROJECT_ID="my-gcp-project"
+export CLAUDE_REGION="us-central1"
+export CLAUDE_CLUSTER_NAME="my-gke-cluster"
+
+# Install without questions
+npx gaia-scan --non-interactive
+```
+
+### Complete CLI Options
+
+```
+gaia-scan [options]
+
+Options:
+  --non-interactive          Skip prompts, use provided values or defaults
+  --gitops <path>           GitOps directory path
+  --terraform <path>        Terraform directory path
+  --app-services <path>     Applications directory path
+  --project-id <id>         GCP project ID
+  --region <region>         Primary region (default: us-central1)
+  --cluster <name>          Cluster name
+  --skip-claude-install     Skip Claude Code installation
+```
+
+---
+
+## 📦 What Gets Installed?
+
+### Created Structure
+
+```
+your-project/
+├── .claude/                    ← New directory
+│   ├── agents/ (symlink)       → Agent definitions
+│   ├── skills/ (symlink)       → Skill modules
+│   ├── tools/ (symlink)        → Orchestration tools
+│   ├── hooks/ (symlink)        → Security validations
+│   ├── commands/ (symlink)     → Slash commands
+│   ├── config/ (symlink)       → Configuration (contracts, rules)
+│   ├── templates/ (symlink)    → Installation templates
+│   ├── project-context/        ← Your project context (SSOT)
+│   ├── logs/                   ← Audit logs
+│   └── settings.json           ← Security configuration
+└── node_modules/
+    └── @jaguilar87/gaia/       ← npm package
+```
+
+---
+
+## 📚 Documentation Available After Installation
+
+Once installed, you have access to **complete documentation** in each directory:
+
+### Directory READMEs
+
+```
+.claude/
+├── agents/               6 agents (terraform-architect, gitops-operator, etc.)
+├── skills/README.md      20 skill modules
+├── commands/README.md    Slash commands (gaia-plan, scan-project)
+├── config/README.md      Contracts, git standards, universal rules
+├── hooks/README.md       8 hook scripts (4 primary + 4 event handlers)
+├── tools/                Context, memory, validation, review
+├── templates/README.md   Installation templates
+└── bin/README.md         CLI utilities
+```
+
+---
+
+## ✅ Post-Installation
+
+### 1. Verify Installation
+
+```bash
+# Check created structure
+ls -la .claude/
+
+# Should show symlinks:
+# agents -> ../node_modules/@jaguilar87/gaia/agents
+# tools -> ../node_modules/@jaguilar87/gaia/tools
+```
+
+### 2. Review Generated Configuration
+
+```bash
+# View project-context.json
+cat .claude/project-context/project-context.json
+
+# View settings.json
+cat .claude/settings.json
+```
+
+### 3. Start Claude Code
+
+```bash
+claude
+```
+
+### 4. Test the System
+
+```bash
+# In Claude Code, try:
+"Show me GKE clusters"
+"List deployments in production namespace"
+
+# Or use slash commands:
+/scan-project
+```
+
+---
+
+## 🔄 Package Updates
+
+### ⚠️ Files That Get Overwritten
+
+When you update `@jaguilar87/gaia`, these files are **regenerated from templates**:
+
+| File | Behavior | Recommended Action |
+|------|----------|-------------------|
+| `.claude/settings.json` | ⚠️ **Replaced** from template (source of truth) | Safe |
+| `.claude/project-context/project-context.json` | ✅ **Preserved** | Safe |
+| `.claude/logs/` | ✅ **Preserved** | Safe |
+| Other `.claude/` files | ✅ **Auto-updated via symlinks** | Safe |
+
+Orchestrator identity lives in `agents/gaia-orchestrator.md` and is activated via `settings.json: { "agent": "gaia-orchestrator" }` -- no `CLAUDE.md` is generated.
+
+### Update Process
+
+```bash
+# 1. Update package
+npm install @jaguilar87/gaia@latest
+
+# 2. Postinstall hook automatically:
+#    - Replaces settings.json from template
+#    - Fixes broken symlinks
+```
+
+---
+
+## 🛠️ Claude Code Management
+
+### Avoiding Multiple Installations
+
+Gaia **automatically detects** if you already have Claude Code installed and **does NOT reinstall it**.
+
+#### Installation Verification
+
+```bash
+# See where Claude Code is installed
+which claude
+
+# Should show ONE location:
+# ✅ /usr/local/bin/claude (native - recommended)
+```
+
+#### If You Have Multiple Installations
+
+**Option 1: Automatic Cleanup**
+```bash
+npx gaia-cleanup
+```
+
+**Option 2: Manual Cleanup**
+```bash
+# Remove npm global installation (if exists)
+npm -g uninstall @anthropic-ai/claude-code
+
+# Verify only one remains
+which claude
+claude --version
+```
+
+---
+
+## 🐛 Troubleshooting
+
+### Problem: Claude Code Not Found
+
+**Solution:**
+```bash
+# Verify installation
+which claude
+
+# If not found, install via npm
+npm install -g @anthropic-ai/claude-code
+```
+
+---
+
+### Problem: Multiple Claude Code Installations
+
+**Solution:**
+```bash
+# Automatic cleanup
+npx gaia-cleanup
+```
+
+---
+
+### Problem: Permission Denied on npm global
+
+**Solution (recommended):**
+```bash
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+export PATH=~/.npm-global/bin:$PATH
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+```
+
+---
+
+### Problem: Symlinks Not Created
+
+**Solution:**
+```bash
+# Re-run installation
+npx gaia-scan
+```
+
+---
+
+## 🧹 Uninstallation
+
+### Complete Uninstallation
+
+```bash
+# Interactive script (recommended)
+npx gaia-uninstall
+
+# Forced uninstall (no questions)
+npx gaia-uninstall --force --remove-all
+```
+
+### Manual Uninstallation
+
+```bash
+# 1. Remove .claude/ directory
+rm -rf .claude/
+
+# 2. Uninstall npm package
+npm uninstall @jaguilar87/gaia
+```
+
+---
+
+## 💡 Design Principles
+
+Gaia is designed with these principles:
+
+✅ **Minimal** - Only creates what's needed, no duplicates  
+✅ **Adaptive** - Auto-detects existing installations  
+✅ **Non-invasive** - Works from any directory  
+✅ **Safe** - Validates paths and skips reinstalls  
+✅ **Clear** - Explicit feedback on each step  
+✅ **Documented** - Complete documentation in each directory  
+
+---
+
+## 📞 Support
+
+### Resources
+
+- **Documentation:** Inside `.claude/*/README.md`
+- **Issues:** https://github.com/metraton/gaia/issues
+- **Email:** jorge.aguilar87@gmail.com
+
+### Frequently Asked Questions
+
+**Q: Can I use Gaia in multiple projects?**  
+A: Yes. Install in each project and each will have its own `project-context.json`.
+
+**Q: Do symlinks work on Windows?**  
+A: Yes, but you need to enable developer mode or run as administrator.
+
+**Q: How do I update only documentation without changing code?**
+A: `npm update @jaguilar87/gaia` - symlinks point to the new version automatically.
+
+---
+
+**Version:** 5.0.0-rc1
+**Last updated:** 2026-04-21
+**Maintained by:** Jorge Aguilar + Gaia (meta-agent)
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jorge Aguilar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.