jarvis-ai-framework 2.0.0 → 2.1.1

package/bin/commands/tokens.js

@@ -0,0 +1,93 @@
+import { buildReport } from "../lib/core/token-report.js";
+import { resolveEnvPath, loadEnv } from "../lib/env-loader.js";
+import { getFrameworkRoot } from "../lib/utils/paths.js";
+import {
+  showBanner,
+  RED,
+  GREEN,
+  BLUE,
+  YELLOW,
+  CYAN,
+  DIM,
+  NC,
+} from "../lib/utils/ui.js";
+import { logger } from "../lib/utils/logger.js";
+
+const AXES = ["HUB", "POSITION", "AREA", "SQUAD"];
+
+/** Perfil: as flags (`--hub` etc.) mandam; o que faltar vem do ENV.md. */
+function resolveProfile(flags) {
+  const profile = {};
+  for (const axis of AXES) {
+    const value = flags[axis.toLowerCase()];
+    if (typeof value === "string") profile[axis] = value;
+  }
+
+  let rtkEnabled = flags.rtk === true || flags.rtk === "true";
+  // O ENV.md só entra quando falta algum eixo; com os 4 eixos nas flags, o RTK vem só da flag.
+  if (AXES.some((axis) => !profile[axis])) {
+    try {
+      const { path } = resolveEnvPath(process.cwd(), flags);
+      const env = loadEnv(process.cwd(), path);
+      for (const axis of AXES) {
+        if (!profile[axis] && env[axis]) profile[axis] = env[axis];
+      }
+      if (flags.rtk === undefined) rtkEnabled = env.RTK_ENABLED === "true";
+    } catch {
+      // sem ENV.md: valem só as flags
+    }
+  }
+
+  const missing = AXES.filter((axis) => !profile[axis]);
+  return { profile, rtkEnabled, missing };
+}
+
+const kb = (bytes) => (bytes / 1000).toFixed(1);
+
+export async function tokens(flags) {
+  const { profile, rtkEnabled, missing } = resolveProfile(flags);
+
+  if (missing.length > 0) {
+    logger.error(`${RED}❌ Perfil incompleto: faltam ${missing.join(", ")}${NC}`);
+    logger.info(
+      `${YELLOW}Uso: jarvis tokens [--hub X --position Y --area Z --squad W] [--rtk] [--json]${NC}`,
+    );
+    logger.info(`${DIM}Sem flags, o perfil vem do ENV.md do workspace (use --ide <ide> se houver mais de um).${NC}\n`);
+    process.exit(1);
+  }
+
+  const report = buildReport(getFrameworkRoot(), profile, { rtkEnabled });
+
+  if (flags.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return;
+  }
+
+  showBanner();
+  logger.info(`${CYAN}📏 Custo estimado no início da sessão${NC}`);
+  logger.info(
+    `${DIM}Perfil: HUB=${profile.HUB} | POSITION=${profile.POSITION} | AREA=${profile.AREA} | SQUAD=${profile.SQUAD}` +
+      ` | RTK=${rtkEnabled ? "ligado" : "desligado"}${NC}`,
+  );
+  logger.info(`${DIM}${report.estimate}${NC}`);
+  logger.info("");
+  logger.info(`${DIM}${"Tipo".padEnd(26)}${"Arquivos".padStart(9)}${"KB".padStart(10)}${"Tokens (≈)".padStart(13)}${NC}`);
+  logger.info(`${DIM}${"─".repeat(58)}${NC}`);
+
+  for (const c of report.categories) {
+    logger.info(
+      `${GREEN}${c.label.padEnd(26)}${NC}${String(c.files.length).padStart(9)}` +
+        `${kb(c.bytes).padStart(10)}${String(c.tokens).padStart(13)}`,
+    );
+    if (c.files[0]) {
+      logger.info(`  ${DIM}maior: ${c.files[0].path} (${kb(c.files[0].bytes)} KB) — ${c.note}${NC}`);
+    }
+  }
+
+  logger.info(`${DIM}${"─".repeat(58)}${NC}`);
+  logger.info(
+    `${BLUE}${"Total".padEnd(26)}${NC}${"".padStart(9)}` +
+      `${kb(report.total.bytes).padStart(10)}${String(report.total.tokens).padStart(13)}`,
+  );
+  logger.info("");
+}

