@hippo-digital/hippocampus 1.0.0-rc.1 → 1.0.0-rc.3

package/CHANGELOG.md

@@ -47,9 +47,23 @@ journeys and screens they justify, rendered as a viewer inside your prototype.
 
 ### Docs and skills
 
-- The 16 guides are served at `{basePath}/docs`, version-matched to the
+- The 13 guides are served at `{basePath}/docs`, version-matched to the
   installed package rather than copied into your repo.
-- `skills install` copies the 19 agent skills into `.github/skills` with content
-  hashes, so an upgrade can tell a stale copy from one your team has edited.
+- `skills install` copies the 21 skills into `.github/skills`, the six agents
+  into `.github/agents` and the instructions into `.github/instructions`, with
+  content hashes so an upgrade can tell a stale copy from one your team has
+  edited. They install together because every agent's preferred skills point
+  into `.github/skills` and every skill names its `owners` by agent, so either
+  half alone is a set of dangling references. `--no-agents` installs the skills
+  only.
+- Everything the agents and skills reference that is not a repo file is read
+  from the installed package, so those references are version-matched too.
+- `skills validate` checks both directions between skills and agents: a skill
+  owned by an agent that does not exist, an agent naming a skill that is not in
+  the catalog, and a skill in the catalog that no agent lists - the last of
+  which was true of four skills, installed but invisible to the runtime.
+- `init` scaffolds `artefacts/` with the READMEs carrying the naming
+  conventions, so the skills writing accessibility notes, screenshot review
+  packs and delivery summaries have somewhere to put them in a fresh host.
 - `init` reports research material in `hippocampus/source-artefacts/` rather
   than silently committing it; `--private-artefacts` gitignores it.

package/README.md

@@ -34,11 +34,18 @@ back out and leaves every byte of your knowledge base where it is.
 
 ```bash
 npx hippocampus doctor        # what is wired, what is not, and where it looked
-npx hippocampus skills install  # copy the agent skills into .github/skills
+npx hippocampus skills install  # copy the skills, agents and instructions in
 ```
 
-`skills install` records a hash of what it wrote, so a later upgrade can tell a
-stale copy from one your team has edited - the edited one is left alone.
+`skills install` writes three directories: `.github/skills` (the skill catalog),
+`.github/agents` (role wrappers naming who runs each skill) and
+`.github/instructions`. They install together because every agent's preferred
+skills point into `.github/skills`, and every skill names its `owners` by agent,
+so either half on its own is a set of dangling references. `--no-agents`
+installs the skills alone for a host whose agent runtime is not Copilot.
+
+It records a hash of what it wrote, so a later upgrade can tell a stale copy
+from one your team has edited - the edited one is left alone and named.
 
 ## Wiring it by hand
 
@@ -119,9 +126,11 @@ describe the version you have installed. Nothing is copied into your repo -
 a copied guide goes stale within a release, and the stale one is the copy people
 read, because it is the one sitting in their editor.
 
-`skills install` is the deliberate exception: an agent reads skills as repo
-files, so those are copied, with hashes so an upgrade can tell a stale copy from
-one your team has edited.
+`skills install` is the deliberate exception: an agent reads skills, agent
+definitions and instructions as repo files, so those are copied, with hashes so
+an upgrade can tell a stale copy from one your team has edited. Everything they
+reference that is not a repo file is read from the installed package, so those
+references cannot go stale either.
 
 ## Keeping research material out of the repo
 

package/agents/README.md

