Skip to content

notque/vexjoy-agent / skills/process/workflow

workflow

Verified

Structured work: multi-phase tasks, feature builds, planning, objective loops, hill climbing.

FileKindSize
SKILL.mdskill md13.2 KB
references/adr-template.mdmarkdown9.4 KB
references/agent-upgrade.mdmarkdown12.5 KB
references/article-evaluation-pipeline.mdmarkdown8.9 KB
references/article-evaluation-pipeline/references/report-template.mdmarkdown2.5 KB
references/article-evaluation-pipeline/references/wabi-sabi-classification.mdmarkdown2.4 KB
references/auto-pipeline.mdmarkdown12.5 KB
references/auto-pipeline/references/pipeline-catalog.jsonconfig15.0 KB
references/auto-pipeline/references/pipeline-catalog.mdmarkdown4.3 KB
references/build_dag.pyscript12.5 KB
references/chain-composer.mdmarkdown20.4 KB
references/chain-composer/references/canonical-chains.mdmarkdown13.9 KB
references/comprehensive-review-workflow.jsscript19.3 KB
references/comprehensive-review.mdmarkdown27.8 KB
references/comprehensive-review/references/output-templates.mdmarkdown10.6 KB
references/comprehensive-review/references/wave-0-per-package.mdmarkdown5.6 KB
references/comprehensive-review/references/wave-1-foundation.mdmarkdown10.4 KB
references/comprehensive-review/references/wave-2-deep-dive.mdmarkdown7.3 KB
references/comprehensive-review/references/wave-3-adversarial.mdmarkdown7.4 KB
references/dag-compatibility-matrix.mdmarkdown13.0 KB
references/dag-composition-patterns.mdmarkdown5.0 KB
references/dag-orchestration-advanced.mdmarkdown6.3 KB
references/dag-orchestration-examples.mdmarkdown11.4 KB
references/dag-skill-patterns.mdmarkdown12.5 KB
references/de-ai-pipeline.jsscript14.6 KB
references/de-ai-pipeline.mdmarkdown6.3 KB
references/discover_skills.pyscript12.1 KB
references/do-perspectives.mdmarkdown11.5 KB
references/doc-pipeline.mdmarkdown9.2 KB
references/domain-research.mdmarkdown32.8 KB
references/domain-research/references/task-type-guide.mdmarkdown11.4 KB
references/explore-pipeline.jsscript18.6 KB
references/explore-pipeline.mdmarkdown15.0 KB
references/fan-out-workflow.jsscript9.7 KB
references/fan-out-workflow.pyscript10.4 KB
references/feedback-loop-construction.mdmarkdown14.3 KB
references/fl-design.mdmarkdown9.6 KB
references/fl-error-handling.mdmarkdown8.5 KB
references/fl-implement.mdmarkdown7.6 KB
references/fl-pipeline.mdmarkdown6.0 KB
references/fl-plan.mdmarkdown11.0 KB
references/fl-release.mdmarkdown3.8 KB
references/fl-shared.mdmarkdown3.6 KB
references/fl-validate.mdmarkdown4.5 KB
references/github-profile-rules.mdmarkdown10.5 KB
references/github-profile-rules/references/rule-categories.mdmarkdown6.5 KB
references/hc-SPEC.mdmarkdown3.3 KB
references/hc-domain-playbooks.mdmarkdown15.4 KB
references/hc-ledger.mdmarkdown3.3 KB
references/hc-profiling-tools.mdmarkdown3.7 KB
references/hill-climb.mdmarkdown9.3 KB
references/hook-development-pipeline.mdmarkdown12.9 KB
references/mcp-pipeline-builder.mdmarkdown16.3 KB
references/mcp-pipeline-builder/references/analysis-checklist.mdmarkdown6.2 KB
references/mcp-pipeline-builder/references/design-rules.mdmarkdown7.1 KB
references/mcp-pipeline-builder/references/evaluation-guide.mdmarkdown7.6 KB
references/mcp-pipeline-builder/references/python-scaffold-template.mdmarkdown9.5 KB
references/mcp-pipeline-builder/references/ts-scaffold-template.mdmarkdown1.6 KB
references/mcp-pipeline-builder/scripts/assemble-scaffold.pyscript6.3 KB
references/mcp-pipeline-builder/scripts/register_mcp.pyscript6.9 KB
references/mcp-pipeline-builder/templates/client-cli.ts.tmplother682 B
references/mcp-pipeline-builder/templates/client-http.ts.tmplother1.4 KB
references/mcp-pipeline-builder/templates/index.ts.tmplother1.1 KB
references/mcp-pipeline-builder/templates/package.json.tmplother477 B
references/mcp-pipeline-builder/templates/readme.md.tmplother1.1 KB
references/mcp-pipeline-builder/templates/tools.ts.tmplother3.0 KB
references/mcp-pipeline-builder/templates/ts-scaffold.tmplother556 B
references/mcp-pipeline-builder/templates/tsconfig.json.tmplother408 B
references/ol-SPEC.mdmarkdown2.4 KB
references/ol-state-file.mdmarkdown2.9 KB
references/pipeline-index.jsonconfig23.9 KB
references/pipeline-orchestrator.mdmarkdown15.3 KB
references/pipeline-orchestrator/orchestration-patterns.mdmarkdown8.1 KB
references/pipeline-orchestrator/preferred-patterns.mdmarkdown4.6 KB
references/pipeline-retro.mdmarkdown19.0 KB
references/pipeline-scaffolder.mdmarkdown22.4 KB
references/pipeline-scaffolder/references/architecture-rules.mdmarkdown18.9 KB
references/pipeline-scaffolder/references/generated-skill-template.mdmarkdown1.9 KB
references/pipeline-scaffolder/references/pipeline-spec-format.mdmarkdown36.8 KB
references/pipeline-scaffolder/references/step-menu.mdmarkdown21.5 KB
references/pipeline-scaffolder/scripts/assemble-skill.pyscript6.3 KB
references/pipeline-scaffolder/templates/phases/decision-planning.md.tmplother1.2 KB
references/pipeline-scaffolder/templates/phases/domain-extension.md.tmplother1.5 KB
references/pipeline-scaffolder/templates/phases/generation.md.tmplother427 B
references/pipeline-scaffolder/templates/phases/git-release.md.tmplother1.1 KB
references/pipeline-scaffolder/templates/phases/interaction.md.tmplother965 B
references/pipeline-scaffolder/templates/phases/learning-retro.md.tmplother1.5 KB
references/pipeline-scaffolder/templates/phases/observation.md.tmplother1.3 KB
references/pipeline-scaffolder/templates/phases/research-gathering.md.tmplother1.2 KB
references/pipeline-scaffolder/templates/phases/review.md.tmplother930 B
references/pipeline-scaffolder/templates/phases/safety-guarding.md.tmplother1.7 KB
references/pipeline-scaffolder/templates/phases/structuring.md.tmplother361 B
references/pipeline-scaffolder/templates/phases/synthesis-reporting.md.tmplother1.9 KB
references/pipeline-scaffolder/templates/phases/validation.md.tmplother1.1 KB
references/pipeline-scaffolder/templates/skill-template.md.tmplother12.0 KB
references/pipeline-test-runner.mdmarkdown16.7 KB
references/pl-ambiguity-triage.mdmarkdown2.7 KB
references/pl-check-dimensions.mdmarkdown7.4 KB
references/pl-check-errors.mdmarkdown824 B
references/pl-check-verdict-format.mdmarkdown3.2 KB
references/pl-check.mdmarkdown6.5 KB
references/pl-context-boundary.mdmarkdown1.6 KB
references/pl-depth-first-interview.mdmarkdown11.6 KB
references/pl-empirical-prototype.mdmarkdown825 B
references/pl-executor-ready-plan-template.mdmarkdown7.7 KB
references/pl-human-source-elicitation.mdmarkdown1.5 KB
references/pl-manage.mdmarkdown5.1 KB
references/pl-pause-confirm-and-errors.mdmarkdown2.1 KB
references/pl-pause-extract-decisions.mdmarkdown3.0 KB
references/pl-pause-gather-steps.mdmarkdown2.3 KB
references/pl-pause-synthesize-fields.mdmarkdown2.3 KB
references/pl-pause-write-templates.mdmarkdown5.3 KB
references/pl-pause.mdmarkdown6.5 KB
references/pl-plan-files.mdmarkdown8.4 KB
references/pl-pre-plan.mdmarkdown11.6 KB
references/pl-resume.mdmarkdown12.3 KB
references/pl-spec.mdmarkdown5.2 KB
references/pr-fix-loop.mdmarkdown10.3 KB
references/pr-fix-loop/references/message-formats.mdmarkdown1.6 KB
references/pr-fix-loop/references/publish.mdmarkdown5.4 KB
references/pr-fix-loop/references/review-checklist.mdmarkdown3.4 KB
references/pr-pipeline/references/pr-templates.mdmarkdown5.4 KB
references/pr-pipeline/references/preflight-checklist.mdmarkdown2.8 KB
references/pr-pipeline/references/retro-adr-phases.mdmarkdown2.7 KB
references/pr-pipeline/references/review-fix-loop.mdmarkdown2.0 KB
references/project-coordinator.mdmarkdown6.5 KB
references/project-coordinator/agent-capability-map.mdmarkdown5.4 KB
references/project-coordinator/communication-protocols.mdmarkdown4.5 KB
references/project-coordinator/coordination-playbook.mdmarkdown3.7 KB
references/project-coordinator/death-loop-prevention.mdmarkdown3.6 KB
references/project-coordinator/error-catalog.mdmarkdown2.7 KB
references/project-coordinator/parallel-execution-patterns.mdmarkdown2.8 KB
references/project-coordinator/preferred-patterns.mdmarkdown5.9 KB
references/project-coordinator/todowrite-integration.mdmarkdown5.6 KB
references/research-pipeline.jsscript15.2 KB
references/skill-creation-pipeline.mdmarkdown17.1 KB
references/system-upgrade.mdmarkdown12.8 KB
references/systematic-debugging.mdmarkdown11.0 KB
references/systematic-refactoring.mdmarkdown11.4 KB
references/toolkit-improvement.jsscript39.0 KB
references/toolkit-improvement.mdmarkdown20.5 KB
references/toolkit-improvement/references/adr-template.mdmarkdown10.5 KB
references/toolkit-improvement/references/agent-roster.mdmarkdown15.8 KB
references/workflow-helpers.jsscript12.1 KB
references/workflow-orchestrator.mdmarkdown20.8 KB
references/workflow-orchestrator/references/plan-template.mdmarkdown1.3 KB
references/workflow-orchestrator/references/task-patterns.mdmarkdown23.3 KB
references/workflow-orchestrator/scripts/assemble-plan.pyscript6.9 KB
references/workflow-orchestrator/scripts/validate.pyscript14.4 KB
references/workflow-orchestrator/templates/plan-template.json.tmplother904 B

