@hippo-digital/hippocampus 1.0.0-rc.1

package/skills/examples/non-copilot-service-slice.md

@@ -0,0 +1,64 @@
+# Worked example: non-Copilot service slice delivery
+
+This example shows how another agent runtime can use the portable catalog to drive a source-first feature slice.
+
+## 1. Resolve the workflow
+
+Open `.github/skills/skills.json` and find:
+
+- `id`: `deliver-service-slice`
+- `purpose`: end-to-end fictional service slice delivery
+
+Load the referenced file:
+
+```text
+.github/skills/deliver-service-slice.skill.md
+```
+
+## 2. Use the catalog for planning
+
+The catalog entry already tells the agent:
+
+- which role agents normally own the work via `owners`
+- which lower-level skills are chained via `composes`
+- which commands complete the workflow via `runs`
+- what outputs and acceptance criteria define success
+
+## 3. Use the skill card for execution
+
+Read the skill card front matter and body, then work through:
+
+1. source-model authoring with:
+   - `generate-service-slice`
+   - `add-user-needs`
+   - `add-scenario`
+   - `create-journey-from-scenario`
+2. route/view work with `add-prototype-screen` only if needed
+3. review with `audit-knowledge-source`
+4. handover with a dated note under `artefacts/delivery-summaries/`
+
+## 4. Run the required checks
+
+```bash
+npx hippocampus validate
+npx hippocampus doctor
+```
+
+## 5. Stop conditions
+
+A non-Copilot agent should treat the workflow as complete only when:
+
+- the source records are linked in dependency order
+- any visible route work passes smoke testing
+- the delivery summary records what changed and any unresolved risks
+
+## 6. Why this is portable
+
+The workflow depends on:
+
+- `skills.json` for discovery
+- Markdown skill cards for execution details
+- repo scripts and docs for validation
+
+It does not require product-specific agent syntax beyond being able to read files, edit files, and run commands.
+

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

@@ -0,0 +1,57 @@
+---
+id: generate-service-slice
+title: Generate service slice
+purpose: Create a coherent fictional Hippocampus slice across linked source records.
+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/
+edits:
+  - hippocampus/source/users.json
+  - hippocampus/source/needs.json
+  - hippocampus/source/scenarios.json
+  - hippocampus/source/journeys.json
+  - hippocampus/source/screens.json
+  - hippocampus/source/evidence.json
+  - hippocampus/source/decisions.json
+  - hippocampus/source/assumptions.json
+runs:
+  - npx hippocampus validate
+outputs:
+  - Linked source records in hippocampus/source/
+  - A validation-ready slice for Hippocampus views
+guardrails:
+  - Preserve existing IDs unless the request is a true replacement.
+  - Keep all data fictional.
+  - Keep prototype facts in source JSON, not only in Nunjucks.
+acceptance:
+  - Users, needs, scenario, journey, screens, and decisions are linked in dependency order.
+  - Evidence gaps are captured in assumptions.json.
+  - npx hippocampus validate passes.
+---
+
+# Generate service slice
+
+## Use when
+- A new service area needs its first coherent Hippocampus slice.
+- You need users, needs, scenario, journey, screens and evidence to line up in one pass.
+
+## Workflow
+1. Read the current source collections before adding records.
+2. Add or update records in dependency order: users → needs → evidence or assumptions → scenarios → journeys → screens → decisions.
+3. Create a small linked slice: at least 1 user, 3 to 6 needs, 1 scenario, 1 journey with 4 to 7 steps, 2 to 4 screens, and at least 1 decision.
+4. Link every need to a user and evidence, every scenario to needs, every journey to a scenario, and every screen to at least one need.
+5. Put unsupported claims in `hippocampus/source/assumptions.json`, not in evidence.
+
+## Guardrails
+- Preserve existing IDs unless the request is a true replacement.
+- Keep all data fictional.
+- Keep prototype facts in source JSON, not only in Nunjucks.
+
+## Finish
+- Run `npx hippocampus validate`.
+- Report records created or updated, validation result, and assumptions added for missing evidence.
+

package/skills/ingest-project-context.skill.md