@@ -0,0 +1,32 @@
+# Agents
+
+These agent definitions are Copilot-friendly role wrappers for the portable skill catalog in `.github/skills/`.
+
+Use role agents to decide **who** should do the work. Use skill files to decide **how** the task should be run with repo docs, scripts and finish checks.
+
+Use the source model as the handoff contract between agents.
+
+## Agents
+
+- `knowledge-builder.md`
+- `prototype-builder.md`
+- `ingestion-curator.md`
+- `screenshot-runner.md`
+- `accessibility-tester.md`
+- `workflow-orchestrator.md`
+
+## Portable skills
+
+- See `.github/skills/README.md` for the catalog.
+- See `.github/skills/skills.json` for a machine-readable index that other agent runtimes can parse.
+- See `.github/skills/COVERAGE-MATRIX.md` for archived prompt to current skill mapping.
+
+## Common entrypoints
+
+- End-to-end research ingestion: `.github/skills/ingest-research-round.skill.md`
+- End-to-end project context ingestion: `.github/skills/ingest-project-context.skill.md`
+- End-to-end service slice delivery: `.github/skills/deliver-service-slice.skill.md`
+- Route review pack: `.github/skills/capture-route-review-pack.skill.md`
+- Accessibility review note: `.github/skills/record-accessibility-review.skill.md`
+- Route review handover: `.github/skills/write-route-review-summary.skill.md`
+

package/agents/accessibility-tester.md

@@ -0,0 +1,21 @@
+# accessibility-tester
+
+Reviews accessibility of changed prototype and Hippocampus pages.
+
+## Responsibilities
+
+- Check heading order, labels, link text and keyboard flow.
+- Check NHS component usage.
+- Store findings under `artefacts/accessibility/`.
+- Separate blockers from improvements.
+
+## Preferred Skills
+
+- `.github/skills/record-accessibility-review.skill.md`
+- `.github/skills/write-route-review-summary.skill.md`
+
+## Read First
+
+- `.github/instructions/nhs-frontend.instructions.md`
+- `node_modules/@hippo-digital/hippocampus/docs/custom-agents-usage.md`
+- `artefacts/accessibility/README.md`

package/agents/ingestion-curator.md

@@ -0,0 +1,29 @@
+# ingestion-curator
+
+Improves script-generated research and project-context drafts before human review and promotion.
+
+## Responsibilities
+
+- Work in `hippocampus/imports/research/` and `hippocampus/imports/project/`.
+- Combine extracted draft files with source-model docs and promotion scripts.
+- Keep reviewable metadata and extracted text intact.
+- Run dry-run promotion checks, not direct promotion.
+- Summarise changed draft fields, evidence gaps and remaining warnings.
+
+## Preferred Skills
+
+- `.github/skills/ingest-project-context.skill.md`
+- `.github/skills/ingest-research-round.skill.md`
+- `.github/skills/structure-project-context-draft.skill.md`
+- `.github/skills/structure-research-draft.skill.md`
+- `.github/skills/review-research-import-draft.skill.md`
+- `.github/skills/map-research-to-graph.skill.md`
+- `.github/skills/ingest-user-personas.skill.md`
+- `.github/skills/record-design-decision.skill.md`
+- `.github/skills/triage-research-corpus.skill.md`
+
+## Read First
+
+- `node_modules/@hippo-digital/hippocampus/docs/repeatable-research-round-ingestion.md`
+- `.github/instructions/knowledge-source.instructions.md`
+

package/agents/knowledge-builder.md

@@ -0,0 +1,29 @@
+# knowledge-builder
+
+Maintains the Hippocampus source model.
+
+## Responsibilities
+
+- Edit `hippocampus/source`.
+- Preserve linked source relationships.
+- Add assumptions when evidence is missing.
+- Run `npx hippocampus validate`.
+- Summarise records changed and unresolved assumptions.
+
+## Preferred Skills
+
+- `.github/skills/deliver-service-slice.skill.md`
+- `.github/skills/generate-service-slice.skill.md`
+- `.github/skills/add-user-needs.skill.md`
+- `.github/skills/add-scenario.skill.md`
+- `.github/skills/create-journey-from-scenario.skill.md`
+- `.github/skills/audit-knowledge-source.skill.md`
+- `.github/skills/ingest-user-personas.skill.md`
+- `.github/skills/record-design-decision.skill.md`
+- `.github/skills/onboard-team-member.skill.md`
+
+## Read First
+
+- `node_modules/@hippo-digital/hippocampus/docs/source-model.md`
+- `.github/instructions/knowledge-source.instructions.md`
+- `node_modules/@hippo-digital/hippocampus/lib/schema.js`