references/comprehensive-review-workflow.js

View on GitHub
// comprehensive-review-workflow.js
//
// Native dynamic-Workflow variant of the four-wave comprehensive review.
// The markdown flow at ./comprehensive-review.md remains the documented
// fallback; this script is the deterministic-runtime OPTION for diffs that
// benefit (tier >= 3, or wide multi-package changes). It mirrors the same
// waves but replaces the $REVIEW_DIR/*.md disk round-trips with
// schema-validated typed agent() returns, real barriers (parallel) and
// item-streaming (pipeline), and a token-budget-bounded fix loop.
//
// Safety default: the run reports and edits nothing. The fix loop runs only
// when the caller passes `implement: true` and a non-default work `branch`
// (editBlocker in workflow-helpers.js). Every fix agent checks the branch.
//
// Runtime contract (see docs/dynamic-workflows-vs-vexjoy-diff.md):
//   - meta is a pure object literal (name + description) parsed before the body.
//   - parallel(thunks) is a hard barrier; a failed agent resolves to null.
//   - pipeline(items, ...stages) streams items through stages without a barrier.
//   - agent({prompt, schema, model}) forces a StructuredOutput tool call,
//     validates against schema at the tool layer, auto-retries on mismatch,
//     and returns a typed object — no markdown re-parse, no disk read.
//   - budget.remaining() returns run-wide tokens left; agent() throws when
//     exhausted. The fix loop is bounded by it.
//   - Wall-clock and randomness are unavailable by design, so determinism is
//     bit-stable across replay. This script uses neither.

