@hippo-digital/hippocampus 1.0.0-rc.1

package/scripts/triage-research-corpus.js

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+/**
+ * Triage a research folder before anything is imported.
+ *
+ * `research:sync` answers "did the import run?". It cannot answer the question
+ * a team actually asks first: out of several hundred files in a shared drive,
+ * which ones are worth turning into knowledge, and what would each become?
+ *
+ * This script reads every artefact, scores the signals that matter to the
+ * Hippocampus schema, and writes a ranked review pack. It never writes to
+ * hippocampus/source and never promotes anything.
+ *
+ *   node scripts/triage-research-corpus.js --source "/path/to/folder" --topic ncrs-ur
+ */
+
+const fs = require('fs')
+const path = require('path')
+const { extractArtefact, supports, sourceTypeFor } = require('./lib/artefact-text')
+const { createContextOrExit } = require('../lib/context')
+const ctx = createContextOrExit()
+const { researchInboxDir } = ctx.paths
+
+const MEDIA = new Set(['.mp4', '.mov', '.png', '.jpg', '.jpeg', '.webp', '.gif', '.svg', '.msg', '.mht', '.msi', '.json', '.html', '.download', '.dotx'])
+
+/** Signals that predict which Hippocampus record a file can become. */
+const SIGNALS = {
+  participant: /\bP\d{1,3}\b/g,
+  quote: /“[^”]{40,}”/g,
+  insight: /\b(insight|finding|theme|what we learned|key takeaway|pain point|problem statement)\b/gi,
+  action: /\b(design action|recommendation|next action|opportunity|we should|we will)\b/gi,
+  need: /\b(user need|i need to|so that i can|as an? [a-z ]{3,30}, i need)\b/gi,
+  assumption: /\b(assumption|we assume|riskiest assumption|hypothesis)\b/gi,
+  scenario: /\b(scenario|use case|journey|workflow|trigger)\b/gi,
+  persona: /\b(persona|goals|frustrations|motivations|responsibilities)\b/gi,
+  method: /\b(discussion guide|research plan|screener|consent|recruitment|interview guide)\b/gi
+}
+
+/**
+ * Weighted because a direct participant quote is worth far more to the graph
+ * than another occurrence of the word "theme".
+ */
+const WEIGHTS = { quote: 4, participantsUnique: 3, insight: 3, need: 3, action: 2, assumption: 2, persona: 1, scenario: 1 }
+
+async function main () {
+  const args = parseArgs(process.argv.slice(2))
+  const sourceDir = path.resolve(args.source || researchInboxDir)
+  const date = args.date || new Date().toISOString().slice(0, 10)
+  const topic = args.topic || kebab(path.basename(sourceDir))
+
+  if (!fs.existsSync(sourceDir)) throw new Error(`Source folder not found: ${sourceDir}`)
+
+  const files = listFiles(sourceDir)
+  const results = []
+
+  for (const file of files) {
+    results.push(await triageFile(file, sourceDir))
+  }
+
+  results.sort((a, b) => b.score - a.score)
+
+  const outputDir = path.join(ctx.paths.artefactsDir, 'research-triage')
+  fs.mkdirSync(outputDir, { recursive: true })
+  const reportPath = path.join(outputDir, `${date}-${topic}.md`)
+  const dataPath = path.join(outputDir, `${date}-${topic}.json`)
+
+  fs.writeFileSync(reportPath, buildReport({ sourceDir, date, topic, results }))
+  fs.writeFileSync(dataPath, `${JSON.stringify({ sourceDir, date, topic, results }, null, 2)}\n`)
+
+  reportToConsole(results)
+  console.log(`\nTriage report written to ${path.relative(ctx.root, reportPath)}`)
+  console.log(`Triage data written to ${path.relative(ctx.root, dataPath)}`)
+}
+
+async function triageFile (file, sourceDir) {
+  const rel = path.relative(sourceDir, file)
+  const extension = path.extname(file).toLowerCase()
+  const base = {
+    path: rel,
+    name: path.basename(file),
+    extension,
+    bytes: fs.statSync(file).size,
+    round: roundFrom(rel),
+    stage: stageFrom(rel),
+    importableToday: ['.pptx', '.pdf'].includes(extension),
+    score: 0
+  }
+
+  if (!supports(file)) {
+    return { ...base, status: MEDIA.has(extension) ? 'media (register as evidence, no text)' : 'unsupported', target: 'evidence artefact only' }
+  }
+
+  let extracted
+  try {
+    extracted = await extractArtefact(file)
+  } catch (error) {
+    return { ...base, status: `extract failed: ${error.message}`, target: 'needs manual conversion' }
+  }
+
+  const lines = extracted.sections.flatMap((section) => [...section.text, ...section.notes])
+  const blob = lines.join('\n')
+  // Spreadsheet rows repeat their column header on every cell so the structuring
+  // step keeps the field name. That is right for the draft and wrong for a volume
+  // measure, so headers are stripped back out before counting.
+  const measurable = blob.replace(/(^|\| )[^:|]{1,60}: /gm, '$1')
+  const words = measurable.trim() ? measurable.trim().split(/\s+/).length : 0
+  const counts = countSignals(blob)
+  const score = Math.round(
+    Object.entries(WEIGHTS).reduce((total, [key, weight]) => total + (counts[key] || 0) * weight, 0) +
+    Math.min(words, 4000) / 200
+  )
+
+  return {
+    ...base,
+    status: words < 30 ? 'low yield (likely image-only)' : 'text extracted',
+    sourceType: extracted.sourceType,
+    sections: extracted.sections.length,
+    words,
+    notesWords: extracted.sections.reduce((total, section) => total + section.notes.join(' ').split(/\s+/).filter(Boolean).length, 0),
+    signals: counts,
+    target: classify(rel, base.name, counts),
+    score
+  }
+}
+
+function countSignals (blob) {
+  const counts = {}
+  for (const [key, pattern] of Object.entries(SIGNALS)) {
+    counts[key] = (blob.match(pattern) || []).length
+  }
+  counts.participantsUnique = new Set(blob.match(SIGNALS.participant) || []).size
+  return counts
+}
+
+/** Maps a file to the Hippocampus records it could realistically become. */
+function classify (rel, name, signals) {
+  if (/detailed scenario map/i.test(name)) return 'scenarios (locationSearch) + participants'
+  if (/persona/i.test(rel) && signals.persona >= 3) return 'users + needs'
+  if (/insight|design action|tracker/i.test(name) && /\.xlsx$/i.test(name)) return 'insights + design-actions + relationships'
+  if (/transcript/i.test(name)) return 'evidence (quotes) + participants'
+  if (/urfinder|findings|playback|show and tell|summary of key/i.test(name)) return 'research-round + insights'
+  if (/interviewed list|participant log|user panel/i.test(rel)) return 'participants'
+  if (/assumption/i.test(name)) return 'assumptions'
+  if (signals.method >= 2 && signals.quote < 3) return 'method artefact (context only)'
+  if (signals.quote >= 5 || signals.insight >= 5) return 'insights + evidence'
+  if (/\.url$/i.test(name)) return 'evidence (external link)'
+  return 'low signal - review manually'
+}
+
+function roundFrom (rel) {
+  const match = rel.match(/Round\s*(\d+)/i)
+  return match ? `round-${match[1]}` : ''
+}
+
+/** The 01/02/03/04 folder convention is reliable provenance - use it. */
+function stageFrom (rel) {
+  const segment = rel.split(path.sep).find((part) => /^0\d[\s_-]/.test(part))
+  if (!segment) return ''
+  if (/plan/i.test(segment)) return 'planning'
+  if (/doing/i.test(segment)) return 'fieldwork'
+  if (/analys/i.test(segment)) return 'analysis'
+  if (/shar/i.test(segment)) return 'sharing'
+  if (/design action/i.test(segment)) return 'design actions'
+  return segment.trim()
+}
+
+function buildReport ({ sourceDir, date, topic, results }) {
+  const text = results.filter((r) => r.status === 'text extracted')
+  const tiers = {
+    'Tier 1 - promote first': text.filter((r) => r.score >= 120),
+    'Tier 2 - strong supporting material': text.filter((r) => r.score >= 40 && r.score < 120),
+    'Tier 3 - context only': text.filter((r) => r.score < 40)
+  }
+
+  const lines = [
+    `# Research corpus triage: ${topic}`,
+    '',
+    `- **Source:** ${sourceDir}`,
+    `- **Triaged:** ${date}`,
+    `- **Files scanned:** ${results.length}`,
+    `- **Text extracted:** ${text.length}`,
+    `- **Words available:** ${text.reduce((total, r) => total + r.words, 0).toLocaleString()}`,
+    `- **Importable by \`research:sync\` today:** ${results.filter((r) => r.importableToday).length}`,
+    '',
+    'This is a review pack, not an import. Nothing in `hippocampus/source/` has changed.',
+    '',
+    '## Coverage gap',
+    '',
+    '| Extension | Files | Words | Supported by research:sync |',
+    '| --- | ---: | ---: | --- |'
+  ]
+
+  const byExtension = new Map()
+  for (const result of results) {
+    const entry = byExtension.get(result.extension) || { files: 0, words: 0 }
+    entry.files += 1
+    entry.words += result.words || 0
+    byExtension.set(result.extension, entry)
+  }
+  for (const [extension, entry] of [...byExtension].sort((a, b) => b[1].files - a[1].files)) {
+    lines.push(`| \`${extension || '(none)'}\` | ${entry.files} | ${entry.words.toLocaleString()} | ${['.pptx', '.pdf'].includes(extension) ? 'yes' : 'no'} |`)
+  }
+
+  const narrative = text.filter((r) => ['.docx', '.pptx', '.pdf', '.txt', '.md'].includes(r.extension))
+  lines.push(
+    '',
+    `Word totals are skewed by operational spreadsheets and data extracts. Research narrative — documents, decks and reports — accounts for ${narrative.reduce((total, r) => total + r.words, 0).toLocaleString()} words across ${narrative.length} files, and that is the material insights come from.`
+  )
+
+  for (const [tier, items] of Object.entries(tiers)) {
+    lines.push('', `## ${tier} (${items.length})`, '')
+    if (!items.length) { lines.push('_None._'); continue }
+    lines.push('| Score | Words | Quotes | P# | Becomes | File |', '| ---: | ---: | ---: | ---: | --- | --- |')
+    for (const item of items.slice(0, 40)) {
+      lines.push(`| ${item.score} | ${item.words} | ${item.signals.quote} | ${item.signals.participantsUnique} | ${item.target} | \`${item.path}\` |`)
+    }
+    if (items.length > 40) lines.push(`| | | | | | _...and ${items.length - 40} more, see the JSON sidecar_ |`)
+  }
+
+  const problems = results.filter((r) => r.status !== 'text extracted')
+  lines.push('', `## Needs handling before import (${problems.length})`, '')
+  if (!problems.length) {
+    lines.push('_None._')
+  } else {
+    lines.push('| Issue | File |', '| --- | --- |')
+    for (const item of problems.slice(0, 60)) lines.push(`| ${item.status} | \`${item.path}\` |`)
+    if (problems.length > 60) lines.push(`| _...and ${problems.length - 60} more_ | |`)
+  }
+
+  return `${lines.join('\n')}\n`
+}
+
+function reportToConsole (results) {
+  const text = results.filter((r) => r.status === 'text extracted')
+  console.log(`Files scanned: ${results.length}`)
+  console.log(`Text extracted: ${text.length}`)
+  console.log(`Importable by research:sync today: ${results.filter((r) => r.importableToday).length}`)
+  console.log('\nTop contenders:')
+  for (const item of text.slice(0, 15)) {
+    console.log(`- ${String(item.score).padStart(5)}  ${item.target.padEnd(46)} ${item.path}`)
+  }
+}
+
+function listFiles (dir) {
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    if (entry.name.startsWith('.') || entry.name.startsWith('~$')) return []
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) return listFiles(full)
+    if (entry.isFile()) return [full]
+    return []
+  })
+}
+
+function parseArgs (args) {
+  const parsed = {}
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index]
+    if (!arg.startsWith('--')) continue
+    const [rawKey, value] = arg.slice(2).split('=', 2)
+    const key = rawKey.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase())
+    if (value !== undefined) parsed[key] = value
+    else if (args[index + 1] && !args[index + 1].startsWith('--')) { parsed[key] = args[index + 1]; index++ }
+    else parsed[key] = true
+  }
+  return parsed
+}
+
+function kebab (value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+}
+
+main().catch((error) => {
+  console.error(error.message)
+  process.exit(1)
+})

