@jaguilar87/gaia-ops 1.0.0

package/commands/architect.md

@@ -0,0 +1,97 @@
+---
+description: Invoke claude-architect to analyze system architecture, diagnose issues, or propose improvements
+scope: project
+---
+
+You are invoking the **claude-architect** meta-agent to analyze the agent orchestration system itself.
+
+## Context: System Expert Agent
+
+claude-architect is a specialized agent that understands:
+- The entire agent system architecture (.claude/, CLAUDE.md, agents, tools, hooks)
+- Spec-Kit workflows (specify, plan, tasks, implement, add-task, analyze-task)
+- Session management (save, restore, bundles)
+- Multi-repository structure (symlinks, ops/, shared configs)
+- Logs analysis and debugging
+- Test suite and validation
+- Best practices research via web search
+
+## Your Task
+
+Invoke the claude-architect agent with the user's request. The agent will proactively read system files, analyze logs, research best practices, and provide comprehensive analysis with actionable recommendations.
+
+**IMPORTANT:** Pass the user's exact question/request to the agent. Examples:
+- "Analiza este log y dime qué pasó"
+- "¿Por qué el routing está fallando?"
+- "¿Cómo funciona spec-kit?"
+- "Propón mejoras al sistema de contexto"
+- "Explica cómo funcionan los symlinks en ops/"
+
+## Invocation
+
+Use the Task tool to invoke claude-architect with this structure:
+
+```
+Task(
+    subagent_type="claude-architect",
+    description="[Brief 3-5 word description]",
+    prompt="""
+## System Context (Auto-provided)
+
+**System Paths:**
+- Agent system: /home/jaguilar/aaxis/rnd/repositories/.claude/
+- Orchestrator logic: /home/jaguilar/aaxis/rnd/repositories/CLAUDE.md
+- Logs: /home/jaguilar/aaxis/rnd/repositories/.claude/logs/
+- Tests: /home/jaguilar/aaxis/rnd/repositories/.claude/tests/
+- Tools: /home/jaguilar/aaxis/rnd/repositories/.claude/tools/
+- Agents: /home/jaguilar/aaxis/rnd/repositories/.claude/agents/
+- Commands: /home/jaguilar/aaxis/rnd/repositories/.claude/commands/
+- Sessions: /home/jaguilar/aaxis/rnd/repositories/.claude/session/
+- Ops repository: /home/jaguilar/aaxis/rnd/repositories/ops/
+- Project context: /home/jaguilar/aaxis/rnd/repositories/.claude/project-context.json
+
+**Spec-Kit Commands:**
+- /speckit.specify - Create/update feature specification
+- /speckit.plan - Generate implementation plan
+- /speckit.tasks - Generate tasks.md from plan
+- /speckit.implement - Execute tasks
+- /speckit.add-task - Add ad-hoc task
+- /speckit.analyze-task - Deep-dive task analysis
+
+**Session Commands:**
+- /save-session - Persist current session
+- /restore-session - Load previous session
+- /session-status - Check session state
+
+**Your System Knowledge:**
+You have complete knowledge of:
+1. **Agent System:** 5 specialist agents (terraform-architect, gitops-operator, gcp-troubleshooter, aws-troubleshooter, devops-developer)
+2. **Orchestrator:** CLAUDE.md workflow (routing, context provision, approval gates)
+3. **Context System:** context_provider.py, context contracts, enrichment
+4. **Routing:** agent_router.py, semantic matching, triggers
+5. **Security:** Hooks (pre_tool_use.py, post_tool_use.py), security tiers (T0-T3)
+6. **Spec-Kit:** Full workflow from specification to implementation
+7. **Sessions:** Active context, bundles, restoration
+8. **Multi-repo:** Symlinks structure in ops/ (claude-rnd, claude-vtr)
+9. **Logs:** JSONL format, audit trail, event tracking
+10. **Tests:** 55+ tests, routing accuracy, SSOT validation
+
+## User's Request
+
+{USER_REQUEST}
+
+## Your Mission
+
+1. **Understand the request:** What does the user want to know/analyze/improve?
+2. **Locate relevant files:** You know exactly where everything lives - read what you need
+3. **Analyze deeply:** Don't just read - understand patterns, issues, opportunities
+4. **Research if needed:** Use WebSearch for best practices, benchmarks, solutions
+5. **Provide comprehensive answer:** Include evidence, examples, recommendations
+6. **Propose next steps:** If applicable, suggest concrete action items
+
+**Remember:** You are the system expert. You have access to EVERYTHING. Use it.
+"""
+)
+```
+
+Replace `{USER_REQUEST}` with the user's actual question/request.

