@dsalazardev/ai-hub-cli 0.2.0 → 0.3.0

package/dist/sync/sync.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { mapLimit } from '../concurrency.js';
 import { isEngineCheckout } from '../source-checkout.js';
 import { loadSyncConfig, resolveSourcePath } from './config.js';
+import { ownedBySpeckit, readSpeckitState, speckitOwnedPaths } from '../speckit/state.js';
 import { normalize, renderAll } from './render.js';
 import { GENERATOR_VERSION, readLock, sha256, writeLock, } from './lock.js';
 export class SyncSourceError extends Error {
@@ -15,6 +16,16 @@ export class SyncSourceError extends Error {
         this.name = 'SyncSourceError';
     }
 }
+export class SpeckitOwnershipError extends Error {
+    paths;
+    constructor(paths) {
+        super(`colisión de propiedad con Spec Kit: ${paths.join(', ')}\n` +
+            'Esas rutas pertenecen a Spec Kit (sus manifiestos de integración, sus extensiones o el espacio speckit-*/speckit.*); ' +
+            'ai-hub no las escribe. No se escribió ningún archivo ni el lock.');
+        this.paths = paths;
+        this.name = 'SpeckitOwnershipError';
+    }
+}
 export class SyncSourceCheckoutError extends Error {
     root;
     constructor(root) {
@@ -34,16 +45,28 @@ export async function runSync(root, options) {
     const rendered = await renderAll(root, config);
     const previous = await readLock(root);
     const result = { written: [], removed: [], problems: [] };
+    // Un dueño por archivo: lo que reclama Spec Kit no se escribe ni se borra desde aquí.
+    const speckitPresent = (await readSpeckitState(root)).present;
+    const owned = await speckitOwnedPaths(root, config.tools);
+    const isSpeckit = (rel) => ownedBySpeckit(rel, owned, config.tools, speckitPresent);
+    const collisions = [...rendered.keys()].filter(isSpeckit).sort();
+    if (collisions.length > 0) {
+        if (options.check) {
+            result.problems.push(...collisions.map((rel) => `colisión con Spec Kit: ${rel}`));
+            return result;
+        }
+        throw new SpeckitOwnershipError(collisions);
+    }
     const symlinks = await findSymlinks(root, config, rendered);
-    const obsolete = previous
-        ? Object.keys(previous.files)
-            .filter((rel) => !rendered.has(rel))
-            .sort()
-        : [];
+    const previousEntries = previous ? Object.keys(previous.files).filter((rel) => !rendered.has(rel)) : [];
+    // Entradas que pasaron a Spec Kit: se sueltan del lock sin tocar el archivo de su nuevo dueño.
+    const transferred = previousEntries.filter(isSpeckit).sort();
+    const obsolete = previousEntries.filter((rel) => !isSpeckit(rel)).sort();
     if (options.check) {
         result.problems.push(...(await checkCopies(root, rendered, previous)));
         result.problems.push(...symlinks.map((rel) => `enlace simbólico no permitido: ${rel}`));
         result.problems.push(...obsolete.map((rel) => `destino obsoleto: ${rel}`));
+        result.problems.push(...transferred.map((rel) => `propiedad transferida a Spec Kit (ejecuta ai-hub sync): ${rel}`));
         return result;
     }
     const nextLock = await buildLock(root, rendered);
@@ -55,6 +78,10 @@ export async function runSync(root, options) {
         await fs.rm(path.join(root, rel), { force: true });
         result.removed.push(rel);
     }
+    // Un destino obsoleto no deja su carpeta vacía (p. ej. `.github/skills/speckit-plan/` tras 0.2.x).
+    for (const dir of [...new Set(obsolete.map((rel) => path.posix.dirname(rel)))].sort((a, b) => b.length - a.length)) {
+        await pruneEmptyDirs(root, dir);
+    }
     const written = await mapLimit(sortedEntries(rendered), 24, async ([rel, file]) => {
         const abs = path.join(root, rel);
         const current = await readCopy(abs);
@@ -138,6 +165,9 @@ function categoryOf(source) {
     if (source === '@engine/engine/preflight.md' || source === 'engine/preflight.md') {
         return 'preflight';
     }
+    if (source === '@engine/engine/engine.yaml') {
+        return 'rules';
+    }
     if (source.startsWith('@engine/skills/') || source.includes('/skills/')) {
         return 'skills';
     }
@@ -276,6 +306,19 @@ async function collectSymlinks(root, relDir, found) {
         }
     }
 }
+/** Borra `rel` y sus padres mientras estén vacíos, sin salir de `root`. */
+async function pruneEmptyDirs(root, rel) {
+    let current = rel;
+    while (current !== '.' && current !== '' && !current.startsWith('..')) {
+        const abs = path.join(root, current);
+        const entries = await fs.readdir(abs).catch(() => null);
+        if (entries === null || entries.length > 0) {
+            return;
+        }
+        await fs.rmdir(abs).catch(() => undefined);
+        current = path.posix.dirname(current);
+    }
+}
 async function readCopy(abs) {
     const text = await fs.readFile(abs, 'utf8').catch(() => null);
     return text === null ? null : normalize(text);

package/dist/sync/targets.d.ts

@@ -3,6 +3,17 @@ export type ToolId = (typeof TOOL_IDS)[number];
 export type SkillShape = 'dir' | 'file';
 export type RuleShape = 'md' | 'mdc' | 'instructions';
 export type HookKind = 'markdown' | 'cursor-mdc' | 'copilot-instructions';
+/**
+ * Integración de Spec Kit que sirve a un destino. `commandsDir` es donde Spec Kit escribe
+ * sus comandos y delimita el espacio de nombres reservado `speckit-*` / `speckit.*`.
+ * `skill-dir` escribe `<dir>/speckit-plan/SKILL.md`; `command-file` escribe `<dir>/speckit.plan.md`.
+ */
+export interface SpeckitTarget {
+    integration: string;
+    separator: '-' | '.';
+    commandsDir: string;
+    layout: 'skill-dir' | 'command-file';
+}
 export interface ToolTargets {
     skills: string;
     agents: string | null;
@@ -11,6 +22,8 @@ export interface ToolTargets {
     skillShape: SkillShape;
     ruleShape: RuleShape;
     hookKind: HookKind;
+    /** `null`: el destino no recibe Spec Kit (Copilot). */
+    speckit: SpeckitTarget | null;
 }
 /**
  * Declarative destination table. Adding a tool means adding one row and one id

package/dist/sync/targets.js

@@ -12,6 +12,7 @@ export const TARGETS = {
         skillShape: 'dir',
         ruleShape: 'md',
         hookKind: 'markdown',
+        speckit: { integration: 'claude', separator: '-', commandsDir: '.claude/skills', layout: 'skill-dir' },
     },
     opencode: {
         skills: '.opencode/skills',
@@ -21,6 +22,7 @@ export const TARGETS = {
         skillShape: 'dir',
         ruleShape: 'md',
         hookKind: 'markdown',
+        speckit: { integration: 'opencode', separator: '.', commandsDir: '.opencode/commands', layout: 'command-file' },
     },
     pi: {
         skills: '.pi/skills',
@@ -30,6 +32,7 @@ export const TARGETS = {
         skillShape: 'dir',
         ruleShape: 'md',
         hookKind: 'markdown',
+        speckit: { integration: 'pi', separator: '.', commandsDir: '.pi/prompts', layout: 'command-file' },
     },
     cursor: {
         skills: '.cursor/rules',
@@ -39,6 +42,7 @@ export const TARGETS = {
         skillShape: 'file',
         ruleShape: 'mdc',
         hookKind: 'cursor-mdc',
+        speckit: { integration: 'cursor-agent', separator: '-', commandsDir: '.cursor/skills', layout: 'skill-dir' },
     },
     copilot: {
         skills: '.github/skills',
@@ -48,6 +52,7 @@ export const TARGETS = {
         skillShape: 'dir',
         ruleShape: 'instructions',
         hookKind: 'copilot-instructions',
+        speckit: null,
     },
 };
 export function isToolId(value) {

package/engine/engine.yaml

@@ -113,87 +113,87 @@ commands:
     name: /speckit-assess-intake
     lane: assessment
     artifacts: [intake.md]
-    exit: [GO, KILL, NEEDS_CLARIFICATION]
+    exit: [DONE, BLOCKED]
     role: spec-explorer
-    skill: speckit-assess-intake
+    speckit: speckit.assess.intake
   - id: assess-research
     name: /speckit-assess-research
     lane: assessment
     artifacts: [research.md]
-    exit: [GO, KILL, NEEDS_CLARIFICATION]
+    exit: [DONE, BLOCKED]
     role: spec-explorer
-    skill: speckit-assess-research
+    speckit: speckit.assess.research
   - id: assess-define
     name: /speckit-assess-define
     lane: assessment
     artifacts: [problem.md]
-    exit: [GO, KILL, NEEDS_CLARIFICATION]
+    exit: [DONE, BLOCKED]
     role: spec-explorer
-    skill: speckit-assess-define
+    speckit: speckit.assess.define
   - id: assess-shape
     name: /speckit-assess-shape
     lane: assessment
     artifacts: [concept.md]
-    exit: [GO, KILL, NEEDS_CLARIFICATION]
+    exit: [DONE, BLOCKED]
     role: spec-explorer
-    skill: speckit-assess-shape
+    speckit: speckit.assess.shape
   - id: assess-decide
     name: /speckit-assess-decide
     lane: assessment
     artifacts: [decision.md]
-    exit: [GO, KILL, NEEDS_CLARIFICATION]
+    exit: [GO, NEEDS_CLARIFICATION, KILL]
     role: spec-explorer
-    skill: speckit-assess-decide
+    speckit: speckit.assess.decide
 
   - id: constitution
     name: /speckit.constitution
     lane: feature
     artifacts: [constitution.md]
-    exit: [CREATED, UPDATED]
+    exit: [DONE, BLOCKED]
     role: spec-author
-    skill: speckit-constitution
+    speckit: speckit.constitution
   - id: specify
     name: /speckit.specify
     lane: feature
     artifacts: [spec.md]
-    exit: [DRAFT, READY]
+    exit: [DONE, BLOCKED]
     role: spec-author
-    skill: speckit-specify
+    speckit: speckit.specify
   - id: clarify
     name: /speckit.clarify
     lane: feature
     artifacts: [spec.md]
-    exit: [RESOLVED, OPEN]
+    exit: [DONE, BLOCKED]
     role: spec-author
-    skill: speckit-clarify
+    speckit: speckit.clarify
   - id: plan
     name: /speckit.plan
     lane: feature
     artifacts: [plan.md]
-    exit: [READY]
+    exit: [DONE, BLOCKED]
     role: spec-author
-    skill: speckit-plan
+    speckit: speckit.plan
   - id: checklist
     name: /speckit.checklist
     lane: feature
     artifacts: [checklist.md]
-    exit: [PASS, NEEDS_FIX]
+    exit: [DONE, BLOCKED]
     role: spec-author
-    skill: speckit-checklist
+    speckit: speckit.checklist
   - id: tasks
     name: /speckit.tasks
     lane: feature
     artifacts: [tasks.md]
-    exit: [READY]
+    exit: [DONE, BLOCKED]
     role: spec-author
-    skill: speckit-tasks
+    speckit: speckit.tasks
   - id: analyze
     name: /speckit.analyze
     lane: feature
     artifacts: [analysis.md]
-    exit: [PASS, NEEDS_FIX]
+    exit: [DONE, BLOCKED]
     role: spec-author
-    skill: speckit-analyze
+    speckit: speckit.analyze
   - id: implement
     name: /speckit.implement
     lane: feature
@@ -201,37 +201,57 @@ commands:
     exit: [DONE, BLOCKED]
     role: implementer-frontend
     co_roles: [implementer-backend]
-    skill: speckit-implement
+    speckit: speckit.implement
   - id: converge
     name: /speckit.converge
     lane: feature
     artifacts: [convergence.md]
     exit: [CONVERGED, NEEDS_WORK]
     role: reviewer-architecture
-    skill: speckit-converge
+    speckit: speckit.converge
 
   - id: bug-assess
     name: /speckit-bug-assess
     lane: bug
     artifacts: [assessment.md]
-    exit: [ROOT_CAUSE, NEEDS_DATA]
+    exit: [VALID, NEEDS_REPRODUCTION, INVALID]
     role: reviewer-architecture
-    skill: speckit-bug-assess
+    speckit: speckit.bug.assess
   - id: bug-fix
     name: /speckit-bug-fix
     lane: bug
     artifacts: [fix.md]
-    exit: [FIXED, BLOCKED]
+    exit: [APPLIED, PARTIAL, NOT_APPLIED]
     role: implementer-backend
     co_roles: [implementer-frontend]
-    skill: speckit-bug-fix
+    speckit: speckit.bug.fix
   - id: bug-test
     name: /speckit-bug-test
     lane: bug
     artifacts: [test.md]
     exit: [VERIFIED, PARTIAL, FAILED]
     role: reviewer-tests
-    skill: speckit-bug-test
+    speckit: speckit.bug.test
+
+# Efecto de cada estado de salida sobre las etiquetas ai::* (tabla única, design D2.6).
+# Ningún agente mueve una etiqueta: hermes-control aplica o propone el cambio y un humano confirma
+# las propuestas de cierre (KILL, INVALID).
+exit_effects:
+  GO: mantiene ai::in-spec; Spec-Author empieza la autoría de la feature
+  NEEDS_CLARIFICATION: mantiene ai::in-spec; se repite la etapa indicada
+  KILL: propone ai::done; hermes-control propone el cierre y un humano lo confirma
+  DONE: sin cambio de etiqueta; el artefacto declarado existe y el carril continúa
+  BLOCKED: ai::blocked con motivo y evidencia
+  CONVERGED: ai::in-review
+  NEEDS_WORK: mantiene ai::in-dev; las tareas pendientes se añaden a tasks.md
+  VALID: sin cambio de etiqueta; el bug pasa a bug-fix
+  NEEDS_REPRODUCTION: ai::blocked; faltan datos para reproducir
+  INVALID: propone ai::done; hermes-control propone el cierre y un humano lo confirma
+  APPLIED: ai::in-review
+  PARTIAL: mantiene ai::in-dev
+  NOT_APPLIED: ai::blocked con motivo y evidencia
+  VERIFIED: ai::done a través de la revisión
+  FAILED: ai::blocked con motivo y evidencia
 
 labels:
   - ai::todo
@@ -248,3 +268,17 @@ targets:
   - pi
   - cursor
   - copilot
+
+# Spec Kit: dependencia de runtime fijada por el paquete. Un proyecto solo puede
+# restringirla desde el bloque `speckit` de manifest.yaml, nunca ampliarla.
+speckit:
+  package: specify-cli
+  pin: 1.2.3
+  supported: '>=1.2.3 <1.3.0'
+  # Fecha --exclude-newer de uvx: valor provisional; se fija el día de la publicación de 0.3.0.
+  # Moverla es una decisión de release, nunca automática. Es la única copia de esta fecha.
+  excludeNewer: '2026-10-27'
+  script: sh
+  extensions:
+    assess: 1.0.1
+    bug: 1.0.1

package/manifest.json

@@ -29,103 +29,103 @@
       "id": "analyze",
       "lane": "feature",
       "role": "spec-author",
-      "skill": "speckit-analyze"
+      "speckit": "speckit.analyze"
     },
     {
       "id": "assess-decide",
       "lane": "assessment",
       "role": "spec-explorer",
-      "skill": "speckit-assess-decide"
+      "speckit": "speckit.assess.decide"
     },
     {
       "id": "assess-define",
       "lane": "assessment",
       "role": "spec-explorer",
-      "skill": "speckit-assess-define"
+      "speckit": "speckit.assess.define"
     },
     {
       "id": "assess-intake",
       "lane": "assessment",
       "role": "spec-explorer",
-      "skill": "speckit-assess-intake"
+      "speckit": "speckit.assess.intake"
     },
     {
       "id": "assess-research",
       "lane": "assessment",
       "role": "spec-explorer",
-      "skill": "speckit-assess-research"
+      "speckit": "speckit.assess.research"
     },
     {
       "id": "assess-shape",
       "lane": "assessment",
       "role": "spec-explorer",
-      "skill": "speckit-assess-shape"
+      "speckit": "speckit.assess.shape"
     },
     {
       "id": "bug-assess",
       "lane": "bug",
       "role": "reviewer-architecture",
-      "skill": "speckit-bug-assess"
+      "speckit": "speckit.bug.assess"
     },
     {
       "id": "bug-fix",
       "lane": "bug",
       "role": "implementer-backend",
-      "skill": "speckit-bug-fix"
+      "speckit": "speckit.bug.fix"
     },
     {
       "id": "bug-test",
       "lane": "bug",
       "role": "reviewer-tests",
-      "skill": "speckit-bug-test"
+      "speckit": "speckit.bug.test"
     },
     {
       "id": "checklist",
       "lane": "feature",
       "role": "spec-author",
-      "skill": "speckit-checklist"
+      "speckit": "speckit.checklist"
     },
     {
       "id": "clarify",
       "lane": "feature",
       "role": "spec-author",
-      "skill": "speckit-clarify"
+      "speckit": "speckit.clarify"
     },
     {
       "id": "constitution",
       "lane": "feature",
       "role": "spec-author",
-      "skill": "speckit-constitution"
+      "speckit": "speckit.constitution"
     },
     {
       "id": "converge",
       "lane": "feature",
       "role": "reviewer-architecture",
-      "skill": "speckit-converge"
+      "speckit": "speckit.converge"
     },
     {
       "id": "implement",
       "lane": "feature",
       "role": "implementer-frontend",
-      "skill": "speckit-implement"
+      "speckit": "speckit.implement"
     },
     {
       "id": "plan",
       "lane": "feature",
       "role": "spec-author",
-      "skill": "speckit-plan"
+      "speckit": "speckit.plan"
     },
     {
       "id": "specify",
       "lane": "feature",
       "role": "spec-author",
-      "skill": "speckit-specify"
+      "speckit": "speckit.specify"
     },
     {
       "id": "tasks",
       "lane": "feature",
       "role": "spec-author",
-      "skill": "speckit-tasks"
+      "speckit": "speckit.tasks"
     }
   ],
   "labels": [
@@ -150,8 +150,8 @@
     "rules": "custom"
   },
   "catalog": {
-    "version": "0.2.0",
-    "hash": "f30e2590a4eb078ea520873661b5f10fb3cf9171d1422438c35aafd722abbb23"
+    "version": "0.3.0",
+    "hash": "9605441252114d0ccd1e03a433420d7645618f8956c71bd16634d35e8b427f66"
   },
   "agents": [
     "cpp-build-resolver",
@@ -195,7 +195,6 @@
     "accessibility",
     "agent-eval",
     "agent-safety",
-    "analyze",
     "angular",
     "api-connector-builder",
     "api-design",
@@ -208,7 +207,6 @@
     "building-agents",
     "chatbot",
     "chrome-extension",
-    "clarify",
     "clickhouse-analytics",
     "cloudflare",
     "code-review",
@@ -272,7 +270,6 @@
     "htmx",
     "huggingface",
     "idea-refinement",
-    "implement",
     "init",
     "java",
     "knowledge-ops",
@@ -300,7 +297,6 @@
     "performance",
     "phoenix",
     "php",
-    "plan",
     "planetscale",
     "planning-with-files",
     "postgresdb",
@@ -316,39 +312,17 @@
     "render",
     "replicate",
     "research-ops",
-    "review",
     "ruby",
     "runpod",
     "rust",
     "scaling",
-    "sdd",
-    "sdd-init",
     "secure-coding",
     "security-scan",
-    "ship",
     "shopify",
     "simplify-code",
     "skill-scout",
     "solid-js",
     "source-grounded-development",
-    "specify",
-    "speckit-analyze",
-    "speckit-assess-decide",
-    "speckit-assess-define",
-    "speckit-assess-intake",
-    "speckit-assess-research",
-    "speckit-assess-shape",
-    "speckit-bug-assess",
-    "speckit-bug-fix",
-    "speckit-bug-test",
-    "speckit-checklist",
-    "speckit-clarify",
-    "speckit-constitution",
-    "speckit-converge",
-    "speckit-implement",
-    "speckit-plan",
-    "speckit-specify",
-    "speckit-tasks",
     "spreadsheet-ops",
     "spring-boot",
     "sql",
@@ -358,7 +332,6 @@
     "supabase",
     "svelte",
     "swift-ios",
-    "tasks",
     "tauri",
     "technical-writing",
     "testing-go",
@@ -376,7 +349,6 @@
     "variant-explorer",
     "vector-db",
     "vercel",
-    "verify",
     "vllm",
     "vue-nuxt",
     "webhooks",
@@ -396,7 +368,7 @@
     "labels": 7,
     "targets": 5,
     "agents": 35,
-    "skills": 191,
+    "skills": 163,
     "rules": 5
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsalazardev/ai-hub-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "author": "Daner Alejandro Salazar Colorado",
   "license": "MIT",
   "type": "module",

package/schema/engine.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "AiHubEngineV2",
   "type": "object",
-  "required": ["version", "roles", "commands", "labels", "targets"],
+  "required": ["version", "roles", "commands", "exit_effects", "labels", "targets", "speckit"],
   "additionalProperties": false,
   "properties": {
     "version": { "const": 2 },
@@ -32,7 +32,7 @@
       "maxItems": 17,
       "items": {
         "type": "object",
-        "required": ["id", "name", "lane", "artifacts", "exit", "role", "skill"],
+        "required": ["id", "name", "lane", "artifacts", "exit", "role", "speckit"],
         "additionalProperties": false,
         "properties": {
           "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
@@ -42,10 +42,14 @@
           "exit": { "type": "array", "minItems": 1, "items": { "type": "string" } },
           "role": { "type": "string", "minLength": 1 },
           "co_roles": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
-          "skill": { "type": "string", "pattern": "^speckit-" }
+          "speckit": { "type": "string", "pattern": "^speckit[.][a-z]+([.][a-z]+)?$" }
         }
       }
     },
+    "exit_effects": {
+      "type": "object",
+      "additionalProperties": { "type": "string", "minLength": 1 }
+    },
     "labels": {
       "type": "array",
       "minItems": 7,
@@ -68,6 +72,21 @@
       "minItems": 5,
       "uniqueItems": true,
       "items": { "enum": ["claude", "opencode", "pi", "cursor", "copilot"] }
+    },
+    "speckit": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "package": { "type": "string", "minLength": 1 },
+        "pin": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
+        "supported": { "type": "string", "minLength": 1 },
+        "excludeNewer": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
+        "script": { "enum": ["sh", "ps"] },
+        "extensions": {
+          "type": "object",
+          "additionalProperties": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" }
+        }
+      }
     }
   }
 }

package/schema/manifest.schema.json

@@ -147,6 +147,16 @@
       "properties": {
         "source": { "type": "string", "minLength": 1 }
       }
+    },
+    "speckit": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "managed": { "type": "boolean" },
+        "version": { "type": "string", "minLength": 1 },
+        "script": { "enum": ["sh", "ps"] },
+        "defaultTarget": { "type": "string", "minLength": 1 }
+      }
     }
   }
 }

package/skills/shared/analyze/SKILL.md

@@ -3,7 +3,8 @@ name: analyze
 description: "Use when constitution, spec, plan and tasks all exist and you want them cross-read against each other before any code is written — the ai-hub Spec-Kit pre-implementation gate. Reports coverage gaps, contradictions, duplication, ambiguity and scope drift; edits nothing. NOT the task breakdown (that is `tasks`), NOT the coding (that is `implement`), NOT the post-code test gate (that is `verify`), NOT resolving ambiguity (that is `clarify`)."
 tags: [sdd, analyze, consistency]
 recommends: [implement]
-profiles: [core, full]
+profiles: [full]
+runtime: false
 origin: ai-hub
 ---