@@ -0,0 +1,58 @@
+---
+id: ingest-project-context
+title: Ingest project context
+purpose: Run the no-promote project-context ingestion workflow from inbox artefact to review-ready draft.
+owners:
+  - ingestion-curator
+  - workflow-orchestrator
+composes:
+  - structure-project-context-draft
+reads:
+  - node_modules/@hippo-digital/hippocampus/docs/repeatable-research-round-ingestion.md
+  - node_modules/@hippo-digital/hippocampus/docs/hippocampus-technical.md
+  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
+  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
+  - hippocampus/inbox/project/
+  - hippocampus/imports/project/[draft-id].review.md
+  - hippocampus/imports/project/[draft-id].json
+edits:
+  - hippocampus/imports/project/[draft-id].json
+  - artefacts/delivery-summaries/
+runs:
+  - npx hippocampus import project-context -- --no-promote
+  - npx hippocampus promote project-context -- --draft hippocampus/imports/project/[draft-id].json --dry-run
+outputs:
+  - Structured project-context draft ready for human review
+  - Dry-run-ready handoff with gaps and warnings
+guardrails:
+  - Do not edit hippocampus/source/ during this workflow.
+  - Do not promote the draft.
+  - Do not add generic policy, risk, or milestone claims unless the source names them.
+acceptance:
+  - Sync and structuring steps complete without canonical source edits.
+  - Unsupported overview claims are omitted or flagged as gaps.
+  - npx hippocampus promote project-context -- --dry-run passes.
+---
+
+# Ingest project context
+
+## Use when
+- A project overview deck or PDF needs to become a review-ready project-context draft.
+- You want one entrypoint for the no-promote import, draft structuring, and dry-run validation flow.
+
+## Workflow
+1. Put the artefact in `hippocampus/inbox/project/` and run the sync command if a draft does not exist yet.
+2. Improve only the generated draft JSON with `structure-project-context-draft`, using the matching review Markdown as evidence.
+3. Strengthen source-backed purpose, proposition, users, channels, policies, constraints, risks, milestones, facts, and source artefacts.
+4. Re-run the dry-run promotion command and keep weak or unsupported material out of the draft.
+5. Hand off for human review and real promotion only after the draft is clearly useful at `/hippocampus/project`.
+
+## Guardrails
+- Do not edit `hippocampus/source/` during this workflow.
+- Do not promote the draft.
+- Do not add generic policy, risk, or milestone claims unless the source names them.
+
+## Finish
+- Run the dry-run promotion command.
+- Report the draft path, fields improved, gaps deliberately left out, remaining warnings, and whether the draft is ready for human promotion.
+

package/skills/ingest-research-round.skill.md

@@ -0,0 +1,60 @@
+---
+id: ingest-research-round
+title: Ingest research round
+purpose: Run the no-promote research ingestion workflow from inbox artefact to review-ready draft.
+owners:
+  - ingestion-curator
+  - workflow-orchestrator
+composes:
+  - structure-research-draft
+  - review-research-import-draft
+  - map-research-to-graph
+reads:
+  - node_modules/@hippo-digital/hippocampus/docs/repeatable-research-round-ingestion.md
+  - node_modules/@hippo-digital/hippocampus/docs/research-knowledge-graph.md
+  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
+  - hippocampus/inbox/research/
+  - hippocampus/imports/research/[draft-id].review.md
+  - hippocampus/imports/research/[draft-id].json
+edits:
+  - hippocampus/imports/research/[draft-id].json
+  - artefacts/delivery-summaries/
+runs:
+  - npx hippocampus research sync -- --no-promote
+  - npx hippocampus promote research -- --draft hippocampus/imports/research/[draft-id].json --dry-run
+outputs:
+  - Structured research draft ready for human review
+  - Dry-run-ready handoff with counts, warnings, and supported links
+guardrails:
+  - Do not edit hippocampus/source/ during this workflow.
+  - Do not promote the draft.
+  - Preserve extracted text, source metadata, and warnings unless the underlying issue is actually resolved.
+acceptance:
+  - Sync, structuring, review, and graph-linking steps are completed without promotion.
+  - The draft remains source-backed and warnings stay visible until resolved.
+  - npx hippocampus promote research -- --dry-run passes.
+---
+
+# Ingest research round
+
+## Use when
+- A research deck or report needs to move from inbox artefact to a review-ready Hippocampus draft.
+- You want one entrypoint that chains structuring, review, and graph-linking without promoting source data.
+
+## Workflow
+1. Put the artefact in `hippocampus/inbox/research/` and run the sync command if a draft does not exist yet.
+2. Improve the generated draft with `structure-research-draft` using only the extracted review Markdown and draft JSON.
+3. Review the draft with `review-research-import-draft` and treat dry-run failures or unsupported claims as blockers.
+4. Add only supported links to existing needs, screens, evidence, journeys, or decisions with `map-research-to-graph`.
+5. Repeat structuring and review until the draft has credible participants, real insights, concrete actions, and a clean dry-run result.
+6. Hand off for human approval before any real promotion command.
+
+## Guardrails
+- Do not edit `hippocampus/source/` during this workflow.
+- Do not promote the draft.
+- Preserve extracted text, source metadata, and warnings unless the underlying issue is actually resolved.
+
+## Finish
+- Run the dry-run promotion command.
+- Report the draft path, counts improved, remaining warnings or blockers, supported graph links added, and whether the draft is ready for human promotion.
+