package/commands/restore-session.md

@@ -0,0 +1,87 @@
+---
+description: Restore a previous Claude session with intelligent context loading
+---
+
+This command provides intelligent session restoration with context loading for both main Claude and specialized sub-agents on-demand.
+
+## Quick command (restore latest relevant)
+```bash
+python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/session_startup_check.py
+```
+
+Shows the most relevant recent session with restoration suggestions.
+
+## Restore specific session
+```bash
+python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/restore_session.py <bundle-id>
+```
+
+Restores complete session context from the specified bundle.
+
+## List available sessions
+```bash
+python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/restore_session.py --list
+```
+
+Shows all available session bundles with descriptions and timestamps.
+
+## View session details (without restoring)
+```bash
+python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/restore_session.py <bundle-id> --show
+```
+
+Display detailed information about a session bundle without loading it.
+
+## Agent-specific context extraction
+```bash
+python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/restore_session.py <bundle-id> --agent terraform-architect
+python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/restore_session.py <bundle-id> --agent gitops-operator
+python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/restore_session.py <bundle-id> --agent devops-developer
+```
+
+Extract context specific to a particular agent type for on-demand loading.
+
+## Examples
+
+**View recent sessions:**
+```bash
+# Check what sessions are available
+/restore-session --list
+
+# See startup recommendations
+python3 .claude/session/scripts/session_startup_check.py
+```
+
+**Restore a session:**
+```bash
+# Full session restore
+/restore-session 2025-09-26-session-164535-384ea531
+
+# Just view details first
+/restore-session 2025-09-26-session-164535-384ea531 --show
+```
+
+**Agent context loading:**
+```bash
+# For terraform work
+/restore-session latest --agent terraform-architect
+
+# For kubernetes/GitOps work
+/restore-session latest --agent gitops-operator
+```
+
+## What gets restored
+
+- ✅ **Active context** - Current session state, primers, and context files
+- ✅ **Project state** - Git status, working directory, recent changes
+- ✅ **Session metadata** - Task information, timestamps, descriptions
+- ✅ **Conversation summary** - Key accomplishments and next steps
+
+## Session restoration is smart
+
+- **Non-destructive**: Backs up current context before restoring
+- **Selective**: Can extract context for specific agents without full restore
+- **Informative**: Shows session details before committing to restore
+- **Flexible**: Supports partial bundle IDs for convenience
+
+Use this when you want to continue work from a previous session or need context from past work for current tasks.

package/commands/save-session.md

@@ -0,0 +1,88 @@
+---
+description: Persist the current Claude session (bundle + active context) to disk.
+---
+
+This command saves the complete current session into a new bundle with all context, artifacts, and git operations captured. Use it whenever you want a comprehensive snapshot of your work before closing the workspace.
+
+## Quick command (recommended)
+
+### Default session bundle
+```bash
+python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/create_current_session_bundle.py
+```
+
+Creates: `2025-10-16-session-163244-abc12345`
+
+### Custom labeled bundle
+```bash
+python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/create_current_session_bundle.py --label agent-upgrades
+```
+
+Creates: `2025-10-16-agent-upgrades-163244-abc12345`
+
+**Options:**
+- `--label LABEL` - Add a custom descriptive label to the bundle name
+- `--no-git-ops` - Skip capturing git operations
+
+**Common labels:**
+- `agent-upgrades` - Agent system improvements
+- `feature-xyz` - Feature implementation
+- `bugfix-abc` - Bug fix work
+- `infrastructure` - Infrastructure changes
+- `refactor` - Code refactoring
+
+**Features:**
+- Creates a brand new bundle with unique timestamp ID
+- Captures complete session context: git operations, modified files, conversation summary
+- Copies important artifacts and active context for full restoration capability
+- Generates comprehensive metadata and human-readable summary template
+- Ready for sharing, archival, or future restoration
+
+**⚠️ Important: Update the Summary**
+After creating a bundle, **manually update** the `summary.md` file to capture:
+- Key accomplishments of the session
+- Specific technical changes made
+- Important decisions or findings
+- Relevant next steps
+
+The auto-generated summary is a template. For accurate session documentation,
+edit: `.claude/session/bundles/<bundle-id>/summary.md`
+
+## Alternative: Legacy snapshot (updates existing bundle)
+```bash
+python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/save_session_snapshot.py
+```
+
+- Updates an existing bundle with current active context only
+- Use `--bundle-id=<id>` to target a specific bundle
+
+## Flujo detallado (opcional)
+Si prefieres hacerlo paso a paso o necesitas crear un nuevo bundle antes de guardar:
+
+1. **Crear/actualizar bundle**  
+   Ejecuta cualquier comando del agente (p.ej. `/analizer T010`) para que el hook `subagent_stop` genere un bundle fresco.
+
+2. **Inspeccionar bundles disponibles**
+   ```bash
+   python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/session-manager.py list
+   ```
+
+3. **Copiar contexto activo al bundle deseado**
+   ```bash
+   python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/save_session_snapshot.py --bundle-id <bundle-id>
+   ```
+
+4. **(Opcional) Empaquetar para compartir**
+   ```bash
+   tar -czf /home/jaguilar/aaxis/rnd/repositories/.claude/session/bundles/<bundle-id>.tar.gz \
+     -C /home/jaguilar/aaxis/rnd/repositories/.claude/session/bundles/<bundle-id> .
+   ```
+
+## Notes
+- The exported tarball contains the bundle (metadata, transcript, artifacts).
+- Copying `session/active` preserves the live context (primers, json/md summaries).
+- You can restore later with:
+  ```bash
+  python3 .claude/session/scripts/session-manager.py import <path-to-bundle-tar>
+  ```
+- Keep exports outside of version control unless you intend to commit them.

