ostacky 0.9.6 → 0.10.0
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.
- package/README.md +95 -291
- package/assets/agents/ostacky.md +4 -4
- package/assets/commands/install-stack.md +11 -11
- package/assets/commands/opsx-sync.md +1 -0
- package/assets/mcp/ostacky-controller/controller-core.js +4 -0
- package/assets/mcp/ostacky-controller/index.js +227 -9
- package/assets/plugins/ostacky-controller/controller-core.ts +4 -0
- package/assets/plugins/ostacky-controller/index.ts +136 -23
- package/dist/cli.js +261 -86
- package/manifest.json +29 -29
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,375 +1,179 @@
|
|
|
1
1
|
# Ostacky
|
|
2
2
|
|
|
3
|
-
Ostacky es un **agent harness** para [OpenCode](https://opencode.ai)
|
|
3
|
+
Ostacky es un **agent harness** para [OpenCode](https://opencode.ai): el orquestador que instalás en tu proyecto para que **4 herramientas** trabajen en sinergia sin pisarse y sin quemar tokens de más.
|
|
4
4
|
|
|
5
|
-
| Herramienta | Rol |
|
|
5
|
+
| Herramienta | Rol | Responde |
|
|
6
6
|
| --------------------------------------------------------- | ------------------- | -------------------------------------- |
|
|
7
7
|
| [CodeGraph](https://github.com/colbymchenry/codegraph) | Grafo de código | DÓNDE está el código y a quién impacta |
|
|
8
8
|
| [OpenSpec](https://github.com/Fission-AI/OpenSpec/) | Especificaciones | QUÉ hay que construir y POR QUÉ |
|
|
9
9
|
| [Superpowers](https://github.com/obra/superpowers) | Ejecución | CÓMO se implementa, prueba y revisa |
|
|
10
10
|
| [Engram](https://github.com/Gentleman-Programming/engram) | Memoria persistente | QUÉ aprendimos en sesiones anteriores |
|
|
11
11
|
|
|
12
|
-
Ostacky las rutea según el **nivel de impacto del cambio
|
|
13
|
-
|
|
14
|
-
## Cómo empezar
|
|
15
|
-
|
|
16
|
-
Después de instalar Ostacky (con `npx ostacky install`), necesitás iniciar OpenCode para usarlo. Tenés dos formas:
|
|
17
|
-
|
|
18
|
-
### Terminal UI (TUI) — recomendado para daily driving
|
|
19
|
-
|
|
20
|
-
```bash
|
|
21
|
-
opencode
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
Abre la interfaz de terminal interactiva. **Para elegir el agente Ostacky: usá `Tab` para navegar entre agentes** en el panel lateral, o escribí `/agent Ostacky` en el chat.
|
|
25
|
-
|
|
26
|
-
### Web UI — para usar desde el navegador (OpenCode v2)
|
|
27
|
-
|
|
28
|
-
```bash
|
|
29
|
-
opencode pair
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
Abre el link de un solo uso (expira en 5 minutos) o escaneá el QR en el navegador para cargar la web UI con cookie de sesión (30 días). **Para elegir el agente Ostacky: abrí el combo/selector de agentes** en la barra superior y seleccioná "Ostacky". Útil para sesiones largas, trabajo en equipo o cuando querés compartir pantalla sin compartir terminal.
|
|
33
|
-
|
|
34
|
-
> Por defecto el server corre en `http://127.0.0.1:49374` solo en localhost. Cambialo con `opencode service` (ver tabla). Docs: https://opencode.ai/v2/docs/cli/web
|
|
35
|
-
|
|
36
|
-
Opciones útiles (v2):
|
|
37
|
-
|
|
38
|
-
| Comando | Qué hace |
|
|
39
|
-
| -------------------------------------------------- | --------------------------------------------------------------- |
|
|
40
|
-
| `opencode pair` | Muestra URL + QR para conectar web/app (links de un uso, 5 min) |
|
|
41
|
-
| `opencode serve --hostname 0.0.0.0 --port 4096` | Server dedicado en foreground (host remoto, Docker/systemd) |
|
|
42
|
-
| `opencode --server http://127.0.0.1:4096` | Conectar un cliente TUI a un server activo |
|
|
43
|
-
| `opencode service set hostname 0.0.0.0` | Escuchar en red local (luego `opencode service start`) |
|
|
44
|
-
| `opencode service set port 49374` | Puerto fijo en vez del default del channel |
|
|
45
|
-
| `opencode service set password "un-secreto-largo"` | Reemplaza password generado (rota todas las sesiones) |
|
|
46
|
-
|
|
47
|
-
> 💡 Si no tenés OpenCode instalado aún: `curl -fsSL https://opencode.ai/install | bash`
|
|
48
|
-
|
|
49
|
-
## ¿Qué es?
|
|
50
|
-
|
|
51
|
-
`Ostacky` es el agente (`.opencode/agents/`) que se instala directamente desde GitHub Releases. Cada instalación queda registrada en un lockfile con versión y checksum, lo que permite actualizaciones controladas y reproducibles.
|
|
52
|
-
|
|
53
|
-
## Stack
|
|
54
|
-
|
|
55
|
-
Ostacky integra **4 herramientas** especializadas para que trabajen en conjunto sin pisarse:
|
|
56
|
-
|
|
57
|
-
### Cómo trabajan en sinergia
|
|
58
|
-
|
|
59
|
-
1. **CodeGraph** descubre el alcance del cambio sin escanear el repo entero (consulta `codegraph_explore`, `codegraph_impact`).
|
|
60
|
-
2. **OpenSpec** documenta requisitos, contratos y escenarios de aceptación (proposal → design → spec → tasks).
|
|
61
|
-
3. **Superpowers** ejecuta con TDD, testing automatizado y review (brainstorming → plans → tdd → review).
|
|
62
|
-
4. **Engram** persiste decisiones, bugs y descubrimientos con `mem_save` para que el agente no pierda contexto entre sesiones ni necesite re-ejecutar tool calls.
|
|
63
|
-
|
|
64
|
-
Ostacky decide **cuándo y cómo** usar cada herramienta según el **nivel de impacto** del cambio:
|
|
12
|
+
Ostacky las rutea según el **nivel de impacto del cambio**, preguntándote antes de actuar: cambios grandes van por OpenSpec (spec-driven development), cambios chicos ejecutan directo con skills de Superpowers.
|
|
65
13
|
|
|
66
14
|
| Nivel | Cuándo aplica | Flujo |
|
|
67
15
|
| ------- | ---------------------------------------- | ---------------------------------------------------------------------- |
|
|
68
16
|
| **0** | <5 líneas, 1 archivo, trivial | CodeGraph → directo a inline |
|
|
69
|
-
| **0+1** | 5-10 líneas, 1-2 archivos, sin API nueva | CodeGraph →
|
|
17
|
+
| **0+1** | 5-10 líneas, 1-2 archivos, sin API nueva | CodeGraph → vos elegís: spec o directo |
|
|
70
18
|
| **1+** | >10 líneas, API pública, refactors | CodeGraph → OpenSpec → execution-mode-evaluation → subagentes o inline |
|
|
71
19
|
|
|
72
|
-
Antes de ejecutar, Ostacky
|
|
73
|
-
|
|
74
|
-
## ¿Para qué sirve?
|
|
75
|
-
|
|
76
|
-
- Instalar el agente `Ostacky` en cualquier proyecto con un solo comando.
|
|
77
|
-
- Mantener un registro de qué versión está instalada (`ostacky-lock.json`)
|
|
78
|
-
- Detectar y aplicar actualizaciones mostrando el diff de versiones antes de confirmar
|
|
79
|
-
- Evitar descargas repetidas gracias al cache local en `.opencode/cache/`
|
|
80
|
-
- Resolver tareas chicas sin overhead extra de coordinación.
|
|
81
|
-
- Ejecutar tareas independientes en paralelo con **subagentes** cuando no comparten archivos, o inline secuencial cuando se pisan.
|
|
20
|
+
Antes de ejecutar, Ostacky muestra qué tasks tocan los mismos archivos para que elijas el modo de ejecución informado (inline secuencial o subagentes en paralelo).
|
|
82
21
|
|
|
83
22
|
## Requisitos
|
|
84
23
|
|
|
85
|
-
- [Node.js](https://nodejs.org/) >= 20 (para
|
|
86
|
-
-
|
|
87
|
-
-
|
|
88
|
-
- **WSL:**
|
|
24
|
+
- [Node.js](https://nodejs.org/) >= 20 (para `npx`) o [Bun](https://bun.sh/) >= 1.x (para `bunx` o desarrollo)
|
|
25
|
+
- [OpenCode](https://opencode.ai) instalado: `curl -fsSL https://opencode.ai/install | bash`
|
|
26
|
+
- Git recomendado: con git hay aislamiento por worktree; sin git Ostacky instala en el directorio actual con un aviso
|
|
27
|
+
- **WSL:** seguí las instrucciones de **Linux** — WSL corre un kernel Linux real, no uses los comandos de PowerShell aunque estés en Windows
|
|
89
28
|
|
|
90
|
-
##
|
|
29
|
+
## Instalación
|
|
91
30
|
|
|
92
|
-
No requiere instalación global ni clonar el repositorio
|
|
31
|
+
No requiere instalación global ni clonar el repositorio:
|
|
93
32
|
|
|
94
33
|
```bash
|
|
95
|
-
npx ostacky
|
|
34
|
+
npx ostacky # menú interactivo
|
|
35
|
+
bunx ostacky # lo mismo con Bun
|
|
96
36
|
```
|
|
97
37
|
|
|
98
|
-
|
|
99
|
-
bunx ostacky
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
## Uso
|
|
103
|
-
|
|
104
|
-
### Menú interactivo
|
|
38
|
+
### Local (default)
|
|
105
39
|
|
|
106
40
|
```bash
|
|
107
|
-
npx ostacky
|
|
41
|
+
npx ostacky install # <proyecto>/.opencode (default)
|
|
42
|
+
npx ostacky install --scope local # explícito
|
|
108
43
|
```
|
|
109
44
|
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
### Instalar todo
|
|
45
|
+
Instala el núcleo (agente, commands, skills, MCPs, plugins) más el stack de herramientas (CodeGraph, Engram) en `<proyecto>/.opencode`, y asegura `.gitignore` con `.opencode/tools/`, `.codegraph/`, `.opencode/cache/` y `ostacky-state.json*`.
|
|
113
46
|
|
|
114
|
-
|
|
115
|
-
npx ostacky install # siempre local en <proyecto>/.opencode
|
|
116
|
-
npx ostacky install --scope local # <proyecto>/.opencode (único scope soportado)
|
|
117
|
-
```
|
|
47
|
+
> Si el log muestra `toolsDir` en tu home (ej. `C:\Users\...\.opencode\tools\codegraph`) y esperabas tu proyecto, es porque corriste el comando fuera de un repo git. Hacé `cd` al proyecto y re-ejecutá.
|
|
118
48
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
> **Instalación siempre local:** Ostacky vive por proyecto/worktree (CodeGraph index `.codegraph/` y `ostacky-state.json` aislados). Si ves `C:\Users\...\ .opencode\tools\codegraph` y esperabas `D:\mi-proyecto\.opencode`, es porque corriste `npx ostacky` desde tu home sin estar dentro del proyecto (sin `.git`). Hacé `cd` al proyecto y re-ejecutá; el log muestra `projectRoot` y `toolsDir` explícitos.
|
|
122
|
-
|
|
123
|
-
### Agregar agentes o commands individualmente
|
|
49
|
+
### Global (opt-in)
|
|
124
50
|
|
|
125
51
|
```bash
|
|
126
|
-
npx ostacky
|
|
127
|
-
npx ostacky
|
|
52
|
+
npx ostacky --scope global # menú interactivo global
|
|
53
|
+
npx ostacky install --scope global # núcleo global (agente + commands + skills + MCPs + plugins)
|
|
128
54
|
```
|
|
129
55
|
|
|
130
|
-
|
|
56
|
+
Escribe el núcleo en el config dir global de OpenCode, sin tocar ningún proyecto:
|
|
131
57
|
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
58
|
+
| SO | Dir global |
|
|
59
|
+
| ------------- | ------------------------------------------------------- |
|
|
60
|
+
| Linux / macOS | `~/.config/opencode` (respeta `XDG_CONFIG_HOME`) |
|
|
61
|
+
| Windows | `%APPDATA%\opencode` (fallback: `~/.config/opencode`) |
|
|
62
|
+
| WSL | como Linux |
|
|
137
63
|
|
|
138
|
-
|
|
64
|
+
La config global acepta `opencode.json` o `opencode.jsonc`. Si el proyecto define el mismo MCP, el del proyecto reemplaza al global (comportamiento v2); en skills con mismo ID gana la del proyecto.
|
|
139
65
|
|
|
140
|
-
|
|
141
|
-
Actualizaciones disponibles
|
|
142
|
-
agente ostacky 0.0.1 → 0.0.2
|
|
143
|
-
command install-stack 0.0.1 → 0.0.2
|
|
66
|
+
> **Migración v1 → v2:** `npx ostacky` sin subcomando busca la última versión publicada y, si detecta v1 instalada, ofrece migrar (siempre con confirmación).
|
|
144
67
|
|
|
145
|
-
|
|
146
|
-
```
|
|
68
|
+
### Por qué el stack es local
|
|
147
69
|
|
|
148
|
-
|
|
70
|
+
Con `--scope global` el stack (CodeGraph, Engram) **se omite** — se instala por proyecto con `npx ostacky install-stack` dentro de cada repo. El motivo:
|
|
149
71
|
|
|
150
|
-
|
|
72
|
+
- **El índice `.codegraph/` describe UN repo.** Se crea con `codegraph init` en cada proyecto y un watcher lo mantiene al día. Un índice global mezclaría símbolos de proyectos distintos (dos `UserService` colisionarían), no podría seguir ramas ni worktrees, y cada consulta arrastraría contexto ajeno. Como `.git/`: el motor puede ser global, el dato es por proyecto.
|
|
73
|
+
- **El `ostacky-state.json` es por worktree.** Guarda fase, locks y auditoría del orquestador; aislado por worktree, varios agentes en paralelo no se pisan.
|
|
74
|
+
- **Los binarios SÍ podrían ser globales** — ambos proyectos lo soportan (`npm i -g @colbymchenry/codegraph`; Engram vía Homebrew o su `setup.sh`, con datos en `~/.engram`). Ostacky prefiere una copia local versionada junto al lockfile para instalaciones reproducibles sin depender de tu PATH. Si ya tenés `engram` global, Ostacky lo reutiliza.
|
|
151
75
|
|
|
152
|
-
|
|
76
|
+
## Primeros pasos
|
|
153
77
|
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
```
|
|
78
|
+
1. **Iniciá OpenCode:** `opencode` (terminal) u `opencode pair` (web: abrí el link de un solo uso o escaneá el QR).
|
|
79
|
+
2. **Elegí el agente:** `/agents` → `ostacky` (o Shift+Tab / Ctrl+X A).
|
|
80
|
+
3. Escribí tu mensaje en el chat. En OpenCode v2, `@` es solo para referenciar archivos, no agentes.
|
|
158
81
|
|
|
159
|
-
|
|
82
|
+
> Por defecto la web corre en `http://127.0.0.1:49374` solo en localhost. Docs: https://opencode.ai/v2/docs/cli/web
|
|
160
83
|
|
|
161
|
-
|
|
84
|
+
Si algo del stack falló durante la instalación, regeneralo sin salir de la sesión: seleccioná `ostacky` y ejecutá `/install-stack` en el chat.
|
|
162
85
|
|
|
163
|
-
|
|
86
|
+
## Uso diario
|
|
164
87
|
|
|
165
88
|
```bash
|
|
166
|
-
npx ostacky
|
|
167
|
-
npx ostacky
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
Por ejemplo:
|
|
171
|
-
|
|
172
|
-
```bash
|
|
173
|
-
npx ostacky uninstall agent ostacky
|
|
174
|
-
```
|
|
175
|
-
|
|
176
|
-
#### Desinstalar un command puntual
|
|
177
|
-
|
|
178
|
-
```bash
|
|
179
|
-
npx ostacky uninstall command <nombre> # también admite --scope local
|
|
180
|
-
npx ostacky uninstall command # sin nombre → selector
|
|
181
|
-
```
|
|
182
|
-
|
|
183
|
-
Por ejemplo:
|
|
184
|
-
|
|
185
|
-
```bash
|
|
186
|
-
npx ostacky uninstall command install-stack
|
|
89
|
+
npx ostacky add agent # selector múltiple (indica instalados y versión)
|
|
90
|
+
npx ostacky add command
|
|
91
|
+
npx ostacky update # diff de versiones antes de confirmar
|
|
92
|
+
npx ostacky@latest update # update con la última versión publicada del instalador
|
|
187
93
|
```
|
|
188
94
|
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
#### Desinstalar todo el stack (tools + config)
|
|
95
|
+
> `@latest` y `update` son cosas distintas: `@latest` es el tag de npm (qué instalador descargás), `update` es la acción (qué contenido actualizás según el lockfile).
|
|
192
96
|
|
|
193
97
|
```bash
|
|
194
|
-
npx ostacky uninstall
|
|
195
|
-
npx ostacky uninstall
|
|
98
|
+
npx ostacky uninstall # safe-delete en <proyecto>/.opencode
|
|
99
|
+
npx ostacky uninstall --scope global # safe-delete global
|
|
100
|
+
npx ostacky uninstall agent <nombre> # puntual (sin nombre → selector)
|
|
101
|
+
npx ostacky uninstall-stack # limpia config del stack del proyecto
|
|
102
|
+
npx ostacky --version | npx ostacky --help
|
|
196
103
|
```
|
|
197
104
|
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
### Otros
|
|
201
|
-
|
|
202
|
-
```bash
|
|
203
|
-
npx ostacky --version # muestra la versión del CLI
|
|
204
|
-
npx ostacky --help # muestra la ayuda
|
|
205
|
-
```
|
|
105
|
+
**Safe-delete:** solo borra lo trackeado en `ostacky-lock.json` — nunca toca componentes tuyos. Muestra preview con `Scope: <ruta>` y pide confirmación. Los plugins Ostacky-owned se limpian por allowlist; los custom no se tocan.
|
|
206
106
|
|
|
207
|
-
##
|
|
107
|
+
## Qué se instala
|
|
208
108
|
|
|
209
|
-
|
|
109
|
+
Local (`<proyecto>/.opencode`) o global (mismo árbol bajo el dir global, sin stack):
|
|
210
110
|
|
|
211
111
|
```
|
|
212
112
|
.opencode/
|
|
213
|
-
├── agents/
|
|
214
|
-
|
|
215
|
-
├── commands/
|
|
216
|
-
│ ├── install-stack.md
|
|
113
|
+
├── agents/ostacky.md
|
|
114
|
+
├── commands/install-stack.md
|
|
217
115
|
│ └── opsx-sync.md
|
|
218
|
-
├── skills/
|
|
219
|
-
│
|
|
220
|
-
│
|
|
221
|
-
│
|
|
222
|
-
│ ├── execution-mode-evaluation/
|
|
223
|
-
│ ├── subagent-driven-development/
|
|
224
|
-
│ ├── dispatching-parallel-agents/
|
|
225
|
-
│ ├── openspec-propose/
|
|
226
|
-
│ ├── openspec-apply-change/
|
|
227
|
-
│ ├── openspec-archive-change/
|
|
228
|
-
│ ├── receiving-code-review/
|
|
229
|
-
│ ├── using-git-worktrees/
|
|
230
|
-
│ ├── using-superpowers/
|
|
231
|
-
│ ├── writing-skills/
|
|
232
|
-
│ └── graceful-degradation/
|
|
116
|
+
├── skills/ ← brainstorming, tdd, review, execution-mode-evaluation,
|
|
117
|
+
│ subagent-driven, dispatching-parallel-agents, openspec-* (3),
|
|
118
|
+
│ receiving-code-review, using-git-worktrees,
|
|
119
|
+
│ using-superpowers, writing-skills, graceful-degradation
|
|
233
120
|
├── plugins/
|
|
234
|
-
│ ├── ostacky-
|
|
235
|
-
│ └── engram.ts
|
|
121
|
+
│ ├── ostacky-controller/ ← controller hard-gate (index.ts + core + security + tiered)
|
|
122
|
+
│ └── engram.ts ← plugin Engram
|
|
236
123
|
├── mcp/
|
|
237
|
-
│ ├── ostacky-controller/
|
|
124
|
+
│ ├── ostacky-controller/ ← MCP thin (observabilidad)
|
|
238
125
|
│ └── openspec/
|
|
239
|
-
├── tools/
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
├── ostacky-state.json ← estado por worktree (aislado)
|
|
244
|
-
└── ostacky-lock.json ← versiones instaladas (agentes, commands, skills, mcpServers)
|
|
126
|
+
├── tools/ ← SOLO local: codegraph/bin + engram/bin
|
|
127
|
+
├── cache/codegraph/ ← cache local de descargas
|
|
128
|
+
├── ostacky-state.json ← SOLO local: estado aislado por worktree
|
|
129
|
+
└── ostacky-lock.json ← versiones instaladas (agents, commands, skills, mcpServers)
|
|
245
130
|
```
|
|
246
131
|
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
### ostacky-lock.json
|
|
132
|
+
`plugins/` y `tools/` **no** se trackean en el lockfile (allowlist Ostacky-owned). Instalaciones viejas con archivos legacy sueltos (`ostacky-plugin.ts`, `ostacky-guard.ts`, `ostacky-controller.ts`) se limpian automáticamente.
|
|
250
133
|
|
|
251
134
|
```json
|
|
252
135
|
{
|
|
253
|
-
"version": "0.
|
|
254
|
-
"
|
|
255
|
-
"
|
|
256
|
-
"
|
|
257
|
-
"
|
|
258
|
-
|
|
259
|
-
"version": "0.9.6",
|
|
260
|
-
"installedAt": "2025-01-01T00:00:00.000Z",
|
|
261
|
-
"sha256": "abc123..."
|
|
262
|
-
}
|
|
263
|
-
},
|
|
264
|
-
"commands": {
|
|
265
|
-
"install-stack": {
|
|
266
|
-
"version": "0.9.6",
|
|
267
|
-
"installedAt": "2025-01-01T00:00:00.000Z",
|
|
268
|
-
"sha256": "def456..."
|
|
269
|
-
},
|
|
270
|
-
"opsx-sync": {
|
|
271
|
-
"version": "0.9.6",
|
|
272
|
-
"installedAt": "2025-01-01T00:00:00.000Z",
|
|
273
|
-
"sha256": "ghi789..."
|
|
274
|
-
}
|
|
275
|
-
},
|
|
276
|
-
"skills": {
|
|
277
|
-
"brainstorming": { "version": "0.9.6", ... },
|
|
278
|
-
"execution-mode-evaluation": { "version": "0.9.6", ... },
|
|
279
|
-
"openspec-propose": { "version": "0.9.6", ... }
|
|
280
|
-
},
|
|
281
|
-
"mcpServers": {
|
|
282
|
-
"ostacky-controller": { "version": "0.9.6", ... },
|
|
283
|
-
"openspec": { "version": "0.9.6", ... }
|
|
284
|
-
}
|
|
136
|
+
"version": "0.10.0",
|
|
137
|
+
"tag": "v0.10.0",
|
|
138
|
+
"agents": { "ostacky": { "version": "0.10.0", "sha256": "…" } },
|
|
139
|
+
"commands": { "install-stack": { … }, "opsx-sync": { … } },
|
|
140
|
+
"skills": { "brainstorming": { … }, "…" : {} },
|
|
141
|
+
"mcpServers": { "ostacky-controller": { … }, "openspec": { … } }
|
|
285
142
|
}
|
|
286
143
|
```
|
|
287
144
|
|
|
288
|
-
|
|
145
|
+
Versionado con checksums: sumá `ostacky-lock.json` a git para que el equipo instale exactamente las mismas versiones. Las descargas usan tags de GitHub (nunca `main`) y cada path se valida contra path traversal.
|
|
289
146
|
|
|
290
|
-
|
|
147
|
+
## Comandos útiles
|
|
291
148
|
|
|
292
|
-
|
|
149
|
+
Engram y CodeGraph viven en `.opencode/tools/<herramienta>/bin/` y se exponen como MCP servers. Algunos comandos CLI:
|
|
293
150
|
|
|
294
|
-
|
|
151
|
+
| Comando | Qué hace |
|
|
152
|
+
| ----------------------------------------------------------------- | ------------------------------------------------------- |
|
|
153
|
+
| `engram list-projects` | Proyectos con memoria |
|
|
154
|
+
| `engram clean-content --project <nombre>` \| `--all` | Borra memoria de un proyecto / de todos |
|
|
155
|
+
| `engram --version` | Versión instalada |
|
|
156
|
+
| `codegraph init -i` | Indexa el proyecto (crea `.codegraph/`) |
|
|
157
|
+
| `codegraph sync` / `codegraph status` | Sincroniza / muestra estado del índice |
|
|
158
|
+
| `codegraph install --target opencode --location local --yes` | Recablea CodeGraph a OpenCode y genera AGENTS.md |
|
|
295
159
|
|
|
296
|
-
|
|
297
|
-
- **TUI:** `opencode` en tu terminal → seleccioná el agente con `/agents` (o atajos **Shift+Tab** / **Ctrl+X A**)
|
|
298
|
-
- **Web:** `opencode pair` y abrí el link impreso (ej. `http://127.0.0.1:49374/auth/...`) o escaneá el QR → abrí el selector de agentes de la interfaz y elegí `ostacky`
|
|
299
|
-
2. OpenCode detecta automáticamente los archivos nuevos en `.opencode/` al iniciar, no necesita recarga manual.
|
|
300
|
-
3. Para usar el agente, seleccionalo con `/agents` y escribí tu mensaje en el chat. (En OpenCode v2, `@` es solo para referenciar archivos, no agentes.)
|
|
160
|
+
## Troubleshooting
|
|
301
161
|
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
```text
|
|
307
|
-
/install-stack
|
|
308
|
-
```
|
|
309
|
-
|
|
310
|
-
Es opcional y solo necesario si algo falló durante la instalación o si querés verificar que todo esté en orden.
|
|
162
|
+
- **Instalé fuera del proyecto / sin git:** hacé `cd` al proyecto y re-ejecutá. El log muestra `projectRoot` y `toolsDir` explícitos para diagnosticar scope.
|
|
163
|
+
- **El install global creó `.opencode/` local:** actualizá (`npx ostacky@latest`) y reinstalá — el menú interactivo ya propaga el scope y el stack se omite en global.
|
|
164
|
+
- **Windows `cmd.exe ... codegraph.cmd init -i` durante el install:** warning no fatal — el binario quedó, solo falta el índice. Reintentá con `npx ostacky install-stack --scope local` o corré `.opencode\tools\codegraph\bin\codegraph.exe init -i` dentro del proyecto.
|
|
165
|
+
- **¿Errores en el stack?** Desde el chat de OpenCode: `/install-stack`.
|
|
311
166
|
|
|
312
167
|
## Seguridad
|
|
313
168
|
|
|
314
|
-
- `opencode.jsonc`
|
|
315
|
-
-
|
|
316
|
-
-
|
|
317
|
-
-
|
|
318
|
-
- El cache local (`.opencode/cache/`) también valida integridad al servir archivos cacheados
|
|
319
|
-
|
|
320
|
-
#### Restricciones de acceso a credenciales
|
|
321
|
-
|
|
322
|
-
- La configuración local de OpenCode (`opencode.jsonc`) bloquea lectura y escritura de `*.env` y `.secret/**` con `deny`.
|
|
323
|
-
- La sesión sigue ejecutándose después del bloqueo porque `experimental.continue_loop_on_deny` está activado.
|
|
324
|
-
- Para worktrees, el repo prefiere `.worktrees/` o `worktrees/` (ambos project-local).
|
|
325
|
-
|
|
326
|
-
#### Patrones sensibles configurables (hardening-v2)
|
|
327
|
-
|
|
328
|
-
- Variable `OSTACKY_SENSITIVE_PATTERNS` overridea los patrones por defecto (`**/.env*`, `**/.secrets/**`, `**/*.pem`, `**/*.key`, `**/.aws/**`, `**/.ssh/**`, `**/credentials.json`, `**/.npmrc`).
|
|
329
|
-
- Ejemplo: `OSTACKY_SENSITIVE_PATTERNS="**/.env*,**/.secrets/**" bunx ostacky doctor` — `doctor` imprime el patrón efectivo.
|
|
330
|
-
- Allowlist: `.env.example`, `.env.template`, `.env.sample` nunca se bloquean.
|
|
331
|
-
- Fuente única: `src/security.ts` (`SENSITIVE_DEFAULT`, `isSensitive`, `BASH_SENSITIVE_RE`) — mirrors generados en `assets/plugins/security.ts` y `assets/mcp/ostacky-controller/security.js` vía `bun run scripts/sync-controller-core.ts`; `ostacky-plugin.ts` importa de `./security.ts` (self-contained). Ver `doctor` para verificar.
|
|
332
|
-
|
|
333
|
-
#### Aislamiento de worktrees (harness-prod-hardening)
|
|
334
|
-
|
|
335
|
-
Cada worktree de git tiene su **propio** `ostacky-state.json` aislado (resuelto via `findProjectRoot()` con `git rev-parse --show-toplevel`). Dos worktrees no comparten `statePath`, locks ni backups — 3 agentes en 3 worktrees no corrompen el estado del otro. Ver `assets/skills/using-git-worktrees/SKILL.md` §Ostacky Worktree Isolation y `src/fs.ts:findProjectRoot`.
|
|
169
|
+
- `opencode.jsonc` puede versionarse para compartir permisos y MCP de forma reproducible.
|
|
170
|
+
- Descargas por tags de GitHub + validación anti path-traversal + checksums SHA-256 del manifest + cache local con validación de integridad.
|
|
171
|
+
- Lectura/escritura de `*.env` y `.secret/**` bloqueadas con `deny` (la sesión sigue por `experimental.continue_loop_on_deny`).
|
|
172
|
+
- Patrones sensibles configurables: `OSTACKY_SENSITIVE_PATTERNS="**/.env*,**/.secrets/**" bunx ostacky doctor` (allowlist: `.env.example/.template/.sample`). Fuente única en `src/security.ts`; verificá con `npx ostacky doctor`.
|
|
336
173
|
|
|
337
174
|
## Cache
|
|
338
175
|
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
```
|
|
342
|
-
.opencode/cache/<repo>/<tag>/<ruta-del-archivo>
|
|
343
|
-
```
|
|
344
|
-
|
|
345
|
-
Si ya existe un archivo en cache con el hash correcto, no se hace ninguna petición de red.
|
|
346
|
-
|
|
347
|
-
## Comandos útiles de las herramientas
|
|
348
|
-
|
|
349
|
-
### Engram (memoria persistente)
|
|
350
|
-
|
|
351
|
-
Engram está instalado localmente en `.opencode/tools/engram/bin/engram` y se configura como MCP server en `opencode.json`. Desde el chat de OpenCode, usá las tools de Engram directamente. Algunos comandos CLI útiles:
|
|
352
|
-
|
|
353
|
-
| Comando | Qué hace |
|
|
354
|
-
| -------------------------------------------------------------------- | --------------------------------------------------------- |
|
|
355
|
-
| `.opencode/tools/engram/bin/engram list-projects` | Lista todos los proyectos con memoria en Engram |
|
|
356
|
-
| `.opencode/tools/engram/bin/engram clean-content --project <nombre>` | Borra el contenido de memoria de un proyecto específico |
|
|
357
|
-
| `.opencode/tools/engram/bin/engram clean-content --all` | Borra TODO el contenido de memoria de todos los proyectos |
|
|
358
|
-
| `.opencode/tools/engram/bin/engram serve` | Inicia el server de session tracking (puerto 7437) |
|
|
359
|
-
| `.opencode/tools/engram/bin/engram --version` | Muestra la versión instalada |
|
|
360
|
-
|
|
361
|
-
### CodeGraph (grafo de código)
|
|
362
|
-
|
|
363
|
-
CodeGraph está instalado en `.opencode/tools/codegraph/bin/codegraph` y se configura como MCP server. Desde el chat de OpenCode, usá las tools de CodeGraph directamente (`codegraph_explore`, `codegraph_trace`, etc.). Algunos comandos CLI útiles:
|
|
364
|
-
|
|
365
|
-
| Comando | Qué hace |
|
|
366
|
-
| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
|
|
367
|
-
| `.opencode/tools/codegraph/bin/codegraph init -i` | Indexa el proyecto actual (crea `.codegraph/` con el grafo) |
|
|
368
|
-
| `.opencode/tools/codegraph/bin/codegraph sync` | Sincroniza cambios incrementales al grafo |
|
|
369
|
-
| `.opencode/tools/codegraph/bin/codegraph status` | Muestra estado del index y archivos pendientes |
|
|
370
|
-
| `.opencode/tools/codegraph/bin/codegraph install --target opencode --location local --yes` | Configura CodeGraph para OpenCode y genera AGENTS.md |
|
|
371
|
-
|
|
372
|
-
> **Windows:** si ves `Command failed: cmd.exe /d /c call ... codegraph.cmd init -i` durante `npx ostacky install`, es un _warning_ no fatal — el binario se instaló pero el índice no se pudo crear. Reintentá con `npx ostacky install-stack --scope local` o ejecutá manualmente `.opencode\tools\codegraph\bin\codegraph.exe init -i` (o `codegraph.cmd` si no hay `.exe`) dentro del proyecto. Desde v0.9.6 el instalador usa el patrón resiliente de Engram (strip 0 + búsqueda recursiva) y loguea `projectRoot|toolsDir` para diagnosticar scope.
|
|
176
|
+
Descargas en `.opencode/cache/<repo>/<tag>/<ruta>`. Si el archivo cacheado tiene el hash correcto, no hay petición de red.
|
|
373
177
|
|
|
374
178
|
## Licencia
|
|
375
179
|
|
package/assets/agents/ostacky.md
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
---
|
|
2
2
|
description: Orquestador principal — rutea por nivel, orquesta CodeGraph + OpenSpec + Superpowers.
|
|
3
3
|
mode: primary
|
|
4
|
-
version: 0.
|
|
4
|
+
version: 0.10.0
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
Sos **Ostacky v0.
|
|
7
|
+
Sos **Ostacky v0.10.0**, orquestás, no implementás. Interpretás, clasificás (0/0+1/1+), ruteás y coordinás.
|
|
8
8
|
|
|
9
|
-
> **Versión:** `0.
|
|
9
|
+
> **Versión:** `0.10.0` (sincronizada desde `package.json` vía `scripts/sync-version.ts`). Cuando te pregunten qué versión tenés, qué versión sos, o `¿qué versión tenés?` / `version` / `¿en qué versión estás?`, respondé exactamente: **"Ostacky v0.10.0"** (o `v0.10.0` si te piden solo el número). No inventes otra versión.
|
|
10
10
|
|
|
11
11
|
## Reglas innegociables
|
|
12
12
|
|
|
@@ -71,7 +71,7 @@ Si vago → preguntar. Si claro → `start_request`.
|
|
|
71
71
|
|
|
72
72
|
`record_discovery({level,snapshot})` → `ROUTE_DECISION_PENDING` (`SPEC` si 1+, `DIRECT` si 0/0+1). `proceed_to_route` deprecated no-op.
|
|
73
73
|
|
|
74
|
-
|
|
74
|
+
**Nivel 0 → DIRECT automático (sin pregunta de ruteo):** anunciar `Nivel 0 + archivos + qué se va a hacer` y proceder con `consume_route_decision(DIRECT)`; el veto del usuario vale (si objeta, se frena). Niveles `0+1`/`1+` → preguntar nivel y `consume_route_decision` (una pregunta por turno).
|
|
75
75
|
|
|
76
76
|
### 3. Specification (solo SPEC)
|
|
77
77
|
|
|
@@ -1,31 +1,31 @@
|
|
|
1
1
|
---
|
|
2
2
|
description: Instala CodeGraph, skills curadas, OpenSpec y Engram localmente para OpenCode únicamente
|
|
3
3
|
agent: build
|
|
4
|
+
subagent: false
|
|
4
5
|
---
|
|
5
6
|
|
|
6
7
|
Instala el stack tecnológico de desarrollo para OpenCode. **IMPORTANTE:** las herramientas se instalan por separado (cada una con su propio CLI/comando). `npx ostacky install` solo instala el agente y commands de Ostacky en `.opencode/`. Este comando (`/install-stack`) es la guía de referencia para la instalación manual completa paso a paso.
|
|
7
8
|
|
|
8
|
-
**Nota:** A partir de v0.
|
|
9
|
+
**Nota:** A partir de v0.10.0, `npx ostacky install` ya instala automáticamente el stack completo (CodeGraph, OpenSpec, Engram, MCPs bundleados) además del agente y skills. Este comando es útil para instalación manual, verificación, o cuando algo falló y necesita reinstalarse.
|
|
9
10
|
|
|
10
11
|
**RESTRICCIÓN ABSOLUTA:** instalar ÚNICAMENTE para OpenCode. Está terminantemente prohibido crear o modificar archivos en `.claude/`, `.kiro/`, `.cursor/`, `.gemini/`, `.codex/`, `.antigravity/`, `.windsurf/` o cualquier otro directorio de plataformas externas.
|
|
11
12
|
|
|
12
13
|
**Origen del set curado:** el set de 15 skills referenciado en `assets/agents/ostacky.md` está bundleado en `assets/skills/` dentro del paquete npm. La definición del set y su trazabilidad viven en `manifest.json` y `.opencode/ostacky-lock.json`.
|
|
13
14
|
|
|
14
|
-
## Scope de instalación — local vs global (
|
|
15
|
+
## Scope de instalación — local (default) vs global (opt-in)
|
|
15
16
|
|
|
16
|
-
`npx ostacky install` soporta `--scope local|global
|
|
17
|
+
`npx ostacky install` soporta `--scope local|global` (también `--scope=...`):
|
|
17
18
|
|
|
18
|
-
- `local` (
|
|
19
|
-
- `global`: escribe en `~/.config/opencode`
|
|
20
|
-
- `
|
|
21
|
-
- Sin flag: pregunta interactivamente (default local)
|
|
19
|
+
- `local` (default): escribe en `<proyecto>/.opencode` (`opencode.json` local). Sin flag asume local.
|
|
20
|
+
- `global`: escribe el núcleo (agente, commands, skills, MCPs, plugins) en el config dir global de OpenCode (`~/.config/opencode`, respeta `XDG_CONFIG_HOME`; en Windows el config dir global según SO). No toca `<proyecto>/.opencode`.
|
|
21
|
+
- `--scope auto` y `-g` son error educativo: usá `--scope local` o `--scope global` explícito.
|
|
22
22
|
|
|
23
|
-
Herramientas (`tools/`) permanecen siempre en `<proyecto>/.opencode/tools` por reproducibilidad
|
|
23
|
+
Herramientas (`tools/` CodeGraph/Engram) permanecen siempre en `<proyecto>/.opencode/tools` por reproducibilidad, también con `--scope global`. `npx ostacky install-stack --scope global` avisa y usa local — el stack se instala por proyecto:
|
|
24
24
|
|
|
25
25
|
```bash
|
|
26
|
-
npx ostacky install
|
|
27
|
-
npx ostacky install --scope global
|
|
28
|
-
npx ostacky install-stack
|
|
26
|
+
npx ostacky install # local (default)
|
|
27
|
+
npx ostacky install --scope global # núcleo global (sin stack)
|
|
28
|
+
npx ostacky install-stack # stack local por proyecto
|
|
29
29
|
```
|
|
30
30
|
|
|
31
31
|
> **Windows con espacios** (ej. `C:\Users\Jaime Horacio\Desktop\Mi Proyecto`): la instalación es segura via invocación por arrays (libuv escapa cada argumento); no se aplica pre-quoting. `opencode.json` guarda `command` como array JSON.
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
description: Sincroniza el grafo de CodeGraph y luego los delta specs del change activo con la implementación
|
|
3
3
|
agent: build
|
|
4
|
+
subagent: false
|
|
4
5
|
---
|
|
5
6
|
|
|
6
7
|
Sincroniza primero el grafo y luego los delta specs (`proposal.md` / `design.md` / `tasks.md`) del change activo en `openspec/changes/<name>/` con el estado actual de la implementación.
|
|
@@ -141,6 +141,10 @@ export const DEFAULT_STATE = {
|
|
|
141
141
|
pendingFileAccess: {},
|
|
142
142
|
lastHeartbeat: 0,
|
|
143
143
|
watchdogEnabled: true,
|
|
144
|
+
// multi-sesión: dueño de la request activa (sessionId de OpenCode vía _meta).
|
|
145
|
+
// null = sin dueño conocido. Es UN campo (se sobreescribe) — nunca un archivo por sesión.
|
|
146
|
+
ownerSessionId: null,
|
|
147
|
+
ownerHeartbeat: 0,
|
|
144
148
|
ts: Date.now(),
|
|
145
149
|
specNotInSync: false,
|
|
146
150
|
engramBypassCount: 0,
|