import {
  branchRule,
  editBlocker,
  engineerForPath,
  mandatoryInjections,
  modelFor,
  referenceDirective,
  referenceForPath,
  skillDirectives,
  tierOrFull,
  validateModelOverride,
  WORKER,
} from "./workflow-helpers.js";

export const meta = {
  name: "comprehensive-review-workflow",
  description:
    "Four-wave code review as a deterministic native Workflow: tier-scaled waves (right-sizing), schema-validated typed findings per wave, parallel barriers within a wave, pipelined Wave 1 -> Wave 2 hand-off, per-finding adversarial verify before synthesis, and a budget-bounded fix loop. With no tier the run covers every wave; an explicit tier shrinks it. Report-only by default: the fix loop runs only with implement: true plus a non-default work branch. Each reviewer is a fresh general-purpose worker that loads its review-skill reference and attaches its full skill stack (one exact Skill-tool call per skill) plus the /do mandatory injections. Mirrors comprehensive-review.md; that markdown flow stays the fallback.",
  // --- Conformance contract (pure literal — no calls/variables; see
  //     scripts/validate-workflow-conformance.py + adr/native-fast-path-portable-floor.md
  //     Stages 0-1). This is the declared dispatch shape the conformance gate
  //     asserts the actual script against. STATIC validation pins phases + the
  //     fixed Wave-1 barrier (countable). DYNAMIC validation records the real
  //     dispatch trace and asserts SHAPE + SKILLS, NOT count, where dynamic:true.
  //     name + description stay BEFORE this nested object so the non-greedy
  //     meta-name parser in workflow-registry.py still resolves meta.name.
  contract: {
    // Phase titles this script enters at runtime via phase(). Order matters.
    phases: ["wave-1", "wave-2", "wave-3", "verify", "fix"],
    // Wave-1 is a FIXED barrier: a literal 4-agent roster, every run. Countable.
    // Each entry carries a `skills` LIST (the full stack the agent attaches via
    // one exact Skill-tool call per element) — the gate asserts EACH declared skill has a
    // corresponding exact Skill-tool call in source.
    roster: [
      { agentType: "general-purpose", skills: ["review", "testing"] },
      { agentType: "general-purpose", skills: ["review", "testing"] },
      { agentType: "general-purpose", skills: ["review", "testing"] },
      { agentType: "general-purpose", skills: ["assessment", "testing"] },
    ],
    // The Wave-1 barrier dispatches exactly 4 agents on every run (static).
    agents: { static: 4, dynamic: false },
    // Wave-2/3 rosters are literal arrays (countable) but tier-gated, and the
    // per-finding verify pass + the budget-bounded fix loop fan out over
    // RUNTIME data (findings.length, budget) — NOT statically countable.
    // Honest limit: the gate asserts SHAPE + SKILLS for these, not COUNT.
    dynamic: true,
  },
};