package/skills/map-research-to-graph.skill.md

@@ -0,0 +1,58 @@
+---
+id: map-research-to-graph
+title: Map research to graph
+purpose: Add only supported links between a reviewed research draft and existing Hippocampus entities.
+owners:
+  - ingestion-curator
+  - knowledge-builder
+  - workflow-orchestrator
+reads:
+  - node_modules/@hippo-digital/hippocampus/docs/research-knowledge-graph.md
+  - 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
+  - hippocampus/source/journeys.json
+  - hippocampus/source/screens.json
+  - hippocampus/source/evidence.json
+  - hippocampus/source/decisions.json
+  - hippocampus/source/relationships.json
+  - hippocampus/imports/research/[draft-id].json
+edits:
+  - hippocampus/imports/research/[draft-id].json
+runs:
+  - npx hippocampus promote research -- --draft hippocampus/imports/research/[draft-id].json --dry-run
+outputs:
+  - Updated research draft relationships
+  - Recommendations for plausible but unsupported links
+guardrails:
+  - Do not promote the draft.
+  - Do not create new needs, scenarios, journeys, screens, or decisions unless the user explicitly asks.
+  - Respect relationship direction so dependents point to what they rely on.
+acceptance:
+  - New links reference existing canonical entities or valid draft entities.
+  - Relationship direction follows dependent-to-supporting links.
+  - npx hippocampus promote research -- --dry-run passes.
+---
+
+# Map research to graph
+
+## Use when
+- A reviewed research draft needs explicit links to existing Hippocampus entities.
+
+## Workflow
+1. Read the reviewed draft and current canonical entities together.
+2. Add only supported links such as `has-participant`, `produced-insight`, `contributed-to`, `supports-insight`, `leads-to-action`, `addresses-need`, `renders-screen`, and `records-decision`.
+3. Prefer adding relationships inside the draft where the schema allows it.
+4. Report plausible but unsupported links as recommendations rather than writing them.
+
+## Guardrails
+- Do not promote the draft.
+- Do not create new needs, scenarios, journeys, screens, or decisions unless the user explicitly asks.
+- Respect relationship direction so dependents point to what they rely on.
+
+## Finish
+- Run the dry-run promotion command.
+- Report links added, links recommended but not written, missing canonical entities, evidence gaps, and the dry-run result.
+

package/skills/record-accessibility-review.skill.md

@@ -0,0 +1,52 @@
+---
+id: record-accessibility-review
+title: Record accessibility review
+purpose: Record a dated accessibility review for changed routes or templates.
+owners:
+  - accessibility-tester
+  - 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/components.md
+  - artefacts/accessibility/README.md
+  - app/views/
+edits:
+  - artefacts/accessibility/[yyyy-mm-dd-topic].md
+runs:
+  - npx hippocampus doctor
+outputs:
+  - Accessibility note under artefacts/accessibility/
+  - Blockers and improvements separated by scope
+guardrails:
+  - Do not claim an automated audit ran unless it actually did.
+  - Separate blockers from improvements.
+  - Cite the route, template, or component involved in every important finding.
+acceptance:
+  - Routes or templates reviewed and the review method are stated.
+  - Findings cite the route, template, or component involved.
+  - The smoke-test result and remaining manual follow-up are reported.
+---
+
+# Record accessibility review
+
+## Use when
+- Changed routes or templates need a documented accessibility pass.
+- A review needs blockers separated from follow-up improvements.
+
+## Workflow
+1. Confirm the affected routes and templates, then run `npx hippocampus doctor` if route availability is part of the change.
+2. Review the changed pages or templates for heading order, labels, link text, focus flow, keyboard reachability, error-state clarity, and NHS component usage.
+3. Where runtime inspection is available, note what was checked manually. Where it is not, be explicit that the review is code- and structure-based.
+4. Write findings to `artefacts/accessibility/<YYYY-MM-DD>-<topic>.md` with sections for scope, blockers, improvements, unanswered questions, and routes reviewed.
+5. Link to any matching screenshot pack or delivery summary when it helps explain the issue.
+
+## Guardrails
+- Do not claim an automated audit ran unless it actually did.
+- Separate blockers from improvements.
+- Cite the route, template, or component involved in every important finding.
+
+## Finish
+- Run `npx hippocampus doctor`.
+- Report the accessibility-note path, routes reviewed, blockers, improvements, and any manual follow-up still needed.
+

