@3lineas/grooveskills 1.1.0 → 1.3.1

package/skills/odd-ai/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: odd-ai
+description: Organic & Outcome-Driven Development (ODD) protocol for AI agents: 7-step organic lifecycle, outcome hypotheses, and verifiable receipts.
+---
+
+# Organic & Outcome-Driven Development (ODD) for AI Agents
+
+A hybrid software engineering methodology tailored for AI coding assistants. It combines the lean adaptability of **Organic Driven Development** with the empirical rigor of **Outcome-Driven Development**, eliminating both aimless vibe coding and burdensome waterfall overhead.
+
+---
+
+## 1. The Core Philosophy
+
+| Dimension | The Output Trap (Anti-Pattern) | The Outcome Contract (ODD) |
+| :--- | :--- | :--- |
+| **Objective** | Produce diffs and close prompts quickly. | Satisfy a verifiable behavioral hypothesis. |
+| **Planning** | Either zero planning or bureaucratic waterfall. | Proportionate exploration before first write. |
+| **Verification** | Assumes green because the agent says so. | Empirical receipt: tests, typecheck, or runtime proof. |
+| **Memory** | Ephemeral chat context lost on restart. | Persistent records in `.grooveskills/memory/`. |
+
+---
+
+## 2. The 7-Step ODD Lifecycle
+
+```text
+[1. Authorize] -> [2. Explore] -> [3. Resolve] -> [4. Classify] -> [5. Track & Hypothesize] -> [6. Execute] -> [7. Verify Receipt]
+```
+
+### Step 1: Authorize (Permission Gate)
+- Evaluate whether the user's prompt explicitly authorizes code modification.
+- Inquiries, reviews, audits, or questions trigger **Lane 1 (Answer)**: remain strictly **read-only**.
+
+### Step 2: Explore Proportionately
+- Consult `.grooveskills/memory/context.md` for project architecture, conventions, and key commands.
+- Read only files relevant to the active scope; avoid full codebase traversals that waste tokens.
+
+### Step 3: Resolve Uncertainty Early
+- Disambiguate technical choices directly from codebase inspection.
+- Ask the user focused questions only when facing genuine product or architectural crossroads.
+
+### Step 4: Classify Semantic Scope
+- Classify tasks by semantic complexity and reversibility, never by superficial line counts:
+  - **Micro-Fix**: Focused 1-line or localized tweak; execute directly and verify.
+  - **Feature / Refactor (Lane 2 - Task)**: Requires state tracking in `.grooveskills/memory/tasks/<slug>.md`.
+  - **Architecture (Lane 3 - Spec)**: High ambiguity or cross-domain risk; draft spec and align before writing code.
+
+### Step 5: Track Before First Write & Outcome Hypothesis
+Before modifying source files for substantial tasks, record the **Outcome Hypothesis** in `.grooveskills/memory/tasks/<slug>.md`:
+> *"By [Output / Technical Change], [Outcome / Verifiable Behavior] will occur, proven by [Evidence / Test / Build Command]."*
+
+### Step 6: Execute Proportionate Clean Code
+- Apply strict typing (zero `any`), guard clauses (no nested `if`s), SRP, and file limit (<200 lines).
+- Avoid premature optimizations; implement exactly what the outcome demands.
+
+### Step 7: Verify Against Outcomes (Receipt of Evidence)
+- Run automated verification: typecheck, tests, linter, or build.
+- Record exact outputs under `## Evidence` in the task document.
+- Update `## Next` so work can be resumed seamlessly across agent turns.
+
+---
+
+## 3. Communication Standard
+- Maintain an empathetic, professional, and solution-driven tone.
+- When working in Spanish (`es`), use clear, courteous explanations and actionable guidance.

package/skills/odd-ai/references/odd-protocol-examples.md

