create-harness-btp 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/AI/VERSION +1 -1
  2. package/README.md +47 -15
  3. package/VERSION +1 -1
  4. package/package.json +1 -1
package/AI/VERSION CHANGED
@@ -1 +1 @@
1
- 0.3.0
1
+ 0.3.1
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # harness-btp
2
2
 
3
- [![version](https://img.shields.io/badge/version-v0.3.0-blue)](https://github.com/horangelmillan/harness-btp/releases/tag/v0.3.0)
3
+ [![version](https://img.shields.io/badge/version-v0.3.1-blue)](https://github.com/horangelmillan/harness-btp/releases/tag/v0.3.1)
4
4
  [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
5
5
  [![platform](https://img.shields.io/badge/platform-windows%20%7C%20linux%20%7C%20macos-lightgrey)](https://github.com/horangelmillan/harness-btp)
6
6
  [![agent](https://img.shields.io/badge/agent-any%20AGENTS.md--compatible-purple)](https://github.com/horangelmillan/harness-btp)
@@ -16,6 +16,7 @@ Para quien construye MVPs SAP BTP y quiere empezar cada proyecto con el mismo fl
16
16
  - [Quickstart](#quickstart)
17
17
  - [Instalación](#instalación)
18
18
  - [Instalación asistida por agente](#instalación-asistida-por-agente)
19
+ - [Manual de uso](#manual-de-uso)
19
20
  - [Actualizar y desinstalar](#actualizar-y-desinstalar)
20
21
  - [Adaptadores opcionales](#adaptadores-opcionales)
21
22
  - [Multi-cliente](#multi-cliente)
@@ -56,7 +57,7 @@ El camino de 30 segundos en un proyecto nuevo. Elige tu shell:
56
57
  PowerShell (Windows):
57
58
 
58
59
  ```powershell
59
- npx -p degit degit horangelmillan/harness-btp#v0.3.0 AI-tmp -- AI-tmp
60
+ npx -p degit degit horangelmillan/harness-btp#v0.3.1 AI-tmp -- AI-tmp
60
61
  powershell -ExecutionPolicy Bypass -File AI-tmp/install.ps1 -Dest .
61
62
  Remove-Item -Recurse -Force AI-tmp
62
63
  ```
@@ -64,7 +65,7 @@ Remove-Item -Recurse -Force AI-tmp
64
65
  bash (Linux, macOS o Git Bash):
65
66
 
66
67
  ```bash
67
- npx -p degit degit horangelmillan/harness-btp#v0.3.0 AI-tmp -- AI-tmp
68
+ npx -p degit degit horangelmillan/harness-btp#v0.3.1 AI-tmp -- AI-tmp
68
69
  sh AI-tmp/install.sh --dest .
69
70
  rm -rf AI-tmp
70
71
  ```
@@ -80,7 +81,7 @@ Descarga solo lo necesario, sin historial git:
80
81
  PowerShell:
81
82
 
82
83
  ```powershell
83
- npx -p degit degit horangelmillan/harness-btp#v0.3.0 AI-tmp -- AI-tmp
84
+ npx -p degit degit horangelmillan/harness-btp#v0.3.1 AI-tmp -- AI-tmp
84
85
  powershell -ExecutionPolicy Bypass -File AI-tmp/install.ps1 -Dest .
85
86
  Remove-Item -Recurse -Force AI-tmp
86
87
  ```
@@ -88,7 +89,7 @@ Remove-Item -Recurse -Force AI-tmp
88
89
  bash:
89
90
 
90
91
  ```bash
91
- npx -p degit degit horangelmillan/harness-btp#v0.3.0 AI-tmp -- AI-tmp
92
+ npx -p degit degit horangelmillan/harness-btp#v0.3.1 AI-tmp -- AI-tmp
92
93
  sh AI-tmp/install.sh --dest .
93
94
  rm -rf AI-tmp
94
95
  ```
@@ -100,7 +101,7 @@ Clon superficial anclado al tag:
100
101
  PowerShell:
101
102
 
102
103
  ```powershell
103
- git clone --branch v0.3.0 --depth 1 https://github.com/horangelmillan/harness-btp AI-tmp
104
+ git clone --branch v0.3.1 --depth 1 https://github.com/horangelmillan/harness-btp AI-tmp
104
105
  powershell -ExecutionPolicy Bypass -File AI-tmp/install.ps1 -Dest .
105
106
  Remove-Item -Recurse -Force AI-tmp
106
107
  ```
@@ -108,7 +109,7 @@ Remove-Item -Recurse -Force AI-tmp
108
109
  bash:
109
110
 
110
111
  ```bash
111
- git clone --branch v0.3.0 --depth 1 https://github.com/horangelmillan/harness-btp AI-tmp
112
+ git clone --branch v0.3.1 --depth 1 https://github.com/horangelmillan/harness-btp AI-tmp
112
113
  sh AI-tmp/install.sh --dest .
113
114
  rm -rf AI-tmp
114
115
  ```
@@ -118,7 +119,7 @@ rm -rf AI-tmp
118
119
  Sin descargas manuales (requiere publicar `create-harness-btp` en el registry). Igual en todos los SO:
119
120
 
120
121
  ```bash
121
- pnpm dlx create-harness-btp@0.3.0 --dest .
122
+ pnpm dlx create-harness-btp@0.3.1 --dest .
122
123
  ```
123
124
 
124
125
  ### Qué hace el instalador
@@ -132,11 +133,11 @@ pnpm dlx create-harness-btp@0.3.0 --dest .
132
133
  Salida típica en proyecto nuevo:
133
134
 
134
135
  ```text
135
- CREATE: AI/ (v0.3.0)
136
+ CREATE: AI/ (v0.3.1)
136
137
  CREATE: AGENTS.md
137
138
  CLIENT: auto -> opencode
138
139
  CREATE: .opencode/ (+17 archivos)
139
- OK: harness v0.3.0 instalado
140
+ OK: harness v0.3.1 instalado
140
141
  ```
141
142
 
142
143
  ## Instalación asistida por agente
@@ -149,6 +150,36 @@ Déjame este proyecto listo con el harness BTP: lee https://raw.githubuserconten
149
150
 
150
151
  Vale para proyecto nuevo (con URL), existente, Windows/Linux/macOS y cualquier cliente que lea este README. El archivo `prompts/setup.md` vive versionado con el harness: siempre está al día sin que cambies tu línea.
151
152
 
153
+ ## Manual de uso
154
+
155
+ El recorrido normal de un proyecto, en orden. Cada paso dice **qué hace, con qué comando y cuándo toca**.
156
+
157
+ **1. Instalar (una sola vez por proyecto).** Copia la carpeta `AI/` dentro de tu proyecto con `pnpm dlx`, `degit` o `git clone` (ver [Instalación](#instalación)). No mueve ni renombra nada tuyo; si `AI/` ya existe, avisa en vez de pisar.
158
+
159
+ **2. Comprobar que tu agente lo adoptó.** Abre el proyecto en tu cliente y verifica: el **orquestador** aparece entre sus agentes, existe el comando **`/flow`** y responde si le pides usar una **skill** (p. ej. que te muestre el `target` actual). Si algo de esto falta, mira [Troubleshooting](#troubleshooting) antes de seguir.
160
+
161
+ **3. Contar lo que quieres (la spec).** Copia `AI/specs/_template.md` a `AI/specs/<tu-proyecto>.md` y rellénala: qué debe hacer, dónde vive en SAP y cómo se comprueba que funciona. Sin esto escrito no hay despliegue — el agente lo exige.
162
+
163
+ **4. Ponerlo a trabajar: `/flow`.** Escribe `/flow AI/specs/<tu-proyecto>.md` y el orquestador recorre las etapas (revisar tu spec, investigar la doc oficial, planear, construir, probar, corregir). Te pregunta cuando le falta un dato y al cerrar te cuenta qué hizo, con qué comandos lo verificó y qué quedó pendiente.
164
+
165
+ **5. Revisar antes de publicar: `/verify`.** Es la puerta de despliegue: comprueba destino, artefacto construido, pruebas en verde y Git limpio **sin desplegar nada**. Solo un veredicto "apto" permite pasar al despliegue.
166
+
167
+ **6. Desplegar (solo con tu orden).** El despliegue lo ejecuta un único agente especialista y deja evidencia (apps en marcha, registros, URL). Primer despliegue a un destino nuevo siempre pide tu confirmación del destino.
168
+
169
+ **7. Guardar y contar.** Los cambios se guardan en commits locales; nada sale a remoto sin que lo pidas expresamente. La spec y los informes quedan al día al cerrar.
170
+
171
+ | Comando o guion | Para qué sirve (en una línea) | Cuándo usarlo |
172
+ |---|---|---|
173
+ | `pnpm dlx create-harness-btp …` / `degit` / `git clone` | traer el harness al proyecto | una vez por proyecto; repite contra otro tag para actualizar |
174
+ | `install.ps1` / `install.sh` | copiar `AI/`, crear el puntero y fusionar `.gitignore` sin romper nada | lo corre el paquete solo; úsalo directo si instalaste por `degit`/`clone` |
175
+ | `/flow <spec>` | ejecutar el ciclo completo sobre tu spec | cada vez que construyas o cambies el MVP |
176
+ | `/verify` | revisar que todo está listo sin desplegar | antes de cada despliegue, siempre |
177
+ | `AI/scripts/check-prereqs.*` | decirte qué herramientas te faltan y dónde instalarlas | al estrenar máquina o si algo falla por entorno |
178
+ | `AI/scripts/check-docs.*` | comprobar que los enlaces a documentación oficial siguen vivos | si sospechas docs viejas, o antes de un MVP delicado |
179
+ | `AI/scripts/cf-safe.*` | leer Cloud Foundry tapando secretos | no lo llamas tú: lo usan los agentes por dentro |
180
+
181
+ **Cómo saber que todo va bien:** el instalador termina en `OK:`, `AI/VERSION` dice la versión que instalaste, tu agente muestra al orquestador y `/flow` existe, y `/verify` explica cada veredicto con motivos. Si algo de esto no cuadra, no sigas: está en [Troubleshooting](#troubleshooting).
182
+
152
183
  ## Actualizar y desinstalar
153
184
 
154
185
  **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:
@@ -156,7 +187,7 @@ Vale para proyecto nuevo (con URL), existente, Windows/Linux/macOS y cualquier c
156
187
  PowerShell:
157
188
 
158
189
  ```powershell
159
- npx -p degit degit horangelmillan/harness-btp#v0.3.0 AI-tmp -- AI-tmp
190
+ npx -p degit degit horangelmillan/harness-btp#v0.3.1 AI-tmp -- AI-tmp
160
191
  powershell -ExecutionPolicy Bypass -File AI-tmp/install.ps1 -Dest . -Force
161
192
  Remove-Item -Recurse -Force AI-tmp
162
193
  # tu versión anterior queda en AI.bak por si quieres comparar
@@ -165,7 +196,7 @@ Remove-Item -Recurse -Force AI-tmp
165
196
  bash:
166
197
 
167
198
  ```bash
168
- npx -p degit degit horangelmillan/harness-btp#v0.3.0 AI-tmp -- AI-tmp
199
+ npx -p degit degit horangelmillan/harness-btp#v0.3.1 AI-tmp -- AI-tmp
169
200
  sh AI-tmp/install.sh --dest . --force
170
201
  rm -rf AI-tmp
171
202
  # tu versión anterior queda en AI.bak por si quieres comparar
@@ -246,7 +277,7 @@ harness-btp/
246
277
  ├── install.ps1 / install.sh # instaladores idempotentes (SKIP / CREATE / BACKUP / OK)
247
278
  ├── bin/ # ejecutable de create-harness-btp (pnpm dlx)
248
279
  ├── package.json # name create-harness-btp
249
- └── VERSION # 0.3.0
280
+ └── VERSION # 0.3.1
250
281
  ```
251
282
 
252
283
  ## Cómo lo descubre el agente
@@ -268,7 +299,7 @@ Tú no configuras nada: el agente se adapta solo.
268
299
  | Líneas duplicadas en `.gitignore` | edición manual tras la fusión | el instalador fusiona sin duplicar; borra el duplicado a mano |
269
300
  | `ExecutionPolicy` bloquea `install.ps1` | política de PowerShell | `powershell -ExecutionPolicy Bypass -File AI-tmp/install.ps1 -Dest .` (o usa `install.sh` en Git Bash) |
270
301
  | `ABORT: opción desconocida` en `install.sh` | flag inexistente | `sh install.sh --help` lista `--dest`, `--force` |
271
- | `degit` falla sin Node | `degit` corre sobre Node 18+ | instala Node o usa `git clone --branch v0.3.0` |
302
+ | `degit` falla sin Node | `degit` corre sobre Node 18+ | instala Node o usa `git clone --branch v0.3.1` |
272
303
  | 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` |
273
304
  | Mi cliente no ve los agentes (claude/cursor/copilot) | instalaste sin el `--client` que usa tu proyecto (`auto` no encontró sus huellas) | reinstala sin fuerza con `--client <tu-cliente>` (p. ej. `--client claude`) y verifica la tabla de [Multi-cliente](#multi-cliente): `.claude/`, `.cursor/commands/` + `.agents/skills/`, o `.github/agents\|prompts\|skills` según cliente; si sigue sin verlos, revisa la fusión y no dupliques archivos a mano |
274
305
  | No se deja borrar la carpeta del proyecto ("Carpeta en uso") | procesos huérfanos parados dentro (shells/MCPs de una sesión ya cerrada) | resmon → CPU → Identificadores asociados → busca la carpeta y termina solo esos PIDs; nunca fueron del instalador (solo copia archivos y termina) |
@@ -297,9 +328,10 @@ MIT. Haz lo que quieras con el harness; sin garantía.
297
328
 
298
329
  ## Changelog
299
330
 
331
+ - **v0.3.1** — manual de uso: recorrido 1–7, tabla comando→para qué→cuándo, y señales de que todo va bien, en lenguaje normal.
300
332
  - **v0.3.0** — multi-cliente: definición canónica única en `AI/agents/`, `AI/commands/`, `AI/skills/`; render a `AI/clients/<cliente>/` con `scripts/render-clients.js` (opencode byte-idéntico a `AI/.opencode/`, que se conserva intacto); instaladores con flag `--client auto|all|<lista>` (detección por huellas, fusión idempotente con `SKIP`/`BACKUP` por dir); `prompts/setup.md` pregunta el cliente si es ambiguo y verifica adopción por cliente; CI exige `render-clients.js --check` antes de la guardia de versiones.
301
333
 
302
- - **v0.3.0** — fusión a `.opencode/` raíz: el instalador sincroniza `AI/.opencode/` (agents + commands + skills) en `.opencode/` del proyecto para que OpenCode descubra `orchestrator` y `/flow` (SKIP sin fuerza, `.opencode.bak` con fuerza); `prompts/setup.md` verifica adopción y fusiona el fragmento MCP.
334
+ - **v0.2.5** — fusión a `.opencode/` raíz: el instalador sincroniza `AI/.opencode/` (agents + commands + skills) en `.opencode/` del proyecto para que OpenCode descubra `orchestrator` y `/flow` (SKIP sin fuerza, `.opencode.bak` con fuerza); `prompts/setup.md` verifica adopción y fusiona el fragmento MCP.
303
335
  - **v0.2.4** — estilo Neon: una línea que lee `prompts/setup.md` (versionado, siempre al día) en vez de un bloque que caduca.
304
336
  - **v0.2.3** — prompt universal todo-en-uno: clona + instala con la versión que indique el README (nunca caduca), verifica AI/VERSION instalado.
305
337
  - **v0.2.2** — anti-huérfanos: bloque de agente con regla de cierre limpio (no dejar servidores corriendo, no borrar carpetas con procesos dentro) + troubleshooting de carpeta bloqueada (resmon → Identificadores asociados).
package/VERSION CHANGED
@@ -1 +1 @@
1
- 0.3.0
1
+ 0.3.1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-harness-btp",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
4
4
  "description": "Instala el harness MVP SAP BTP como carpeta AI/ en cualquier proyecto",
5
5
  "keywords": ["sap-btp", "opencode", "harness", "agents", "scaffolder", "create"],
6
6
  "homepage": "https://github.com/horangelmillan/harness-btp#readme",