@jaguilar87/gaia-ops 1.0.0

package/speckit/templates/tasks-template.md

@@ -0,0 +1,345 @@
+# Tasks: [FEATURE NAME]
+
+**Input**: Design documents from `/specs/[###-feature-name]/`
+**Prerequisites**: plan.md (required), research.md, data-model.md, contracts/
+
+## Execution Flow (main)
+```
+1. Load plan.md from feature directory
+   → If not found: ERROR "No implementation plan found"
+   → Extract: tech stack, libraries, structure
+2. Load optional design documents:
+   → data-model.md: Extract entities → model tasks
+   → contracts/: Each file → contract test task
+   → research.md: Extract decisions → setup tasks
+3. Generate tasks by category:
+   → Setup: GitOps setup, HelmRelease validation, image tag verification
+   → Tests: contract tests, integration tests, health checks
+   → Core: models, services, CLI commands
+   → Infrastructure: Ingress-GCE, certificate management, DNS setup
+   → Integration: DB, middleware, logging, observability
+   → Polish: unit tests, performance, documentation, rollback procedures
+4. Apply task rules:
+   → Different files = mark [P] for parallel
+   → Same file = sequential (no [P])
+   → Tests before implementation (TDD)
+5. Number tasks sequentially (T001, T002...)
+6. Generate dependency graph
+7. Create parallel execution examples
+8. Validate task completeness:
+   → All contracts have tests?
+   → All entities have models?
+   → All endpoints implemented?
+9. Return: SUCCESS (tasks ready for execution)
+```
+
+## Format: `[ID] [P?] Description`
+- **[P]**: Can run in parallel (different files, no dependencies)
+- Include exact file paths in descriptions
+
+## Path Conventions
+- **Single project**: `src/`, `tests/` at repository root
+- **Web app**: `backend/src/`, `frontend/src/`
+- **Mobile**: `api/src/`, `ios/src/` or `android/src/`
+- Paths shown below assume single project - adjust based on plan.md structure
+
+## Phase 3.1: Setup
+- [ ] T001 Create project structure per implementation plan
+  <!-- 🤖 Agent: terraform-architect | ✅ T1 | ❓ 0.70 -->
+  <!-- 🏷️ Tags: #code #setup -->
+  <!-- 🧠 Reasoning: Skill 'terraform_operations' matched (score: 2.0), Routed to terraform-architect, Security tier: T1 -->
+  <!-- 🎯 skill: terraform_operations (2.0) -->
+  <!-- 🔄 Fallback: devops-developer -->
+
+- [ ] T002 Initialize [language] project with [framework] dependencies
+  <!-- 🤖 Agent: devops-developer | 👁️ T0 | ❓ 0.00 -->
+  <!-- 🏷️ Tags: #setup -->
+  <!-- 🧠 Reasoning: Defaulted to devops-developer (no specific skill match) -->
+  <!-- 🎯 default: devops-developer -->
+  <!-- 🔄 Fallback: devops-developer -->
+
+- [ ] T003 [P] Configure linting and formatting tools
+  <!-- 🤖 Agent: gitops-operator | 👁️ T0 | ❓ 0.50 -->
+  <!-- 🏷️ Tags: #config #setup -->
+  <!-- 🧠 Reasoning: Skill 'configuration_management' matched (score: 2.0), Routed to gitops-operator, Security tier: T0 -->
+  <!-- 🎯 skill: configuration_management (2.0) -->
+  <!-- 🔄 Fallback: devops-developer -->
+
+
+## Phase 3.2: Tests First (TDD) ⚠️ MUST COMPLETE BEFORE 3.3
+**CRITICAL: These tests MUST be written and MUST FAIL before ANY implementation**
+- [ ] T004 [P] Contract test POST /api/users in tests/contract/test_users_post.py
+  <!-- 🤖 Agent: devops-developer | ✅ T1 | 🔥 1.00 -->
+  <!-- 🏷️ Tags: #api #hr #integration #test -->
+  <!-- 🧠 Reasoning: Skill 'testing_validation' matched (score: 10.0), Routed to devops-developer, Security tier: T1 -->
+  <!-- 🎯 skill: testing_validation (10.0) -->
+  <!-- 🔄 Fallback: gitops-operator -->
+
+- [ ] T005 [P] Contract test GET /api/users/{id} in tests/contract/test_users_get.py
+  <!-- 🤖 Agent: devops-developer | ✅ T1 | 🔥 1.00 -->
+  <!-- 🏷️ Tags: #api #hr #integration #test -->
+  <!-- 🧠 Reasoning: Skill 'testing_validation' matched (score: 10.0), Routed to devops-developer, Security tier: T1 -->
+  <!-- 🎯 skill: testing_validation (10.0) -->
+  <!-- 🔄 Fallback: gitops-operator -->
+
+- [ ] T006 [P] Integration test user registration in tests/integration/test_registration.py
+  <!-- 🤖 Agent: devops-developer | ✅ T1 | ⚡ 1.00 -->
+  <!-- 🏷️ Tags: #hr #test -->
+  <!-- 🧠 Reasoning: Skill 'testing_validation' matched (score: 10.0), Routed to devops-developer, Security tier: T1 -->
+  <!-- 🎯 skill: testing_validation (10.0) -->
+  <!-- 🔄 Fallback: gitops-operator -->
+
+- [ ] T007 [P] Integration test auth flow in tests/integration/test_auth.py
+  <!-- 🤖 Agent: devops-developer | ✅ T1 | 🔥 1.00 -->
+  <!-- 🏷️ Tags: #security #test -->
+  <!-- 🧠 Reasoning: Skill 'testing_validation' matched (score: 10.0), Routed to devops-developer, Security tier: T1 -->
+  <!-- 🎯 skill: testing_validation (10.0) -->
+  <!-- 🔄 Fallback: gitops-operator -->
+
+
+## Phase 3.3: Core Implementation (ONLY after tests are failing)
+- [ ] T008 [P] User model in src/models/user.py
+  <!-- 🤖 Agent: devops-developer | ✅ T1 | ❓ 0.90 -->
+  <!-- 🏷️ Tags: #hr -->
+  <!-- 🧠 Reasoning: Skill 'application_development' matched (score: 6.0), Routed to devops-developer, Security tier: T1 -->
+  <!-- 🎯 skill: application_development (6.0) -->
+  <!-- 🔄 Fallback: gitops-operator -->
+
+- [ ] T009 [P] UserService CRUD in src/services/user_service.py
+  <!-- 🤖 Agent: devops-developer | ✅ T1 | 🔥 1.00 -->
+  <!-- 🏷️ Tags: #api #hr #kubernetes -->
+  <!-- 🧠 Reasoning: Skill 'application_development' matched (score: 8.0), Routed to devops-developer, Security tier: T1 -->
+  <!-- 🎯 skill: application_development (8.0) -->
+  <!-- 🔄 Fallback: gitops-operator -->
+
+- [ ] T010 [P] CLI --create-user in src/cli/user_commands.py
+  <!-- 🤖 Agent: devops-developer | ✅ T1 | ❓ 0.90 -->
+  <!-- 🏷️ Tags: #hr #setup -->
+  <!-- 🧠 Reasoning: Skill 'application_development' matched (score: 6.0), Routed to devops-developer, Security tier: T1 -->
+  <!-- 🎯 skill: application_development (6.0) -->
+  <!-- 🔄 Fallback: gitops-operator -->
+
+- [ ] T011 POST /api/users endpoint
+  <!-- 🤖 Agent: devops-developer | ✅ T1 | ⚡ 0.50 -->
+  <!-- 🏷️ Tags: #api #hr #integration -->
+  <!-- 🧠 Reasoning: Skill 'application_development' matched (score: 2.0), Routed to devops-developer, Security tier: T1 -->
+  <!-- 🎯 skill: application_development (2.0) -->
+  <!-- 🔄 Fallback: gitops-operator -->
+
+- [ ] T012 GET /api/users/{id} endpoint
+  <!-- 🤖 Agent: devops-developer | ✅ T1 | ⚡ 0.50 -->
+  <!-- 🏷️ Tags: #api #hr #integration -->
+  <!-- 🧠 Reasoning: Skill 'application_development' matched (score: 2.0), Routed to devops-developer, Security tier: T1 -->
+  <!-- 🎯 skill: application_development (2.0) -->
+  <!-- 🔄 Fallback: gitops-operator -->
+
+- [ ] T013 Input validation
+  <!-- 🤖 Agent: devops-developer | ✅ T1 | ⚡ 0.70 -->
+  <!-- 🏷️ Tags: #test -->
+  <!-- 🧠 Reasoning: Skill 'testing_validation' matched (score: 2.0), Routed to devops-developer, Security tier: T1 -->
+  <!-- 🎯 skill: testing_validation (2.0) -->
+  <!-- 🔄 Fallback: gitops-operator -->
+
+- [ ] T014 Error handling and logging
+  <!-- 🤖 Agent: gcp-troubleshooter | 👁️ T0 | ❓ 0.50 -->
+  <!-- 🏷️ Tags: #debug -->
+  <!-- 🧠 Reasoning: Skill 'monitoring_observability' matched (score: 2.0), Routed to gcp-troubleshooter, Security tier: T0 -->
+  <!-- 🎯 skill: monitoring_observability (2.0) -->
+  <!-- 🔄 Fallback: aws-troubleshooter -->
+
+
+## Phase 3.4: Integration
+- [ ] T015 Connect UserService to DB
+  <!-- 🤖 Agent: gitops-operator | 👁️ T0 | ⚡ 0.60 -->
+  <!-- 🏷️ Tags: #api #database #hr #kubernetes -->
+  <!-- 🧠 Reasoning: Skill 'kubernetes_deployment' matched (score: 2.0), Routed to gitops-operator, Security tier: T0 -->
+  <!-- 🎯 skill: kubernetes_deployment (2.0) -->
+  <!-- 🔄 Fallback: devops-developer -->
+
+- [ ] T016 Auth middleware
+  <!-- 🤖 Agent: devops-developer | 👁️ T0 | ❓ 0.00 -->
+  <!-- 🏷️ Tags: #security -->
+  <!-- 🧠 Reasoning: Defaulted to devops-developer (no specific skill match) -->
+  <!-- 🎯 default: devops-developer -->
+  <!-- 🔄 Fallback: devops-developer -->
+
+- [ ] T017 Request/response logging
+  <!-- 🤖 Agent: gcp-troubleshooter | 👁️ T0 | ❓ 0.50 -->
+  <!-- 🏷️ Tags:  -->
+  <!-- 🧠 Reasoning: Skill 'monitoring_observability' matched (score: 2.0), Routed to gcp-troubleshooter, Security tier: T0 -->
+  <!-- 🎯 skill: monitoring_observability (2.0) -->
+  <!-- 🔄 Fallback: aws-troubleshooter -->
+
+- [ ] T018 CORS and security headers
+  <!-- 🤖 Agent: devops-developer | ✅ T1 | ⚡ 0.70 -->
+  <!-- 🏷️ Tags: #infrastructure #security #test -->
+  <!-- 🧠 Reasoning: Skill 'testing_validation' matched (score: 2.0), Routed to devops-developer, Security tier: T1 -->
+  <!-- 🎯 skill: testing_validation (2.0) -->
+  <!-- 🔄 Fallback: gitops-operator -->
+
+
+## Phase 3.5: Polish
+- [ ] T019 [P] Unit tests for validation in tests/unit/test_validation.py
+  <!-- 🤖 Agent: devops-developer | ✅ T1 | ⚡ 1.00 -->
+  <!-- 🏷️ Tags: #test -->
+  <!-- 🧠 Reasoning: Skill 'testing_validation' matched (score: 12.0), Routed to devops-developer, Security tier: T1 -->
+  <!-- 🎯 skill: testing_validation (12.0) -->
+  <!-- 🔄 Fallback: gitops-operator -->
+
+- [ ] T020 Performance tests (<200ms)
+  <!-- 🤖 Agent: devops-developer | ✅ T1 | ⚡ 1.00 -->
+  <!-- 🏷️ Tags: #performance #test -->
+  <!-- 🧠 Reasoning: Skill 'testing_validation' matched (score: 5.0), Routed to devops-developer, Security tier: T1 -->
+  <!-- 🎯 skill: testing_validation (5.0) -->
+  <!-- 🔄 Fallback: gitops-operator -->
+
+- [ ] T021 [P] Update docs/api.md
+  <!-- 🤖 Agent: devops-developer | ✅ T1 | 🔥 1.00 -->
+  <!-- 🏷️ Tags: #api #docs #integration -->
+  <!-- 🧠 Reasoning: Skill 'documentation_creation' matched (score: 8.0), Routed to devops-developer, Security tier: T1 -->
+  <!-- 🎯 skill: documentation_creation (8.0) -->
+  <!-- 🔄 Fallback: gitops-operator -->
+
+- [ ] T022 Remove duplication
+  <!-- 🤖 Agent: devops-developer | 👁️ T0 | ❓ 0.00 -->
+  <!-- 🏷️ Tags:  -->
+  <!-- 🧠 Reasoning: Defaulted to devops-developer (no specific skill match) -->
+  <!-- 🎯 default: devops-developer -->
+  <!-- 🔄 Fallback: devops-developer -->
+
+- [ ] T023 Run manual-testing.md
+  <!-- 🤖 Agent: devops-developer | ✅ T1 | ⚡ 1.00 -->
+  <!-- 🏷️ Tags: #docs #test -->
+  <!-- 🧠 Reasoning: Skill 'testing_validation' matched (score: 7.0), Routed to devops-developer, Security tier: T1 -->
+  <!-- 🎯 skill: testing_validation (7.0) -->
+  <!-- 🔄 Fallback: gitops-operator -->
+
+
+## Dependencies
+- Tests (T004-T007) before implementation (T008-T014)
+- T008 blocks T009, T015
+- T016 blocks T018
+- Implementation before polish (T019-T023)
+
+## Parallel Example
+```
+# Launch T004-T007 together:
+Task: "Contract test POST /api/users in tests/contract/test_users_post.py"
+Task: "Contract test GET /api/users/{id} in tests/contract/test_users_get.py"
+Task: "Integration test registration in tests/integration/test_registration.py"
+Task: "Integration test auth in tests/integration/test_auth.py"
+```
+
+## Notes
+- [P] tasks = different files, no dependencies
+- Verify tests fail before implementing
+- Commit after each task
+- Avoid: vague tasks, same file conflicts
+
+## Task Generation Rules
+*Applied during main() execution*
+
+1. **From Contracts**:
+   - Each contract file → contract test task [P]
+   - Each endpoint → implementation task
+   
+2. **From Data Model**:
+   - Each entity → model creation task [P]
+   - Relationships → service layer tasks
+   
+3. **From User Stories**:
+   - Each story → integration test [P]
+   - Quickstart scenarios → validation tasks
+
+4. **Ordering**:
+   - Setup → Tests → Models → Services → Endpoints → Polish
+   - Dependencies block parallel execution
+
+## Validation Checklist
+*GATE: Checked by main() before returning*
+
+- [ ] T024 All contracts have corresponding tests
+  <!-- 🤖 Agent: devops-developer | ✅ T1 | ⚡ 1.00 -->
+  <!-- 🏷️ Tags: #test -->
+  <!-- 🧠 Reasoning: Skill 'testing_validation' matched (score: 7.0), Routed to devops-developer, Security tier: T1 -->
+  <!-- 🎯 skill: testing_validation (7.0) -->
+  <!-- 🔄 Fallback: gitops-operator -->
+
+- [ ] T025 All entities have model tasks
+  <!-- 🤖 Agent: devops-developer | 👁️ T0 | ❓ 0.00 -->
+  <!-- 🏷️ Tags:  -->
+  <!-- 🧠 Reasoning: Defaulted to devops-developer (no specific skill match) -->
+  <!-- 🎯 default: devops-developer -->
+  <!-- 🔄 Fallback: devops-developer -->
+
+- [ ] T026 All tests come before implementation
+  <!-- 🤖 Agent: devops-developer | ✅ T1 | ⚡ 1.00 -->
+  <!-- 🏷️ Tags: #code #test -->
+  <!-- 🧠 Reasoning: Skill 'testing_validation' matched (score: 5.0), Routed to devops-developer, Security tier: T1 -->
+  <!-- 🎯 skill: testing_validation (5.0) -->
+  <!-- 🔄 Fallback: gitops-operator -->
+
+- [ ] T027 Parallel tasks truly independent
+  <!-- 🤖 Agent: devops-developer | 👁️ T0 | ❓ 0.00 -->
+  <!-- 🏷️ Tags:  -->
+  <!-- 🧠 Reasoning: Defaulted to devops-developer (no specific skill match) -->
+  <!-- 🎯 default: devops-developer -->
+  <!-- 🔄 Fallback: devops-developer -->
+
+- [ ] T028 Each task specifies exact file path
+  <!-- 🤖 Agent: devops-developer | ✅ T1 | ⚡ 0.80 -->
+  <!-- 🏷️ Tags: #test -->
+  <!-- 🧠 Reasoning: Skill 'testing_validation' matched (score: 3.0), Routed to devops-developer, Security tier: T1 -->
+  <!-- 🎯 skill: testing_validation (3.0) -->
+  <!-- 🔄 Fallback: gitops-operator -->
+
+- [ ] T029 No task modifies same file as another [P] task
+  <!-- 🤖 Agent: devops-developer | 👁️ T0 | ❓ 0.00 -->
+  <!-- 🏷️ Tags:  -->
+  <!-- 🧠 Reasoning: Defaulted to devops-developer (no specific skill match) -->
+  <!-- 🎯 default: devops-developer -->
+  <!-- 🔄 Fallback: devops-developer -->
+
+
+**TCM Constitution Compliance**:
+- [ ] T030 GitOps patterns enforced (no manual kubectl apply tasks)
+  <!-- 🤖 Agent: terraform-architect | 🚫 T3 | ❓ 0.70 -->
+  <!-- 🏷️ Tags: #docs #kubernetes -->
+  <!-- 🧠 Reasoning: Skill 'terraform_operations' matched (score: 2.0), Routed to terraform-architect, Security tier: T3 -->
+  <!-- 🎯 skill: terraform_operations (2.0) -->
+  <!-- 🔄 Fallback: devops-developer -->
+
+- [ ] T031 Concrete image tags specified (no :latest references)
+  <!-- 🤖 Agent: devops-developer | ✅ T1 | ⚡ 1.00 -->
+  <!-- 🏷️ Tags: #docker #test -->
+  <!-- 🧠 Reasoning: Skill 'testing_validation' matched (score: 8.0), Routed to devops-developer, Security tier: T1 -->
+  <!-- 🎯 skill: testing_validation (8.0) -->
+  <!-- 🔄 Fallback: gitops-operator -->
+
+- [ ] T032 HTTPS endpoints required for external exposure
+  <!-- 🤖 Agent: devops-developer | ✅ T1 | ⚡ 0.60 -->
+  <!-- 🏷️ Tags: #api #web -->
+  <!-- 🧠 Reasoning: Skill 'application_development' matched (score: 3.0), Routed to devops-developer, Security tier: T1 -->
+  <!-- 🎯 skill: application_development (3.0) -->
+  <!-- 🔄 Fallback: gitops-operator -->
+
+- [ ] T033 Health checks included before DNS exposure
+  <!-- 🤖 Agent: gcp-troubleshooter | 👁️ T0 | ❓ 0.50 -->
+  <!-- 🏷️ Tags: #monitoring #networking #test -->
+  <!-- 🧠 Reasoning: Skill 'monitoring_observability' matched (score: 2.0), Routed to gcp-troubleshooter, Security tier: T0 -->
+  <!-- 🎯 skill: monitoring_observability (2.0) -->
+  <!-- 🔄 Fallback: aws-troubleshooter -->
+
+- [ ] T034 Certificate management strategy documented
+  <!-- 🤖 Agent: devops-developer | 👁️ T0 | ❓ 0.00 -->
+  <!-- 🏷️ Tags: #security #tcm -->
+  <!-- 🧠 Reasoning: Defaulted to devops-developer (no specific skill match) -->
+  <!-- 🎯 default: devops-developer -->
+  <!-- 🔄 Fallback: devops-developer -->
+
+- [ ] T035 Rollback procedures defined for deployments
+  <!-- 🤖 Agent: devops-developer | 🚫 T3 | ❓ 0.60 -->
+  <!-- 🏷️ Tags: #deploy #kubernetes -->
+  <!-- 🧠 Reasoning: Skill 'application_development' matched (score: 3.0), Routed to devops-developer, Security tier: T3 -->
+  <!-- 🎯 skill: application_development (3.0) -->
+  <!-- 🔄 Fallback: gitops-operator -->