// Repo agents are retired (plan 009). Every reviewer is a fresh general-purpose
// worker (WORKER) that reads one review reference from the review skill, so each
// lens still runs in its own independent context. REVIEWERS maps each reference
// slug to that reference and to the FULL skill stack the worker invokes by name
// (one exact Skill-tool call per element). reviewer-{system,domain,code} run the
// review methodology; reviewer-perspectives runs the assessment (multi-persona)
// lens; every reviewer also runs testing (verification gate — the /do Phase-3
// stack for review).
const REVIEWERS = {
  "reviewer-system": { agent: "general-purpose", ref: { skill: "review", file: "reviewer-system.md" }, skills: ["review", "testing"] },
  "reviewer-domain": { agent: "general-purpose", ref: { skill: "review", file: "reviewer-domain.md" }, skills: ["review", "testing"] },
  "reviewer-code": { agent: "general-purpose", ref: { skill: "review", file: "reviewer-code.md" }, skills: ["review", "testing"] },
  "reviewer-perspectives": { agent: "general-purpose", ref: { skill: "review", file: "reviewer-perspectives.md" }, skills: ["assessment", "testing"] },
};

// One roster entry: a general-purpose worker, the reference it loads, its skill
// stack, and the wave-specific lens.
function reviewer(slug, lens) {
  const r = REVIEWERS[slug];
  return { agent: r.agent, name: slug, ref: r.ref, skills: r.skills, lens };
}