package/skills/record-design-decision.skill.md

@@ -0,0 +1,53 @@
+---
+id: record-design-decision
+title: Record design decision
+purpose: Turn agreed design actions and the options weighed against them into source records.
+owners:
+  - ingestion-curator
+  - knowledge-builder
+reads:
+  - node_modules/@hippo-digital/hippocampus/docs/design-actions-and-decisions.md
+  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
+  - hippocampus/templates/ncrs-insight-design-action-tracker.xlsx
+edits:
+  - hippocampus/source/design-actions.json
+  - hippocampus/source/decisions.json
+  - hippocampus/source/relationships.json
+runs:
+  - npx hippocampus import design-actions -- --workbook [path] --dry-run
+  - npx hippocampus import design-actions -- --workbook [path]
+  - npx hippocampus validate
+outputs:
+  - Design actions linked to the insights that prompted them
+  - Decisions recording every option weighed, and which one was accepted
+guardrails:
+  - Write a design action once and list every insight ID against it.
+  - Record rejected options, not only the accepted one.
+  - Do not invent options or decisions the team has not agreed.
+acceptance:
+  - Every design action links to at least one existing insight.
+  - At most one accepted decision per design action.
+  - npx hippocampus validate passes.
+---
+
+# Record design decision
+
+## Use when
+- The team has agreed design actions from a round's insights.
+- Options have been weighed against an action and one has been chosen.
+
+## Workflow
+1. Take a copy of `hippocampus/templates/ncrs-insight-design-action-tracker.xlsx` for the round.
+2. Fill the Design Actions sheet: one row per direction, listing the insight IDs that prompted it. An action is an open brief, not a solution.
+3. Fill the Decisions sheet: one row per option, all `proposed` while the team decides.
+4. When the team decides, set one option to `accepted` and the rest to `rejected`, and write the `consequence` of the accepted one.
+5. Dry-run the import and fix anything it names.
+6. Import, then run `npx hippocampus validate`.
+
+## Guardrails
+- An action answered by eleven insights is one row with eleven insight IDs, never eleven rows.
+- Rejected options are the point. Record them.
+- Do not invent options or decisions the team has not agreed. An empty Decisions sheet is a truthful record of a decision not yet made.
+
+## Finish
+- Report the actions and decisions imported, which option was accepted for each action, and any action still carrying only proposed options.

package/skills/review-research-import-draft.skill.md

@@ -0,0 +1,45 @@
+---
+id: review-research-import-draft
+title: Review research import draft
+purpose: Assess whether a research draft is ready for human promotion.
+owners:
+  - ingestion-curator
+  - workflow-orchestrator
+reads:
+  - node_modules/@hippo-digital/hippocampus/docs/research-knowledge-graph.md
+  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
+  - hippocampus/imports/research/[draft-id].review.md
+  - hippocampus/imports/research/[draft-id].json
+edits:
+  - none by default
+runs:
+  - npx hippocampus promote research -- --draft hippocampus/imports/research/[draft-id].json --dry-run
+outputs:
+  - Promotion-readiness review with blockers and suggested fixes
+  - Dry-run result
+guardrails:
+  - Do not promote the draft.
+  - Do not edit the draft unless the user explicitly asks for fixes.
+acceptance:
+  - Unsupported claims, weak insights, and vague actions are called out.
+  - No promotion occurs automatically.
+  - The dry-run result is reported.
+---
+
+# Review research import draft
+
+## Use when
+- A research draft exists and the team needs a promotion-readiness review before touching canonical source.
+
+## Workflow
+1. Run the dry-run promotion command first.
+2. Check whether participants are real, insights are actual findings, actions are concrete, relationship endpoints exist, confidence levels are credible, and every structured item is supported by extracted text.
+3. Check for duplicate or conflicting canonical IDs before promotion.
+
+## Guardrails
+- Do not promote the draft.
+- Do not edit the draft unless the user explicitly asks for fixes.
+
+## Finish
+- Report promotion blockers, unsupported claims, weak insights or vague actions, relationship issues, suggested edits, and the dry-run result.
+