specleap-framework 2.0.8 → 2.0.9

package/CLAUDE.md

@@ -0,0 +1,357 @@
+# SpecLeap — Context for Claude Code & Claude API
+
+**Methodology:** Spec-Driven Development (SDD). Spec first, never code first.
+
+---
+
+## 🌐 Default Language: SPANISH
+
+**CRITICAL:** All feedback, messages, commit messages, and user-facing text MUST be in SPANISH.
+
+This project is for Spanish-speaking teams. All agents, commands, and responses must use Spanish unless explicitly overridden.
+
+**Examples:**
+❌ "Generating plan..."
+✅ "Generando plan..."
+
+❌ "Tests passed"
+✅ "Tests pasaron"
+
+See individual agent files (`.agents/*.md`) for specific language directives.
+
+---
+
+## Project Structure
+
+This is **SpecLeap**, a development framework that combines:
+- **Conversational agents** (specialized roles with commands)
+- **Spec-Driven Development** (contracts first, code second)
+- **Multi-project support** (independent projects with contracts)
+
+---
+
+## Core Principles
+
+1. **CONTRATO.md is IMMUTABLE** — Once accepted, never modify. Use ANEXOS.md for improvements.
+2. **Projects are independent** — Each project in `proyectos/` has its own contract and context.
+3. **Commands are in Spanish** — `refinar`, `planificar`, `implementar`, `explicar`, `documentar`
+4. **Agents have roles** — Backend, Frontend, Product Analyst (see `.agents/`)
+5. **Standards are global** — `specs/*.mdc` apply to ALL projects
+
+---
+
+## Getting Started
+
+### Trigger Word: "Hola"
+
+When the user says **"Hola"** (case-insensitive), execute `.commands/inicio.md`:
+1. List available projects in `proyectos/`
+2. Ask which project to work on (or new project)
+3. Load project context (CONTRATO.md + context/)
+4. Ask what type of work (DESARROLLO / DOCUMENTACIÓN)
+
+---
+
+## Slash Command Detection (CRITICAL)
+
+**When the user writes a SINGLE slash command** (e.g., just `refinar` or `crear-tickets`), **AUTOMATICALLY**:
+
+1. **Detect the command** from the message
+2. **Read the corresponding `.commands/*.md` file**
+3. **Follow the instructions in that file step-by-step**
+
+**Command-to-File Mapping:**
+
+| User writes | Read this file | Then execute |
+|-------------|----------------|--------------|
+| `/inicio` or `Hola` | `.commands/inicio.md` | Start workflow |
+| `ayuda`, `help`, `comandos` | `.commands/ayuda.md` | List ALL available commands |
+| `refinar` | `.commands/refinar.md` | Refine user story |
+| `planificar` | `.commands/planificar.md` | Generate backlog |
+| `crear-tickets` | `.commands/crear-tickets.md` | Alias of `planificar` |
+| `implementar` | `.commands/implementar.md` | Execute implementation |
+| `explicar` | `.commands/explicar.md` | Explain concept |
+| `documentar` | `.commands/documentar.md` | Update docs |
+| `adoptar` | `.commands/adoptar.md` | Adopt legacy project |
+
+**Rules:**
+- If user writes `/comando` alone → read `.commands/comando.md` immediately
+- If user writes `/comando` + context → read file + use context
+- NEVER ask "should I read the file?" — just read it
+
+---
+
+## Commands Available
+
+| Command | Description | Agente |
+|---------|-------------|--------|
+| `refinar SCRUM-XX` | Refine Jira user story | producto.md |
+| `planificar SCRUM-XX` | Generate implementation plan | backend.md / frontend.md |
+| `implementar @plan.md` | Execute plan: branch + code + tests + PR | backend.md / frontend.md |
+| `explicar [concepto]` | Explain code/architecture/decisions | neutral |
+| `documentar` | Update technical documentation | neutral |
+
+**See:** `.commands/` for detailed command specifications.
+
+---
+
+## Agents
+
+Adopt these roles when executing commands:
+
+- **`.agents/backend.md`** — Laravel + PHP + API expert
+- **`.agents/frontend.md`** — React + TypeScript + Vite expert
+- **`.agents/producto.md`** — Product analyst + user story enrichment
+
+**When to adopt:**
+- `refinar` → producto.md
+- `planificar` backend → backend.md
+- `planificar` frontend → frontend.md
+- `implementar` → backend.md or frontend.md (depending on plan)
+
+---
+
+## Standards (Always Apply)
+
+Read and follow these standards for ALL code:
+
+### Global Standards
+1. **`specs/base-standards.mdc`** — Core principles (English only, TDD, small steps)
+2. **`specs/backend-standards.mdc`** — Backend patterns (DDD, testing)
+3. **`specs/frontend-standards.mdc`** — Frontend patterns (components, state)
+4. **`specs/documentation-standards.mdc`** — Documentation structure
+
+### Technology-Specific Standards
+5. **`specs/laravel-standards.mdc`** — Laravel + PHP + Eloquent
+6. **`specs/react-standards.mdc`** — React + TypeScript + hooks
+
+**Always read relevant standards before implementing.**
+
+---
+
+## Agent Skills (Progressive Disclosure)
+
+If **20 Agent Skills TIER 1** are installed (`~/.skills/`), they activate automatically:
+
+### Activation Triggers
+
+Skills load knowledge **only when needed** based on context:
+
+```
+User: "Crear endpoint POST /api/products con validación"
+
+Auto-activates:
+  ✓ api-design-principles
+  ✓ backend-api-security
+  ✓ laravel-specialist
+  ✓ verification-before-completion
+  ✓ postgresql-table-design
+```
+
+### Critical Skills
+
+#### verification-before-completion ⭐ **MANDATORY**
+
+**Before creating ANY function, class, or component:**
+1. **SEARCH** existing code for similar functionality
+2. **READ** conventions.md for naming patterns
+3. **VERIFY** utilities/services don't already exist
+4. **ONLY THEN** create if nothing similar exists
+
+**Anti-Pattern (NEVER DO):**
+- ❌ Create `UserHelper` when `UserService` exists
+- ❌ Create `formatPrice()` when `formatCurrency()` exists
+- ❌ Create new HTTP client when axios instance exists
+
+#### code-review-excellence
+
+Before committing, verify:
+- No duplicated code
+- Follows conventions.md
+- Tests coverage >= 90%
+- Security best practices
+
+#### backend-api-security
+
+For all endpoints:
+- Server-side validation
+- Rate limiting
+- CSRF protection
+- SQL injection prevention
+- XSS sanitization
+
+#### frontend-design + web-design-guidelines
+
+For all components:
+- Professional design (Vercel/Linear style)
+- Consistent spacing (4px grid)
+- Responsive mobile-first
+- Micro-interactions
+- Design system coherence
+
+### Skill Categories
+
+**🔒 Security (5):**
+- sast-configuration
+- stride-analysis-patterns
+- security-requirement-extraction
+- backend-api-security
+- frontend-mobile-security
+
+**🔄 Consistency (3):**
+- verification-before-completion ⭐
+- code-review-excellence
+- systematic-debugging
+
+**🎨 Design/Frontend (6):**
+- web-design-guidelines
+- frontend-design
+- ui-ux-pro-max
+- tailwind-design-system
+- shadcn-ui
+- responsive-design
+
+**🛠️ Backend/Dev (6):**
+- laravel-specialist
+- vercel-react-best-practices
+- test-driven-development
+- api-design-principles
+- postgresql-table-design
+- error-handling-patterns
+
+**See:** [SETUP.md](SETUP.md) for installation details.
+
+---
+
+## Project Structure
+
+```
+proyectos/[project-name]/
+├── CONTRATO.md          # 🔒 IMMUTABLE contract
+├── ANEXOS.md            # ✏️ Improvements/modules
+├── context/             # Memory-bank
+│   ├── brief.md
+│   ├── architecture.md
+│   ├── tech-stack.md
+│   ├── conventions.md
+│   └── decisions.md
+└── specs/               # Feature specs
+    ├── [TICKET-ID]_backend.md
+    └── [TICKET-ID]_frontend.md
+```
+
+**Before working on a project:**
+1. Read `CONTRATO.md` — Understand the contract
+2. Read `context/architecture.md` — Understand architecture
+3. Read `context/conventions.md` — Follow code patterns
+
+---
+
+## Workflow Example
+
+```
+User: "Hola"
+AI: [Execute .commands/inicio.md]
+    - List projects
+    - Ask which project + type of work
+
+User: "app-tienda y desarrollo"
+AI: [Load proyectos/app-tienda/CONTRATO.md + context/]
+    "✅ Proyecto app-tienda cargado. ¿Qué ticket trabajarás?"
+
+User: "SCRUM-23"
+AI: "¿Refinar o planificar directamente?"
+
+User: "planificar SCRUM-23"
+AI: [Adopt .agents/backend.md]
+    [Read CONTRATO + context + ticket]
+    [Generate plan in specs/SCRUM-23_backend.md]
+    "📋 Plan creado. Revisar antes de implementar."
+
+User: "implementar @SCRUM-23_backend.md"
+AI: [Adopt .agents/backend.md]
+    [Execute plan step by step]
+    [Tests, commit, push, PR]
+    "✅ Implementación completada. PR: [URL]"
+```
+
+---
+
+## CLI Tools (Optional)
+
+Besides conversational commands, the `openspec` CLI is available:
+
+```bash
+openspec enrich "user story"      # Refine user story
+openspec new --auto "feature"     # Create proposal
+openspec verify CHANGE-001        # Verify tests
+openspec status                   # List proposals
+```
+
+See: `openspec/cli/README.md`
+
+---
+
+## MCP Integrations
+
+### ⚠️ Jira MCP (MANDATORY)
+
+**Jira is MANDATORY for SpecLeap workflow.**
+
+MUST use for:
+- `crear-tickets` — Generate all tickets from CONTRATO.md
+- `refinar SCRUM-XX` — Read and enrich ticket
+- `planificar SCRUM-XX` — Read ticket for plan generation
+- `implementar` — Update ticket status during implementation
+- Automatic updates: "To Do" → "In Progress" → "In Review" → "Done"
+
+**Without Jira MCP, the workflow DOES NOT WORK.**
+
+### CodeRabbit (Recommended)
+
+**Automatic code review on all PRs.**
+
+- Install CodeRabbit GitHub App on repos
+- Copy `.coderabbit.yaml` from `proyectos/_template/`
+- Reviews in Spanish
+- Checks: specs compliance, tests >= 90%, security, standards
+- `implementar` waits for CodeRabbit approval before marking complete
+
+### Context7 MCP (Optional)
+
+If configured, use for:
+- Fetching up-to-date library documentation (Laravel, React, etc.)
+- Avoid outdated knowledge
+
+---
+
+## Critical Rules
+
+1. **NEVER modify CONTRATO.md** after accepted — Only add to ANEXOS.md
+2. **NEVER push to main directly** — Always via PR
+3. **Tests must pass** — >= 90% coverage
+4. **Follow conventions.md** — Each project has specific patterns
+5. **All code in ENGLISH** — Variables, functions, comments, docs
+6. **User-facing text in SPANISH** — Error messages, UI text
+
+---
+
+## References
+
+- **Commands:** `.commands/*.md`
+- **Agents:** `.agents/*.md`
+- **Standards:** `specs/*.mdc`
+- **Project Template:** `proyectos/_template/`
+- **CLI Reference:** `openspec/cli/COMMAND_REFERENCE.md`
+
+---
+
+**When in doubt:**
+1. Read the relevant `.commands/` file
+2. Adopt the specified `.agents/` role
+3. Follow `specs/` standards
+4. Ask the user for clarification
+
+---
+
+*Made with ❤️ by the SpecLeap Community*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specleap-framework",
-  "version": "2.0.8",
+  "version": "2.0.9",
   "description": "Spec-Driven Development Framework — Transform VSCode, Cursor, JetBrains into spec-first development machines",
   "keywords": [
     "spec-driven-development",
@@ -41,7 +41,7 @@
   },
   "files": [
     ".agents/**",
-    ".claude",
+    ".claude/**",
     ".clinerules",
     ".coderabbit.yaml",
     ".commands/**",
@@ -56,6 +56,7 @@
     "scripts/**",
     "setup.sh",
     "install.sh",
+    "CLAUDE.md",
     "README.md",
     "SETUP.md",
     "LICENSE"