@ancleto/spec 0.12.0 → 0.12.1

package/README.md

@@ -77,7 +77,7 @@ Ancleto resuelve esto centralizando las reglas de negocio en un motor de memoria
 
 **Wizard interactivo** — Banner animado y menús navegables con flechas en `init` e `install`, sin librerías pesadas.
 
-**Hosts e IDEs (7)** — opencode, claude, vscode, antigravity, cursor, roo y copilot, cada uno con su layout nativo (Copilot: prompts en `.github/prompts` + MCP en `copilot-mcp.json`).
+**Hosts e IDEs (8)** — opencode, claude, vscode, antigravity, cursor, roo, copilot y commandcode, cada uno con su layout nativo (Copilot: prompts en `.github/prompts` + MCP en `copilot-mcp.json`; Command Code: `.commandcode/*` + MCP en `.mcp.json`).
 
 **Perfil de test automation** — `--profile test`: tester ampliado (planning/generation/healing/coverage), comandos `cleto-test-*` y estructura `testspec/` para proyectos Playwright.
 
@@ -151,6 +151,7 @@ del host (el CLI no deduplica ni elige un "ganador").
 | `cursor` | `.cursor/skills/<n>/SKILL.md` | — | — |
 | `roo` | `.roo/skills/<n>/SKILL.md` | — | — |
 | `copilot` | — | `.github/prompts/<n>.prompt.md` | `.github/prompts/<n>.prompt.md` |
+| `commandcode` | `.commandcode/skills/<n>/SKILL.md` | `.commandcode/agents/<n>.md` (adaptado) | `.commandcode/commands/<n>.md` |
 
 Cada host recibe sus skills en **su** directorio nativo. **`.agents/skills` es un punto de lectura
 compartido** —lo leen opencode, Cursor, VS Code y Antigravity—, no un destino universal: Claude lee
