@hippo-digital/hippocampus 1.0.0-rc.1

package/skills/README.md

@@ -0,0 +1,77 @@
+# Skill Catalog
+
+This directory converts the legacy prompt pack into portable agent skills.
+
+This README is the catalog entry point and discovery guide. If it ever disagrees with `.github/skills/SKILL-FORMAT.md`, the format document wins.
+
+## Format
+
+- Plain Markdown skill cards with YAML front matter
+- One machine-readable index in `skills.json`
+- One JSON Schema in `skills.schema.json`
+- Stable references to repo docs, scripts and output locations
+- Canonical metadata rules in `SKILL-FORMAT.md`
+
+This keeps the skills usable in Copilot via `.github/agents/*.md`, but also easy for other agents to consume later without a product-specific schema.
+
+## How to use
+
+- Pick a role agent from `.github/agents/` for Copilot-first workflows.
+- Or start from `skills.json` if another agent runtime needs machine-readable discovery first.
+- Follow the linked skill card in this directory for the exact task recipe.
+- Use focused skills for single tasks and orchestration skills for multi-step workflows.
+- Prefer these skills over the legacy prompt text in `.github/legacy/prompts/`.
+
+## Validation
+
+Run:
+
+```bash
+npx hippocampus skills validate
+```
+
+after changing any `*.skill.md`, `skills.json`, `skills.schema.json`, or example files.
+
+## Skill map
+
+- `generate-service-slice.skill.md` ← `generate-service-slice.prompt.md`
+- `add-user-needs.skill.md` ← `add-user-needs.prompt.md`
+- `add-scenario.skill.md` ← `add-scenario.prompt.md`
+- `create-journey-from-scenario.skill.md` ← `create-journey-from-scenario.prompt.md`
+- `add-prototype-screen.skill.md` ← `add-prototype-screen.prompt.md`
+- `audit-knowledge-source.skill.md` ← `audit-knowledge-source.prompt.md`
+- `structure-project-context-draft.skill.md` ← `hippocampus-structure-project-context.prompt.md`
+- `structure-research-draft.skill.md` ← `hippocampus-structure-research.prompt.md`
+- `review-research-import-draft.skill.md` ← `hippocampus-review-import-draft.prompt.md`
+- `map-research-to-graph.skill.md` ← `hippocampus-map-research-to-graph.prompt.md`
+
+## Orchestration skills
+
+- `ingest-research-round.skill.md` - chains research import draft structuring, review, and graph-linking without promotion
+- `ingest-project-context.skill.md` - chains project-context draft structuring and dry-run validation without promotion
+- `deliver-service-slice.skill.md` - chains source-model authoring, optional prototype work, audit, and delivery-summary handoff
+- `write-delivery-summary.skill.md` - records what changed, what was run, and what still needs follow-up
+
+## Review workflow skills
+
+- `capture-route-review-pack.skill.md` - creates a dated screenshot or route-notes review pack after smoke testing
+- `record-accessibility-review.skill.md` - writes dated accessibility notes with blockers and improvements
+- `write-route-review-summary.skill.md` - links smoke-test, screenshot, and accessibility artefacts into one handover note
+
+## Coverage matrix
+
+- See `COVERAGE-MATRIX.md` for archived prompt -> current skill -> role agent mapping.
+
+## Examples
+
+- `examples/non-copilot-research-ingestion.md`
+- `examples/non-copilot-service-slice.md`
+
+## Shared rules
+
+- Treat `hippocampus/source/` as the source of truth.
+- Do not invent evidence; add assumptions or report gaps instead.
+- Keep IDs lowercase kebab-case and dates `YYYY-MM-DD`.
+- Run the command named in the skill before finishing.
+- Use `artefacts/` for generated review outputs, not canonical source data.
+

package/skills/SKILL-FORMAT.md