package/scripts/validate-knowledge.js

@@ -0,0 +1,49 @@
+const { createContextOrExit } = require('../lib/context')
+const { lintKnowledge } = require('../lib/lint-knowledge')
+
+const ctx = createContextOrExit()
+const strict = process.argv.includes('--strict')
+const quiet = process.argv.includes('--quiet')
+
+function main () {
+  let failed = false
+
+  for (const project of ctx.requireProjects()) {
+    const result = project.store.validateKnowledge()
+
+    if (!result.valid) {
+      failed = true
+      console.error(`${project.name}: knowledge data is invalid`)
+      for (const error of result.errors) console.error(`  error   ${error}`)
+      continue
+    }
+
+    const knowledge = project.store.getKnowledge()
+    const { warnings, infos } = lintKnowledge(knowledge)
+
+    for (const warning of knowledge.meta?.warnings || []) {
+      console.warn(`  warning ${warning}`)
+    }
+
+    console.log(`${project.name}: knowledge data is valid`)
+
+    for (const warning of warnings) console.warn(`  warning ${warning.message}`)
+    if (!quiet) {
+      for (const info of infos) console.log(`  info    ${info.message}`)
+    }
+
+    // Warnings are gaps, not breakage: a project three days old has plenty and
+    // should still pass. --strict is for the pipeline that has decided it is
+    // past that stage.
+    if (strict && warnings.length) failed = true
+  }
+
+  process.exit(failed ? 1 : 0)
+}
+
+try {
+  main()
+} catch (error) {
+  console.error(error.message)
+  process.exit(1)
+}

