Claude Code Workflows: orkestrér mange agenter på én gang, men det er dyrt

export const meta = {
  name: "spec-code-test-triangulation",
  description: "Three agents describe the spec, the code and the tests for the same area; a judge triangulates the descriptions and catches tests with no spec coverage as well as spec promises with no test coverage.",
  phases: [
    { title: "Describe the three sources", detail: "Three parallel agents describe, in plain text, the requirements spec, the implementation and the tests for the area." },
    { title: "Triangulate", detail: "A judge agent cross-checks the three descriptions and finds gaps between spec and tests." }
  ]
};

// Arguments: path and/or feature name for the area to triangulate.
const area = (typeof args !== "undefined" && (args.path || args.feature || args.area)) || ".";
log(`Triangulating spec, code and tests for area: ${area}`);

// Each agent describes ONLY its own source in plain prose without guessing at the others.
const describe = (source, what) =>
  `You are investigating the area "${area}" in this repo. Use Glob/Grep/Read to find ${source}. ` +
  `Describe, in clear numbered prose, ${what}; be concrete about each point, cite file paths, and do NOT guess at the other sources.`;

// Phase 1: three independent descriptions at once (barrier).
const grp = { phase: "Describe the three sources", agentType: "Explore" };
const [spec, code, tests] = await parallel([
  () => agent(describe("the requirements spec, README, docs or acceptance criteria", "which requirements and promises the spec states"), { ...grp, label: "Spec description" }),
  () => agent(describe("the source code / implementation", "which behaviour the code actually implements"), { ...grp, label: "Code description" }),
  () => agent(describe("test files and test cases", "which behaviour the tests actually verify"), { ...grp, label: "Test description" })
]);

// Phase 2: the judge cross-checks the three independent descriptions and finds the gaps.
const str = { type: "string" };
const findings = await agent(
  `You are the triangulation judge for the area "${area}".\n\n=== SPEC ===\n${spec}\n\n=== CODE ===\n${code}\n\n=== TESTS ===\n${tests}\n\n` +
  `Find EXACTLY two kinds of gaps: tests that verify behaviour the spec does not mention ("test_without_spec"), and spec promises that are never tested ("spec_without_test"). ` +
  `For each finding: cite in "sources" which source says what, set severity (high/medium/low) and justify briefly. Only include findings you are sure of after cross-checking all three.`,
  { label: "Triangulation judge", phase: "Triangulate", schema: {
    type: "object", required: ["findings"], properties: {
      findings: { type: "array", items: {
        type: "object", required: ["type", "description", "sources", "severity"], properties: {
          type: { type: "string", enum: ["test_without_spec", "spec_without_test"] },
          description: str, sources: str,
          severity: { type: "string", enum: ["high", "medium", "low"] }
        } } }
    } } }
);

const gaps = findings && Array.isArray(findings.findings) ? findings.findings : []; // the judge may return null if skipped
log(`Triangulation done: ${gaps.length} gap(s) found.`);
return gaps;

export const meta = {
  name: "dead-knowledge-audit",
  description: "Finds docs, comments, TODOs and feature flags and verifies, per claim, whether they still match the actual code. Stale claims are flagged with file and reasoning.",
  phases: [
    { title: "Collect claims", detail: "Three agents extract claims from docs, comments/TODOs and feature flags." },
    { title: "Verify claims", detail: "Each claim is traced to the actual code and judged as holds/stale." },
    { title: "Cross-check stale", detail: "An independent agent double-checks the stale findings before reporting." }
  ]
};

// Schema for a list of extracted claims
const collectionSchema = {
  type: "object",
  properties: {
    claims: {
      type: "array",
      items: {
        type: "object",
        properties: {
          source: { type: "string", description: "file:line where the claim appears" },
          type: { type: "string", enum: ["doc", "comment", "todo", "flag"] },
          claim: { type: "string", description: "what the text claims about the code" }
        },
        required: ["source", "type", "claim"]
      }
    }
  },
  required: ["claims"]
};

// Schema for the verification of a single claim
const verificationSchema = {
  type: "object",
  properties: {
    source: { type: "string" },
    claim: { type: "string" },
    status: { type: "string", enum: ["holds", "stale", "uncertain"] },
    evidenceFile: { type: "string", description: "file(s) that confirm or refute the claim" },
    why: { type: "string", description: "short justification" }
  },
  required: ["source", "claim", "status", "why"]
};