@@ -0,0 +1,100 @@
+# Portable Skill Format
+
+This repo keeps skills in a simple, tool-agnostic format so they can work well in Copilot now and remain easy to reuse in other agents later.
+
+## Files
+
+Each skill has:
+
+- a Markdown file: `<skill-id>.skill.md`
+- YAML front matter for machine-readable metadata
+- a short task recipe in Markdown for humans and agents
+
+The catalog also includes:
+
+- `skills.json` as a machine-readable index
+- `skills.schema.json` as the validation contract for that index
+- `README.md` as the human entry point
+
+## Front matter fields
+
+Use these keys on every `*.skill.md` file:
+
+- `id` - stable lowercase kebab-case skill ID
+- `title` - short human-readable name
+- `purpose` - one-sentence statement of the task outcome
+- `owners` - preferred role agents from `.github/agents/`
+- `legacy_prompt` - optional source prompt retained for backwards compatibility
+- `composes` - optional list of lower-level skill IDs used by an orchestration skill
+- `reads` - files or directories to inspect first
+- `edits` - likely files or directories to change
+- `runs` - commands that complete or verify the task
+- `outputs` - files, artefacts or outcomes a successful run should leave behind
+- `guardrails` - task-specific safety rules that must stay visible to any agent runtime
+- `acceptance` - stop conditions that must be true before the task is considered done
+
+Required on every skill card:
+
+- `id`
+- `title`
+- `purpose`
+- `owners`
+- `reads`
+- `edits`
+- `runs`
+- `outputs`
+- `guardrails`
+- `acceptance`
+
+Optional:
+
+- `legacy_prompt`
+- `composes`
+
+## Body shape
+
+Keep the body concise and structured:
+
+1. `Use when`
+2. `Workflow`
+3. `Guardrails`
+4. `Finish`
+
+This mirrors the repo's established prompt shape in `docs/prompt-architecture-guardrails.md` while avoiding vendor-specific syntax.
+
+For higher-level workflows, keep the body explicit about which lower-level skills it chains and where human review still acts as a gate.
+
+## Copilot integration
+
+- `.github/copilot-instructions.md` provides ambient repo rules.
+- `.github/agents/*.md` acts as Copilot-friendly role wrappers.
+- Role agents should point to one or more files in `.github/skills/`.
+
+## Validation
+
+Run this after changing skill files, the catalog, or example files:
+
+```bash
+npx hippocampus skills validate
+```
+
+This checks:
+
+- `skills.json` syntax and catalog shape
+- required front matter on every `*.skill.md`
+- consistency between catalog entries and skill front matter
+- required body headings
+- legacy prompt references and composed skill IDs
+
+## Portability rules
+
+- Prefer plain Markdown and JSON over proprietary agent manifests.
+- Keep commands copyable and repo-relative.
+- Reference real scripts and docs such as `scripts/validate-knowledge.js`, `docs/source-model.md`, and `docs/repeatable-research-round-ingestion.md`.
+- Keep legacy prompt files until external agent runtimes have moved to the skill catalog.
+
+## Non-Copilot examples
+
+- `examples/non-copilot-research-ingestion.md`
+- `examples/non-copilot-service-slice.md`
+

package/skills/add-prototype-screen.skill.md

@@ -0,0 +1,54 @@
+---
+id: add-prototype-screen
+title: Add prototype screen
+purpose: Add a source-backed prototype screen with matching route and view.
+owners:
+  - prototype-builder
+  - workflow-orchestrator
+reads:
+  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
+  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
+  - hippocampus/source/screens.json
+  - hippocampus/source/needs.json
+  - app/routes.js
+  - app/views/
+edits:
+  - hippocampus/source/screens.json
+  - app/routes.js
+  - app/views/
+runs:
+  - npx hippocampus validate
+  - npx hippocampus doctor
+outputs:
+  - Updated screen record in hippocampus/source/screens.json
+  - Matching route and Nunjucks view
+guardrails:
+  - Use fictional data only.
+  - Keep service facts in source JSON rather than only in the template.
+  - Reuse existing Hippocampus components before adding one-off markup.
+acceptance:
+  - The screen has a valid lowercase route and linked need IDs.
+  - Route and template exist and match the source record.
+  - npx hippocampus validate and npx hippocampus doctor pass.
+---
+
+# Add prototype screen
+
+## Use when
+- A new screen needs to exist both as source data and as a working route/view.
+
+## Workflow
+1. Add the screen record to `hippocampus/source/screens.json` with a lowercase kebab-case `id`, absolute lowercase `route`, `title`, `purpose`, linked `needIds`, and NHS component names.
+2. Add the matching Express route in `app/routes.js` and keep the handler thin.
+3. Add the Nunjucks view under `app/views/` using NHS UK Frontend classes.
+4. If the request includes journey coverage, link the screen from the relevant journey step `screenIds`.
+
+## Guardrails
+- Use fictional data only.
+- Keep service facts in source JSON rather than only in the template.
+- Reuse existing Hippocampus components before adding one-off markup.
+
+## Finish
+- Run `npx hippocampus validate` and `npx hippocampus doctor`.
+- Report the screen record, route, view file, linked needs, and validation/smoke results.
+

