Skip to content

rohitg00/pro-workflow / skills/survey-generator

survey-generator

Verified

Compile a structured literature survey on any AI/ML topic. Agent curates a research bundle (taxonomy + sections + bibliography of real papers) from a public anchor resource, then a chosen LLM generates the survey artifact. Output target is a wiki page (markdown), not a one-off HTML — survey lands in `<wiki>/derived/surveys/<slug>.md` with full bibliography rows in `sources.md`. Provider-agnostic (Anthropic/OpenAI/OpenRouter/Fireworks/custom OpenAI-compat). Use when the user asks for a "survey", "literature review", "lit review", or "deep dive" on a technical topic.

FileKindSize
SKILL.mdskill md6.2 KB
scripts/build-survey.jsexecutablescript10.3 KB
templates/research_bundle.template.jsonconfig1.7 KB

scripts/build-survey.js

View on GitHub
#!/usr/bin/env node
const fs = require('fs');
const path = require('path');
const https = require('https');
const { execFileSync } = require('child_process');
const { getCredential } = require('../../../scripts/lib/credentials.js');

const PRO_WORKFLOW_ROOT = path.resolve(__dirname, '..', '..', '..');
const COUNCIL = path.join(PRO_WORKFLOW_ROOT, 'skills', 'llm-council', 'scripts', 'council.js');

function parseArgs(argv) {
  const out = { _: [] };
  for (let i = 0; i < argv.length; i++) {
    const a = argv[i];
    if (a.startsWith('--')) {
      const key = a.slice(2);
      const next = argv[i + 1];
      if (next && !next.startsWith('--')) { out[key] = next; i++; }
      else out[key] = true;
    } else out._.push(a);
  }
  return out;
}

function die(msg) { console.error(`[survey] ${msg}`); process.exit(1); }

function getStore() {
  const distPath = path.join(PRO_WORKFLOW_ROOT, 'dist', 'db', 'store.js');
  if (!fs.existsSync(distPath)) die(`built store missing at ${distPath}. Run npm run build`);
  return require(distPath).createStore();
}

function postJSON(urlStr, body, headers, timeoutMs = 180000) {
  return new Promise((resolve, reject) => {
    const url = new URL(urlStr);
    const data = JSON.stringify(body);
    const req = https.request({
      hostname: url.hostname,
      path: url.pathname + url.search,
      method: 'POST',
      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(data), ...headers },
    }, res => {
      let chunks = '';
      res.on('data', c => { chunks += c; });
      res.on('end', () => resolve({ status: res.statusCode, body: chunks }));
    });
    req.setTimeout(timeoutMs, () => req.destroy(new Error('survey request timeout')));
    req.on('error', reject);
    req.write(data);
    req.end();
  });
}

const PROVIDER_DEFAULTS = {
  anthropic: { envKey: 'ANTHROPIC_API_KEY', baseUrl: 'https://api.anthropic.com', model: 'claude-opus-5-5' },
  openai: { envKey: 'OPENAI_API_KEY', baseUrl: 'https://api.openai.com/v1', model: 'gpt-4o' },
  openrouter: { envKey: 'OPENROUTER_API_KEY', baseUrl: 'https://openrouter.ai/api/v1', model: 'anthropic/claude-opus-4' },
  fireworks: { envKey: 'FIREWORKS_API_KEY', baseUrl: 'https://api.fireworks.ai/inference/v1', model: 'accounts/fireworks/models/kimi-k2p5' },
  custom: { envKey: 'LLM_COUNCIL_API_KEY', baseUrl: process.env.LLM_COUNCIL_BASE_URL || '', model: process.env.LLM_COUNCIL_CHAIRMAN || '' },
};

function pickProvider(arg) {
  if (arg) return Object.hasOwn(PROVIDER_DEFAULTS, arg) && getCredential(PROVIDER_DEFAULTS[arg].envKey) ? arg : null;
  for (const [name, p] of Object.entries(PROVIDER_DEFAULTS)) if (getCredential(p.envKey)) return name;
  return null;
}

