@nextsparkjs/ai-workflow 0.1.0-beta.100

package/claude/skills/session-management/SKILL.md

@@ -0,0 +1,266 @@
+# Session Management Skill
+
+Sistema de gestión de sesiones de desarrollo para Claude Code.
+
+## Conceptos Clave
+
+### Tipos de Sesión
+
+| Tipo | T-Shirt | Workflow | Carpeta | Descripción |
+|------|---------|----------|---------|-------------|
+| **Story** | L - XL | COMPLETE | `stories/` | Features complejos, múltiples iteraciones |
+| **Task** | S - M | STANDARD | `tasks/` | Mejoras, bugs medianos |
+| **Log** | XS | QUICK | `logs/` | Fixes rápidos, cambios triviales |
+
+### Estructura de Carpetas
+
+```
+.claude/sessions/
+├── scripts/              # Scripts de gestión
+├── templates/            # Templates por tipo
+│   ├── story/
+│   ├── task/
+│   ├── iteration/
+│   └── log.md
+├── stories/              # Sesiones COMPLETE
+├── tasks/                # Sesiones STANDARD
+├── logs/                 # Sesiones QUICK
+└── archive/              # Sesiones completadas
+```
+
+---
+
+## Scripts Disponibles
+
+### session-init.sh
+
+Crea una nueva sesión con toda su estructura.
+
+```bash
+# Sintaxis
+.claude/skills/session-management/scripts/session-init.sh <type> <name> [tshirt]
+
+# Parámetros
+# type:   story | task | log
+# name:   nombre descriptivo (sin fecha, se agrega auto)
+# tshirt: xs | s | m | l | xl (opcional, default según type)
+
+# Ejemplos
+.claude/skills/session-management/scripts/session-init.sh story new-products-entity L
+.claude/skills/session-management/scripts/session-init.sh task improve-search M
+.claude/skills/session-management/scripts/session-init.sh log fix-typo
+```
+
+**Output:**
+```
+Creating story session: 2026-01-11-new-products-entity
+
+Created: stories/2026-01-11-new-products-entity/
+Files: context.md, requirements.md, plan.md, scope.json, pendings.md, tests.md
+Iteration: iterations/01-initial/
+Current: current/ -> iterations/01-initial/
+```
+
+### session-list.sh
+
+Lista sesiones activas con su estado.
+
+```bash
+# Sintaxis
+.claude/skills/session-management/scripts/session-list.sh [type] [--all]
+
+# Ejemplos
+.claude/skills/session-management/scripts/session-list.sh              # Solo activas
+.claude/skills/session-management/scripts/session-list.sh stories      # Solo stories activas
+.claude/skills/session-management/scripts/session-list.sh --all        # Incluir archivadas
+```
+
+**Output:**
+```
+=== SESSION LIST ===
+
+STORIES
+  2026-01-11-new-products-entity [L] iteration-02 (60%)
+  2026-01-08-refactor-auth [XL] iteration-01 (30%)
+  Total: 2 active
+
+TASKS
+  2026-01-10-improve-search [M] (80%)
+  Total: 1 active
+
+LOGS
+  2026-01-11-fix-typo-login
+  Total: 1 active
+```
+
+### session-close.sh
+
+Cierra una sesión activa (marca como completada).
+
+```bash
+# Sintaxis
+.claude/skills/session-management/scripts/session-close.sh <session-path> [summary]
+
+# Ejemplo
+.claude/skills/session-management/scripts/session-close.sh stories/2026-01-11-new-products-entity "Feature completed"
+```
+
+### session-archive.sh
+
+Mueve una sesión cerrada al archivo.
+
+```bash
+# Sintaxis
+.claude/skills/session-management/scripts/session-archive.sh <session-path>
+
+# Ejemplo
+.claude/skills/session-management/scripts/session-archive.sh stories/2026-01-11-new-products-entity
+```
+
+### iteration-init.sh
+
+Crea una nueva iteración dentro de una story.
+
+```bash
+# Sintaxis
+.claude/skills/session-management/scripts/iteration-init.sh <session-path> <reason> [name]
+
+# Parámetros
+# reason: scope-change | blocked | review-feedback | continuation
+
+# Ejemplo
+.claude/skills/session-management/scripts/iteration-init.sh stories/2026-01-11-new-products-entity scope-change "add-variants"
+```
+
+### iteration-close.sh
+
+Cierra la iteración actual sin crear una nueva.
+
+```bash
+# Sintaxis
+.claude/skills/session-management/scripts/iteration-close.sh <session-path> <status> [summary]
+
+# Parámetros
+# status: completed | blocked | paused
+
+# Ejemplo
+.claude/skills/session-management/scripts/iteration-close.sh stories/2026-01-11-new-products-entity completed "All ACs met"
+```
+
+---
+
+## Flujos de Uso
+
+### Iniciar Nueva Sesión
+
+1. **Evaluar complejidad** (T-Shirt sizing)
+2. **Determinar tipo** de sesión:
+   - XS → `log`
+   - S-M → `task`
+   - L-XL → `story`
+3. **Ejecutar script**:
+   ```bash
+   ./session-init.sh <type> <name> <tshirt>
+   ```
+4. **Completar templates** generados
+
+### Retomar Sesión Existente
+
+1. **Listar sesiones**:
+   ```bash
+   ./session-list.sh
+   ```
+2. **Leer archivos de la sesión**:
+   - `context.md` → Contexto general
+   - `requirements.md` → Qué hay que hacer
+   - `plan.md` → Cómo hacerlo
+   - `current/progress.md` → Estado actual
+3. **Continuar desarrollo**
+
+### Cambio de Scope
+
+Cuando el alcance cambia significativamente:
+
+1. **Crear nueva iteración**:
+   ```bash
+   ./iteration-init.sh <session> scope-change "descripción"
+   ```
+2. **Actualizar** `requirements.md` o `plan.md`
+3. **Continuar** desde nueva iteración
+
+### Cerrar Sesión
+
+1. **Verificar** que todos los ACs están cumplidos
+2. **Cerrar sesión**:
+   ```bash
+   ./session-close.sh <session> "summary"
+   ```
+3. **Archivar** (opcional):
+   ```bash
+   ./session-archive.sh <session>
+   ```
+
+---
+
+## Templates
+
+### Story (COMPLETE)
+
+| Archivo | Propósito | Cambia entre iteraciones? |
+|---------|-----------|---------------------------|
+| `context.md` | Info permanente del proyecto | No |
+| `requirements.md` | ACs, user stories | Sí (git history) |
+| `plan.md` | Plan técnico | Sí (git history) |
+| `scope.json` | Paths permitidos | Sí |
+| `pendings.md` | Pendientes globales | Sí (acumulativo) |
+| `tests.md` | Selectores, traducciones | Sí (acumulativo) |
+
+### Task (STANDARD)
+
+| Archivo | Propósito |
+|---------|-----------|
+| `requirements.md` | Objetivo y ACs |
+| `progress.md` | Estado actual |
+
+### Log (QUICK)
+
+| Archivo | Propósito |
+|---------|-----------|
+| `{date}-{name}.md` | Registro del fix |
+
+---
+
+## Placeholders en Templates
+
+| Placeholder | Descripción | Ejemplo |
+|-------------|-------------|---------|
+| `{{SESSION_NAME}}` | Nombre sin fecha | new-products-entity |
+| `{{SESSION_FULL}}` | Nombre completo | 2026-01-11-new-products-entity |
+| `{{DATE}}` | Fecha de creación | 2026-01-11 |
+| `{{TSHIRT}}` | T-Shirt size | L |
+| `{{ITERATION}}` | Número de iteración | 01 |
+| `{{ITERATION_NAME}}` | Nombre de iteración | initial |
+| `{{CLICKUP_URL}}` | URL de tarea (manual) | - |
+
+---
+
+## Integración con Comandos
+
+Esta skill es utilizada por los comandos `/session:*`:
+
+- `/session:start` → Usa `session-init.sh`
+- `/session:resume` → Usa `session-list.sh` + lectura de archivos
+- `/session:status` → Usa `session-list.sh`
+- `/session:close` → Usa `session-close.sh`
+- `/session:scope-change` → Usa `iteration-init.sh`
+
+---
+
+## Reducción de Tokens
+
+| Operación | Sin Script | Con Script | Reducción |
+|-----------|------------|------------|-----------|
+| Crear story | ~2350 tokens | ~280 tokens | **88%** |
+| Crear task | ~800 tokens | ~150 tokens | **81%** |
+| Listar sesiones | ~500 tokens | ~100 tokens | **80%** |
+| Nueva iteración | ~1200 tokens | ~200 tokens | **83%** |