@@ -0,0 +1,57 @@
+# ODD Protocol & Workflow Examples
+
+Concrete patterns and templates for applying Organic & Outcome-Driven Development (ODD) with AI coding agents.
+
+---
+
+## 1. Task Document Template (`.grooveskills/memory/tasks/<slug>.md`)
+
+```markdown
+---
+status: in-progress
+createdAt: 2026-11-01
+---
+
+# Feature: Strict Valibot Input Sanitization for Auth Route
+
+## Outcome Hypothesis
+By introducing a Valibot validation schema and an isolated Action in \`src/domains/auth/validate-login.ts\`, the authentication endpoint will reject malformed payloads with structured 400 errors and sanitize incoming email strings, proven by passing Vitest unit tests and a zero-error typecheck.
+
+## Scope
+- In scope:
+  - Valibot schema for \`loginSchema\` with trimmed, lowercased email.
+  - Unit tests covering empty payload, invalid format, and valid login.
+- Out of scope:
+  - Database token generation or session cookies.
+
+## Checklist
+- [x] Create \`src/domains/auth/login.schema.ts\` with Valibot schema
+- [x] Implement isolated action in \`src/domains/auth/validate-login-action.ts\`
+- [x] Add test suite in \`src/domains/auth/validate-login.test.ts\`
+
+## Evidence
+- Ran \`pnpm vitest run src/domains/auth/validate-login.test.ts\`: 3 passed (12ms)
+- Ran \`tsc --noEmit\`: Exit code 0 (0 errors)
+
+## Next
+- Wire \`validateLoginAction\` to the Hono route handler.
+```
+
+---
+
+## 2. Self-Healing Verification Loop (Step 7)
+
+When verification fails during Step 7, the agent enters an automatic self-correction loop:
+
+1. **Capture Exact Error**: Read compiler or test failure without guessing.
+2. **Isolate Root Cause**: Inspect the failing assertion or type mismatch.
+3. **Remediate Minimally**: Fix the implementation without changing test expectations unless the spec changed.
+4. **Re-Verify**: Re-run the verification command and log observed proof in `## Evidence`.
+
+---
+
+## 3. ADR Entry Example (`.grooveskills/memory/decisions.md`)
+
+```markdown
+| 2026-11-01 | Adopt ODD for AI Workflow | Standardize on 7-step ODD protocol | Balances organic iteration with empirical outcome verification across all agent sessions. |
+```