package/templates/CLAUDE.template.md

@@ -0,0 +1,170 @@
+---
+version: 2.1.0
+last_updated: {{TIMESTAMP}}
+description: Orchestrator instructions for Claude Code agent system
+maintainer: jaguilar@aaxis.com
+changelog: .claude/CHANGELOG.md
+project_id: {{PROJECT_ID}}
+region: {{REGION}}
+cluster: {{CLUSTER_NAME}}
+---
+
+# 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 Spanish 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
+- **Default:** When in doubt, delegate (safer)
+
+### Rule 2.0 [P0]: Context Provisioning
+- Use `context_provider.py` to build agent payload (ONLY for project agents)
+- Meta-agents receive manual context in prompt
+
+### Rule 3.0 [P0]: Two-Phase Workflow for Infrastructure
+- **Phase 1 (Planning):** Agent generates code and plan
+- **Phase 2 (Realization):** After user approval, agent persists and applies
+- **Applies to:** Infrastructure changes, deployments, T3 operations
+
+### Rule 4.0 [P1]: Execution Standards
+- Use native tools (`Write`, `Read`, `Edit`, `Grep`) over bash redirections
+- Execute simple commands separately (`cd /path` then `git status`, NOT chained with `&&`)
+- Permission priority: `deny` > `ask (specific)` > `allow (generic)`
+
+## Orchestrator Workflow
+
+**See:** `.claude/docs/orchestration-workflow.md` for complete details.
+
+### Rule 5.0 [P0]: Six-Phase Workflow
+
+| Phase | Action | Tool | Mandatory |
+|-------|--------|------|-----------|
+| 0 | Clarification (if ambiguous) | `clarify_engine.py` | Conditional |
+| 1 | Route to agent | `agent_router.py` | Yes |
+| 2 | Provision context | `context_provider.py` | Yes |
+| 3 | Invoke (Planning) | `Task` tool | Yes |
+| 4 | Approval Gate | `approval_gate.py` | **Yes (T3)** |
+| 5 | Realization | `Task` tool (re-invoke) | Yes |
+| 6 | Update SSOT | Edit `project-context.json`, `tasks.md` | Yes |
+
+### Rule 5.1 [P0]: Approval Gate Enforcement
+- Phase 4 CANNOT be skipped for T3 operations
+- Phase 5 requires `validation["approved"] == True`
+- Phase 6 updates MUST complete after successful realization
+
+## Git Operations
+
+### Rule 6.0 [P0]: Commit Responsibility
+
+| Scenario | Handler | Reason |
+|----------|---------|--------|
+| Ad-hoc commits ("commitea los cambios") | Orchestrator | Simple, atomic |
+| Infrastructure workflow commits | Agent (terraform/gitops) | Part of realization |
+| PR creation | Orchestrator | Simple ops (commit + push + gh) |
+
+### Rule 6.1 [P0]: Universal Validation
+- **ALL commits** (orchestrator + agents) MUST validate via `commit_validator.safe_validate_before_commit(msg)`
+- **Format:** Conventional Commits `<type>(<scope>): <description>`
+- **Max:** 72 chars, imperative mood, no period
+- **Forbidden:** Claude Code attribution footers
+
+**Complete spec:** `.claude/docs/git-standards.md`
+**Config:** `.claude/config/git_standards.json`
+
+## Context Contracts
+
+**See:** `.claude/docs/context-contracts.md` for complete contracts.
+
+| Agent | Required Context |
+|-------|-----------------|
+| terraform-architect | project_details, terraform_infrastructure, operational_guidelines |
+| 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) |
+
+## Agent System
+
+**See:** `.claude/docs/agent-catalog.md` for full capabilities.
+
+### Project Agents (use context_provider.py)
+
+| Agent | Primary Role | Security Tier |
+|-------|--------------|---------------|
+| **terraform-architect** | Terraform/Terragrunt operations | T0-T3 (apply with approval) |
+| **gitops-operator** | Kubernetes/Flux deployments | T0-T3 (push with approval) |
+| **gcp-troubleshooter** | GCP diagnostics | T0-T2 (read-only) |
+| **aws-troubleshooter** | AWS diagnostics | T0-T2 (read-only) |
+| **devops-developer** | Application build/test/debug | T0-T2 |
+
+### Meta-Agents (manual context in prompt)
+
+| Agent | Primary Role |
+|-------|--------------|
+| **claude-architect** | System analysis & optimization |
+| **Explore** | Codebase exploration |
+| **Plan** | Implementation planning |
+
+**Context pattern:**
+- **Project agents:** `context_provider.py` generates payload automatically
+- **Meta-agents:** Manual context in prompt (system paths, logs, tests)
+
+### Security Tiers
+
+| Tier | Operations | Approval | Examples |
+|------|-----------|----------|----------|
+| **T0** | Read-only queries | No | `kubectl get`, `git status`, `terraform show` |
+| **T1** | Local changes only | No | File edits, local commits |
+| **T2** | Reversible remote ops | No | `git push` to feature branch |
+| **T3** | Irreversible ops | **YES** | `git push` to main, `terraform apply`, `kubectl apply` |
+
+## Common Anti-Patterns
+
+### Rule 7.0 [P0]: Violations to Avoid
+
+| ❌ DON'T | ✅ DO |
+|----------|-------|
+| Skip approval gate for T3 ops | Use `approval_gate.py` for ALL T3 operations |
+| Use `context_provider.py` for meta-agents | Provide manual context in prompt for meta-agents |
+| Chain bash with `&&` | Use native tools or separate commands |
+| Proceed without approval (`validation["approved"]`) | Halt and require explicit user approval |
+| Over-prompt agents with step-by-step instructions | Minimalist prompt: context + task only |
+| Skip SSOT updates after realization | Update `project-context.json` and `tasks.md` |
+
+## Project Configuration
+
+**This project:**
+- **GCP Project ID:** {{PROJECT_ID}}
+- **Region:** {{REGION}}
+- **Cluster:** {{CLUSTER_NAME}}
+- **GitOps Path:** {{GITOPS_PATH}}
+- **Terraform Path:** {{TERRAFORM_PATH}}
+- **App Services Path:** {{APP_SERVICES_PATH}}
+
+## System Paths
+
+**NOTE:** All paths are relative to this repository root, resolved at runtime via npm package.
+
+- **Agent system:** `.claude/` (symlinked to `node_modules/@aaxis/claude-agents/`)
+- **Orchestrator:** `./CLAUDE.md` (this file)
+- **Tools:** `.claude/tools/` → `node_modules/@aaxis/claude-agents/tools/`
+- **Logs:** `.claude/logs/` (project-specific, NOT symlinked)
+- **Tests:** `.claude/tests/` (project-specific, NOT symlinked)
+- **Project SSOT:** `.claude/project-context.json` (project-specific, NOT symlinked)
+
+## References
+
+- **Orchestration workflow:** `.claude/docs/orchestration-workflow.md`
+- **Git standards:** `.claude/docs/git-standards.md`
+- **Context contracts:** `.claude/docs/context-contracts.md`
+- **Agent catalog:** `.claude/docs/agent-catalog.md`
+- **Code examples:** `.claude/templates/code-examples/`
+- **Package source:** `@aaxis/claude-agents` (npm package)