package/claude/skills/session-management/scripts/create-session.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""
+Create Session Script
+
+Creates a new development session folder with all 8 template files.
+Part of the session-management skill.
+
+Usage:
+    python create-session.py --name "feature-name" [--version 1]
+    python create-session.py -n "user-authentication" -v 2
+"""
+
+import argparse
+import os
+import shutil
+import sys
+from datetime import datetime
+from pathlib import Path
+
+
+def get_project_root() -> Path:
+    """Find the project root by looking for .claude directory."""
+    current = Path(__file__).resolve()
+
+    # Walk up the directory tree
+    for parent in current.parents:
+        if (parent / ".claude").is_dir():
+            return parent
+
+    # Fallback: check current working directory
+    cwd = Path.cwd()
+    if (cwd / ".claude").is_dir():
+        return cwd
+
+    print("Error: Could not find project root (.claude directory)")
+    sys.exit(1)
+
+
+def validate_name(name: str) -> str:
+    """Validate and normalize session name."""
+    # Convert to lowercase and replace spaces with hyphens
+    normalized = name.lower().strip().replace(" ", "-").replace("_", "-")
+
+    # Remove any characters that aren't alphanumeric or hyphens
+    cleaned = "".join(c for c in normalized if c.isalnum() or c == "-")
+
+    # Remove consecutive hyphens
+    while "--" in cleaned:
+        cleaned = cleaned.replace("--", "-")
+
+    # Remove leading/trailing hyphens
+    cleaned = cleaned.strip("-")
+
+    if not cleaned:
+        print("Error: Invalid session name. Must contain alphanumeric characters.")
+        sys.exit(1)
+
+    return cleaned
+
+
+def create_session(name: str, version: int = 1) -> None:
+    """Create a new session folder with all template files."""
+    project_root = get_project_root()
+    templates_dir = project_root / ".claude" / "tools" / "sessions" / "templates"
+    sessions_dir = project_root / ".claude" / "sessions"
+
+    # Validate templates exist
+    if not templates_dir.is_dir():
+        print(f"Error: Templates directory not found: {templates_dir}")
+        sys.exit(1)
+
+    # Generate session name
+    date_str = datetime.now().strftime("%Y-%m-%d")
+    validated_name = validate_name(name)
+    session_name = f"{date_str}-{validated_name}-v{version}"
+    session_path = sessions_dir / session_name
+
+    # Check if session already exists
+    if session_path.exists():
+        print(f"Error: Session already exists: {session_path}")
+        print(f"Hint: Use --version {version + 1} to create a new version")
+        sys.exit(1)
+
+    # Create session directory
+    session_path.mkdir(parents=True, exist_ok=True)
+    print(f"Created session: {session_name}")
+
+    # Expected template files
+    template_files = [
+        "requirements.md",
+        "clickup_task.md",
+        "scope.json",
+        "plan.md",
+        "progress.md",
+        "context.md",
+        "tests.md",
+        "pendings.md",
+    ]
+
+    # Copy templates
+    copied_count = 0
+    for template_file in template_files:
+        src = templates_dir / template_file
+        dst = session_path / template_file
+
+        if src.exists():
+            shutil.copy2(src, dst)
+
+            # Replace placeholders in the copied file
+            if dst.suffix in [".md", ".json"]:
+                content = dst.read_text()
+                content = content.replace("YYYY-MM-DD", date_str)
+                content = content.replace("[Feature Name]", name.title())
+                content = content.replace("feature-name", validated_name)
+                content = content.replace("feature-name-v1", session_name)
+                dst.write_text(content)
+
+            copied_count += 1
+            print(f"  ✓ {template_file}")
+        else:
+            print(f"  ✗ {template_file} (template not found)")
+
+    print(f"\nSession created with {copied_count}/{len(template_files)} files")
+    print(f"\nSession path: {session_path}")
+    print("\nNext steps:")
+    print("  1. Edit requirements.md with business requirements")
+    print("  2. Configure scope.json with file permissions")
+    print("  3. Run /task:plan to create technical plan")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Create a new development session folder",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  python create-session.py --name "user-authentication"
+  python create-session.py -n "scheduled-actions" -v 2
+  python create-session.py --name "billing integration"
+        """
+    )
+
+    parser.add_argument(
+        "-n", "--name",
+        required=True,
+        help="Session name (will be normalized to kebab-case)"
+    )
+
+    parser.add_argument(
+        "-v", "--version",
+        type=int,
+        default=1,
+        help="Session version number (default: 1)"
+    )
+
+    args = parser.parse_args()
+
+    if args.version < 1:
+        print("Error: Version must be a positive integer")
+        sys.exit(1)
+
+    create_session(args.name, args.version)
+
+
+if __name__ == "__main__":
+    main()