package/bin/jarvis.js

@@ -12,6 +12,8 @@ import { docsSync } from "./commands/docs-sync.js";
 import { docsPublish } from "./commands/docs-publish.js"
 import { qaSignoff } from "./commands/qa-signoff.js";
 import { installRtk } from "./commands/install-rtk.js";
+import { tokens } from "./commands/tokens.js";
+import { map } from "./commands/map.js";
 import { formatIDEsList } from "./lib/config/ide-config.js";
 import { showBanner, BLUE, GREEN, YELLOW, DIM, NC } from "./lib/utils/ui.js";
 import { logger } from "./lib/utils/logger.js";
@@ -63,6 +65,12 @@ function help() {
   logger.info(
     `  ${GREEN}jarvis install-rtk${NC}                      Instalar RTK (token killer — economia 60-90%)`,
   );
+  logger.info(
+    `  ${GREEN}jarvis tokens${NC} [--hub <h> --position <p> --area <a> --squad <s>] [--rtk] [--json]   Estimar o que carrega no início da sessão (perfil do ENV.md se sem flags)`,
+  );
+  logger.info(
+    `  ${GREEN}jarvis map${NC} <nome> [--depth N] [--reverse]   Mapa do que um workflow, skill ou agente chama (ou, com --reverse, quem o chama)`,
+  );
   logger.info(
     `  ${GREEN}jarvis qa-signoff${NC} [--branch <branch>] [--max-age <horas>]   Verificar sign-off QA (usado pelo CI)`,
   );
@@ -142,6 +150,8 @@ const commands = {
   },
   "install-rtk": () => installRtk(flags),
   "qa-signoff": () => qaSignoff(flags),
+  tokens: () => tokens(flags),
+  map: () => map(flags),
   "--version": () => logger.info(getVersion()),
   "-v": () => logger.info(getVersion()),
   "--help": () => help(),

package/bin/lib/config/constants.js

@@ -19,6 +19,7 @@ export const SYNC_DIRS = Object.freeze([
   "workflows",
   "templates",
   "rules",
+  "rules-on-demand",
   "scripts",
 ]);
 
@@ -67,6 +68,16 @@ export const OBSOLETE_PATHS = Object.freeze([
   "skills/report-issue",
   "skills/docs-central",
   "skills/docs-index",
+  // eng.downstream-flow-rules (removida): processo de board de um time, acoplado a Jira
+  "rules/engineering/eng.downstream-flow-rules.md",
+  // rules de uma etapa só: saíram de rules/ (carregada no início) para rules-on-demand/ (lida pelo workflow)
+  "rules/engineering/eng.start-rules.md",
+  "rules/engineering/eng.plan-rules.md",
+  "rules/engineering/eng.work-rules.md",
+  "rules/engineering/eng.pr-rules.md",
+  "rules/engineering/eng.pre-pr-rules.md",
+  "rules/engineering/eng.tech-spec-rules.md",
+  "rules/engineering/eng.breakdown-subtasks-rules.md",
 ]);
 
 /**

package/bin/lib/core/profile-filter.js

@@ -0,0 +1,113 @@
+/**
+ * @fileoverview Filtro de rules por perfil (bloco "Applies to").
+ *
+ * Espelha em JS a lógica do Passo 8 ("Profile-Aware Rules Sync") do skill
+ * `skills/jarvis-init/SKILL.md`, que é executada pela IA. As duas fontes da
+ * regra são esse passo e a seção "Profile-Aware Rules Loading" de
+ * `rules/AGENTS.md`: ao mudar uma, mude as três.
+ *
+ * Regras:
+ * - Os quatro eixos (HUB, POSITION, AREA, SQUAD) são combinados com AND.
+ * - `all` casa qualquer valor; listas são separadas por vírgula.
+ * - FULLCYCLE (HUB) satisfaz qualquer HUB.
+ * - GENERALIST (POSITION) satisfaz qualquer POSITION e qualquer AREA.
+ * - Arquivo sem bloco "Applies to" é universal.
+ * - `rules/AGENTS.md` nunca é filtrado.
+ * - `rtk-rules.md` só entra com RTK habilitado (opt-in).
+ * @module core/profile-filter
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+const APPLIES_TO_RE =
+  /> \*\*Applies to:\*\* HUB: ([^|]+)\| POSITION: ([^|]+)\| AREA: ([^|]+)\| SQUAD: (.+)/;
+
+/**
+ * @typedef {Object} AppliesTo
+ * @property {string} HUB
+ * @property {string} POSITION
+ * @property {string} AREA
+ * @property {string} SQUAD
+ */
+
+/**
+ * @typedef {Object} Profile
+ * @property {string} HUB
+ * @property {string} POSITION
+ * @property {string} AREA
+ * @property {string} SQUAD
+ */
+
+/**
+ * Lê o primeiro bloco "Applies to" do conteúdo.
+ * @param {string} content
+ * @returns {AppliesTo | null} `null` quando não há bloco (arquivo universal)
+ */
+export function parseAppliesTo(content) {
+  const match = content.match(APPLIES_TO_RE);
+  if (!match) return null;
+  return {
+    HUB: match[1].trim(),
+    POSITION: match[2].trim(),
+    AREA: match[3].trim(),
+    SQUAD: match[4].trim(),
+  };
+}
+
+function axisMatches(list, value) {
+  if (list.toLowerCase() === "all") return true;
+  return list.split(",").map((s) => s.trim()).includes(value);
+}
+
+/**
+ * Decide se um bloco "Applies to" casa com o perfil.
+ * @param {AppliesTo | null} appliesTo
+ * @param {Profile} profile
+ * @returns {boolean}
+ */
+export function matchesProfile(appliesTo, profile) {
+  if (!appliesTo) return true;
+  const hub = profile.HUB === "FULLCYCLE" || axisMatches(appliesTo.HUB, profile.HUB);
+  const generalist = profile.POSITION === "GENERALIST";
+  const position = generalist || axisMatches(appliesTo.POSITION, profile.POSITION);
+  const area = generalist || axisMatches(appliesTo.AREA, profile.AREA);
+  const squad = axisMatches(appliesTo.SQUAD, profile.SQUAD);
+  return hub && position && area && squad;
+}
+
+function walkMarkdown(dir) {
+  return readdirSync(dir).flatMap((name) => {
+    const p = join(dir, name);
+    if (statSync(p).isDirectory()) return walkMarkdown(p);
+    return p.endsWith(".md") ? [p] : [];
+  });
+}
+
+/**
+ * Lista as rules que o perfil recebe, com o tamanho em bytes.
+ * @param {string} rulesDir - Pasta `rules/` do framework
+ * @param {Profile} profile
+ * @param {{ rtkEnabled?: boolean }} [opts]
+ * @returns {Array<{ path: string, bytes: number }>} Ordenado do maior para o menor;
+ *   `path` é relativo a `rulesDir`, com `/` como separador
+ */
+export function listRulesForProfile(rulesDir, profile, opts = {}) {
+  if (!existsSync(rulesDir)) return [];
+  const result = [];
+  for (const file of walkMarkdown(rulesDir)) {
+    const rel = relative(rulesDir, file).split(sep).join("/");
+    const content = readFileSync(file, "utf-8");
+    const bytes = Buffer.byteLength(content, "utf-8");
+
+    if (rel === "AGENTS.md") {
+      result.push({ path: rel, bytes });
+      continue;
+    }
+    if (rel.endsWith("rtk-rules.md") && !opts.rtkEnabled) continue;
+    if (matchesProfile(parseAppliesTo(content), profile)) {
+      result.push({ path: rel, bytes });
+    }
+  }
+  return result.sort((a, b) => b.bytes - a.bytes || a.path.localeCompare(b.path));
+}

package/bin/lib/core/scanner.js

@@ -26,10 +26,10 @@ function parseFrontmatter(content) {
 function extractDeps(content) {
   const deps = { rules: [], templates: [], skills: [], agents: [] };
 
-  const ruleFile = content.match(/rules_file:\s*"?\$IDE\/rules\/(.+?)\.md"?/);
+  const ruleFile = content.match(/rules_file:\s*"?\$IDE\/rules(?:-on-demand)?\/(.+?)\.md"?/);
   if (ruleFile) deps.rules.push(ruleFile[1]);
 
-  for (const m of content.matchAll(/rules\/([\w./-]+)\.md/g)) {
+  for (const m of content.matchAll(/rules(?:-on-demand)?\/([\w./-]+)\.md/g)) {
     if (!deps.rules.includes(m[1])) deps.rules.push(m[1]);
   }
 

package/bin/lib/core/token-report.js

@@ -0,0 +1,90 @@
+/**
+ * @fileoverview Estimativa do que o framework carrega no início de uma sessão.
+ *
+ * Mede, por tipo, os arquivos que a IDE lê no início para um perfil (HUB,
+ * POSITION, AREA, SQUAD). Tokens são uma **estimativa** (bytes ÷ 4): serve
+ * para comparar antes e depois, não para cobrar custo.
+ * @module core/token-report
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { listRulesForProfile } from "./profile-filter.js";
+
+/** Bytes por token usados na estimativa. */
+export const BYTES_PER_TOKEN = 4;
+
+/**
+ * @param {number} bytes
+ * @returns {number} tokens estimados (bytes ÷ 4, arredondado)
+ */
+export function estimateTokens(bytes) {
+  return Math.round(bytes / BYTES_PER_TOKEN);
+}
+
+/**
+ * Tamanho em bytes do bloco de frontmatter (do primeiro `---` ao segundo `---`).
+ * @param {string} content
+ * @returns {number} 0 quando não há frontmatter
+ */
+export function frontmatterBytes(content) {
+  const match = content.match(/^---\s*\n[\s\S]*?\n---/);
+  return match ? Buffer.byteLength(match[0], "utf-8") : 0;
+}
+
+function fileBytes(path) {
+  return Buffer.byteLength(readFileSync(path, "utf-8"), "utf-8");
+}
+
+function category(id, label, files, note = "") {
+  const sorted = [...files].sort((a, b) => b.bytes - a.bytes || a.path.localeCompare(b.path));
+  const bytes = sorted.reduce((sum, f) => sum + f.bytes, 0);
+  return { id, label, note, files: sorted, bytes, tokens: estimateTokens(bytes) };
+}
+
+/**
+ * @param {string} root - Raiz do framework (`rules/`, `skills/`, `workflows/`, `AGENTS.md`)
+ * @param {import("./profile-filter.js").Profile} profile
+ * @param {{ rtkEnabled?: boolean }} [opts]
+ */
+export function buildReport(root, profile, opts = {}) {
+  const rtkEnabled = Boolean(opts.rtkEnabled);
+
+  const rules = listRulesForProfile(join(root, "rules"), profile, { rtkEnabled });
+
+  const agentsMd = existsSync(join(root, "AGENTS.md"))
+    ? [{ path: "AGENTS.md", bytes: fileBytes(join(root, "AGENTS.md")) }]
+    : [];
+
+  const skillsDir = join(root, "skills");
+  const skills = [];
+  if (existsSync(skillsDir)) {
+    for (const name of readdirSync(skillsDir)) {
+      const skillMd = join(skillsDir, name, "SKILL.md");
+      if (!statSync(join(skillsDir, name)).isDirectory() || !existsSync(skillMd)) continue;
+      const bytes = frontmatterBytes(readFileSync(skillMd, "utf-8"));
+      if (bytes > 0) skills.push({ path: `skills/${name}/SKILL.md`, bytes });
+    }
+  }
+
+  const warmupPath = join(root, "workflows", "warm-up.md");
+  const warmup = existsSync(warmupPath)
+    ? [{ path: "workflows/warm-up.md", bytes: fileBytes(warmupPath) }]
+    : [];
+
+  const categories = [
+    category("rules", "Rules", rules, "carregadas no início pelo Claude Code"),
+    category("agents-md", "AGENTS.md", agentsMd, "instrução de projeto"),
+    category("skills-frontmatter", "Frontmatter dos skills", skills, "sempre visível; o corpo só ao invocar"),
+    category("warmup", "warm-up", warmup, "só se executado no início da sessão"),
+  ];
+
+  const bytes = categories.reduce((sum, c) => sum + c.bytes, 0);
+  return {
+    profile: { HUB: profile.HUB, POSITION: profile.POSITION, AREA: profile.AREA, SQUAD: profile.SQUAD },
+    rtkEnabled,
+    estimate: `tokens = bytes ÷ ${BYTES_PER_TOKEN} (estimativa)`,
+    categories,
+    total: { bytes, tokens: estimateTokens(bytes) },
+  };
+}

package/bin/lib/flow-map/index.js

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview Índice nome → artefato (workflows, skills e agentes ativos).
+ *
+ * Montado a cada execução, sem arquivo persistido. O nome identifica o item:
+ * - workflow: arquivo `workflows/**\/{nome}.md` (sem README e AGENTS)
+ * - skill: pasta `skills/{nome}/SKILL.md`
+ * - agente: arquivo `agents/**\/{nome}.md` (fora de `archive/`, sem README e AGENTS)
+ * @module flow-map/index
+ */
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { basename, join, relative, sep } from "node:path";
+
+const IGNORED_FILES = new Set(["README.md", "AGENTS.md"]);
+
+function walkMarkdown(dir, skipDirs = []) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).flatMap((name) => {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) {
+      return skipDirs.includes(name) ? [] : walkMarkdown(path, skipDirs);
+    }
+    return name.endsWith(".md") && !IGNORED_FILES.has(name) ? [path] : [];
+  });
+}
+
+/**
+ * @typedef {Object} FlowItem
+ * @property {string} name
+ * @property {"workflow" | "skill" | "agent"} type
+ * @property {string} path - Caminho relativo à raiz do framework, com `/`
+ */
+
+/**
+ * @param {string} root - Raiz do framework (`workflows/`, `skills/`, `agents/`)
+ * @returns {{ items: Map<string, FlowItem>, duplicates: string[] }}
+ */
+export function buildIndex(root) {
+  const items = new Map();
+  const duplicates = [];
+  const rel = (path) => relative(root, path).split(sep).join("/");
+
+  function add(item) {
+    if (items.has(item.name)) duplicates.push(item.name);
+    else items.set(item.name, item);
+  }
+
+  for (const file of walkMarkdown(join(root, "workflows"))) {
+    add({ name: basename(file, ".md"), type: "workflow", path: rel(file) });
+  }
+
+  const skillsDir = join(root, "skills");
+  if (existsSync(skillsDir)) {
+    for (const dir of readdirSync(skillsDir)) {
+      const skillMd = join(skillsDir, dir, "SKILL.md");
+      if (existsSync(skillMd)) add({ name: dir, type: "skill", path: rel(skillMd) });
+    }
+  }
+
+  for (const file of walkMarkdown(join(root, "agents"), ["archive"])) {
+    add({ name: basename(file, ".md"), type: "agent", path: rel(file) });
+  }
+
+  return { items, duplicates };
+}

package/bin/lib/flow-map/parse.js

@@ -0,0 +1,217 @@
+/**
+ * @fileoverview Leitor das declarações padronizadas de chamadas.
+ *
+ * Só lê a estrutura (sem interpretar prosa, sem IA):
+ * - workflows e skills: tabela `| Passo | Skill | Condição |` sob
+ *   `### Skills invocados durante o workflow` (ou `... durante a execução do skill`);
+ * - agentes: `## Skills Disponíveis` (`### {skill}`) e `## Workflows e Agentes Relacionados`.
+ * @module flow-map/parse
+ */
+
+export const WORKFLOW_TITLE = "Skills invocados durante o workflow";
+export const SKILL_TITLE = "Skills invocados durante a execução do skill";
+
+/**
+ * @typedef {Object} Target
+ * @property {"internal" | "agent" | "cli" | "mcp" | "external" | "unresolved"} kind
+ * @property {string} name
+ */
+
+/**
+ * @typedef {Object} Row
+ * @property {string | null} passo
+ * @property {string} condicao
+ * @property {Target[]} targets
+ * @property {string | null} via - Texto de `(via ...)`, quando houver
+ * @property {"quebrada" | "a confirmar" | null} marker
+ * @property {boolean} selfContained - Linha "Nenhuma — … autocontido"
+ * @property {boolean} available - Skill que o agente pode usar (não é chamada fixa)
+ */
+
+/** Troca o conteúdo dos blocos de código por linhas em branco (títulos dentro deles não valem). */
+function stripFences(text) {
+  let fence = false;
+  return text
+    .split("\n")
+    .map((line) => {
+      if (line.trimStart().startsWith("```")) {
+        fence = !fence;
+        return "";
+      }
+      return fence ? "" : line;
+    })
+    .join("\n");
+}
+
+/** Divide uma linha de tabela em células, ignorando `|` dentro de crases. */
+export function splitCells(line) {
+  const cells = [];
+  let current = "";
+  let inCode = false;
+  for (const ch of line.trim()) {
+    if (ch === "`") inCode = !inCode;
+    if (ch === "|" && !inCode) {
+      cells.push(current.trim());
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  cells.push(current.trim());
+  if (cells[0] === "") cells.shift();
+  if (cells[cells.length - 1] === "") cells.pop();
+  return cells;
+}
+
+/**
+ * Classifica a célula `Skill` de uma linha da tabela.
+ * @param {string} cell
+ * @returns {{ targets: Target[], via: string | null, marker: Row["marker"], selfContained: boolean }}
+ */
+export function classifyCell(cell) {
+  const text = cell.trim();
+  if (/^nenhuma/i.test(text)) return { targets: [], via: null, marker: null, selfContained: true };
+
+  const marker = /refer[eê]ncia quebrada/i.test(text)
+    ? "quebrada"
+    : /refer[eê]ncia a confirmar/i.test(text)
+      ? "a confirmar"
+      : null;
+
+  let via = null;
+  let analyzed = text;
+  const viaMatch = text.match(/\(via\s+([^)]*)\)/);
+  if (viaMatch) {
+    via = viaMatch[1].replace(/`/g, "").trim();
+    analyzed = text.replace(viaMatch[0], "");
+  }
+
+  const spans = [...analyzed.matchAll(/`([^`]+)`(\s*\(agente\))?/g)];
+  const targets = [];
+  const external = /skill externo/i.test(analyzed); // skill de fora do framework: não está no índice
+
+  if (/\(MCP/.test(analyzed) && spans[0]) {
+    targets.push({ kind: "mcp", name: spans[0][1].trim() });
+    return { targets, via, marker, selfContained: false };
+  }
+
+  for (const span of spans) {
+    const token = span[1].trim();
+    if (span[2]) targets.push({ kind: "agent", name: token });
+    else if (token.startsWith("/")) {
+      targets.push({ kind: external ? "external" : "internal", name: token.slice(1).split(/\s+/)[0] });
+    }
+    else if (/^(jarvis|node)\s/.test(token)) targets.push({ kind: "cli", name: token });
+    else if (token.startsWith("mcp__")) targets.push({ kind: "mcp", name: token });
+    // Read, Grep, Glob e texto livre não são chamadas a artefatos: ignorados
+  }
+
+  if (marker && targets.length === 0 && spans[0]) {
+    targets.push({ kind: "unresolved", name: spans[0][1].trim() });
+  }
+  return { targets, via, marker, selfContained: false };
+}
+
+function parseTable(text, title) {
+  const lines = stripFences(text).split("\n");
+  const start = lines.findIndex((l) => l.trim() === `### ${title}`);
+  if (start === -1) return null;
+  const rows = [];
+  let i = start + 1;
+  while (i < lines.length && !lines[i].startsWith("|")) {
+    if (/^#{1,3} /.test(lines[i])) return rows;
+    i++;
+  }
+  i += 2; // cabeçalho e separador
+  for (; i < lines.length && lines[i].startsWith("|"); i++) {
+    const [passo = "", skill = "", condicao = ""] = splitCells(lines[i]);
+    const c = classifyCell(skill);
+    rows.push({
+      passo,
+      condicao,
+      targets: c.targets,
+      via: c.via,
+      marker: c.marker,
+      selfContained: c.selfContained,
+      available: false,
+    });
+  }
+  return rows;
+}
+
+function section(text, title) {
+  const m = text.match(new RegExp(`^## ${title}\\s*\\n([\\s\\S]*?)(?=\\n## |\\n---\\s*\\n|(?![\\s\\S]))`, "m"));
+  return m ? m[1] : null;
+}
+
+function parseAgent(text) {
+  const clean = stripFences(text);
+  const rows = [];
+
+  const skills = section(clean, "Skills Disponíveis");
+  if (skills !== null) {
+    for (const block of skills.split(/^### /m).slice(1)) {
+      const [heading, ...rest] = block.split("\n");
+      // Um bloco pode citar mais de uma skill: uma linha por skill (nome tirado do caminho do SKILL.md).
+      const names = [...new Set([...block.matchAll(/skills\/([A-Za-z0-9._-]+)\/SKILL\.md/g)].map((m) => m[1]))];
+      if (names.length === 0) {
+        const token = heading.trim().split(/[\s(]/)[0];
+        if (/[-.]/.test(token)) names.push(token);
+      }
+      const context = rest.map((l) => l.trim()).find((l) => l && !l.startsWith("- ")) ?? "";
+      for (const name of names) {
+        rows.push({
+          passo: null,
+          condicao: context.replace(/:$/, ""),
+          targets: [{ kind: "internal", name }],
+          via: null,
+          marker: null,
+          selfContained: false,
+          available: true,
+        });
+      }
+    }
+  }
+
+  const related = section(clean, "Workflows e Agentes Relacionados");
+  if (related !== null) {
+    for (const line of related.split("\n")) {
+      if (!/^- /.test(line) || /^- Arquivo:/.test(line)) continue;
+      const bold = line.match(/\*\*([^*]+)\*\*/);
+      const code = line.match(/`([^`]+)`/);
+      let name = bold ? bold[1] : code ? code[1] : null;
+      if (!name) continue;
+      if (name.includes("/")) {
+        if (!name.endsWith(".md")) continue;
+        name = name.split("/").pop().replace(/\.md$/, "");
+      }
+      const condicao = line.includes(":") ? line.slice(line.indexOf(":") + 1).trim() : "";
+      rows.push({
+        passo: null,
+        condicao,
+        targets: [{ kind: "internal", name }],
+        via: null,
+        marker: null,
+        selfContained: false,
+        available: false,
+      });
+    }
+  }
+
+  const declared = skills !== null || related !== null;
+  return { declared, selfContained: declared && rows.length === 0, rows };
+}
+
+/**
+ * Lê as chamadas declaradas por um artefato.
+ * @param {"workflow" | "skill" | "agent"} type
+ * @param {string} text
+ * @returns {{ declared: boolean, selfContained: boolean, rows: Row[] }}
+ */
+export function parseDeclaration(type, text) {
+  if (type === "agent") return parseAgent(text);
+  const rows = parseTable(text, type === "workflow" ? WORKFLOW_TITLE : SKILL_TITLE);
+  if (rows === null) return { declared: false, selfContained: false, rows: [] };
+  const hasTargets = rows.some((r) => r.targets.length > 0);
+  return { declared: true, selfContained: rows.some((r) => r.selfContained) && !hasTargets, rows };
+}