// The per-finding verify pass dispatches the challenger reference with its stack.
const VERIFY_REVIEWER = "reviewer-perspectives";

// The fix loop dispatches the engineer that owns the finding's file type
// (engineerForPath, a private overlay agent when indexed) or a general-purpose
// worker that loads the file type's reference (referenceForPath), with this stack.
const FIX_SKILLS = ["programming", "testing"];

// --- Wave rosters: the four review references, applied through wave-specific
//     lenses. Each entry is a separate fresh worker, so the SAME four reviewer
//     references scale in depth across waves without inventing per-topic
//     roles. This mirrors the lens-based scheme in
//     comprehensive-review/references/wave-{1,2,3}-*.md. ----------------------
const WAVE1_AGENTS = [
  reviewer("reviewer-system", "security, input validation, error handling, API contracts"),
  reviewer("reviewer-domain", "business logic, edge cases, data integrity, state transitions"),
  reviewer("reviewer-code", "conventions, naming, dead code, performance, test coverage"),
  reviewer("reviewer-perspectives", "newcomer clarity, user-advocate, senior-maintainer view"),
];

// Tier 3 dispatches the deep-dive subset; Tier 4 adds the remaining lenses.
const WAVE2_SUBSET = [
  reviewer("reviewer-system", "deep security + concurrency + resource lifecycle"),
  reviewer("reviewer-domain", "deep correctness + data integrity + migration safety"),
  reviewer("reviewer-code", "deep performance + error paths + state machines"),
];

const WAVE2_FULL = WAVE2_SUBSET.concat([
  reviewer("reviewer-system", "API-contract compatibility + observability gaps"),
  reviewer("reviewer-perspectives", "senior-maintainer + meta-process review"),
]);

const WAVE3_AGENTS = [
  reviewer("reviewer-perspectives", "contrarian + falsifier: try to break the change"),
  reviewer("reviewer-system", "adversarial security: assume hostile input everywhere"),
  reviewer("reviewer-domain", "adversarial assumptions: challenge every invariant"),
  reviewer("reviewer-code", "simplicity challenge: is this over-engineered?"),
];

// --- Schemas (mirror skills/shared-patterns/schemas/) -------------------------

const FINDING_SCHEMA = {
  type: "object",
  required: ["title", "location", "severity"],
  properties: {
    title: { type: "string" },
    // file:line, matching the review-output-base finding pattern.
    location: { type: "string", pattern: "^[\\w./\\-]+:\\d+" },
    severity: { type: "string", enum: ["critical", "high", "medium", "low"] },
    description: { type: "string" },
    recommendation: { type: "string" },
    reviewer: { type: "string" },
  },
};