package/scripts/validate-skills.js

@@ -0,0 +1,247 @@
+const fs = require('fs')
+const path = require('path')
+const { z } = require('zod')
+
+const packagePaths = require('../lib/package-paths')
+
+// Skills live in the package; the paths inside them (reads:, and the
+// `.github/skills/<id>.skill.md` references in guidance) describe a HOST
+// project, because that is where an agent reads them. So the two roots are
+// separate: skills are validated from the package, their paths against a host.
+// --host defaults to the demo app, which is an ordinary consumer.
+const rootDir = packagePaths.packageRoot
+const skillsDir = packagePaths.skillsDir
+const catalogPath = path.join(skillsDir, 'skills.json')
+
+function readHostRoot () {
+  const flag = process.argv.indexOf('--host')
+  if (flag !== -1 && process.argv[flag + 1]) return path.resolve(process.argv[flag + 1])
+  return path.resolve(rootDir, '../../apps/demo')
+}
+
+const hostRoot = readHostRoot()
+const requiredBodyHeadings = [
+  '## Use when',
+  '## Workflow',
+  '## Guardrails',
+  '## Finish'
+]
+const kebabCasePattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+const catalogEntrySchema = z.object({
+  id: z.string().regex(kebabCasePattern),
+  title: z.string().min(1),
+  purpose: z.string().min(1),
+  file: z.string().regex(/^[^\0]+\.skill\.md$/),
+  owners: z.array(z.string().regex(kebabCasePattern)).min(1),
+  composes: z.array(z.string().regex(kebabCasePattern)).min(1).optional(),
+  legacyPrompt: z.string().regex(/^[^\0]+\.prompt\.md$/).optional(),
+  runs: z.array(z.string().min(1)).min(1),
+  outputs: z.array(z.string().min(1)).min(1),
+  acceptance: z.array(z.string().min(1)).min(1)
+}).strict()
+
+const catalogSchema = z.object({
+  $schema: z.string(),
+  version: z.number().int().positive(),
+  format: z.string().min(1),
+  root: z.string().min(1),
+  // agentsRoot named a directory of agent cards in the old repo layout. The
+  // package ships skills, not agents - a host names its own agents - so it is
+  // optional now rather than required.
+  agentsRoot: z.string().min(1).optional(),
+  skills: z.array(catalogEntrySchema).min(1)
+}).strict()
+
+const frontMatterSchema = z.object({
+  id: z.string().regex(kebabCasePattern),
+  title: z.string().min(1),
+  purpose: z.string().min(1),
+  owners: z.array(z.string().regex(kebabCasePattern)).min(1),
+  legacy_prompt: z.string().regex(/^[^\0]+\.prompt\.md$/).optional(),
+  composes: z.array(z.string().regex(kebabCasePattern)).min(1).optional(),
+  reads: z.array(z.string().min(1)).min(1),
+  edits: z.array(z.string().min(1)).min(1),
+  runs: z.array(z.string().min(1)).min(1),
+  outputs: z.array(z.string().min(1)).min(1),
+  guardrails: z.array(z.string().min(1)).min(1),
+  acceptance: z.array(z.string().min(1)).min(1)
+}).strict()
+
+function main () {
+  const catalog = catalogSchema.parse(readJson(catalogPath))
+  const errors = []
+  const skillFiles = fs.readdirSync(skillsDir)
+    .filter((name) => name.endsWith('.skill.md'))
+    .sort()
+  const catalogFiles = new Set(catalog.skills.map((skill) => skill.file))
+  const catalogIds = new Set(catalog.skills.map((skill) => skill.id))
+
+  for (const skillFile of skillFiles) {
+    if (!catalogFiles.has(skillFile)) {
+      errors.push(`Skill file is not listed in skills.json: ${path.join('.github/skills', skillFile)}`)
+    }
+  }
+
+  for (const entry of catalog.skills) {
+    const skillPath = path.join(skillsDir, entry.file)
+    if (!fs.existsSync(skillPath)) {
+      errors.push(`Catalog entry points to missing skill file: ${path.join('.github/skills', entry.file)}`)
+      continue
+    }
+
+    if (entry.legacyPrompt && !fs.existsSync(path.join(hostRoot, entry.legacyPrompt))) {
+      errors.push(`Catalog entry points to missing legacy prompt: ${entry.legacyPrompt}`)
+    }
+
+    for (const composedId of entry.composes || []) {
+      if (!catalogIds.has(composedId)) {
+        errors.push(`Catalog entry ${entry.id} composes unknown skill: ${composedId}`)
+      }
+    }
+
+    validateSkillFile(skillPath, entry, catalogIds, errors)
+  }
+
+  if (errors.length) {
+    console.error('Skill catalog is invalid')
+    for (const error of errors) {
+      console.error(`- ${error}`)
+    }
+    process.exit(1)
+  }
+
+  console.log(`Skill catalog is valid (${catalog.skills.length} skills)`)
+}
+
+function validateSkillFile (skillPath, catalogEntry, catalogIds, errors) {
+  let parsed
+
+  try {
+    parsed = parseFrontMatter(fs.readFileSync(skillPath, 'utf8'), skillPath)
+  } catch (error) {
+    errors.push(error.message)
+    return
+  }
+
+  const { frontMatter, body } = parsed
+
+  const result = frontMatterSchema.safeParse(frontMatter)
+
+  if (!result.success) {
+    for (const issue of result.error.issues) {
+      errors.push(`${path.relative(rootDir, skillPath)} front matter: ${issue.path.join('.')} ${issue.message}`.trim())
+    }
+    return
+  }
+
+  const metadata = result.data
+
+  if (metadata.legacy_prompt && !fs.existsSync(path.join(hostRoot, metadata.legacy_prompt))) {
+    errors.push(`${path.relative(rootDir, skillPath)} points to missing legacy prompt: ${metadata.legacy_prompt}`)
+  }
+
+  for (const composedId of metadata.composes || []) {
+    if (!catalogIds.has(composedId)) {
+      errors.push(`${path.relative(rootDir, skillPath)} composes unknown skill: ${composedId}`)
+    }
+  }
+
+  for (const heading of requiredBodyHeadings) {
+    if (!body.includes(heading)) {
+      errors.push(`${path.relative(rootDir, skillPath)} is missing body heading: ${heading}`)
+    }
+  }
+
+  // A skill's reads: are paths in the project an agent is working on, so they
+  // resolve against the host. A path inside the installed package resolves
+  // against the package itself - in a real host that is a directory under
+  // node_modules, and in this workspace it is the package we are validating.
+  const INSTALLED = 'node_modules/@hippo-digital/hippocampus/'
+  for (const readPath of metadata.reads) {
+    if (readPath.includes('[')) continue
+    if (readPath.startsWith(INSTALLED)) {
+      const withinPackage = readPath.slice(INSTALLED.length)
+      if (fs.existsSync(path.join(rootDir, withinPackage))) continue
+      errors.push(`${path.relative(rootDir, skillPath)} reads a path the package does not ship: ${withinPackage}`)
+      continue
+    }
+    if (fs.existsSync(path.join(hostRoot, readPath))) continue
+    if (fs.existsSync(path.join(rootDir, readPath))) continue
+    errors.push(`${path.relative(rootDir, skillPath)} reads missing path: ${readPath}`)
+  }
+
+  compareField('id', catalogEntry.id, metadata.id, skillPath, errors)
+  compareField('title', catalogEntry.title, metadata.title, skillPath, errors)
+  compareField('purpose', catalogEntry.purpose, metadata.purpose, skillPath, errors)
+  compareField('owners', catalogEntry.owners, metadata.owners, skillPath, errors)
+  compareField('runs', catalogEntry.runs, metadata.runs, skillPath, errors)
+  compareField('outputs', catalogEntry.outputs, metadata.outputs, skillPath, errors)
+  compareField('acceptance', catalogEntry.acceptance, metadata.acceptance, skillPath, errors)
+  compareField('legacy prompt', catalogEntry.legacyPrompt || null, metadata.legacy_prompt || null, skillPath, errors)
+  compareField('composes', catalogEntry.composes || [], metadata.composes || [], skillPath, errors)
+}
+
+function compareField (label, expected, actual, skillPath, errors) {
+  if (JSON.stringify(expected) !== JSON.stringify(actual)) {
+    errors.push(`${path.relative(rootDir, skillPath)} does not match catalog for ${label}`)
+  }
+}
+
+function readJson (filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'))
+}
+
+function parseFrontMatter (text, filePath) {
+  if (typeof text !== 'string') {
+    throw new Error(`${path.relative(rootDir, filePath)} could not be read as UTF-8 text`)
+  }
+
+  if (!text.startsWith('---\n')) {
+    throw new Error(`${path.relative(rootDir, filePath)} is missing opening front matter fence`)
+  }
+
+  const closingFenceIndex = text.indexOf('\n---\n', 4)
+  if (closingFenceIndex === -1) {
+    throw new Error(`${path.relative(rootDir, filePath)} is missing closing front matter fence`)
+  }
+
+  const frontMatterBlock = text.slice(4, closingFenceIndex)
+  const body = text.slice(closingFenceIndex + 5)
+  const frontMatter = {}
+  let currentKey = null
+
+  for (const line of frontMatterBlock.split('\n')) {
+    if (!line.trim()) continue
+
+    const keyMatch = line.match(/^([a-z_]+):(?:\s+(.*))?$/)
+    if (keyMatch) {
+      const [, key, value] = keyMatch
+      currentKey = key
+      if (value) {
+        frontMatter[key] = value.trim()
+      } else {
+        frontMatter[key] = []
+      }
+      continue
+    }
+
+    const itemMatch = line.match(/^\s*-\s+(.*)$/)
+    if (itemMatch && currentKey) {
+      if (!Array.isArray(frontMatter[currentKey])) {
+        throw new Error(`${path.relative(rootDir, filePath)} has a list item under non-list key: ${currentKey}`)
+      }
+      frontMatter[currentKey].push(itemMatch[1].trim())
+      continue
+    }
+
+    throw new Error(`${path.relative(rootDir, filePath)} has unsupported front matter line: ${line}`)
+  }
+
+  return { frontMatter, body }
+}
+
+main()
+
+
+