package/skills/python-clean/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: python-clean
+description: Modern Python clean code standards, uv environment management, Ruff linting/formatting, Pyright strict type checking, guard clauses (no nested ifs), Pydantic v2 boundaries, zero barrel files (__init__.py re-exports), and hard 200-line limit per file. TRIGGER when writing or modifying Python files (*.py), pyproject.toml, or designing Python services and APIs.
+---
+
+# Python Clean Code Standards (Python 3.12+ / uv / Ruff)
+
+Guidelines for writing safe, performant, and maintainable Python code with flat control flow, strict static typing, and decoupled domain architectures.
+
+---
+
+## 1. Golden Rules (Non-negotiable)
+
+1. **Zero Nested `if` Statements — Guard Clauses & Early Returns**:
+   - Never nest `if` conditions ("Pyramid of Doom").
+   - Validate preconditions, permissions, and edge cases at the top of the function and return or raise immediately.
+   - The primary happy path must remain flat and unindented.
+
+2. **Strict Static Typing Everywhere (Zero `Any`)**:
+   - Type all function parameters, return types, and class attributes.
+   - Use modern union syntax (`str | None`, never `Optional[str]` or `Union`).
+   - Use PEP 695 generics (`def first[T](items: list[T]) -> T | None:`).
+   - Use `typing.Protocol` for structural typing and dependency inversion instead of heavy abstract base classes.
+
+3. **Strict Boundaries with Pydantic v2**:
+   - Never pass loose dictionaries (`dict[str, Any]`) across application layers.
+   - Validate external inputs (APIs, CLI arguments, environment configs) using frozen Pydantic models (`ConfigDict(frozen=True)`).
+
+4. **Zero Barrel Files (`__init__.py` Re-exports)**:
+   - `__init__.py` files must remain empty or contain only module docstrings.
+   - Do not re-export functions or classes via `__all__` or `from .module import *`.
+   - Always use explicit, absolute imports from the project package root.
+
+5. **Single Responsibility & 200-Line Limit**:
+   - Every file must do exactly one thing. Isolate business actions into single-purpose modules (`app/actions/<domain>/<action>.py`).
+   - Strictly adhere to the <200 lines limit per file. Split helpers into atomic modules.
+
+6. **Friendly & Persuasive User Copy**:
+   - Error messages, validations, and logs intended for users must be empathetic, clear, and solution-focused.
+
+---
+
+## 2. Guard Clauses vs Nested Ifs
+
+```python
+# ❌ FORBIDDEN: Deeply nested if statements
+def activate_subscription(customer_id: str | None, plan: Plan | None) -> Invoice:
+    if customer_id is not None:
+        if plan is not None:
+            if plan.is_active:
+                return execute_activation(customer_id, plan)
+    raise ValueError("Invalid parameters")
+
+# ✅ CLEAN: Guard clauses with early returns and clear errors
+def activate_subscription(customer_id: str | None, plan: Plan | None) -> Invoice:
+    if customer_id is None or not customer_id.strip():
+        raise AppError(
+            message="El identificador de cliente es requerido para continuar.",
+            status_code=400,
+        )
+
+    if plan is None or not plan.is_active:
+        raise AppError(
+            message="El plan seleccionado no está disponible actualmente. ¿Deseas elegir otro?",
+            status_code=422,
+        )
+
+    return execute_activation(customer_id, plan)
+```
+
+---
+
+## 3. Atomic Action Blueprint
+
+```python
+from dataclasses import dataclass
+from app.domains.billing.models import Invoice, SubscriptionPlan
+from app.errors.app_error import AppError
+from app.types.response import ActionResponse
+
+@dataclass(frozen=True, slots=True)
+class ChargeSubscriptionInput:
+    customer_id: str
+    plan_id: str
+    amount_cents: int
+
+def charge_subscription_action(
+    input_data: ChargeSubscriptionInput,
+    payment_gateway: PaymentGatewayProtocol,
+) -> ActionResponse[Invoice]:
+    if not input_data.customer_id.strip():
+        raise AppError(
+            message="El cliente es requerido para procesar el pago.",
+            status_code=400,
+        )
+
+    if input_data.amount_cents <= 0:
+        raise AppError(
+            message="El monto de la suscripción debe ser superior a cero.",
+            status_code=422,
+        )
+
+    invoice = payment_gateway.charge(input_data.customer_id, input_data.amount_cents)
+    return ActionResponse(success=True, data=invoice)
+```
+
+---
+
+## 4. Sibling Skills & References
+
+- **`best-practices`**: Universal clean architecture rules.
+- **`ux-writing`**: Persuasive and courteous microcopy guidelines.
+- Tooling setup & Pydantic templates: `references/python-tooling-and-types.md`.

package/skills/python-clean/references/python-tooling-and-types.md

@@ -0,0 +1,78 @@
+# Python Tooling & Architecture Reference
+
+## 1. Modern Tooling Baseline (`pyproject.toml`)
+
+Modern Python projects standardize on **uv**, **Ruff**, and **Pyright**:
+
+```toml
+[project]
+name = "my-service"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = [
+    "pydantic>=2.7.0",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "F",   # pyflakes
+    "I",   # isort imports
+    "UP",  # pyupgrade modern syntax
+    "B",   # bugbear
+    "SIM", # simplify (detects nested ifs & unnecessary else)
+    "RET", # return early checks
+]
+
+[tool.pyright]
+typeCheckingMode = "strict"
+reportMissingTypeStubs = false
+pythonVersion = "3.12"
+```
+
+---
+
+## 2. Structured AppError & Response Pattern
+
+```python
+from dataclasses import dataclass
+
+class AppError(Exception):
+    def __init__(self, message: str, status_code: int = 400, code: str = "BAD_REQUEST") -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+
+@dataclass(frozen=True, slots=True)
+class ActionResponse[T]:
+    success: bool
+    data: T | None = None
+    error: str | None = None
+```
+
+---
+
+## 3. Directory Layout (No `__init__.py` Barrels)
+
+```text
+src/
+└── app/
+    ├── errors/
+    │   └── app_error.py
+    ├── actions/
+    │   └── billing/
+    │       ├── charge_subscription.py # One action per file (<100 lines)
+    │       └── cancel_subscription.py
+    ├── domains/
+    │   └── billing/
+    │       ├── models.py              # Pure frozen dataclasses
+    │       └── tax_calculator.py      # Pure function
+    └── infrastructure/
+        └── stripe/
+            └── client.py
+```