const WAVE_OUTPUT_SCHEMA = {
  type: "object",
  required: ["verdict", "findings"],
  properties: {
    verdict: { type: "string", enum: ["BLOCK", "FIX", "APPROVE"] },
    summary: { type: "string", minLength: 10 },
    findings: { type: "array", items: FINDING_SCHEMA },
    positives: { type: "array", items: { type: "string" } },
  },
};

// Per-finding adversarial verdict (mirrors the pr-review per-finding verify).
const VERIFY_SCHEMA = {
  type: "object",
  required: ["finding_title", "disposition"],
  properties: {
    finding_title: { type: "string" },
    disposition: {
      type: "string",
      enum: ["AGREE", "CHALLENGE", "DOWNGRADE", "DISMISS"],
    },
    rationale: { type: "string" },
  },
};

const FIX_SCHEMA = {
  type: "object",
  required: ["finding_title", "outcome"],
  properties: {
    finding_title: { type: "string" },
    outcome: { type: "string", enum: ["FIXED", "BLOCKED"] },
    files_changed: { type: "array", items: { type: "string" } },
    note: { type: "string" },
  },
};

// --- Helpers ------------------------------------------------------------------

const SEVERITY_ORDER = { critical: 0, high: 1, medium: 2, low: 3 };

function collectFindings(waveOutputs) {
  // waveOutputs: array of (typed wave result | null from a failed barrier slot).
  const out = [];
  for (const result of waveOutputs) {
    if (result && Array.isArray(result.findings)) {
      out.push(...result.findings);
    }
  }
  return out;
}

function hasCritical(findings) {
  return findings.some((f) => f.severity === "critical");
}

function dedupeFindings(findings) {
  // Same file:line + title -> keep the higher severity, merge reviewer credit.
  const byKey = new Map();
  for (const f of findings) {
    const key = `${f.location}::${f.title}`;
    const prior = byKey.get(key);
    if (!prior) {
      byKey.set(key, { ...f, reviewers: [f.reviewer].filter(Boolean) });
      continue;
    }
    if (SEVERITY_ORDER[f.severity] < SEVERITY_ORDER[prior.severity]) {
      prior.severity = f.severity;
      prior.recommendation = f.recommendation || prior.recommendation;
    }
    if (f.reviewer && !prior.reviewers.includes(f.reviewer)) {
      prior.reviewers.push(f.reviewer);
    }
  }
  return [...byKey.values()].sort(
    (a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity],
  );
}

function reviewPrompt(roster, scope, priorContext) {
  // roster is {agent, name, ref, skills, lens}; priorContext is the typed prior-wave summary
  // passed in-memory (no disk read). skillDirectives emits one exact call per
  // element of roster.skills (the full stack) — the call resolves path-
  // independent inside a native Workflow agent() dispatch (proven this session).
  // mandatoryInjections() embeds the /do completeness/density/base-instructions/
  // reference-loading block so a workflow agent gets the same context as a direct
  // /do dispatch.
  const context = priorContext
    ? `\n\nPrior-wave findings (typed, in-memory):\n${JSON.stringify(priorContext)}`
    : "";
  return (
    `You are a ${roster.name} review worker. Apply this review lens: ${roster.lens}.` +
    skillDirectives(roster.skills) +
    referenceDirective(roster.ref) +
    `\nReview the changed code for this diff scope:\n` +
    `${JSON.stringify(scope)}\n` +
    `Return only findings within your lens. The only valid dispositions are ` +
    `FIX NOW, FIX IN FOLLOW-UP (with a tracking artifact), or NOT AN ISSUE ` +
    `(with evidence). "Acceptable", "valid but deferred", and "conservative" ` +
    `are not valid dispositions. Severity is one of critical|high|medium|low.` +
    mandatoryInjections() +
    context
  );
}