log("Phase 1: Collecting claims from docs, comments/TODOs and feature flags...");

// Three independent collectors run at once (barrier)
const sources = [
  { label: "Doc collector", focus: "README, docs/, markdown and other documentation files" },
  { label: "Comment/TODO collector", focus: "code comments and TODO/FIXME/HACK/XXX markers" },
  { label: "Feature-flag collector", focus: "feature flags, toggles, env-based conditions and their described behaviour" }
];
const collections = await parallel(sources.map((k) => () =>
  agent(
    `Search this repo with Glob/Grep/Read and extract concrete, checkable claims about the code from ${k.focus}. ` +
    `A claim is a statement that CAN have become wrong (e.g. "function X returns Y", "flag Z is active", "the module uses library W"). ` +
    `Ignore pure opinions. Give the source as file:line. Return up to 15 of the most risky claims.`,
    { label: k.label, phase: "Collect claims", agentType: "Explore", schema: collectionSchema }
  )
));

// Collect all claims into one flat list
const allClaims = collections
  .filter(Boolean)
  .flatMap((s) => s.claims || [])
  .slice(0, 60);

log(`Found ${allClaims.length} claims. Phases 2-3: Verifying and cross-checking per claim...`);

// Pipeline: verify each claim against the code, then cross-check only the stale ones
const results = await pipeline(
  allClaims,
  // Step 1: trace the claim to the actual code and determine its status
  (p) => agent(
    `Verify this claim against the ACTUAL code in the repo. Use Grep/Read/Glob to find the relevant code. ` +
    `Source: ${p.source}\nType: ${p.type}\nClaim: "${p.claim}"\n` +
    `Decide whether the claim still holds ("holds"), is stale ("stale") or cannot be determined ("uncertain"). ` +
    `Give the evidence file and a short justification.`,
    { label: `Verify: ${p.source}`, phase: "Verify claims", schema: verificationSchema }
  ),
  // Step 2: independently cross-check ONLY the claims that were marked stale
  (v) => v && v.status === "stale"
    ? agent(
        `Another agent marked this claim as STALE. Independently verify against the code whether that is correct. ` +
        `Source: ${v.source}\nClaim: "${v.claim}"\nClaimed evidence: ${v.evidenceFile || "unknown"}\nReasoning: ${v.why}\n` +
        `Return your own assessment. If you agree, keep status "stale"; otherwise change it to "holds" or "uncertain".`,
        { label: `Cross-check: ${v.source}`, phase: "Cross-check stale", schema: verificationSchema }
      )
    : v
);

// Consolidate: stale findings (confirmed by cross-check) first, then uncertain ones
const findings = results.filter(Boolean);
const stale = findings.filter((r) => r.status === "stale");
const uncertain = findings.filter((r) => r.status === "uncertain");

log(`Audit done: ${stale.length} confirmed stale, ${uncertain.length} uncertain, ${findings.length - stale.length - uncertain.length} still hold.`);

return {
  summary: { total: findings.length, stale: stale.length, uncertain: uncertain.length },
  staleFindings: stale,
  uncertainFindings: uncertain
};

export const meta = {
  name: "i18n-meaning-drift",
  description: "Compares translations across languages key by key and flags meaning drift (not missing keys or formatting).",
  phases: [
    { title: "Map locale files", detail: "Find translation files and form language pairs from base and target languages." },
    { title: "Compare meaning per language pair", detail: "One agent per language pair compares the meaning key by key." },
    { title: "Verify drift", detail: "An independent agent cross-checks each flagged drift for false positives." }
  ]
};

// Args: the base language treated as the source of truth, and optionally specific target languages (comma-separated). Empty = all found.
const baseLang = (args && args.base) ? String(args.base) : "en";
const targetLangsArg = (args && args.target) ? String(args.target).split(",").map(s => s.trim()).filter(Boolean) : null;

// Schema for the mapping: language pairs found in the repo (baseFile -> targetFile).
const mapSchema = { type: "object", required: ["pairs"], properties: { pairs: { type: "array", items: {
  type: "object", required: ["targetLang", "baseFile", "targetFile"], properties: {
    targetLang: { type: "string", description: "ISO code for the target language" },
    baseFile: { type: "string", description: "Absolute path to the base-language file" },
    targetFile: { type: "string", description: "Absolute path to the translated file" } } } } } };