package/skills/rust-clean/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: rust-clean
+description: Modern Rust clean code standards, let-else guard clauses, no nested ifs/matches, explicit typed error handling with thiserror, Clippy strictness, zero unwrap in production, Newtype pattern, zero barrel files (mod.rs), and hard 200-line limit per file. TRIGGER when writing or modifying Rust files (*.rs), Cargo.toml, or designing Rust domain modules and traits.
+---
+
+# Rust Clean Code Standards (Rust 2024 / 1.80+)
+
+Engineering guidelines for writing idiomatic, highly performant, and maintainable Rust code with flat control flow, strict error boundaries, and zero runtime panics.
+
+---
+
+## 1. Golden Rules (Non-negotiable)
+
+1. **Zero Nested `if` / `match` — Guard Clauses with `let-else`**:
+   - Never nest `if let` or deep `match` pyramids.
+   - Use `let-else` statements at function entry points to bind irrefutable patterns and exit immediately via divergence (`return`, `break`).
+   - The primary happy path must always stay flat and left-aligned.
+
+2. **Zero `.unwrap()` or `.expect()` in Production Code**:
+   - Production logic must never panic on dynamic runtime data.
+   - Propagate errors explicitly with the `?` operator or handle `None`/`Err` via `let-else`.
+
+3. **Explicit Domain Errors with `thiserror`**:
+   - Model all domain and infrastructure failures as strongly typed enums derived with `thiserror::Error`.
+   - Distinguish technical context for logging (`tracing`) from courteous, solution-oriented error messages presented to end users.
+
+4. **Make Illegal States Unrepresentable (Newtypes & ADTs)**:
+   - Use the **Newtype pattern** (`pub struct UserId(pub String);`) to prevent passing arbitrary primitives interchangeably.
+   - Replace boolean flag combinations with algebraic state enums.
+
+5. **Zero Barrel Files (`mod.rs`) & Explicit Absolute Imports (`crate::...`)**:
+   - Do not use old-style `mod.rs` files filled with wildcard re-exports (`pub use something::*`).
+   - Use the modern file hierarchy (`domain.rs` and `domain/module.rs`).
+   - Always import symbols directly from `crate::...` path roots. Avoid deep relative paths (`super::super::`).
+
+6. **Isolated Actions & 200-Line Limit**:
+   - Isolate each business use case into its own atomic action file (`src/actions/<domain>/<action>.rs`).
+   - Keep all source files strictly under 200 lines. Split large modules into atomic domain helpers.
+
+7. **Zero Allocation Waste**:
+   - Prefer borrowed views (`&str`, `&[T]`) over cloning (`.clone()`) unless transfer of ownership is explicitly required.
+
+---
+
+## 2. Canonical Guard Clause Pattern (`let-else`)
+
+```rust
+// ❌ FORBIDDEN: Nested match / if-let pyramid
+pub fn process_order(order: Option<OrderInput>) -> Result<Order, AppError> {
+    if let Some(input) = order {
+        if input.is_valid() {
+            if input.items.len() > 0 {
+                return Ok(execute(input));
+            }
+        }
+    }
+    Err(AppError::bad_request("Invalid order payload"))
+}
+
+// ✅ CLEAN: Flat guard clauses with let-else
+pub fn process_order(order: Option<OrderInput>) -> Result<Order, AppError> {
+    let Some(input) = order else {
+        return Err(AppError::validation(
+            "Por favor, ingresa los datos de tu orden para continuar.",
+        ));
+    };
+
+    if !input.is_valid() || input.items.is_empty() {
+        return Err(AppError::validation(
+            "Tu orden debe contener al menos un producto válido.",
+        ));
+    }
+
+    Ok(execute(input))
+}
+```
+
+---
+
+## 3. Atomic Action Blueprint
+
+```rust
+use crate::domains::billing::models::{Customer, Invoice};
+use crate::errors::AppError;
+
+pub struct ChargeSubscriptionInput {
+    pub customer_id: String,
+    pub plan_id: String,
+    pub amount_cents: u64,
+}
+
+pub fn charge_subscription_action(
+    input: &ChargeSubscriptionInput,
+    payment_client: &impl PaymentGateway,
+) -> Result<Invoice, AppError> {
+    if input.customer_id.trim().is_empty() {
+        return Err(AppError::validation(
+            "El identificador de cliente es obligatorio.",
+        ));
+    }
+
+    if input.amount_cents == 0 {
+        return Err(AppError::validation(
+            "El monto de suscripción debe ser superior a cero.",
+        ));
+    }
+
+    let receipt = payment_client.process_charge(&input.customer_id, input.amount_cents)?;
+    Ok(Invoice::from_receipt(receipt))
+}
+```
+
+---
+
+## 4. Sibling Skills & References
+
+- **`best-practices`**: Universal clean code principles.
+- **`ux-writing`**: Guidelines for friendly, persuasive user copy.
+- Detailed config and error templates: `references/rust-error-and-clippy.md`.