// Defensive phase marker: the native runtime guarantees agent/parallel/pipeline/
// budget, but does NOT document a phase() global. Guard the call so the real
// runtime never throws if phase is absent, while the conformance harness's mock
// records the entered phase. Phase titles match meta.contract.phases.
function enterPhase(title) {
  if (typeof phase === "function") {
    phase(title);
  }
}

// --- Workflow body ------------------------------------------------------------
//
// `scope` is the diff descriptor the caller passes in (changed files, packages,
// and the right-size-review tier). `tier` honors scripts/right-size-review.py:
//   tier <= 2 -> Wave 1 only; tier 3 -> Wave 1 + Wave 2 subset (Wave 3 only on a
//   CRITICAL); tier 4 -> Wave 1 + Wave 2 full + Wave 3. Wave 3 also runs at any
//   tier once a CRITICAL surfaces (the escalation safety valve). An unset tier
//   runs every wave (tier 4): 4 + 5 + 4 = 13 reviewers. Only an explicit tier
//   shrinks the review (owner, 2026-11-09: "Comprehensive review is no longer
//   comprehensive with 1 wave").
// `implement` + `branch` clear the fix gate: `implement: true` and a work branch
// that is not main, master, or trunk. Pass both only after the operator asks
// for fixes. Otherwise the run stops after verify and returns `fix_blocked`.
// `reviewOnly: true` stops after verify even when `implement` is set (the prose
// --review-only flag).
// `modelOverride` is a model the owner named for this task. When set, every
// agent runs on it. Unset: every agent runs the `work` model, because reviewers
// and verifiers return findings that decide and the fix loop edits files.

