@jaguilar87/gaia-ops 1.0.0

package/commands/speckit.init.md

@@ -0,0 +1,237 @@
+---
+description: Bootstrap Spec-Kit structure and validate/create project-context.json
+---
+
+**USAGE**: `/speckit.init [feature-name]`
+
+**Examples**:
+```
+/speckit.init 005-new-feature
+/speckit.init  # Without feature name - just validates project-context.json
+```
+
+## Purpose
+
+Initialize Spec-Kit for a new feature or bootstrap the project configuration. This command:
+1. Validates that `project-context.json` exists and is properly configured
+2. If missing, interactively creates `project-context.json` from user input
+3. Optionally creates feature directory structure with templates
+
+## Execution Steps
+
+### 1. Validate project-context.json
+
+Check if `.claude/project-context.json` exists:
+
+**If EXISTS**:
+- Read and validate structure
+- Check required fields:
+  - `project_details.id`
+  - `project_details.region`
+  - `project_details.cluster_name`
+  - `gitops_configuration.repository.path`
+  - `terraform_infrastructure.layout.base_path`
+- Report validation results
+- If missing critical fields, offer to fix interactively
+
+**If NOT EXISTS**:
+- Inform user that project-context.json is missing
+- Offer to create it interactively
+- Ask the following questions:
+
+#### Interactive Project Context Creation
+
+**Question 1: GCP Project ID**
+```
+What is your GCP project ID?
+Example: aaxis-rnd-general-project
+```
+
+**Question 2: GCP Region**
+```
+What is your primary GCP region?
+Options:
+- us-central1
+- us-east1
+- us-west1
+- europe-west1
+- Other (specify)
+```
+
+**Question 3: GKE Cluster Name**
+```
+What is your GKE cluster name?
+Example: tcm-gke-non-prod
+```
+
+**Question 4: GitOps Repository Path**
+```
+What is the ABSOLUTE path to your GitOps repository?
+Example: /home/jaguilar/aaxis/rnd/repositories/gitops
+```
+
+**Question 5: Terraform Repository Path**
+```
+What is the ABSOLUTE path to your Terraform repository?
+Example: /home/jaguilar/aaxis/rnd/repositories/terraform
+```
+
+**Question 6: PostgreSQL Instance (Optional)**
+```
+PostgreSQL Cloud SQL instance name (or skip):
+Example: tcm-postgres-non-prod
+[Press Enter to skip]
+```
+
+After collecting answers, generate `project-context.json`:
+
+```json
+{
+  "version": "2.0.0",
+  "last_updated": "YYYY-MM-DD",
+  "project_details": {
+    "id": "<answer1>",
+    "region": "<answer2>",
+    "environment": "non-prod",
+    "cluster_name": "<answer3>"
+  },
+  "gitops_configuration": {
+    "repository": {
+      "path": "<answer4>",
+      "structure": "flux-standard"
+    },
+    "flux_details": {
+      "version": "v2",
+      "reconciliation_interval": "5m"
+    }
+  },
+  "terraform_infrastructure": {
+    "layout": {
+      "base_path": "<answer5>",
+      "structure": "terragrunt-hierarchical"
+    },
+    "provider_credentials": {
+      "auth_method": "gcloud-default"
+    }
+  },
+  "databases": {
+    "postgres": {
+      "instance": "<answer6>",
+      "type": "cloud-sql"
+    }
+  },
+  "operational_guidelines": {
+    "commit_standards": "conventional-commits",
+    "gitops_principles": "flux-cd",
+    "security_tiers": ["T0", "T1", "T2", "T3"]
+  }
+}
+```
+
+Write file to `.claude/project-context.json` and report success.
+
+### 2. Feature Directory Bootstrap (Optional)
+
+If `[feature-name]` argument provided:
+
+a) **Determine Spec-Kit root**:
+   - Check if directory `spec-kit-tcm-plan` exists in current directory
+   - If not, ask user: "Spec-Kit root directory name? (default: spec-kit-tcm-plan)"
+
+b) **Create feature directory structure**:
+   ```
+   <speckit-root>/specs/<feature-name>/
+   ├── spec.md          (from .claude/speckit/templates/spec-template.md)
+   ├── plan.md          (empty placeholder)
+   ├── tasks.md         (empty placeholder)
+   └── contracts/       (empty directory)
+   ```
+
+c) **Initialize spec.md with project context**:
+   - Copy spec-template.md to feature directory
+   - **AUTO-FILL** placeholders using project-context.json:
+     - `[PROJECT_ID]` → `project_details.id`
+     - `[REGION]` → `project_details.region`
+     - `[CLUSTER]` → `project_details.cluster_name`
+     - `[GITOPS_PATH]` → `gitops_configuration.repository.path`
+     - `[TERRAFORM_PATH]` → `terraform_infrastructure.layout.base_path`
+
+d) **Report feature initialization**:
+   ```markdown
+   ✅ Feature initialized: <feature-name>
+
+   **Directory**: <speckit-root>/specs/<feature-name>/
+   **Files created**:
+   - spec.md (auto-filled with project context)
+   - plan.md (placeholder)
+   - tasks.md (placeholder)
+   - contracts/ (directory)
+
+   **Next steps**:
+   1. Edit spec.md to define your feature
+   2. Run: /speckit.plan <speckit-root> <feature-name>
+   ```
+
+### 3. Validation Summary
+
+Always output validation summary:
+
+```markdown
+## Project Context Validation
+
+✅ project-context.json exists
+✅ All required fields present
+✅ GitOps path exists: <path>
+✅ Terraform path exists: <path>
+
+**Configuration**:
+- Project ID: <id>
+- Region: <region>
+- Cluster: <cluster-name>
+- GitOps: <path>
+- Terraform: <path>
+
+**Spec-Kit Status**:
+- Governance: .claude/speckit/governance.md
+- ADR Template: .claude/speckit/templates/adr-template.md
+- Commands: /specify, /plan, /tasks, /implement, /init
+
+**You're ready to use Spec-Kit!**
+```
+
+## Error Handling
+
+**Missing paths**:
+```
+⚠️ WARNING: GitOps path does not exist: <path>
+This may cause issues with gitops-operator agent.
+Recommendation: Create directory or update project-context.json
+```
+
+**Invalid JSON**:
+```
+❌ ERROR: project-context.json is malformed
+<JSON parse error>
+
+Fix the JSON syntax or delete the file to regenerate.
+```
+
+**Permission issues**:
+```
+❌ ERROR: Cannot write to .claude/project-context.json
+Check directory permissions for .claude/
+```
+
+## Notes
+
+- **Run once per project** to create project-context.json
+- **Run per feature** to bootstrap new feature directory
+- **Idempotent**: Safe to run multiple times (won't overwrite existing files)
+- **No config.json**: Spec-Kit 2.0 uses project-context.json + explicit arguments
+- **No constitution.md**: Replaced with governance.md (project-wide, not versioned per feature)
+
+## See Also
+
+- `/speckit.specify` - Create feature specification (uses project-context.json)
+- `/speckit.plan` - Generate implementation plan
+- `.claude/speckit/governance.md` - Project governance principles

package/commands/speckit.plan.md

@@ -0,0 +1,88 @@
+---
+description: Execute the implementation planning workflow using the plan template to generate design artifacts.
+---
+
+The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
+
+User input:
+
+$ARGUMENTS
+
+**IMPORTANT**: This command now requires TWO arguments:
+1. `<speckit-root>`: Path to spec-kit root directory (e.g., `spec-kit-tcm-plan` or `/absolute/path/to/spec-kit-tcm-plan`)
+2. `<feature-name>`: Feature name (e.g., `004-project-guidance-deployment`)
+
+**Example usage**:
+```
+/speckit.plan spec-kit-tcm-plan 004-project-guidance-deployment
+```
+
+Given the implementation details provided as an argument, do this:
+
+1. Extract `<speckit-root>` and `<feature-name>` from $ARGUMENTS. If not provided, ERROR and show usage example.
+2. Run `.claude/speckit/scripts/setup-plan.sh --json <speckit-root> <feature-name>` from the repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, FEATURE_DIR, FEATURE_NAME, SPECKIT_ROOT. All future file paths must be absolute.
+
+3. **Automatic Clarification (Integrated)**:
+   BEFORE proceeding with planning, perform ambiguity detection and clarification:
+
+   a) **Scan for ambiguities** across these categories:
+      - Functional Scope (user goals, out-of-scope, roles)
+      - Data Model (entities, relationships, lifecycle)
+      - Non-Functional (performance, security, reliability targets)
+      - Integration (external APIs, failure modes)
+      - Edge Cases (error handling, conflicts)
+      - Terminology (vague adjectives like "robust", "intuitive")
+
+   b) **Generate clarification questions** (max 5 total):
+      - Only ask if answer materially impacts architecture, data model, or testing
+      - Prioritize by Impact × Uncertainty heuristic
+      - Use multiple-choice (2-5 options) or short-answer (≤5 words)
+      - Skip if already answered in spec or low-impact
+
+   c) **Interactive questioning** (if needed):
+      - Present ONE question at a time
+      - For multiple-choice, use markdown table with options
+      - After answer, validate and integrate IMMEDIATELY into spec
+      - Create `## Clarifications / ### Session YYYY-MM-DD` section
+      - Update appropriate sections (Functional Requirements, Data Model, etc.)
+      - Save spec after EACH answer (atomic updates)
+      - Stop when: all critical ambiguities resolved, user says "done", or 5 questions reached
+
+   d) **Clarification Results**:
+      - If NO ambiguities found: Report "No critical ambiguities detected" and continue
+      - If clarifications made: Report count, sections updated, suggest proceeding
+      - If high-impact areas still unresolved: Warn user about rework risk
+
+   **CRITICAL**: Clarification is automatic and integrated. No separate command invocation required.
+
+4. Read and analyze the feature specification to understand:
+   - The feature requirements and user stories
+   - Functional and non-functional requirements
+   - Success criteria and acceptance criteria
+   - Any technical constraints or dependencies mentioned
+
+5. Read governance.md to understand architectural principles and standards:
+   - Path: `.claude/speckit/governance.md` (project-wide standards)
+   - Extract: Code-First Protocol, GitOps principles, security tiers, commit standards
+
+4. Execute the implementation plan template:
+   - Load `.claude/speckit/templates/plan-template.md` (already copied to IMPL_PLAN path as plan.md)
+   - Set Input path to FEATURE_SPEC
+   - Run the Execution Flow (main) function steps 1-9
+   - The template is self-contained and executable
+   - Follow error handling and gate checks as specified
+   - Let the template guide artifact generation in $SPECS_DIR:
+     * Phase 0 generates research.md
+     * Phase 1 generates plan.md, data-model.md, contracts/, quickstart.md
+     * Phase 2 generates tasks.md
+   - Incorporate user-provided details from arguments into Technical Context: $ARGUMENTS
+   - Update Progress Tracking as you complete each phase
+
+5. Verify execution completed:
+   - Check Progress Tracking shows all phases complete
+   - Ensure all required artifacts were generated
+   - Confirm no ERROR states in execution
+
+6. Report results con las rutas generadas y los artefactos creados (no es necesario incluir la rama git).
+
+Use absolute paths with the repository root for all file operations to avoid path issues.