package/templates/code-examples/approval_gate_workflow.py

@@ -0,0 +1,141 @@
+# Phase 4: Approval Gate Workflow Example
+# MANDATORY for T3 operations (terraform apply, kubectl apply, git push to main)
+
+import sys
+sys.path.insert(0, '/home/jaguilar/aaxis/rnd/repositories/.claude/tools')
+from approval_gate import request_approval, process_approval_response
+
+# Example 1: Generate approval summary
+def generate_approval_summary(realization_package: dict, agent_name: str, phase: str):
+    """
+    Generate structured approval summary from realization package.
+    """
+    approval_data = request_approval(
+        realization_package=realization_package,
+        agent_name=agent_name,  # "gitops-operator", "terraform-architect", etc.
+        phase=phase  # "Phase 3.3", "Deploy production", etc.
+    )
+
+    # approval_data contains:
+    # - summary: Human-readable breakdown
+    # - question_config: Pre-formatted for AskUserQuestion
+    # - gate_instance: Reference for validation step
+
+    return approval_data
+
+
+# Example 2: Present summary and ask user
+def ask_user_approval(approval_data: dict):
+    """
+    Present approval summary and ask for user decision.
+    """
+    # Show summary
+    print(approval_data["summary"])
+
+    # Ask question (3 options: Approve, Reject, Other)
+    question_config = approval_data["question_config"]
+    # response = AskUserQuestion(**question_config)  # Simulated
+
+    # Example response
+    response = {"answers": {"question_1": "✅ Aprobar y ejecutar"}}
+
+    return response
+
+
+# Example 3: Validate user response
+def validate_approval(approval_data: dict, user_response: dict, realization_package: dict, agent_name: str, phase: str):
+    """
+    Process user response and determine if approved.
+    """
+    validation = process_approval_response(
+        gate_instance=approval_data["gate_instance"],
+        user_response=user_response["answers"]["question_1"],
+        realization_package=realization_package,
+        agent_name=agent_name,
+        phase=phase
+    )
+
+    # validation contains:
+    # - approved: Boolean (True if user approved)
+    # - action: String ("proceed", "halt_workflow", "clarify_with_user")
+    # - reason: String (explanation)
+
+    return validation
+
+
+# Example 4: Enforcement rules
+def enforce_approval_gate(validation: dict):
+    """
+    Enforce approval gate rules before proceeding to Phase 5.
+    """
+    if validation["approved"]:
+        # Approved, proceed to Phase 5 (Realization)
+        return {"allow_phase_5": True}
+
+    if validation["action"] == "halt_workflow":
+        # Rejected, STOP workflow
+        return {
+            "allow_phase_5": False,
+            "message": "User rejected realization. Workflow halted."
+        }
+
+    if validation["action"] == "clarify_with_user":
+        # Need more info, re-run approval gate
+        return {
+            "allow_phase_5": False,
+            "message": "Clarification needed. Re-run approval gate."
+        }
+
+    # Default: deny
+    return {"allow_phase_5": False, "message": "Unknown validation state"}
+
+
+# Example 5: Full approval gate workflow
+def approval_gate_workflow(realization_package: dict, agent_name: str, phase: str):
+    """
+    Complete Phase 4 workflow (MANDATORY for T3 operations).
+    """
+    # Step 1: Generate approval summary
+    approval_data = generate_approval_summary(realization_package, agent_name, phase)
+
+    # Step 2: Ask user for approval
+    user_response = ask_user_approval(approval_data)
+
+    # Step 3: Validate response
+    validation = validate_approval(
+        approval_data,
+        user_response,
+        realization_package,
+        agent_name,
+        phase
+    )
+
+    # Step 4: Enforce rules
+    enforcement = enforce_approval_gate(validation)
+
+    if not enforcement["allow_phase_5"]:
+        # Cannot proceed to Phase 5
+        return {
+            "status": "blocked",
+            "message": enforcement["message"]
+        }
+
+    # Approved, can proceed to Phase 5
+    return {
+        "status": "approved",
+        "message": "User approved. Proceeding to Phase 5 (Realization)."
+    }
+
+
+# Example 6: CRITICAL - Cannot skip approval gate
+def attempt_to_skip_approval_gate():
+    """
+    This is an ANTI-PATTERN. NEVER do this.
+    """
+    # ❌ WRONG: Skip approval gate for T3 operation
+    # Task(subagent_type="gitops-operator", prompt="Deploy to prod")  # Direct realization
+    # This violates Rule 5.1 [P0]: Approval Gate Enforcement
+
+    # ✅ CORRECT: Always go through approval gate
+    # Phase 3: Planning -> Phase 4: Approval Gate -> Phase 5: Realization
+    pass