@3lineas/grooveskills 1.5.0 → 1.7.0

package/skills/docs-standards/references/adr-template-and-lifecycle.md

@@ -0,0 +1,111 @@
+# Architecture Decision Records (ADR) Lifecycle and Template
+
+Authoritative specification for creating, managing, and deprecating Architecture Decision Records.
+
+---
+
+## 1. What is an ADR?
+
+An Architecture Decision Record (ADR) captures an important architectural or technical choice made on a project along with its context and consequences.
+
+Key attributes of effective ADRs:
+- **Immutable historical record**: Once accepted, an ADR is not revised to say something different. If the decision changes, a new ADR supersedes it.
+- **Context-focused**: Explains *why* options were selected and what trade-offs were accepted.
+- **English-only**: Standardized in English across all engineering teams.
+
+---
+
+## 2. ADR Lifecycle States
+
+```mermaid
+flowchart LR
+  Proposed["1. Proposed"] --> Accepted["2. Accepted"]
+  Proposed --> Rejected["Rejected"]
+  Accepted --> Superseded["3. Superseded"]
+  Accepted --> Deprecated["Deprecated"]
+```
+
+1. **Proposed**: Under RFC or active peer discussion. Implementation has not started.
+2. **Accepted**: Approved by technical leads/team. Implementation adheres to this decision.
+3. **Rejected**: Decision evaluated and abandoned. Preserved to prevent re-hashing settled debates.
+4. **Superseded**: Replaced by a newer ADR (e.g., "Superseded by ADR-0012").
+5. **Deprecated**: The feature or architectural pattern has been retired completely.
+
+---
+
+## 3. Storage Formats
+
+Projects may choose either a **Unified Log** (ideal for smaller or harness-managed repos) or **Modular Files** (ideal for enterprise systems).
+
+### Option A: Unified Log (`decisions.md`)
+Maintained under `.grooveskills/memory/decisions.md` or `docs/decisions.md`:
+
+```markdown
+# Architecture Decision Records (ADR)
+
+| Date | Title | Decision | Reason & Consequences |
+| :--- | :--- | :--- | :--- |
+| 2026-11-01 | Adopt Harness | Initialized `.grooveskills/` | Standardized agent memory and 3-lane execution |
+| 2026-11-03 | Fail-Fast Env Validation | Adopted Valibot at boot time | Catches missing env vars before startup; slight schema build overhead |
+```
+
+### Option B: Modular Numbered Records (`docs/architecture/adr/XXXX-title.md`)
+Numbered sequentially with zero-padded prefixes:
+- `0001-use-hono-over-express.md`
+- `0002-cache-aside-with-redis.md`
+
+---
+
+## 4. Canonical ADR Template (Markdown)
+
+Use the following template when authoring dedicated ADR files:
+
+```markdown
+# ADR-0004: Decouple External Providers via Pure Domain Ports
+
+- **Status**: Accepted
+- **Date**: 2026-11-03
+- **Deciders**: Engineering Team
+- **Consulted**: Tech Leads, Security Team
+- **Supersedes**: ADR-0001 (Direct Vendor SDK Calls)
+
+## Context and Problem Statement
+Our application previously instantiated third-party SDKs (Stripe, Resend) directly inside HTTP controllers and actions. This created tight coupling, prevented automated unit testing with in-memory fakes, and made switching cloud providers painful.
+
+## Decision Drivers
+- Need for deterministic unit testing without network mocks or live API keys.
+- Need to isolate credential management into dedicated infrastructure wrappers.
+- Need to support swapping email providers (Resend -> AWS SES) with zero changes to business logic.
+
+## Considered Options
+1. **Direct SDK usage** (Status quo) - Minimal initial boilerplate, but fragile and untestable.
+2. **Repository pattern for all APIs** - Misleading abstraction for non-database operations.
+3. **Domain Ports & Swappable Adapters** (Chosen) - Actions depend on pure interfaces.
+
+## Decision Outcome
+Chosen Option: **Domain Ports & Swappable Adapters**. We define pure domain interfaces (e.g. `PaymentGatewayPort`) under `src/domains/<domain>/` and concrete implementations under `src/infrastructure/adapters/`.
+
+### Positive Consequences
+- Business actions remain 100% pure and independent of vendor libraries.
+- Unit tests use fast `MemoryPaymentGatewayAdapter` executing in milliseconds.
+- Provider changes require writing only one new adapter file.
+
+### Negative Consequences / Trade-offs
+- Requires writing an explicit port interface and DTO mapping per external provider.
+- Increases the number of files by one port and one wrapper per integration.
+
+## Links & References
+- Relative spec link: [Architecture Overview](../system-design.md)
+- Domain Ports Guide: [External Service Adapters Guide](../../guides/adapters.md)
+```
+
+---
+
+## 5. Review & Authoring Checklist
+
+Before submitting an ADR:
+- [ ] Is it written in clear, concise English?
+- [ ] Does it reference relevant documents using relative POSIX paths?
+- [ ] Are trade-offs (negative consequences) explicitly stated, not hidden?
+- [ ] Is the status clearly marked?
+- [ ] Does the file stay well under the 200-line limit?