package/commands/speckit.specify.md

@@ -0,0 +1,161 @@
+---
+description: Create or update the feature specification from a natural language feature description.
+---
+
+The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
+
+User input:
+
+$ARGUMENTS
+
+**IMPORTANT**: This command now requires arguments in format:
+```
+/speckit.specify <speckit-root> <feature-description>
+```
+
+**Example usage**:
+```
+/speckit.specify spec-kit-tcm-plan Add dark mode toggle to settings
+```
+
+The text after `<speckit-root>` is the feature description.
+
+Given those arguments, do this:
+
+1. Extract `<speckit-root>` (first word) and `<feature-description>` (remaining text) from $ARGUMENTS.
+   - If speckit-root is missing, ERROR and show usage example.
+   - If feature-description is empty, ERROR and ask user to provide a description.
+
+2. **CLARIFICATION CHECK (NEW)**:
+   Before proceeding, analyze the feature description for ambiguity using the clarification engine:
+
+   ```python
+   import sys
+   sys.path.insert(0, '/home/jaguilar/aaxis/rnd/repositories/.claude/tools')
+   from clarify_engine import request_clarification, process_clarification
+
+   # Detect ambiguity in feature description
+   clarification_data = request_clarification(
+       user_prompt=feature_description,
+       command_context={"command": "speckit.specify"}
+   )
+
+   if clarification_data["needs_clarification"]:
+       # Present summary
+       print(clarification_data["summary"])
+
+       # Ask questions (AskUserQuestion tool)
+       response = AskUserQuestion(**clarification_data["question_config"])
+
+       # Enrich feature description
+       result = process_clarification(
+           clarification_data["engine_instance"],
+           feature_description,
+           response["answers"],
+           clarification_data["clarification_context"]
+       )
+
+       # Use enriched description for remaining steps
+       feature_description = result["enriched_prompt"]
+   ```
+
+   **What gets clarified**:
+   - Ambiguous service references (e.g., "add API endpoint" → which API?)
+   - Ambiguous namespace (e.g., "deploy to cluster" → which namespace?)
+   - Infrastructure keywords without specifics (e.g., "needs Redis" → which Redis instance?)
+   - Environment confusion (e.g., user says "prod" but context is "non-prod")
+
+   **Example clarification**:
+   ```
+   Feature description: "Add caching to the API"
+
+   Clarification question:
+   📦 Servicio
+   ¿Qué API quieres modificar?
+
+   Options:
+     📦 tcm-api (NestJS | tcm-non-prod | Port 3001 | ✅ Running)
+     📦 pg-api (Spring Boot | pg-non-prod | Port 8086 | ✅ Running)
+
+   Enriched description:
+   "Add caching to the API
+
+   [Clarification - service_ambiguity]: tcm-api"
+   ```
+
+3. Run the script `.claude/speckit/scripts/create-new-feature.sh --json <speckit-root> <feature-description>` from repo root and parse its JSON output for FEATURE_NAME, SPEC_FILE, FEATURE_DIR, and FEATURE_NUM. All file paths must be absolute.
+   **IMPORTANT** You must only ever run this script once. The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for.
+
+4. **Load project-context.json (MANDATORY)**:
+   Read `.claude/project-context.json` to auto-fill infrastructure placeholders.
+
+   **If project-context.json EXISTS**:
+   - Extract: `project_details.id`, `project_details.region`, `project_details.cluster_name`
+   - Extract: `gitops_configuration.repository.path`
+   - Extract: `terraform_infrastructure.layout.base_path`
+   - Extract (optional): `databases.postgres.instance`
+   - Use these values to replace placeholders in spec template
+
+   **If project-context.json MISSING**:
+   - Warn user: "⚠️ project-context.json not found"
+   - Suggest: "Run /speckit.init to create project configuration"
+   - **Ask interactively**:
+     - "GCP Project ID?"
+     - "GCP Region?"
+     - "GKE Cluster Name?"
+     - "GitOps repository path?"
+     - "Terraform repository path?"
+   - Store answers temporarily for this spec
+   - Recommend running /init after to persist configuration
+
+5. Load `.claude/speckit/templates/spec-template.md` to understand required sections.
+
+6. Write the specification to SPEC_FILE using the template structure:
+   - Replace **infrastructure placeholders** with project-context.json values:
+     - `[PROJECT_ID]` → `project_details.id`
+     - `[REGION]` → `project_details.region`
+     - `[CLUSTER]` → `project_details.cluster_name`
+     - `[GITOPS_PATH]` → `gitops_configuration.repository.path`
+     - `[TERRAFORM_PATH]` → `terraform_infrastructure.layout.base_path`
+     - `[POSTGRES_INSTANCE]` → `databases.postgres.instance` (if applicable)
+
+   - Replace **feature placeholders** with derived content from feature description:
+     - `[FEATURE_NAME]` → Extracted from arguments
+     - `[FEATURE_DESCRIPTION]` → User's feature description
+     - `[FUNCTIONAL_REQUIREMENTS]` → Analyze description for requirements
+     - `[USER_STORIES]` → Generate user stories from description
+     - `[TECHNICAL_CONSTRAINTS]` → Infer from description (or mark TBD)
+
+   - Preserve section order and headings from template
+   - Flag any placeholders that couldn't be auto-filled (mark with TODO)
+
+7. **Auto-context verification**:
+   - List which placeholders were auto-filled from project-context.json
+   - List which placeholders need manual completion
+   - If >5 manual placeholders remain, suggest running /clarify after
+
+8. Report completion with feature name, spec file path, feature directory, and auto-filled context summary:
+   ```markdown
+   ✅ Feature specification created: <FEATURE_NAME>
+
+   **Files**:
+   - Spec: <SPEC_FILE>
+   - Directory: <FEATURE_DIR>
+
+   **Auto-filled from project-context.json**:
+   - ✅ Project ID: <value>
+   - ✅ Region: <value>
+   - ✅ Cluster: <value>
+   - ✅ GitOps path: <value>
+   - ✅ Terraform path: <value>
+
+   **Manual placeholders** (review and complete):
+   - [ ] Performance targets (spec.md:L45)
+   - [ ] Security requirements (spec.md:L67)
+
+   **Next steps**:
+   1. Review and complete manual placeholders in spec.md
+   2. Run: /speckit.plan <speckit-root> <feature-name>
+   ```
+
+Note: The script creates the feature directory (specs/###-feature-name/) and initializes the spec file. Git workflow is managed separately by the user.

package/commands/speckit.tasks.md

@@ -0,0 +1,188 @@
+---
+description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
+---
+
+The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
+
+User input:
+
+$ARGUMENTS
+
+**IMPORTANT**: This command now requires TWO arguments:
+1. `<speckit-root>`: Path to spec-kit root directory (e.g., `spec-kit-tcm-plan`)
+2. `<feature-name>`: Feature name (e.g., `004-project-guidance-deployment`)
+
+**Example usage**:
+```
+/speckit.tasks spec-kit-tcm-plan 004-project-guidance-deployment
+```
+
+1. Extract `<speckit-root>` and `<feature-name>` from $ARGUMENTS. If not provided, ERROR and show usage example.
+2. Derive paths manually (no check-prerequisites.sh needed):
+   ```
+   SPECKIT_ROOT = <speckit-root> (resolve to absolute if relative)
+   FEATURE_DIR = $SPECKIT_ROOT/specs/<feature-name>
+   IMPL_PLAN = $FEATURE_DIR/plan.md
+   DATA_MODEL = $FEATURE_DIR/data-model.md
+   CONTRACTS_DIR = $FEATURE_DIR/contracts/
+   RESEARCH = $FEATURE_DIR/research.md
+   QUICKSTART = $FEATURE_DIR/quickstart.md
+   TASKS = $FEATURE_DIR/tasks.md
+   ```
+3. Check which design documents are available (use file existence checks):
+2. Load and analyze available design documents:
+   - Always read plan.md for tech stack and libraries
+   - IF EXISTS: Read data-model.md for entities
+   - IF EXISTS: Read contracts/ for API endpoints
+   - IF EXISTS: Read research.md for technical decisions
+   - IF EXISTS: Read quickstart.md for test scenarios
+
+   Note: Not all projects have all documents. For example:
+   - CLI tools might not have contracts/
+   - Simple libraries might not need data-model.md
+   - Generate tasks based on what's available
+
+3. Generate tasks following the template:
+   - Use `.claude/speckit/templates/tasks-template.md` as the base
+   - Replace example tasks with actual tasks based on:
+     * **Setup tasks**: Project init, dependencies, linting
+     * **Test tasks [P]**: One per contract, one per integration scenario
+     * **Core tasks**: One per entity, service, CLI command, endpoint
+     * **Integration tasks**: DB connections, middleware, logging
+     * **Polish tasks [P]**: Unit tests, performance, docs
+
+4. Task generation rules:
+   - Each contract file → contract test task marked [P]
+   - Each entity in data-model → model creation task marked [P]
+   - Each endpoint → implementation task (not parallel if shared files)
+   - Each user story → integration test marked [P]
+   - Different files = can be parallel [P]
+   - Same file = sequential (no [P])
+
+5. Order tasks by dependencies:
+   - Setup before everything
+   - Tests before implementation (TDD)
+   - Models before services
+   - Services before endpoints
+   - Core before integration
+   - Everything before polish
+
+6. Include parallel execution examples:
+   - Group [P] tasks that can run together
+   - Show actual Task agent commands
+
+7. Create FEATURE_DIR/tasks.md with enriched metadata:
+   - Correct feature name from implementation plan
+   - Numbered tasks (T001, T002, etc.)
+   - Clear file paths for each task
+   - Dependency notes
+   - Parallel execution guidance
+   - **INLINE metadata for EVERY task** (generated automatically, not post-processed)
+
+8. **Automatic Task Enrichment (MANDATORY)**:
+   For EACH task you generate, automatically add metadata comments IMMEDIATELY after the task line:
+
+   **Task Format**:
+   ```markdown
+   - [ ] T001 Create GKE cluster configuration
+     <!-- 🤖 Agent: terraform-architect | 👁️ T0 | ⚡ 0.85 -->
+     <!-- 🏷️ Tags: #terraform #infrastructure #gke -->
+     <!-- 🎯 skill: terraform_infrastructure (8.0) -->
+   ```
+
+   **Agent Routing Rules** (analyze task description):
+
+   | Keywords in Task | Agent | Tier |
+   |-----------------|-------|------|
+   | terraform, terragrunt, .tf, infrastructure, vpc, gke, cloud-sql | terraform-architect | T0 (read), T2 (plan), T3 (apply) |
+   | kubectl, helm, flux, kubernetes, k8s, deployment, service, ingress | gitops-operator | T0 (read), T2 (dry-run), T3 (push) |
+   | gcloud, GCP, cloud logging, IAM, service account | gcp-troubleshooter | T0 (diagnostics) |
+   | docker, npm, build, test, CI, pipeline, Dockerfile | devops-developer | T0-T1 |
+
+   **Security Tier Detection**:
+   - T0: describe, get, show, list, logs, read operations
+   - T1: validate, lint, template, format operations
+   - T2: plan, dry-run, diff operations
+   - T3: apply, push, create, delete, deploy operations (⚠️ HIGH RISK)
+
+   **Tag Generation** (add ALL matching):
+   - Tech: #terraform #kubernetes #helm #docker #gcp #aws
+   - Domain: #database #security #networking #api #monitoring
+   - Work: #setup #test #deploy #config #docs #debug
+
+   **Priority Signal**:
+   - ❓ Low complexity (setup, config, docs)
+   - ⚡ Medium complexity (implementation, integration)
+   - 🔥 High impact (security, database, production)
+
+   **High-Risk Warning** (for T2/T3 tasks):
+   ```markdown
+   - [ ] T042 Apply Terraform changes to production VPC
+     <!-- 🤖 Agent: terraform-architect | 🚫 T3 | 🔥 0.95 -->
+     <!-- 🏷️ Tags: #terraform #infrastructure #networking #production -->
+     <!-- ⚠️ HIGH RISK: Analyze before execution -->
+     <!-- 💡 Suggested: /speckit.analyze-task T042 -->
+     <!-- 🎯 skill: terraform_infrastructure (12.0) -->
+   ```
+
+   **CRITICAL**: Generate ALL tasks with metadata inline. NO post-processing step required.
+
+9. **Automatic Cross-Artifact Validation (Integrated)**:
+   After generating tasks.md, IMMEDIATELY perform consistency analysis:
+
+   a) **Load artifacts for validation**:
+      - spec.md: Functional/Non-functional requirements, User Stories, Edge Cases
+      - plan.md: Architecture, Data Model, Technical constraints
+      - tasks.md: All generated tasks with metadata
+      - governance.md: Architectural principles and standards
+
+   b) **Detection passes** (automated):
+      - **Duplication**: Flag near-duplicate requirements or tasks
+      - **Ambiguity**: Detect vague adjectives ("fast", "robust") without measurable criteria, unresolved TODOs/placeholders
+      - **Underspecification**: Requirements missing acceptance criteria, tasks referencing undefined components
+      - **Governance alignment**: Check against principles (GitOps, Code-First Protocol, Security Tiers, etc.)
+      - **Coverage gaps**: Requirements with zero tasks, tasks with no mapped requirement, missing non-functional coverage
+      - **Inconsistency**: Terminology drift, data entities mismatch, task ordering contradictions
+
+   c) **Severity assignment**:
+      - CRITICAL: Violates governance MUST principle, requirement with zero coverage
+      - HIGH: Duplicate/conflicting requirements, ambiguous security/performance
+      - MEDIUM: Terminology drift, missing non-functional coverage
+      - LOW: Style/wording improvements
+
+   d) **Validation report** (inline output):
+      ```markdown
+      ### Validation Report
+
+      **Metrics**:
+      - Total Requirements: X
+      - Total Tasks: Y
+      - Coverage: Z% (requirements with ≥1 task)
+      - Issues: A critical, B high, C medium, D low
+
+      **Issues Found**:
+      | ID | Severity | Category | Location | Summary | Recommendation |
+      |----|----------|----------|----------|---------|----------------|
+      | A1 | CRITICAL | Coverage | spec.md:L45 | "Performance monitoring" has zero tasks | Add task for metrics/logging setup |
+      | A2 | HIGH | Ambiguity | spec.md:L89 | "Fast response time" lacks metric | Clarify: <200ms p95 latency? |
+
+      **Next Actions**:
+      - If CRITICAL issues: Resolve before proceeding to /implement
+      - If only MEDIUM/LOW: Proceed with caution, address during implementation
+      ```
+
+   e) **Automatic remediation** (if no CRITICAL issues):
+      - For LOW/MEDIUM issues: Add notes to tasks.md Dependencies section
+      - For ambiguities: Flag for clarification during implementation
+      - For coverage gaps: Generate missing tasks inline
+
+   f) **Gate decision**:
+      - If CRITICAL issues found: Pause and require user approval to proceed
+      - If only HIGH/MEDIUM/LOW: Report and continue
+      - If zero issues: Report success and proceed
+
+   **CRITICAL**: Validation runs automatically. NO separate /analyze-plan command needed.
+
+Context for task generation: $ARGUMENTS
+
+The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.