orca-multiagent-kit 0.0.0-stage → 1.2.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.
Files changed (73) hide show
  1. package/AI_INSTALL.md +49 -0
  2. package/CHANGELOG.md +79 -0
  3. package/GUIA.html +401 -0
  4. package/LICENSE +21 -0
  5. package/README.md +240 -2
  6. package/VERSION +1 -0
  7. package/bin/omk.js +175 -0
  8. package/bin/ui.js +165 -0
  9. package/core/AGENTS.md +80 -0
  10. package/docs/MANUAL.md +208 -0
  11. package/install.sh +403 -0
  12. package/output-styles/csr-minimal.md +14 -0
  13. package/package.json +23 -4
  14. package/rules/00-router.md +28 -0
  15. package/rules/10-communication.md +58 -0
  16. package/rules/20-clean-code.md +59 -0
  17. package/rules/30-security.md +81 -0
  18. package/rules/31-security-audit.md +58 -0
  19. package/rules/40-testing.md +48 -0
  20. package/rules/50-done-gate.md +66 -0
  21. package/rules/60-git-workflow.md +49 -0
  22. package/rules/70-performance.md +36 -0
  23. package/rules/75-reliability.md +36 -0
  24. package/rules/80-supply-chain.md +35 -0
  25. package/rules/90-docs-comments.md +36 -0
  26. package/rules/95-multi-agent.md +56 -0
  27. package/rules/lang/cpp.md +26 -0
  28. package/rules/lang/csharp.md +27 -0
  29. package/rules/lang/dart-flutter.md +26 -0
  30. package/rules/lang/go.md +30 -0
  31. package/rules/lang/infra.md +33 -0
  32. package/rules/lang/java.md +29 -0
  33. package/rules/lang/kotlin.md +25 -0
  34. package/rules/lang/php.md +27 -0
  35. package/rules/lang/python.md +33 -0
  36. package/rules/lang/react.md +32 -0
  37. package/rules/lang/ruby.md +23 -0
  38. package/rules/lang/rust.md +32 -0
  39. package/rules/lang/shell.md +24 -0
  40. package/rules/lang/sql.md +29 -0
  41. package/rules/lang/swift.md +31 -0
  42. package/rules/lang/typescript.md +32 -0
  43. package/rules/lang/web.md +31 -0
  44. package/skills/csr-audit/SKILL.md +14 -0
  45. package/skills/csr-gate/SKILL.md +16 -0
  46. package/skills/csr-stack/SKILL.md +23 -0
  47. package/skills/kit-init/SKILL.md +61 -0
  48. package/skills/orca/SKILL.md +88 -0
  49. package/skills/orca/references/adapters/artifact.md +32 -0
  50. package/skills/orca/references/adapters/chat.md +33 -0
  51. package/skills/orca/references/adapters/native-plan.md +18 -0
  52. package/skills/orca/references/adapters/plan-file.md +20 -0
  53. package/skills/orca/references/adapters/speckit.md +42 -0
  54. package/skills/orca/references/engine-manual.md +30 -0
  55. package/skills/orca/references/engine-orca.md +36 -0
  56. package/skills/orca/references/engine-subagents.md +19 -0
  57. package/skills/orca/references/integrate.md +37 -0
  58. package/skills/orca/references/plan.md +48 -0
  59. package/skills/orca/references/race.md +35 -0
  60. package/skills/orca/references/setup.md +26 -0
  61. package/skills/orca/references/units.md +44 -0
  62. package/skills/orca/references/worker-contract.md +49 -0
  63. package/skills/speckit-orca-implement/SKILL.md +17 -0
  64. package/speckit-extension/orca/README.md +15 -0
  65. package/speckit-extension/orca/commands/implement.md +16 -0
  66. package/speckit-extension/orca/extension.yml +26 -0
  67. package/templates/.worktreeinclude +4 -0
  68. package/templates/AGENTS.md +13 -0
  69. package/templates/CLAUDE.md +4 -0
  70. package/templates/ORCHESTRATION.md +49 -0
  71. package/templates/STACK.md +91 -0
  72. package/templates/claude-settings.json +27 -0
  73. package/templates/orca.yaml +5 -0