package/skills/docs-standards/references/code-comments-and-docstrings.md

@@ -0,0 +1,147 @@
+# In-Code Comments and Docstrings Standard
+
+Guidelines for writing intent-focused, maintainable code comments and docstrings in TypeScript, Python, and Rust.
+
+---
+
+## 1. Golden Philosophy: Document the "Why", Not the "What"
+
+Comments must justify non-obvious engineering decisions, document invariants, and highlight failure modes. They must never repeat what the code already says.
+
+### Anti-Patterns to Avoid
+
+```ts
+// ❌ WRONG: Useless repetition of obvious code
+// Increment counter by one
+counter += 1;
+
+// ❌ WRONG: Commented-out dead code (delete it; git keeps history)
+// const oldRate = fetchV1Rate(currency);
+// return oldRate * 1.05;
+
+// ❌ WRONG: Speculative "maybe one day" comments
+// TODO: Maybe we can convert this to a microservice in 2028 if needed
+```
+
+### Clean Patterns to Adopt
+
+```ts
+// ✅ CORRECT: Explains the underlying constraint / rationale
+// Stripe requires idempotency keys to expire within 24 hours. We pin the key
+// to the daily order UUID to avoid duplicate authorization calls on network retry.
+const idempotencyKey = `ord_${order.id}_${txDate}`;
+
+// ✅ CORRECT: Documents intentional performance trade-off
+// Using a bitmask instead of Set<string> here because this validation executes
+// inside the hot per-packet loop processing ~100k records/second.
+const permissionsMask = roleFlags & REQUIRED_FLAGS;
+```
+
+---
+
+## 2. TypeScript / JavaScript (TSDoc & JSDoc)
+
+Use standard TSDoc for public module APIs, interfaces, and actions. Keep types inside TypeScript; do not duplicate type annotations inside docstrings.
+
+```ts
+export interface CacheRememberOptions {
+  ttlSeconds: number;
+  tags?: string[];
+}
+
+/**
+ * Executes the fallback fetcher and caches the result when a cache miss occurs.
+ *
+ * Employs a single-flight mutex per key to prevent thundering-herd cache stampedes
+ * when multiple concurrent requests query an expired key simultaneously.
+ *
+ * @param key - Unique cache partition key.
+ * @param ttlSeconds - Cache TTL in seconds.
+ * @param fetcher - Asynchronous producer function executed on miss.
+ * @returns The cached or freshly computed value.
+ * @throws {AppError} If fetcher throws or cache connection drops.
+ */
+export async function remember<T>(
+  key: string,
+  ttlSeconds: number,
+  fetcher: () => Promise<T>
+): Promise<T> {
+  // Implementation...
+}
+```
+
+---
+
+## 3. Python (PEP 257 & Google Style)
+
+Use triple-quoted strings for modules, classes, and functions. Document exceptions raised and edge-case behavior.
+
+```python
+"""Rate limiting domain service with sliding-window support."""
+
+from typing import Protocol
+
+
+class RateLimiterPort(Protocol):
+    """Domain contract for rate limiting adapters."""
+
+    def is_allowed(self, client_id: str, limit: int, window_sec: int) -> bool:
+        """Evaluate if the client request stays within the sliding window limit.
+
+        Uses a Redis Sorted Set under the hood to ensure atomic score increments.
+        Fails open (returns True) if the Redis node is unreachable to prevent
+        taking down downstream checkout APIs during cache outages.
+
+        Args:
+            client_id: Unique IP, API token, or user account identifier.
+            limit: Maximum requests allowed in the sliding window.
+            window_sec: Window duration in seconds.
+
+        Returns:
+            True if the call is allowed, False if limit is exceeded.
+        """
+        ...
+```
+
+---
+
+## 4. Rust (Rustdoc: `///` and `//!`)
+
+Use `//!` for module-level documentation and `///` for structs, enums, and functions. Include doc tests or failure conditions.
+
+```rust
+//! Cryptographic HMAC webhook signature verifier.
+//!
+//! Provides zero-allocation constant-time verification for incoming
+//! payment webhooks.
+
+use subtle::ConstantTimeEq;
+
+/// Verifies whether an incoming payload matches the expected HMAC-SHA256 signature.
+///
+/// Compares signatures using constant-time comparison to protect against
+/// timing attacks on the cryptographic hash digest.
+///
+/// # Errors
+///
+/// Returns `Err(WebhookError::InvalidSignature)` if the digest lengths
+/// mismatch or if the signature does not authenticate the payload.
+pub fn verify_signature(
+    secret: &[u8],
+    payload: &[u8],
+    expected_hex_sig: &str,
+) -> Result<(), WebhookError> {
+    // Implementation...
+}
+```
+
+---
+
+## 5. Commenting Checklist
+
+Before committing code:
+- [ ] Are all comments and docstrings written in English?
+- [ ] Are all commented-out dead code blocks deleted?
+- [ ] Do comments answer "Why was it built this way?" rather than "What does this line do?"?
+- [ ] For public functions: are edge cases, thrown exceptions, or fallbacks documented?
+- [ ] Does the file stay under 200 lines?