package/agents/prototype-builder.md

@@ -0,0 +1,23 @@
+# prototype-builder
+
+Builds NHS Prototype Kit routes and views from the source model.
+
+## Responsibilities
+
+- Edit `app/routes.js` and `app/views`.
+- Use source data rather than hard-coded service facts.
+- Reuse Hippocampus components where practical.
+- Keep NHS UK Frontend conventions.
+- Run `npx hippocampus validate` and `npx hippocampus doctor` when routes, views or screen routes change.
+
+## Preferred Skills
+
+- `.github/skills/deliver-service-slice.skill.md`
+- `.github/skills/add-prototype-screen.skill.md`
+- `.github/skills/audit-knowledge-source.skill.md`
+
+## Read First
+
+- `.github/instructions/nhs-prototype-kit.instructions.md`
+- `.github/instructions/nhs-frontend.instructions.md`
+- `app/routes.js`

package/agents/screenshot-runner.md

@@ -0,0 +1,22 @@
+# screenshot-runner
+
+Captures review evidence for prototype and Hippocampus routes.
+
+## Responsibilities
+
+- Start the prototype kit when needed.
+- Visit changed routes.
+- Capture screenshots or concise route notes.
+- Store outputs under `artefacts/screenshots/<YYYY-MM-DD>-<topic>/`.
+- Write a manifest describing routes captured and issues found.
+
+## Preferred Skills
+
+- `.github/skills/capture-route-review-pack.skill.md`
+- `.github/skills/write-route-review-summary.skill.md`
+
+## Read First
+
+- `node_modules/@hippo-digital/hippocampus/docs/custom-agents-usage.md`
+- `artefacts/screenshots/README.md`
+- `app/routes.js`

package/agents/workflow-orchestrator.md

@@ -0,0 +1,37 @@
+# workflow-orchestrator
+
+Coordinates larger Hippocampus delivery work.
+
+## Responsibilities
+
+- Break work into source, prototype, validation and review steps.
+- Use `knowledge-builder` before `prototype-builder` for service content.
+- Use `ingestion-curator` for script-generated research and project-context drafts.
+- Request screenshot and accessibility review for visible journeys.
+- Store delivery summaries under `artefacts/delivery-summaries/`.
+
+## Preferred Skills
+
+- `.github/skills/deliver-service-slice.skill.md`
+- `.github/skills/ingest-project-context.skill.md`
+- `.github/skills/ingest-research-round.skill.md`
+- `.github/skills/write-delivery-summary.skill.md`
+- `.github/skills/capture-route-review-pack.skill.md`
+- `.github/skills/record-accessibility-review.skill.md`
+- `.github/skills/write-route-review-summary.skill.md`
+- `.github/skills/generate-service-slice.skill.md`
+- `.github/skills/add-prototype-screen.skill.md`
+- `.github/skills/structure-project-context-draft.skill.md`
+- `.github/skills/structure-research-draft.skill.md`
+- `.github/skills/review-research-import-draft.skill.md`
+- `.github/skills/map-research-to-graph.skill.md`
+- `.github/skills/audit-knowledge-source.skill.md`
+- `.github/skills/triage-research-corpus.skill.md`
+- `.github/skills/onboard-team-member.skill.md`
+
+## Required Finish
+
+- Validation result.
+- Routes or artefacts reviewed.
+- Assumptions and unresolved risks.
+- Suggested next action.

package/bin/hippocampus.js

@@ -24,7 +24,7 @@ const COMMANDS = {
   'link insight-needs': 'link-insights-to-needs.js',
   'source index': 'index-source-artefacts.js',
   'source audit': 'audit-provenance.js',
-  'skills install': 'install-skills.js',
+  'skills install': 'install-skills.js', // also installs agents and instructions
   'skills validate': 'validate-skills.js'
 }
 