@@ -172,18 +173,36 @@ for agent '<n>'`): un id inexistente cuelga el subagent. Los ids que sólo exist
 de MCP se expresa por `mcpServers`/`.agents/mcp_config.json`, nunca como tool id. El campo `skill` no
 es una tool: se cubre con el surfaceo automático de skills de Antigravity.
 
+**Command Code** (CLI `cmd`) usa su layout nativo por asset bajo `.commandcode/`: skills en
+`.commandcode/skills/<n>/SKILL.md` (Agent Skills, verbatim), agents en `.commandcode/agents/<n>.md`
+(frontmatter adaptado) y commands en `.commandcode/commands/<n>.md` (el body es el prompt, copia
+verbatim). Sus agents adaptan el frontmatter de opencode: `name` inyectado, `description` preservado,
+`mode`/`color`/`temperature`/`permission` eliminados, `model` **omitido** (el host hereda el modelo de
+sesión; elegilo con `/model`, el tier no lo reescribe) y `tools` como **lista** de ids verificados
+(`read`→`read_file`, `write`→`write_file`, `edit`→`edit_file`, `bash`→`shell_command`, `grep`→`grep`,
+`glob`→`glob`, `webfetch`→`web_fetch`, `websearch`→`web_search`, `todowrite`→`todo_write`). Las tools
+de memoria (`searchMemory`/`recordRule`/`recordDecision`) se emiten con la convención MCP de Command
+Code (`mcp__ancleto-memory__<tool>`). Una clave sin id verificado se omite con aviso
+(`skip tool '<k>': no verified Command Code id for agent '<n>'`). A diferencia de otros hosts, en
+Command Code `tools` **omitido** significa "ninguna tool": si el agent de origen no declara `tools`,
+se emite `tools: "*"` (el default de opencode es "todas"). El body de los commands invoca "the Skill
+tool" (no se transforma); en Command Code el equivalente es `/skill:<name>`.
+
 Los assets que un host no soporta (por ejemplo `agents`/`commands` de `cursor` y `roo`)
 **no se escriben** y el instalador avisa por `stderr`
 (`skip agents: not supported by host 'cursor'`) sin abortar. La instalación es **aditiva y no
 destructiva**: instalar con otro agente escribe en su base y preserva los layouts previos, y el
 manifiesto `.ancletorc.installedPaths` acumula la unión de los destinos realmente escritos.
 
-La **configuración MCP específica de host** está fuera de alcance con **una excepción**: para
+La **configuración MCP específica de host** está fuera de alcance con **dos excepciones**: para
 `agent: antigravity` el CLI genera o mergea (no destructivo) el MCP de workspace
-`.agents/mcp_config.json` con esquema `{ "mcpServers": { "<n>": { "command", "args", "env" } } }`,
-incluyendo el servidor de memoria `ancleto-memory`; preserva `mcpServers` preexistentes y no pisa
-homónimos. `.mcp.json` (Claude) y `.vscode/mcp.json` (VS Code) siguen fuera de alcance, al igual que el
-MCP global de Antigravity. `claude` se soporta con adaptación de frontmatter obligatoria para `agents`
+`.agents/mcp_config.json` con esquema `{ "mcpServers": { "<n>": { "command", "args", "env" } } }`, y
+para `agent: commandcode` el MCP de proyecto `.mcp.json` con esquema
+`{ "mcpServers": { "<n>": { "transport": "stdio", "command", "args", "env" } } }`; en ambos casos
+incluye el servidor de memoria `ancleto-memory`, preserva `mcpServers` preexistentes y no pisa
+homónimos. `.mcp.json` sólo lo gestiona `commandcode` (para `claude` sigue fuera de alcance), al igual
+que `.vscode/mcp.json` (VS Code) y el MCP global de Antigravity. `claude` se soporta con adaptación de
+frontmatter obligatoria para `agents`
 (se omiten `model`/`tools` sin equivalencia verificada y las claves
 `mode`/`color`/`temperature`/`permission`), sin MCP propio. **Copilot** instala agents y commands
 como prompt files en `.github/prompts/*.prompt.md` (mismo adapter, sin `model:`) y su MCP en

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ancleto/spec",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "Orquestador SDD liviano con subagentes optimizados para costo/tokens",
   "type": "module",
   "bin": {

package/src/cli/index.js

@@ -36,13 +36,15 @@ Uso:
   ancleto install --tier <nivel>     normal | minimo | gratis (wizard interactivo en TTY)
   ancleto install --lang <codigo>    auto | es | en | pt (idioma de los artifacts; auto = idioma de la conversacion)
   ancleto install --exclude <globs>  Paths excluidos del discovery, coma-separados (ej: "**/*.png,docs")