// Schema for drift findings per key.
const driftSchema = { type: "object", required: ["findings"], properties: { findings: { type: "array", items: {
  type: "object", required: ["key", "baseText", "targetText", "severity", "explanation"], properties: {
    key: { type: "string" }, baseText: { type: "string" }, targetText: { type: "string" },
    severity: { type: "string", enum: ["critical", "moderate", "minor"], description: "How much the meaning has drifted" },
    explanation: { type: "string", description: "Why the meaning differs (not formatting)" } } } } } };

phase("Map locale files");
log(`Searching for locale files; base language = ${baseLang}`);
const map = await agent(
  `Find all localisation/translation files in the repo (e.g. in i18n, locales, lang, translations; .json/.yaml/.po/.properties/.arb). ` +
  `The base language is "${baseLang}". ${targetLangsArg ? `Limit target languages to: ${targetLangsArg.join(", ")}.` : "Include all target languages found that differ from the base."} ` +
  `Form language pairs (baseFile -> targetFile) where both cover the same key set. Use absolute paths.`,
  { schema: mapSchema, agentType: "Explore", phase: "Map locale files", label: "Map locales" }
);

const pairs = (map && map.pairs ? map.pairs : []).filter(p => p && p.targetFile && p.baseFile);
log(`Found ${pairs.length} language pairs. Comparing meaning.`);

// Two-step pipeline: (1) flag drift per pair, (2) let an independent agent verify each flagged drift.
const results = await pipeline(
  pairs,
  (p) => agent(
    `Compare the MEANING key by key between the base file ${p.baseFile} and the translation ${p.targetFile} (target language ${p.targetLang}). ` +
    `Read both files. Report ONLY keys where the translated text says something different from the base (wrong number/negation/concept/instruction, omitted or added meaning). ` +
    `Ignore pure formatting, punctuation, placeholder and style differences as well as missing keys. Quote both texts.`,
    { schema: driftSchema, phase: "Compare meaning per language pair", label: `Drift ${p.targetLang}` }
  ),
  async (flagged, p) => {
    const findings = (flagged && flagged.findings ? flagged.findings : []).filter(f => f && f.key);
    if (findings.length === 0) return { targetLang: p.targetLang, targetFile: p.targetFile, findings: [] };
    const v = await agent(
      `Verify these alleged meaning drifts between ${p.baseFile} (base) and ${p.targetFile} (${p.targetLang}). ` +
      `Read the files yourself. Keep ONLY findings where the meaning genuinely differs; remove false positives that are merely formatting, idiom or a correct translation. ` +
      `Claims:\n${JSON.stringify(findings, null, 2)}`,
      { schema: driftSchema, phase: "Verify drift", label: `Verify ${p.targetLang}` }
    );
    return { targetLang: p.targetLang, targetFile: p.targetFile, findings: (v && v.findings ? v.findings : []) };
  }
);

// Consolidate into one flat list of verified drifts.
const combined = results.filter(Boolean).flatMap(r => r.findings.map(f => ({ targetLang: r.targetLang, targetFile: r.targetFile, ...f })));
log(`Done: ${combined.length} verified meaning drifts across ${pairs.length} language pairs.`);
return combined;

export const meta = {
  name: "terminology-consistency",
  description: "Maps the names of key domain concepts in each layer (code, UI strings, DB schema, API) and finds where one concept has multiple names.",
  phases: [
    { title: "Map layers", detail: "One agent per layer finds concept names in code, UI, DB schema and API." },
    { title: "Find collisions", detail: "A judge collects the map and cross-checks for concepts with multiple names." }
  ]
};

// Schema for one layer's map (name, covered concept, examples) and for the judge's collision findings
const termItem = { type: "object", required: ["name", "meaning", "examples"], properties: { name: { type: "string" }, meaning: { type: "string" }, examples: { type: "array", items: { type: "string" } } } };
const layerSchema = { type: "object", required: ["layer", "terms"], properties: { layer: { type: "string" }, terms: { type: "array", items: termItem } } };
const collisionItem = { type: "object", required: ["concept", "names", "severity", "recommendation"], properties: { concept: { type: "string" }, names: { type: "array", items: { type: "string" } }, severity: { type: "string", enum: ["high", "medium", "low"] }, recommendation: { type: "string" } } };
const judgeSchema = { type: "object", required: ["collisions"], properties: { collisions: { type: "array", items: collisionItem } } };