package/skills/COVERAGE-MATRIX.md

@@ -0,0 +1,39 @@
+# Prompt to Skill Coverage Matrix
+
+This matrix shows how the archived prompt pack now maps to the active skill catalog and role agents.
+
+## Direct prompt replacements
+
+| Archived prompt | Current skill | Preferred role agents | Coverage | Notes |
+| --- | --- | --- | --- | --- |
+| `generate-service-slice.prompt.md` | `generate-service-slice`, `deliver-service-slice` | `knowledge-builder`, `workflow-orchestrator` | direct + bundled | Low-level slice creation plus an end-to-end orchestration entrypoint. |
+| `add-user-needs.prompt.md` | `add-user-needs`, `deliver-service-slice` | `knowledge-builder`, `workflow-orchestrator` | direct + bundled | Kept as a focused source-edit skill and included in the service-slice bundle. |
+| `add-scenario.prompt.md` | `add-scenario`, `deliver-service-slice` | `knowledge-builder`, `workflow-orchestrator` | direct + bundled | Scenario authoring remains separate and is also part of service-slice delivery. |
+| `create-journey-from-scenario.prompt.md` | `create-journey-from-scenario`, `deliver-service-slice` | `knowledge-builder`, `workflow-orchestrator` | direct + bundled | Journey authoring stays focused but now has an orchestration parent. |
+| `add-prototype-screen.prompt.md` | `add-prototype-screen`, `deliver-service-slice` | `prototype-builder`, `workflow-orchestrator` | direct + bundled | Screen work remains usable standalone and inside slice delivery. |
+| `audit-knowledge-source.prompt.md` | `audit-knowledge-source`, `write-delivery-summary` | `knowledge-builder`, `workflow-orchestrator` | direct + adjacent | The audit stays direct; delivery summaries turn audit findings into handover artefacts. |
+| `hippocampus-structure-project-context.prompt.md` | `structure-project-context-draft`, `ingest-project-context` | `ingestion-curator`, `workflow-orchestrator` | direct + bundled | The original draft-fixing prompt now has a no-promote orchestration wrapper. |
+| `hippocampus-structure-research.prompt.md` | `structure-research-draft`, `ingest-research-round` | `ingestion-curator`, `workflow-orchestrator` | direct + bundled | Draft structuring stays focused and is bundled into the full research-ingestion path. |
+| `hippocampus-review-import-draft.prompt.md` | `review-research-import-draft`, `ingest-research-round` | `ingestion-curator`, `workflow-orchestrator` | direct + bundled | Review remains explicit and also acts as a gate inside the orchestration flow. |
+| `hippocampus-map-research-to-graph.prompt.md` | `map-research-to-graph`, `ingest-research-round` | `ingestion-curator`, `knowledge-builder`, `workflow-orchestrator` | direct + bundled | Graph-linking remains focused but is now part of the normal research-ingestion path. |
+
+## Workflow bundles added after migration
+
+| Workflow intent | Current orchestration skill | Preferred role agents | Uses |
+| --- | --- | --- | --- |
+| Research round from inbox to review-ready draft | `ingest-research-round` | `ingestion-curator`, `workflow-orchestrator` | `structure-research-draft`, `review-research-import-draft`, `map-research-to-graph` |
+| Project-context artefact from inbox to review-ready draft | `ingest-project-context` | `ingestion-curator`, `workflow-orchestrator` | `structure-project-context-draft` |
+| Service-slice delivery from source records to routes and summary | `deliver-service-slice` | `workflow-orchestrator`, `knowledge-builder`, `prototype-builder` | `generate-service-slice`, `add-user-needs`, `add-scenario`, `create-journey-from-scenario`, `add-prototype-screen`, `audit-knowledge-source` |
+| Handover note for multi-step agent work | `write-delivery-summary` | `workflow-orchestrator` | validation, smoke, and dry-run results plus changed-file summary |
+| Screenshot or route-note review pack for changed pages | `capture-route-review-pack` | `screenshot-runner`, `workflow-orchestrator` | smoke-tested route list plus dated manifest and captures/notes |
+| Accessibility note for changed pages | `record-accessibility-review` | `accessibility-tester`, `workflow-orchestrator` | smoke-tested route list plus blockers/improvements note |
+| Combined route review handover note | `write-route-review-summary` | `workflow-orchestrator`, `screenshot-runner`, `accessibility-tester` | screenshot pack, accessibility note, and delivery summary |
+
+## How to use this matrix
+
+- Start with the role agent in `.github/agents/`.
+- Use the direct skill when you need one focused change.
+- Use the orchestration skill when the work spans multiple low-level skills or handoff steps.
+- Treat `.github/legacy/prompts/` as historical context, not the active workflow source.
+
+