package/skills/rust-clean/references/rust-error-and-clippy.md

@@ -0,0 +1,92 @@
+# Rust Error Handling & Clippy Reference
+
+## 1. Domain Error Pattern with `thiserror`
+
+```rust
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum AppError {
+    #[error("Validación: {message}")]
+    Validation { message: String },
+
+    #[error("No encontrado: {resource} con id {id}")]
+    NotFound { resource: &'static str, id: String },
+
+    #[error("Error de pasarela de pago: {0}")]
+    PaymentGateway(String),
+
+    #[error("Error de base de datos")]
+    Database(#[from] sqlx::Error),
+}
+
+impl AppError {
+    pub fn validation(msg: impl Into<String>) -> Self {
+        Self::Validation { message: msg.into() }
+    }
+
+    pub fn not_found(resource: &'static str, id: impl Into<String>) -> Self {
+        Self::NotFound { resource, id: id.into() }
+    }
+
+    /// User-friendly message for UI responses
+    pub fn user_message(&self) -> String {
+        match self {
+            Self::Validation { message } => message.clone(),
+            Self::NotFound { resource, .. } => {
+                format!("No pudimos encontrar el recurso solicitado ({resource}).")
+            }
+            Self::PaymentGateway(_) => {
+                "Hubo un inconveniente al procesar tu pago. Por favor, verifica tus datos.".into()
+            }
+            Self::Database(_) => {
+                "Ocurrió un error inesperado al guardar la información. Intenta de nuevo en unos momentos.".into()
+            }
+        }
+    }
+}
+```
+
+---
+
+## 2. Clippy & Linter Baseline (`Cargo.toml`)
+
+Modern Rust codebases configure compiler warnings and Clippy directly in `Cargo.toml`:
+
+```toml
+[lints.rust]
+unsafe_code = "deny"
+missing_debug_implementations = "warn"
+
+[lints.clippy]
+all = "warn"
+pedantic = "warn"
+unwrap_used = "deny"
+expect_used = "warn"
+panic = "deny"
+manual_let_else = "warn"
+needless_pass_by_value = "warn"
+```
+
+---
+
+## 3. Directory Layout (No `mod.rs` Barrels)
+
+```text
+src/
+├── main.rs (or lib.rs)
+├── errors.rs                     # AppError definition
+├── actions/
+│   ├── billing/
+│   │   ├── charge_subscription.rs # One action per file
+│   │   └── cancel_subscription.rs
+│   └── billing.rs                # Module entry (no mod.rs)
+├── domains/
+│   ├── billing/
+│   │   └── models.rs             # Invoices, plans, pure structs
+│   └── billing.rs
+└── infrastructure/
+    ├── stripe/
+    │   └── client.rs
+    └── stripe.rs
+```