package/commands/session-status.md

@@ -0,0 +1,61 @@
+---
+description: Check current session status and show recent session information
+---
+
+This command provides an intelligent overview of your current session state and recent work.
+
+## Quick status check
+```bash
+python3 /home/jaguilar/aaxis/rnd/repositories/.claude/session/scripts/session_startup_check.py
+```
+
+Shows:
+- 🎯 Most relevant recent session based on current work
+- 📚 Summary of other recent sessions (last 24 hours)
+- 💡 Smart suggestions for session restoration
+- 🔧 Available session management commands
+
+## What you'll see
+
+**Current context analysis:**
+- Working directory y feature activa (si se definió `SPECIFY_FEATURE`)
+- Recent commits and project activity
+- Relevance scoring for available sessions
+
+**Session recommendations:**
+- Bundles with high relevance to current work
+- Time-based suggestions (recent sessions)
+- Project context matching (similar technologies/tasks)
+
+**Available actions:**
+- Commands to restore specific sessions
+- Options to view session details
+- Links to session management tools
+
+## Intelligence features
+
+The status check analyzes your current work context and compares it with recent sessions to:
+
+- **Score relevance** based on project keywords, git activity, and timing
+- **Suggest restoration** when previous sessions are highly relevant
+- **Provide context** about what each session accomplished
+- **Show continuation paths** for ongoing work
+
+## Use cases
+
+**Starting a work session:**
+- Run `/session-status` to see if you should continue previous work
+- Get oriented about recent sessions and accomplishments
+- Decide whether to restore context or start fresh
+
+**During development:**
+- Check what sessions are available for reference
+- Find sessions related to current task
+- Get quick overview of recent work
+
+**Before switching contexts:**
+- Review current session state before saving
+- Check if similar work was done in recent sessions
+- Plan session organization and cleanup
+
+This replaces the need to manually browse session directories or remember what you were working on previously.

package/commands/speckit.add-task.md