@@ -37,6 +37,7 @@ function usage () {
   for (const name of Object.keys(COMMANDS)) console.log(`  ${name}`)
   console.log('\nOptions:')
   console.log('  --root <dir>   the project to act on (default: nearest project above the cwd)')
+  console.log('  --no-agents    skills install: skills only, no agents or instructions')
   console.log('  --version      print the installed version')
   console.log('  --help         this message')
   console.log('\nEvery command resolves a project root the same way; run `hippocampus validate`')

package/docs/agent-roadmap.md

@@ -206,8 +206,8 @@ The repo now has enough agent-facing documentation that overlap will become a ma
 - Do not make skills promote drafts automatically.
 - Do not treat generated artefacts as canonical source data.
 - Do not reintroduce active prompt-first workflows.
-- Do not port NCRS clinical content or FHIR-heavy workflows unless Hippocampus actually needs them.
-- Do not add a huge NHS component reference unless repeated component mistakes justify it.
+- Do not port a host project's domain content or integration-heavy workflows unless Hippocampus actually needs them.
+- Do not add a huge component reference unless repeated component mistakes justify it.
 
 ## Recommended Next Commits
 

package/docs/design-actions-and-decisions.md

@@ -29,14 +29,14 @@ along; it was only ever used for five notes about the prototype spike.
 ## Why the rejected options matter
 
 The accepted option ends up in production, where anyone can see it. The rejected
-ones are the ones that get asked about eighteen months later — "why didn't NCRS
+ones are the ones that get asked about eighteen months later — "why didn't we
 just do the obvious thing?" — and by then the answer lives in one person's memory
 or in a meeting no one recorded. A rejected decision record with a `consequence`
 answers it.
 
 ## The workbook
 
-`hippocampus/templates/ncrs-insight-design-action-tracker.xlsx`, one copy per round.
+`hippocampus/templates/insight-design-action-tracker.xlsx`, one copy per round.
 Three sheets that reference each other by ID:
 
 | Sheet | One row per | Key columns |

package/docs/research-source-file-conventions.md

@@ -7,8 +7,9 @@ is a change to how a file is *authored or named*, not a change to the research
 itself. Each convention exists because the ingestion pipeline currently loses
 something real without it.
 
-The reference corpus behind this guidance is the NCRS user research drive:
-599 files, 2.3 million extractable words, rounds 4 to 16.
+This guidance was derived from a real user research drive of 599 files and
+2.3 million extractable words spanning thirteen rounds, so the conventions are
+the ones that survived contact with a messy corpus rather than a tidy example.
 
 ## The one thing that matters most
 

package/instructions/knowledge-source.instructions.md

@@ -0,0 +1,29 @@
+---
+applyTo: "hippocampus/source/**/*.json,app/lib/hippocampus/**/*.js,scripts/validate-knowledge.js,docs/source-model.md"
+---
+
+# Knowledge Source Instructions
+
+The Hippocampus knowledge base is source-model first. JSON records in `hippocampus/source` drive the visible artefacts and prototype traceability.
+
+## Editing Rules
+
+- Read `docs/source-model.md` before editing records.
+- Use structured JSON edits. Do not rely on fragile string manipulation.
+- Keep IDs lowercase kebab-case.
+- Preserve IDs unless a rename is explicitly requested.
+- Keep arrays ordered for human review: project context first, then journey/user-facing order.
+- Add assumptions instead of unsupported evidence claims.
+- Use fictional and synthetic content only.
+
+## Required Checks
+
+Run:
+
+```bash
+npm run validate:knowledge
+```
+
+Validation must pass before the work is considered done.
+
+If validation fails, fix the source relationships or schema issue before changing views.

package/instructions/nhs-frontend.instructions.md

@@ -0,0 +1,22 @@
+---
+applyTo: "app/views/**/*.html,app/views/**/*.njk,app/assets/sass/**/*.scss"
+---
+
+# NHS Frontend Instructions
+
+Use NHS UK Frontend conventions.
+
+## Interface Rules
+
+- Use NHS component classes before custom styling.
+- Keep headings hierarchical and page-specific.
+- Use summary lists, cards, tables and tags only when they improve scanning.
+- Use clear link text that makes sense out of context.
+- Keep prototype screens accessible and keyboard-friendly.
+- Avoid decorative UI that does not help the service-design task.
+
+## Content Rules
+
+- Write plain, task-focused NHS-style content.
+- Keep clinical and service details synthetic unless explicitly provided as approved source material.
+- Avoid overclaiming certainty. Represent unknowns as assumptions or risks.

package/instructions/nhs-prototype-kit.instructions.md

@@ -0,0 +1,30 @@
+---
+applyTo: "app/routes.js,app/views/**/*.html,app/views/**/*.njk,app/config.js"
+---
+
+# NHS Prototype Kit Instructions
+
+Use the existing NHS Prototype Kit structure.
+
+## Routes
+
+- Keep route handlers in `app/routes.js` concise.
+- Load knowledge through `app/lib/hippocampus/load-knowledge.js`.
+- Return useful not-found states instead of crashing on missing IDs.
+
+## Views
+
+- Use Nunjucks and NHS UK Frontend classes.
+- Reuse components from `app/views/hippocampus/components` when patterns repeat.
+- Keep page content driven by source data wherever possible.
+- Do not put service facts only in Nunjucks if they belong in `hippocampus/source`.
+
+## Checks
+
+After route or view changes, run:
+
+```bash
+npm run validate:knowledge
+```
+
+When practical, start the kit and smoke-test affected routes.

package/lib/docs.js

@@ -15,8 +15,7 @@ const packagePaths = require('./package-paths')
 // a stale copy from an edited one.
 
 const TITLE_OVERRIDES = {
-  'hippocampus-for-designers-and-researchers': 'Hippocampus for designers and researchers',
-  'gp-connect-real-data-to-production': 'GP Connect: real data to production'
+  'hippocampus-for-designers-and-researchers': 'Hippocampus for designers and researchers'
 }
 
 function slugOf (filename) {

package/lib/package-paths.js

@@ -28,5 +28,7 @@ module.exports = {
   scriptsDir: path.join(packageRoot, 'scripts'),
   templatesDir: path.join(packageRoot, 'templates'),
   skillsDir: path.join(packageRoot, 'skills'),
+  agentsDir: path.join(packageRoot, 'agents'),
+  instructionsDir: path.join(packageRoot, 'instructions'),
   docsDir: path.join(packageRoot, 'docs')
 }

package/lib/schema.js

@@ -172,7 +172,7 @@ const ScreenSchema = z.object({
   purpose: nonEmptyString,
   needIds: z.array(id).min(1),
   components: stringList,
-  // A screen in the real NCRS prototype rather than in this viewer. The
+  // A screen in the host project rather than in this viewer. The
   // knowledge base models the service, not only the screens this repo happens
   // to render, so the route smoke test skips these instead of failing on them.
   external: z.boolean().optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hippo-digital/hippocampus",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0-rc.3",
   "description": "A design-knowledge base for NHS Prototype Kit projects: research, insights, needs, journeys and screens, traceable end to end.",
   "license": "MIT",
   "main": "index.js",
@@ -15,6 +15,8 @@
     "assets",
     "scripts",
     "skills",
+    "agents",
+    "instructions",
     "templates",
     "docs",
     "README.md",

package/scripts/import-design-actions.js

@@ -179,7 +179,7 @@ function main () {
 
 function rows (workbook, sheetName) {
   if (!workbook.sheetFiles.has(sheetName)) {
-    throw new Error(`The workbook has no "${sheetName}" sheet. It has: ${[...workbook.sheetFiles.keys()].join(', ')}. Start from hippocampus/templates/ncrs-insight-design-action-tracker.xlsx.`)
+    throw new Error(`The workbook has no "${sheetName}" sheet. It has: ${[...workbook.sheetFiles.keys()].join(', ')}. Start from the blank tracker that ships with the package: node_modules/@hippo-digital/hippocampus/templates/insight-design-action-tracker.xlsx`)
   }
   const grid = readSheetGrid(workbook, sheetName)
   const header = grid.find((r) => r && r.some(Boolean)) || []

package/scripts/init.js

@@ -4,6 +4,7 @@ const path = require('path')
 const { resolveRoot, CONFIG_FILENAME } = require('../lib/resolve-root')
 const { CURRENT_SCHEMA_VERSION } = require('../lib/schema-version')
 const hostEdit = require('../lib/host-edit')
+const packagePaths = require('../lib/package-paths')
 
 // Set a host project up to use Hippocampus: write the config and an empty
 // knowledge base, then make the two host edits - both inside marked blocks, both
@@ -37,6 +38,7 @@ function main () {
 
   planConfig(root)
   planKnowledgeBase(root)
+  planArtefacts(root, artefactsDir(root))
   planArtefactGovernance(root)
   if (!noWire) {
     planHostEdit(path.join(root, 'app/routes.js'), wireRoutes)
@@ -75,6 +77,54 @@ function planConfig (root) {
   }, null, 2) + '\n'))
 }
 
+// Several skills write into `artefacts/` - accessibility notes, screenshot
+// review packs, delivery summaries - and two agents name the READMEs there as
+// required reading. A fresh host had none of it, so those skills had nowhere to
+// put their output and the agents pointed at files that did not exist. The
+// READMEs carry the naming conventions, which is the part that stops every
+// project inventing its own.
+//
+// Each file is written only when absent: these are the host's to edit.
+// The host may have renamed it in the config; honour that rather than assuming.
+function artefactsDir (root) {
+  const configPath = path.join(root, CONFIG_FILENAME)
+  if (!fs.existsSync(configPath)) return 'artefacts'
+  try {
+    return JSON.parse(fs.readFileSync(configPath, 'utf8')).artefactsDir || 'artefacts'
+  } catch {
+    return 'artefacts'
+  }
+}
+
+function planArtefacts (root, artefactsDir) {
+  const from = path.join(packagePaths.templatesDir, 'artefacts')
+  const to = path.join(root, artefactsDir)
+  const missing = []
+
+  for (const rel of listTemplateFiles(from)) {
+    if (!fs.existsSync(path.join(to, rel))) missing.push(rel)
+  }
+  if (!missing.length) return
+
+  plan(`${artefactsDir}/ and ${missing.length} README${missing.length === 1 ? '' : 's'}`, () => {
+    for (const rel of missing) {
+      const target = path.join(to, rel)
+      fs.mkdirSync(path.dirname(target), { recursive: true })
+      fs.copyFileSync(path.join(from, rel), target)
+    }
+  })
+}
+
+function listTemplateFiles (dir, prefix = '') {
+  const found = []
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const rel = prefix ? path.posix.join(prefix, entry.name) : entry.name
+    if (entry.isDirectory()) found.push(...listTemplateFiles(path.join(dir, entry.name), rel))
+    else found.push(rel)
+  }
+  return found
+}
+
 function planKnowledgeBase (root) {
   const sourceDir = path.join(root, 'hippocampus/source')
   const projectPath = path.join(sourceDir, 'project.json')
@@ -87,7 +137,7 @@ function planKnowledgeBase (root) {
   const id = kebab(dirName) || 'prototype'
   const name = dirName
   plan('hippocampus/source/project.json and an empty knowledge base', () => {
-    for (const dir of ['source', 'inbox/project', 'inbox/research', 'imports/project', 'imports/research', 'manifests']) {
+    for (const dir of ['source', 'inbox/personas', 'inbox/project', 'inbox/research', 'imports/project', 'imports/research', 'manifests']) {
       fs.mkdirSync(path.join(root, 'hippocampus', dir), { recursive: true })
     }
     fs.writeFileSync(projectPath, JSON.stringify({