// The four layers, each mapped by an independent agent
const layers = [
  { name: "code", hint: "class, function, variable and type names in the source code" },
  { name: "UI strings", hint: "labels, button text, headings and translations in frontend/i18n files" },
  { name: "DB schema", hint: "table and column names in migrations, ORM models and SQL" },
  { name: "API/endpoints", hint: "route paths, request/response fields and DTOs in the API layer" }
];

log("Mapping terminology across " + layers.length + " layers in parallel ...");
const map = (await parallel(layers.map((l) => () => agent(
  "You are mapping TERMINOLOGY in the '" + l.name + "' layer (" + l.hint + ") of this repo. Use Glob/Grep/Read to find the names of the key DOMAIN CONCEPTS (entities, resources, statuses, roles); ignore pure technical plumbing. For each concept: give the concrete name, which concept it covers, and 1-3 concrete examples (file:line). Only report names you have actually seen.",
  { schema: layerSchema, label: "Map: " + l.name, phase: "Map layers", agentType: "Explore" })))).filter(Boolean);

log("Judge cross-checks the layers and finds naming collisions ...");
// The judge verifies it really is the same concept before reporting (quality check)
const judgment = await agent(
  "You are the TERMINOLOGY JUDGE. Below are concept maps from four layers as JSON:\n\n" + JSON.stringify(map, null, 2) + "\n\nFind COLLISIONS: one and the same domain concept that appears under DIFFERENT names across layers (e.g. 'customer' in UI, 'client' in code, 'account' in DB). Verify it really is the same concept before reporting; ignore plain synonyms that cause no confusion. State the severity and recommend one canonical name per collision.",
  { schema: judgeSchema, label: "Judge: collisions", phase: "Find collisions" });

const order = { high: 0, medium: 1, low: 2 }; // sort by severity
const findings = (judgment?.collisions ?? []).sort((a, b) => (order[a.severity] ?? 3) - (order[b.severity] ?? 3));
log("Done. Found " + findings.length + " terminology collision(s).");
return { collisions: findings, layersMapped: map.map((k) => k.layer) };

export const meta = {
  name: "semantic-refactor-regression",
  description: "Assertion-free regression test: describes each affected module's behaviour before and after a refactor and lets a judge flag unintended changes.",
  phases: [
    { title: "Describe behaviour before and after", detail: "Two agents describe the old and new module's behaviour in plain text." },
    { title: "Judge semantic deviations", detail: "A judge compares them and flags unintended behaviour changes." }
  ]
};

// The list of affected files/modules is taken from args (comma- or space-separated).
const files = (typeof args === "string" ? args : (args?.files || args?.join?.(" ") || ""))
  .split(/[\s,]+/).map(s => s.trim()).filter(Boolean);
log(`Semantic regression test of ${files.length} affected module(s).`);

// Schema for behaviour descriptions.
const behaviorSchema = { type: "object", required: ["module", "behavior"], properties: {
  module: { type: "string" },
  behavior: { type: "array", items: { type: "string" }, description: "Observable behaviour points in plain text (in/output, side effects, errors)." }
}};

// Schema for the judge's verdict.
const verdictSchema = { type: "object", required: ["module", "deviations"], properties: {
  module: { type: "string" },
  deviations: { type: "array", items: { type: "object", required: ["description", "severity", "unintended"], properties: {
    description: { type: "string" },
    severity: { type: "string", enum: ["critical", "moderate", "cosmetic"] },
    unintended: { type: "boolean", description: "True if the change appears unintended (a regression)." }
  }}}
}};

// Pipeline per module: the first step describes both BEFORE and AFTER in parallel, the second step judges.
const results = await pipeline(files,
  (_, file) => parallel([
    () => agent(`Describe, in plain text, the OBSERVABLE behaviour of '${file}' BEFORE the change. Use Bash to run 'git show HEAD~1:${file}' (or the most recent version present in history) and read the contents. Cover input/output, side effects, error handling and edge cases. No assertions, only a behaviour description.`,
      { label: `before: ${file}`, phase: "Describe behaviour before and after", agentType: "Explore", schema: behaviorSchema }),
    () => agent(`Describe, in plain text, the OBSERVABLE behaviour of '${file}' AFTER the change. Read the current file in the working tree with Read. Cover input/output, side effects, error handling and edge cases. No assertions, only a behaviour description.`,
      { label: `after: ${file}`, phase: "Describe behaviour before and after", agentType: "Explore", schema: behaviorSchema })
  ]),
  ([before, after], file) => {
    // Cross-check: an independent judge compares the two descriptions.
    if (!before || !after) return null;
    return agent(`You are the semantic judge for the module '${file}'. Compare BEFORE and AFTER and flag only behaviour that has changed unintentionally (a regression). A pure refactor should preserve behaviour. Verify doubtful cases against the actual code with Read/Grep before reporting.\n\nBEFORE:\n${JSON.stringify(before)}\n\nAFTER:\n${JSON.stringify(after)}`,
      { label: `verdict: ${file}`, phase: "Judge semantic deviations", schema: verdictSchema });
  }
);

