@ancleto/spec 0.7.2 → 0.9.0

package/README.md

@@ -31,6 +31,8 @@
 - [Referencia de comandos CLI](#referencia-de-comandos-cli)
 - [Motor de memoria persistente](#motor-de-memoria-persistente)
 - [Comandos del ciclo SDD en tu IDE](#comandos-del-ciclo-sdd-en-tu-ide)
+- [Perfil de test automation](#perfil-de-test-automation)
+- [Portabilidad entre máquinas](#portabilidad-entre-máquinas)
 - [Azure DevOps (opcional)](#azure-devops-opcional)
 - [Referencia: agentes y modelos por tier](#referencia-agentes-y-modelos-por-tier)
 
@@ -74,6 +76,12 @@ Ancleto resuelve esto centralizando las reglas de negocio en un motor de memoria
 
 **Wizard interactivo** — Banner animado y menús navegables con flechas en `init` e `install`, sin librerías pesadas.
 
+**Hosts e IDEs (7)** — opencode, claude, vscode, antigravity, cursor, roo y copilot, cada uno con su layout nativo (Copilot: prompts en `.github/prompts` + MCP en `copilot-mcp.json`).
+
+**Perfil de test automation** — `--profile test`: tester ampliado (planning/generation/healing/coverage), comandos `cleto-test-*` y estructura `testspec/` para proyectos Playwright.
+
+**Portabilidad entre máquinas** — `ancleto export`/`import` mudan el proyecto regenerando el MCP local (`import --repair` repara rutas rotas sin bundle).
+
 ---
 
 ## Requisitos
@@ -138,24 +146,49 @@ del host (el CLI no deduplica ni elige un "ganador").
 | `opencode` (default) | `.opencode/skills/<n>/SKILL.md` | `.opencode/agents/<n>.md` | `.opencode/commands/<n>.md` |
 | `claude` | `.claude/skills/<n>/SKILL.md` | `.claude/agents/<n>.md` (adaptado) | `.claude/commands/<n>.md` |
 | `vscode` (VS Code / Copilot) | `.github/skills/<n>/SKILL.md` | `.github/agents/<n>.agent.md` | `.github/prompts/<n>.prompt.md` |
-| `antigravity` | `.agents/skills/<n>/SKILL.md` | — (no soportado) | — (no soportado) |
+| `antigravity` | `.agents/skills/<n>/SKILL.md` | `.agents/agents/<n>.md` (adaptado) | `.agents/skills/<n>/SKILL.md` (como skill) |
 | `cursor` | `.cursor/skills/<n>/SKILL.md` | — | — |
 | `roo` | `.roo/skills/<n>/SKILL.md` | — | — |
+| `copilot` | — | `.github/prompts/<n>.prompt.md` | `.github/prompts/<n>.prompt.md` |
 
 Cada host recibe sus skills en **su** directorio nativo. **`.agents/skills` es un punto de lectura
 compartido** —lo leen opencode, Cursor, VS Code y Antigravity—, no un destino universal: Claude lee
 `.claude/skills` y Roo, `.roo/skills`. Por eso el CLI no escribe todas las skills en `.agents/skills`.
 
-Los assets que un host no soporta (por ejemplo `agents`/`commands` de `antigravity`, `cursor` y `roo`)
+**Antigravity** no tiene directorio de commands de proyecto; sus `/cleto-*` se materializan como
+**command-skills** en `.agents/skills/<n>/SKILL.md` (los Workflows están deprecados a favor de Agent
+Skills), por eso `installedPaths.commands` queda vacío para este host. Sus `agents` se escriben en
+`.agents/agents/<n>.md` con el frontmatter adaptado: `name` inyectado, `tools` como **lista** de ids
+verificados de Antigravity (`read`→`view_file`, `edit`→`replace_file_content`, `grep`→`grep_search`,
+`bash`→`run_command`, `todowrite`→`manage_task`), `mode`→`mainAgent`/`subagent`,
+`commandExecutionPolicy: sandbox` y `model: inherit` (el tier no reescribe modelos de Antigravity). Una
+tool de opencode sin id verificado se **omite con aviso** (`skip tool '<k>': no verified Antigravity id
+for agent '<n>'`): un id inexistente cuelga el subagent. Los ids que sólo existen en el SDK
+(`find_file`, `edit_file`, `search_web`, `read_url_content`, …), los de comunidad (`write_to_file`,
+`call_mcp_tool`, `multi_replace_file_content`, …) y los de delegación (`invoke_subagent`,
+`start_subagent`, `define_subagent`) **no** se emiten; el uso de MCP se expresa por
+`mcpServers`/`.agents/mcp_config.json`, nunca como tool id. El campo `skill` no es una tool: se cubre
+con el surfaceo automático de skills de Antigravity.
+
+Los assets que un host no soporta (por ejemplo `agents`/`commands` de `cursor` y `roo`)
 **no se escriben** y el instalador avisa por `stderr`
-(`skip agents: not supported by host 'antigravity'`) sin abortar. La instalación es **aditiva y no
+(`skip agents: not supported by host 'cursor'`) sin abortar. La instalación es **aditiva y no
 destructiva**: instalar con otro agente escribe en su base y preserva los layouts previos, y el
 manifiesto `.ancletorc.installedPaths` acumula la unión de los destinos realmente escritos.
 
-La **configuración MCP específica de host** está fuera de alcance: el CLI no genera ni transforma
-`.mcp.json`, `mcp_config.json` ni `.vscode/mcp.json`, y no pisa config MCP preexistente. `claude` se
-soporta con adaptación de frontmatter obligatoria para `agents` (se omiten `model`/`tools` sin
-equivalencia verificada y las claves `mode`/`color`/`temperature`/`permission`), sin MCP propio.
+La **configuración MCP específica de host** está fuera de alcance con **una excepción**: para
+`agent: antigravity` el CLI genera o mergea (no destructivo) el MCP de workspace
+`.agents/mcp_config.json` con esquema `{ "mcpServers": { "<n>": { "command", "args", "env" } } }`,
+incluyendo el servidor de memoria `ancleto-memory`; preserva `mcpServers` preexistentes y no pisa
+homónimos. `.mcp.json` (Claude) y `.vscode/mcp.json` (VS Code) siguen fuera de alcance, al igual que el
+MCP global de Antigravity. `claude` se soporta con adaptación de frontmatter obligatoria para `agents`
+(se omiten `model`/`tools` sin equivalencia verificada y las claves
+`mode`/`color`/`temperature`/`permission`), sin MCP propio. **Copilot** instala agents y commands
+como prompt files en `.github/prompts/*.prompt.md` (mismo adapter, sin `model:`) y su MCP en
+`copilot-mcp.json` (merge en install, regeneración de rotas en upgrade, nunca toca tu
+`copilot-instructions.md`); el modelo lo elegís en el picker —el tier solo marca el nivel de
+esfuerzo—. Tanto `init` como `install --project`
+configuran el MCP del host en la misma ejecución; `--no-mcp` lo omite.
 
 ---
 
@@ -297,10 +330,10 @@ ancleto discovery         # Genera .discovery-map.json y empaqueta el repo
 ## Referencia de comandos CLI
 
 ```bash
-ancleto init [--agent <nombre>] [--tier <nivel>] [--lang <codigo>] [--exclude <globs>] [--with-azure]
+ancleto init [--agent <nombre>] [--tier <nivel>] [--lang <codigo>] [--exclude <globs>] [--with-azure] [--profile <perfil>]
                           # Configura el proyecto (interactivo en TTY)
 
-ancleto install [--project <dir>] [--tier <nivel>] [--agent <nombre>] [--lang <codigo>] [--exclude <globs>] [--no-mcp]
+ancleto install [--project <dir>] [--tier <nivel>] [--agent <nombre>] [--lang <codigo>] [--exclude <globs>] [--no-mcp] [--profile <perfil>]
                           # Instala agentes, skills y templates
 
 ancleto update            # Re-instala la última versión sobre lo existente
@@ -309,6 +342,13 @@ ancleto update            # Re-instala la última versión sobre lo existente
 
 ancleto upgrade           # Re-aplica templates y skills respetando tus personalizaciones
 
+ancleto export [--tar <archivo>]
+                          # Empaqueta lo portable del proyecto (bundle + manifest.json sin rutas)
+
+ancleto import <bundle> [--repair] | ancleto import --repair
+                          # Restaura el bundle regenerando el MCP local; --repair solo arregla
+                          # entradas con command inexistente
+
 ancleto check             # Verifica la integridad de la instalación (faltantes / huérfanos)
 
 ancleto specs check [--change <nombre>] [--json]
@@ -386,11 +426,43 @@ Una vez instalado, tu IDE expone el ciclo de vida completo como comandos barra:
 | `/cleto-ff` | Avanzar rápido con el contexto ya recuperado. |
 | `/cleto-apply` | Aplicar el código del change. |
 | `/cleto-verify` | Verificar reglas, tests y memoria antes de cerrar. |
+| `/cleto-security` | Realizar una auditoría de seguridad integral en el proyecto o change. |
 | `/cleto-sync` | Sincronizar las specs con el estado del repositorio. |
 | `/cleto-archive` | Archivar el change y registrar aprendizajes. |
 | `/cleto-continue` | Retomar un change con artefactos pendientes. |
 | `/cleto-explore` | Explorar un problema sin comprometerse a implementar. |
 | `/cleto-onboard` | Recorrer el ciclo completo en modo tutorial. |
+| `/cleto-bulk-archive` | Archivar varios changes juntos. |
+| `/cleto-recall` | Recuperar memoria del proyecto antes de empezar. |
+| `/cleto-transplant` | Mudar el proyecto entre máquinas (export/import). |
+
+Con perfil `test` se suman `cleto-test-proposal`, `cleto-test-apply`, `cleto-test-heal`, `cleto-test-coverage` y `cleto-test-archive` (ver perfil abajo).
+
+---
+
+## Perfil de test automation
+
+Para proyectos de test automation con Playwright:
+
+```bash
+ancleto init --profile test   # o: ancleto install --project . --profile test
+```
+
+Instala un tester ampliado con 4 workflows (planning, generation, healing, coverage), comandos `cleto-test-*`, estructura `testspec/specs` + `testspec/changes` (o reuso de `aspec/`) y convenciones Playwright en `AGENTS.md`. El orchestrator rutea lo test-only al tester ampliado y lo mixto al SDD general. Sin Playwright instalado, los workflows degradan a análisis y lo reportan. Combinable con cualquier host (`--profile test --agent copilot`, etc.).
+
+---
+
+## Portabilidad entre máquinas
+
+Al copiar un proyecto de una PC a otra, las rutas absolutas del MCP se rompen (caso real: Windows → Linux). Para mudarlo:
+
+```bash
+ancleto export --tar traslado.tgz   # en origen, antes de copiar
+ancleto import traslado.tgz         # en destino, regenera el MCP local + doctor
+ancleto import --repair             # sin bundle: repara entradas con command inexistente
+```
+
+El bundle lleva solo lo portable (manifiesto con intención MCP, sin rutas ni secretos: nunca incluye credenciales, `service.json`, global ni `memory.db`). El import no pisa entradas MCP sanas.
 
 ---
 

package/agents/orchestrator.md

@@ -234,6 +234,14 @@ Delegate directly to `@tester` when the request is limited to testing work such
 
 Do not use this category if the request is likely to require product-code changes, behavior changes, or broader requirement clarification.
 
+### Test profile routing (only when `.ancletorc` declares `profile: test`)
+
+When the project uses the test automation profile, refine the classification above:
+
+- Change is test-only (new/fixed coverage, no product-code change) → run the profile workflow: planning (`cleto-test-proposal`), generation (`cleto-test-apply`), healing (`cleto-test-heal`), coverage (`cleto-test-coverage`); delegate to the amplified `@tester`.
+- Change is mixed (product code + tests) → follow the general SDD paths above, with the amplified `@tester` owning the testing stages.
+- Testing changes live under `testspec/changes/` (or `aspec/changes/` when the project reuses aspec).
+
 ### 3. `direct-implementation`
 
 Skip `@spec-writer` and delegate directly to implementation when the request is limited to:

package/commands/cleto-security.md

@@ -0,0 +1,7 @@
+---
+description: Perform a comprehensive security audit of the codebase or a specific change
+---
+
+Invoke the `ancleto-security` skill with the Skill tool and follow it exactly; do not improvise steps.
+
+**Input**: The argument after `/cleto-security` is the optional target (e.g., a change name, a file path, or 'all'). If omitted, infer from context or ask the user.

package/commands/cleto-transplant.md

@@ -0,0 +1,30 @@
+---
+description: Move a project between machines via ancleto export/import
+---
+
+Mudá un proyecto ancleto entre máquinas sin romper el MCP local.
+
+**En la máquina origen** (antes de copiar el proyecto), parado en su raíz:
+
+```bash
+ancleto export --tar traslado.tgz
+```
+
+Llevá el proyecto + `traslado.tgz` a la máquina destino (cualquier medio: USB, red, nube).
+
+**En la máquina destino** (tras copiar el proyecto), parado en su raíz:
+
+```bash
+ancleto import traslado.tgz
+```
+
+Esto aplica los portables (`.ancletorc`, templates, `aspec/`, agents, commands, skills),
+regenera las entradas MCP con las rutas locales y corre `ancleto doctor` al final.
+
+Si no tenés bundle y el `opencode.json` apunta a rutas inexistentes:
+
+```bash
+ancleto import --repair
+```
+
+Nunca se exportan credenciales, tokens, `service.json`, la config global ni `memory.db`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ancleto/spec",
-  "version": "0.7.2",
+  "version": "0.9.0",
   "description": "Orquestador SDD liviano con subagentes optimizados para costo/tokens",
   "type": "module",
   "bin": {
@@ -12,6 +12,7 @@
     "commands",
     "skills",
     "templates",
+    "profiles",
     "src"
   ],
   "publishConfig": {

package/profiles/test/agents/reviewer.md

@@ -0,0 +1,35 @@
+---
+description: Reviews test automation work for correctness, conventions, and approved-scope compliance (test profile)
+mode: subagent
+model: opencode-go/qwen3.6-plus
+temperature: 0.1
+color: '#ef4444'
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: false
+---
+
+# Reviewer Agent (test automation profile)
+
+You perform a final review of test automation work for this project.
+
+Read `AGENTS.md` at the repo root for project-specific conventions, tech stack, and patterns.
+
+## Primary Responsibility
+
+Review testing work using one of these approved inputs:
+
+- An active testing change in `testspec/changes/{change-name}/` (or `aspec/changes/{change-name}/`)
+- A direct test-only request explicitly approved by `@orchestrator`
+
+## What to check
+
+- Every generated or healed test traces to an approved plan item or requirement; no orphan tests.
+- Playwright patterns match the repo conventions (selectors, fixtures, timeouts); no invented patterns when an established one exists.
+- Healing changed the smaller side: test updated for intentional behavior change, product code touched only within the approved scope — otherwise flag for `@orchestrator`.
+- The Validation Ledger classifies every command (`passed`, `task-regression`, `pre-existing-unrelated`, `inconclusive`); failures outside task-owned files are not dismissed as out of scope.
+- No production behavior change hides inside a "test-only" change.
+
+You do not have Bash and must not run commands. You do not write specs. Only raise flags so `@orchestrator` can decide.

package/profiles/test/agents/tester.md

@@ -0,0 +1,68 @@
+---
+description: Plans, generates, heals and covers Playwright automation tests (test profile)
+mode: subagent
+model: opencode-go/deepseek-v4.1-flash
+temperature: 0.1
+color: '#3b82f6'
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+permission:
+  bash:
+    '*': allow
+    '*az *': deny
+---
+
+# Tester Agent (test automation profile)
+
+You are the QA Automation Engineer for this project, running the **test automation profile**.
+Everything in the base tester contract applies (input modes, bash rules, verification
+priority, output expectations). This profile adds four test-automation workflows and
+Playwright conventions below.
+
+Read `AGENTS.md` at the repo root for project-specific testing conventions, frameworks, and patterns.
+
+## Playwright precondition
+
+Before any workflow that executes tests, check whether Playwright is available in the
+target project (`package.json` dependency or `playwright.config.*` at the repo root).
+
+- If present: run the workflows normally.
+- If absent: degrade with a clear message — deliver planning and coverage analysis
+  (no execution), and do NOT attempt healing or generation runs. Report the gap instead
+  of guessing.
+
+## Workflows
+
+### 1. planning
+
+Propose what to test: read the approved change artifacts (or the orchestrator brief),
+define the coverage target (critical flows, edge cases, regressions), and record it as
+a testing change under `testspec/changes/{name}/` (or `aspec/changes/{name}/` when the
+project reuses aspec). No test code yet.
+
+### 2. generation
+
+Generate Playwright tests from the approved testing plan. Follow the repo's existing
+test structure and patterns before introducing a new pattern. Each generated test maps
+to a plan item; untestable items are reported as gaps, not skipped silently.
+
+### 3. healing
+
+When a Playwright test fails: reproduce first, then diagnose (product bug vs stale
+test vs environment). Fix the smaller side — update the test when behavior changed
+intentionally, fix the product code only when the orchestrator scope allows it;
+otherwise escalate back to `@orchestrator` for reclassification. Re-run to green.
+
+### 4. coverage
+
+Report gaps between specs (source-of-truth and deltas) and existing tests: which
+requirements lack automation, which tests lack a backing requirement. Output a
+prioritized gap list, not new tests.
+
+## Output expectations (profile addition)
+
+Append to the base summary: workflow used (planning/generation/healing/coverage),
+Playwright availability, and the coverage gaps found (if any).

package/profiles/test/commands/cleto-test-apply.md

@@ -0,0 +1,10 @@
+---
+description: Generate Playwright tests from an approved testing plan
+---
+
+You are running the test-automation **generation** workflow under the test profile.
+
+1. Load the approved testing plan (`testspec/changes/{name}/` or the aspec change).
+2. Verify the Playwright precondition; if absent, stop and report instead of generating runnable tests.
+3. Generate one Playwright test per plan item using the repo's existing patterns. Map each test to its item.
+4. Report untestable items as gaps (never skip silently) and hand the new tests to validation (healing/coverage as needed).

package/profiles/test/commands/cleto-test-archive.md

@@ -0,0 +1,9 @@
+---
+description: Archive a finished testing change
+---
+
+You are running the test-automation **archive** workflow under the test profile.
+
+1. Verify the testing change is complete: plan approved, tests generated, suite green (or gaps explicitly accepted).
+2. Confirm the delta specs reflect the final tests (re-delegate updates when behavior changed mid-flight).
+3. Archive per the project's SDD close process (same rules as `cleto-archive`), keeping `testspec/` deltas consistent.

package/profiles/test/commands/cleto-test-coverage.md

@@ -0,0 +1,10 @@
+---
+description: Report gaps between specs and existing automation
+---
+
+You are running the test-automation **coverage** workflow under the test profile.
+
+1. Read the source-of-truth specs (`testspec/specs/` or `aspec/specs/`) plus active deltas.
+2. Map each requirement to the existing Playwright tests (no execution needed — static analysis suffices).
+3. Output a prioritized gap list: requirements without automation, tests without a backing requirement.
+4. Do not write new tests here; propose them via `cleto-test-proposal` when asked.

package/profiles/test/commands/cleto-test-heal.md

@@ -0,0 +1,10 @@
+---
+description: Diagnose and repair a failing Playwright test
+---
+
+You are running the test-automation **healing** workflow under the test profile.
+
+1. Reproduce the failure first (run the single failing test, not the whole suite).
+2. Diagnose: product bug vs stale test vs environment issue.
+3. Fix the smaller side: update the test when the behavior change was intentional; touch product code only within the orchestrator-approved scope, otherwise escalate to `@orchestrator` for reclassification.
+4. Re-run to green and report cause, side fixed, and commands run.

package/profiles/test/commands/cleto-test-proposal.md

@@ -0,0 +1,10 @@
+---
+description: Propose what to automate (test planning) as a testing change
+---
+
+You are running the test-automation **planning** workflow under the test profile.
+
+1. Read the approved change artifacts (or the orchestrator brief) and the current Playwright suite layout.
+2. Define the coverage target: critical flows, edge cases, regressions.
+3. Check the Playwright precondition (`package.json` / `playwright.config.*`): if absent, plan analysis-only and say so.
+4. Record the plan as a testing change under `testspec/changes/{name}/` (proposal + tasks; reuse `aspec/changes/{name}/` when the project reuses aspec). STOP and wait for approval before generating tests.

package/profiles/test/templates/AGENTS.md

@@ -0,0 +1,14 @@
+# AI Agents Context (test automation profile)
+
+> Contexto global para agentes de IA en proyectos con perfil de test automation.
+
+<!-- LOCKED: test-profile -->
+### Test automation profile (Playwright)
+
+Este proyecto usa el perfil `test` de ancleto (`profile: test` en `.ancletorc`).
+
+- Workflows: planning (`cleto-test-proposal`), generation (`cleto-test-apply`), healing (`cleto-test-heal`), coverage (`cleto-test-coverage`), archive (`cleto-test-archive`).
+- Estructura: `testspec/specs/` (cobertura actual) + `testspec/changes/` (deltas), o reuso de `aspec/` cuando el proyecto ya lo usa.
+- Framework: Playwright. Si no está instalado, los workflows degradan a análisis sin ejecución y lo reportan.
+- Ruteo: cambio test-only → tester ampliado; cambio mixto → SDD general con apoyo del tester.
+<!-- /LOCKED: test-profile -->

package/skills/ancleto-security/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: ancleto-security
+description: Perform a comprehensive security audit of the codebase or a specific change. Checks for common vulnerabilities like SQL injection, XSS, hardcoded secrets, etc.
+license: MIT
+compatibility: No external binaries required. Works with any agent runtime.
+metadata:
+  author: ancleto
+  version: '1.0'
+---
+
+# aspec Security Audit
+
+Perform a comprehensive security audit of the project.
+
+**Input**: Optionally a change name or directory (e.g., `add-auth`, `src/`); if omitted, infer from context.
+
+## Steps
+
+### 1. Identify the Scope
+Determine if the user wants to review a specific file, recent changes, or the whole project. 
+
+### 2. Basic Static Analysis
+Run existing built-in static analysis tools (e.g., `npm run lint`) to catch obvious security issues caught by linters.
+
+### 3. Agent Manual Review
+Actively search for vulnerabilities in the target scope using file viewing and grep tools. Look for:
+- **SQL Injections:** Check for concatenated queries instead of parameterized ones.
+- **XSS (Cross-Site Scripting):** Review how user inputs are rendered in views.
+- **Hardcoded Secrets:** Look for passwords, API tokens, or encryption keys in source code.
+- **Command Injection:** Review usage of `exec`, `spawn`, or similar functions with unsanitized user input.
+- **Path Traversal:** Check manipulation of file paths with user input.
+
+### 4. Create Audit Report
+Generate an artifact named `security_audit_report.md` detailing the findings:
+- Classify by severity: Critical, High, Medium, Low.
+- Show exactly in which file and line the issue occurs.
+- Propose a remediation or corrected code.
+
+### 5. Action Plan
+Present the report to the user and offer to apply the security fixes.