package/claude/skills/session-management/scripts/iteration-close.sh

@@ -0,0 +1,105 @@
+#!/bin/bash
+#
+# iteration-close.sh - Close the current iteration without creating a new one
+#
+# Usage: iteration-close.sh <session-path> <status> [summary]
+#   session-path: path to story (e.g., stories/2026-01-11-new-entity)
+#   status:       completed | blocked | paused
+#   summary:      optional summary message
+#
+# Examples:
+#   ./iteration-close.sh stories/2026-01-11-new-products-entity completed
+#   ./iteration-close.sh stories/2026-01-11-new-products-entity blocked "Waiting for API"
+#
+
+set -e
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+# Get script directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SESSIONS_DIR="$(dirname "$SCRIPT_DIR")"
+
+# Parse arguments
+SESSION_PATH="$1"
+STATUS="$2"
+SUMMARY="${3:-Iteration closed}"
+
+# Validate session path
+if [[ -z "$SESSION_PATH" ]]; then
+    echo -e "${RED}Error: Session path is required${NC}"
+    echo "Usage: $0 <session-path> <status> [summary]"
+    exit 1
+fi
+
+# Validate status
+if [[ ! "$STATUS" =~ ^(completed|blocked|paused)$ ]]; then
+    echo -e "${RED}Error: Invalid status '$STATUS'${NC}"
+    echo "Valid statuses: completed, blocked, paused"
+    exit 1
+fi
+
+# Resolve full path
+if [[ "$SESSION_PATH" != /* ]]; then
+    FULL_PATH="$SESSIONS_DIR/$SESSION_PATH"
+else
+    FULL_PATH="$SESSION_PATH"
+fi
+
+# Check if session exists
+if [[ ! -d "$FULL_PATH" ]]; then
+    echo -e "${RED}Error: Session not found: $FULL_PATH${NC}"
+    exit 1
+fi
+
+# Verify it's a story (has iterations folder)
+if [[ ! -d "$FULL_PATH/iterations" ]]; then
+    echo -e "${RED}Error: Not a story session (no iterations folder)${NC}"
+    exit 1
+fi
+
+CURRENT_DIR="$FULL_PATH/current"
+CLOSED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# Find current iteration
+CURRENT_PROGRESS=$(readlink "$CURRENT_DIR/progress.md" 2>/dev/null || echo "")
+if [[ -z "$CURRENT_PROGRESS" ]]; then
+    echo -e "${RED}Error: No active iteration found${NC}"
+    exit 1
+fi
+
+ITERATION_DIR=$(dirname "$CURRENT_PROGRESS")
+ITERATION_DIR=$(cd "$CURRENT_DIR" && cd "$ITERATION_DIR" && pwd)
+ITERATION_NAME=$(basename "$ITERATION_DIR")
+
+echo -e "${BLUE}Closing iteration: $ITERATION_NAME${NC}"
+echo ""
+
+# Create closed.json
+cat > "$ITERATION_DIR/closed.json" << EOF
+{
+  "iteration": "$ITERATION_NAME",
+  "status": "$STATUS",
+  "closedAt": "$CLOSED_AT",
+  "closedBy": "claude",
+  "summary": "$SUMMARY"
+}
+EOF
+
+echo -e "${GREEN}Iteration closed: $ITERATION_NAME${NC}"
+echo -e "${GREEN}Status: $STATUS${NC}"
+echo -e "${GREEN}Created: closed.json${NC}"
+echo ""
+
+if [[ "$STATUS" == "blocked" ]]; then
+    echo -e "${YELLOW}Note: Iteration is blocked. Use iteration-init.sh when ready to continue.${NC}"
+elif [[ "$STATUS" == "paused" ]]; then
+    echo -e "${YELLOW}Note: Iteration is paused. Use iteration-init.sh with 'continuation' reason to resume.${NC}"
+else
+    echo -e "${BLUE}Session can now be archived with session-archive.sh${NC}"
+fi