@@ -0,0 +1,33 @@
1
+ # Infraestructura: Docker, Kubernetes, Terraform, CI, YAML
2
+ **Gates**: `hadolint` · `trivy fs .` y `trivy image` · `checkov -d .` · `tfsec` · `terraform validate` + `plan` revisado · `kube-score`/`kubeconform` · `actionlint` · `yamllint`
3
+
4
+ ## Docker
5
+ - Imagen base mínima y **fijada por digest** (`node:22-alpine@sha256:...`); multi-stage para no arrastrar herramientas de build.
6
+ - `USER` no root, sistema de ficheros de solo lectura cuando se pueda, `--cap-drop ALL`.
7
+ - Sin secretos en `ENV`, ni en argumentos de build, ni en capas intermedias (quedan en el historial). Usa montajes de secreto de BuildKit.
8
+ - `.dockerignore` que excluya `.git`, `.env`, `node_modules`, artefactos.
9
+ - `HEALTHCHECK` definido; señales gestionadas (`exec` form de `CMD`, init si hace falta reaper de zombies).
10
+ - Escaneo de la imagen antes de publicar; reconstruye para recoger parches de la base.
11
+
12
+ ## Kubernetes
13
+ - `requests` y `limits` en todo contenedor; `livenessProbe` y `readinessProbe` distintas.
14
+ - `securityContext`: `runAsNonRoot`, `readOnlyRootFilesystem`, `allowPrivilegeEscalation: false`, `seccompProfile: RuntimeDefault`.
15
+ - NetworkPolicy por defecto denegando; ServiceAccount dedicada con RBAC mínimo; sin `cluster-admin`.
16
+ - Secretos por gestor externo (External Secrets, Vault, SOPS); nunca en el repo ni en `ConfigMap`.
17
+ - `PodDisruptionBudget`, estrategia de despliegue y rollback definidos; sin `latest` como tag.
18
+
19
+ ## Terraform / IaC
20
+ - Estado remoto con bloqueo y cifrado; nunca estado local en equipo compartido.
21
+ - Versiones fijadas de proveedores y módulos; `plan` revisado por humano antes de `apply`; `apply` automático solo con aprobación.
22
+ - Sin secretos en variables planas ni en el estado si se puede evitar; marca `sensitive`.
23
+ - Principio de mínimo privilegio en IAM: nada de `*:*`. Cifrado en reposo y en tránsito por defecto. Logs y auditoría activados.
24
+ - Etiquetado consistente (dueño, entorno, coste) y entornos separados por cuenta o proyecto.
25
+
26
+ ## CI/CD
27
+ - Acciones de terceros ancladas por SHA; permisos del token mínimos; sin secretos accesibles desde PR de forks.
28
+ - Gates bloqueantes: format, lint, typecheck, build, test, cobertura, `gitleaks`, SAST, auditoría de dependencias.
29
+ - Construcción reproducible, artefactos con checksum o firma, SBOM en release.
30
+ - Despliegue con rollback de un paso y salud verificada tras el cambio.
31
+
32
+ ## YAML
33
+ Indentación de 2 espacios, sin tabuladores · comilla las cadenas ambiguas (`yes`, `no`, `on`, versiones como `1.10`) · sin anclas crípticas · valida contra esquema cuando exista.
@@ -0,0 +1,29 @@
1
+ # Java (y Spring Boot / Quarkus)
2
+ **Gates**: `mvn -q verify` o `gradle check` · Spotless/Checkstyle · SpotBugs + find-sec-bugs · `mvn dependency-check` u OSV · JaCoCo con umbral
3
+
4
+ ## Idiomas
5
+ - Java moderno: `record` para datos, `sealed` + `switch` con patrones para jerarquías cerradas, `var` solo cuando el tipo es evidente, text blocks.
6
+ - Inmutabilidad por defecto: campos `final`, colecciones `List.of`/`Map.copyOf`, sin setters en objetos de dominio.
7
+ - `Optional` como tipo de retorno; nunca como parámetro ni como campo. Nunca devolver `null` en API pública.
8
+ - Excepciones: comprobadas para fallos recuperables del dominio, no comprobadas para errores de programación. Nunca `catch (Exception e) {}`. Conserva la causa.
9
+ - Inyección por constructor, no por campo. Sin `static` mutable.
10
+ - `try-with-resources` para todo `Closeable`. `equals`/`hashCode` coherentes.
11
+
12
+ ## Spring / Quarkus
13
+ - Capas: controlador (validación y mapeo) → servicio (negocio, transacciones) → repositorio. Sin entidades JPA en la API pública: usa DTO.
14
+ - `@Transactional` en el servicio, con el alcance mínimo; sin llamadas remotas dentro de la transacción.
15
+ - Validación con Bean Validation en el borde (`@Valid`).
16
+ - Seguridad: autorización por método/endpoint (`@PreAuthorize`), denegar por defecto, CSRF activo si hay sesión por cookie, CORS explícito, actuator restringido.
17
+ - Configuración externalizada; secretos en el gestor, nunca en `application.yml` del repo.
18
+
19
+ ## JPA
20
+ `FetchType.LAZY` por defecto; evita N+1 con `join fetch` o `EntityGraph`; paginación siempre; consultas con parámetros nombrados, nunca concatenadas; `@Version` para bloqueo optimista; migraciones con Flyway/Liquibase, jamás `ddl-auto=update` en producción.
21
+
22
+ ## Seguridad
23
+ `PreparedStatement` siempre · sin deserialización Java de datos externos · `SecureRandom` · BCrypt/Argon2 para contraseñas · `MessageDigest.isEqual` para comparar · parser XML con entidades externas desactivadas · límites de tamaño de petición.
24
+
25
+ ## Concurrencia
26
+ Prefiere inmutabilidad y `ExecutorService`/virtual threads a hilos manuales. `ConcurrentHashMap` en vez de sincronizar a mano. Nada de bloqueo dentro de secciones críticas. Timeouts en todo cliente.
27
+
28
+ ## Tests
29
+ JUnit 5 + AssertJ; Mockito solo para colaboradores externos; Testcontainers para BD y colas; `@SpringBootTest` solo en pruebas de integración reales; ArchUnit para reglas de arquitectura; jqwik para propiedades; PIT para mutación.
@@ -0,0 +1,25 @@
1
+ # Kotlin (JVM, Android, KMP)
2
+ **Gates**: `ktlint`/`spotless` · `detekt` · `./gradlew build` con warnings como error · `./gradlew test connectedCheck` · `lint` de Android · OSV/Dependabot
3
+
4
+ ## Idiomas
5
+ - Nulabilidad real: sin `!!`, sin `lateinit` evitable, sin `platform types` sin anotar. `?.`, `?:` y `requireNotNull` con mensaje.
6
+ - `data class` para datos, `sealed interface` + `when` exhaustivo para estados, `value class` para identificadores.
7
+ - Inmutabilidad: `val` por defecto, `List` en vez de `MutableList` en APIs públicas.
8
+ - Funciones de extensión con criterio; nada de extensiones sobre tipos del framework que confundan.
9
+ - Errores: `Result` o tipo sellado de dominio; excepciones para lo excepcional. Nunca `catch (e: Exception) {}`.
10
+
11
+ ## Corrutinas
12
+ - `suspend` para I/O; `Dispatchers.IO` para bloqueo; nunca bloquear el hilo principal.
13
+ - Concurrencia estructurada: alcance con ciclo de vida (`viewModelScope`, `lifecycleScope`), nada de `GlobalScope`.
14
+ - Cancelación cooperativa: comprueba `isActive`, usa `withTimeout`, limpia en `finally` con `NonCancellable` solo si es imprescindible.
15
+ - `Flow` frío para flujos; `StateFlow`/`SharedFlow` para estado; `flowOn` para cambiar de contexto; sin `collect` sin alcance.
16
+
17
+ ## Android
18
+ - Estado de UI inmutable expuesto desde el ViewModel; eventos de una sola vez por canal, no por estado.
19
+ - Sin lógica ni claves en `Activity`/`Composable`. Nada de secretos en el APK ni en `strings.xml`.
20
+ - Permisos mínimos y justificados; `EncryptedSharedPreferences`/Keystore para datos sensibles; `usesCleartextTraffic=false`; certificate pinning si aplica.
21
+ - Compose: estado elevado, `remember` con claves correctas, `key` estable en listas, evita recomposición por lambdas nuevas, `derivedStateOf` cuando toca.
22
+ - Exporta componentes solo si es necesario; valida los `Intent` recibidos; `PendingIntent` inmutable.
23
+
24
+ ## Tests
25
+ JUnit5 + Turbine para `Flow` · `kotlinx-coroutines-test` con dispatcher controlado · MockK para dependencias externas · Robolectric/Compose UI tests para pantallas · Testcontainers en backend Ktor/Spring.
@@ -0,0 +1,27 @@
1
+ # PHP (y Laravel / Symfony)
2
+ **Gates**: `php-cs-fixer fix --dry-run` (PSR-12) · `phpstan analyse --level=max` o Psalm · `phpunit --coverage-text` · `composer audit` · `psalm --taint-analysis`
3
+
4
+ ## Idiomas
5
+ - `declare(strict_types=1)` en todos los ficheros. Tipos en parámetros, retornos y propiedades.
6
+ - `readonly` y objetos de valor para datos; enums nativos en vez de constantes sueltas.
7
+ - Excepciones de dominio propias; nunca `@` para silenciar errores; nunca `die`/`exit` en código de librería.
8
+ - Composer con `composer.lock` commiteado y autoload PSR-4. Sin `require` de rutas dinámicas.
9
+
10
+ ## Seguridad
11
+ - SQL: PDO con sentencias preparadas y `PDO::ATTR_EMULATE_PREPARES => false`. Eloquent/Doctrine con binding; nunca concatenar.
12
+ - XSS: escapa en la plantilla (`{{ }}` de Blade/Twig escapa; `{!! !!}` y `|raw` prohibidos salvo sanitizado explícito).
13
+ - Nunca `eval`, `extract`, `unserialize` sobre datos externos (usa JSON), ni `include` con variable del usuario.
14
+ - `password_hash`/`password_verify` (Argon2id si está disponible); `random_bytes` para tokens; `hash_equals` para comparar.
15
+ - CSRF activo en todo formulario; sesión con cookie `httponly`, `secure`, `samesite`; regenerar id al iniciar sesión.
16
+ - Subida de ficheros: comprobar tipo real, renombrar, guardar fuera del webroot, sin permisos de ejecución.
17
+ - Producción: `display_errors=Off`, `expose_php=Off`, `open_basedir` si aplica, dependencias sin CVE.
18
+
19
+ ## Laravel
20
+ - Validación con Form Request; autorización con Policies (denegar por defecto) en cada acción.
21
+ - Sin asignación masiva ciega: `$fillable` explícito, nunca `$guarded = []`.
22
+ - Evita N+1 con `with()`; activa `Model::preventLazyLoading()` en desarrollo.
23
+ - Colas para trabajo lento; jobs idempotentes. Migraciones reversibles.
24
+ - `.env` fuera del repo; `php artisan config:cache` en despliegue.
25
+
26
+ ## Tests
27
+ PHPUnit o Pest · factories para datos · base de datos en transacción o contenedor efímero · Infection para mutación · tests de autorización por cada endpoint protegido.
@@ -0,0 +1,33 @@
1
+ # Python
2
+ **Gates**: `ruff format --check .` · `ruff check .` · `mypy --strict` · `pytest -q --cov` · `bandit -r src` · `pip-audit`
3
+
4
+ ## Estilo y tipos
5
+ - PEP 8 vía Ruff. Anotaciones de tipo en todo lo público.
6
+ - `mypy --strict` como objetivo; `# type: ignore[codigo]` solo con motivo en la misma línea.
7
+ - Datos: `dataclass(frozen=True, slots=True)` o Pydantic v2. `Protocol` para interfaces. `Enum`/`Literal` en vez de strings sueltos.
8
+ - Nunca argumentos por defecto mutables. Nunca estado global mutable.
9
+
10
+ ## Idiomas
11
+ - Comprensiones para transformar; generadores para volumen (memoria constante).
12
+ - `with` para todo recurso. `pathlib` en vez de `os.path`. `enumerate` y `zip` en vez de índices.
13
+ - Excepciones específicas y jerarquía de dominio propia. `raise ... from e`. Nunca `except:` desnudo ni `except Exception: pass`.
14
+ - `logging` con logger por módulo; nunca `print` en librería.
15
+ - Dependencias con `uv` o Poetry y lockfile; `pyproject.toml` como única fuente.
16
+
17
+ ## Seguridad
18
+ - SQL parametrizado o SQLAlchemy; nunca f-strings en consultas.
19
+ - `subprocess.run([...])` sin shell; nunca `os.system`.
20
+ - Nunca `eval`, `exec` ni `pickle.loads` sobre datos externos. `yaml.safe_load`. `defusedxml` para XML.
21
+ - `secrets` para tokens, `hmac.compare_digest` para comparar, `argon2-cffi` o `bcrypt` para contraseñas. `random` nunca en seguridad.
22
+ - `requests`/`httpx`: `timeout` obligatorio, verificación TLS activa, redirecciones controladas.
23
+ - Rutas del usuario: resolver a absoluto y comprobar que cuelgan del directorio base.
24
+ - Django/Flask/FastAPI: `DEBUG` desactivado en producción, `SECRET_KEY` fuera del código, ORM sin `raw`, permisos comprobados por vista.
25
+
26
+ ## Asincronía
27
+ No mezclar bloqueo con `asyncio`: `asyncio.to_thread` o ejecutor. `asyncio.timeout` en toda espera externa. `TaskGroup` en vez de tareas sueltas sin supervisión.
28
+
29
+ ## Rendimiento
30
+ Perfila con `cProfile` o `py-spy` antes de tocar nada. `"".join` en vez de concatenar en bucle. `set`/`dict` para pertenencia. NumPy/Polars cuando hay volumen.
31
+
32
+ ## Tests
33
+ `pytest` con fixtures, `parametrize` para tablas de casos, `hypothesis` para propiedades, `freezegun` para tiempo, `respx`/`responses` para HTTP, `pytest-cov` con umbral, `mutmut` en dominio crítico.
@@ -0,0 +1,32 @@
1
+ # React / Next.js
2
+ **Gates**: `eslint` con `react-hooks` y `jsx-a11y` · `tsc --noEmit` · Testing Library · Playwright · Lighthouse
3
+
4
+ ## Componentes
5
+ - Función pura de props a UI. La lógica no visual vive en hooks propios o módulos de dominio.
6
+ - Extrae cuando el JSX pasa de ~80 líneas o mezcla dos conceptos.
7
+ - Props tipadas y explícitas; sin spread ciego sobre elementos del DOM.
8
+ - `key` estable y única; nunca el índice si la lista se reordena o filtra.
9
+
10
+ ## Estado y efectos
11
+ - Menos estado posible: deriva en el render en vez de duplicar. Estado del servidor en TanStack Query/SWR, no en `useState`.
12
+ - `useEffect` solo para sincronizar con sistemas externos. No para transformar datos, ni para responder a eventos de usuario.
13
+ - Dependencias completas y honestas; nunca silenciar la regla del linter.
14
+ - Toda suscripción, timer o listener se limpia en el retorno del efecto.
15
+ - Estados de UI obligatorios: cargando, error, vacío y con datos. Los cuatro.
16
+
17
+ ## Rendimiento
18
+ - Mide con el Profiler antes de memoizar. `useMemo`/`useCallback`/`memo` solo con causa medida.
19
+ - Re-render típico: objeto, array o función nueva en props. Saca las constantes fuera del componente.
20
+ - Listas largas virtualizadas; rutas con `lazy` + `Suspense`; imágenes dimensionadas y diferidas.
21
+
22
+ ## Seguridad
23
+ - `dangerouslySetInnerHTML` prohibido salvo con sanitizador y comentario.
24
+ - Nunca secretos en el bundle ni en variables `NEXT_PUBLIC_*`.
25
+ - Server actions y route handlers: validar entrada y autorizar en servidor siempre; ocultar un botón no es control de acceso.
26
+ - Vigila filtrar datos del servidor al cliente vía props de componentes cliente.
27
+
28
+ ## Accesibilidad
29
+ HTML semántico antes que `div` con `onClick`. Etiqueta asociada a cada control. Foco visible y orden lógico. Modal con trampa de foco y cierre con `Esc`. `aria-*` solo si el elemento nativo no basta. Contraste AA. Detalle en `lang/web.md`.
30
+
31
+ ## Tests
32
+ Consultas por rol y texto accesible, no por clase CSS. MSW para red. Un E2E por recorrido crítico.
@@ -0,0 +1,23 @@
1
+ # Ruby (y Rails)
2
+ **Gates**: `rubocop` · `srb tc` o RBS/Steep si hay tipos · `rspec` con cobertura (SimpleCov) · `brakeman` · `bundler-audit check --update`
3
+
4
+ ## Idiomas
5
+ - Métodos cortos; `guard clauses` en vez de anidar. Sin `unless` con `else`.
6
+ - Objetos de valor y `Struct`/`Data` para datos; `freeze` en constantes.
7
+ - Excepciones específicas; nunca `rescue => e` genérico sin relanzar; nunca `rescue nil`.
8
+ - Sin monkey patching de clases del core ni de gemas; si es inevitable, en un refinement documentado.
9
+ - `Enumerable` antes que bucles manuales; cuidado con cargar colecciones enteras en memoria.
10
+
11
+ ## Rails
12
+ - Modelo gordo no: lógica de negocio en objetos de servicio o de dominio; el modelo mantiene invariantes y consultas.
13
+ - Strong parameters siempre; nunca `params.permit!`.
14
+ - Autorización explícita por acción (Pundit/CanCan), denegando por defecto; comprueba propiedad del recurso.
15
+ - Evita N+1 con `includes`; usa `bullet` en desarrollo; paginación obligatoria.
16
+ - Consultas: parámetros de Active Record; nunca interpolar en `where("... #{}")`.
17
+ - Vistas: escapado por defecto; `html_safe` y `raw` prohibidos sobre datos del usuario.
18
+ - `has_secure_password` (BCrypt) o Argon2; `SecureRandom` para tokens; credenciales cifradas de Rails, nunca en el repo.
19
+ - Migraciones reversibles; índices con la migración; `strong_migrations` para cambios peligrosos en caliente.
20
+ - Jobs idempotentes con reintentos acotados.
21
+
22
+ ## Tests
23
+ RSpec o Minitest · factories (FactoryBot) con datos mínimos · `request specs` sobre controladores · VCR/WebMock para HTTP externo · un test de autorización por endpoint protegido · sin `sleep` en tests de sistema.
@@ -0,0 +1,32 @@
1
+ # Rust
2
+ **Gates**: `cargo fmt --check` · `cargo clippy --all-targets --all-features -- -D warnings` · `cargo test` · `cargo build --locked --release` · `cargo audit` · `cargo deny check` · `cargo llvm-cov`
3
+
4
+ ## Idiomas
5
+ - Errores: `thiserror` en librería, `anyhow` en binario. `?` para propagar, `.context(...)` para contexto.
6
+ - Prohibido en producción: `unwrap()`, `expect()`, `panic!`, indexado sin comprobar; salvo comentario `// INVARIANT:` que demuestre que no puede fallar. En tests, libre.
7
+ - Tipos que impiden estados inválidos: newtype (`struct UserId(Uuid)`), enum en vez de booleanos, `NonZeroU32`, typestate.
8
+ - Préstamos antes que clones. `&str`/`&[T]` en parámetros, tipo propio en retorno. `Cow<str>` si dudas.
9
+ - Iteradores en vez de índices. `collect::<Result<Vec<_>, _>>()` para propagar en lote.
10
+ - Traits pequeños, `impl Trait` en argumentos, genéricos solo con más de un tipo real.
11
+ - `#[must_use]` en constructores; `#[non_exhaustive]` en enums de error públicos.
12
+
13
+ ## Seguridad
14
+ - `unsafe`: prohibido salvo necesidad demostrada; bloque mínimo con `// SAFETY:` justificando cada invariante; testear con Miri.
15
+ - Aritmética: `checked_*` / `saturating_*` / `wrapping_*` explícito donde pueda desbordar (release no comprueba overflow).
16
+ - Cripto: RustCrypto (`aes-gcm`, `chacha20poly1305`), `argon2`, `rand::rngs::OsRng`; `zeroize` para claves y contraseñas.
17
+ - SQL: `sqlx` con macros verificadas en compilación, o `rusqlite` con parámetros nombrados. Nunca `format!` en SQL.
18
+ - Serde en entrada externa: `#[serde(deny_unknown_fields)]` y límites de tamaño.
19
+ - `cargo deny` para licencias, duplicados y avisos de seguridad.
20
+
21
+ ## Async
22
+ - Un solo runtime. No bloquear el executor: `spawn_blocking` para CPU o I/O sincrónica.
23
+ - `tokio::time::timeout` en toda operación de red. Cuidado con cancelación: estado a medias al soltar un future.
24
+ - Canales y propiedad antes que `Arc<Mutex<T>>`.
25
+
26
+ ## Tauri (si aplica)
27
+ - Capabilities al mínimo, CSP estricta, sin `shell.open` con entrada del usuario.
28
+ - Claves y material criptográfico **solo** en el core Rust; el frontend invoca comandos tipados y nunca ve una clave.
29
+ - Todo argumento que llega del WebView es entrada no confiable: validar en Rust.
30
+
31
+ ## Tests
32
+ Unitarios en `#[cfg(test)]`, integración en `tests/`. `proptest` para invariantes, `cargo fuzz` en parsers, `insta` para snapshots, `criterion` para benchmarks, `cargo-mutants` en dominio crítico.
@@ -0,0 +1,24 @@
1
+ # Shell (Bash) y PowerShell
2
+ **Gates**: `shellcheck -S style` · `shfmt -d` · `Invoke-ScriptAnalyzer` · ejecución en seco (`--dry-run`) antes de la real
3
+
4
+ ## Bash
5
+ - Cabecera obligatoria: `#!/usr/bin/env bash` y `set -Eeuo pipefail`; `IFS=$'\n\t'` si iteras texto.
6
+ - **Comilla todo**: `"$var"`, `"$@"`, `"${array[@]}"`. Sin comillas = bug de espacios y de globbing.
7
+ - `trap 'cleanup' EXIT INT TERM` para temporales; `mktemp -d` para directorios de trabajo.
8
+ - Comprueba dependencias al inicio (`command -v jq >/dev/null || exit 1`) y valida los argumentos.
9
+ - Nunca `eval`. Nunca `curl ... | bash`. Nunca rutas relativas asumidas: calcula el directorio del script.
10
+ - Nada de parsear `ls`; usa globs o `find -print0` con `read -d ''`.
11
+ - `rm -rf` solo sobre ruta construida y verificada (comprueba que no está vacía y que cuelga de la base esperada).
12
+ - Salida: errores a `stderr`, código de salida significativo, mensajes sin secretos.
13
+
14
+ ## PowerShell
15
+ - `Set-StrictMode -Version Latest` y `$ErrorActionPreference = 'Stop'`.
16
+ - Verbo-Sustantivo aprobado, `[CmdletBinding()]`, `SupportsShouldProcess` con `-WhatIf` en cualquier función destructiva.
17
+ - Parámetros tipados con validación (`[ValidateSet]`, `[ValidateNotNullOrEmpty]`).
18
+ - `try/catch/finally` con excepciones tipadas; nunca `-ErrorAction SilentlyContinue` para tapar un fallo.
19
+ - Secretos: `SecureString`/`PSCredential` o gestor externo; nunca en texto plano ni en el historial de consola.
20
+ - Nunca `Invoke-Expression` con entrada externa. Llama binarios con `&` y array de argumentos.
21
+ - No uses `New-Item -Force` sobre un fichero existente: trunca.
22
+
23
+ ## Ambos
24
+ Scripts idempotentes · `--help` y modo verboso · sin rutas absolutas de tu máquina · sin credenciales en línea de comandos (aparecen en la tabla de procesos) · registra lo que hace antes de hacerlo si es destructivo.
@@ -0,0 +1,29 @@
1
+ # SQL y bases de datos
2
+ **Gates**: linter SQL (sqlfluff) · `EXPLAIN ANALYZE` en consultas nuevas · migración aplicada y revertida en entorno efímero · revisión de índices
3
+
4
+ ## Seguridad
5
+ - **Siempre parametrizado**. Identificadores dinámicos (tabla, columna, orden) desde allowlist cerrada, jamás desde la petición.
6
+ - Usuario de aplicación con permisos mínimos: sin `SUPERUSER`, sin DDL en producción, sin acceso a tablas que no usa.
7
+ - Row Level Security cuando hay multi-tenant (y verifica que la política se aplica también al rol de la app).
8
+ - Nunca datos sensibles en claro: hash para credenciales, cifrado para PII; cuidado con logs de consultas lentas que registran parámetros.
9
+ - Copias de seguridad cifradas y **restauración probada**, no solo programada.
10
+
11
+ ## Modelado
12
+ - Claves primarias estables (UUIDv7 o bigint); claves foráneas con `ON DELETE` explícito.
13
+ - `NOT NULL` por defecto; `CHECK` para invariantes; `UNIQUE` para reglas de unicidad reales.
14
+ - Tipos correctos: `timestamptz` (nunca `timestamp` sin zona), `numeric` para dinero (nunca `float`), `text` en Postgres, enum o tabla de catálogo para conjuntos cerrados.
15
+ - Normaliza primero; desnormaliza solo con medición y con plan de consistencia.
16
+
17
+ ## Consultas
18
+ - Sin `SELECT *` en código de aplicación. Paginación por keyset cuando el offset crece.
19
+ - Índice que cubra `WHERE` + `ORDER BY`; cuidado con funciones sobre la columna (rompen el índice) y con `LIKE '%x'`.
20
+ - Evita N+1 desde el ORM; agrupa con `IN` o `JOIN`.
21
+ - `EXISTS` mejor que `COUNT(*) > 0`. `UNION ALL` si no hace falta deduplicar.
22
+ - CTE cuando aclara; vigila que no fuerce materialización innecesaria.
23
+ - Transacción corta: nada de llamadas de red dentro; nivel de aislamiento consciente; reintento ante deadlock.
24
+
25
+ ## Migraciones
26
+ - Versionadas, en el repo, reversibles, idempotentes en lo posible. Una migración, un cambio.
27
+ - Cambios en caliente en dos o tres pasos: añadir (nullable/valor por defecto) → rellenar por lotes → hacer obligatorio → retirar lo viejo en un despliegue posterior.
28
+ - `CREATE INDEX CONCURRENTLY` en Postgres. Evita bloqueos largos: comprueba el nivel de lock antes de aplicar.
29
+ - Prueba la migración con datos de volumen realista y mide el tiempo antes de producción.
@@ -0,0 +1,31 @@
1
+ # Swift (iOS / macOS)
2
+ **Gates**: `swiftformat --lint` · `swiftlint --strict` · `swift build -warnings-as-errors` · `swift test` / `xcodebuild test` · escaneo de dependencias SPM
3
+
4
+ ## Idiomas
5
+ - Semántica de valor: `struct` y `enum` por defecto; `class` solo con identidad o ciclo de vida compartido; `final` salvo que se herede a propósito.
6
+ - Opcionales explícitos: sin `!` forzado, sin `try!`, sin `as!`. `guard let` con salida temprana.
7
+ - Errores con `throws` y tipos de error propios; `Result` en fronteras asíncronas antiguas. Nunca silenciar con `try?` sin comentario.
8
+ - Protocolos pequeños y composición; extensiones para conformidad. Genéricos con restricciones claras.
9
+ - `@inlinable`/`@usableFromInline` solo con motivo; `Codable` con claves explícitas y validación del payload externo.
10
+
11
+ ## Concurrencia (Swift 6)
12
+ - `async/await` y actores; sin `DispatchSemaphore` para esperar código asíncrono.
13
+ - Estado mutable compartido dentro de un actor; `@MainActor` para todo lo que toque UI.
14
+ - Respeta `Sendable`: si el compilador se queja de concurrencia, es un bug real, no ruido.
15
+ - Cancelación cooperativa: comprueba `Task.isCancelled`, propaga el `Task` y cancélalo en `deinit`/`onDisappear`.
16
+
17
+ ## Memoria
18
+ `weak`/`unowned` para romper ciclos en closures y delegados (`[weak self]`); cuidado con retención en `Task` de larga vida; instrumenta fugas con Instruments.
19
+
20
+ ## Seguridad (app)
21
+ - Secretos y tokens en Keychain (`kSecAttrAccessibleWhenUnlockedThisDeviceOnly`), nunca en `UserDefaults` ni en el bundle.
22
+ - Biometría con `LAContext` como conveniencia, no como única barrera; la clave real protegida por Secure Enclave o por contraseña del usuario.
23
+ - ATS activo; certificate pinning si el modelo de amenaza lo exige. Sin `NSAllowsArbitraryLoads`.
24
+ - `CryptoKit` para cripto (`AES.GCM`, `ChaChaPoly`, `SymmetricKey`); nunca cripto propia. Borra material sensible de memoria cuando puedas.
25
+ - Valida todo lo que entre por URL scheme, universal link, pasteboard o ficheros compartidos.
26
+
27
+ ## SwiftUI
28
+ Una fuente de verdad por estado; `@State` local, `@Observable`/`@StateObject` para modelos; vistas pequeñas y puras; `id` estable en `ForEach`; evita trabajo pesado en `body`.
29
+
30
+ ## Tests
31
+ XCTest o Swift Testing · dependencias inyectadas por protocolo · `URLProtocol` simulado para red · pruebas de UI solo en recorridos críticos · snapshot tests con tolerancia controlada.
@@ -0,0 +1,32 @@
1
+ # TypeScript / JavaScript / Node
2
+ **Gates**: `prettier --check .` · `eslint . --max-warnings=0` · `tsc --noEmit` · `vitest run --coverage` · `npm audit --omit=dev` · `knip`
3
+
4
+ ## Tipos
5
+ - `strict: true` + `noUncheckedIndexedAccess` + `exactOptionalPropertyTypes` + `noImplicitOverride` + `verbatimModuleSyntax`.
6
+ - `any` prohibido: usa `unknown` y estrecha. `as` solo con comentario. Sin `@ts-ignore` (`@ts-expect-error` con motivo si es inevitable).
7
+ - Datos externos (HTTP, env, JSON, storage) validados con Zod/Valibot y tipo derivado. Los tipos no existen en runtime.
8
+ - Uniones discriminadas con `switch` exhaustivo y `never` en el default.
9
+ - `readonly`, `as const`, `satisfies`. Uniones de literales en vez de enums.
10
+
11
+ ## Idiomas
12
+ - ESM, imports `type`-only, sin `export default` en módulos internos.
13
+ - `===` siempre. `??` y `?.` en vez de `||` cuando 0 o cadena vacía son válidos.
14
+ - Inmutabilidad: `map`/`filter`/`reduce` y spread; no mutar parámetros.
15
+ - Errores: clases propias con `cause`; nunca lanzar strings. `Promise.allSettled` si el fallo parcial es aceptable.
16
+ - Async: sin promesas flotantes; `Promise.all` cuando no hay dependencia; `await` dentro de manejo real de error.
17
+ - `AbortController` y timeout en todo `fetch`.
18
+
19
+ ## Node
20
+ - Nunca `exec` con interpolación: `execFile`/`spawn` con array de argumentos.
21
+ - Rutas: `path.resolve` y comprobar que el resultado está bajo el directorio base.
22
+ - Config desde `process.env` validada con esquema al arrancar; si falta algo, fallo al iniciar.
23
+ - Express/Fastify: `helmet`, límite de body, rate limit, CORS explícito, cookies `httpOnly`+`secure`+`sameSite`, manejador de errores que no filtra stack.
24
+ - JWT: algoritmo fijado (rechaza `none` y confusión RS/HS), verifica `exp`, `aud`, `iss`; revocación prevista. Sesión en cookie antes que token en localStorage.
25
+ - `crypto.randomUUID`, `crypto.randomBytes`, `timingSafeEqual`. Nunca `Math.random` en seguridad.
26
+ - ORM: consultas parametrizadas; `$queryRaw` solo con plantilla etiquetada `sql`.
27
+
28
+ ## Navegador
29
+ `textContent` antes que `innerHTML`; si hace falta HTML, DOMPurify. Sin `eval` ni `new Function`. CSP sin `unsafe-inline`. `postMessage`: verifica `origin`. Enlaces externos con `rel="noopener noreferrer"`.
30
+
31
+ ## Tests
32
+ Vitest/Jest + Testing Library, MSW para HTTP, Playwright para E2E, `fast-check` para propiedades. No mockear el propio dominio. Sin snapshots gigantes.
@@ -0,0 +1,31 @@
1
+ # HTML / CSS / Accesibilidad / Frontend base
2
+ **Gates**: validador HTML · `stylelint` · `axe`/Lighthouse (a11y ≥95) · presupuesto de bundle · Core Web Vitals
3
+
4
+ ## HTML semántico
5
+ - Un `h1` por página y jerarquía de encabezados sin saltos. `header`, `nav`, `main`, `section`, `article`, `footer`, `button`, `a`.
6
+ - `button` para acciones, `a[href]` para navegación. Nunca `div` con `onClick`.
7
+ - Todo control con etiqueta asociada (`label for` o `aria-label`). `alt` en imágenes (vacío si son decorativas).
8
+ - Formularios: `type` correcto, `autocomplete`, `required`, mensajes de error asociados con `aria-describedby` y anunciados.
9
+ - Idioma en `html lang`; `title` descriptivo por página; `meta viewport` sin bloquear el zoom.
10
+
11
+ ## Accesibilidad (WCAG 2.2 AA)
12
+ - Todo lo usable con ratón, usable con teclado. Foco **visible** y orden lógico. Sin trampas de foco salvo en modales (y con `Esc`).
13
+ - Contraste texto ≥4,5:1 (grande ≥3:1); elementos de interfaz ≥3:1.
14
+ - Objetivo táctil ≥24×24 px. Respeta `prefers-reduced-motion`.
15
+ - ARIA solo si el elemento nativo no basta; ARIA mal usado es peor que nada.
16
+ - Cambios dinámicos anunciados (`aria-live` en mensajes de estado y errores).
17
+ - Prueba real: navega la pantalla solo con `Tab`, y una vez con lector de pantalla.
18
+
19
+ ## CSS
20
+ - Sistema de diseño con tokens (color, espaciado, tipografía) en custom properties; sin valores mágicos repetidos.
21
+ - Layout con Grid y Flexbox; evita posicionamiento absoluto para estructura.
22
+ - Mobile-first, unidades relativas (`rem`, `ch`, `%`), `clamp()` para escalas fluidas.
23
+ - Especificidad baja y plana; sin `!important` salvo utilidades documentadas; sin selectores de más de 3 niveles.
24
+ - Modo oscuro por `prefers-color-scheme` con variables, no duplicando hojas.
25
+ - Anima solo `transform` y `opacity`; nada de animar `width`/`top` en bucles.
26
+
27
+ ## Rendimiento
28
+ Imágenes dimensionadas, modernas (AVIF/WebP), `loading="lazy"`, `srcset` · fuentes con `font-display: swap`, subconjunto y precarga de la crítica · CSS crítico en línea si mejora el LCP · sin librerías pesadas para una animación · presupuesto: JS inicial <200 KB comprimido, LCP <2,5 s, CLS <0,1, INP <200 ms.
29
+
30
+ ## Seguridad en el navegador
31
+ CSP estricta sin `unsafe-inline` (nonce o hash) · `Subresource Integrity` en scripts de CDN · sin datos sensibles en `localStorage` · `iframe` con `sandbox` y `allow` mínimos · `noopener` en enlaces externos · validar `origin` en `postMessage`.
@@ -0,0 +1,14 @@
1
+ ---
2
+ name: csr-audit
3
+ description: Auditoria de seguridad completa (OWASP Top 10 2025, ASVS 5.0, CWE Top 25) sobre el diff, un fichero, un modulo o todo el repositorio, con informe de hallazgos y correcciones.
4
+ ---
5
+
6
+ # csr-audit — Auditoría de seguridad
7
+
8
+ 1. Define el alcance: diff actual (por defecto), fichero, módulo o repo completo si el usuario lo pide.
9
+ 2. Ejecuta `~/.agents/rules/31-security-audit.md` completo: fases A (modelo de amenaza) → G (criterio de cierre).
10
+ 3. Ejecuta las herramientas disponibles de la fase E; lo que no esté instalado, se declara `SKIPPED`, no se simula.
11
+ 4. Informe: una línea por hallazgo con severidad, CWE/OWASP, `fichero:línea`, problema y corrección. Ordenado por severidad.
12
+ 5. Ofrece corregir CRIT y HIGH en el mismo turno; MED y LOW se listan para decisión del usuario.
13
+
14
+ **Prohibido**: inventar hallazgos, inventar resultados de escáneres, o escribir exploits armados. Prueba de concepto mínima y corrección.
@@ -0,0 +1,16 @@
1
+ ---
2
+ name: csr-gate
3
+ description: Ejecuta la puerta de validez completa (format, lint, typecheck, build, test, cobertura, seguridad, dependencias) y reporta PASS/FAIL/SKIPPED antes de dar una tarea por terminada.
4
+ ---
5
+
6
+ # csr-gate — Puerta de validez
7
+
8
+ 1. Lee `STACK.md` §3 para los comandos. Si falta, deduce del manifiesto y dilo.
9
+ 2. Lee `~/.agents/rules/50-done-gate.md` y ejecuta las fases 4 a 8.
10
+ 3. Ejecuta en este orden, parando y arreglando la causa raíz en el primer fallo:
11
+ `format → lint → typecheck → build → test → coverage → sec-scan → deps-audit`
12
+ 4. Autorrevisión adversarial (fase 4 del done-gate): responde las 7 preguntas en una línea cada una, solo para el diff actual.
13
+ 5. Si el diff toca entrada de usuario, autenticación, autorización, criptografía, ficheros, red, SQL, procesos, deserialización o dependencias, ejecuta además `~/.agents/rules/31-security-audit.md`.
14
+ 6. Reporta la tabla de gates (`50-done-gate.md` §8). Nada de prosa adicional.
15
+
16
+ **Regla absoluta**: un gate que no se ejecutó se reporta `SKIPPED (motivo)`. Nunca `PASS`.
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: csr-stack
3
+ description: Genera o actualiza el STACK.md del repositorio actual detectando lenguajes, frameworks, comandos y riesgos. Usar al abrir un proyecto sin STACK.md, o cuando el stack haya cambiado.
4
+ ---
5
+
6
+ # csr-stack — Ficha de stack del proyecto
7
+
8
+ ## Procedimiento
9
+ 1. **Detecta** sin preguntar lo que se puede leer:
10
+ - Manifiestos: `package.json`, `pnpm-workspace.yaml`, `Cargo.toml`, `pyproject.toml`, `requirements*.txt`, `go.mod`, `pom.xml`, `build.gradle*`, `*.csproj`, `composer.json`, `Gemfile`, `pubspec.yaml`, `Package.swift`, `CMakeLists.txt`, `mix.exs`.
11
+ - Config: `tsconfig.json`, `.eslintrc*`, `ruff.toml`, `.golangci.yml`, `Makefile`, `Taskfile.yml`, `justfile`, `docker-compose*.yml`, `Dockerfile`, `.github/workflows/*`, `terraform/`, `k8s/`.
12
+ - Versiones reales: `.nvmrc`, `.tool-versions`, `rust-toolchain.toml`, `.python-version`, campos `engines`/`edition`/`target-framework`.
13
+ - Comandos reales: scripts del manifiesto, targets del Makefile, jobs del CI. **No inventes ninguno**: lo que no exista va como `N/A`.
14
+ 2. **Infiera** tipo de proyecto, base de datos, framework de tests, gestor de paquetes (por el lockfile presente).
15
+ 3. **Escribe** `STACK.md` en la raíz usando la plantilla `~/.agents/templates/STACK.md`.
16
+ 4. **Marca** con `TODO:` solo lo que no se puede deducir del repo (nivel ASVS, amenazas, presupuestos, decisiones cerradas) y pregunta al usuario **como máximo 3** de esos puntos, en una sola tanda.
17
+ 5. **Selecciona** los módulos CSR activos (§9) según los lenguajes detectados.
18
+ 6. Reporta en 2 líneas: stack detectado y qué quedó como `TODO:`.
19
+
20
+ ## Reglas
21
+ - Si ya existe `STACK.md`, **actualiza** preservando lo escrito a mano (§5–§8); no lo sobrescribas entero.
22
+ - Versiones exactas, no rangos, cuando el repo las fije.
23
+ - Si hay monorepo, una tabla por paquete relevante, no una ficha por paquete.
@@ -0,0 +1,61 @@
1
+ ---
2
+ name: kit-init
3
+ description: Inicializa o migra un proyecto al Orca Multiagent Kit con un solo prompt - crea o actualiza AGENTS.md y CLAUDE.md desde las plantillas, detecta el stack (csr-stack), prepara la orquestacion multiagente, activa el hook de spec-kit para que /speckit.implement reparta el trabajo y deja .work/ ignorado. Usar con "inicializa el proyecto", "prepara este repo", "kit-init", al abrir un repo sin AGENTS.md o STACK.md, o con un AGENTS.md/CLAUDE.md con bloques CSR antiguos.
4
+ ---
5
+
6
+ # kit-init — Proyecto listo en un prompt
7
+
8
+ No necesita terminal ni el instalador: copia desde `~/.agents/templates/`. Si esa carpeta no existe: `BLOCKED: Orca Multiagent Kit no está instalado globalmente (./install.sh)`.
9
+
10
+ ## 1. Diagnóstico (solo lectura)
11
+ Comprueba y anota en una línea cada uno:
12
+ - `AGENTS.md`: falta | tiene bloque `AGENTS:BEGIN project` | tiene bloque antiguo `CSR:`/`MAW:` | contenido propio sin bloque.
13
+ - `CLAUDE.md`: igual. Es correcto si solo contiene el bloque con `@AGENTS.md`.
14
+ - `STACK.md`: falta | plantilla sin rellenar (campos vacíos, `| | |`) | rellena.
15
+ - `ORCHESTRATION.md`, `orca.yaml`, `.worktreeinclude`, `.gitignore` con `.work/`.
16
+ - Ficheros de otras herramientas que conviven: `.specify/` (spec-kit), `PRODUCT.md`/`DESIGN.md` (impeccable), `planes/`, `.cursor/rules/`, `.agents/rules/`, `.github/copilot-instructions.md`. No se tocan; se tienen en cuenta.
17
+
18
+ ## 2. Reglas del proyecto
19
+ 1. `AGENTS.md`: inserta al principio el bloque de `~/.agents/templates/AGENTS.md`. Si había un bloque antiguo `CSR:BEGIN project`, **migra** sus líneas de "Overrides de este proyecto" a la sección del bloque nuevo y elimina el bloque antiguo. Conserva todo el contenido que no esté en bloques.
20
+ 2. `CLAUDE.md`: debe quedar con el bloque de `~/.agents/templates/CLAUDE.md` (`@AGENTS.md`). Si tenía reglas propias fuera de bloques, **no las borres**: proponlas como overrides en `AGENTS.md` (una pregunta) para que las vean todos los agentes.
21
+ 3. No crees ficheros de reglas por agente (`GEMINI.md`, `.cursor/rules/…`): todos leen `AGENTS.md`.
22
+
23
+ ## 3. Stack
24
+ - Si `STACK.md` falta o es plantilla: ejecuta `csr-stack` (detecta lenguajes, frameworks, comandos reales y riesgos; pregunta como máximo 3 cosas).
25
+ - Si está relleno: no lo toques; solo avisa (`RISK:`) si sus comandos no coinciden con el manifiesto.
26
+
27
+ ## 4. Orquestación
28
+ Sigue `~/.agents/skills/orca/references/setup.md` (`ORCHESTRATION.md` con su nivel de autonomía, `orca.yaml`, `.worktreeinclude`, `.work/` en `.gitignore`). Añade a la lista `shared` los ficheros de contexto de otras herramientas que existan: `PRODUCT.md`, `DESIGN.md`, `.specify/memory/constitution.md`.
29
+ Agrupa sus preguntas con las de `csr-stack` en **una sola tanda** (máximo 4 en total).
30
+
31
+ ## 5. spec-kit (si existe `.specify/`)
32
+ Activa la implementación orquestada: el hook `before_implement` de la extensión `orca`.
33
+ 1. Si existe el CLI `specify`: `specify extension add --dev ~/.agents/speckit-ext/orca`.
34
+ 2. Si no, añade el hook a mano en `.specify/extensions.yml` (créalo si no existe; conserva lo que haya):
35
+ ```yaml
36
+ installed:
37
+ - orca
38
+ hooks:
39
+ before_implement:
40
+ - extension: orca
41
+ command: speckit.orca.implement
42
+ enabled: true
43
+ optional: false
44
+ priority: 10
45
+ description: "Orquestación multiagente: reparte las user stories si compensa"
46
+ ```
47
+ El comando lo resuelve la skill global `speckit-orca-implement`.
48
+ 3. Comprueba que `/speckit.implement` lo verá: la skill `speckit-implement` del proyecto debe mencionar `hooks.before_implement`. Si es una versión antigua sin hooks: `RISK:` y propón actualizar spec-kit.
49
+
50
+ ## 6. Cierre
51
+ No hagas commit sin permiso. Reporta:
52
+ ```
53
+ kit-init · <proyecto>
54
+ AGENTS.md | creado / migrado (overrides: N) / ya ok
55
+ CLAUDE.md | @AGENTS.md
56
+ STACK.md | detectado: <stack en 1 línea> · TODO: <n>
57
+ ORCHESTR. | agentes: <reparto> · shared: <n> ficheros · autonomía: <nivel>
58
+ spec-kit | hook before_implement: activo / no aplica
59
+ convive con | spec-kit · impeccable · …
60
+ commit sugerido: chore: inicializar Orca Multiagent Kit (AGENTS, STACK, ORCHESTRATION)
61
+ ```
@@ -0,0 +1,88 @@
1
+ ---
2
+ name: orca
3
+ description: Desarrollo orquestado con varios agentes en paralelo (Orca, subagentes o worktrees). Úsala por iniciativa propia cuando una tarea tenga 2 o más partes independientes de más de 15 minutos cada una (varias user stories, sprints, módulos o pantallas), cuando el usuario pida paralelo, Orca, worktrees, varios agentes o una carrera, y siempre que la invoque el hook before_implement de spec-kit. Decide si compensa, reparte, vigila e integra con solo dos confirmaciones.
4
+ ---
5
+
6
+ # orca — Desarrollo orquestado de principio a fin
7
+
8
+ Un solo punto de entrada. El usuario no tiene que conocer fases ni comandos: tú decides si compensa repartir y, si compensa, llevas el ciclo completo. Detalle en `references/` (léelo solo cuando llegues a ese paso).
9
+
10
+ ## 0. Configuración del run
11
+ Lee `./ORCHESTRATION.md` (si no existe, valores por defecto entre paréntesis):
12
+ - **Autonomía** (`semi`):
13
+ | Nivel | Confirmaciones del usuario |
14
+ |---|---|
15
+ | `manual` | plan de rondas · cada ronda antes de lanzarla · cada merge |
16
+ | `semi` | **1)** plan de rondas (autoriza también los commits del run) · **2)** merge final a la rama destino |
17
+ | `auto` | solo **2)**; el plan se muestra pero no espera respuesta |
18
+ En ningún nivel se mergea a la rama por defecto ni se hace push sin confirmación. Las decisiones de producto que surjan siempre se preguntan.
19
+ - **Agentes por capa**, **ficheros `shared`**, **máximo de workers** (3), **motor preferido**.
20
+
21
+ ## 1. ¿Compensa? (decídelo en menos de un minuto)
22
+ Compensa si hay ≥2 unidades sin dependencia entre sí, con `write` disjuntos, de ≥15 min cada una y verificables por separado (`~/.agents/rules/95-multi-agent.md` §Cuándo paralelizar).
23
+ - **No compensa** ⇒ una línea `ORCA: secuencial — <motivo>` y:
24
+ - si vienes del hook de spec-kit: termina aquí; `/speckit.implement` continúa normal;
25
+ - si no: hazlo tú directamente y pasa `csr-gate`.
26
+ - **Compensa** ⇒ sigue. Declara: `ORCA: <N> unidades · <R> rondas · motor <orca|subagents|manual> · autonomía <nivel>`.
27
+
28
+ ## 2. Unidades
29
+ Identifica la entrada y lee **solo** su adaptador:
30
+ | Entrada | Adaptador |
31
+ |---|---|
32
+ | spec-kit (`specs/<feature>/tasks.md`, o vienes del hook) | `references/adapters/speckit.md` |
33
+ | `planes/*.md` / `.plans/*.md` | `references/adapters/plan-file.md` |
34
+ | Plan nativo (modo plan de Claude, `implementation_plan.md` de Antigravity) | `references/adapters/native-plan.md` |
35
+ | Prompt de chat o ticket | `references/adapters/chat.md` (si es grande y vago, primero `references/plan.md`) |
36
+ | Mockup, diseño, documento | `references/adapters/artifact.md` |
37
+ Escribe las unidades con el formato de `references/units.md` en `.work/runs/<run>/units.md` (`.work/` en `.gitignore`).
38
+
39
+ ## 3. Plan de rondas — confirmación 1 (`manual`, `semi`)
40
+ Una sola tabla, sin más prosa:
41
+ ```
42
+ run 20261107-recargas · spec-kit 003-recargas · autonomía semi
43
+ ronda | unidad | agente | ficheros | depende
44
+ 0 | U0 setup + foundational | coordinador | 7 | —
45
+ 1 | U1 consulta de saldo (P1) | claude | 9 | U0
46
+ 1 | U2 recarga con tarjeta (P1)| antigravity | 11 | U0
47
+ 2 | U3 historial (P2) | codex | 6 | U1 (comparte layout)
48
+ merge final: feat/003-recargas → main (te lo pediré al terminar)
49
+ ¿Lanzo? (sí / cambia X)
50
+ ```
51
+ El «sí» autoriza los commits y merges **del run** en ramas de trabajo y en la rama de integración.
52
+
53
+ ## 4. Base común (U0)
54
+ Haz tú la ronda 0, pasa `csr-gate`, crea la rama de integración (`feat/<feature>` si no existe) y haz commit. Todas las unidades parten de ese commit.
55
+
56
+ ## 5. Lanzar la ronda
57
+ Motor: Orca si responde `orca status --json` y la orquestación está activada; si no, subagentes nativos; si no, manual. Lee solo su guía: `references/engine-orca.md` · `engine-subagents.md` · `engine-manual.md`.
58
+ Mensaje de despacho (todo dentro del mensaje: el worker no ve tu checkout ni tu conversación):
59
+ ```
60
+ UNIT: U2 — <título> RUN: <run> BASE: <sha> PUERTO DEV: <PORT_BASE+n>
61
+ <bloque completo de la unidad, tal cual está en units.md>
62
+ Shared (no tocar salvo los de tu unidad): <lista de ORCHESTRATION.md>
63
+ <contrato de references/worker-contract.md (con Orca, solo su §2 Alcance)>
64
+ ```
65
+
66
+ ## 6. Vigilar sin molestar
67
+ - Preguntas de workers: respóndelas tú si la respuesta está en spec, plan, `notes` o el código. Al usuario solo le llegan decisiones de producto, una por mensaje.
68
+ - Worker atascado (sin progreso en el doble del tiempo esperado) o `failed`: lee su salida y reintenta una vez (mismo agente o el otro proveedor). Si vuelve a fallar: la unidad queda `BLOCKED` y sigues con el resto.
69
+ - En Orca, deja el estado visible: `orca worktree set --worktree active --comment "<ronda X: n/m unidades>"`.
70
+
71
+ ## 7. Integrar cada ronda
72
+ Sigue `references/integrate.md`: revisas cada diff contra su unidad, mergeas en la **rama de integración** (no en la de por defecto), pasas `csr-gate` sobre el conjunto y actualizas el estado (`[x]` en `tasks.md`, sprint completado en el plan). Después, la siguiente ronda parte del nuevo commit.
73
+
74
+ ## 8. Cierre — confirmación 2
75
+ ```
76
+ ORCA: hecho · 4/4 unidades · 2 rondas · 1h52m
77
+ rama: feat/003-recargas (+1.240/−310, 46 ficheros)
78
+ <tabla de gates del conjunto>
79
+ BLOCKED/DEFERRED: <si aplica>
80
+ ¿Mergeo feat/003-recargas en main? (o abre PR)
81
+ ```
82
+ Limpieza de worktrees y ramas de unidades integradas tras el merge (Orca: `worker-release`).
83
+ - **Si vienes del hook de spec-kit**: todas las tareas quedan marcadas `[x]`. Di en una línea «Tareas completadas por la orquestación; /speckit.implement solo debe validar y ejecutar sus hooks posteriores» y devuelve el control.
84
+
85
+ ## Otros modos (cuando el usuario lo pide explícitamente)
86
+ - «carrera», «que lo intenten varios» ⇒ `references/race.md`.
87
+ - «solo planifica», «divide en sprints» ⇒ `references/plan.md` (plan sin ejecutar).
88
+ - «prepara la orquestación» ⇒ `references/setup.md` (normalmente lo hace `kit-init`).