@@ -0,0 +1,144 @@
+---
+
+**USAGE**: This command requires: `<speckit-root> <feature-name>`
+**Example**: `/speckit.add-task spec-kit-tcm-plan 004-feature-name`
+description: Add a single task to active feature's tasks.md with automatic enrichment. Use during implementation for ad-hoc tasks.
+---
+
+**USAGE**: This command requires: `<speckit-root> <feature-name>`
+**Example**: `/speckit.add-task spec-kit-tcm-plan 004-feature-name`
+
+The user input after `/speckit.add-task` MUST contain the high-level task intent (e.g., "Fix database connection pool leak"). Treat `$ARGUMENTS` below as that description and combine it with interactive prompts.
+
+User input:
+
+$ARGUMENTS
+
+## Overview
+Use this command to append or insert a **single** task in the currently active Spec-Kit feature (e.g., `specs/001-feature-name/tasks.md`). Every task must respect the phase ordering, ID sequencing, and formatting rules defined in `.claude/speckit/templates/tasks-template.md`.
+
+**When to use:**
+- Discovered new requirement during implementation
+- Hotfix or bug discovered mid-development
+- Plan changed and need to add unplanned tasks
+- Ad-hoc investigation or research task needed
+
+## Required Inputs (ask the user if any are missing)
+1. **Task ID** (e.g., `T024`): MUST be unique and sequential for its section. Confirm with the user before writing.
+2. **Phase**: One of the existing headers (e.g., `## Phase 3.1: Setup`). Ask where the task belongs.
+3. **Parallel marker**: Whether the task can run in parallel (`[P]`). Default to sequential if unsure.
+4. **Task description**: Clear action phrased as "Verb ..." and including file paths when applicable. Use the `/speckit.add-task` arguments as starting point and refine with the user.
+5. **Dependencies / notes** (optional): If the task introduces new dependencies, capture them in the `## Dependencies` or checklist section.
+
+## Procedure
+1. **Run prerequisite discovery** (repo root):
+   ```bash
+   .claude/speckit/scripts/check-prerequisites.sh --json --require-tasks --include-tasks
+   ```
+   Parse `FEATURE_DIR` and ensure `tasks.md` exists.
+
+2. **Load context**:
+   - Read `tasks.md` to understand current phases, ordering, and existing task IDs.
+   - Read `plan.md` and `.claude/speckit/governance.md` to keep the new task aligned with architectural and governance rules.
+
+3. **Gather missing details**:
+   - If the command arguments do not include the task ID, phase, or `[P]` marker, explicitly ask the user.
+   - Verify that the proposed ID is unused and fits the numeric ordering inside the chosen phase. If not, negotiate a new ID with the user.
+
+4. **Insert the task with inline metadata**:
+   - Add a markdown checklist line under the selected phase, keeping alphabetical order by ID.
+   - Format: `- [ ] T0XX [P] Description` (omit `[P]` when sequential).
+   - Include precise file paths or scripts where applicable.
+   - **IMMEDIATELY add metadata comments** using the enrichment rules:
+
+   **Enrichment Rules** (analyze task description):
+
+   | Keywords | Agent | Base Tier |
+   |----------|-------|-----------|
+   | terraform, terragrunt, .tf, infrastructure, vpc, gke | terraform-architect | T0/T2/T3 |
+   | kubectl, helm, flux, kubernetes, deployment, service | gitops-operator | T0/T2/T3 |
+   | gcloud, GCP, cloud logging, IAM | gcp-troubleshooter | T0 |
+   | docker, npm, build, test, CI, Dockerfile | devops-developer | T0-T1 |
+
+   **Security Tier**:
+   - T0: get, describe, show, list, logs, read
+   - T1: validate, lint, template, format
+   - T2: plan, dry-run, diff
+   - T3: apply, push, create, delete, deploy (⚠️ HIGH RISK)
+
+   **Tags**: Add ALL matching: #terraform #kubernetes #helm #docker #gcp #database #security #api #monitoring #setup #test #deploy #config #docs
+
+   **Priority**: ❓ (low) | ⚡ (medium) | 🔥 (high impact)
+
+   **Example**:
+   ```markdown
+   - [ ] T042 Configure CORS headers for API endpoints
+     <!-- 🤖 Agent: devops-developer | ✅ T1 | ⚡ 0.75 -->
+     <!-- 🏷️ Tags: #api #config #security -->
+     <!-- 🎯 skill: api_configuration (6.0) -->
+   ```
+
+   For T2/T3 tasks, add high-risk warning:
+   ```markdown
+   - [ ] T055 Apply Terraform VPC changes
+     <!-- 🤖 Agent: terraform-architect | 🚫 T3 | 🔥 0.95 -->
+     <!-- 🏷️ Tags: #terraform #infrastructure #networking -->
+     <!-- ⚠️ HIGH RISK: Analyze before execution -->
+     <!-- 💡 Suggested: /speckit.analyze-task T055 -->
+     <!-- 🎯 skill: terraform_infrastructure (12.0) -->
+   ```
+
+5. **Update supporting sections** (if required):
+   - `## Dependencies`: reflect any new blocking relationships.
+   - `## Validation Checklist` / Governance Compliance: add or adjust items to keep requirements accurate.
+
+6. **Validate task metadata**:
+   - Verify metadata comments are present and accurate
+   - Check agent assignment matches task type
+   - Confirm security tier is appropriate
+   - If T2/T3, ensure `⚠️ HIGH RISK` marker is present
+
+7. **Auto-analyze task** (Quality gate):
+   - After task is added and enriched, automatically execute `/speckit.analyze-task <Task-ID>`
+   - This validates the task before continuing implementation
+   - Display analysis output to user
+   - User reviews to ensure task is well-defined and properly placed
+
+8. **Report & next steps**:
+   - Run `git diff` to show the inserted task WITH inline metadata
+   - Summarize the new task details:
+     * Task ID and phase
+     * Description and file paths
+     * Suggested agent and tier
+     * High-risk status (if applicable)
+     * Dependencies added
+   - Mention that analysis was completed (step 7)
+   - If task is T2/T3, remind user it will trigger analysis again during `/speckit.implement`
+
+## Notes
+- Never guess the task ID: always confirm with the user
+- Avoid creating multiple tasks in one run; invoke `/speckit.add-task` per task
+- Metadata is added INLINE during task creation (step 4)
+- Honor security tiers: auto-detect T2/T3 operations from task keywords
+- If the user request conflicts with governance.md principles, surface the concern and seek clarification before writing
+
+## Example Usage
+```bash
+# During implementation, you discover a missing config:
+/speckit.add-task "Configure CORS headers for API endpoints"
+
+# System will:
+# 1. Ask for task ID (e.g., T042)
+# 2. Ask for phase (e.g., Integration)
+# 3. Ask if parallel (e.g., yes, different file)
+# 4. Insert task with inline metadata
+# 5. Auto-analyze task (quality gate)
+# 6. Show enriched result
+```
+
+## Inline Metadata Benefits
+- ✅ No post-processing step required
+- ✅ Consistent metadata format
+- ✅ Automatic agent routing
+- ✅ Security tier classification
+- ✅ High-risk detection for T2/T3

