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
package/install.sh ADDED
@@ -0,0 +1,403 @@
1
+ #!/usr/bin/env bash
2
+ # Orca Multiagent Kit — fuente única de reglas y skills para todos tus agentes (CSR + MAW).
3
+ # ./install.sh --dry-run muestra lo que haria, sin escribir
4
+ # ./install.sh instala/migra para los agentes detectados
5
+ # ./install.sh --agents claude,codex solo esos (claude antigravity codex copilot cursor devin)
6
+ # ./install.sh --project /ruta ademas, migra/prepara un proyecto
7
+ # ./install.sh --project-only /ruta solo el proyecto
8
+ # ./install.sh --verify comprueba instalacion y que no queden copias divergentes
9
+ # ./install.sh --restore AAAAMMDD-HHMMSS deshace una instalacion desde su backup
10
+ # ./install.sh --adopt <carpeta-skill> hace multiproveedor una skill externa (una copia, todos la ven)
11
+ # Compatible con bash 3.2 (macOS).
12
+ set -Eeuo pipefail
13
+
14
+ SRC="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
15
+ AG="${AGENT_KIT_HOME:-$HOME/.agents}"
16
+ CLAUDE_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
17
+ GEMINI_DIR="${GEMINI_DIR:-$HOME/.gemini}"
18
+ CODEX_DIR="${CODEX_HOME:-$HOME/.codex}"
19
+ COPILOT_DIR="$HOME/.copilot"
20
+ CURSOR_DIR="$HOME/.cursor"
21
+ DEVIN_DIR="$HOME/.config/devin"
22
+ STAMP="$(date +%Y%m%d-%H%M%S)"
23
+ BK="$AG/backups/$STAMP"
24
+ VERSION="$(cat "$SRC/VERSION")"
25
+ KIT_SKILLS="kit-init orca speckit-orca-implement csr-stack csr-gate csr-audit"
26
+ # Skills de versiones anteriores que esta versión retira (consolidadas en "orca")
27
+ OLD_SKILLS="maw-route maw-brief maw-plan maw-dispatch maw-worker maw-integrate maw-race maw-setup"
28
+ # Ficheros de reglas que versiones anteriores (CSR v1, MAW v1) copiaban dentro de cada agente.
29
+ OLD_RULES="00-router.md 10-communication.md 20-clean-code.md 30-security.md 31-security-audit.md 40-testing.md 50-done-gate.md 60-git-workflow.md 70-performance.md 75-reliability.md 80-supply-chain.md 90-docs-comments.md 95-multi-agent.md comunicacion-densa.md idioma-siempre.md"
30
+ OLD_LANGS="cpp csharp dart-flutter go infra java kotlin php python react ruby rust shell sql swift typescript web"
31
+
32
+ PROJECT=""; PROJECT_ONLY=0; VERIFY=0; DRY=0; AGENTS=""; RESTORE=""; ADOPT=""
33
+ while [ $# -gt 0 ]; do
34
+ case "$1" in
35
+ --project) PROJECT="${2:-}"; shift 2 ;;
36
+ --project-only) PROJECT="${2:-}"; PROJECT_ONLY=1; shift 2 ;;
37
+ --agents) AGENTS="${2:-}"; shift 2 ;;
38
+ --verify) VERIFY=1; shift ;;
39
+ --dry-run) DRY=1; shift ;;
40
+ --restore) RESTORE="${2:-}"; shift 2 ;;
41
+ --adopt) ADOPT="${2:-}"; shift 2 ;;
42
+ -h|--help) sed -n '2,12p' "$0"; exit 0 ;;
43
+ *) echo "Opcion desconocida: $1" >&2; exit 2 ;;
44
+ esac
45
+ done
46
+
47
+ # ------------------------------------------------------------------ salida
48
+ # Con OMK_EVENTS=1 (lo pone omk) se emiten eventos «::tipo::…» que omk dibuja con spinner y color.
49
+ # Sin él (./install.sh), el mismo contenido en texto, con color si es una terminal.
50
+ EV="${OMK_EVENTS:-}"
51
+ C_L=''; C_D=''; C_Y=''; C_R=''; C_B=''; C_0=''
52
+ if [ -z "$EV" ] && [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then
53
+ C_L=$'\033[38;5;154m'; C_D=$'\033[2m'; C_Y=$'\033[38;5;221m'; C_R=$'\033[38;5;203m'; C_B=$'\033[1m'; C_0=$'\033[0m'
54
+ fi
55
+ TODO=""; INFO=""; MOVED=0
56
+ ev() { printf '::%s\n' "$1"; }
57
+ title() { if [ -n "$EV" ]; then ev "title::$1::${2:-}"; else printf '\n%s%s%s %s%s%s\n%s%s%s\n\n' "$C_L$C_B" "■" "$C_0" "$C_B" "$1" "$C_0" "$C_D" "${2:-}" "$C_0"; fi; }
58
+ phase() { if [ -n "$EV" ]; then ev "begin::$1"; else printf ' %s›%s %s%s%s\n' "$C_L" "$C_0" "$C_B" "$1" "$C_0"; fi; }
59
+ done_phase() { if [ -n "$EV" ]; then ev "end::${1:-}"; elif [ -n "${1:-}" ]; then printf ' %s%s%s\n' "$C_D" "$1" "$C_0"; fi; return 0; }
60
+ item() { # $1 add|keep|dry|warn|fail · $2 texto
61
+ if [ -n "$EV" ]; then ev "item::$1::$2"; return 0; fi
62
+ case "$1" in add) m="$C_L+$C_0" ;; keep) m="$C_D=$C_0" ;; dry) m="$C_Y~$C_0" ;; fail) m="${C_R}✗${C_0}" ;; *) m="$C_Y!$C_0" ;; esac
63
+ printf ' %s %s\n' "$m" "$2"; }
64
+ todo() { TODO="${TODO}$1
65
+ "; if [ -n "$EV" ]; then ev "todo::$1"; fi; return 0; }
66
+ info() { INFO="${INFO}$1
67
+ "; if [ -n "$EV" ]; then ev "info::$1"; fi; return 0; }
68
+ short() { local x="$*"; x="${x//"$SRC"/<kit>}"; printf '%s' "${x//"$HOME"/~}"; }
69
+ run() { if [ "$DRY" -eq 1 ]; then item dry "$(short "$*")"; else "$@"; fi; }
70
+ # Resumen final: pendientes, información y siguientes pasos (solo texto; omk lo dibuja él)
71
+ footer() { # $1 global|project|both
72
+ local st=""; [ -d "$BK" ] && [ "$DRY" -eq 0 ] && st="$STAMP"
73
+ if [ -n "$EV" ]; then ev "footer::$1::$st::$DRY"; return 0; fi
74
+ if [ -n "$TODO" ]; then printf '\n%sPendiente%s\n' "$C_Y$C_B" "$C_0"; printf '%s' "$TODO" | while IFS= read -r l; do printf ' %s›%s %s\n' "$C_Y" "$C_0" "$l"; done; fi
75
+ if [ -n "$INFO" ]; then printf '\n%sPara tu información%s\n' "$C_D$C_B" "$C_0"; printf '%s' "$INFO" | while IFS= read -r l; do printf ' %s· %s%s\n' "$C_D" "$l" "$C_0"; done; fi
76
+ if [ "$DRY" -eq 1 ]; then printf '\n%sSimulación: no se ha escrito nada.%s\n\n' "$C_Y" "$C_0"; return 0; fi
77
+ printf '\n%s✓ Hecho%s\n' "$C_L$C_B" "$C_0"
78
+ case "$1" in
79
+ global) printf ' %scomprobar%s ./install.sh --verify\n %sproyecto%s ./install.sh --project-only <ruta>\n' "$C_D" "$C_0" "$C_D" "$C_0" ;;
80
+ *) printf ' %ssiguiente%s en el agente: «inicializa el proyecto»\n' "$C_D" "$C_0" ;;
81
+ esac
82
+ [ -n "$st" ] && printf ' %sdeshacer%s ./install.sh --restore %s\n' "$C_D" "$C_0" "$st"
83
+ printf '\n'; }
84
+ NSK=0; for _s in $KIT_SKILLS; do NSK=$((NSK+1)); done
85
+ # Cursor guarda las reglas de usuario en su base de datos de estado: basta con buscar la ruta del núcleo.
86
+ cursor_rule_set() {
87
+ local f
88
+ for f in "$HOME/Library/Application Support/Cursor/User/globalStorage/state.vscdb" "$HOME/.config/Cursor/User/globalStorage/state.vscdb"; do
89
+ [ -f "$f" ] && grep -aq '.agents/AGENTS.md' "$f" 2>/dev/null && return 0
90
+ done
91
+ return 1; }
92
+ agent_names() { local o="" a; for a in $(printf '%s' "$AGENTS" | tr ',' ' '); do
93
+ case "$a" in claude) a="Claude Code" ;; antigravity) a="Antigravity" ;; codex) a="Codex" ;; copilot) a="Copilot CLI" ;; cursor) a="Cursor" ;; devin) a="Devin" ;; esac
94
+ o="${o:+$o · }$a"; done; printf '%s' "$o"; }
95
+ has_agent() { case ",$AGENTS," in *",$1,"*) return 0 ;; *) return 1 ;; esac; }
96
+
97
+ # Mueve una ruta al backup conservando su ruta relativa a $HOME.
98
+ stash() {
99
+ local p="$1" rel
100
+ [ -e "$p" ] || [ -L "$p" ] || return 0
101
+ rel="${p#$HOME/}"
102
+ run mkdir -p "$BK/$(dirname "$rel")"
103
+ run mv "$p" "$BK/$rel"
104
+ MOVED=$((MOVED+1))
105
+ }
106
+ # Copia (sin mover) una ruta al backup.
107
+ snapshot() {
108
+ local p="$1" rel
109
+ [ -e "$p" ] || return 0
110
+ rel="${p#$HOME/}"
111
+ run mkdir -p "$BK/$(dirname "$rel")"
112
+ run cp -a "$p" "$BK/$rel"
113
+ }
114
+ # Deja $2 como enlace simbolico a $1. Si habia otra cosa, va al backup.
115
+ link() {
116
+ local target="$1" l="$2"
117
+ if [ -L "$l" ] && [ "$(readlink "$l")" = "$target" ]; then return 0; fi
118
+ stash "$l"
119
+ run mkdir -p "$(dirname "$l")"
120
+ run ln -s "$target" "$l"
121
+ }
122
+ # Quita los bloques gestionados (CSR, MAW, AGENTS) de un fichero, conservando el resto.
123
+ strip_blocks() { # $1 fichero -> stdout
124
+ awk 'BEGIN{tag=""}
125
+ tag=="" && match($0,/<!-- (CSR|MAW|AGENTS):BEGIN/) {tag=substr($0,RSTART+5,RLENGTH-11); next}
126
+ tag!="" { if (index($0,"<!-- " tag ":END -->")) tag=""; next }
127
+ {print}' "$1" | cat -s | awk 'NF{f=1} f'
128
+ }
129
+ # Lineas de "Overrides de este proyecto" dentro de un bloque CSR/AGENTS de proyecto.
130
+ extract_overrides() { # $1 fichero -> stdout
131
+ awk 'BEGIN{inb=0;ov=0}
132
+ /<!-- (CSR|AGENTS):BEGIN project/ {inb=1; next}
133
+ inb && /<!-- (CSR|AGENTS):END -->/ {inb=0; ov=0; next}
134
+ inb && /^## Overrides de este proyecto/ {ov=1; next}
135
+ inb && ov && !/^<!--/ && !/^-[[:space:]]*$/ && NF>0 {print}' "$1"
136
+ }
137
+ write_file() { # $1 destino, stdin contenido
138
+ if [ "$DRY" -eq 1 ]; then cat >/dev/null; item dry "escribir $(short "$1")"; else mkdir -p "$(dirname "$1")"; cat > "$1"; fi
139
+ }
140
+
141
+ [ -f "$SRC/core/AGENTS.md" ] || { echo "No encuentro core/AGENTS.md en $SRC" >&2; exit 1; }
142
+
143
+ # ------------------------------------------------------------------ restore
144
+ if [ -n "$RESTORE" ]; then
145
+ R="$AG/backups/$RESTORE"; [ -d "$R" ] || { echo "No existe la copia $R (consulta: omk backups)" >&2; exit 1; }
146
+ title "Restaurar" "copia $RESTORE"
147
+ phase "Devolviendo ficheros a su sitio"
148
+ N=0
149
+ while IFS= read -r rel; do
150
+ [ -n "$rel" ] || continue
151
+ dest="$HOME/$rel"
152
+ # si algun directorio padre es ahora un enlace (p. ej. una skill enlazada), quita el enlace: no escribir a traves de el
153
+ p="$(dirname "$dest")"
154
+ while [ "$p" != "$HOME" ] && [ "$p" != "/" ]; do [ -L "$p" ] && run rm -f "$p"; p="$(dirname "$p")"; done
155
+ if [ -L "$dest" ] || [ -f "$dest" ]; then run rm -f "$dest"; fi
156
+ run mkdir -p "$(dirname "$dest")"; run cp -a "$R/$rel" "$dest"
157
+ N=$((N+1))
158
+ done <<EOF
159
+ $(cd "$R" && find . \( -type f -o -type l \) | sed 's#^\./##')
160
+ EOF
161
+ done_phase "$N ficheros restaurados"
162
+ info "Los enlaces que el kit creó donde antes no había nada siguen ahí; bórralos a mano si quieres."
163
+ if [ -n "$EV" ]; then ev "footer::restore::$RESTORE::$DRY"; else printf '\n%s✓ Restaurado%s\n\n' "$C_L$C_B" "$C_0"; fi
164
+ exit 0
165
+ fi
166
+
167
+ # ------------------------------------------------------------------ agentes
168
+ if [ -z "$AGENTS" ]; then
169
+ [ -d "$CLAUDE_DIR" ] && AGENTS="$AGENTS,claude"
170
+ [ -d "$GEMINI_DIR" ] && AGENTS="$AGENTS,antigravity"
171
+ [ -d "$CODEX_DIR" ] && AGENTS="$AGENTS,codex"
172
+ [ -d "$COPILOT_DIR" ] && AGENTS="$AGENTS,copilot"
173
+ [ -d "$CURSOR_DIR" ] && AGENTS="$AGENTS,cursor"
174
+ AGENTS="${AGENTS#,}" # devin solo con --agents (opt-in)
175
+ fi
176
+
177
+ # ------------------------------------------------------------------ adopt
178
+ if [ -n "$ADOPT" ]; then
179
+ SKD="${ADOPT%/}"
180
+ [ -f "$SKD/SKILL.md" ] || { echo "No es una skill (falta SKILL.md): $SKD" >&2; exit 1; }
181
+ [ -L "$SKD" ] && { echo "Ya es un enlace: $SKD -> $(readlink "$SKD")" >&2; exit 1; }
182
+ NAME="$(basename "$SKD")"; DEST="$AG/skills/$NAME"
183
+ [ -e "$DEST" ] && { echo "Ya existe $DEST. Si es la misma skill, borra una de las dos copias antes." >&2; exit 1; }
184
+ title "Adoptar skill" "$NAME"
185
+ phase "Compartiendo $NAME con todos los agentes"
186
+ run mkdir -p "$BK" "$AG/skills"
187
+ run cp -a "$SKD" "$BK/$NAME.orig"
188
+ run mv "$SKD" "$DEST"
189
+ run ln -s "$DEST" "$SKD"
190
+ item add "copia única en $(short "$DEST")"
191
+ item add "en su sitio original queda un enlace"
192
+ case "$SKD" in "$CLAUDE_DIR"/skills/*) ;; *) has_agent claude && { link "$DEST" "$CLAUDE_DIR/skills/$NAME"; item add "enlazada en Claude Code"; } ;; esac
193
+ case "$SKD" in "$GEMINI_DIR"/*) ;; *) has_agent antigravity && { link "$DEST" "$GEMINI_DIR/config/skills/$NAME"; item add "enlazada en Antigravity"; } ;; esac
194
+ done_phase "Codex, Copilot y Cursor la leen desde ~/.agents/skills"
195
+ info "Si la skill se actualiza con su propio instalador, vuelve a adoptarla."
196
+ footer global
197
+ exit 0
198
+ fi
199
+
200
+ # ------------------------------------------------------------------ verify
201
+ if [ "$VERIFY" -eq 1 ]; then
202
+ bad=0; nok=0
203
+ vok() { nok=$((nok+1)); if [ -n "$EV" ]; then ev "check::ok::$1"; else printf ' %s✓%s %s\n' "$C_L" "$C_0" "$1"; fi; }
204
+ vfail() { bad=$((bad+1)); if [ -n "$EV" ]; then ev "check::fail::$1"; else printf ' %s✗ %s%s\n' "$C_R" "$1" "$C_0"; fi; }
205
+ vinfo() { if [ -n "$EV" ]; then ev "check::info::$1"; else printf ' %s· %s%s\n' "$C_D" "$1" "$C_0"; fi; }
206
+ chk_link() { if [ -L "$3" ] && [ "$(readlink "$3")" = "$2" ]; then vok "$1"; else vfail "$1: $(short "$3") no enlaza a $(short "$2")"; fi; }
207
+ title "Verificación" "$(agent_names)"
208
+ [ -f "$AG/AGENTS.md" ] && vok "núcleo en ~/.agents/AGENTS.md (v$(cat "$AG/AGENT_KIT_VERSION" 2>/dev/null || echo '?'))" || vfail "falta ~/.agents/AGENTS.md: ejecuta omk install"
209
+ n=$(ls -1 "$AG/rules/lang"/*.md 2>/dev/null | wc -l | tr -d ' '); [ "$n" -ge 17 ] && vok "$n guías de lenguaje" || vfail "guías de lenguaje: $n de 17"
210
+ ms=""; for s in $KIT_SKILLS; do [ -f "$AG/skills/$s/SKILL.md" ] || ms="$ms $s"; done
211
+ [ -z "$ms" ] && vok "$NSK skills del kit" || vfail "faltan skills:$ms"
212
+ [ -f "$AG/speckit-ext/orca/extension.yml" ] && vok "extensión de spec-kit" || vfail "falta la extensión de spec-kit (~/.agents/speckit-ext/orca)"
213
+ for s in $OLD_SKILLS; do [ -e "$AG/skills/$s" ] && vfail "skill retirada sigue instalada: $s"; done
214
+ if has_agent claude; then
215
+ grep -q '@~/.agents/AGENTS.md' "$CLAUDE_DIR/CLAUDE.md" 2>/dev/null && vok "Claude Code: CLAUDE.md importa el núcleo" || vfail "Claude Code: CLAUDE.md no importa el núcleo"
216
+ grep -Eq '<!-- (CSR|MAW):BEGIN' "$CLAUDE_DIR/CLAUDE.md" 2>/dev/null && vfail "Claude Code: CLAUDE.md conserva bloques CSR/MAW antiguos" || true
217
+ for r in $OLD_RULES; do [ -e "$CLAUDE_DIR/rules/$r" ] && vfail "Claude Code: copia antigua $(short "$CLAUDE_DIR/rules/$r") (Claude la carga siempre)"; done
218
+ ms=""; for s in $KIT_SKILLS; do [ -L "$CLAUDE_DIR/skills/$s" ] && [ "$(readlink "$CLAUDE_DIR/skills/$s")" = "$AG/skills/$s" ] || ms="$ms $s"; done
219
+ [ -z "$ms" ] && vok "Claude Code: skills enlazadas" || vfail "Claude Code: skills sin enlazar:$ms"
220
+ fi
221
+ if has_agent antigravity; then
222
+ chk_link "Antigravity: GEMINI.md es el núcleo" "$AG/AGENTS.md" "$GEMINI_DIR/GEMINI.md"
223
+ for r in $OLD_RULES; do [ -e "$GEMINI_DIR/rules/$r" ] && vfail "Antigravity: copia antigua $(short "$GEMINI_DIR/rules/$r")"; done
224
+ [ -e "$GEMINI_DIR/config/plugins/claude-session-rules" ] && vfail "Antigravity: el plugin claude-session-rules sigue instalado (duplica csr-*)"
225
+ ms=""; for s in $KIT_SKILLS; do [ -L "$GEMINI_DIR/config/skills/$s" ] && [ "$(readlink "$GEMINI_DIR/config/skills/$s")" = "$AG/skills/$s" ] || ms="$ms $s"; done
226
+ [ -z "$ms" ] && vok "Antigravity: skills enlazadas" || vfail "Antigravity: skills sin enlazar:$ms"
227
+ fi
228
+ has_agent codex && chk_link "Codex: AGENTS.md es el núcleo" "$AG/AGENTS.md" "$CODEX_DIR/AGENTS.md"
229
+ has_agent copilot && chk_link "Copilot CLI: copilot-instructions.md es el núcleo" "$AG/AGENTS.md" "$COPILOT_DIR/copilot-instructions.md"
230
+ has_agent devin && chk_link "Devin: AGENTS.md es el núcleo" "$AG/AGENTS.md" "$DEVIN_DIR/AGENTS.md"
231
+ if has_agent cursor; then
232
+ if cursor_rule_set; then vok "Cursor: regla de usuario configurada"; else vinfo "Cursor: no veo la regla de usuario que apunta a ~/.agents/AGENTS.md (Settings → Rules)"; fi
233
+ fi
234
+ if [ -n "$EV" ]; then ev "result::$bad::$nok"; exit $((bad > 0)); fi
235
+ if [ "$bad" -eq 0 ]; then printf '\n%s✓ Todo correcto%s %s%s comprobaciones%s\n\n' "$C_L$C_B" "$C_0" "$C_D" "$nok" "$C_0"; exit 0; fi
236
+ printf '\n%s✗ %s fallos%s %sejecuta «omk install» para repararlos%s\n\n' "$C_R$C_B" "$bad" "$C_0" "$C_D" "$C_0"; exit 1
237
+ fi
238
+
239
+ # ------------------------------------------------------------------ global
240
+ if [ "$PROJECT_ONLY" -eq 0 ]; then
241
+ [ -n "$AGENTS" ] || { echo "No detecto ningún agente (Claude Code, Antigravity, Codex, Copilot o Cursor). Indica cuáles con --agents." >&2; exit 1; }
242
+ SUB="$(agent_names)"; [ "$DRY" -eq 1 ] && SUB="$SUB · simulación, no se escribe nada"
243
+ title "Orca Multiagent Kit v${VERSION}" "$SUB"
244
+ run mkdir -p "$BK"
245
+
246
+ # 1. Fuente canonica
247
+ phase "Fuente única en ~/.agents"
248
+ PREV="$(cat "$AG/AGENT_KIT_VERSION" 2>/dev/null || true)"
249
+ [ -f "$AG/AGENTS.md" ] && snapshot "$AG/AGENTS.md"
250
+ run mkdir -p "$AG/rules" "$AG/skills" "$AG/templates" "$AG/output-styles"
251
+ run cp "$SRC/core/AGENTS.md" "$AG/AGENTS.md"
252
+ run cp -R "$SRC/rules/." "$AG/rules/"
253
+ for r in comunicacion-densa.md idioma-siempre.md; do [ -e "$AG/rules/$r" ] && stash "$AG/rules/$r"; done
254
+ for s in $KIT_SKILLS; do
255
+ [ -e "$AG/skills/$s" ] && run rm -rf "$AG/skills/$s"
256
+ run cp -R "$SRC/skills/$s" "$AG/skills/$s"
257
+ done
258
+ run cp -R "$SRC/templates/." "$AG/templates/"
259
+ run cp -R "$SRC/output-styles/." "$AG/output-styles/"
260
+ run cp "$SRC/VERSION" "$AG/AGENT_KIT_VERSION"
261
+ run mkdir -p "$AG/speckit-ext"
262
+ [ -e "$AG/speckit-ext/orca" ] && run rm -rf "$AG/speckit-ext/orca"
263
+ run cp -R "$SRC/speckit-extension/orca" "$AG/speckit-ext/orca"
264
+ NR=$(find "$SRC/rules" -name '*.md' | wc -l | tr -d ' '); NS=$NSK
265
+ if [ -z "$PREV" ]; then item add "instalada v${VERSION}"; elif [ "$PREV" = "$VERSION" ]; then item keep "v${VERSION} reinstalada"; else item add "actualizada de v${PREV} a v${VERSION}"; fi
266
+ done_phase "núcleo · $NR reglas · $NS skills · extensión de spec-kit"
267
+
268
+ # 2. Restos de versiones anteriores
269
+ phase "Versiones anteriores"
270
+ M0=$MOVED
271
+ [ -d "$AG/maw" ] && stash "$AG/maw" # restos de MAW v1
272
+ for s in $OLD_SKILLS; do
273
+ stash "$AG/skills/$s"; stash "$CLAUDE_DIR/skills/$s"; stash "$GEMINI_DIR/config/skills/$s"
274
+ done
275
+ if [ $((MOVED-M0)) -gt 0 ]; then done_phase "$((MOVED-M0)) elementos retirados a la copia de seguridad"; else done_phase "nada que retirar"; fi
276
+
277
+ # 3. Claude Code: import en CLAUDE.md; reglas fuera de ~/.claude/rules (Claude carga TODO lo que hay ahi)
278
+ if has_agent claude; then
279
+ phase "Claude Code"
280
+ M0=$MOVED
281
+ if [ -L "$CLAUDE_DIR/CLAUDE.md" ]; then stash "$CLAUDE_DIR/CLAUDE.md"; fi
282
+ [ -f "$CLAUDE_DIR/CLAUDE.md" ] && snapshot "$CLAUDE_DIR/CLAUDE.md"
283
+ TMP="$(mktemp)"; [ -f "$CLAUDE_DIR/CLAUDE.md" ] && strip_blocks "$CLAUDE_DIR/CLAUDE.md" > "$TMP"
284
+ { printf '<!-- AGENTS:BEGIN v%s Orca Multiagent Kit -- reglas globales: edita ~/.agents/AGENTS.md, no este bloque -->\n@~/.agents/AGENTS.md\n<!-- AGENTS:END -->\n' "$VERSION"; [ -s "$TMP" ] && { printf '\n'; cat "$TMP"; }; true; } | write_file "$CLAUDE_DIR/CLAUDE.md"
285
+ [ -s "$TMP" ] && KEPT=1 || KEPT=0
286
+ rm -f "$TMP"
287
+ for r in $OLD_RULES; do stash "$CLAUDE_DIR/rules/$r"; done
288
+ for l in $OLD_LANGS; do stash "$CLAUDE_DIR/rules/lang/$l.md"; done
289
+ [ -d "$CLAUDE_DIR/rules/lang" ] && [ "$DRY" -eq 0 ] && rmdir "$CLAUDE_DIR/rules/lang" 2>/dev/null || true
290
+ for s in $KIT_SKILLS; do link "$AG/skills/$s" "$CLAUDE_DIR/skills/$s"; done
291
+ link "$AG/output-styles/csr-minimal.md" "$CLAUDE_DIR/output-styles/csr-minimal.md"
292
+ stash "$CLAUDE_DIR/templates/STACK.md"; stash "$CLAUDE_DIR/templates/project-CLAUDE.md"
293
+ item add "CLAUDE.md importa el núcleo"
294
+ [ "$KEPT" -eq 1 ] && item keep "tu contenido propio de CLAUDE.md se conserva debajo"
295
+ item add "$NS skills enlazadas · estilo csr-minimal"
296
+ [ $((MOVED-M0)) -gt 0 ] && item add "$((MOVED-M0)) copias antiguas de reglas retiradas"
297
+ done_phase
298
+ info "Claude Code: en la app de escritorio (Cowork) no se cargan imports de fuera de la carpeta de trabajo; en la terminal y el IDE sí."
299
+ fi
300
+
301
+ # 4. Antigravity: GEMINI.md pasa a ser un enlace a la fuente unica
302
+ if has_agent antigravity; then
303
+ phase "Antigravity"
304
+ M0=$MOVED
305
+ if [ -f "$GEMINI_DIR/GEMINI.md" ] && [ ! -L "$GEMINI_DIR/GEMINI.md" ]; then
306
+ EXTRA="$(strip_blocks "$GEMINI_DIR/GEMINI.md" | grep -v '^[[:space:]]*$' || true)"
307
+ [ -n "$EXTRA" ] && info "Antigravity: lo que tenías en GEMINI.md fuera de los bloques está en la copia de seguridad. Si era tuyo, pásalo a ~/.agents/rules/personal.md."
308
+ fi
309
+ link "$AG/AGENTS.md" "$GEMINI_DIR/GEMINI.md"
310
+ for r in $OLD_RULES; do stash "$GEMINI_DIR/rules/$r"; done
311
+ for l in $OLD_LANGS; do stash "$GEMINI_DIR/rules/lang/$l.md"; done
312
+ [ -d "$GEMINI_DIR/rules/lang" ] && [ "$DRY" -eq 0 ] && rmdir "$GEMINI_DIR/rules/lang" 2>/dev/null || true
313
+ stash "$GEMINI_DIR/templates/STACK.md"; stash "$GEMINI_DIR/templates/project-CLAUDE.md"
314
+ stash "$GEMINI_DIR/output-styles/csr-minimal.md"
315
+ if [ -e "$GEMINI_DIR/config/plugins/claude-session-rules" ]; then
316
+ stash "$GEMINI_DIR/config/plugins/claude-session-rules"
317
+ item add "plugin claude-session-rules retirado (ya está en la fuente única)"
318
+ info "Antigravity: si se queja de un plugin ausente (claude-session-rules), desactívalo en su configuración."
319
+ fi
320
+ for s in $KIT_SKILLS; do link "$AG/skills/$s" "$GEMINI_DIR/config/skills/$s"; done
321
+ item add "GEMINI.md es un enlace al núcleo"
322
+ item add "$NS skills enlazadas"
323
+ [ $((MOVED-M0)) -gt 0 ] && item add "$((MOVED-M0)) copias antiguas retiradas"
324
+ done_phase
325
+ [ -d "$GEMINI_DIR/config/plugins/user-workflows/skills/planificar" ] && todo "Antigravity: desactiva la skill «planificar» cuando hayas probado «orca», que la sustituye."
326
+ fi
327
+
328
+ # 5. Agentes que leen ~/.agents/skills de forma nativa: solo hay que enlazar las reglas globales
329
+ if has_agent codex; then phase "Codex"; link "$AG/AGENTS.md" "$CODEX_DIR/AGENTS.md"; item add "AGENTS.md es un enlace al núcleo"; item add "skills: las lee de ~/.agents/skills"; done_phase; fi
330
+ if has_agent copilot; then phase "Copilot CLI"; link "$AG/AGENTS.md" "$COPILOT_DIR/copilot-instructions.md"; item add "copilot-instructions.md es un enlace al núcleo"; item add "skills: las lee de ~/.agents/skills"; done_phase; fi
331
+ if has_agent devin; then phase "Devin"; link "$AG/AGENTS.md" "$DEVIN_DIR/AGENTS.md"; item add "AGENTS.md es un enlace al núcleo"; done_phase
332
+ info "Devin: también lee ~/.claude/CLAUDE.md; si ves reglas duplicadas, quita uno de los dos."; fi
333
+ if has_agent cursor; then phase "Cursor"
334
+ item add "skills: las lee de ~/.agents/skills"
335
+ if cursor_rule_set; then item keep "regla de usuario ya configurada"; else
336
+ item warn "falta la regla de usuario (Cursor no la guarda en un fichero)"
337
+ todo "Cursor: añade en Settings → Rules → User Rules una regla con este texto: «Al empezar, lee y aplica ~/.agents/AGENTS.md y, bajo demanda, ~/.agents/rules/»"
338
+ fi
339
+ done_phase
340
+ has_agent claude && info "Cursor: también lee ~/.claude/skills, así que puede listar las skills dos veces (con el mismo contenido)."
341
+ fi
342
+ fi
343
+
344
+ # ------------------------------------------------------------------ proyecto
345
+ if [ -n "$PROJECT" ]; then
346
+ [ -d "$PROJECT" ] || { echo "No existe la ruta de proyecto: $PROJECT" >&2; exit 1; }
347
+ PNAME="$(basename "$PROJECT")"
348
+ [ "$PROJECT_ONLY" -eq 1 ] && title "Orca Multiagent Kit v${VERSION}" "proyecto $(short "$PROJECT")$([ "$DRY" -eq 1 ] && echo ' · simulación')"
349
+ phase "Proyecto $PNAME"
350
+ INSTALLED="$(cat "$AG/AGENT_KIT_VERSION" 2>/dev/null || true)"
351
+ if [ "$PROJECT_ONLY" -eq 1 ] && [ "$INSTALLED" != "$VERSION" ]; then
352
+ if [ -n "${OMK_CLI:-}" ]; then FIX="omk install"; else FIX="./install.sh"; fi
353
+ todo "Instalación global: en ~/.agents hay ${INSTALLED:-una versión sin instalar} y este kit es v${VERSION}. Ejecuta «${FIX}» para tener las skills orca y kit-init."
354
+ fi
355
+ OV=""
356
+ for f in "$PROJECT/CLAUDE.md" "$PROJECT/AGENTS.md"; do [ -f "$f" ] && OV="$OV$(extract_overrides "$f")
357
+ "; done
358
+ OV="$(printf '%s' "$OV" | awk 'NF && !seen[$0]++')"
359
+ for f in AGENTS.md CLAUDE.md; do [ -f "$PROJECT/$f" ] && snapshot "$PROJECT/$f"; done
360
+ [ -f "$PROJECT/AGENTS.md" ] && HADAG=1 || HADAG=0
361
+
362
+ TMP="$(mktemp)"; [ -f "$PROJECT/AGENTS.md" ] && strip_blocks "$PROJECT/AGENTS.md" > "$TMP"
363
+ { if [ -n "$OV" ]; then OV="$OV" awk '/^-$/ && !d {print ENVIRON["OV"]; d=1; next} {print}' "$SRC/templates/AGENTS.md"; else cat "$SRC/templates/AGENTS.md"; fi
364
+ [ -s "$TMP" ] && { printf '\n'; cat "$TMP"; }; true; } | write_file "$PROJECT/AGENTS.md"
365
+ REST="$(mktemp)"; [ -f "$PROJECT/CLAUDE.md" ] && strip_blocks "$PROJECT/CLAUDE.md" > "$REST"
366
+ { cat "$SRC/templates/CLAUDE.md"; [ -s "$REST" ] && { printf '\n'; cat "$REST"; }; true; } | write_file "$PROJECT/CLAUDE.md"
367
+ if [ "$HADAG" -eq 1 ]; then item add "AGENTS.md actualizado (tu contenido se conserva)"; else item add "AGENTS.md creado"; fi
368
+ [ -n "$OV" ] && item add "overrides del proyecto movidos a AGENTS.md"
369
+ item add "CLAUDE.md importa AGENTS.md"
370
+ grep -q '[^[:space:]]' "$REST" && todo "$PNAME: CLAUDE.md tiene reglas propias que solo ve Claude. Pide al agente «inicializa el proyecto» para pasarlas a AGENTS.md y que las vean todos."
371
+ rm -f "$TMP" "$REST"
372
+ for f in STACK.md ORCHESTRATION.md orca.yaml .worktreeinclude; do
373
+ if [ -e "$PROJECT/$f" ]; then item keep "$f ya existía: no se toca"; else run cp "$SRC/templates/$f" "$PROJECT/$f"; item add "$f creado"; fi
374
+ done
375
+ if [ ! -e "$PROJECT/.claude/settings.json" ] && has_agent claude; then run mkdir -p "$PROJECT/.claude"; run cp "$SRC/templates/claude-settings.json" "$PROJECT/.claude/settings.json"; item add ".claude/settings.json creado"; fi
376
+ if [ -d "$PROJECT/.specify" ]; then
377
+ EXT="$PROJECT/.specify/extensions.yml"
378
+ if grep -q 'speckit.orca.implement' "$EXT" 2>/dev/null; then item keep "spec-kit: el hook de orquestación ya estaba activo"
379
+ elif command -v specify >/dev/null 2>&1; then
380
+ SKX="$AG/speckit-ext/orca"; [ -f "$SKX/extension.yml" ] || SKX="$SRC/speckit-extension/orca"
381
+ if (cd "$PROJECT" && run specify extension add --dev "$SKX") >/dev/null 2>&1; then item add "spec-kit: extensión orca instalada (hook before_implement)"
382
+ else item warn "spec-kit: «specify extension add» ha fallado"; todo "$PNAME: no se pudo activar el hook de spec-kit. Pide al agente «inicializa el proyecto» y lo añadirá."; fi
383
+ elif [ ! -e "$EXT" ]; then
384
+ # mismo formato que escribe 'specify extension add'
385
+ printf '%s\n' 'installed:' '- orca' 'settings:' ' auto_execute_hooks: true' 'hooks:' ' before_implement:' ' - extension: orca' \
386
+ ' command: speckit.orca.implement' ' enabled: true' ' optional: false' ' priority: 10' \
387
+ ' description: "Orquestacion multiagente: reparte las user stories si compensa"' | write_file "$EXT"
388
+ item add "spec-kit: hook before_implement creado en .specify/extensions.yml"
389
+ else
390
+ item warn "spec-kit: hay extensions.yml y no está el comando specify"
391
+ todo "$PNAME: pide al agente «inicializa el proyecto» para añadir el hook de spec-kit sin romper tu extensions.yml."
392
+ fi
393
+ else
394
+ item keep "sin spec-kit (.specify/): no hace falta hook"
395
+ fi
396
+ if ! grep -qxF '.work/' "$PROJECT/.gitignore" 2>/dev/null; then
397
+ if [ "$DRY" -eq 1 ]; then item dry "añadir .work/ a .gitignore"; else printf '\n# Orca Multiagent Kit: briefs e informes de runs multiagente\n.work/\n' >> "$PROJECT/.gitignore"; fi
398
+ item add ".work/ añadido a .gitignore"
399
+ fi
400
+ done_phase
401
+ fi
402
+
403
+ if [ -n "$PROJECT" ] && [ "$PROJECT_ONLY" -eq 0 ]; then footer both; elif [ -n "$PROJECT" ]; then footer project; else footer global; fi
@@ -0,0 +1,14 @@
1
+ ---
2
+ name: CSR Minimal
3
+ description: Maximo rigor tecnico, minimo gasto en prosa. Resultado primero, sin narracion ni cortesia.
4
+ ---
5
+
6
+ Eres un ingeniero senior. Tu razonamiento y tu código son exhaustivos; tu prosa es mínima.
7
+
8
+ - Primera línea = resultado o estado. Sin preámbulo, sin narrar herramientas, sin cortesía, sin recapitulación.
9
+ - ≤4 líneas de prosa por turno. Código, diffs, tablas de gates y comandos no cuentan.
10
+ - El resto del protocolo (prefijos, excepciones, disparadores de detalle) está en `~/.agents/AGENTS.md` §2 y en `~/.agents/rules/10-communication.md`. Aplícalo; no lo repitas.
11
+ - El ahorro es solo de salida en prosa. No reduzcas análisis, lectura de código, tests ni auditoría de seguridad.
12
+ - Antes de declarar algo terminado: `~/.agents/rules/50-done-gate.md` y tabla de gates. Un comando no ejecutado se reporta `SKIPPED (motivo)`, nunca `PASS`.
13
+
14
+ Excepción: avisos de seguridad, acciones irreversibles y secuencias donde el orden importa se escriben completos y sin comprimir.
package/package.json CHANGED
@@ -1,6 +1,25 @@
1
1
  {
2
2
  "name": "orca-multiagent-kit",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.2.0",
4
+ "description": "Una sola fuente de reglas y skills (CSR + MAW) para Claude Code, Antigravity, Codex, Copilot y Cursor, con orquestación multiagente.",
5
+ "license": "MIT",
6
+ "author": "Fernando Baquero (https://github.com/FernandoBaqueroo)",
7
+ "contributors": ["Necro-Coder (https://github.com/Necro-Coder)"],
8
+ "homepage": "https://github.com/FernandoBaqueroo/orca-multiagent-kit#readme",
9
+ "repository": { "type": "git", "url": "git+https://github.com/FernandoBaqueroo/orca-multiagent-kit.git" },
10
+ "bugs": { "url": "https://github.com/FernandoBaqueroo/orca-multiagent-kit/issues" },
11
+ "bin": {
12
+ "omk": "bin/omk.js",
13
+ "orca-multiagent-kit": "bin/omk.js"
14
+ },
15
+ "files": [
16
+ "bin/", "speckit-extension/", "core/", "rules/", "skills/", "templates/", "output-styles/", "docs/",
17
+ "install.sh", "VERSION", "GUIA.html", "AI_INSTALL.md", "CHANGELOG.md", "LICENSE", "README.md"
18
+ ],
19
+ "engines": { "node": ">=18" },
20
+ "os": ["darwin", "linux", "win32"],
21
+ "keywords": ["ai-agents", "claude-code", "antigravity", "gemini", "codex", "copilot", "cursor", "orca", "agent-skills", "multi-agent", "worktrees", "spec-kit", "agents-md"],
22
+ "scripts": {
23
+ "test": "bash scripts/check.sh && bash tests/test_install.sh && bash tests/test_cli.sh && bash tests/test_speckit.sh"
24
+ }
25
+ }
@@ -0,0 +1,28 @@
1
+ # 00 — Router de reglas CSR
2
+
3
+ Carga progresiva: el núcleo (`~/.agents/AGENTS.md`) está siempre en contexto; todo lo demás se lee **solo cuando el disparador se cumple**. Objetivo: máxima calidad por token.
4
+
5
+ | Fichero (`~/.agents/rules/`) | Disparador | Coste aprox. |
6
+ |---|---|---|
7
+ | `10-communication.md` | El usuario se queja del formato, pide verbosidad, o dudas de estilo | ~600 tok |
8
+ | `20-clean-code.md` | Escribir, revisar o refactorizar cualquier código | ~1.100 tok |
9
+ | `30-security.md` | Siempre que se escriba código de producción | ~1.300 tok |
10
+ | `31-security-audit.md` | Auditoría, pre-release, o código que toca I/O, auth, cripto, red, SQL, ficheros, procesos | ~2.000 tok |
11
+ | `40-testing.md` | Escribir/arreglar tests o definir cobertura | ~1.200 tok |
12
+ | `50-done-gate.md` | Antes de declarar una tarea terminada | ~1.100 tok |
13
+ | `60-git-workflow.md` | Commit, rama, PR, release | ~700 tok |
14
+ | `70-performance.md` | Queja de lentitud, bucles calientes, consultas, bundle, memoria | ~1.000 tok |
15
+ | `75-reliability.md` | Errores, reintentos, timeouts, logging, métricas, migraciones | ~900 tok |
16
+ | `80-supply-chain.md` | Añadir/actualizar dependencia, tocar CI/CD, publicar artefacto | ~900 tok |
17
+ | `90-docs-comments.md` | README, ADR, comentarios, changelog, API docs | ~700 tok |
18
+ | `95-multi-agent.md` | Repartir trabajo entre varios agentes, worktrees, Orca | ~1.200 tok |
19
+ | `lang/<x>.md` | Se edita un fichero de ese lenguaje | 400-900 tok c/u |
20
+
21
+ ## Lenguajes disponibles (`~/.agents/rules/lang/`)
22
+ `rust` · `typescript` (TS+JS+Node) · `react` · `python` · `go` · `java` · `csharp` · `cpp` · `php` · `ruby` · `kotlin` · `swift` · `dart-flutter` · `sql` · `shell` (bash+PowerShell) · `web` (HTML/CSS/a11y) · `infra` (Docker/K8s/Terraform/YAML/CI)
23
+
24
+ ## Regla de economía
25
+ 1. `STACK.md` primero: dice qué módulos están activos en este repo.
26
+ 2. Un módulo por necesidad real, no "por si acaso".
27
+ 3. Si ya leíste un módulo en esta sesión, no lo releas.
28
+ 4. Cita reglas por identificador (`30-security §Cripto`), no copiando el texto.
@@ -0,0 +1,58 @@
1
+ # 10 — Protocolo de comunicación: casos y ejemplos
2
+
3
+ > Las reglas duras están en `~/.agents/AGENTS.md` §2 y no se repiten aquí.
4
+ > Este fichero solo cubre lo que no cabe en el núcleo: prefijos, disparadores de detalle, excepciones y ejemplos.
5
+
6
+ ## Principio
7
+ Los tokens de prosa son gasto. Los de razonamiento y código son inversión. Comprime lo primero; no toques lo segundo.
8
+
9
+ ## Prefijos canónicos (una línea cada uno)
10
+ - `RISK:` riesgo técnico relevante que el usuario debe conocer.
11
+ - `ASSUMPTION:` supuesto tomado para no bloquear el trabajo.
12
+ - `BLOCKED:` no se puede continuar, y por qué.
13
+ - `CONFLICT:` una regla superior contradice a otra (ver precedencia en §0 del núcleo).
14
+ - `DEFERRED:` fuera de alcance, o no hecho, y por qué.
15
+
16
+ ## Cuándo extenderse
17
+ Disparadores explícitos del usuario: `explica`, `detalla`, `justifica`, `compara`, `--verbose`, `why`, `walk me through`.
18
+ También cuando el producto es un documento para terceros (ADR, README, informe, PR): ahí escribes para esa audiencia, con la extensión que merezca, no para el chat.
19
+
20
+ ## Excepciones obligatorias a la brevedad (claridad por encima del ahorro)
21
+ - Avisos de seguridad y acciones irreversibles: frase completa e inequívoca.
22
+ - Secuencias donde el orden importa: migraciones, despliegues, rollback.
23
+ - Cuando comprimir crearía ambigüedad técnica.
24
+ - Cuando el usuario repite una pregunta: significa que la respuesta anterior no se entendió.
25
+
26
+ ## Ejemplos
27
+ Mal: «¡Buena pregunta! He revisado el fichero y parece que el problema podría estar en el middleware de autenticación. Voy a arreglarlo ahora.»
28
+ Bien: «Bug: `auth.ts:31` compara expiración con `<` en vez de `<=`. Corregido + test.»
29
+
30
+ Mal: tabla decorativa de 12 filas resumiendo los cambios.
31
+ Bien: `4 ficheros, +120/-31. Gates: PASS.`
32
+
33
+ Mal: pegar 80 líneas de stack trace.
34
+ Bien: `FAIL test_transfer: expected 0, got -50 (overdraft.rs:44). Falta la comprobación de saldo.`
35
+
36
+ ## Lectura de ficheros
37
+ Lee solo lo necesario, con búsqueda dirigida (grep/glob/símbolo) en vez de volcar ficheros enteros. No vuelques en el chat lo leído: solo el fragmento decisivo.
38
+
39
+ ## Preguntas y confirmaciones
40
+ - No pidas confirmación para acciones reversibles y de bajo riesgo (leer, listar, generar un borrador).
41
+ - Pregunta solo si la ambigüedad cambia el resultado de forma material (arquitecturas incompatibles) o la acción es irreversible o de alto impacto (borrar datos, producción, migraciones). Una pregunta concreta, no una lista.
42
+
43
+ ## Nivel técnico del usuario
44
+ Desarrollador fullstack (Next.js/React, Node.js/Express, TypeScript, PostgreSQL/Supabase, Docker, CI/CD, Google Cloud). Da por sabidos los conceptos estándar (async/await, contenedores, REST, SQL, transacciones): sin glosarios ni analogías. Contexto histórico o teórico solo si lo pide ("por qué existe X").
45
+
46
+ ## Tabla de comportamiento
47
+ | Situación | Comportamiento |
48
+ |---|---|
49
+ | Petición de código | Código directo, sin preámbulo ni cierre |
50
+ | Explicación técnica | Solo lo no obvio, frases cortas |
51
+ | Ambigüedad menor | Asume la interpretación más probable: `ASSUMPTION:` |
52
+ | Ambigüedad crítica o acción irreversible | Una sola pregunta concreta |
53
+ | Multi-paso con éxito | Solo el resultado |
54
+ | Error en ejecución | Error + causa probable, 1–2 frases |
55
+ | Petición de brevedad | Lista o tabla, sin prosa |
56
+
57
+ ## Límite
58
+ La brevedad nunca justifica omitir avisos de seguridad, confirmaciones de acciones destructivas, ni ocultar que un test falló o que parte del alcance quedó sin hacer.
@@ -0,0 +1,59 @@
1
+ # 20 — Clean Code y buenas prácticas (agnóstico de lenguaje)
2
+
3
+ ## Ley 0
4
+ Escribe código que parezca escrito por quien ya mantenía el repo: mismas convenciones, mismo vocabulario, misma densidad de comentarios. Coherencia > preferencia personal.
5
+
6
+ ## Nombres
7
+ - Revelan intención: `elapsedDays`, no `d`. Sin abreviaturas inventadas (`cfg`, `usr`, `tmp2`).
8
+ - Pronunciables y buscables. Constantes con nombre, nunca números mágicos.
9
+ - Funciones = verbo (`calculateTotal`), booleanos = predicado (`isExpired`, `hasAccess`).
10
+ - Un concepto, una palabra en todo el repo (`fetch` vs `get` vs `retrieve`: elige una).
11
+ - El nombre no miente: si la función también escribe en disco, el nombre lo dice.
12
+
13
+ ## Funciones
14
+ - Una responsabilidad, un nivel de abstracción por función.
15
+ - Objetivo: ≤ 40 líneas, ≤ 4 parámetros, complejidad ciclomática ≤ 10, anidamiento ≤ 3.
16
+ Superarlo exige justificación escrita en el PR, no en un comentario.
17
+ - Sin efectos secundarios ocultos. Comando (muta, no devuelve) o consulta (devuelve, no muta).
18
+ - Sin flags booleanos como parámetro: si hay `doX(true)`, hay dos funciones.
19
+ - Cláusulas de guarda al principio; return temprano en vez de `else` anidados.
20
+
21
+ ## Estructura
22
+ - **Núcleo puro / cáscara imperativa**: lógica de negocio determinista y sin I/O; I/O en los bordes.
23
+ - Dependencias hacia dentro (dominio no conoce framework, ni ORM, ni HTTP).
24
+ - Inyecta dependencias; nada de singletons globales ni `new` de infraestructura dentro del dominio.
25
+ - Módulos por capacidad de negocio, no por tipo técnico, cuando el proyecto crece.
26
+ - Interfaces mínimas: expón lo que se usa; todo lo demás, privado.
27
+
28
+ ## Estado y datos
29
+ - Inmutabilidad por defecto; mutación local y explícita.
30
+ - Estado válido por construcción: tipos que no permiten representar lo imposible (`NonEmptyList`, `Email`, `Money{amount,currency}`).
31
+ - Valida en el borde, confía dentro. Nada de revalidar lo mismo en 6 capas.
32
+ - Nulos: evítalos; `Option`/`Maybe`/union explícita. Si el lenguaje los tiene, prohíbe el null implícito.
33
+
34
+ ## Errores
35
+ - Falla rápido y ruidoso en errores de programación; devuelve error tipado en errores esperados.
36
+ - Nunca captures lo que no sabes tratar. Nunca `catch {}` vacío.
37
+ - Mensajes con contexto accionable (qué, dónde, con qué entrada), sin datos sensibles.
38
+ - Conserva la causa original (`cause`, `%w`, `from e`, `source`).
39
+
40
+ ## Duplicación y abstracción
41
+ - DRY sobre conocimiento, no sobre texto coincidente.
42
+ - **Regla de tres**: no abstraigas hasta el tercer caso real. La abstracción errónea cuesta más que la duplicación.
43
+ - YAGNI: nada de parámetros, hooks o capas "para el futuro".
44
+ - Prefiere composición a herencia; herencia solo para sustitución real (LSP).
45
+
46
+ ## Comentarios
47
+ - Explican **por qué**, nunca **qué**. Si el comentario explica el qué, renombra el código.
48
+ - Comentario obligatorio en: decisiones no obvias, workarounds (con enlace al issue), invariantes, complejidad algorítmica elegida, cualquier supresión de lint/tipo.
49
+ - Prohibido: código comentado, changelogs en cabecera, comentarios obsoletos.
50
+
51
+ ## Olores que obligan a refactor
52
+ Función >40 líneas · clase >300 líneas · >3 niveles de anidamiento · lista de parámetros larga · envidia de características · obsesión por primitivos · cadenas de `if/else` sobre tipo (usa polimorfismo o match exhaustivo) · retorno de `null` como señal · booleano de control de flujo · dependencia circular · nombre con `Manager`/`Helper`/`Utils` sin significado.
53
+
54
+ ## Antes de dar por escrito un fichero
55
+ - [ ] ¿Se lee de arriba abajo como una narración?
56
+ - [ ] ¿Cada nombre resiste ser leído en voz alta por otro dev?
57
+ - [ ] ¿Hay algún camino de error sin probar?
58
+ - [ ] ¿He borrado lo que ya no se usa (código, imports, flags, tests)?
59
+ - [ ] ¿He respetado el estilo del repo por encima del mío?