@jeancodogno/specforce-kit 0.2.1 → 1.0.0-alpha.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.
- package/README.es.md +189 -0
- package/README.md +28 -10
- package/README.pt.md +189 -0
- package/index.js +13 -7
- package/package.json +7 -9
package/README.es.md
ADDED
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
|
|
2
|
+
<p align="center">
|
|
3
|
+
<a href="https://github.com/jeancodogno/specforce-kit/">
|
|
4
|
+
<picture>
|
|
5
|
+
<img src="assets/logo.png" alt="Logotipo de OpenSpec" height="128">
|
|
6
|
+
</picture>
|
|
7
|
+
</a>
|
|
8
|
+
</p>
|
|
9
|
+
<p align="center">Ecosistema para el desarrollo asistido por IA.</p>
|
|
10
|
+
|
|
11
|
+
# Specforce Kit
|
|
12
|
+
|
|
13
|
+
<p align="center">
|
|
14
|
+
<a href="https://github.com/jeancodogno/specforce-kit/releases"><img src="https://img.shields.io/github/v/release/jeancodogno/specforce-kit?style=flat-square" alt="Latest Release"></a>
|
|
15
|
+
<a href="https://github.com/jeancodogno/specforce-kit/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/jeancodogno/specforce-kit/ci.yml?branch=main&style=flat-square" alt="CI Status"></a>
|
|
16
|
+
<a href="https://goreportcard.com/report/github.com/jeancodogno/specforce-kit"><img src="https://img.shields.io/badge/go%20report-A+-brightgreen?style=flat-square" alt="Go Report Card"></a>
|
|
17
|
+
<a href="https://www.npmjs.com/package/@jeancodogno/specforce-kit"><img src="https://img.shields.io/npm/v/@jeancodogno/specforce-kit?style=flat-square" alt="NPM Version"></a>
|
|
18
|
+
<a href="go.mod"><img src="https://img.shields.io/github/go-mod/go-version/jeancodogno/specforce-kit?style=flat-square" alt="Go Version"></a>
|
|
19
|
+
<a href="https://github.com/jeancodogno/specforce-kit/issues"><img src="https://img.shields.io/github/issues/jeancodogno/specforce-kit?style=flat-square" alt="GitHub issues"></a>
|
|
20
|
+
<a href="https://github.com/jeancodogno/specforce-kit/pulls"><img src="https://img.shields.io/github/issues-pr/jeancodogno/specforce-kit?style=flat-square" alt="GitHub pull requests"></a>
|
|
21
|
+
<a href="LICENSE"><img src="https://img.shields.io/github/license/jeancodogno/specforce-kit?style=flat-square" alt="License"></a>
|
|
22
|
+
</p>
|
|
23
|
+
|
|
24
|
+
<p align="center">
|
|
25
|
+
<a href="README.md"><img src="https://img.shields.io/badge/lang-en-red.svg?style=flat-square" alt="English"></a>
|
|
26
|
+
<a href="README.pt.md"><img src="https://img.shields.io/badge/lang-pt--br-green.svg?style=flat-square" alt="Português"></a>
|
|
27
|
+
<a href="README.es.md"><img src="https://img.shields.io/badge/lang-es-yellow.svg?style=flat-square" alt="Español"></a>
|
|
28
|
+
</p>
|
|
29
|
+
|
|
30
|
+
> **La Capa de Orquestación para la Ingeniería Nativa de IA.**
|
|
31
|
+
|
|
32
|
+
Specforce Kit es un marco de trabajo de nivel profesional diseñado para coordinar agentes de IA (Claude Code, Cursor, KiloCode) a través del **Desarrollo Orientado por Especificaciones (SDD - Spec-Driven Development)**. Proporciona los **Kits**, la **Constitución** y las **Herramientas de Orquestación** estandarizadas necesarias para transformar la IA de un asistente "basado en vibras" en una fuerza de ingeniería determinista.
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## 🧠 Filosofía
|
|
37
|
+
|
|
38
|
+
En la era de la IA, la implementación es un commodity, pero el diseño es una responsabilidad. **La implementación sin una especificación está estrictamente prohibida en Specforce.**
|
|
39
|
+
|
|
40
|
+
El Desarrollo Orientado por Especificaciones (SDD) desacopla el diseño de la implementación. Una especificación actúa como un contrato estricto entre los diseñadores humanos y los ejecutores de máquinas. Al hacerlo, evitamos el "vibe coding" (la acumulación de decisiones ad-hoc y no verificadas), asegurando que su sistema permanezca coherente, seguro y mantenible, independientemente de qué agente de IA escriba el código.
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## 📊 ¿Por qué usar Specforce?
|
|
45
|
+
|
|
46
|
+
La codificación con IA sin guías estrictas conduce inevitablemente al "vibe coding": prompts vagos, resultados impredecibles y una montaña de deuda técnica que se acumula rápidamente. Aunque otras herramientas intentan resolver esto, a menudo te obligan a entrar en nuevos ecosistemas de IDE, requieren configuraciones pesadas o saturan la ventana de contexto de tu IA.
|
|
47
|
+
|
|
48
|
+
Specforce está diseñado para ser la **capa de orquestación invisible**. Aporta previsibilidad, control arquitectónico y verificación estricta a tus flujos de trabajo de IA, actuando como una máquina de estados activa en lugar de una simple colección de plantillas estáticas.
|
|
49
|
+
|
|
50
|
+
### Fortalezas Clave:
|
|
51
|
+
|
|
52
|
+
- **Constitución Segmentada**: En lugar de un único prompt masivo, las reglas se dividen en dominios especializados (Arquitectura, UI/UX, Seguridad). El agente solo carga el contexto exacto que necesita, manteniendo bajos los costos de tokens y reduciendo las alucinaciones.
|
|
53
|
+
- **Hooks de Verificación Dinámica**: Ejecuta pruebas, linters o scripts personalizados automáticamente antes de que un agente pueda marcar una tarea como finalizada.
|
|
54
|
+
- **Soporte de Git Worktree**: Descubre y visualiza de forma nativa las especificaciones en múltiples ramas de git simultáneamente sin cambiar de contexto.
|
|
55
|
+
- **Instrucciones Sensibles al Contexto**: Inyecta reglas y restricciones específicas de forma dinámica en función del artefacto o la fase en la que el agente esté trabajando.
|
|
56
|
+
- **Agnóstico a Herramientas e IDE**: Lleva el Desarrollo Orientado por Especificaciones directamente a tu terminal. Funciona a la perfección con tu IDE favorito y agentes de IA basados en CLI (Gemini, Claude, Cursor, KiloCode, etc.).
|
|
57
|
+
- **Ultrarrápido y Sin Dependencias**: Distribuido como un único binario, no requiere pesadas configuraciones de Python ni ecosistemas forzados para arrancar tu proyecto.
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## 🤖 Uso del Agente (Comandos Slash)
|
|
62
|
+
|
|
63
|
+
Specforce interactúa a la perfección con tu agente de IA preferido a través de comandos slash sencillos. Este es el flujo de trabajo estándar:
|
|
64
|
+
|
|
65
|
+
### 1. Descubrimiento (`/spf:discovery`)
|
|
66
|
+
**Comando:** `/spf:discovery {idea o informe de error}`
|
|
67
|
+
|
|
68
|
+
La fase de exploración temprana. Úsalo para intercambiar ideas sobre nuevas funciones o investigar problemas técnicos sin modificar ningún archivo.
|
|
69
|
+
- **Exploración de Solo Lectura:** El agente tiene estrictamente prohibido escribir código o artefactos. Se centra en la investigación, el análisis de la causa raíz y la estrategia técnica.
|
|
70
|
+
- **Personas Expertas:** Cambia automáticamente entre "Arquitecto Senior de Producto" (Lluvia de ideas) e "Ingeniero Senior de Sistemas" (Detective) según tu entrada.
|
|
71
|
+
- **Alineación con el Proyecto:** Lee la Constitución de tu proyecto (`.specforce/docs/`) para asegurar que todas las ideas se alineen con tus principios y arquitectura.
|
|
72
|
+
|
|
73
|
+
### 2. La Constitución (`/spf:constitution`)
|
|
74
|
+
**Comando:** `/spf:constitution {descripción del proyecto}`
|
|
75
|
+
|
|
76
|
+
El primer paso en cualquier proyecto. Esto genera la Constitución de tu proyecto, que contiene todas las reglas, principios, pautas de UI/UX, arquitectura, seguridad y memoria del agente.
|
|
77
|
+
- **Agnóstico a Herramientas y Segmentado:** En lugar de volcar las reglas en archivos específicos de la herramienta (como `.clauderc` o `.gemini/GEMINI.md`) o mantener todo en el contexto, Specforce mantiene sus propios archivos de memoria especializados y segmentados. El agente solo carga lo que necesita. Puedes cambiar de herramienta (por ejemplo, de Gemini CLI a Claude Code) y la memoria del proyecto permanece completamente intacta.
|
|
78
|
+
- **Configuración Interactiva:** Describe tu idea de proyecto y stack. El agente te hará preguntas aclaratorias para ayudarte a tomar decisiones fundamentales.
|
|
79
|
+
- **Flexible:** Ejecútalo una vez para configurar, o vuelve a ejecutarlo en cualquier momento para actualizar la constitución. Puedes usarlo en ideas nuevas o apuntarlo a un proyecto existente para analizar y documentar su arquitectura actual.
|
|
80
|
+
|
|
81
|
+
### 2. Creación de una Spec (`/spf:spec`)
|
|
82
|
+
**Comando:** `/spf:spec {descripción de qué añadir o modificar}`
|
|
83
|
+
|
|
84
|
+
¿Listo para construir? El agente aclarará tus requisitos y generará tres documentos principales: `requirements.md`, `design.md` y `tasks.md`.
|
|
85
|
+
|
|
86
|
+
### 3. Implementación (`/spf:implement`)
|
|
87
|
+
**Comando:** `/spf:implement`
|
|
88
|
+
|
|
89
|
+
Después de validar los documentos de especificación generados, ejecuta este comando. El agente seguirá estrictamente las tareas planificadas en la especificación para implementar la función, garantizando una desviación cero del diseño acordado.
|
|
90
|
+
|
|
91
|
+
### 4. Archivado (`/spf:archive`)
|
|
92
|
+
**Comando:** `/spf:archive`
|
|
93
|
+
|
|
94
|
+
Una vez que la implementación está completada y verificada, este comando analiza qué debe actualizarse en la Constitución global del proyecto basándose en la nueva implementación, y archiva la especificación completada. Sigue las **Instrucciones de Archivado** estandarizadas que aseguran que las lecciones aprendidas se capturen en el memorial del proyecto y que se realice cualquier limpieza específica del proyecto.
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
## ⚡ Toque Humano
|
|
99
|
+
|
|
100
|
+
Mientras Specforce potencia a tus agentes de IA, los humanos interactúan principalmente a través de dos comandos de terminal:
|
|
101
|
+
|
|
102
|
+
### 1. Inicialización del Proyecto
|
|
103
|
+
Configura la gobernanza y los kits de agentes para tu proyecto.
|
|
104
|
+
```bash
|
|
105
|
+
specforce init
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### 2. La Consola (TUI)
|
|
109
|
+
Inicia el centro de mando para supervisar la salud del proyecto, el progreso de las especificaciones y las implementaciones de los agentes en tiempo real.
|
|
110
|
+
```bash
|
|
111
|
+
specforce console
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## 🛠️ Agentes de IA y Herramientas Soportadas
|
|
117
|
+
|
|
118
|
+
Specforce Kit está diseñado para ser agnóstico a las herramientas, pero viene con kits preconstruidos y soporte nativo de comandos slash para los asistentes de codificación de IA más populares:
|
|
119
|
+
|
|
120
|
+
- **Gemini CLI** (Google)
|
|
121
|
+
- **Claude Code** (Anthropic)
|
|
122
|
+
- **Qwen** (Alibaba)
|
|
123
|
+
- **Kimi Code** (Moonshot AI)
|
|
124
|
+
- **OpenCode**
|
|
125
|
+
- **KiloCode**
|
|
126
|
+
- **Codex**
|
|
127
|
+
- **Antigravity**
|
|
128
|
+
|
|
129
|
+
*¿No ves tu herramienta favorita? ¡Aceptamos PRs para añadir nuevos kits!*
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## 🚀 Primeros Pasos
|
|
134
|
+
|
|
135
|
+
### Instalación
|
|
136
|
+
|
|
137
|
+
**Usando NPM (Recomendado)**
|
|
138
|
+
```bash
|
|
139
|
+
npm i -g @jeancodogno/specforce-kit
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
**Desde el Código Fuente (Requiere Go 1.26+ y Make)**
|
|
143
|
+
```bash
|
|
144
|
+
git clone https://github.com/jeancodogno/specforce-kit.git
|
|
145
|
+
cd specforce-kit
|
|
146
|
+
make build
|
|
147
|
+
make install
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
## 📚 Documentación
|
|
153
|
+
|
|
154
|
+
Para profundizar en Specforce Kit, consulta nuestra documentación oficial:
|
|
155
|
+
|
|
156
|
+
- [Primeros Pasos y Flujo de Trabajo](docs/es/getting-started.md): Configuración del entorno, primeros pasos y el ciclo de vida recomendado del Desarrollo Orientado por Especificaciones.
|
|
157
|
+
- [Soporte de Git Worktree](docs/es/git-worktrees.md): Guía para el descubrimiento de especificaciones entre ramas, consola unificada y restricciones de solo lectura.
|
|
158
|
+
- [Artefactos](docs/es/artifacts.md): Detalles sobre los archivos generados (Constitución, Requisitos, Diseño, Tareas).
|
|
159
|
+
- [Configuración](docs/es/configuration.md): Guía para personalizar hooks e instrucciones.
|
|
160
|
+
- [Referencia de la CLI](docs/es/cli.md): Uso de la terminal y comandos slash.
|
|
161
|
+
- [Herramientas Soportadas](docs/es/supported-tools.md): Lista de agentes de IA y asistentes de codificación soportados de forma nativa.
|
|
162
|
+
|
|
163
|
+
---
|
|
164
|
+
|
|
165
|
+
## 🔍 Resolución de Problemas
|
|
166
|
+
|
|
167
|
+
### "command not found: specforce"
|
|
168
|
+
Si te encuentras con este error después de la instalación, suele significar que el directorio bin global de npm no está en el `PATH` de tu sistema.
|
|
169
|
+
|
|
170
|
+
**Solución para macOS/Linux:**
|
|
171
|
+
Añade la siguiente línea a tu perfil de shell (por ejemplo, `~/.zshrc` o `~/.bashrc`):
|
|
172
|
+
```bash
|
|
173
|
+
export PATH="$(npm config get prefix)/bin:$PATH"
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
**Solución para Windows:**
|
|
177
|
+
Asegúrate de que `%AppData%\npm` esté en tus variables de entorno.
|
|
178
|
+
|
|
179
|
+
Para una resolución de problemas más detallada, consulta [Primeros Pasos: Resolución de Problemas](docs/es/getting-started.md#troubleshooting).
|
|
180
|
+
|
|
181
|
+
---
|
|
182
|
+
|
|
183
|
+
## 🤝 Contribuir
|
|
184
|
+
¡Agradecemos las contribuciones! Consulta nuestro [CONTRIBUTING.md](CONTRIBUTING.md) para aprender cómo añadir soporte para nuevos agentes de IA o mejorar los kits existentes.
|
|
185
|
+
|
|
186
|
+
---
|
|
187
|
+
|
|
188
|
+
## 📜 Licencia
|
|
189
|
+
Specforce Kit se publica bajo la **Licencia MIT**. Consulta [LICENSE](LICENSE) para más detalles.
|
package/README.md
CHANGED
|
@@ -10,6 +10,23 @@
|
|
|
10
10
|
|
|
11
11
|
# Specforce Kit
|
|
12
12
|
|
|
13
|
+
<p align="center">
|
|
14
|
+
<a href="https://github.com/jeancodogno/specforce-kit/releases"><img src="https://img.shields.io/github/v/release/jeancodogno/specforce-kit?style=flat-square" alt="Latest Release"></a>
|
|
15
|
+
<a href="https://github.com/jeancodogno/specforce-kit/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/jeancodogno/specforce-kit/ci.yml?branch=main&style=flat-square" alt="CI Status"></a>
|
|
16
|
+
<a href="https://goreportcard.com/report/github.com/jeancodogno/specforce-kit"><img src="https://img.shields.io/badge/go%20report-A+-brightgreen?style=flat-square" alt="Go Report Card"></a>
|
|
17
|
+
<a href="https://www.npmjs.com/package/@jeancodogno/specforce-kit"><img src="https://img.shields.io/npm/v/@jeancodogno/specforce-kit?style=flat-square" alt="NPM Version"></a>
|
|
18
|
+
<a href="go.mod"><img src="https://img.shields.io/github/go-mod/go-version/jeancodogno/specforce-kit?style=flat-square" alt="Go Version"></a>
|
|
19
|
+
<a href="https://github.com/jeancodogno/specforce-kit/issues"><img src="https://img.shields.io/github/issues/jeancodogno/specforce-kit?style=flat-square" alt="GitHub issues"></a>
|
|
20
|
+
<a href="https://github.com/jeancodogno/specforce-kit/pulls"><img src="https://img.shields.io/github/issues-pr/jeancodogno/specforce-kit?style=flat-square" alt="GitHub pull requests"></a>
|
|
21
|
+
<a href="LICENSE"><img src="https://img.shields.io/github/license/jeancodogno/specforce-kit?style=flat-square" alt="License"></a>
|
|
22
|
+
</p>
|
|
23
|
+
|
|
24
|
+
<p align="center">
|
|
25
|
+
<a href="README.md"><img src="https://img.shields.io/badge/lang-en-red.svg?style=flat-square" alt="English"></a>
|
|
26
|
+
<a href="README.pt.md"><img src="https://img.shields.io/badge/lang-pt--br-green.svg?style=flat-square" alt="Português"></a>
|
|
27
|
+
<a href="README.es.md"><img src="https://img.shields.io/badge/lang-es-yellow.svg?style=flat-square" alt="Español"></a>
|
|
28
|
+
</p>
|
|
29
|
+
|
|
13
30
|
> **The Orchestration Layer for AI-Native Engineering.**
|
|
14
31
|
|
|
15
32
|
Specforce Kit is a professional-grade framework designed to coordinate AI agents (Claude Code, Cursor, KiloCode) through **Spec-Driven Development (SDD)**. It provides the standardized **Kits**, **Constitution**, and **Orchestration Tools** required to transform AI from a "vibe-based" assistant into a deterministic engineering force.
|
|
@@ -122,12 +139,13 @@ Specforce Kit is designed to be tool-agnostic but comes with pre-built kits and
|
|
|
122
139
|
npm i -g @jeancodogno/specforce-kit
|
|
123
140
|
```
|
|
124
141
|
|
|
125
|
-
**From Source (Requires Go 1.
|
|
142
|
+
**From Source (Requires Go 1.24+ & Make)**
|
|
126
143
|
```bash
|
|
127
144
|
git clone https://github.com/jeancodogno/specforce-kit.git
|
|
128
145
|
cd specforce-kit
|
|
129
146
|
make build
|
|
130
|
-
|
|
147
|
+
# Binary 'specforce' is created in the root.
|
|
148
|
+
# You can move it to your PATH manually or run it from here.
|
|
131
149
|
```
|
|
132
150
|
|
|
133
151
|
---
|
|
@@ -136,12 +154,12 @@ make install
|
|
|
136
154
|
|
|
137
155
|
For a deeper dive into Specforce Kit, check out our official documentation:
|
|
138
156
|
|
|
139
|
-
- [Getting Started & Workflow](docs/getting-started.md): Environment setup, first steps, and the recommended Spec-Driven Development lifecycle.
|
|
140
|
-
- [Git Worktree Support](docs/git-worktrees.md): Guide to cross-branch specification discovery, unified console, and read-only constraints.
|
|
141
|
-
- [Artifacts](docs/artifacts.md): Details about the generated files (Constitution, Requirements, Design, Tasks).
|
|
142
|
-
- [Configuration](docs/configuration.md): Guide to customize hooks and instructions.
|
|
143
|
-
- [CLI Reference](docs/cli.md): Terminal and slash command usage.
|
|
144
|
-
- [Supported Tools](docs/supported-tools.md): List of natively supported AI agents and coding assistants.
|
|
157
|
+
- [Getting Started & Workflow](docs/en/getting-started.md): Environment setup, first steps, and the recommended Spec-Driven Development lifecycle.
|
|
158
|
+
- [Git Worktree Support](docs/en/git-worktrees.md): Guide to cross-branch specification discovery, unified console, and read-only constraints.
|
|
159
|
+
- [Artifacts](docs/en/artifacts.md): Details about the generated files (Constitution, Requirements, Design, Tasks).
|
|
160
|
+
- [Configuration](docs/en/configuration.md): Guide to customize hooks and instructions.
|
|
161
|
+
- [CLI Reference](docs/en/cli.md): Terminal and slash command usage.
|
|
162
|
+
- [Supported Tools](docs/en/supported-tools.md): List of natively supported AI agents and coding assistants.
|
|
145
163
|
|
|
146
164
|
---
|
|
147
165
|
|
|
@@ -159,7 +177,7 @@ export PATH="$(npm config get prefix)/bin:$PATH"
|
|
|
159
177
|
**Fix for Windows:**
|
|
160
178
|
Ensure that `%AppData%\npm` is in your environment variables.
|
|
161
179
|
|
|
162
|
-
For more detailed troubleshooting, see [Getting Started: Troubleshooting](docs/getting-started.md#troubleshooting).
|
|
180
|
+
For more detailed troubleshooting, see [Getting Started: Troubleshooting](docs/en/getting-started.md#troubleshooting).
|
|
163
181
|
|
|
164
182
|
---
|
|
165
183
|
|
|
@@ -169,4 +187,4 @@ We welcome contributions! See our [CONTRIBUTING.md](CONTRIBUTING.md) to learn ho
|
|
|
169
187
|
---
|
|
170
188
|
|
|
171
189
|
## 📜 License
|
|
172
|
-
Specforce Kit is released under the **MIT License**. See [LICENSE](LICENSE) for details.
|
|
190
|
+
Specforce Kit is released under the **MIT License**. See [LICENSE](LICENSE) for details.pecforce Kit is released under the **MIT License**. See [LICENSE](LICENSE) for details.
|
package/README.pt.md
ADDED
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
|
|
2
|
+
<p align="center">
|
|
3
|
+
<a href="https://github.com/jeancodogno/specforce-kit/">
|
|
4
|
+
<picture>
|
|
5
|
+
<img src="assets/logo.png" alt="Logo OpenSpec" height="128">
|
|
6
|
+
</picture>
|
|
7
|
+
</a>
|
|
8
|
+
</p>
|
|
9
|
+
<p align="center">Ecossistema para desenvolvimento assistido por IA.</p>
|
|
10
|
+
|
|
11
|
+
# Specforce Kit
|
|
12
|
+
|
|
13
|
+
<p align="center">
|
|
14
|
+
<a href="https://github.com/jeancodogno/specforce-kit/releases"><img src="https://img.shields.io/github/v/release/jeancodogno/specforce-kit?style=flat-square" alt="Latest Release"></a>
|
|
15
|
+
<a href="https://github.com/jeancodogno/specforce-kit/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/jeancodogno/specforce-kit/ci.yml?branch=main&style=flat-square" alt="CI Status"></a>
|
|
16
|
+
<a href="https://goreportcard.com/report/github.com/jeancodogno/specforce-kit"><img src="https://img.shields.io/badge/go%20report-A+-brightgreen?style=flat-square" alt="Go Report Card"></a>
|
|
17
|
+
<a href="https://www.npmjs.com/package/@jeancodogno/specforce-kit"><img src="https://img.shields.io/npm/v/@jeancodogno/specforce-kit?style=flat-square" alt="NPM Version"></a>
|
|
18
|
+
<a href="go.mod"><img src="https://img.shields.io/github/go-mod/go-version/jeancodogno/specforce-kit?style=flat-square" alt="Go Version"></a>
|
|
19
|
+
<a href="https://github.com/jeancodogno/specforce-kit/issues"><img src="https://img.shields.io/github/issues/jeancodogno/specforce-kit?style=flat-square" alt="GitHub issues"></a>
|
|
20
|
+
<a href="https://github.com/jeancodogno/specforce-kit/pulls"><img src="https://img.shields.io/github/issues-pr/jeancodogno/specforce-kit?style=flat-square" alt="GitHub pull requests"></a>
|
|
21
|
+
<a href="LICENSE"><img src="https://img.shields.io/github/license/jeancodogno/specforce-kit?style=flat-square" alt="License"></a>
|
|
22
|
+
</p>
|
|
23
|
+
|
|
24
|
+
<p align="center">
|
|
25
|
+
<a href="README.md"><img src="https://img.shields.io/badge/lang-en-red.svg?style=flat-square" alt="English"></a>
|
|
26
|
+
<a href="README.pt.md"><img src="https://img.shields.io/badge/lang-pt--br-green.svg?style=flat-square" alt="Português"></a>
|
|
27
|
+
<a href="README.es.md"><img src="https://img.shields.io/badge/lang-es-yellow.svg?style=flat-square" alt="Español"></a>
|
|
28
|
+
</p>
|
|
29
|
+
|
|
30
|
+
> **A Camada de Orquestração para Engenharia Nativa de IA.**
|
|
31
|
+
|
|
32
|
+
O Specforce Kit é um framework de nível profissional projetado para coordenar agentes de IA (Claude Code, Cursor, KiloCode) através do **Desenvolvimento Orientado por Especificação (SDD - Spec-Driven Development)**. Ele fornece os **Kits**, a **Constituição** e as **Ferramentas de Orquestração** padronizadas necessárias para transformar a IA de um assistente "baseado em vibes" em uma força de engenharia determinística.
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## 🧠 Filosofia
|
|
37
|
+
|
|
38
|
+
Na era da IA, a implementação é uma commodity, mas o design é uma responsabilidade. **A implementação sem uma especificação é estritamente proibida no Specforce.**
|
|
39
|
+
|
|
40
|
+
O Desenvolvimento Orientado por Especificação (SDD) desacopla o design da implementação. Uma especificação atua como um contrato rigoroso entre designers humanos e executores de máquina. Ao fazer isso, evitamos o "vibe coding" - o acúmulo de decisões ad-hoc e não verificadas - garantindo que seu sistema permaneça coerente, seguro e sustentável, independentemente de qual agente de IA escreva o código.
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## 📊 Por que usar o Specforce?
|
|
45
|
+
|
|
46
|
+
A codificação por IA sem diretrizes rígidas leva inevitavelmente ao "vibe coding": prompts vagos, resultados imprevisíveis e uma montanha de dívida técnica que se acumula rapidamente. Embora outras ferramentas tentem resolver isso, elas muitas vezes forçam você a novos ecossistemas de IDE, exigem configurações pesadas ou incham a janela de contexto da sua IA.
|
|
47
|
+
|
|
48
|
+
O Specforce foi projetado para ser a **camada de orquestração invisível**. Ele traz previsibilidade, controle arquitetônico e verificação rigorosa aos seus fluxos de trabalho de IA, atuando como uma máquina de estados ativa em vez de apenas uma coleção de templates estáticos.
|
|
49
|
+
|
|
50
|
+
### Principais Diferenciais:
|
|
51
|
+
|
|
52
|
+
- **Constituição Segmentada**: Em vez de um único prompt massivo, as regras são divididas em domínios especializados (Arquitetura, UI/UX, Segurança). O agente carrega apenas o contexto exato de que precisa, mantendo os custos de tokens baixos e reduzindo alucinações.
|
|
53
|
+
- **Hooks de Verificação Dinâmica**: Execute testes, linters ou scripts personalizados automaticamente antes que um agente seja autorizado a marcar uma tarefa como finalizada.
|
|
54
|
+
- **Suporte a Git Worktree**: Descubra e visualize nativamente especificações em múltiplas branches git simultaneamente, sem trocar de contexto.
|
|
55
|
+
- **Instruções Sensíveis ao Contexto**: Injete regras e restrições específicas dinamicamente com base no artefato ou fase em que o agente está trabalhando.
|
|
56
|
+
- **Agnóstico a Ferramentas e IDEs**: Traga o Desenvolvimento Orientado por Especificação diretamente para o seu terminal. Funciona perfeitamente com sua IDE favorita e agentes de IA baseados em CLI (Gemini, Claude, Cursor, KiloCode, etc).
|
|
57
|
+
- **Rápido e Sem Dependências**: Distribuído como um único binário, sem necessidade de configurações pesadas de Python ou ecossistemas forçados para iniciar seu projeto.
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## 🤖 Uso pelo Agente (Comandos Slash)
|
|
62
|
+
|
|
63
|
+
O Specforce interage perfeitamente com seu agente de IA preferido através de comandos slash simples. Aqui está o fluxo de trabalho padrão:
|
|
64
|
+
|
|
65
|
+
### 1. Descoberta (`/spf:discovery`)
|
|
66
|
+
**Comando:** `/spf:discovery {ideia ou relatório de erro}`
|
|
67
|
+
|
|
68
|
+
A fase inicial de exploração. Use isso para debater novas funcionalidades ou investigar problemas técnicos sem modificar nenhum arquivo.
|
|
69
|
+
- **Exploração Somente Leitura:** O agente é estritamente proibido de escrever código ou artefatos. Ele se concentra em pesquisa, análise de causa raiz e estratégia técnica.
|
|
70
|
+
- **Personas Especialistas:** Alterna automaticamente entre "Arquiteto de Produto Sênior" (Brainstorming) e "Engenheiro de Sistemas Sênior" (Detetive) com base na sua entrada.
|
|
71
|
+
- **Alinhamento com o Projeto:** Lê a Constituição do seu projeto (`.specforce/docs/`) para garantir que todas as ideias estejam alinhadas com seus princípios e arquitetura.
|
|
72
|
+
|
|
73
|
+
### 2. A Constituição (`/spf:constitution`)
|
|
74
|
+
**Comando:** `/spf:constitution {descrição do projeto}`
|
|
75
|
+
|
|
76
|
+
O primeiro passo em qualquer projeto. Isso gera a Constituição do seu projeto, contendo todas as regras, princípios, diretrizes de UI/UX, arquitetura, segurança e memória do agente.
|
|
77
|
+
- **Agnóstico a Ferramentas e Segmentado:** Em vez de despejar regras em arquivos específicos de ferramentas (como `.clauderc` ou `.gemini/GEMINI.md`) ou manter tudo no contexto, o Specforce mantém seus próprios arquivos de memória especializados e segmentados. O agente carrega apenas o que precisa. Você pode trocar de ferramenta (ex: de Gemini CLI para Claude Code) e a memória do projeto permanece completamente intacta.
|
|
78
|
+
- **Configuração Interativa:** Descreva sua ideia de projeto e stack. O agente fará perguntas esclarecedoras para ajudá-lo a tomar decisões fundamentais.
|
|
79
|
+
- **Flexível:** Execute uma vez para configurar, ou execute novamente a qualquer momento para atualizar a constituição. Você pode usá-lo em ideias novas ou apontá-lo para um projeto existente para analisar e documentar sua arquitetura atual.
|
|
80
|
+
|
|
81
|
+
### 2. Criando uma Spec (`/spf:spec`)
|
|
82
|
+
**Comando:** `/spf:spec {descrição do que adicionar ou modificar}`
|
|
83
|
+
|
|
84
|
+
Pronto para construir? O agente esclarecerá seus requisitos e gerará três documentos principais: `requirements.md`, `design.md` e `tasks.md`.
|
|
85
|
+
|
|
86
|
+
### 3. Implementação (`/spf:implement`)
|
|
87
|
+
**Comando:** `/spf:implement`
|
|
88
|
+
|
|
89
|
+
Após validar os documentos de especificação gerados, execute este comando. O agente seguirá estritamente as tarefas planejadas na spec para implementar a funcionalidade, garantindo desvio zero do design acordado.
|
|
90
|
+
|
|
91
|
+
### 4. Arquivamento (`/spf:archive`)
|
|
92
|
+
**Comando:** `/spf:archive`
|
|
93
|
+
|
|
94
|
+
Assim que a implementação estiver totalmente concluída e verificada, este comando analisa o que precisa ser atualizado na Constituição global do projeto com base na nova implementação e arquiva a spec concluída. Ele segue **Instruções de Arquivamento** padronizadas que garantem que as lições aprendidas sejam capturadas no memorial do projeto e qualquer limpeza específica do projeto seja realizada.
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
## ⚡ Toque Humano
|
|
99
|
+
|
|
100
|
+
Enquanto o Specforce potencializa seus agentes de IA, os humanos interagem principalmente através de dois comandos de terminal:
|
|
101
|
+
|
|
102
|
+
### 1. Inicialização do Projeto
|
|
103
|
+
Configure a governança e os kits de agentes para o seu projeto.
|
|
104
|
+
```bash
|
|
105
|
+
specforce init
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### 2. O Console (TUI)
|
|
109
|
+
Inicie o centro de comando para monitorar a saúde do projeto, o progresso das especificações e as implementações dos agentes em tempo real.
|
|
110
|
+
```bash
|
|
111
|
+
specforce console
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## 🛠️ Agentes de IA e Ferramentas Suportadas
|
|
117
|
+
|
|
118
|
+
O Specforce Kit foi projetado para ser agnóstico a ferramentas, mas vem com kits pré-construídos e suporte nativo a comandos slash para os assistentes de codificação de IA mais populares:
|
|
119
|
+
|
|
120
|
+
- **Gemini CLI** (Google)
|
|
121
|
+
- **Claude Code** (Anthropic)
|
|
122
|
+
- **Qwen** (Alibaba)
|
|
123
|
+
- **Kimi Code** (Moonshot AI)
|
|
124
|
+
- **OpenCode**
|
|
125
|
+
- **KiloCode**
|
|
126
|
+
- **Codex**
|
|
127
|
+
- **Antigravity**
|
|
128
|
+
|
|
129
|
+
*Não vê sua ferramenta favorita? Aceitamos PRs para adicionar novos kits!*
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## 🚀 Primeiros Passos
|
|
134
|
+
|
|
135
|
+
### Instalação
|
|
136
|
+
|
|
137
|
+
**Usando NPM (Recomendado)**
|
|
138
|
+
```bash
|
|
139
|
+
npm i -g @jeancodogno/specforce-kit
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
**A partir do Código Fonte (Requer Go 1.26+ e Make)**
|
|
143
|
+
```bash
|
|
144
|
+
git clone https://github.com/jeancodogno/specforce-kit.git
|
|
145
|
+
cd specforce-kit
|
|
146
|
+
make build
|
|
147
|
+
make install
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
## 📚 Documentação
|
|
153
|
+
|
|
154
|
+
Para um mergulho mais profundo no Specforce Kit, confira nossa documentação oficial:
|
|
155
|
+
|
|
156
|
+
- [Primeiros Passos e Fluxo de Trabalho](docs/pt/getting-started.md): Configuração do ambiente, primeiros passos e o ciclo de vida recomendado do Desenvolvimento Orientado por Especificação.
|
|
157
|
+
- [Suporte a Git Worktree](docs/pt/git-worktrees.md): Guia para descoberta de especificações entre branches, console unificado e restrições de apenas leitura.
|
|
158
|
+
- [Artefatos](docs/pt/artifacts.md): Detalhes sobre os arquivos gerados (Constituição, Requisitos, Design, Tarefas).
|
|
159
|
+
- [Configuração](docs/pt/configuration.md): Guia para personalizar hooks e instruções.
|
|
160
|
+
- [Referência da CLI](docs/pt/cli.md): Uso do terminal e comandos slash.
|
|
161
|
+
- [Ferramentas Suportadas](docs/pt/supported-tools.md): Lista de agentes de IA e assistentes de codificação suportados nativamente.
|
|
162
|
+
|
|
163
|
+
---
|
|
164
|
+
|
|
165
|
+
## 🔍 Resolução de Problemas
|
|
166
|
+
|
|
167
|
+
### "command not found: specforce"
|
|
168
|
+
Se você encontrar este erro após a instalação, geralmente significa que o diretório bin global do npm não está no `PATH` do seu sistema.
|
|
169
|
+
|
|
170
|
+
**Correção para macOS/Linux:**
|
|
171
|
+
Adicione a seguinte linha ao seu perfil de shell (ex: `~/.zshrc` ou `~/.bashrc`):
|
|
172
|
+
```bash
|
|
173
|
+
export PATH="$(npm config get prefix)/bin:$PATH"
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
**Correção para Windows:**
|
|
177
|
+
Certifique-se de que `%AppData%\npm` esteja em suas variáveis de ambiente.
|
|
178
|
+
|
|
179
|
+
Para uma resolução de problemas mais detalhada, veja [Primeiros Passos: Resolução de Problemas](docs/pt/getting-started.md#troubleshooting).
|
|
180
|
+
|
|
181
|
+
---
|
|
182
|
+
|
|
183
|
+
## 🤝 Contribuindo
|
|
184
|
+
Contribuições são bem-vindas! Veja nosso [CONTRIBUTING.md](CONTRIBUTING.md) para aprender como adicionar suporte para novos agentes de IA ou melhorar os kits existentes.
|
|
185
|
+
|
|
186
|
+
---
|
|
187
|
+
|
|
188
|
+
## 📜 Licença
|
|
189
|
+
O Specforce Kit é lançado sob a **Licença MIT**. Veja [LICENSE](LICENSE) para detalhes.
|
package/index.js
CHANGED
|
@@ -1,11 +1,14 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
|
|
3
2
|
const { spawnSync } = require('child_process');
|
|
4
3
|
const path = require('path');
|
|
4
|
+
const fs = require('fs');
|
|
5
5
|
|
|
6
6
|
/**
|
|
7
7
|
* SpecForce Kit Proxy
|
|
8
|
-
*
|
|
8
|
+
*
|
|
9
|
+
* SECURITY NOTE: This proxy uses 'child_process.spawnSync' to execute native binaries.
|
|
10
|
+
* To prevent shell injection, we NEVER use 'shell: true' and always pass arguments
|
|
11
|
+
* as an explicit array. All paths are validated to be absolute before execution.
|
|
9
12
|
*/
|
|
10
13
|
|
|
11
14
|
const platform = process.platform;
|
|
@@ -19,15 +22,14 @@ try {
|
|
|
19
22
|
const pkgJsonPath = require.resolve(`${pkgName}/package.json`);
|
|
20
23
|
const pkgDir = path.dirname(pkgJsonPath);
|
|
21
24
|
const pkgJson = require(pkgJsonPath);
|
|
22
|
-
|
|
25
|
+
|
|
23
26
|
// 2. Extract binary path from package.json bin field
|
|
24
27
|
const binRelativePath = typeof pkgJson.bin === 'string' ? pkgJson.bin : pkgJson.bin.specforce;
|
|
25
28
|
binaryPath = path.resolve(pkgDir, binRelativePath);
|
|
26
29
|
} catch (e) {
|
|
27
|
-
// Fallback 1: Look for a binary in the root (built via 'make build'
|
|
30
|
+
// Fallback 1: Look for a binary in the root (built via 'make build')
|
|
28
31
|
const localBinaryName = platform === 'win32' ? 'specforce.exe' : 'specforce';
|
|
29
32
|
const rootBinaryPath = path.join(__dirname, localBinaryName);
|
|
30
|
-
const fs = require('fs');
|
|
31
33
|
|
|
32
34
|
if (fs.existsSync(rootBinaryPath)) {
|
|
33
35
|
binaryPath = rootBinaryPath;
|
|
@@ -45,12 +47,16 @@ try {
|
|
|
45
47
|
}
|
|
46
48
|
}
|
|
47
49
|
|
|
50
|
+
// Security Hardening: Ensure binaryPath is absolute and exists before execution
|
|
51
|
+
if (!binaryPath || !path.isAbsolute(binaryPath) || !fs.existsSync(binaryPath)) {
|
|
52
|
+
runDiagnostic(platform, arch, pkgName);
|
|
53
|
+
process.exit(1);
|
|
54
|
+
}
|
|
55
|
+
|
|
48
56
|
/**
|
|
49
57
|
* Runs a diagnostic check to help the user fix their environment.
|
|
50
58
|
*/
|
|
51
59
|
function runDiagnostic(platform, arch, pkgName) {
|
|
52
|
-
const fs = require('fs');
|
|
53
|
-
|
|
54
60
|
// Aesthetic Colors
|
|
55
61
|
const RESET = "\x1b[0m";
|
|
56
62
|
const BOLD = "\x1b[1m";
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jeancodogno/specforce-kit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "1.0.0-alpha.1",
|
|
4
4
|
"description": "SpecForce Kit CLI - Distributed via Native Binaries",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -15,20 +15,18 @@
|
|
|
15
15
|
},
|
|
16
16
|
"scripts": {
|
|
17
17
|
"build": "make build",
|
|
18
|
-
"test": "go test ./..."
|
|
19
|
-
"prepare": "make build || true",
|
|
20
|
-
"postinstall": "make build || true"
|
|
18
|
+
"test": "go test ./..."
|
|
21
19
|
},
|
|
22
20
|
"files": [
|
|
23
21
|
"index.js",
|
|
24
22
|
"LICENSE"
|
|
25
23
|
],
|
|
26
24
|
"optionalDependencies": {
|
|
27
|
-
"@jeancodogno/specforce-kit-linux-x64": "0.
|
|
28
|
-
"@jeancodogno/specforce-kit-linux-arm64": "0.
|
|
29
|
-
"@jeancodogno/specforce-kit-darwin-x64": "0.
|
|
30
|
-
"@jeancodogno/specforce-kit-darwin-arm64": "0.
|
|
31
|
-
"@jeancodogno/specforce-kit-win32-x64": "0.
|
|
25
|
+
"@jeancodogno/specforce-kit-linux-x64": "1.0.0-alpha.1",
|
|
26
|
+
"@jeancodogno/specforce-kit-linux-arm64": "1.0.0-alpha.1",
|
|
27
|
+
"@jeancodogno/specforce-kit-darwin-x64": "1.0.0-alpha.1",
|
|
28
|
+
"@jeancodogno/specforce-kit-darwin-arm64": "1.0.0-alpha.1",
|
|
29
|
+
"@jeancodogno/specforce-kit-win32-x64": "1.0.0-alpha.1"
|
|
32
30
|
},
|
|
33
31
|
"author": "Jean Codogno <jeancarlo.eng.comp@gmail.com>",
|
|
34
32
|
"license": "MIT"
|