package/commands/speckit.analyze-task.md

@@ -0,0 +1,65 @@
+---
+
+**USAGE**: This command requires: `<speckit-root> <feature-name>`
+**Example**: `/speckit.analyze-task spec-kit-tcm-plan 004-feature-name`
+description: Deep-dive analysis of a specific task before execution. Auto-triggered for high-risk tasks (T2/T3).
+---
+
+**USAGE**: This command requires: `<speckit-root> <feature-name>`
+**Example**: `/speckit.analyze-task spec-kit-tcm-plan 004-feature-name`
+
+The text typed after `/speckit.analyze-task` is the task identifier or description you must inspect. Treat `$ARGUMENTS` literally as that input and reference it throughout the analysis.
+
+User input:
+
+$ARGUMENTS
+
+## Objective
+Provide a thorough explanation of **one** task without executing it. Clarify what must be done, why it matters, expected side-effects, and how to verify completion using read-only/dry-run steps.
+
+## Workflow
+1. **Locate the task**
+   - Find active feature in `specs/` directory
+   - Open the task list (`specs/<feature>/tasks.md`)
+   - If the user supplied a description instead of an ID, search the file and confirm the exact task with them before proceeding
+
+2. **Collect context**
+   - Record the phase, dependencies, `[P]` parallel marker, and any notes adjacent to the task entry
+   - Review the implementation plan (`plan.md`) and `.claude/speckit/governance.md` for constraints that apply to the task
+   - Inspect referenced artifacts (contracts/, data-model.md, quickstart.md) so the explanation is accurate
+
+3. **Extract routing metadata**
+   - Read the task's inline metadata comments to understand routing information
+   - Extract: agent assignment, security tier, tags, and confidence scores
+   - Example metadata format:
+     ```markdown
+     - [ ] T055 Apply Terraform VPC changes
+       <!-- 🤖 Agent: terraform-architect | 🚫 T3 | 🔥 0.95 -->
+       <!-- 🏷️ Tags: #terraform #infrastructure #networking -->
+     ```
+   - Use this metadata for consultation only. Do NOT execute the task
+
+4. **Produce the explanation**
+   Structure the response in four sections:
+   - **What it does** – plain-language summary of the task’s action and scope.
+   - **Why it matters** – link to plan/constitution requirements and note risks of skipping it.
+   - **Impact on system** – dependencies, affected services/repos, expected state after completion (call out T3 or manual approvals).
+   - **How to validate** – explicit read-only or dry-run commands someone can run to confirm success.
+
+## Rules
+- Never mark the task as completed or modify `tasks.md`.
+- Ask for clarification if multiple tasks match the input.
+- Highlight manual approvals or cross-team coordination when applicable.
+- Reference file paths and commands precisely; prefer absolute or repo-relative routes.
+
+## Example prompts
+```bash
+/speckit.analyze-task T011
+/speckit.analyze-task "Update ManagedCertificate for bot service"
+/speckit.analyze-task "Verify health-check BackendConfig"
+```
+
+**Note:** This command is automatically triggered when executing high-risk tasks (T2/T3) via `/speckit.implement`. You can also call it manually to analyze any task before execution.
+
+## Output expectations
+Deliver a concise, well-structured answer (sections or bullet points) so the user can immediately understand intent, impact, and verification steps without running the task.

package/commands/speckit.implement.md

@@ -0,0 +1,96 @@
+---
+description: Execute the implementation plan by processing and executing all tasks defined in tasks.md
+---
+
+The user input 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.implement 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:
+   ```
+   SPECKIT_ROOT = <speckit-root> (resolve to absolute if relative)
+   FEATURE_DIR = $SPECKIT_ROOT/specs/<feature-name>
+   TASKS = $FEATURE_DIR/tasks.md
+   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
+   ```
+3. Verify tasks.md exists (REQUIRED for this command). If not found, ERROR with instructions to run /speckit.tasks first.
+
+2. Load and analyze the implementation context:
+   - **REQUIRED**: Read tasks.md for the complete task list and execution plan
+   - **REQUIRED**: Read plan.md for tech stack, architecture, and file structure
+   - **IF EXISTS**: Read data-model.md for entities and relationships
+   - **IF EXISTS**: Read contracts/ for API specifications and test requirements
+   - **IF EXISTS**: Read research.md for technical decisions and constraints
+   - **IF EXISTS**: Read quickstart.md for integration scenarios
+
+3. Parse tasks.md structure and extract:
+   - **Task phases**: Setup, Tests, Core, Integration, Polish
+   - **Task dependencies**: Sequential vs parallel execution rules
+   - **Task details**: ID, description, file paths, parallel markers [P]
+   - **Execution flow**: Order and dependency requirements
+   - **High-risk markers**: Identify tasks with `<!-- ⚠️ HIGH RISK -->` markers
+
+4. **High-Risk Task Analysis** (Automatic Safety Check):
+   Before executing ANY task, check if it contains:
+   ```
+   <!-- ⚠️ HIGH RISK: Analyze before execution -->
+   <!-- 💡 Suggested: /speckit.analyze-task T### -->
+   ```
+
+   If found:
+   a. Automatically execute `/speckit.analyze-task T###` (do not skip this!)
+   b. Display the analysis output to user
+   c. Ask for confirmation: "This is a HIGH RISK task (T2/T3). Analysis complete. Proceed with execution? (y/n/skip)"
+   d. If user answers:
+      - "y" or "yes": Proceed with task execution
+      - "n" or "no": Skip task and mark as skipped in tasks.md
+      - "skip": Skip task without marking (can be retried later)
+
+   **IMPORTANT**: Never skip the analysis for high-risk tasks. User safety depends on this review.
+
+5. Execute implementation following the task plan:
+   - **Phase-by-phase execution**: Complete each phase before moving to the next
+   - **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together
+   - **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks
+   - **File-based coordination**: Tasks affecting the same files must run sequentially
+   - **Validation checkpoints**: Verify each phase completion before proceeding
+
+6. Implementation execution rules:
+   - **Setup first**: Initialize project structure, dependencies, configuration
+   - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios
+   - **Core development**: Implement models, services, CLI commands, endpoints
+   - **Integration work**: Database connections, middleware, logging, external services
+   - **Polish and validation**: Unit tests, performance optimization, documentation
+
+7. Progress tracking and error handling:
+   - Report progress after each completed task
+   - Halt execution if any non-parallel task fails
+   - For parallel tasks [P], continue with successful tasks, report failed ones
+   - Provide clear error messages with context for debugging
+   - Suggest next steps if implementation cannot proceed
+   - **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file.
+
+8. Completion validation:
+   - Verify all required tasks are completed
+   - Check that implemented features match the original specification
+   - Validate that tests pass and coverage meets requirements
+   - Confirm the implementation follows the technical plan
+   - Report final status with summary of completed work
+
+Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/tasks` first to regenerate the task list.