package/skills/add-scenario.skill.md

@@ -0,0 +1,47 @@
+---
+id: add-scenario
+title: Add scenario
+purpose: Add a concrete scenario that links existing users and needs to journey work.
+owners:
+  - knowledge-builder
+  - workflow-orchestrator
+reads:
+  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
+  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
+  - hippocampus/source/users.json
+  - hippocampus/source/needs.json
+  - hippocampus/source/scenarios.json
+edits:
+  - hippocampus/source/scenarios.json
+runs:
+  - npx hippocampus validate
+outputs:
+  - Updated scenario records in hippocampus/source/scenarios.json
+  - A scenario ready to drive journey authoring
+guardrails:
+  - Avoid vague scenarios like "user uses the service".
+  - Keep the scenario grounded in current source evidence and assumptions.
+acceptance:
+  - The scenario links to existing user and need IDs.
+  - Trigger, context, and edge cases are specific enough to generate a journey.
+  - npx hippocampus validate passes.
+---
+
+# Add scenario
+
+## Use when
+- Existing users and needs need a concrete trigger/context that can drive a journey.
+
+## Workflow
+1. Pick an existing `userId` and linked `needIds`.
+2. Add a scenario with `title`, `trigger`, `context`, `riskLevel`, `happyPath`, and `edgeCases`.
+3. Make it specific enough to generate journey steps and screens: what starts the work, what the user is deciding, what data matters, and what can go wrong.
+
+## Guardrails
+- Avoid vague scenarios like "user uses the service".
+- Keep the scenario grounded in current source evidence and assumptions.
+
+## Finish
+- Run `npx hippocampus validate`.
+- Report the scenario created, linked needs, unresolved assumptions, and validation result.
+

package/skills/add-user-needs.skill.md

@@ -0,0 +1,51 @@
+---
+id: add-user-needs
+title: Add user needs
+purpose: Add or sharpen traceable need records for an existing user group.
+owners:
+  - knowledge-builder
+  - workflow-orchestrator
+reads:
+  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
+  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
+  - hippocampus/source/users.json
+  - hippocampus/source/needs.json
+  - hippocampus/source/evidence.json
+  - hippocampus/source/assumptions.json
+edits:
+  - hippocampus/source/needs.json
+  - hippocampus/source/assumptions.json
+runs:
+  - npx hippocampus validate
+outputs:
+  - Updated need records in hippocampus/source/needs.json
+  - Assumptions for unsupported needs when required
+guardrails:
+  - Do not invent evidence or rename existing IDs casually.
+  - Keep need statements short enough to display cleanly in Hippocampus lists and blueprint views.
+acceptance:
+  - Each changed need has a valid userId, priority, and supporting evidence or assumption gap.
+  - Need text remains concise enough for lists and blueprint views.
+  - npx hippocampus validate passes.
+---
+
+# Add user needs
+
+## Use when
+- A user group already exists and its needs need to be added or sharpened.
+- Evidence exists, but traceable need records are missing or weak.
+
+## Workflow
+1. Confirm the target `userId` already exists in `hippocampus/source/users.json`.
+2. Add or revise need records with a lowercase kebab-case `id`, a single clear statement, a `priority`, and at least one `evidenceId`.
+3. Reuse existing evidence where it really supports the need.
+4. If the direction is plausible but not evidenced, add an assumption and call out the evidence gap.
+
+## Guardrails
+- Do not invent evidence or rename existing IDs casually.
+- Keep need statements short enough to display cleanly in Hippocampus lists and blueprint views.
+
+## Finish
+- Run `npx hippocampus validate`.
+- Report needs added or changed, evidence used, assumptions added, and validation result.
+