// Collect the flagged regressions into one consolidated list.
const verdicts = results.filter(Boolean);
const regressions = verdicts.flatMap(d => (d.deviations || [])
  .filter(a => a.unintended).map(a => ({ module: d.module, ...a })));
log(`Done. ${regressions.length} possible regression(s) found across ${verdicts.length} module(s).`);
return { modulesReviewed: verdicts.length, regressions, allVerdicts: verdicts };

export const meta = {
  name: "pr-narrative-vs-diff",
  description: "Compares the PR/commit narrative with the actual diff and catches discrepancies, especially hidden behaviour changes described as a pure refactor.",
  phases: [
    { title: "Collect narrative and diff", detail: "Extract claims from the description and facts from the actual diff in parallel." },
    { title: "Judge discrepancies", detail: "Cross-check narrative against diff and find deviations, especially hidden behaviour changes." }
  ]
};
// The PR/diff reference is taken as an argument; falls back to the most recent commit range.
const ref = (typeof args !== "undefined" && args && args.ref) ? args.ref : "HEAD~1..HEAD";
log(`Analysing PR/diff reference: ${ref}`);
// Schema for the claimed narrative and for the actual diff.
const narrativeSchema = { type: "object", required: ["claims"], properties: { claims: { type: "array", items: { type: "object", required: ["claim", "type"], properties: { claim: { type: "string" }, type: { type: "string", enum: ["refactor", "bugfix", "new-feature", "behavior-change", "other"] } } } } } };
const diffSchema = { type: "object", required: ["changes"], properties: { changes: { type: "array", items: { type: "object", required: ["description", "affectsBehavior"], properties: { file: { type: "string" }, description: { type: "string" }, affectsBehavior: { type: "boolean" } } } } } };
// Two independent readers run in parallel (barrier): one sees only the narrative, one sees only the diff.
const [narrative, diff] = await parallel([
  () => agent(`Read ONLY the PR/commit message for reference '${ref}'. Use Bash: 'git log ${ref} --format=%B' and optionally 'gh pr view'. Extract each claimed change and classify its type. Do NOT inspect the code.`, { label: "Narrative reader", phase: "Collect narrative and diff", agentType: "Explore", schema: narrativeSchema }),
  () => agent(`Read ONLY the actual diff for reference '${ref}' via Bash 'git diff ${ref}'. Describe objectively what each change does, and mark whether it changes runtime behaviour (not just structure). Do NOT read the description.`, { label: "Diff reader", phase: "Collect narrative and diff", agentType: "Explore", schema: diffSchema })
]);
// The judge cross-checks the two independent descriptions and finds dangerous discrepancies.
const judgeSchema = { type: "object", required: ["findings", "verdictSummary"], properties: { findings: { type: "array", items: { type: "object", required: ["severity", "description"], properties: { severity: { type: "string", enum: ["critical", "high", "medium", "low"] }, description: { type: "string" }, category: { type: "string", enum: ["hidden-behavior-change", "unmentioned-change", "claim-without-coverage", "ok"] } } } }, verdictSummary: { type: "string" } } };
const verdict = await agent(`You are the judge. Compare the CLAIMED narrative with the ACTUAL diff.\nNARRATIVE: ${JSON.stringify(narrative)}\nACTUAL DIFF: ${JSON.stringify(diff)}\nFind discrepancies. Prioritise the dangerous pattern: the narrative says "refactor only", but the diff actually changes behaviour (mark as critical/high). Also find unmentioned changes and claims without coverage in the diff.`, { label: "Judge", phase: "Judge discrepancies", schema: judgeSchema });
// Consolidate and report the combined findings to the user.
log(`Verdict (${(verdict.findings || []).length} findings): ${verdict.verdictSummary}`);
for (const f of (verdict.findings || [])) log(`- [${f.severity}] ${f.description}`);