async function callProvider(providerName, model, system, user, maxTokens) {
  const p = PROVIDER_DEFAULTS[providerName];
  const apiKey = getCredential(p.envKey);
  if (!apiKey) die(`Configure ${providerName} in plugin settings, or set PRO_WORKFLOW_${p.envKey} for the standalone CLI`);
  if (providerName === 'anthropic') {
    const res = await postJSON(`${p.baseUrl}/v1/messages`, {
      model, max_tokens: maxTokens, system, messages: [{ role: 'user', content: user }],
    }, { 'x-api-key': apiKey, 'anthropic-version': '2023-06-01' });
    if (res.status >= 400) die(`anthropic error ${res.status}: ${res.body.slice(0, 300)}`);
    const data = JSON.parse(res.body);
    return (data.content || []).map(b => b.text || '').join('');
  }
  const res = await postJSON(`${p.baseUrl}/chat/completions`, {
    model, max_tokens: maxTokens, temperature: 0.7,
    messages: [{ role: 'system', content: system }, { role: 'user', content: user }],
  }, { Authorization: `Bearer ${apiKey}` });
  if (res.status >= 400) die(`${providerName} error ${res.status}: ${res.body.slice(0, 300)}`);
  const data = JSON.parse(res.body);
  return data.choices?.[0]?.message?.content || '';
}

function slugify(s) { return s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 60); }

function bibCitationId(key) {
  return `src-bib-${slugify(key)}`;
}

function appendBibliographyToSources(wikiRoot, bibliography) {
  const file = path.join(wikiRoot, 'sources.md');
  let existing = '';
  if (fs.existsSync(file)) existing = fs.readFileSync(file, 'utf8');
  const seenKeys = new Set();
  for (const m of existing.matchAll(/\| (src-bib-[a-z0-9-]+) \|/g)) seenKeys.add(m[1]);

  const newRows = [];
  for (const b of bibliography) {
    const id = bibCitationId(b.key);
    if (seenKeys.has(id)) continue;
    const url = b.url || (b.venue && b.venue.startsWith('arXiv:') ? `https://arxiv.org/abs/${b.venue.slice(6)}` : '');
    newRows.push(`| ${id} | paper | ${url} | ${b.title.replace(/\|/g, '\\|')} | ${b.key} | ${new Date().toISOString().slice(0, 10)} |`);
  }
  if (!newRows.length) return 0;

  const tableHeader = '| id | type | url | title | key | added_at |\n| --- | --- | --- | --- | --- | --- |';
  const hasHeader = existing.includes('| id | type |');
  if (!hasHeader) {
    const prefix = existing.length ? (existing.endsWith('\n') ? existing : existing + '\n') : '';
    fs.writeFileSync(file, `${prefix}${tableHeader}\n${newRows.join('\n')}\n`);
  } else {
    fs.writeFileSync(file, existing.trimEnd() + '\n' + newRows.join('\n') + '\n');
  }
  return newRows.length;
}

function nextVersion(dir, baseSlug) {
  if (!fs.existsSync(dir)) return 1;
  const re = new RegExp(`^${baseSlug}-v(\\d+)\\.md$`);
  let max = 0;
  for (const f of fs.readdirSync(dir)) {
    const m = f.match(re);
    if (m) max = Math.max(max, parseInt(m[1], 10));
  }
  return max + 1;
}

function buildPrompt(bundle) {
  const bibWithIds = bundle.bibliography.map(b => ({ ...b, citation_id: bibCitationId(b.key) }));
  const sectionsWithIds = bundle.sections.map(s => ({
    ...s,
    paper_citation_ids: (s.papers || []).map(k => bibCitationId(k)),
  }));
  return `Compile a literature survey on the topic "${bundle.topic}" using ONLY the bibliography provided.

Output strict markdown:
- H1 = topic title
- Numbered H2 sections following the provided sections list
- Inline citations as [^citation_id] using the EXACT citation_id from the bibliography below (e.g., [^src-bib-park-2023-generative-agents])
- A "## References" section at the end listing every cited [^citation_id] with: citation_id, authors, year, title, venue, one-sentence summary
- No HTML, no SVG, no inline images
- ~600-1200 words per section, scaled by bibliography size
- For each section, weave together the papers in section.paper_citation_ids; do not just list them

Bibliography (USE THE citation_id FIELD EXACTLY for inline citations):
${JSON.stringify(bibWithIds, null, 2)}

Sections to produce in order (use paper_citation_ids for citations):
${JSON.stringify(sectionsWithIds, null, 2)}

Anchor (context only, do not cite):
${bundle.anchor_source || ''}

Hard rules:
- Cite real papers from the bibliography only. Do not invent.
- Every section that lists papers MUST cite each one at least once via its citation_id.
- Use [^citation_id] for inline citations. The References section reuses these citation_id values.
- Do not write any prose under the H1; start sections immediately.`;
}