package/skills/audit-knowledge-source.skill.md

@@ -0,0 +1,47 @@
+---
+id: audit-knowledge-source
+title: Audit knowledge source
+purpose: Review traceability, route coverage, and evidence quality before handover.
+owners:
+  - knowledge-builder
+  - workflow-orchestrator
+reads:
+  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
+  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
+  - hippocampus/source/
+  - app/routes.js
+  - app/views/
+edits:
+  - none by default
+runs:
+  - npx hippocampus validate
+  - npx hippocampus doctor
+outputs:
+  - Audit findings for blockers, traceability gaps, and model risks
+  - Optional follow-up recommendations without rewriting records
+guardrails:
+  - Do not rewrite records during an audit unless asked.
+  - Treat validation failures and missing routes as blockers ahead of content quality comments.
+acceptance:
+  - Validation and route coverage are checked first.
+  - Findings distinguish blockers from model-quality improvements.
+  - The output stays review-first unless fixes are requested.
+---
+
+# Audit knowledge source
+
+## Use when
+- You need a review of traceability, route coverage, and evidence quality before handover or design review.
+
+## Workflow
+1. Run validation first.
+2. Check for weak evidence links, scenarios without usable edge cases, shallow journey lanes, missing screens, orphaned screens, stale decisions, unsupported assumptions, and route drift between source data and implemented pages.
+3. Keep the output review-first unless the user explicitly asks for fixes.
+
+## Guardrails
+- Do not rewrite records during an audit unless asked.
+- Treat validation failures and missing routes as blockers ahead of content quality comments.
+
+## Finish
+- Report findings in this order: blockers, traceability gaps, evidence/assumption risks, model quality issues, suggested next edits.
+

package/skills/capture-route-review-pack.skill.md

@@ -0,0 +1,52 @@
+---
+id: capture-route-review-pack
+title: Capture route review pack
+purpose: Create a dated screenshot or notes pack for changed routes after smoke testing.
+owners:
+  - screenshot-runner
+  - workflow-orchestrator
+reads:
+  - node_modules/@hippo-digital/hippocampus/docs/agent-workflow.md
+  - node_modules/@hippo-digital/hippocampus/docs/custom-agents-usage.md
+  - node_modules/@hippo-digital/hippocampus/docs/hippocampus-technical.md
+  - artefacts/screenshots/README.md
+  - app/routes.js
+edits:
+  - artefacts/screenshots/[yyyy-mm-dd-topic]/manifest.md
+runs:
+  - npx hippocampus doctor
+outputs:
+  - Route review pack under artefacts/screenshots/<date-topic>/
+  - Manifest with routes reviewed and issues found
+guardrails:
+  - Keep all visible data fictional.
+  - Say explicitly when the pack is notes-only rather than image-backed.
+  - Keep route slugs and filenames aligned so the manifest is easy to audit.
+acceptance:
+  - The smoke-test result is captured before handover.
+  - The manifest says which routes have screenshots versus notes only.
+  - The review-pack path and issues are reported.
+---
+
+# Capture route review pack
+
+## Use when
+- A visible route change needs review evidence for handover, design review, or comparison.
+- You need one dated place for screenshots, route notes, and issues found.
+
+## Workflow
+1. Build the route list from the request, changed screen routes, affected Hippocampus pages, or the smoke-test surface.
+2. Run `npx hippocampus doctor` first when route or view changes are in scope.
+3. Start the prototype manually if interactive checks are needed, then visit the agreed routes.
+4. Save screenshots when capture is available. If not, record concise per-route notes in the manifest instead of pretending screenshots exist.
+5. Write `artefacts/screenshots/<YYYY-MM-DD>-<topic>/manifest.md` with the routes reviewed, whether each route had an image or notes, and the issues found.
+
+## Guardrails
+- Keep all visible data fictional.
+- Say explicitly when the pack is notes-only rather than image-backed.
+- Keep route slugs and filenames aligned so the manifest is easy to audit.
+
+## Finish
+- Run `npx hippocampus doctor`.
+- Report the review-pack path, routes covered, missing captures, and the issues or follow-up checks found.
+

