ostacky 0.9.7 → 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 +93 -309
- package/assets/agents/ostacky.md +3 -3
- package/assets/commands/install-stack.md +1 -1
- 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 +55 -36
- package/manifest.json +28 -28
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,395 +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:**
|
|
89
|
-
|
|
90
|
-
## Uso rápido (para usuarios)
|
|
91
|
-
|
|
92
|
-
No requiere instalación global ni clonar el repositorio. Se usa directamente con `npx` o `bunx`:
|
|
93
|
-
|
|
94
|
-
```bash
|
|
95
|
-
npx ostacky
|
|
96
|
-
```
|
|
97
|
-
|
|
98
|
-
```bash
|
|
99
|
-
bunx ostacky
|
|
100
|
-
```
|
|
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
|
|
101
28
|
|
|
102
|
-
##
|
|
29
|
+
## Instalación
|
|
103
30
|
|
|
104
|
-
|
|
31
|
+
No requiere instalación global ni clonar el repositorio:
|
|
105
32
|
|
|
106
33
|
```bash
|
|
107
|
-
npx ostacky
|
|
34
|
+
npx ostacky # menú interactivo
|
|
35
|
+
bunx ostacky # lo mismo con Bun
|
|
108
36
|
```
|
|
109
37
|
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
### Instalar todo (local, default)
|
|
38
|
+
### Local (default)
|
|
113
39
|
|
|
114
40
|
```bash
|
|
115
|
-
npx ostacky install #
|
|
116
|
-
npx ostacky install --scope local #
|
|
41
|
+
npx ostacky install # <proyecto>/.opencode (default)
|
|
42
|
+
npx ostacky install --scope local # explícito
|
|
117
43
|
```
|
|
118
44
|
|
|
119
|
-
|
|
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*`.
|
|
120
46
|
|
|
121
|
-
>
|
|
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á.
|
|
122
48
|
|
|
123
|
-
###
|
|
49
|
+
### Global (opt-in)
|
|
124
50
|
|
|
125
51
|
```bash
|
|
126
52
|
npx ostacky --scope global # menú interactivo global
|
|
127
53
|
npx ostacky install --scope global # núcleo global (agente + commands + skills + MCPs + plugins)
|
|
128
54
|
```
|
|
129
55
|
|
|
130
|
-
Escribe el núcleo en el config dir global de OpenCode sin tocar ningún proyecto:
|
|
56
|
+
Escribe el núcleo en el config dir global de OpenCode, sin tocar ningún proyecto:
|
|
131
57
|
|
|
132
|
-
| SO
|
|
133
|
-
|
|
134
|
-
| Linux / macOS | `~/.config/opencode` (respeta `XDG_CONFIG_HOME`)
|
|
135
|
-
| Windows
|
|
136
|
-
| WSL
|
|
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
|
-
> **Migración v1 → v2:** `npx ostacky`
|
|
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).
|
|
141
67
|
|
|
142
|
-
###
|
|
68
|
+
### Por qué el stack es local
|
|
143
69
|
|
|
144
|
-
|
|
145
|
-
npx ostacky add agent
|
|
146
|
-
npx ostacky add command
|
|
147
|
-
```
|
|
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:
|
|
148
71
|
|
|
149
|
-
|
|
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.
|
|
150
75
|
|
|
151
|
-
|
|
76
|
+
## Primeros pasos
|
|
152
77
|
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
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.
|
|
156
81
|
|
|
157
|
-
|
|
82
|
+
> Por defecto la web corre en `http://127.0.0.1:49374` solo en localhost. Docs: https://opencode.ai/v2/docs/cli/web
|
|
158
83
|
|
|
159
|
-
|
|
160
|
-
Actualizaciones disponibles
|
|
161
|
-
agente ostacky 0.0.1 → 0.0.2
|
|
162
|
-
command install-stack 0.0.1 → 0.0.2
|
|
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.
|
|
163
85
|
|
|
164
|
-
|
|
165
|
-
```
|
|
166
|
-
|
|
167
|
-
Solo descarga los items que cambiaron de versión.
|
|
168
|
-
|
|
169
|
-
> **Nota:** `@latest` y `update` son cosas distintas. `npx ostacky@latest` fuerza a descargar la **última versión publicada** del instalador (el `@latest` es el tag de npm) y, sin subcomando, abre el menú interactivo. `npx ostacky update` corre la **acción de actualizar** (trae el manifest remoto y actualiza lo instalado según el lockfile) con la versión del instalador que npx resuelva (puede ser cacheada). Para ambas garantías, combinalos: `npx ostacky@latest update`.
|
|
170
|
-
|
|
171
|
-
### Desinstalar
|
|
86
|
+
## Uso diario
|
|
172
87
|
|
|
173
88
|
```bash
|
|
174
|
-
npx ostacky
|
|
175
|
-
npx ostacky
|
|
176
|
-
npx ostacky
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
**Safe-delete:** solo borra lo trackeado en `.opencode/ostacky-lock.json` (agentes, commands, skills, MCPs) — nunca toca componentes previos del usuario que no estén en el lockfile. Antes de borrar muestra preview con `Scope: <ruta>` + lista de paths y pide confirmación. Los plugins Ostacky-owned (`ostacky-plugin.ts`, `engram.ts` + legacy `ostacky-guard.ts`/`ostacky-controller.ts` si quedaron) se limpian automáticamente via allowlist, nunca se borran plugins custom.
|
|
180
|
-
|
|
181
|
-
> Si el lockfile no existe o está vacío → `No hay nada instalado.` y no borra nada.
|
|
182
|
-
|
|
183
|
-
#### Desinstalar un agente puntual
|
|
184
|
-
|
|
185
|
-
```bash
|
|
186
|
-
npx ostacky uninstall agent <nombre> # también admite --scope local
|
|
187
|
-
npx ostacky uninstall agent # sin nombre → selector de instalados
|
|
188
|
-
```
|
|
189
|
-
|
|
190
|
-
Por ejemplo:
|
|
191
|
-
|
|
192
|
-
```bash
|
|
193
|
-
npx ostacky uninstall agent ostacky
|
|
194
|
-
```
|
|
195
|
-
|
|
196
|
-
#### Desinstalar un command puntual
|
|
197
|
-
|
|
198
|
-
```bash
|
|
199
|
-
npx ostacky uninstall command <nombre> # también admite --scope local
|
|
200
|
-
npx ostacky uninstall command # sin nombre → selector
|
|
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
|
|
201
93
|
```
|
|
202
94
|
|
|
203
|
-
|
|
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).
|
|
204
96
|
|
|
205
97
|
```bash
|
|
206
|
-
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
|
|
207
103
|
```
|
|
208
104
|
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
#### Desinstalar todo el stack (tools + config)
|
|
212
|
-
|
|
213
|
-
```bash
|
|
214
|
-
npx ostacky uninstall-stack # limpia mcp.codegraph/engram de opencode.json + .codegraph/ + .opencode/tools/
|
|
215
|
-
npx ostacky uninstall-stack --scope local
|
|
216
|
-
```
|
|
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.
|
|
217
106
|
|
|
218
|
-
|
|
107
|
+
## Qué se instala
|
|
219
108
|
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
```bash
|
|
223
|
-
npx ostacky --version # muestra la versión del CLI
|
|
224
|
-
npx ostacky --help # muestra la ayuda
|
|
225
|
-
```
|
|
226
|
-
|
|
227
|
-
## Estructura generada
|
|
228
|
-
|
|
229
|
-
Tras instalar (`--scope local`), el proyecto queda así:
|
|
109
|
+
Local (`<proyecto>/.opencode`) o global (mismo árbol bajo el dir global, sin stack):
|
|
230
110
|
|
|
231
111
|
```
|
|
232
112
|
.opencode/
|
|
233
|
-
├── agents/
|
|
234
|
-
|
|
235
|
-
├── commands/
|
|
236
|
-
│ ├── install-stack.md
|
|
113
|
+
├── agents/ostacky.md
|
|
114
|
+
├── commands/install-stack.md
|
|
237
115
|
│ └── opsx-sync.md
|
|
238
|
-
├── skills/
|
|
239
|
-
│
|
|
240
|
-
│
|
|
241
|
-
│
|
|
242
|
-
│ ├── execution-mode-evaluation/
|
|
243
|
-
│ ├── subagent-driven-development/
|
|
244
|
-
│ ├── dispatching-parallel-agents/
|
|
245
|
-
│ ├── openspec-propose/
|
|
246
|
-
│ ├── openspec-apply-change/
|
|
247
|
-
│ ├── openspec-archive-change/
|
|
248
|
-
│ ├── receiving-code-review/
|
|
249
|
-
│ ├── using-git-worktrees/
|
|
250
|
-
│ ├── using-superpowers/
|
|
251
|
-
│ ├── writing-skills/
|
|
252
|
-
│ └── 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
|
|
253
120
|
├── plugins/
|
|
254
|
-
│ ├── ostacky-
|
|
255
|
-
│ └── engram.ts
|
|
121
|
+
│ ├── ostacky-controller/ ← controller hard-gate (index.ts + core + security + tiered)
|
|
122
|
+
│ └── engram.ts ← plugin Engram
|
|
256
123
|
├── mcp/
|
|
257
|
-
│ ├── ostacky-controller/
|
|
124
|
+
│ ├── ostacky-controller/ ← MCP thin (observabilidad)
|
|
258
125
|
│ └── openspec/
|
|
259
|
-
├── tools/
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
├── ostacky-state.json ← estado por worktree (aislado)
|
|
264
|
-
└── 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)
|
|
265
130
|
```
|
|
266
131
|
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
### 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.
|
|
270
133
|
|
|
271
134
|
```json
|
|
272
135
|
{
|
|
273
|
-
"version": "0.
|
|
274
|
-
"
|
|
275
|
-
"
|
|
276
|
-
"
|
|
277
|
-
"
|
|
278
|
-
|
|
279
|
-
"version": "0.9.7",
|
|
280
|
-
"installedAt": "2025-01-01T00:00:00.000Z",
|
|
281
|
-
"sha256": "abc123..."
|
|
282
|
-
}
|
|
283
|
-
},
|
|
284
|
-
"commands": {
|
|
285
|
-
"install-stack": {
|
|
286
|
-
"version": "0.9.7",
|
|
287
|
-
"installedAt": "2025-01-01T00:00:00.000Z",
|
|
288
|
-
"sha256": "def456..."
|
|
289
|
-
},
|
|
290
|
-
"opsx-sync": {
|
|
291
|
-
"version": "0.9.7",
|
|
292
|
-
"installedAt": "2025-01-01T00:00:00.000Z",
|
|
293
|
-
"sha256": "ghi789..."
|
|
294
|
-
}
|
|
295
|
-
},
|
|
296
|
-
"skills": {
|
|
297
|
-
"brainstorming": { "version": "0.9.7", ... },
|
|
298
|
-
"execution-mode-evaluation": { "version": "0.9.7", ... },
|
|
299
|
-
"openspec-propose": { "version": "0.9.7", ... }
|
|
300
|
-
},
|
|
301
|
-
"mcpServers": {
|
|
302
|
-
"ostacky-controller": { "version": "0.9.7", ... },
|
|
303
|
-
"openspec": { "version": "0.9.7", ... }
|
|
304
|
-
}
|
|
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": { … } }
|
|
305
142
|
}
|
|
306
143
|
```
|
|
307
144
|
|
|
308
|
-
|
|
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.
|
|
309
146
|
|
|
310
|
-
|
|
147
|
+
## Comandos útiles
|
|
311
148
|
|
|
312
|
-
|
|
149
|
+
Engram y CodeGraph viven en `.opencode/tools/<herramienta>/bin/` y se exponen como MCP servers. Algunos comandos CLI:
|
|
313
150
|
|
|
314
|
-
|
|
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 |
|
|
315
159
|
|
|
316
|
-
|
|
317
|
-
- **TUI:** `opencode` en tu terminal → seleccioná el agente con `/agents` (o atajos **Shift+Tab** / **Ctrl+X A**)
|
|
318
|
-
- **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`
|
|
319
|
-
2. OpenCode detecta automáticamente los archivos nuevos en `.opencode/` al iniciar, no necesita recarga manual.
|
|
320
|
-
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
|
|
321
161
|
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
```text
|
|
327
|
-
/install-stack
|
|
328
|
-
```
|
|
329
|
-
|
|
330
|
-
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`.
|
|
331
166
|
|
|
332
167
|
## Seguridad
|
|
333
168
|
|
|
334
|
-
- `opencode.jsonc`
|
|
335
|
-
-
|
|
336
|
-
-
|
|
337
|
-
-
|
|
338
|
-
- El cache local (`.opencode/cache/`) también valida integridad al servir archivos cacheados
|
|
339
|
-
|
|
340
|
-
#### Restricciones de acceso a credenciales
|
|
341
|
-
|
|
342
|
-
- La configuración local de OpenCode (`opencode.jsonc`) bloquea lectura y escritura de `*.env` y `.secret/**` con `deny`.
|
|
343
|
-
- La sesión sigue ejecutándose después del bloqueo porque `experimental.continue_loop_on_deny` está activado.
|
|
344
|
-
- Para worktrees, el repo prefiere `.worktrees/` o `worktrees/` (ambos project-local).
|
|
345
|
-
|
|
346
|
-
#### Patrones sensibles configurables (hardening-v2)
|
|
347
|
-
|
|
348
|
-
- Variable `OSTACKY_SENSITIVE_PATTERNS` overridea los patrones por defecto (`**/.env*`, `**/.secrets/**`, `**/*.pem`, `**/*.key`, `**/.aws/**`, `**/.ssh/**`, `**/credentials.json`, `**/.npmrc`).
|
|
349
|
-
- Ejemplo: `OSTACKY_SENSITIVE_PATTERNS="**/.env*,**/.secrets/**" bunx ostacky doctor` — `doctor` imprime el patrón efectivo.
|
|
350
|
-
- Allowlist: `.env.example`, `.env.template`, `.env.sample` nunca se bloquean.
|
|
351
|
-
- 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.
|
|
352
|
-
|
|
353
|
-
#### Aislamiento de worktrees (harness-prod-hardening)
|
|
354
|
-
|
|
355
|
-
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`.
|
|
356
173
|
|
|
357
174
|
## Cache
|
|
358
175
|
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
```
|
|
362
|
-
.opencode/cache/<repo>/<tag>/<ruta-del-archivo>
|
|
363
|
-
```
|
|
364
|
-
|
|
365
|
-
Si ya existe un archivo en cache con el hash correcto, no se hace ninguna petición de red.
|
|
366
|
-
|
|
367
|
-
## Comandos útiles de las herramientas
|
|
368
|
-
|
|
369
|
-
### Engram (memoria persistente)
|
|
370
|
-
|
|
371
|
-
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:
|
|
372
|
-
|
|
373
|
-
| Comando | Qué hace |
|
|
374
|
-
| -------------------------------------------------------------------- | --------------------------------------------------------- |
|
|
375
|
-
| `.opencode/tools/engram/bin/engram list-projects` | Lista todos los proyectos con memoria en Engram |
|
|
376
|
-
| `.opencode/tools/engram/bin/engram clean-content --project <nombre>` | Borra el contenido de memoria de un proyecto específico |
|
|
377
|
-
| `.opencode/tools/engram/bin/engram clean-content --all` | Borra TODO el contenido de memoria de todos los proyectos |
|
|
378
|
-
| `.opencode/tools/engram/bin/engram serve` | Inicia el server de session tracking (puerto 7437) |
|
|
379
|
-
| `.opencode/tools/engram/bin/engram --version` | Muestra la versión instalada |
|
|
380
|
-
|
|
381
|
-
### CodeGraph (grafo de código)
|
|
382
|
-
|
|
383
|
-
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:
|
|
384
|
-
|
|
385
|
-
| Comando | Qué hace |
|
|
386
|
-
| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
|
|
387
|
-
| `.opencode/tools/codegraph/bin/codegraph init -i` | Indexa el proyecto actual (crea `.codegraph/` con el grafo) |
|
|
388
|
-
| `.opencode/tools/codegraph/bin/codegraph sync` | Sincroniza cambios incrementales al grafo |
|
|
389
|
-
| `.opencode/tools/codegraph/bin/codegraph status` | Muestra estado del index y archivos pendientes |
|
|
390
|
-
| `.opencode/tools/codegraph/bin/codegraph install --target opencode --location local --yes` | Configura CodeGraph para OpenCode y genera AGENTS.md |
|
|
391
|
-
|
|
392
|
-
> **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.7 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.
|
|
393
177
|
|
|
394
178
|
## Licencia
|
|
395
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
|
|
|
@@ -6,7 +6,7 @@ subagent: false
|
|
|
6
6
|
|
|
7
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.
|
|
8
8
|
|
|
9
|
-
**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.
|
|
10
10
|
|
|
11
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.
|
|
12
12
|
|
|
@@ -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,
|