create-harness-btp 0.1.1 → 0.2.0

package/README.md

@@ -1,13 +1,13 @@
 # harness-btp
 
-[![version](https://img.shields.io/badge/version-v0.1.0-blue)](https://github.com/horangelmillan/harness-btp/releases/tag/v0.1.0)
+[![version](https://img.shields.io/badge/version-v0.2.0-blue)](https://github.com/horangelmillan/harness-btp/releases/tag/v0.2.0)
 [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
-[![platform](https://img.shields.io/badge/platform-windows%20%7C%20linux-lightgrey)](https://github.com/horangelmillan/harness-btp)
-[![opencode](https://img.shields.io/badge/agent-OpenCode-purple)](https://opencode.ai)
+[![platform](https://img.shields.io/badge/platform-windows%20%7C%20linux%20%7C%20macos-lightgrey)](https://github.com/horangelmillan/harness-btp)
+[![agent](https://img.shields.io/badge/agent-any%20AGENTS.md--compatible-purple)](https://github.com/horangelmillan/harness-btp)
 
-Reglas, agentes y scripts reutilizables para llevar un MVP SAP de la especificación al despliegue en Cloud Foundry con OpenCode.
+Reglas, agentes y scripts reutilizables para llevar un MVP SAP de la especificación al despliegue en Cloud Foundry, con cualquier cliente agéntico que lea `AGENTS.md`.
 
-Para quien construye MVPs SAP BTP en equipo Windows con OpenCode y quiere empezar cada proyecto con el mismo flujo probado, sin copiar y pegar.
+Para quien construye MVPs SAP BTP y quiere empezar cada proyecto con el mismo flujo probado, sin copiar y pegar. Funciona en Windows, Linux y macOS, con OpenCode, Claude Code o cualquier otro cliente que lea `AGENTS.md` y ejecute scripts del proyecto.
 
 ## Contenidos
 
@@ -16,6 +16,7 @@ Para quien construye MVPs SAP BTP en equipo Windows con OpenCode y quiere empeza
 - [Quickstart](#quickstart)
 - [Instalación](#instalación)
 - [Actualizar y desinstalar](#actualizar-y-desinstalar)
+- [Adaptadores opcionales](#adaptadores-opcionales)
 - [Estructura del repo](#estructura-del-repo)
 - [Cómo lo descubre el agente](#cómo-lo-descubre-el-agente)
 - [Troubleshooting](#troubleshooting)
@@ -27,71 +28,101 @@ Para quien construye MVPs SAP BTP en equipo Windows con OpenCode y quiere empeza
 ## Features
 
 - **Carpeta `AI/` sin envolver:** se instala dentro de tu proyecto (nuevo o existente) sin mover ni renombrar nada de lo que ya tienes.
-- **Idempotente con `SKIP` / `-Force` + backup:** repetir la instalación no pisa nada; solo reemplaza con `-Force` y guarda copia en `AI.bak`.
+- **Idempotente con `SKIP` / `-Force` + backup:** repetir la instalación no pisa nada; solo reemplaza con `-Force` (`.ps1`) o `--force` (`.sh`) y guarda copia en `AI.bak`.
 - **Sin secretos:** el repo no contiene credenciales, tokens ni rutas de máquina; solo nombres y placeholders por paisaje.
 - **Tres formas de instalar:** `degit`, `git clone` o `pnpm dlx`, todas ancladas a un tag versionado.
 - **Versionado por tags:** cada versión es un tag `vX.Y.Z`; actualizar es repetir el comando contra el tag nuevo.
-- **El agente se adapta solo:** deja un puntero `AGENTS.md` en la raíz y OpenCode encuentra `AI/AGENTS.md`, `INICIO.md`, agentes, skills y plantilla de spec.
+- **Instaladores pares:** `install.ps1` (PowerShell) e `install.sh` (bash/sh) con la misma lógica (`SKIP` / `CREATE` / `BACKUP` / `OK`). Elige el de tu shell.
+- **Agnóstico al cliente:** el núcleo es Markdown + shell (`AI/AGENTS.md`, `AI/INICIO.md`, `AI/docs/`, `AI/scripts/`). `AI/.opencode/` y `AI/opencode.fragment.jsonc` son adaptadores opcionales de ejemplo, no requisitos (ver [Adaptadores opcionales](#adaptadores-opcionales)).
+- **El agente se adapta solo:** deja un puntero `AGENTS.md` en la raíz y el cliente encuentra `AI/AGENTS.md`, `INICIO.md`, agentes, skills y plantilla de spec.
 
 ## Requisitos
 
 | Necesitas | Versión | Para qué |
 |---|---|---|
-| Windows PowerShell 5.1 / bash | incluido en el SO | ejecutar `install.ps1` / `install.sh` |
+| PowerShell 5.1+ o bash/sh | incluido en el SO | ejecutar `install.ps1` / `install.sh` |
 | Node.js 18+ | solo si usas `degit` o `pnpm dlx` | descargar e instalar el harness |
 | `gh` (opcional) | cualquiera reciente | clonar repo privado o crear PRs |
-| OpenCode | cualquiera reciente | leer `AGENTS.md` y orquestar el flujo |
+| Cliente agéntico | cualquiera reciente que lea `AGENTS.md` (OpenCode, Claude Code, etc.) | leer `AGENTS.md` y orquestar el flujo |
 
 > Sin Node también puedes instalar vía `git clone`, que no lo necesita.
 
 ## Quickstart
 
-El camino de 30 segundos en un proyecto nuevo (Windows, recomendado):
+El camino de 30 segundos en un proyecto nuevo. Elige tu shell:
+
+PowerShell (Windows):
 
 ```powershell
-npx -p degit degit horangelmillan/harness-btp#v0.1.0 AI-tmp -- AI-tmp
+npx -p degit degit horangelmillan/harness-btp#v0.2.0 AI-tmp -- AI-tmp
 powershell -ExecutionPolicy Bypass -File AI-tmp/install.ps1 -Dest .
 Remove-Item -Recurse -Force AI-tmp
 ```
 
-Eso es todo. Abre el proyecto en OpenCode y el agente ya sabe qué hacer: lee `AGENTS.md` → `AI/AGENTS.md` → `AI/INICIO.md`.
+bash (Linux, macOS o Git Bash):
 
-## Instalación
+```bash
+npx -p degit degit horangelmillan/harness-btp#v0.2.0 AI-tmp -- AI-tmp
+sh AI-tmp/install.sh --dest .
+rm -rf AI-tmp
+```
 
-> En Linux/macOS sustituye `install.ps1 -Dest .` por `install.sh --dest .` en todos los ejemplos.
+Eso es todo. Abre el proyecto en tu cliente agéntico y el agente ya sabe qué hacer: lee `AGENTS.md` → `AI/AGENTS.md` → `AI/INICIO.md`.
+
+## Instalación
 
 ### Opción 1 — degit (recomendado)
 
 Descarga solo lo necesario, sin historial git:
 
+PowerShell:
+
 ```powershell
-npx -p degit degit horangelmillan/harness-btp#v0.1.0 AI-tmp -- AI-tmp
+npx -p degit degit horangelmillan/harness-btp#v0.2.0 AI-tmp -- AI-tmp
 powershell -ExecutionPolicy Bypass -File AI-tmp/install.ps1 -Dest .
 Remove-Item -Recurse -Force AI-tmp
 ```
 
+bash:
+
+```bash
+npx -p degit degit horangelmillan/harness-btp#v0.2.0 AI-tmp -- AI-tmp
+sh AI-tmp/install.sh --dest .
+rm -rf AI-tmp
+```
+
 ### Opción 2 — git clone
 
 Clon superficial anclado al tag:
 
+PowerShell:
+
 ```powershell
-git clone --branch v0.1.0 --depth 1 https://github.com/horangelmillan/harness-btp AI-tmp
+git clone --branch v0.2.0 --depth 1 https://github.com/horangelmillan/harness-btp AI-tmp
 powershell -ExecutionPolicy Bypass -File AI-tmp/install.ps1 -Dest .
 Remove-Item -Recurse -Force AI-tmp
 ```
 
+bash:
+
+```bash
+git clone --branch v0.2.0 --depth 1 https://github.com/horangelmillan/harness-btp AI-tmp
+sh AI-tmp/install.sh --dest .
+rm -rf AI-tmp
+```
+
 ### Opción 3 — pnpm dlx
 
-Sin descargas manuales (requiere publicar `create-harness-btp` en el registry):
+Sin descargas manuales (requiere publicar `create-harness-btp` en el registry). Igual en todos los SO:
 
-```powershell
+```bash
 pnpm dlx create-harness-btp --dest .
 ```
 
 ### Qué hace el instalador
 
-- `CREATE: AI/` o `SKIP: AI/ ya existe` (solo lo reemplaza con `-Force`, con backup a `AI.bak`).
-- `CREATE: AGENTS.md` o `SKIP: AGENTS.md ya existe` (tu `AGENTS.md` propio se conserva; con `-Force` se respalda a `AGENTS.md.bak`).
+- `CREATE: AI/` o `SKIP: AI/ ya existe` (solo lo reemplaza con `-Force` / `--force`, con backup a `AI.bak`).
+- `CREATE: AGENTS.md` o `SKIP: AGENTS.md ya existe` (tu `AGENTS.md` propio se conserva; con `-Force` / `--force` se respalda a `AGENTS.md.bak`).
 - Fusiona `.gitignore`: añade las líneas que falten, sin duplicar ni borrar las tuyas.
 - **No toca** `package.json` ni `mta.yaml` de tu proyecto, nunca.
 
@@ -100,12 +131,14 @@ Salida típica en proyecto nuevo:
 ```text
 CREATE: AI/
 CREATE: AGENTS.md
-OK: harness v0.1.0 instalado
+OK: harness v0.2.0 instalado
 ```
 
 ## Actualizar y desinstalar
 
-**Actualizar:** repite el mismo comando de instalación contra el tag nuevo. Sin `-Force` lo existente se conserva (`SKIP:`); con `-Force` se reemplaza con backup:
+**Actualizar:** repite el mismo comando de instalación contra el tag nuevo. Sin `-Force` / `--force` lo existente se conserva (`SKIP:`); con fuerza se reemplaza con backup:
+
+PowerShell:
 
 ```powershell
 npx -p degit degit horangelmillan/harness-btp#v0.2.0 AI-tmp -- AI-tmp
@@ -114,15 +147,43 @@ Remove-Item -Recurse -Force AI-tmp
 # tu versión anterior queda en AI.bak por si quieres comparar
 ```
 
+bash:
+
+```bash
+npx -p degit degit horangelmillan/harness-btp#v0.2.0 AI-tmp -- AI-tmp
+sh AI-tmp/install.sh --dest . --force
+rm -rf AI-tmp
+# tu versión anterior queda en AI.bak por si quieres comparar
+```
+
 **Desinstalar:** borra la carpeta y el puntero. No deja servicios ni hooks:
 
+PowerShell:
+
 ```powershell
 Remove-Item -Recurse -Force AI
 Remove-Item -Force AGENTS.md  # solo si es el puntero al harness
 ```
 
+bash:
+
+```bash
+rm -rf AI
+rm -f AGENTS.md  # solo si es el puntero al harness
+```
+
 > Si tu `AGENTS.md` tenía contenido propio antes del harness, el instalador lo respaldó en `AGENTS.md.bak`: restáuralo en vez de borrarlo.
 
+## Adaptadores opcionales
+
+El harness funciona con **cualquier** cliente agéntico que lea `AGENTS.md`. Estos archivos son ayudas para un cliente concreto, no requisitos:
+
+- **`AI/.opencode/`** — agentes, comandos y skills de ejemplo con el layout de OpenCode. Si tu cliente usa otro layout, ignóralos o adaptalos: el flujo vive en `AI/AGENTS.md`, `AI/INICIO.md`, `AI/docs/` y `AI/scripts/`, que son Markdown + shell portátil.
+- **`AI/opencode.fragment.jsonc`** — fragmento de ejemplo para fusionar en tu `opencode.jsonc` (p. ej. el bloque MCP `graphify-code`, deshabilitado por defecto). Solo aplica a OpenCode; otros clientes lo ignoran sin efecto.
+- **`install.ps1` / `install.sh`** — elige el de tu shell; ambos aplican la misma lógica idempotente. Los scripts de `AI/scripts/` también vienen en par `.ps1` / `.sh`.
+
+Nada del núcleo exige OpenCode, Windows ni ningún modelo concreto.
+
 ## Estructura del repo
 
 ```text
@@ -130,9 +191,9 @@ harness-btp/
 ├── AI/                        # lo que queda instalado en tu proyecto
 │   ├── AGENTS.md              # reglas del harness (parametrizado, sin rutas absolutas)
 │   ├── INICIO.md              # punto de entrada para el agente
-│   ├── opencode.fragment.jsonc# fragmento relativo para tu opencode.jsonc
-│   ├── .opencode/             # 11 agents + 2 commands + 4 skills
-│   ├── scripts/               # 5 scripts .ps1 + provision-espacio.template.ps1
+│   ├── opencode.fragment.jsonc# ADAPTER opcional: ejemplo para opencode.jsonc
+│   ├── .opencode/             # ADAPTER opcional: agents + commands + skills de ejemplo
+│   ├── scripts/               # pares .ps1 / .sh + provision-espacio.template.ps1
 │   ├── docs/                  # flujo-etapas, cf-safe, habilitacion-trial
 │   ├── specs/                 # plantilla _template.md
 │   └── .gitignore.fragment    # líneas a fusionar en tu .gitignore
@@ -141,15 +202,15 @@ harness-btp/
 ├── install.ps1 / install.sh   # instaladores idempotentes (SKIP / CREATE / BACKUP / OK)
 ├── bin/                       # ejecutable de create-harness-btp (pnpm dlx)
 ├── package.json               # name create-harness-btp
-└── VERSION                    # 0.1.0
+└── VERSION                    # 0.2.0
 ```
 
 ## Cómo lo descubre el agente
 
-1. OpenCode abre tu proyecto y lee `AGENTS.md` en la raíz (el puntero que deja el instalador).
-2. El puntero lo lleva a `AI/AGENTS.md`: reglas, herramientas (`sap_cf`, `mbt`) y presupuestos.
-3. Desde ahí sigue a `AI/INICIO.md` para el flujo por etapas (`/flow`), descubre agentes en `.opencode/`, skills y scripts, y usa `AI/specs/_template.md` para nuevas especificaciones.
-4. Antes del primer despliegue adapta los dos placeholders a tu máquina y destino (ver `AI/INICIO.md`).
+1. Tu cliente agéntico abre el proyecto y lee `AGENTS.md` en la raíz (el puntero que deja el instalador).
+2. El puntero lo lleva a `AI/AGENTS.md`: reglas, herramientas (`cf`, `mbt`) y presupuestos.
+3. Desde ahí sigue a `AI/INICIO.md` para el flujo por etapas (`/flow`), descubre los agentes de ejemplo en `.opencode/`, skills y scripts, y usa `AI/specs/_template.md` para nuevas especificaciones.
+4. Antes del primer despliegue adapta los dos placeholders a tu destino (ver `AI/INICIO.md`).
 
 Tú no configuras nada: el agente se adapta solo.
 
@@ -157,17 +218,24 @@ Tú no configuras nada: el agente se adapta solo.
 
 | Problema | Causa | Comando |
 |---|---|---|
-| `SKIP: AI/ ya existe` y quería actualizar | reinstalación sin `-Force` conserva lo existente | repite con `-Force` (guarda `AI.bak`) |
-| Mi `AGENTS.md` propio desapareció | se instaló con `-Force` | recupera `AGENTS.md.bak` |
+| `SKIP: AI/ ya existe` y quería actualizar | reinstalación sin fuerza conserva lo existente | repite con `-Force` (`.ps1`) o `--force` (`.sh`); guarda `AI.bak` |
+| Mi `AGENTS.md` propio desapareció | se instaló con fuerza | recupera `AGENTS.md.bak` |
 | Líneas duplicadas en `.gitignore` | edición manual tras la fusión | el instalador fusiona sin duplicar; borra el duplicado a mano |
-| `ExecutionPolicy` bloquea `install.ps1` | política de PowerShell | `powershell -ExecutionPolicy Bypass -File AI-tmp/install.ps1 -Dest .` |
-| `degit` falla sin Node | `degit` corre sobre Node 18+ | instala Node o usa `git clone --branch v0.1.0` |
+| `ExecutionPolicy` bloquea `install.ps1` | política de PowerShell | `powershell -ExecutionPolicy Bypass -File AI-tmp/install.ps1 -Dest .` (o usa `install.sh` en Git Bash) |
+| `ABORT: opción desconocida` en `install.sh` | flag inexistente | `sh install.sh --help` lista `--dest`, `--force` |
+| `degit` falla sin Node | `degit` corre sobre Node 18+ | instala Node o usa `git clone --branch v0.2.0` |
+| Tu cliente no lee los agentes de `.opencode/` | layout específico de OpenCode | son un adapter opcional; el flujo está en `AI/AGENTS.md` + `AI/INICIO.md` |
 
 ## Compatibilidad
 
-- Windows 10/11 + PowerShell 5.1 verificado.
-- Linux/macOS vía `install.sh` (mismo comportamiento `SKIP` / `--force` + backup).
-- OpenCode como orquestador del flujo.
+Matriz honesta cliente × SO (`verificado` = probado con evidencia; `esperado` = sin bloqueo conocido, pendiente de evidencia):
+
+| Cliente agéntico | Windows | Linux | macOS |
+|---|---|---|---|
+| OpenCode | verificado | esperado (`install.sh` par verificado en Git Bash) | esperado |
+| Claude Code, otros que lean `AGENTS.md` | esperado | esperado | esperado |
+
+- Instaladores y `check-prereqs` / `check-docs` verificados en Windows (`.ps1` nativo, `.sh` vía Git Bash, paridad CREATE/SKIP/BACKUP/OK + mismos `exit`).
 - SAP BTP Cloud Foundry solo cuando el MVP lo pida: el harness no crea cuentas ni espacios por sí solo.
 
 ## Contribuir
@@ -182,4 +250,4 @@ MIT. Haz lo que quieras con el harness; sin garantía.
 
 ## Changelog
 
-- **v0.1.0** — versión inicial: carpeta `AI/` parametrizada, instaladores idempotentes `install.ps1` / `install.sh`, `create-harness-btp` vía `pnpm dlx`, plantilla de puntero, docs de flujo / cf-safe / habilitación trial, plantilla de spec.
+- **v0.2.0** — versión inicial: carpeta `AI/` parametrizada, instaladores idempotentes `install.ps1` / `install.sh`, `create-harness-btp` vía `pnpm dlx`, plantilla de puntero, docs de flujo / cf-safe / habilitación trial, plantilla de spec.

package/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.0

package/install.ps1

@@ -58,3 +58,9 @@ if (Test-Path $GiDst) {
 }
 
 Write-Output "OK: harness instalado en $Dest (package.json y mta.yaml intactos)"
+
+# Verificación de prerrequisitos en modo aviso (no bloquea la instalación).
+try {
+  $Check = Join-Path $AiSrc "scripts\check-prereqs.ps1"
+  if (Test-Path $Check) { & $Check -WarnOnly }
+} catch { Write-Output "AVISO: no se pudo ejecutar check-prereqs.ps1 (ver AI/docs/prerequisitos.md)" }

package/install.sh

@@ -1,6 +1,6 @@
 #!/bin/sh
 # Instalador del harness BTP (idempotente, POSIX sh).
-# Uso: ./install.sh [--dest .] [--force]
+# Uso: ./install.sh [--dest <dir>] [--force] [--help]
 # Sin secretos. No toca package.json ni mta.yaml del proyecto.
 DEST="."
 FORCE=0
@@ -8,7 +8,13 @@ while [ $# -gt 0 ]; do
   case "$1" in
     --dest) DEST="$2"; shift 2 ;;
     --force) FORCE=1; shift ;;
-    *) echo "ABORT: opción desconocida $1"; exit 1 ;;
+    -h|--help)
+      echo "Uso: ./install.sh [--dest <dir>] [--force] [--help]"
+      echo "  --dest <dir>  proyecto destino (por defecto: .)"
+      echo "  --force       reinstala AI/ con backup a AI.bak"
+      echo "  -h, --help    muestra esta ayuda"
+      exit 0 ;;
+    *) echo "ABORT: opción desconocida $1 (usa --help)"; exit 1 ;;
   esac
 done
 SRC="$(cd "$(dirname "$0")" && pwd)"
@@ -46,3 +52,10 @@ if [ "$ADDED" -eq 0 ]; then echo "SKIP: .gitignore ya contiene el fragmento"
 else echo "CREATE: .gitignore (+$ADDED líneas)"; fi
 
 echo "OK: harness instalado en $DEST (package.json y mta.yaml intactos)"
+
+# Verificación de prerrequisitos en modo aviso (no bloquea la instalación).
+if [ -f "$SRC/AI/scripts/check-prereqs.sh" ]; then
+  sh "$SRC/AI/scripts/check-prereqs.sh" --warn-only || true
+else
+  echo "AVISO: no se encontró check-prereqs.sh (ver AI/docs/prerequisitos.md)"
+fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-harness-btp",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Instala el harness MVP SAP BTP como carpeta AI/ en cualquier proyecto",
   "keywords": ["sap-btp", "opencode", "harness", "agents", "scaffolder", "create"],
   "homepage": "https://github.com/horangelmillan/harness-btp#readme",

package/AI/.opencode/skills/sap-cf-cli/SKILL.md

@@ -1,41 +0,0 @@
----
-name: sap-cf-cli
-description: Uso seguro del CLI de Cloud Foundry como sap_cf en Windows
----
-
-# CLI Cloud Foundry (`sap_cf`)
-
-En [TU_PC] `cf` es el CLI de **Cloudflare**. Cloud Foundry se invoca
-**siempre** como `sap_cf` (`sap_cf.cmd`, ruta de instalación de
-Cloud Foundry CLI en [TU_PC]; verificado en Windows, adapta rutas).
-
-## Lectura segura (sin secretos)
-
-```
-sap_cf target          # endpoint / org / espacio actuales
-sap_cf api             # endpoint y versión API
-sap_cf orgs            # solo nombres
-sap_cf spaces          # solo nombres
-sap_cf apps            # estado observable (started/stopped, rutas)
-sap_cf services        # instancias visibles
-sap_cf logs <app> --recent
-```
-
-`target`, `api`, `orgs`, `spaces` y `app <nombre>` nunca muestran tokens.
-Si una salida incluyera un secreto, redáctalo antes de citarla.
-
-## Mutaciones (solo `deploy-cf`, con destino confirmado)
-
-- Confirmar endpoint/org/espacio contra la spec **antes** de cada despliegue.
-- `sap_cf push` para apps simples; `sap_cf deploy <archivo>.mtar` para MTA
-  (requiere plugin `multiapps`, no instalado: ver skill `mta-build`).
-- Verificar después: `sap_cf apps` + `sap_cf logs <app> --recent` + URL.
-
-## Denylist
-
-- `cf ...` para cualquier operación Foundry.
-- Borrar o renombrar orgs, espacios, apps o servicios fuera del MVP.
-- `sap_cf login`/re-autenticaciones no solicitadas (si la sesión caduca,
-  pedir al usuario el flujo interactivo, nunca credenciales en texto).
-- `--var`/`--vars-file` con secretos en shell compartida; usar archivos ya
-  ignorados por Git y no citar sus valores.