@ancleto/spec 0.1.0

package/skills/ancleto-upgrade/references/templates.md

@@ -0,0 +1,320 @@
+# Templates — Artefactos OpenSpec
+
+Este archivo contiene los templates exactos para los cuatro artefactos que genera
+el skill. Leer este archivo en el Paso 6 y completar cada placeholder `{...}`.
+
+---
+
+## proposal.md
+
+```markdown
+# Propuesta: Migración a {LIBRARY} v{TARGET_VERSION}
+
+## Contexto
+
+{Descripción del estado actual: versión actual de LIBRARY instalada, razón para migrar
+(EOL, mejoras de performance, compatibilidad, nuevas features). Si se obtuvo documentación
+oficial, resumir los puntos más relevantes del changelog aquí.}
+
+## Cobertura del análisis
+
+- source files analizados: {source_files_scanned}
+- test files analizados: {test_files_scanned}
+- config files analizados: {config_files_scanned}
+- archivos con matches: {files_with_matches}
+- archivos sin matches: {files_without_matches}
+
+## Alcance del cambio
+
+### Dependencias afectadas — {N} paquetes en {M} package.json
+
+| package.json | Paquete | Versión actual | Versión objetivo |
+| ------------ | ------- | -------------- | ---------------- |
+
+{Una fila por cada entry en DEPENDENCY_CHANGES[]}
+
+### Archivos de configuración a modificar — {N} archivos
+
+{Lista de archivos con descripción del cambio requerido. Si no hay, escribir "Ninguno."}
+
+### Código fuente con breaking changes — {N} archivos
+
+{Lista de archivos afectados con el breaking change detectado. Si no hay, escribir "Ninguno."}
+
+### Tests con breaking changes — {N} archivos
+
+{Lista de archivos de test afectados. Si no hay, escribir "Ninguno."}
+
+## Evaluación de breaking changes
+
+{Para cada KNOWN_BREAK relevante a la migración:}
+
+- ✅ AFECTA — {id}: {description} — {N} ocurrencias en {M} archivos
+- ✓ NO AFECTA — {id}: {description}
+
+## Matches de baja confianza
+
+{Lista de UNSURE_MATCHES[] para revisión manual. Si no hay, escribir "Ninguno."}
+
+## Decisión
+
+Migrar {LIBRARY} {CURRENT_VERSION} → v{TARGET_VERSION}.
+
+Fuente de información: {DOCS_URL | "Búsqueda web: {query}" | "Knowledge base interna"}
+```
+
+---
+
+## specs/{LIBRARY_SLUG}{TARGET_VERSION}.md
+
+```markdown
+# Especificaciones: {LIBRARY} v{TARGET_VERSION} Migration
+
+## Dependencias
+
+{Para cada entry en DEPENDENCY_CHANGES[]:}
+
+- REQ-D-{N}: `{package_name}` en `{path}` SHALL usar versión `^{TARGET_VERSION}.0.0`
+
+## Configuración
+
+{Para cada entry en CONFIG_CHANGES[]:}
+
+- REQ-C-{N}: `{file}` SHALL {descripción del cambio requerido}
+
+{Si CONFIG_CHANGES está vacío:}
+No se requieren cambios de configuración.
+
+## Código fuente
+
+{Para cada entry en BREAKING_CHANGES_IN_CODE[]:}
+
+- REQ-S-{N} [{break_id}]: {descripción del cambio requerido en el código}
+  Evidencia: `{file}:{line_number}` ({confidence})
+
+{Si BREAKING_CHANGES_IN_CODE está vacío:}
+No se detectaron breaking changes en código fuente.
+
+## Tests
+
+{Para cada entry en BREAKING_CHANGES_IN_TESTS[]:}
+
+- REQ-T-{N} [{break_id}]: {descripción del cambio requerido en los tests}
+  Evidencia: `{file}:{line_number}` ({confidence})
+
+{Si BREAKING_CHANGES_IN_TESTS está vacío:}
+No se detectaron breaking changes en tests.
+
+## Verificación
+
+- REQ-V-001: El proyecto SHALL compilar sin errores TypeScript
+- REQ-V-002: Todos los tests SHALL pasar luego de la migración
+  {Si lint script existe:}
+- REQ-V-003: El proyecto SHALL pasar lint sin errores
+
+## Cobertura
+
+- REQ-X-001: El análisis SHALL incluir todo archivo de código fuente elegible (`.ts`, `.tsx`, `.js`) excluyendo `node_modules`, `dist` y artefactos generados
+- REQ-X-002: El análisis SHALL incluir todo archivo de tests elegible (`*.spec.*`, `*.test.*`)
+- REQ-X-003: El resultado SHALL reportar métricas de cobertura (`source_files_scanned`, `test_files_scanned`, `config_files_scanned`)
+```
+
+---
+
+## tasks.md
+
+````markdown
+# Tasks: {LIBRARY} v{TARGET_VERSION} Migration
+
+## Fase 1: Dependencias
+
+{Para cada entry en DEPENDENCY_CHANGES[]:}
+
+- [ ] **T-D-{N}** Actualizar `{package_name}` en `{path}` de `{current_version}` a `^{TARGET_VERSION}.0.0`
+
+- [ ] **T-D-LAST** Regenerar lockfile:
+  ```bash
+  npm install
+  ```
+````
+
+## Fase 2: Infraestructura y runtime
+
+{Solo si IS_RUNTIME = true:}
+{Si .nvmrc existe o debe crearse:}
+
+- [ ] **T-I-001** {Crear | Actualizar} `.nvmrc` con el valor `{TARGET_VERSION}`
+
+{Para cada CI file con nodeVersion a cambiar:}
+
+- [ ] **T-I-002** Actualizar `nodeVersion` en `{CI_FILE}` de `{current}` a `{TARGET_VERSION}.x`
+
+{Para cada Dockerfile con FROM node:X:}
+
+- [ ] **T-I-003** Actualizar imagen base en `{Dockerfile}`:
+  ```dockerfile
+  # Antes
+  FROM node:{current}-alpine
+  # Después
+  FROM node:{TARGET_VERSION}-alpine
+  ```
+  _(Ajustar variant según el Dockerfile existente: alpine, slim, bullseye, etc.)_
+
+{Para cada appSettings.json con "Runtime":}
+
+- [ ] **T-I-004** Actualizar `Runtime` en `{appSettings.json}` a `NODEJS_{TARGET_VERSION}_X`
+
+{Si IS*RUNTIME = false:}
+*(No aplica para migraciones de librería)\_
+
+## Fase 3: Configuración de build y tests
+
+{Para cada entry en CONFIG_CHANGES[]:}
+
+- [ ] **T-C-{N}** {Descripción concreta del cambio}
+      Archivo: `{file}`
+  ```
+  // Antes
+  {current_value}
+  // Después
+  {target_value}
+  ```
+
+{Si CONFIG*CHANGES está vacío:}
+*(No se detectaron cambios de configuración necesarios)\_
+
+## Fase 4: Breaking changes en código fuente
+
+{Para cada entry en BREAKING_CHANGES_IN_CODE[]:}
+
+- [ ] **T-S-{N}** [{break_id}] `{severity}` — {description}
+      Fix: {fix}
+      Archivos afectados:
+      {Para cada {file, line_number, snippet}:}
+  - `{file}:{line_number}` ({confidence}) — `{snippet}`
+
+{Si BREAKING*CHANGES_IN_CODE está vacío:}
+*(No se detectaron breaking changes en código fuente para esta migración)\_
+
+## Fase 5: Breaking changes en tests
+
+{Para cada entry en BREAKING_CHANGES_IN_TESTS[]:}
+
+- [ ] **T-T-{N}** [{break_id}] `{severity}` — {description}
+      Fix: {fix}
+      Archivos afectados:
+      {Para cada {file, line_number, snippet}:}
+  - `{file}:{line_number}` ({confidence}) — `{snippet}`
+
+{Si BREAKING*CHANGES_IN_TESTS está vacío:}
+*(No se detectaron breaking changes en tests para esta migración)\_
+
+## Fase 6: Verificación
+
+- [ ] **T-V-001** Verificar compilación TypeScript:
+  ```bash
+  npx tsc --noEmit
+  # En monorepos Nx: npx nx affected --target=typecheck
+  ```
+
+{Si script "build" en SCRIPTS_AVAILABLE[]:}
+
+- [ ] **T-V-002** Verificar build:
+  ```bash
+  npm run build
+  # En monorepos Nx: npx nx affected --target=build
+  ```
+
+{Si script "lint" en SCRIPTS_AVAILABLE[]:}
+
+- [ ] **T-V-003** Ejecutar linter:
+  ```bash
+  npm run lint
+  # En monorepos Nx: npx nx affected:lint
+  ```
+
+{Si script "test" en SCRIPTS_AVAILABLE[]:}
+
+- [ ] **T-V-004** Correr suite de tests:
+  ```bash
+  npm test
+  # En monorepos Nx: npx nx affected --target=test
+  ```
+
+{Si script "test:ci" en SCRIPTS_AVAILABLE[]:}
+
+- [ ] **T-V-005** Correr tests en modo CI:
+
+  ```bash
+  npm run test:ci
+  ```
+
+- [ ] **T-V-900** Validar cobertura del escaneo:
+  - confirmar conteo de archivos escaneados (source/tests/config)
+  - revisar `UNSURE_MATCHES[]` y clasificar cada caso
+
+````
+
+---
+
+## design.md
+
+```markdown
+# Design: {LIBRARY} v{TARGET_VERSION} Migration
+
+## Estrategia de migración
+
+{Explicar el enfoque en orden de las fases: primero dependencias (para detectar errores
+de compilación antes de tocar código), luego infraestructura, luego config, luego código.
+Describir el riesgo principal y cómo se mitiga.}
+
+## Decisiones técnicas
+
+### Rango de versión — `^{TARGET_VERSION}.0.0`
+
+Se usa caret (`^`) en lugar de pin exacto para recibir parches y minor automáticamente,
+manteniendo la estabilidad del major. Se evita `>=` para no aceptar accidentalmente el
+próximo major con potenciales breaking changes.
+
+### Cambios de configuración
+
+{Para cada CONFIG_CHANGE relevante: explicar el razonamiento técnico.}
+{Ej para MIDDY7-001: "Jest necesita transformIgnorePatterns porque @middy v7 publica
+ESM puro y Jest por defecto no transpila node_modules. Sin este cambio, los tests
+fallan con SyntaxError en el import."}
+
+### Breaking changes — análisis de impacto
+
+{Para cada breaking change encontrado: explicar el impacto técnico y por qué el fix
+propuesto es la solución correcta y no un workaround.}
+
+{Si no hay breaking changes: "No se detectaron breaking changes en este repositorio
+para esta migración. El riesgo es bajo."}
+
+### Compatibilidad del ecosistema
+
+{Mencionar dependencias relacionadas que pueden verse afectadas.}
+{Ej para Middy v7: listar middlewares de terceros y su estado de compatibilidad con v7.}
+{Si no aplica: "No se identificaron dependencias del ecosistema con riesgo de incompatibilidad."}
+
+### Calidad del análisis
+
+- Cobertura: {source_files_scanned} source, {test_files_scanned} tests, {config_files_scanned} config
+- Matches de alta confianza: {N}
+- Matches de media confianza: {N}
+- Matches de baja confianza: {N}
+- Estrategia de revisión manual para baja confianza: {criterio aplicado}
+
+## Tabla de cambios
+
+| Archivo | Campo / Patrón | Antes | Después |
+|---------|----------------|-------|---------|
+{Una fila por cada cambio concreto en DEPENDENCY_CHANGES[], CONFIG_CHANGES[],
+BREAKING_CHANGES_IN_CODE[] y BREAKING_CHANGES_IN_TESTS[]}
+
+## Referencias
+
+- {DOCS_URL si está disponible}
+- {Links adicionales encontrados durante el análisis}
+- Knowledge base interna consultada: {lista de break_ids relevantes de known-breaks.md}
+````

package/src/cli/index.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import { cp, mkdir, access, writeFile, readFile } from 'node:fs/promises'
+import { join, dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { homedir } from 'node:os'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const ROOT = join(__dirname, '..', '..')
+const ASSETS = ['agents', 'commands', 'skills']
+const TEMPLATES = ['AGENTS.md', 'PRODUCT.md', 'CONTRIBUTING.md']
+
+const HELP = `ancleto - orquestador SDD liviano con subagentes optimizados para costo/tokens
+(alias: aspec)
+
+Uso:
+  ancleto install [--project <dir>]   Instala agents/commands/skills en opencode
+                                   (global por defecto, o en .opencode/ del proyecto)
+  ancleto update [--project <dir>]    Alias de install (re-instala sobre lo existente)
+  ancleto init                        Crea .ancletorc en el repositorio actual
+  ancleto discovery --check           Estado del technical seed (no implementado aun)
+  ancleto discovery --compress        Genera el pack del repo (no implementado aun)
+  ancleto --help                      Esta ayuda
+  ancleto --version                   Version del paquete
+`
+
+async function exists(p) {
+  try { await access(p); return true } catch { return false }
+}
+
+function globalConfigDir() {
+  return process.env.XDG_CONFIG_HOME
+    ? join(process.env.XDG_CONFIG_HOME, 'opencode')
+    : join(homedir(), '.config', 'opencode')
+}
+
+async function copyAssets(dest) {
+  await mkdir(dest, { recursive: true })
+  for (const d of ASSETS) {
+    await cp(join(ROOT, d), join(dest, d), { recursive: true })
+  }
+}
+
+async function copyTemplates(projectDir) {
+  const dest = join(projectDir, '.opencode')
+  await copyAssets(dest)
+  for (const t of TEMPLATES) {
+    const target = join(projectDir, t)
+    if (await exists(target)) continue
+    await writeFile(target, await readFile(join(ROOT, 'templates', t)))
+  }
+}
+
+async function install(args) {
+  const pi = args.indexOf('--project')
+  const project = pi >= 0 ? args[pi + 1] : null
+  if (project) {
+    const dir = resolve(project)
+    if (!(await exists(dir))) {
+      console.error(`ancleto: el directorio no existe: ${dir}`)
+      process.exit(1)
+    }
+    await copyTemplates(dir)
+    console.log(`ancleto: instalado en ${dir} (.opencode/ + templates en la raiz)`)
+  } else {
+    const target = globalConfigDir()
+    await copyAssets(target)
+    console.log(`ancleto: instalado en ${target} (disponible en todos tus proyectos)`)
+  }
+}
+
+async function initProject() {
+  const rc = join(process.cwd(), '.ancletorc')
+  if (await exists(rc)) {
+    console.log('ancleto: .ancletorc ya existe, no se toca')
+    return
+  }
+  const content = JSON.stringify({
+    version: 1,
+    discovery: {
+      outputDir: 'docs/technical-discovery',
+      exclude: []
+    }
+  }, null, 2)
+  await writeFile(rc, content + '\n')
+  console.log(`ancleto: .ancletorc creado en ${process.cwd()}`)
+}
+
+function discovery() {
+  console.error('ancleto: discovery todavia no esta implementado (motor de repomix pendiente).')
+  process.exit(1)
+}
+
+const [cmd, ...rest] = process.argv.slice(2)
+
+switch (cmd) {
+  case 'install':
+  case 'update':
+    await install(rest)
+    break
+  case 'init':
+    await initProject()
+    break
+  case 'discovery':
+    discovery()
+    break
+  case '--version':
+  case '-v':
+    console.log('ancleto 0.1.0')
+    break
+  case '--help':
+  case '-h':
+  case undefined:
+    console.log(HELP)
+    break
+  default:
+    console.error(`ancleto: comando desconocido: ${cmd}`)
+    console.log(HELP)
+    process.exit(1)
+}

package/templates/AGENTS.md

@@ -0,0 +1,36 @@
+# AI Agents Context
+
+> Contexto global para agentes de IA en este repositorio.
+
+## Context Hierarchy
+
+Antes de actuar, consultar el contexto en este orden:
+
+1. El `AGENTS.md` local del package o app afectada, si existe.
+2. `PRODUCT.md` para contexto del repositorio, estructura, comandos y reglas de producto.
+3. `CONTRIBUTING.md` para el flujo de contribución y validaciones esperadas.
+4. Este `AGENTS.md` como marco común.
+
+En caso de conflicto, gana la documentación más específica del área afectada.
+
+## Guardrails
+
+- Cambios de TypeScript en modo estricto donde aplique.
+- Mantener el repositorio en estado mergeable.
+- No commits directos a ramas protegidas (`main`, `develop`).
+- Commits con Conventional Commits.
+- Toda operación destructiva requiere confirmación explícita del usuario.
+- Antes de cerrar un cambio, correr las validaciones que el proyecto considere necesarias.
+
+## Flujo de trabajo
+
+Este repositorio usa el flujo spec-driven (OpenSpec) cuando corresponde:
+
+- Cambios nuevos o con scope incierto: artifacts en `openspec/changes/<name>/`
+- Cambios chicos y de riesgo bajo: implementación directa
+- Archivar con `openspec archive` cuando el cambio este completo
+
+## Herramientas
+
+- `ancleto` CLI para inicialización de proyectos y descubrimiento técnico.
+- `openspec` CLI para el ciclo de changes (proposal, specs, design, tasks, archive).

package/templates/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# Contributing
+
+Guía de contribución para este repositorio personal.
+
+## Flujo
+
+1. Crear rama de features: `feat/`, `fix/`, `chore/`
+2. Commits en formato Conventional Commits:
+   - `feat(scope): descripcion en presente`
+   - `fix(scope): descripcion en presente`
+   - `chore(scope): descripcion en presente`
+   - `docs(scope): ...`
+   - `refactor(scope): ...`
+   - `test(scope): ...`
+4. Abrir PR/merge request contra `main` con título semántico y plan de pruebas cuando aplique.
+5. No forzar push ni saltar hooks de validación.
+
+## Validaciones
+
+Correr antes de cerrar un cambio (según el proyecto):
+
+- `npm run typecheck` / `tsc --noEmit`
+- `npm run lint`
+- `npm test`
+- `npm run build`

package/templates/PRODUCT.md

@@ -0,0 +1,180 @@
+# Product Context - [Product Name]
+
+> **This file is EXTENSIBLE and will never be replaced by @ancleto/ai-tooling-framework**
+>
+> Fill in the sections according to your product/project. This file is read by AI agents (Claude, Cursor, etc.) to understand the specific context of your product.
+
+> **How to complete this file:** replace `[Product Name]` in the title and fill each section with your product's real values, deleting the example/placeholder text as you go. At a minimum, complete **Project Type**, **Tech Stack**, **Azure DevOps**, **AI Memory**, **Project Structure**, and **Project Commands** — agents rely on these to operate in your repo. The remaining sections are optional but recommended.
+
+## Project Type
+
+_Describe the project type: Web App, API, Library, Monorepo, etc._
+
+**Example:**
+
+- Web application with SSR
+- REST API with Node.js
+- Shared TypeScript library
+- Nx/Lerna monorepo
+
+---
+
+## Tech Stack
+
+_List the project's main technologies._
+
+**Base stack:**
+
+- **Runtime**: Node.js 20.x
+- **Language**: TypeScript
+- **Build**: Nx / Webpack / Vite (depending on the project)
+- **Testing**: Jest + Testing Library
+- **CI/CD**: Azure DevOps
+
+**Additional per project:**
+
+- Framework: React / Vue / Angular / Express
+- State: Redux / Context / Zustand
+- Styling: TailwindCSS / Sass / CSS-in-JS
+- Infra: AWS CDK / Serverless / Containers
+
+---
+
+## Azure DevOps
+
+_How this project retrieves work items and other Azure DevOps resources. AI agents read this to resolve cards._
+
+**Fill in for your project:**
+
+- **Organization URL**: https://dev.azure.com/your-org
+- **Team Project**: YourProject
+
+Keep the `Organization URL` value as a plain URL, on a line containing the words `Organization URL` — the fetch command below reads it from here with a `grep`.
+
+**Work items (card fetch):** via the `az` CLI (`azure-devops` extension), in a single call:
+
+```bash
+ORG=$(grep -Eim1 '\*\*(Organization URL|Organization)\*\*:' PRODUCT.md | grep -oE 'https?://[^ `"]+') && \
+az boards work-item show --id <id> --org "$ORG" --expand none --fields System.Id,System.Title,System.WorkItemType,System.TeamProject,System.State,System.Description,Microsoft.VSTS.Common.AcceptanceCriteria \
+ | sed 's/\\r\\n/\n/g; s/\\n/\n/g; s/<[^>]*>//g; s/&nbsp;/ /g; s/&quot;/"/g; s/&lt;/</g; s/&gt;/>/g; s/&amp;/\&/g' \
+ | fold -s -w 200
+```
+
+- **Required inputs**: `id` (card number) + `org`. Do NOT pass `--project` — it fails with `unrecognized arguments: --project`; the id is org-global and the project comes back as `System.TeamProject`.
+- **The organization is read from this file by the shell**, from the `Organization URL` line above — one substitution inside the same call, instead of an agent reading this whole file into its context.
+- **Always project with `--expand none --fields`**: the CLI defaults to `--expand all` and returns the entire work item. `--fields` without `--expand none` fails with `The expand parameter can not be used with the fields parameter`.
+- **`sed` + `fold` are not cosmetic**: `System.Description` arrives as a single HTML line that can exceed 70.000 characters, and the agent runtime truncates long lines at 2.000 — without them the agent silently receives a fraction of the description.
+- **Response fields used** (`.fields`): `System.Id`, `System.Title`, `System.Description`, `Microsoft.VSTS.Common.AcceptanceCriteria`, `System.WorkItemType`, `System.TeamProject`, `System.State`.
+- **Setup/auth**: requires `az extension add --name azure-devops`; `az login` (AAD) is enough — a PAT (`AZURE_DEVOPS_EXT_PAT`) only as a fallback.
+
+## AI Memory
+
+- **Repository App ID**: ancleto.YourProject
+
+`Repository App ID` identifies this repository in the shared mem0 store. Agents use it to isolate memories from other repositories. It must be unique to this repository, not shared across the Azure DevOps team project.
+
+`Team Project` from the Azure DevOps section is stored as `project_id` in mem0. Complete both `Repository App ID` and `Team Project` before using AI memory.
+
+---
+
+## Project Structure
+
+_Describe the project's main folder structure._
+
+**Example for a monorepo:**
+
+```
+libs/                    # Shared libraries
+apps/                    # Applications
+tools/                   # Build tools
+openspec/               # OpenSpec configuration
+  config.yaml           # Project context
+  changes/              # Active changes
+```
+
+**Example for a standalone app:**
+
+```
+src/
+  components/           # Reusable components
+  features/             # Business features
+  services/             # Services and APIs
+  utils/                # Utilities
+openspec/
+  config.yaml
+  changes/
+```
+
+---
+
+## Critical Files & Guardrails
+
+_Project-specific critical files or folders that require special care._
+
+**Take special care when modifying:**
+
+**Example:**
+
+- Code in `src/core/` (affects the whole app)
+- Routing configuration
+- Shared assets
+- Infrastructure (CDK, Terraform, etc.)
+
+**Avoid:**
+
+- Architecture changes without documenting them in OpenSpec
+- Introducing new dependencies without reviewing existing ones
+- Modifying established conventions without team consensus
+
+---
+
+## Project Commands
+
+_The project's most important npm/yarn/pnpm commands._
+
+**Example:**
+
+- `npm run dev` → Development server
+- `npm test` → Run tests
+- `npm run build` → Production build
+- `npm run lint` → Linter
+- `npm run deploy` → Deploy (per environment)
+
+---
+
+## Team Guidelines
+
+_Team-specific conventions, patterns, and guides._
+
+**You can add:**
+
+- Specific naming conventions
+- Preferred design patterns
+- Architecture guides
+- Links to internal documentation
+- Reference contacts
+
+---
+
+## Custom Commit Rules
+
+_Project-specific commit rules (in addition to the Conventional Commits convention defined in `CONTRIBUTING.md` and `AGENTS.md`)._
+
+**Example:**
+
+- Use a specific scope for modules: `feat(auth):`, `fix(payments):`
+- Include the ticket number in the commit: `feat(auth): add OAuth #JIRA-123`
+- Team-specific breaking-change format
+
+---
+
+## Custom Agent Configuration
+
+_Agent configuration specific to this project._
+
+**Example:**
+
+- Code style preferences
+- Patterns to follow/avoid
+- Custom workflows
+- Specific testing rules