package/skills/docs-standards/references/relative-paths-and-diagrams.md

@@ -0,0 +1,123 @@
+# Relative Paths and Mermaid Diagrams Standard
+
+Reference guide for constructing portable markdown links and bulletproof Mermaid diagrams.
+
+---
+
+## 1. Relative POSIX Links
+
+Documentation must remain navigable across GitHub/GitLab web view, local IDEs, CLI tools, and static site generators without relying on machine-specific absolute paths.
+
+### 1.1 Strict Rules
+
+1. **Always Relative**:
+   - ✅ Correct: `[Architecture Overview](../architecture/overview.md)`
+   - ❌ Wrong: `[Architecture Overview](/Users/alice/projects/app/docs/architecture/overview.md)`
+   - ❌ Wrong: `[Architecture Overview](file:///C:/projects/app/docs/architecture/overview.md)`
+2. **POSIX Forward Slashes Only**:
+   - Always use `/` even in Windows environments (`./guides/setup.md`, never `.\guides\setup.md`).
+3. **Explicit Dot Notation**:
+   - Siblings or subfolders: prefix with `./` (e.g., `./references/diagrams.md`).
+   - Parents: prefix with `../` (e.g., `../../README.md`).
+4. **Anchor Links**:
+   - Match GitHub header slug generation: lowercase, hyphen-separated, strip special symbols.
+   - Example: `[Jump to Section](#3-mermaid-syntax-safety)`.
+
+### 1.2 Path Resolution Reference
+
+Given this file layout:
+```text
+repo/
+├── README.md
+├── docs/
+│   ├── overview.md
+│   └── architecture/
+│       ├── system-design.md
+│       └── adr/
+│           └── 0001-queue.md
+└── src/
+    └── index.ts
+```
+
+| Source File | Destination File | Correct Markdown Link |
+| :--- | :--- | :--- |
+| `README.md` | `docs/overview.md` | `[Overview](./docs/overview.md)` |
+| `docs/overview.md` | `docs/architecture/system-design.md` | `[System Design](./architecture/system-design.md)` |
+| `docs/architecture/adr/0001-queue.md` | `docs/architecture/system-design.md` | `[System Design](../system-design.md)` |
+| `docs/architecture/adr/0001-queue.md` | `README.md` | `[Root README](../../../README.md)` |
+
+---
+
+## 2. Mermaid Diagram Construction
+
+Mermaid diagrams render directly in GitHub and modern editors. Invalid syntax breaks the entire document view. Follow these guidelines to ensure resilient diagrams.
+
+### 2.1 Direction and Layout
+- Prefer `flowchart TD` (Top-to-Bottom) for hierarchical workflows or pipelines.
+- Prefer `flowchart LR` (Left-to-Right) for message busses, data processing streams, or step sequences.
+
+### 2.2 Node Names and Safe Quoting
+Mermaid syntax uses special characters like `(`, `[`, `{`, `<`, `>`, `"`, and `:` for shape definitions. Placing these inside unquoted labels triggers parsing failures.
+
+**The Golden Rule**: Always wrap the label string in double quotes `["..."]`.
+
+```mermaid
+flowchart TD
+  %% ✅ CORRECT: All node texts and edge labels safely quoted
+  Client["Client Application (Web / Mobile)"]
+  Gateway["API Gateway: Port 8080"]
+  Queue[("Cloudflare Queue: events-stream")]
+  Worker["Queue Worker: SyncProcessor"]
+
+  Client -->|"POST /v1/events"| Gateway
+  Gateway -->|"Publish message"| Queue
+  Queue -->|"Batch consume"| Worker
+```
+
+### 2.3 Subgraphs with Safe Identifiers
+Always give subgraphs explicit alphanumeric identifiers before their quoted titles:
+
+```mermaid
+flowchart LR
+  subgraph IngestionBoundary["Ingestion Domain"]
+    IngestController["IngestController"]
+    VerifyHmac["VerifyHmacAction"]
+    IngestController --> VerifyHmac
+  end
+
+  subgraph ProcessingBoundary["Async Processing Domain"]
+    WorkerJob["ProcessJobWorker"]
+    DbStore[("PostgreSQL Store")]
+    WorkerJob -->|"Write audit"| DbStore
+  end
+
+  VerifyHmac -->|"Enqueue task"| WorkerJob
+```
+
+### 2.4 Sequence Diagrams
+For sequence flows, quote participants with descriptive names:
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor User as "Client App"
+  participant API as "API Controller"
+  participant Policy as "RBAC Policy Engine"
+  participant DB as "Database Cluster"
+
+  User->>+API: POST /organizations/42/members
+  API->>+Policy: canManageOrg(actor, orgId)
+  Policy-->>-API: Allowed (true)
+  API->>+DB: INSERT INTO org_members ...
+  DB-->>-API: Result(201 Created)
+  API-->>-User: 201 Created (MemberDTO)
+```
+
+### 2.5 Common Pitfalls & Anti-Patterns
+1. **Unquoted brackets inside shapes**:
+   - ❌ Broken: `A[User [Admin]]`
+   - ✅ Correct: `A["User [Admin]"]`
+2. **Missing line breaks**:
+   - Keep node declarations on separate lines for readability.
+3. **Overly dense diagrams**:
+   - If a diagram exceeds 20 nodes, break it down into modular sub-flowcharts across topic guides.

package/skills/env-feature-flags/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: env-feature-flags
+description: Architectural standards for fail-fast environment validation with Valibot and decoupled Feature Flags wrappers with swappable adapters (PostHog, LaunchDarkly, Unleash, In-Memory). Guarantees that applications crash at boot time on invalid config and allows toggling features without coupling code to vendor SDKs. TRIGGER when reading environment variables, structuring process.env, configuring feature flags, or running A/B experiments.
+---
+
+# Fail-Fast Environment Validation & Feature Flags Adapters
+
+Opinionated architectural standard combining **Fail-Fast Environment Schema Validation** (using Valibot) and **Feature Flags Adapters** (PostHog, LaunchDarkly, In-Memory).
+
+---
+
+## 1. Architectural Invariants
+
+1. **Fail-Fast at Startup**:
+   - Environment variables must be validated on application boot. If a required secret or URL is missing or malformed, the process exits immediately with a clean diagnostic message.
+   - Raw `process.env` is NEVER accessed directly inside business actions or controllers. All code imports the strongly typed `env` singleton.
+2. **Feature Flags as a Domain Port**:
+   - Business actions evaluate feature availability through `FeatureFlagPort`.
+   - Vendor SDKs (PostHog, LaunchDarkly, Unleash) remain isolated inside infrastructure adapters.
+
+---
+
+## 2. Directory Layout
+
+```text
+src/
+├── config/
+│   └── env.ts                              # Fail-fast Valibot environment parser (<70 lines)
+├── domains/
+│   └── feature-flags/
+│       ├── feature-flag.port.ts            # Domain interface for flags (<40 lines)
+│       └── flag-keys.ts                    # Strongly typed flag registry (<30 lines)
+└── infrastructure/
+    └── adapters/
+        └── feature-flags/
+            ├── posthog-flags.adapter.ts    # PostHog implementation (<70 lines)
+            ├── launchdarkly-flags.adapter.ts # LaunchDarkly implementation (<70 lines)
+            └── memory-flags.adapter.ts     # In-memory testing flags fake (<50 lines)
+```
+
+---
+
+## 3. Fail-Fast Environment Config (`src/config/env.ts`)
+
+```ts
+import * as v from "valibot";
+
+const EnvSchema = v.object({
+  NODE_ENV: v.fallback(v.picklist(["development", "production", "test"]), "development"),
+  PORT: v.fallback(v.pipe(v.string(), v.transform(Number)), 3000),
+  DATABASE_URL: v.pipe(v.string(), v.url("DATABASE_URL debe ser una URL válida.")),
+  API_SECRET_KEY: v.pipe(v.string(), v.minLength(32, "API_SECRET_KEY requiere al menos 32 caracteres.")),
+});
+
+function loadEnv() {
+  const result = v.safeParse(EnvSchema, process.env);
+  if (!result.success) {
+    console.error("❌ Error fatal en variables de entorno:");
+    for (const issue of result.issues) {
+      console.error(`  - ${issue.path?.[0]?.key}: ${issue.message}`);
+    }
+    process.exit(1);
+  }
+  return result.output;
+}
+
+export const env = loadEnv();
+```
+
+---
+
+## 4. Feature Flag Port (`src/domains/feature-flags/feature-flag.port.ts`)
+
+```ts
+export type FeatureFlagKey = "new-checkout-flow" | "ai-copilot" | "export-pdf";
+
+export interface FeatureFlagEvaluationContext {
+  distinctId: string;
+  organizationId?: string;
+  properties?: Record<string, unknown>;
+}
+
+export interface FeatureFlagPort {
+  isEnabled(key: FeatureFlagKey, context?: FeatureFlagEvaluationContext): Promise<boolean>;
+  getVariant<T = string>(key: FeatureFlagKey, context?: FeatureFlagEvaluationContext): Promise<T | null>;
+}
+```
+
+---
+
+## 5. Detailed Adapters Reference
+
+For real implementations of PostHog, LaunchDarkly, and In-Memory Feature Flag adapters, see:
+- `references/env-feature-flags-examples.md`

package/skills/env-feature-flags/references/env-feature-flags-examples.md

@@ -0,0 +1,93 @@
+# Implementation Reference: Env & Feature Flag Adapters
+
+Production implementations of PostHog, LaunchDarkly, and In-Memory testing feature flag adapters.
+
+---
+
+## 1. PostHog Feature Flags Adapter (`posthog-node`)
+
+```ts
+// src/infrastructure/adapters/feature-flags/posthog-flags.adapter.ts
+import { PostHog } from "posthog-node";
+import type { FeatureFlagPort, FeatureFlagKey, FeatureFlagEvaluationContext } from "@/domains/feature-flags/feature-flag.port";
+
+export class PostHogFeatureFlagAdapter implements FeatureFlagPort {
+  constructor(private client: PostHog) {}
+
+  async isEnabled(key: FeatureFlagKey, context?: FeatureFlagEvaluationContext): Promise<boolean> {
+    const distinctId = context?.distinctId ?? "anonymous";
+    const res = await this.client.isFeatureEnabled(key, distinctId, {
+      personProperties: context?.properties,
+    });
+    return Boolean(res);
+  }
+
+  async getVariant<T = string>(key: FeatureFlagKey, context?: FeatureFlagEvaluationContext): Promise<T | null> {
+    const distinctId = context?.distinctId ?? "anonymous";
+    const variant = await this.client.getFeatureFlag(key, distinctId, {
+      personProperties: context?.properties,
+    });
+    return (variant as T) ?? null;
+  }
+}
+```
+
+---
+
+## 2. LaunchDarkly Feature Flags Adapter (`@launchdarkly/node-server-sdk`)
+
+```ts
+// src/infrastructure/adapters/feature-flags/launchdarkly-flags.adapter.ts
+import type { LDClient } from "@launchdarkly/node-server-sdk";
+import type { FeatureFlagPort, FeatureFlagKey, FeatureFlagEvaluationContext } from "@/domains/feature-flags/feature-flag.port";
+
+export class LaunchDarklyFeatureFlagAdapter implements FeatureFlagPort {
+  constructor(private client: LDClient) {}
+
+  async isEnabled(key: FeatureFlagKey, context?: FeatureFlagEvaluationContext): Promise<boolean> {
+    const user = {
+      key: context?.distinctId ?? "anonymous",
+      custom: { organizationId: context?.organizationId, ...context?.properties },
+    };
+    return this.client.variation(key, user, false);
+  }
+
+  async getVariant<T = string>(key: FeatureFlagKey, context?: FeatureFlagEvaluationContext): Promise<T | null> {
+    const user = {
+      key: context?.distinctId ?? "anonymous",
+      custom: { organizationId: context?.organizationId, ...context?.properties },
+    };
+    return this.client.variation(key, user, null);
+  }
+}
+```
+
+---
+
+## 3. In-Memory Testing Flags Adapter
+
+```ts
+// src/infrastructure/adapters/feature-flags/memory-flags.adapter.ts
+import type { FeatureFlagPort, FeatureFlagKey } from "@/domains/feature-flags/feature-flag.port";
+
+export class MemoryFeatureFlagAdapter implements FeatureFlagPort {
+  private flags = new Map<string, boolean>();
+  private variants = new Map<string, unknown>();
+
+  setFlag(key: FeatureFlagKey, enabled: boolean): void {
+    this.flags.set(key, enabled);
+  }
+
+  setVariant(key: FeatureFlagKey, variant: unknown): void {
+    this.variants.set(key, variant);
+  }
+
+  async isEnabled(key: FeatureFlagKey): Promise<boolean> {
+    return this.flags.get(key) ?? false;
+  }
+
+  async getVariant<T = string>(key: FeatureFlagKey): Promise<T | null> {
+    return (this.variants.get(key) as T) ?? null;
+  }
+}
+```