seeding-playbooks

Seeding Playbooks

Coordinate bulk creation or enrichment of playbook agent notes across many orgs using parallel sub-agents.

What a playbook is

A playbook is a per-org skill for fetching that org's releases. Same mental model as the global skills in this corpus (parsing-changelogs, managing-sources, etc.) — but scoped to one organization. It tells a future agent (managed or local) how to pull updates from this org: extraction quirks, naming conventions, which sources are canonical, what to skip, where rollups hide.

Global skills teach general patterns; per-source parseInstructions teach source-specific hints; the playbook is the org-level layer between them. When agents fetch any of an org's sources, they should load that org's playbook into context alongside the global skills — the playbook overrides general rules with specific org behavior.

Write notes as instructions to an LLM, not as human documentation. Imperative voice ("Set version=null", "Parse <h2> as version boundaries"), concrete examples from real data, and only observations that change future fetch behavior.

Currently a local-Claude-Code skill. The dispatch pattern below uses Claude Code's Agent tool — that's what's actually wired up. Managed agents (discovery worker, Haiku worker) can spawn sub-agents in principle, but the harness, prompt scaffolding, and rate-limit accounting for managed sub-agent dispatch in this repo haven't been built yet. If/when that gets wired up, the prompts and dispatch shape in this skill port directly.

When to Use

• Batch-populating playbooks for orgs that have sources but no notes
• Re-running the verified workflow on existing playbooks to enrich them with data-grounded observations
• After a wave of new orgs are onboarded and need initial playbook scaffolding

Step 1: Identify Targets

Find orgs that need playbooks. Run this to check coverage:

bun -e "
const orgs = JSON.parse(Bun.spawnSync(['releases', 'admin', 'org', 'list', '--json'], { stderr: 'ignore' }).stdout.toString());
const active = orgs.filter(o => o.sourceCount > 0).sort((a,b) => b.releaseCount - a.releaseCount);
for (const org of active) {
  const playbook = JSON.parse(Bun.spawnSync(['releases', 'admin', 'playbook', org.slug, '--json'], { stderr: 'ignore' }).stdout.toString());
  const status = playbook.notes?.length > 100 ? 'has notes (' + playbook.notes.length + ' chars)' : 'NEEDS PLAYBOOK';
  console.log(org.slug.padEnd(25) + ' sources=' + String(org.sourceCount).padStart(2) + '  ' + status);
}
" 2>/dev/null