package/skills/testing-vitest/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: testing-vitest
+description: Clean, deterministic unit and integration testing with Vitest. Enforces Arrange-Act-Assert (AAA), behavioral testing over implementation details, in-memory fakes over brittle mocks, strict assertions, and boundary/edge case test matrices. TRIGGER when writing, maintaining, or fixing automated tests (*.test.ts, *.spec.ts), test utilities, or testing infrastructure with Vitest.
+---
+
+# Vitest Testing Standards
+
+Guidelines for authoring reliable, fast, and maintainable unit and integration tests with **Vitest**.
+
+---
+
+## 1. Golden Rules (Non-negotiable)
+
+1. **Test Behavior, Not Implementation Details**:
+   - Assert on observable inputs, outputs, side-effects, and state changes.
+   - Do not test private methods, internal variable states, or intermediate execution order.
+
+2. **Strict Arrange-Act-Assert (AAA) Structure**:
+   - Organize every test clearly into three visually distinct blocks:
+     - `// Arrange`: Set up inputs, state, and dependencies.
+     - `// Act`: Execute the unit under test.
+     - `// Assert`: Verify outputs and invariants.
+
+3. **In-Memory Fakes Over Brittle Mocks**:
+   - Prefer in-memory fakes (e.g., `FakeUserRepository`, `MemoryStorage`) over deeply nested `vi.spyOn()` or mock chains.
+   - Only mock external boundaries (network HTTP calls, system clocks, third-party APIs).
+
+4. **Deterministic & Isolated (Zero Shared Mutable State)**:
+   - Each test must run independently in any order without relying on state from preceding tests.
+   - Use `beforeEach` strictly to reset test fixtures.
+
+5. **Exhaustive Edge Cases & Failure Modes**:
+   - Always test boundary values: empty strings, zero, negative numbers, missing optional fields, expired tokens, and rejected promises.
+   - Never write happy-path-only tests.
+
+6. **Clear, Intention-Revealing Test Names**:
+   - Use descriptive sentences: `it("should calculate tax accurately when order total exceeds threshold")`.
+   - Avoid vague names like `it("works")` or `it("test 1")`.
+
+---
+
+## 2. Standard Test Pattern (AAA)
+
+```ts
+import { describe, it, expect } from "vitest";
+import { calculateDiscount } from "./calculate-discount";
+
+describe("calculateDiscount", () => {
+  it("should apply 15% discount when user is a premium member", () => {
+    // Arrange
+    const originalPrice = 100;
+    const isPremium = true;
+
+    // Act
+    const finalPrice = calculateDiscount(originalPrice, isPremium);
+
+    // Assert
+    expect(finalPrice).toBe(85);
+  });
+
+  it("should return unchanged price when discount percentage is zero", () => {
+    // Arrange & Act
+    const finalPrice = calculateDiscount(50, false);
+
+    // Assert
+    expect(finalPrice).toBe(50);
+  });
+
+  it("should throw an AppError when input price is negative", () => {
+    // Arrange, Act & Assert
+    expect(() => calculateDiscount(-10, true)).toThrowError(/Price must be non-negative/);
+  });
+});
+```
+
+---
+
+## 3. Mocking External Boundaries Safely
+
+```ts
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { fetchExchangeRate } from "./fetch-exchange-rate";
+
+describe("fetchExchangeRate", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("should parse rate safely when API returns 200", async () => {
+    const fakeFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ rate: 1.08 }),
+    });
+    vi.stubGlobal("fetch", fakeFetch);
+
+    const rate = await fetchExchangeRate("EUR", "USD");
+
+    expect(rate).toBe(1.08);
+    expect(fakeFetch).toHaveBeenCalledWith(expect.stringContaining("EUR/USD"));
+  });
+});
+```
+
+---
+
+## 4. Sibling Skills
+
+- **`best-practices`**: Universal clean code rules.
+- **`error-handling-logging`**: Testing expected `AppError` throws and error payloads.