package/skills/create-journey-from-scenario.skill.md

@@ -0,0 +1,50 @@
+---
+id: create-journey-from-scenario
+title: Create journey from scenario
+purpose: Turn an existing scenario into a blueprint-ready journey.
+owners:
+  - knowledge-builder
+  - workflow-orchestrator
+reads:
+  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
+  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
+  - hippocampus/source/scenarios.json
+  - hippocampus/source/journeys.json
+  - hippocampus/source/screens.json
+  - hippocampus/source/evidence.json
+  - hippocampus/source/decisions.json
+edits:
+  - hippocampus/source/journeys.json
+runs:
+  - npx hippocampus validate
+outputs:
+  - Updated journey records in hippocampus/source/journeys.json
+  - Journey steps with lane-ready content and references
+guardrails:
+  - Do not put all detail in userAction; the blueprint views render lane content separately.
+  - Keep screenIds, evidenceIds, and decisionIds aligned with existing source records.
+acceptance:
+  - The journey links to an existing scenario and has 4 to 7 useful steps.
+  - Step lanes use needIds, screenIds, evidenceIds, and decisionIds consistently.
+  - npx hippocampus validate passes.
+---
+
+# Create journey from scenario
+
+## Use when
+- A scenario exists and needs a blueprint-ready journey.
+
+## Workflow
+1. Confirm the `scenarioId` exists.
+2. Add or revise a journey with `title`, `description`, `entryPoint`, `exitPoint`, and 4 to 7 steps.
+3. For each step, fill the real blueprint lanes used by `buildBlueprintViewModel()`: `userAction`, `frontstage`, `backstage`, `supportProcesses`, `dataDependencies`, `securityAndGovernance`, `painPoints`, `exceptionHandling`, `needIds`, `screenIds`, `evidenceIds`, and `decisionIds`.
+4. Flag missing screens or evidence instead of hiding gaps in free text.
+
+## Guardrails
+- Do not put all detail in `userAction`; the blueprint views render lane content separately.
+- Keep `screenIds`, `evidenceIds`, and `decisionIds` aligned with existing source records.
+
+## Finish
+- Run `npx hippocampus validate`.
+- Report the journey created or updated, missing screens, evidence gaps, and validation result.
+

package/skills/deliver-service-slice.skill.md