export default async function run({
  scope,
  tier,
  fixThreshold,
  modelOverride,
  implement,
  branch,
  reviewOnly,
} = {}) {
  // Reject a bad model name before any dispatch.
  validateModelOverride(modelOverride);
  const effectiveTier = tierOrFull(tier);
  const fixBlocked = reviewOnly === true ? "reviewOnly is set" : editBlocker(implement, branch);
  const minBudgetPerFix = typeof fixThreshold === "number" ? fixThreshold : 8000;

  // Wave 1: foundation. Hard barrier — every foundation agent completes before
  // the wave is considered closed. Failed slots resolve to null and are dropped.
  enterPhase("wave-1");
  const wave1 = await parallel(
    WAVE1_AGENTS.map((r) => () =>
      agent({
        prompt: reviewPrompt(r, scope, null),
        schema: WAVE_OUTPUT_SCHEMA,
        model: modelFor("work", modelOverride),
        agentType: r.agent,
      }),
    ),
  );
  let findings = collectFindings(wave1);

  // Wave 2: deep-dive, only at tier >= 3. pipeline() streams each Wave 1
  // finding into a matched deep-dive agent without a disk re-read — agent B
  // can start while agent A is still running.
  if (effectiveTier >= 3) {
    enterPhase("wave-2");
    const wave2Roster = effectiveTier >= 4 ? WAVE2_FULL : WAVE2_SUBSET;
    const wave2Summary = { findings, source: "wave1" };
    const wave2 = await parallel(
      wave2Roster.map((r) => () =>
        agent({
          prompt: reviewPrompt(r, scope, wave2Summary),
          schema: WAVE_OUTPUT_SCHEMA,
          model: modelFor("work", modelOverride),
          agentType: r.agent,
        }),
      ),
    );
    findings = findings.concat(collectFindings(wave2));
  }

  // Wave 3: adversarial. Runs at tier 4 unconditionally, or at any tier once a
  // CRITICAL is present (escalation safety valve mirrored from the markdown).
  const wave3Required = effectiveTier >= 4 || hasCritical(findings);
  if (wave3Required) {
    enterPhase("wave-3");
    const wave3Summary = { findings, source: "wave1+2" };
    const wave3 = await parallel(
      WAVE3_AGENTS.map((r) => () =>
        agent({
          prompt: reviewPrompt(r, scope, wave3Summary),
          schema: WAVE_OUTPUT_SCHEMA,
          model: modelFor("work", modelOverride),
          agentType: r.agent,
        }),
      ),
    );
    findings = findings.concat(collectFindings(wave3));
  }

  findings = dedupeFindings(findings);

  // Per-finding adversarial verify BEFORE synthesis (mirrors the pr-review
  // gated per-finding verify). Each finding gets one challenger (a worker that
  // loads VERIFY_REVIEWER's reference, with its skill stack); DISMISS drops it from the fix queue. parallel()
  // barriers the whole verify pass.
  enterPhase("verify");
  const verdicts = await parallel(
    findings.map((f) => () =>
      agent({
        prompt:
          `You are a ${VERIFY_REVIEWER} review worker. Adversarially verify this ` +
          `review finding. Confirm it is real and correctly rated, or challenge ` +
          `it with evidence.` +
          skillDirectives(REVIEWERS[VERIFY_REVIEWER].skills) +
          referenceDirective(REVIEWERS[VERIFY_REVIEWER].ref) +
          `\nFinding:\n${JSON.stringify(f)}` +
          mandatoryInjections(),
        schema: VERIFY_SCHEMA,
        model: modelFor("work", modelOverride),
        agentType: WORKER,
      }),
    ),
  );
  const dismissed = new Set(
    verdicts
      .filter((v) => v && v.disposition === "DISMISS")
      .map((v) => v.finding_title),
  );
  const verified = findings.filter((f) => !dismissed.has(f.title));

  // The fix gate: stop before any edit unless the caller passed implement: true
  // with a non-default work branch. The verified findings are the report.
  if (fixBlocked != null) {
    return {
      tier: effectiveTier,
      wave3_ran: wave3Required,
      total_findings: findings.length,
      verified_findings: verified.length,
      verified,
      dismissed: [...dismissed],
      review_only: true,
      implement_requested: implement === true,
      fix_blocked: fixBlocked,
      fixes: [],
      unfixed: verified.map((f) => f.title),
      deferred_for_budget: [],
      budget_remaining: budget.remaining(),
    };
  }

  // Phase 4 fix loop, bounded by the native token budget. CRITICAL first.
  // The loop stops when findings are exhausted OR the run-wide budget can no
  // longer afford another fix agent — a hard, replayable spend ceiling. Every
  // fix agent gets the branch rule: edit only on the caller's work branch.
  enterPhase("fix");
  const queue = verified.slice();
  const fixes = [];
  const deferred = [];
  while (queue.length > 0) {
    if (budget.remaining() < minBudgetPerFix) {
      deferred.push(...queue.splice(0));
      break;
    }
    const f = queue.shift();
    const result = await agent({
      prompt:
        `Apply the fix for this verified review finding, then confirm it ` +
        `compiles and relevant tests pass. If the fix breaks tests and an ` +
        `alternative also breaks tests, return outcome BLOCKED. On a branch ` +
        `mismatch return outcome BLOCKED.` +
        branchRule(branch) +
        skillDirectives(FIX_SKILLS) +
        referenceDirective(referenceForPath(f.location)) +
        `\nFinding:\n${JSON.stringify(f)}` +
        mandatoryInjections(),
      schema: FIX_SCHEMA,
      model: modelFor("work", modelOverride),
      agentType: engineerForPath(f.location) ?? WORKER,
    });
    if (result) {
      fixes.push(result);
    }
  }

  return {
    tier: effectiveTier,
    wave3_ran: wave3Required,
    total_findings: findings.length,
    verified_findings: verified.length,
    dismissed: [...dismissed],
    review_only: false,
    implement_requested: true,
    fix_blocked: null,
    branch,
    fixes,
    deferred_for_budget: deferred.map((f) => f.title),
    budget_remaining: budget.remaining(),
  };
}
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall