Ignaciobrenas · Nov 14, 2026 · Nov 14, 2026
@@ -0,0 +1,19 @@
+---
+name: commitflow-canvas-dag
+description: Guía técnica para diseñar y optimizar el motor topológico del DAG, renderizado de splines Bézier, virtual scrolling (< 150 nodos DOM), minimapa de ramas, drag-and-drop y Web Workers / OffscreenCanvas en CommitFlow.
+---
+
+# CommitFlow DAG & Virtual Scroll Skill
+
+Cuando trabajes en `src/graph/graphLayout.ts`, `src/graph/dagWorkerClient.ts` o el renderizado del grafo en `src/webview/main.ts`:
+1. **Presupuesto de DOM y Rendimiento:**
+   - El scroll virtual (`updateVirtualWindow`) DEBE mantener `< 150` filas DOM montadas en el viewport en todo momento, reciclando elementos del pool cuando sea posible incluso con `100,000+` commits.
+   - Usa cálculos incrementales con `requestAnimationFrame` y evita reflows síncronos (`offsetHeight`/`getBoundingClientRect`) dentro de bucles por fila.
+2. **Motor Topológico y Offload (`GraphLayout` & `DagWorkerEngine`):**
+   - Mantén el cálculo puro en funciones deterministas sin dependencias de `vscode` para poder ejecutarlas tanto en Node.js como dentro de un Web Worker.
+   - Al usar `OffscreenCanvas` (para el minimapa o carriles), provee siempre fallback limpio para entornos sin `OffscreenCanvas`.
+   - Soporta hashes SHA-1 (40 chars) y SHA-256 (64 chars), así como merges múltiples (octopus) y commits raíz huérfanos.
+3. **Interactividad & A11y:**
+   - Todo nodo SVG/Canvas decorativo debe llevar `aria-hidden="true"`.
+   - Cada fila de commit debe mantener su `role="row"`, `aria-label` descriptivo con ramas/tags/padres y sincronización exacta con la navegación por teclado (`ArrowUp`, `ArrowDown`, `PageUp`, `PageDown`, `Home`, `End`).
+   - Las operaciones Drag-and-Drop sobre ramas/commits (reset, checkout, cherry-pick, rebase) DEBEN pedir confirmación explícita en modal seguro antes de mutar Git.
@@ -0,0 +1,27 @@
+---
+name: commitflow-issue-workflow
+description: Flujo de trabajo GitFlow estricto de CommitFlow: main <- staging <- ramas por issue (feat|fix|design|test|perf/<id>-<slug>), enlace con gh issue develop, Conventional Commits y PRs hacia staging.
+---
+
+# CommitFlow Issue & Branch Workflow Skill
+
+Sigue siempre este ciclo de vida GitFlow adaptado al repositorio `Ignaciobrenas/CommitFlow`:
+1. **Jerarquía de Ramas:**
+   - `main`: Producción estable y releases del Marketplace. Solo recibe PRs desde `staging` (o `hotfix/*`).
+   - `staging`: Rama de integración continua. **Todas** las ramas de trabajo nacen de `staging` y regresan mediante PR hacia `staging`.
+   - Nomenclatura de ramas (compatible con `IssueBranchLinker`):
+     - `feat/<id>-<slug>` (nuevas funcionalidades)
+     - `fix/<id>-<slug>` (corrección de bugs)
+     - `design/<id>-<slug>` (UI/UX, `DESIGN.md`, `SKILL.md`, accesibilidad)
+     - `test/<id>-<slug>` (suites de tests, fuzzing, E2E, CI)
+     - `perf/<id>-<slug>` (rendimiento, Web Workers, `OffscreenCanvas`, watcher)
+2. **Crear rama enlazada al Issue:**
+   ```bash
+   git checkout staging && git pull origin staging
+   gh issue develop <ID> --base staging --name <tipo>/<ID>-<slug> --checkout
+   ```
+3. **Commits Convencionales:**
+   - Usa `type(scope): description (#ID)`, por ejemplo: `feat(engine): add binary packfile reader in GitFsReader (#10)`.
+4. **Pull Request hacia `staging`:**
+   - Incluye siempre `Refs #<ID>` en el cuerpo del PR hacia `staging` (y `Closes #<ID>` en el PR de release `staging` -> `main` para cierre automático).
+   - Antes de abrir o mergear el PR, ejecuta `npm run compile`, `npm test` y `npm run build`.
@@ -0,0 +1,20 @@
+---
+name: commitflow-qa-testing
+description: Guía de la pirámide completa de QA para CommitFlow: tests unitarios, property-based fuzzing, pruebas E2E del servidor MCP (stdio + HTTP/SSE), auditoría responsiva y WCAG 2.1 AA en Chromium headless, benchmarks de 50k commits y smoke tests E2E de extensión VS Code.
+---
+
+# CommitFlow QA & Testing Pyramid Skill
+
+Antes de dar por finalizada cualquier feature, bugfix o refactorización, valida las capas aplicables de la pirámide de calidad:
+1. **Typecheck y Compilación (`npm run compile` & `npm run build`):**
+   - Cero errores de TypeScript estricto y bundle limpio en `dist/`.
+2. **Tests Unitarios y de Integración (`npm test` -> `test/runTests.ts`):**
+   - Cubre lógica pura (`GraphLayout`, `GitFsReader`, `GitParser`, `SshConfigParser`, `IssueBranchLinker`, `ConventionalCommitsBuilder`, `IpcSchemaValidator`, `AdaptiveDebouncer`).
+3. **Property-Based Fuzzing (`test/fuzzTests.ts`):**
+   - Ejecuta 1,000+ iteraciones deterministas inyectando `packed-refs` corruptos, reflogs truncados, buffers binarios aleatorios, alias SSH circulares, rutas Unicode y grafos complejos sin lanzar excepciones no controladas.
+4. **E2E del Servidor MCP (`test/mcpE2eTests.ts`):**
+   - Prueba real contra repositorio temporal en disco: `stdio` (`dist/mcp.js`) y `CommitFlowHttpServer` (`/health`, `/sse`, `/mcp`), JSON-RPC 2.0 `initialize`, todas las tools y resources, scoping de repo, rechazo 401/403, rate-limiting 429 y log de auditoría.
+5. **Webview Multi-Viewport, Temas y WCAG 2.1 AA (`scripts/verify-responsive.js`):**
+   - Verifica en Chromium/Edge headless los 4 breakpoints (`240px` Nano, `360px` Sidebar, `520px` Compact, `1100px` Wide Split) y temas (`dark`, `light`, `high-contrast`, `high-contrast-light`) con `0` overflows, `0` colisiones y `0` violaciones A11y.
+6. **Benchmarks y Empaquetado (`scripts/benchmark-50k.js` & `npx vsce package`):**
+   - Verifica layout de 50,000 commits dentro del presupuesto de latencia/memoria y que el `.vsix` se empaquete sin errores.
@@ -0,0 +1,19 @@
+---
+name: commitflow-ui-design
+description: Diseña e implementa interfaces Webview para CommitFlow siguiendo DESIGN.md, variables CSS de VS Code, Codicons, accesibilidad WCAG 2.1 AA y los 4 breakpoints responsivos multi-dock. Úsala al crear o modificar componentes UI, drawers, modales o temas.
+---
+
+# CommitFlow UI & Webview Design Skill
+
+Antes de escribir código UI en `src/graph/graphWebviewProvider.ts`, `src/webview/main.ts`, `src/webview/primitives.ts` o `src/webview/style.css`:
+1. Lee `DESIGN.md` en la raíz del proyecto.
+2. Verifica que **NO** se importe ni se referencie `@vscode/webview-ui-toolkit` (deprecado en enero de 2025). Utiliza tokens `--vscode-*` y los primitivos nativos en `src/webview/primitives.ts` (`CfButton`, `CfBadge`, `CfDrawer`, `CfTabs`, `CfToast`, `CfSkeleton`, `clampPopoverToViewport`).
+3. **Checklist obligatorio por componente:**
+   - [ ] Funciona en temas VS Code: Dark+, Light+, High Contrast Dark (`.vscode-high-contrast`) y High Contrast Light (`.vscode-high-contrast-light`).
+   - [ ] Verificado en los 4 viewports multi-dock: Nano (`240px`), Sidebar Compact (`360px`), Compact (`520px`), Wide Split (`1100px`) y Bottom Panel (`1000x250px`).
+   - [ ] Usa `tabular-nums` (`font-variant-numeric: tabular-nums`) para hashes SHA, timestamps y contadores `+N/-N`.
+   - [ ] Incluye roles ARIA semánticos (`treegrid`, `row`, `gridcell` en el grafo; `role="dialog"` y `trapModalFocus` en modales) y foco visible (`outline: 1px solid var(--vscode-focusBorder)`).
+   - [ ] Cero `innerHTML` con datos de commits/issues/usuarios sin escapar (`escapeHtml`); CSP estricto con `nonce`.
+   - [ ] Popovers/drawers usan `clampPopoverToViewport` y se cierran al hacer clic fuera o pulsar `Escape`.
+   - [ ] Mensajes de estado vacío claros con CTA accionable y `CfSkeleton` loaders no bloqueantes.
+   - [ ] Respeta `@media (prefers-reduced-motion: reduce)`.
@@ -2,9 +2,9 @@ name: CI & Quality Gate
 
 on:
   push:
-    branches: [ main ]
+    branches: [ main, staging ]
   pull_request:
-    branches: [ main ]
+    branches: [ main, staging ]
 
 jobs:
   build-and-test:

@@ -0,0 +1,23 @@
+name: Staging PR & Issue Link Gate
+
+on:
+  pull_request:
+    branches: [ staging, main ]
+
+jobs:
+  verify-issue-link:
+    name: Verify Issue Reference in PR
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check PR references an Issue
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const pr = context.payload.pull_request;
+            const text = `${pr.title}\n${pr.body || ''}`;
+            const hasIssueRef = /#\d+/.test(text);
+            if (!hasIssueRef) {
+              core.setFailed('El PR debe referenciar al menos un Issue (ej: "Refs #6" o "Closes #6").');
+            } else {
+              core.info(`PR #${pr.number} references issue(s) cleanly.`);
+            }
@@ -0,0 +1,61 @@
+# CommitFlow Design System (DESIGN.md)
+
+## 1. Visual Theme & Atmosphere
+- **Philosophy:** **"Precision Developer Telemetry"**. High information density without visual noise; native VS Code integration that respects 100% of the user's active IDE theme (Light, Dark, High Contrast Dark, High Contrast Light) while delivering vivid semantic identity across the commit DAG via curated chromatic lane palettes.
+- **Surface Hierarchy:** Strictly layered via native VS Code tokens with sensible fallbacks:
+  - Primary Canvas / Editor Surface: `var(--vscode-editor-background)` (`--bg-primary`)
+  - Secondary Chrome / Sidebar / Header: `var(--vscode-sideBar-background)` (`--bg-secondary`)
+  - Elevated / Tabs / Popovers / Modals: `var(--vscode-editorGroupHeader-tabsBackground)` / `var(--vscode-panel-background)` (`--bg-tertiary`)
+  - Interactive States: `var(--vscode-list-hoverBackground)` (`--bg-hover`), `var(--vscode-list-activeSelectionBackground)` (`--bg-active`)
+  - Borders & Focus: `var(--vscode-widget-border)` / `var(--vscode-panel-border)` (`--border-subtle`), `var(--vscode-focusBorder)` (`--focus-ring`)
+
+## 2. Color Palette & Tokens
+- **Base IDE Integration:**
+  - Foreground: `var(--vscode-editor-foreground)` / `var(--vscode-foreground)`
+  - Secondary Muted Text: `var(--vscode-descriptionForeground)`
+  - Focus Ring: `var(--vscode-focusBorder)` (must always remain visible on keyboard focus)
+  - High Contrast Borders: `var(--vscode-contrastBorder)`, `var(--vscode-contrastActiveBorder)`
+- **Semantic Status Tokens:**
+  - `Success / Bisect Good / Valid Sig / Ready PR`: `#10b981` (`--accent-emerald` in Dark) / `#1a7f37` (Light)
+  - `Danger / Bisect Bad / Conflict / Drop`: `#ef4444` / `#f43f5e` (`--accent-rose` in Dark) / `#cf222e` (Light)
+  - `Warning / Untrusted / Dirty / Pending`: `#f59e0b` (`--accent-amber` in Dark) / `#9a6700` (Light)
+  - `Probe / Active Bisect / Primary Accent`: `#38bdf8` / `#06b6d4` (`--accent-cyan` in Dark) / `#0969da` (Light)
+  - `MCP / AI Studio / Rebase Accent`: `#8b5cf6` (`--accent-violet` in Dark) / `#8250df` (Light)
+- **DAG Chromatic Lane Palettes (`GraphLayout.THEME_LANE_COLORS`):**
+  - Supported presets: `auto`, `dark`, `light`, `cyberpunk`, `dracula`, `github`, `neon-pink`, `neon-green`, `neon-blue`.
+  - Adjacent lanes must maintain clear perceptual color separation. In High Contrast themes (`vscode-high-contrast`, `vscode-high-contrast-light`), borders and focus outlines override subtle alpha fills.
+
+## 3. Typography & Rhythm
+- **UI Font:** `var(--vscode-font-family)` with adaptive sizing (`--font-size-base: 12px`, `--font-size-sm: 11px`, `--font-size-xs: 10px`).
+- **Monospace Telemetry Font:** `var(--vscode-editor-font-family)` with mandatory `font-variant-numeric: tabular-nums` (`class="tabular-nums"`) for:
+  - Commit SHAs (`shortHash`, full 40/64-char SHA)
+  - Diff line deltas (`+N / -M`)
+  - Relative/absolute timestamps, branch pill counters, and stat bar counters
+  - File paths and bisect step estimators
+- **Spacing & Radii:** `--radius-xs: 4px`, `--radius-sm: 6px`, `--radius-md: 8px`, `--radius-lg: 10px`, `--radius-xl: 12px`, `--radius-full: 9999px`.
+- **Density Tiers (`commitflow.graph.density`):** `compact` (`22px` row height), `comfortable` (`26px`), `spacious` (`32px`).
+
+## 4. Adaptive Multi-Dock Breakpoints
+CommitFlow operates seamlessly across left/right Activity Bar sidebars, bottom terminal panel, and full Editor panels using container-aware layout classes:
+- **Nano (`<= 260px` / `.layout-nano`):**
+  - Navigation tabs collapse to icon-only buttons with native `title` + `aria-label` tooltips.
+  - Secondary metadata (author email, timestamps, extra stats dividers) are hidden cleanly.
+  - Minimum touch/click target size `28x28px`.
+- **Sidebar Compact (`261px - 440px` / `.layout-sidebar-compact`):**
+  - Single-column stacked layout for DAG rows and cards.
+  - Inspector drawer renders as a full-width overlay drawer clamped cleanly inside the viewport.
+- **Compact (`441px - 600px` / `.layout-width-compact`):**
+  - Compact branch pills, abbreviated badges, wrapped flex toolbars with zero horizontal overflow.
+- **Wide / Bottom Panel (`> 600px`):**
+  - Dual-pane split view (DAG + Minimap on the left, Commit/PR Inspector Drawer on the right) or horizontal bottom-dock layout (`>= 540px` width and `<= 380px` height -> `.auto-detected-bottom` / `.layout-height-short`).
+
+## 5. Component Rules (Zero Deprecated Toolkits)
+1. **ZERO `@vscode/webview-ui-toolkit`:** Officially deprecated and archived in January 2025. Never import or depend on it.
+2. **Native UI Primitives (`src/webview/primitives.ts`):** All new UI elements use CommitFlow's lightweight zero-dependency primitives (`CfButton`, `CfBadge`, `CfDrawer`, `CfTabs`, `CfToast`, `CfSkeleton`) built exclusively with `--vscode-*` CSS variables and `@vscode/codicons`.
+3. **Icons:** Use `@vscode/codicons` (`<i class="codicon codicon-...">`) or accessible inline SVGs marked with `aria-hidden="true"`.
+4. **Viewport Clamping & Popover Dismissal:** All popovers, tooltips, context menus, and drawers must clamp against viewport edges (`clampPopoverToViewport`) and dismiss on outside click or `Escape`.
+5. **Motion & Reduced Motion:** Use `--ease-spring` / `--duration-fast` for crisp transitions, and strictly disable animations, spinners, and pulse keyframes inside `@media (prefers-reduced-motion: reduce)`.
+6. **Security & CSP:** Enforce `default-src 'none'` with cryptographic `nonce` per load; never inject untrusted user or commit strings via raw `innerHTML` without HTML escaping.
+7. **Accessibility (WCAG 2.1 AA):**
+   - Graph container uses `role="treegrid"` with `role="row"` and `role="gridcell"`, descriptive `aria-label` per commit, and roving `tabindex` (`ArrowUp`, `ArrowDown`, `PageUp`, `PageDown`, `Home`, `End`).
+   - All modals trap `Tab`/`Shift+Tab` focus (`trapModalFocus`) and restore focus on close.
@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# 1. Asegurar main actualizada y crear staging (si no existe)
+git checkout main
+git pull origin main
+if ! git show-ref --verify --quiet refs/heads/staging; then
+  git checkout -b staging
+  git push -u origin staging
+else
+  git checkout staging
+  git pull origin staging
+fi
+
+# 2. Crear etiquetas organizadas en el repositorio
+gh label create "epic:design"   --color "ec4899" --description "Design system, SKILLS, UI/UX y responsive" --force
+gh label create "epic:engine"   --color "0284c7" --description "GitFsReader offline, performance y DAG" --force
+gh label create "epic:features" --color "10b981" --description "Funcionalidades Git, Providers y Conflict Studio" --force
+gh label create "epic:security" --color "ef4444" --description "Seguridad MCP, CSP y validacion IPC" --force
+gh label create "epic:testing"  --color "8b5cf6" --description "Playwright, Fuzzing, A11y, MCP E2E y CI" --force
+
+create_issue() {
+  local title="$1"
+  local label="$2"
+  local body="$3"
+  gh issue create --title "$title" --label "$label" --body "$body"
+}
+
+echo "Usa create_issue \"<titulo>\" \"<etiqueta>\" \"<cuerpo>\" para crear nuevos issues enlazables a staging."