@@ -0,0 +1,65 @@
+---
+id: deliver-service-slice
+title: Deliver service slice
+purpose: Deliver an end-to-end fictional service slice across source data, optional prototype routes/views, audit, and handover.
+owners:
+  - workflow-orchestrator
+  - knowledge-builder
+  - prototype-builder
+composes:
+  - generate-service-slice
+  - add-user-needs
+  - add-scenario
+  - create-journey-from-scenario
+  - add-prototype-screen
+  - audit-knowledge-source
+reads:
+  - node_modules/@hippo-digital/hippocampus/docs/agent-workflow.md
+  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
+  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
+  - app/routes.js
+  - hippocampus/source/
+  - app/views/
+edits:
+  - hippocampus/source/
+  - app/routes.js
+  - app/views/
+  - artefacts/delivery-summaries/
+runs:
+  - npx hippocampus validate
+  - npx hippocampus doctor
+outputs:
+  - Updated source records and optional route/view files
+  - Delivery summary under artefacts
+guardrails:
+  - Keep hippocampus/source/ as the source of truth and add assumptions instead of unsupported evidence.
+  - Keep routes thin and use NHS UK Frontend conventions in views.
+  - Keep all service data fictional.
+acceptance:
+  - Source records are created in dependency order and stay linked.
+  - Any visible route work passes smoke testing.
+  - Validation, smoke-test, and handover summary are reported.
+---
+
+# Deliver service slice
+
+## Use when
+- A new or revised service area needs an end-to-end Hippocampus slice across source data, routes, views, and review notes.
+- You want a single orchestration recipe rather than manually chaining low-level source and prototype skills.
+
+## Workflow
+1. Read the existing source collections and decide whether the work is new-slice creation or an extension of an existing slice.
+2. Use `generate-service-slice`, `add-user-needs`, `add-scenario`, and `create-journey-from-scenario` to shape the linked source records in dependency order.
+3. Use `add-prototype-screen` only when the source model needs a visible route or the existing renderer cannot show the new slice clearly.
+4. Run `audit-knowledge-source` before handover to catch weak evidence links, missing screens, or route drift.
+5. Write a delivery summary under `artefacts/delivery-summaries/` capturing records changed, routes/views changed, validation, assumptions, and follow-up work.
+
+## Guardrails
+- Keep `hippocampus/source/` as the source of truth and add assumptions instead of unsupported evidence.
+- Keep routes thin and use NHS UK Frontend conventions in views.
+- Keep all service data fictional.
+
+## Finish
+- Run `npx hippocampus validate` and `npx hippocampus doctor`.
+- Report the source records, routes, views, delivery-summary path, validation result, smoke-test result, and unresolved risks.
+

package/skills/examples/README.md

@@ -0,0 +1,15 @@
+# Skill examples
+
+These worked examples show how a non-Copilot agent can consume the portable skill catalog.
+
+Files:
+
+- `non-copilot-research-ingestion.md`
+- `non-copilot-service-slice.md`
+
+Use them alongside:
+
+- `.github/skills/skills.json` for discovery
+- `.github/skills/SKILL-FORMAT.md` for the metadata contract
+- the referenced `*.skill.md` files for the exact workflow
+

package/skills/examples/non-copilot-research-ingestion.md

@@ -0,0 +1,68 @@
+# Worked example: non-Copilot research ingestion
+
+This example shows how a generic agent runtime can use the portable skill catalog without relying on Copilot-specific role wrappers.
+
+## 1. Resolve the entrypoint
+
+Open `.github/skills/skills.json` and find the entry with:
+
+- `id`: `ingest-research-round`
+- `purpose`: review-ready research ingestion without promotion
+
+Use its `file` field to load:
+
+```text
+.github/skills/ingest-research-round.skill.md
+```
+
+## 2. Read the skill metadata
+
+From the front matter, collect:
+
+- `reads` - the docs and draft files to inspect first
+- `runs` - the commands to execute
+- `composes` - the lower-level skills that this orchestration skill chains
+- `outputs` - what a successful run should leave behind
+- `acceptance` - what must be true before stopping
+
+## 3. Execute the workflow
+
+1. Put the source artefact in `hippocampus/inbox/research/`.
+2. Run:
+
+   ```bash
+   npx hippocampus research sync -- --no-promote
+   ```
+
+3. Read the generated files named in the skill:
+
+   ```text
+   hippocampus/imports/research/<draft-id>.review.md
+   hippocampus/imports/research/<draft-id>.json
+   ```
+
+4. Follow the composed skills in order:
+   - `structure-research-draft`
+   - `review-research-import-draft`
+   - `map-research-to-graph`
+
+5. Stop only when the orchestration skill's `acceptance` items are satisfied.
+
+## 4. Respect the guardrails
+
+The skill card makes the critical safety rules explicit:
+
+- do not edit `hippocampus/source/`
+- do not promote the draft automatically
+- keep extracted text and warnings unless the underlying issue is resolved
+
+## 5. Handover
+
+The output should be a review-ready draft plus a dry-run result, not promoted source data.
+
+If the human reviewer approves, promotion remains a separate deliberate command:
+
+```bash
+npx hippocampus promote research -- --draft hippocampus/imports/research/<draft-id>.json
+```
+