-  ancleto install --agent <nombre>    opencode | claude | vscode | antigravity | cursor | roo | copilot (wizard si no esta guardado)
+  ancleto install --agent <nombre>    opencode | claude | vscode | antigravity | cursor | roo | copilot | commandcode (wizard si no esta guardado)
                                    Elige el layout nativo a materializar (directorio + convencion de
                                    nombre) y el adapter de frontmatter del host. NO arbitra el
                                    descubrimiento entre hosts: si dos leen el mismo directorio, eso es
                                    efecto del host (no se deduplica ni se elige "ganador").
                                    antigravity instala skills, agents adaptados y commands como skills
                                    (.agents/*) y mergea el MCP de workspace .agents/mcp_config.json.
+                                   commandcode instala skills, agents adaptados y commands en
+                                   .commandcode/* y mergea el MCP de proyecto .mcp.json.
   ancleto install --profile <perfil>  general | test (perfil de test automation con Playwright; persiste en .ancletorc)
   ancleto update [--project <dir>]    Alias de install (re-instala sobre lo existente)
                                    Parado en un proyecto con .ancletorc opera sobre ese proyecto;
@@ -612,7 +614,7 @@ async function applyTier(agentsDir, tier, models = null) {
   }
 }
 
-const SUPPORTED_AGENTS = ['opencode', 'claude', 'vscode', 'antigravity', 'cursor', 'roo', 'copilot']
+const SUPPORTED_AGENTS = ['opencode', 'claude', 'vscode', 'antigravity', 'cursor', 'roo', 'copilot', 'commandcode']
 const DEFAULT_AGENT = 'opencode'
 
 function askAgent() {
@@ -855,12 +857,48 @@ async function mergeCopilotMcp(projectDir, mcpMap) {
   return { file, added }
 }
 
+// Command Code: MCP de proyecto en `.mcp.json` (scope `project`, versionado con
+// el repo). Esquema del host: `{ mcpServers: { <name>: { transport: 'stdio',
+// command, args, env? } } }` (se descartan `type`/`enabled` de opencode). Merge NO
+// destructivo: se preservan `mcpServers` y demas claves top-level, no se pisa un
+// servidor homonimo, y un JSON invalido se avisa sin sobrescribir.
+function toCommandCodeServer(def) {
+  const command = Array.isArray(def.command) ? def.command : [def.command]
+  const server = { transport: 'stdio', command: command[0], args: command.slice(1) }
+  if (def.env) server.env = def.env
+  return server
+}
+
+async function mergeCommandCodeMcp(projectDir, mcpMap) {
+  if (Object.keys(mcpMap).length === 0) return { file: null, added: [] }
+  const file = join(projectDir, '.mcp.json')
+  let cfg = {}
+  if (await exists(file)) {
+    try {
+      cfg = JSON.parse((await readFile(file, 'utf8')).replace(/^\uFEFF/, ''))
+    } catch {
+      console.warn('ancleto: no se pudo leer .mcp.json como JSON; MCP de Command Code no se modifico')
+      return { file, added: [] }
+    }
+  }
+  cfg.mcpServers = cfg.mcpServers || {}
+  const added = []
+  for (const [name, def] of Object.entries(mcpMap)) {
+    if (cfg.mcpServers[name]) continue
+    cfg.mcpServers[name] = toCommandCodeServer(def)
+    added.push(name)
+  }
+  await writeFile(file, JSON.stringify(cfg, null, 2) + '\n')
+  return { file, added }
+}
+
 // D6: dueno unico del MCP de host. Antigravity mergea `.agents/mcp_config.json`;
-// el resto conserva `mergeMcp` sobre opencode.json (targetDir = .opencode del
-// proyecto o config global).
+// Command Code mergea `.mcp.json`; el resto conserva `mergeMcp` sobre opencode.json
+// (targetDir = .opencode del proyecto o config global).
 async function setupHostMcp(targetDir, mcpMap, { projectDir = null, agent = null } = {}) {
   if (Object.keys(mcpMap).length === 0) return { file: null, added: [] }
   if (agent === 'antigravity' && projectDir) return mergeAntigravityMcp(projectDir, mcpMap)
+  if (agent === 'commandcode' && projectDir) return mergeCommandCodeMcp(projectDir, mcpMap)
   await mkdir(targetDir, { recursive: true })
   return mergeMcp(targetDir, mcpMap)
 }
@@ -895,6 +933,39 @@ async function refreshCopilotMcp(projectDir) {
   return { file, fixed }
 }
 
+// Regenera entradas rotas y agrega ausentes en `.mcp.json` de Command Code (para
+// upgrade). Mismo criterio que `refreshCopilotMcp`, con el esquema del host.
+async function refreshCommandCodeMcp(projectDir) {
+  const file = join(projectDir, '.mcp.json')
+  let cfg = {}
+  if (await exists(file)) {
+    try {
+      cfg = JSON.parse((await readFile(file, 'utf8')).replace(/^\uFEFF/, ''))
+    } catch {
+      cfg = {}
+    }
+  }
+  cfg.mcpServers = cfg.mcpServers || {}
+  const fresh = buildDefaultMcp({ withEngram: Boolean(cfg.mcpServers.engram) })
+  const fixed = []
+  for (const [name, def] of Object.entries(cfg.mcpServers)) {
+    if (!fresh[name]) continue
+    const asArray = { command: [def.command, ...(Array.isArray(def.args) ? def.args : [])] }
+    if (mcpCommandBroken(asArray)) {
+      Object.assign(cfg.mcpServers[name], toCommandCodeServer(fresh[name]))
+      fixed.push(name)
+    }
+  }
+  for (const [name, def] of Object.entries(fresh)) {
+    if (!cfg.mcpServers[name]) {
+      cfg.mcpServers[name] = toCommandCodeServer(def)
+      fixed.push(`${name} (agregado)`)
+    }
+  }
+  await writeFile(file, JSON.stringify(cfg, null, 2) + '\n')
+  return { file, fixed }
+}
+
 async function copyAssets(dest) {
   await mkdir(dest, { recursive: true })
   for (const d of ASSETS) {
@@ -940,6 +1011,16 @@ const AGENT_TARGETS = {
     skills: null,
     agents: { dir: '.github/prompts', ext: '.prompt.md' },
     commands: { dir: '.github/prompts', ext: '.prompt.md' }
+  },
+  // Command Code: layout nativo por asset bajo `.commandcode/`. Los tres assets
+  // son nativos: skills (Agent Skills, identity), agents (frontmatter adaptado,
+  // ver `adaptCommandCodeFrontmatter`) y commands (custom slash commands, el body
+  // es el prompt, copia verbatim). El MCP de proyecto vive en `.mcp.json`
+  // (ver `mergeCommandCodeMcp`).
+  commandcode: {
+    skills: { dir: '.commandcode/skills' },
+    agents: { dir: '.commandcode/agents', ext: MD_EXT },
+    commands: { dir: '.commandcode/commands', ext: MD_EXT }
   }
 }
 
@@ -956,6 +1037,18 @@ normal = flujo completo, minimo = pasos agrupados y económicos, gratis = modelo
 gratis disponible en tu cuenta.
 `
 
+// Solo Command Code: los tiers tampoco cambian modelos (el agent no fija `model`,
+// hereda el de la sesión); la nota lo recuerda al empezar.
+const COMMANDCODE_MODEL_NOTE = `
+## Nota de modelo (solo Command Code)
+
+Elegí el modelo con \`/model\` antes de empezar: los tiers de ancleto
+(normal|minimo|gratis) no cambian modelos en Command Code, solo el nivel de
+esfuerzo (normal = flujo completo, minimo = pasos agrupados y económicos,
+gratis = modelo gratis disponible en tu cuenta). Los subagentes heredan el
+modelo de la sesión porque su frontmatter no fija \`model\`.
+`
+
 // D12: asset no soportado -> no se escribe y se avisa a stderr (no bloqueante).
 function warnUnsupportedAsset(asset, agent) {
   console.error(`skip ${asset}: not supported by host '${agent}'`)
@@ -985,7 +1078,11 @@ async function installAssetFiles(cat, projectDir, spec, host, srcDir = null) {
     const base = e.name.slice(0, -MD_EXT.length)
     const content = await readFile(join(origin, e.name), 'utf8')
     const adapted = adaptFrontmatter(content, host, cat, base)
-    const body = (host === 'copilot' && cat === 'agents' && base === 'orchestrator') ? adapted + COPILOT_MODEL_NOTE : adapted
+    let body = adapted
+    if (cat === 'agents' && base === 'orchestrator') {
+      if (host === 'copilot') body += COPILOT_MODEL_NOTE
+      else if (host === 'commandcode') body += COMMANDCODE_MODEL_NOTE
+    }
     await writeFile(join(destDir, `${base}${spec.ext}`), body)
   }
 }
@@ -1490,6 +1587,12 @@ async function upgradeCmd(args) {
     console.log(fixed.length
       ? `  ✔ MCP regenerados en ${file}: ${fixed.join(', ')}`
       : `  ✔ MCP sanos en ${file}, sin cambios`)
+  } else if (agent === 'commandcode') {
+    const { file, fixed } = await refreshCommandCodeMcp(projectDir)
+    console.log(`  ✔ skills actualizadas en ${skillsDir} (${ANCLETO_SKILLS.length} skills)`)
+    console.log(fixed.length
+      ? `  ✔ MCP regenerados en ${file}: ${fixed.join(', ')}`
+      : `  ✔ MCP sanos en ${file}, sin cambios`)
   } else {
     console.log(`  ✔ skills actualizadas en ${skillsDir} (${ANCLETO_SKILLS.length} skills)`)
   }
@@ -2265,8 +2368,9 @@ async function checkAgentsFrontmatter(cwd, dirRel, actual, expected, fileExt) {
       source = source.replace(/^model: .*$/m, `model: ${tierModelsMap[name]}`)
     }
     let expectedContent = adaptFrontmatter(source, host, 'agents', name)
-    if (host === 'copilot' && name === 'orchestrator') {
-      expectedContent += COPILOT_MODEL_NOTE
+    if (name === 'orchestrator') {
+      if (host === 'copilot') expectedContent += COPILOT_MODEL_NOTE
+      else if (host === 'commandcode') expectedContent += COMMANDCODE_MODEL_NOTE
     }
     const installed = await readFile(join(cwd, dirRel, f), 'utf8')
     if (installed !== expectedContent) {

package/src/core/adapters/frontmatter.js

@@ -12,12 +12,12 @@ export const AGENT_ADAPTER_DROP = new Set(['mode', 'color', 'temperature', 'perm
 // Hosts conocidos por el modulo. Cualquier host fuera de este conjunto cae en la
 // rama `unknown` (no aborta; emite aviso a stderr y retorna el contenido sin
 // cambios).
-const KNOWN_HOSTS = new Set(['opencode', 'claude', 'vscode', 'antigravity', 'cursor', 'roo', 'copilot'])
+const KNOWN_HOSTS = new Set(['opencode', 'claude', 'vscode', 'antigravity', 'cursor', 'roo', 'copilot', 'commandcode'])
 
 // Hosts para los que existe una transformacion documentada de agents
 // (distinta de identidad). Cursor y Roo viven fuera: no hay formato de frontmatter
 // propio, así que la adaptación es passthrough con aviso.
-const TRANSFORM_AGENTS = new Set(['claude', 'vscode', 'antigravity', 'copilot'])
+const TRANSFORM_AGENTS = new Set(['claude', 'vscode', 'antigravity', 'copilot', 'commandcode'])
 
 // Tabla unica (fijada contra la tabla oficial de frontmatter de Custom
 // Subagents) de ids de Antigravity. Conjunto CERRADO: solo se emiten estos ids.
@@ -35,6 +35,31 @@ export const ANTIGRAVITY_TOOL_MAP = {
   todowrite: 'manage_task'
 }
 
+// Tabla unica (fijada contra la documentacion oficial de Command Code) de ids de
+// tools. Conjunto CERRADO: solo se emiten estos ids. Toda clave del mapa `tools`
+// de opencode sin id aqui se omite con aviso a stderr (nunca en silencio).
+export const COMMANDCODE_TOOL_MAP = {
+  read: 'read_file',
+  write: 'write_file',
+  edit: 'edit_file',
+  bash: 'shell_command',
+  grep: 'grep',
+  glob: 'glob',
+  webfetch: 'web_fetch',
+  websearch: 'web_search',
+  todowrite: 'todo_write'
+}
+
+// Tools de la memoria propia del framework. Command Code expone los servers MCP
+// con la convencion documentada `mcp__<server>__<tool>`; `ancleto-memory` es el
+// server que registra `buildDefaultMcp`. Estas claves del mapa `tools` de opencode
+// son sus tools, asi que se emiten con el nombre MCP completo.
+export const COMMANDCODE_MCP_TOOL_MAP = {
+  searchMemory: 'mcp__ancleto-memory__searchMemory',
+  recordRule: 'mcp__ancleto-memory__recordRule',
+  recordDecision: 'mcp__ancleto-memory__recordDecision'
+}
+
 // Parser propio sin dependencias. Cada entrada conserva su clave y sus lineas
 // crudas (incluye block scalars y mapas anidados), preservando orden.
 export function parseFrontmatter(content) {
@@ -147,6 +172,45 @@ function adaptAntigravityFrontmatter(content, name) {
   return serializeFrontmatter(parsed)
 }
 
+// Adapta el frontmatter de un agent de opencode al de Command Code. `name` (el
+// host lo requiere; default filename) se inyecta desde el nombre del archivo.
+// `description` se preserva. `mode`/`color`/`temperature`/`permission` se eliminan
+// y `model` se omite: Command Code hereda el modelo de sesion cuando no se declara
+// (nunca se mapea un id de `opencode-go/*`). `tools` sale como lista de ids
+// verificados (o `"*"` si el origen no declara tools: el default de opencode es
+// "todas" y el de Command Code es "ninguna"). Una clave sin id verificado se omite
+// con aviso a stderr (nunca en silencio).
+function adaptCommandCodeFrontmatter(content, name) {
+  const parsed = parseFrontmatter(content)
+  if (!parsed.hasFrontmatter) return content
+  const byKey = (k) => parsed.entries.find((e) => e.key === k)
+
+  const managed = new Set([...AGENT_ADAPTER_DROP, 'name', 'description', 'tools'])
+  const kept = parsed.entries.filter((e) => e.key && !managed.has(e.key))
+
+  const toolsEntry = byKey('tools')
+  const toolIds = []
+  if (toolsEntry) {
+    for (const { key, value } of parseToolFlags(toolsEntry)) {
+      if (value === 'false') continue
+      const id = COMMANDCODE_TOOL_MAP[key] || COMMANDCODE_MCP_TOOL_MAP[key]
+      if (id) {
+        toolIds.push(id)
+        continue
+      }
+      console.error(`skip tool '${key}': no verified Command Code id for agent '${name}'`)
+    }
+  }
+
+  const out = [{ key: 'name', lines: [`name: ${name}`] }]
+  const description = byKey('description')
+  if (description) out.push(description)
+  out.push(toolsEntry ? { key: 'tools', lines: [`tools: [${toolIds.join(', ')}]`] } : { key: 'tools', lines: ['tools: "*"'] })
+  out.push(...kept)
+  parsed.entries = out
+  return serializeFrontmatter(parsed)
+}
+
 // Elimina las claves gestionadas por el adaptador (mode/color/temperature/
 // permission/model/tools) preservando el resto y el body. Para claude, vscode y
 // copilot. Si no hay frontmatter, retorna el contenido sin cambios.
@@ -166,6 +230,8 @@ function dropManagedKeys(content) {
 //   opencode                    → identity (passthrough)
 //   antigravity + agents        → adaptAntigravityFrontmatter(content, name)
 //   antigravity + (skills/cmds) → identity
+//   commandcode + agents        → adaptCommandCodeFrontmatter(content, name)
+//   commandcode + (skills/cmds) → identity
 //   claude/vscode/copilot + ags → dropManagedKeys(content)
 //   claude/vscode/copilot + sk  → identity
 //   cursor/roo                  → identity + aviso stderr (sin formato documentado)
@@ -182,5 +248,6 @@ export function adaptFrontmatter(content, host, assetKind, name) {
   if (assetKind !== 'agents') return content
   if (!TRANSFORM_AGENTS.has(host)) return content // opencode u otro conocido sin transform
   if (host === 'antigravity') return adaptAntigravityFrontmatter(content, name)
+  if (host === 'commandcode') return adaptCommandCodeFrontmatter(content, name)
   return dropManagedKeys(content)
 }