async function cmdRun(args) {
  const bundlePath = args.bundle;
  const slug = args.wiki;
  if (!bundlePath || !slug) die('usage: build-survey.js --bundle <path> --wiki <slug> [--provider name] [--model id]');
  if (!fs.existsSync(bundlePath)) die(`bundle not found: ${bundlePath}`);

  const bundle = JSON.parse(fs.readFileSync(bundlePath, 'utf8'));
  if (!bundle.topic || !Array.isArray(bundle.bibliography)) die('bundle missing topic or bibliography[]');
  const invalid = bundle.bibliography.find(
    b => !b || typeof b.key !== 'string' || !b.key.trim() || typeof b.title !== 'string' || !b.title.trim()
  );
  if (invalid) die('bundle bibliography[] entries must include non-empty string key and title');

  const bibKeys = new Set();
  for (const b of bundle.bibliography) {
    if (bibKeys.has(b.key)) die(`duplicate bibliography key: ${b.key}`);
    bibKeys.add(b.key);
  }

  if (Array.isArray(bundle.sections)) {
    for (const [i, s] of bundle.sections.entries()) {
      if (!Array.isArray(s.papers)) continue;
      for (const k of s.papers) {
        if (typeof k !== 'string' || !k.trim()) die(`sections[${i}].papers contains non-string entry`);
        if (!bibKeys.has(k)) die(`sections[${i}].papers references unknown bibliography key: ${k}`);
      }
    }
  }

  const providerName = pickProvider(args.provider);
  if (!providerName) die('No configured provider. Set a key in plugin settings, or use a PRO_WORKFLOW_*_API_KEY variable for the standalone CLI.');
  const model = args.model || PROVIDER_DEFAULTS[providerName].model;
  if (!model) die('no model — pass --model');

  const store = getStore();
  let wiki;
  try { wiki = store.getWiki(slug); } finally { store.close(); }
  if (!wiki) die(`unknown wiki: ${slug}`);

  console.error(`[survey] generating with ${providerName}:${model} for wiki ${slug}`);
  const md = await callProvider(providerName, model, 'You are a careful technical-writing assistant generating a literature survey.', buildPrompt(bundle), 16000);

  const surveysDir = path.join(wiki.root_path, 'derived', 'surveys');
  fs.mkdirSync(surveysDir, { recursive: true });
  const baseSlug = slugify(bundle.topic);
  const v = nextVersion(surveysDir, baseSlug);
  const fileName = `${baseSlug}-v${v}.md`;
  const fileAbs = path.join(surveysDir, fileName);
  fs.writeFileSync(fileAbs, md);

  const added = appendBibliographyToSources(wiki.root_path, bundle.bibliography);
  console.error(`[survey] wrote ${fileAbs}`);
  console.error(`[survey] appended ${added} new bibliography rows to sources.md`);

  // Index via wiki-cli
  const wikiCli = path.join(PRO_WORKFLOW_ROOT, 'skills', 'wiki-builder', 'scripts', 'wiki-cli.js');
  const relPath = path.relative(wiki.root_path, fileAbs);
  try {
    execFileSync('node', [wikiCli, 'page', slug, relPath, '--type', 'survey'], { stdio: 'inherit' });
  } catch (e) {
    die(`wiki-cli page failed: ${e.message}`);
  }
  console.log(JSON.stringify({ slug, file: fileAbs, version: v, bibliography_added: added }, null, 2));
}

async function main() {
  const [, , ...rest] = process.argv;
  const args = parseArgs(rest);
  if (rest.length === 0 || args.help) {
    console.error('Usage: build-survey.js --bundle <path> --wiki <slug> [--provider anthropic|openai|openrouter|fireworks|custom] [--model id]');
    process.exit(1);
  }
  await cmdRun(args);
}

main().catch(e => { console.error(e); process.exit(1); });
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall