@jaguilar87/gaia-ops 1.0.0

package/speckit/README.md

@@ -0,0 +1,353 @@
+# Spec-Kit 2.0 - Framework de Desarrollo de Features Estructurado
+
+Framework simplificado para desarrollo dirigido por especificaciones con orchestración inteligente de agentes.
+
+## 🎯 Visión General
+
+Spec-Kit 2.0 es un workflow automatizado que traduce descripciones de features en implementaciones completas:
+
+```
+Idea → Spec → Plan → Tasks → Implementation
+```
+
+**Mejoras en 2.0**:
+- ✅ **Simplificado**: 5 comandos core (antes 10)
+- ✅ **Automático**: Clarificación, validación y enrichment integrados
+- ✅ **Inteligente**: Auto-context desde project-context.json
+- ✅ **Sin pasos manuales**: tasks-richer.py eliminado, todo inline
+- ✅ **Governance simple**: ADRs inmutables vs constitution versionado
+
+---
+
+## 📋 Workflow Simplificado
+
+### Paso 0: Bootstrap (Una vez por proyecto)
+```bash
+/speckit.init
+```
+- Valida/crea `project-context.json`
+- Configura paths de GitOps, Terraform, GCP
+- Ready para crear features
+
+### Paso 1: Especificar Feature
+```bash
+/speckit.specify spec-kit-tcm-plan Add dark mode toggle to settings
+```
+- Crea `spec.md` con template
+- **AUTO-LLENA** project context (cluster, namespace, paths)
+- Genera functional requirements y user stories
+- Output: `specs/00N-dark-mode-toggle/spec.md`
+
+### Paso 2: Planear Implementación
+```bash
+/speckit.plan spec-kit-tcm-plan 00N-dark-mode-toggle
+```
+- **INTEGRA clarify**: Detecta ambigüedades, pregunta inline (max 5 questions)
+- Lee governance.md para standards
+- Genera plan técnico con arquitectura, data model, contracts
+- Output: `plan.md`, `data-model.md`, `contracts/`, `research.md`
+
+### Paso 3: Generar Tareas
+```bash
+/speckit.tasks spec-kit-tcm-plan 00N-dark-mode-toggle
+```
+- Genera tasks.md con metadata INLINE (no post-process)
+- **INTEGRA validation**: Auto-detecta coverage gaps, inconsistencias
+- **AUTO-ENRICH**: Cada task con agent, tier, tags, confidence
+- **GATE**: Pausa si issues CRITICAL
+- Output: `tasks.md` (listo para implement)
+
+### Paso 4: Implementar
+```bash
+/speckit.implement spec-kit-tcm-plan 00N-dark-mode-toggle
+```
+- Lee tasks.md enriquecido
+- Auto-ejecuta tasks con agentes especializados
+- T2/T3 tasks → Auto-análisis antes de ejecutar
+- TaskManager para files >25K tokens
+- Output: Código implementado, tests, docs
+
+---
+
+## 🚀 Comandos Core (5)
+
+| Comando | Propósito | Integra |
+|---------|-----------|---------|
+| `/speckit.init` | Bootstrap project configuration | project-context.json validation |
+| `/speckit.specify` | Create feature spec | Auto-context filling |
+| `/speckit.plan` | Generate implementation plan | Clarification (inline) |
+| `/speckit.tasks` | Generate enriched task list | Validation + Enrichment (inline) |
+| `/speckit.implement` | Execute tasks with agents | High-risk analysis (auto) |
+
+## 🛠️ Comandos Auxiliares (3)
+
+| Comando | Uso |
+|---------|-----|
+| `/speckit.add-task` | Add single task during implementation (inline enrichment) |
+| `/speckit.analyze-task` | Deep analysis of specific task (auto-triggered for T2/T3) |
+| `/save-session` | Export session bundle with context |
+
+---
+
+## 📁 Estructura de Proyecto
+
+```
+.claude-shared/speckit/
+├── governance.md                 # Project-wide principles (NO versioning)
+├── decisions/                    # ADRs (immutable records)
+│   └── ADR-001-example.md
+├── templates/
+│   ├── spec-template.md
+│   ├── plan-template.md
+│   ├── tasks-template.md
+│   └── adr-template.md
+├── scripts/                      # Bash automation
+└── README.md                     # This file
+
+<speckit-root>/                   # e.g., spec-kit-tcm-plan/
+└── specs/
+    ├── 001-feature-name/
+    │   ├── spec.md               # Auto-filled with project context
+    │   ├── plan.md               # With clarifications integrated
+    │   ├── tasks.md              # With inline metadata
+    │   ├── data-model.md
+    │   └── contracts/
+    └── 002-another-feature/
+```
+
+---
+
+## 🔑 Características Clave
+
+### 1. Auto-Context desde project-context.json
+
+`/specify` automáticamente llena:
+- `[PROJECT_ID]` → `aaxis-rnd-general-project`
+- `[CLUSTER]` → `tcm-gke-non-prod`
+- `[GITOPS_PATH]` → `/path/to/gitops`
+- `[TERRAFORM_PATH]` → `/path/to/terraform`
+
+**Sin project-context.json**: Pregunta interactivamente y sugiere ejecutar `/init`.
+
+### 2. Clarification Integrada en /plan
+
+ANTES (Spec-Kit 1.0):
+```bash
+/specify ...
+/clarify ...      # Manual step
+/plan ...
+```
+
+AHORA (Spec-Kit 2.0):
+```bash
+/specify ...
+/plan ...         # Clarify happens inline automatically
+```
+
+### 3. Validation Integrada en /tasks
+
+ANTES:
+```bash
+/tasks ...
+/analyze-plan ... # Manual validation
+```
+
+AHORA:
+```bash
+/tasks ...        # Validation happens inline automatically
+```
+
+### 4. Task Enrichment Inline
+
+ANTES:
+```bash
+/tasks ...
+python3 tasks-richer.py ... # Manual enrichment
+```
+
+AHORA:
+```bash
+/tasks ...        # Enrichment happens during generation
+```
+
+Cada task generada con:
+```markdown
+- [ ] T001 Create GKE cluster configuration
+  <!-- 🤖 Agent: terraform-architect | 👁️ T0 | ⚡ 0.85 -->
+  <!-- 🏷️ Tags: #terraform #infrastructure #gke -->
+  <!-- 🎯 skill: terraform_infrastructure (8.0) -->
+```
+
+### 5. Governance con ADRs (No Versioning)
+
+ANTES:
+- `constitution.md` con semantic versioning (MAJOR.MINOR.PATCH)
+- Complex template propagation
+- Per-feature versioning
+
+AHORA:
+- `governance.md` simple (project-wide standards)
+- ADRs para decisions (immutable, one per decision)
+- Git history = versioning (no manual version numbers)
+
+**Crear ADR**:
+1. Copy `.claude-shared/speckit/templates/adr-template.md`
+2. Fill with decision context, options, rationale
+3. Save to `.claude-shared/speckit/decisions/ADR-XXX-title.md`
+4. Reference in commits: `feat: implement feature (ADR-005)`
+
+---
+
+## 🧠 Agent Routing
+
+Spec-Kit integra con agentes especializados:
+
+| Agent | Triggers | Tier |
+|-------|----------|------|
+| **terraform-architect** | terraform, terragrunt, .tf, infrastructure, gke, vpc | T0-T3 |
+| **gitops-operator** | kubectl, helm, flux, kubernetes, deployment, service | T0-T3 |
+| **gcp-troubleshooter** | gcloud, GCP, cloud logging, IAM | T0 |
+| **devops-developer** | docker, npm, build, test, CI, Dockerfile | T0-T1 |
+
+**Code-First Protocol**: Todos los agentes exploran patterns existentes antes de crear nuevos recursos.
+
+---
+
+## 📝 Ejemplos
+
+### Bootstrap Nuevo Proyecto
+```bash
+# 1. Initialize (interactive)
+/speckit.init
+
+# Questions asked:
+# - GCP Project ID? aaxis-rnd-general-project
+# - Region? us-central1
+# - Cluster? tcm-gke-non-prod
+# - GitOps path? /path/to/gitops
+# - Terraform path? /path/to/terraform
+
+# Creates .claude/project-context.json
+```
+
+### Feature Completo
+```bash
+# 1. Specify
+/speckit.specify spec-kit-tcm-plan Add user authentication with OAuth2
+
+# Auto-fills: project_id, cluster, gitops_path, terraform_path
+# Output: specs/003-user-authentication/spec.md
+
+# 2. Plan (with auto-clarify)
+/speckit.plan spec-kit-tcm-plan 003-user-authentication
+
+# Asks max 5 clarification questions inline:
+# Q1: Which OAuth provider? (Google, GitHub, Azure)
+# Q2: Session duration? (1h, 24h, 7d)
+# Updates spec.md with answers
+# Output: plan.md, data-model.md, contracts/
+
+# 3. Tasks (with auto-validation)
+/speckit.tasks spec-kit-tcm-plan 003-user-authentication
+
+# Generates 25 tasks with inline metadata
+# Validates coverage (100%), no critical issues
+# Output: tasks.md (ready to implement)
+
+# 4. Implement
+/speckit.implement spec-kit-tcm-plan 003-user-authentication
+
+# Executes tasks with agents:
+# T001 → terraform-architect (T2)
+# T002 → gitops-operator (T3)
+# T003 → devops-developer (T1)
+# Output: Código + commits
+```
+
+### Agregar Task Durante Implementación
+```bash
+/speckit.add-task spec-kit-tcm-plan 003-user-authentication
+
+# Interactive:
+# Task description? Configure session timeout middleware
+# Task ID? T026
+# Phase? Integration
+# Parallel? No
+
+# Generates with inline metadata:
+# - [ ] T026 Configure session timeout middleware
+#   <!-- 🤖 Agent: devops-developer | ✅ T1 | ⚡ 0.75 -->
+#   <!-- 🏷️ Tags: #config #security #middleware -->
+```
+
+---
+
+## 🔧 Troubleshooting
+
+### Error: project-context.json not found
+```bash
+/speckit.init
+# Creates .claude/project-context.json interactively
+```
+
+### Error: Task file exceeds token limit (>25K)
+TaskManager handles this automatically during `/implement`. No manual intervention.
+
+### Error: CRITICAL issues in validation
+```markdown
+### Validation Report
+Issues: 1 critical, 2 high
+
+| ID | Severity | Summary |
+|----|----------|---------|
+| A1 | CRITICAL | "Performance monitoring" has zero tasks |
+
+# Fix: Add tasks or mark as out-of-scope in spec.md
+```
+
+### Warning: High-risk task (T2/T3)
+```markdown
+T055 Apply Terraform VPC changes (T3)
+⚠️ HIGH RISK: Analyze before execution
+
+# /speckit.analyze-task auto-triggered
+# User approval required before execution
+```
+
+---
+
+## 📚 Governance
+
+- **Standards**: `.claude-shared/speckit/governance.md`
+- **Decisions**: `.claude-shared/speckit/decisions/ADR-XXX-title.md`
+- **Commit Format**: Conventional Commits (enforced by hooks)
+- **Security Tiers**: T0 (read) → T1 (validate) → T2 (plan) → T3 (apply)
+
+---
+
+## 🆕 What's New in 2.0
+
+| Feature | 1.0 | 2.0 |
+|---------|-----|-----|
+| Commands | 10 | **5 core + 3 aux** |
+| Clarify | Manual `/clarify` | **Integrated in `/plan`** |
+| Validation | Manual `/analyze-plan` | **Integrated in `/tasks`** |
+| Enrichment | External `tasks-richer.py` | **Inline during generation** |
+| Governance | Versioned constitution.md | **governance.md + ADRs** |
+| Init | Deprecated | **Revived with project-context** |
+| Auto-context | None | **project-context.json integration** |
+
+---
+
+## 📖 Ver También
+
+- [Agent Prompts](../.claude-shared/agents/) - terraform-architect, gitops-operator, etc.
+- [Governance](governance.md) - Project-wide standards
+- [ADR Template](templates/adr-template.md) - Decision record template
+- [CLAUDE.md](../../CLAUDE.md) - Orchestrator workflow
+
+---
+
+**Versión**: 2.0.0
+**Última actualización**: 2025-11-05
+**Maintainers**: Claude Code Agent System

package/speckit/governance.md

@@ -0,0 +1,169 @@
+# Project Governance
+
+This document defines the architectural principles and standards that guide all development decisions in this project.
+
+## Stack Definition
+
+### Infrastructure Layer
+- **Cloud Provider**: Google Cloud Platform (GCP)
+- **Region**: us-central1
+- **Project ID**: aaxis-rnd-general-project
+- **Infrastructure as Code**: Terraform + Terragrunt
+- **Terraform Base Path**: `/home/jaguilar/aaxis/rnd/repositories/terraform`
+
+### Kubernetes Layer
+- **Orchestration**: Google Kubernetes Engine (GKE)
+- **Cluster**: tcm-gke-non-prod
+- **GitOps Tool**: Flux CD
+- **GitOps Repository**: `/home/jaguilar/aaxis/rnd/repositories/gitops`
+- **Package Manager**: Helm
+
+### Application Layer
+- **Primary Database**: PostgreSQL (Cloud SQL)
+- **Instance**: tcm-postgres-non-prod
+- **Container Registry**: Artifact Registry (us-central1-docker.pkg.dev)
+- **Service Architecture**: Microservices with Helm charts
+
+## Core Architectural Principles
+
+### 1. Code-First Protocol (Mandatory)
+
+**All agents MUST analyze existing patterns before creating new resources.**
+
+When creating any new infrastructure or Kubernetes resource:
+1. **Discover**: Search for similar existing resources in the codebase
+2. **Read**: Examine 2-3 examples to identify patterns
+3. **Extract**: Document directory structure, naming conventions, configuration patterns
+4. **Replicate**: Follow discovered patterns, adapt only what's specific to the new resource
+5. **Explain**: Document which pattern was followed and why
+
+**Rationale**: Ensures consistency, reduces drift, and leverages proven configurations.
+
+### 2. GitOps as Single Source of Truth
+
+**All Kubernetes changes MUST go through Git, never direct cluster manipulation.**
+
+- Infrastructure state lives in Terraform repository
+- Application state lives in GitOps repository
+- Flux CD synchronizes Git → Cluster
+- Manual `kubectl apply` is forbidden in production workflows
+- All changes require git commit → push → Flux reconciliation
+
+**Rationale**: Auditability, rollback capability, and declarative state management.
+
+### 3. Security Tier Enforcement
+
+**All operations are classified by security tier with explicit approval gates.**
+
+| Tier | Operations | Approval |
+|------|-----------|----------|
+| T0 | Read-only (get, describe, logs, plan) | Auto-approved |
+| T1 | Validation (validate, template, lint) | Auto-approved |
+| T2 | Simulation (dry-run, plan) | Auto-approved |
+| T3 | Realization (apply, push, reconcile) | User approval required |
+
+**Rationale**: Prevents accidental infrastructure changes and provides approval visibility.
+
+### 4. Conventional Commits Standard
+
+**All commits MUST follow Conventional Commits specification.**
+
+Format: `<type>(<scope>): <description>`
+
+Allowed types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `ci`, `perf`, `style`, `build`
+
+Examples:
+- `feat(helmrelease): add report-generator worker service`
+- `fix(terraform): correct VPC network peering configuration`
+- `refactor(gitops): consolidate duplicate service account definitions`
+
+**Rationale**: Enables automated changelog generation, semantic versioning, and clear change tracking.
+
+### 5. Workload Identity for All Services
+
+**All GKE services MUST use Workload Identity, not service account keys.**
+
+- Create Kubernetes ServiceAccount with GCP IAM binding annotation
+- Bind GCP Service Account with `iam.workloadIdentityUser` role
+- Never use downloaded JSON keys in containers
+
+**Rationale**: Eliminates static credentials, follows GCP security best practices, automatic key rotation.
+
+### 6. Resource Limits as Default
+
+**All Helm releases MUST define resource requests and limits.**
+
+Standard tiers:
+- **Small**: 256Mi/512Mi memory, 250m/500m CPU
+- **Medium**: 512Mi/1Gi memory, 500m/1000m CPU
+- **Large**: 1Gi/2Gi memory, 1000m/2000m CPU
+
+**Rationale**: Prevents resource contention, enables proper scheduling, cost predictability.
+
+## Decision Making Process
+
+### When to Create an ADR
+
+Create an Architecture Decision Record (ADR) when:
+- Choosing between multiple viable technical approaches
+- Making a decision that affects multiple services or teams
+- Establishing a new pattern or standard
+- Deviating from an existing principle for valid reasons
+
+**ADR Template**: `.claude-shared/speckit/templates/adr-template.md`
+
+**ADR Location**: `.claude-shared/speckit/decisions/`
+
+### ADR Lifecycle
+
+1. **Draft**: Create ADR with status "Proposed"
+2. **Review**: Share with team (if applicable)
+3. **Decide**: Update status to "Accepted" or "Rejected"
+4. **Implement**: Reference ADR number in commits
+5. **Archive**: ADRs are immutable; superseding decisions get new ADRs
+
+**Rationale**: Decisions are immutable historical records. Context matters more than current state.
+
+## Standards Evolution
+
+### How to Update This Document
+
+1. Identify need for principle change
+2. Create ADR documenting the proposed change and rationale
+3. If ADR is accepted, update this governance.md
+4. Commit both files together with message: `docs(governance): [description] (ADR-XXX)`
+
+### Versioning Strategy
+
+This document uses **Git history as version control**. No semantic versioning.
+
+- To see why a principle exists: `git log -p governance.md`
+- To see decision context: Read corresponding ADR
+- To propose changes: Create ADR first, then update
+
+**Rationale**: Git already provides perfect versioning. Additional versioning adds complexity without value.
+
+## Compliance
+
+### Enforcement
+
+These principles are enforced through:
+1. **Agent Protocols**: Specialized agents (terraform-architect, gitops-operator) follow these standards
+2. **Validation Hooks**: Pre-commit and pre-tool-use hooks validate compliance
+3. **Security Tiers**: Permission system blocks non-compliant operations
+4. **Code Review**: Human review of T3 operations before realization
+
+### Exceptions
+
+Exceptions to these principles require:
+1. ADR documenting the exception and time-bound context
+2. Explicit approval in the ADR review process
+3. Scheduled re-evaluation date in ADR
+
+**No permanent exceptions.** All deviations must justify their continued existence or be removed.
+
+---
+
+**Last Updated**: 2025-11-05
+**Related ADRs**: None yet (foundation document)
+**Supersedes**: constitution.md (deprecated)