@hippo-digital/hippocampus 1.0.0-rc.1

package/skills/skills.json

@@ -0,0 +1,464 @@
+{
+  "$schema": "./skills.schema.json",
+  "version": 1,
+  "format": "markdown-skill-catalog",
+  "root": "skills",
+  "skills": [
+    {
+      "id": "add-prototype-screen",
+      "title": "Add prototype screen",
+      "purpose": "Add a source-backed prototype screen with matching route and view.",
+      "file": "add-prototype-screen.skill.md",
+      "owners": [
+        "prototype-builder",
+        "workflow-orchestrator"
+      ],
+      "runs": [
+        "npx hippocampus validate",
+        "npx hippocampus doctor"
+      ],
+      "outputs": [
+        "Updated screen record in hippocampus/source/screens.json",
+        "Matching route and Nunjucks view"
+      ],
+      "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."
+      ]
+    },
+    {
+      "id": "add-scenario",
+      "title": "Add scenario",
+      "purpose": "Add a concrete scenario that links existing users and needs to journey work.",
+      "file": "add-scenario.skill.md",
+      "owners": [
+        "knowledge-builder",
+        "workflow-orchestrator"
+      ],
+      "runs": [
+        "npx hippocampus validate"
+      ],
+      "outputs": [
+        "Updated scenario records in hippocampus/source/scenarios.json",
+        "A scenario ready to drive journey authoring"
+      ],
+      "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."
+      ]
+    },
+    {
+      "id": "add-user-needs",
+      "title": "Add user needs",
+      "purpose": "Add or sharpen traceable need records for an existing user group.",
+      "file": "add-user-needs.skill.md",
+      "owners": [
+        "knowledge-builder",
+        "workflow-orchestrator"
+      ],
+      "runs": [
+        "npx hippocampus validate"
+      ],
+      "outputs": [
+        "Updated need records in hippocampus/source/needs.json",
+        "Assumptions for unsupported needs when required"
+      ],
+      "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."
+      ]
+    },
+    {
+      "id": "audit-knowledge-source",
+      "title": "Audit knowledge source",
+      "purpose": "Review traceability, route coverage, and evidence quality before handover.",
+      "file": "audit-knowledge-source.skill.md",
+      "owners": [
+        "knowledge-builder",
+        "workflow-orchestrator"
+      ],
+      "runs": [
+        "npx hippocampus validate",
+        "npx hippocampus doctor"
+      ],
+      "outputs": [
+        "Audit findings for blockers, traceability gaps, and model risks",
+        "Optional follow-up recommendations without rewriting records"
+      ],
+      "acceptance": [
+        "Validation and route coverage are checked first.",
+        "Findings distinguish blockers from model-quality improvements.",
+        "The output stays review-first unless fixes are requested."
+      ]
+    },
+    {
+      "id": "capture-route-review-pack",
+      "title": "Capture route review pack",
+      "purpose": "Create a dated screenshot or notes pack for changed routes after smoke testing.",
+      "file": "capture-route-review-pack.skill.md",
+      "owners": [
+        "screenshot-runner",
+        "workflow-orchestrator"
+      ],
+      "runs": [
+        "npx hippocampus doctor"
+      ],
+      "outputs": [
+        "Route review pack under artefacts/screenshots/<date-topic>/",
+        "Manifest with routes reviewed and issues found"
+      ],
+      "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."
+      ]
+    },
+    {
+      "id": "create-journey-from-scenario",
+      "title": "Create journey from scenario",
+      "purpose": "Turn an existing scenario into a blueprint-ready journey.",
+      "file": "create-journey-from-scenario.skill.md",
+      "owners": [
+        "knowledge-builder",
+        "workflow-orchestrator"
+      ],
+      "runs": [
+        "npx hippocampus validate"
+      ],
+      "outputs": [
+        "Updated journey records in hippocampus/source/journeys.json",
+        "Journey steps with lane-ready content and references"
+      ],
+      "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."
+      ]
+    },
+    {
+      "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.",
+      "file": "deliver-service-slice.skill.md",
+      "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"
+      ],
+      "runs": [
+        "npx hippocampus validate",
+        "npx hippocampus doctor"
+      ],
+      "outputs": [
+        "Updated source records and optional route/view files",
+        "Delivery summary under artefacts"
+      ],
+      "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."
+      ]
+    },
+    {
+      "id": "generate-service-slice",
+      "title": "Generate service slice",
+      "purpose": "Create a coherent fictional Hippocampus slice across linked source records.",
+      "file": "generate-service-slice.skill.md",
+      "owners": [
+        "knowledge-builder",
+        "workflow-orchestrator"
+      ],
+      "runs": [
+        "npx hippocampus validate"
+      ],
+      "outputs": [
+        "Linked source records in hippocampus/source/",
+        "A validation-ready slice for Hippocampus views"
+      ],
+      "acceptance": [
+        "Users, needs, scenario, journey, screens, and decisions are linked in dependency order.",
+        "Evidence gaps are captured in assumptions.json.",
+        "npx hippocampus validate passes."
+      ]
+    },
+    {
+      "id": "ingest-project-context",
+      "title": "Ingest project context",
+      "purpose": "Run the no-promote project-context ingestion workflow from inbox artefact to review-ready draft.",
+      "file": "ingest-project-context.skill.md",
+      "owners": [
+        "ingestion-curator",
+        "workflow-orchestrator"
+      ],
+      "composes": [
+        "structure-project-context-draft"
+      ],
+      "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"
+      ],
+      "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."
+      ]
+    },
+    {
+      "id": "ingest-research-round",
+      "title": "Ingest research round",
+      "purpose": "Run the no-promote research ingestion workflow from inbox artefact to review-ready draft.",
+      "file": "ingest-research-round.skill.md",
+      "owners": [
+        "ingestion-curator",
+        "workflow-orchestrator"
+      ],
+      "composes": [
+        "structure-research-draft",
+        "review-research-import-draft",
+        "map-research-to-graph"
+      ],
+      "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"
+      ],
+      "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."
+      ]
+    },
+    {
+      "id": "map-research-to-graph",
+      "title": "Map research to graph",
+      "purpose": "Add only supported links between a reviewed research draft and existing Hippocampus entities.",
+      "file": "map-research-to-graph.skill.md",
+      "owners": [
+        "ingestion-curator",
+        "knowledge-builder",
+        "workflow-orchestrator"
+      ],
+      "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"
+      ],
+      "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."
+      ]
+    },
+    {
+      "id": "record-accessibility-review",
+      "title": "Record accessibility review",
+      "purpose": "Record a dated accessibility review for changed routes or templates.",
+      "file": "record-accessibility-review.skill.md",
+      "owners": [
+        "accessibility-tester",
+        "workflow-orchestrator"
+      ],
+      "runs": [
+        "npx hippocampus doctor"
+      ],
+      "outputs": [
+        "Accessibility note under artefacts/accessibility/",
+        "Blockers and improvements separated by scope"
+      ],
+      "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."
+      ]
+    },
+    {
+      "id": "record-design-decision",
+      "title": "Record design decision",
+      "purpose": "Turn agreed design actions and the options weighed against them into source records.",
+      "file": "record-design-decision.skill.md",
+      "owners": [
+        "ingestion-curator",
+        "knowledge-builder"
+      ],
+      "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"
+      ],
+      "acceptance": [
+        "Every design action links to at least one existing insight.",
+        "At most one accepted decision per design action.",
+        "npx hippocampus validate passes."
+      ]
+    },
+    {
+      "id": "review-research-import-draft",
+      "title": "Review research import draft",
+      "purpose": "Assess whether a research draft is ready for human promotion.",
+      "file": "review-research-import-draft.skill.md",
+      "owners": [
+        "ingestion-curator",
+        "workflow-orchestrator"
+      ],
+      "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"
+      ],
+      "acceptance": [
+        "Unsupported claims, weak insights, and vague actions are called out.",
+        "No promotion occurs automatically.",
+        "The dry-run result is reported."
+      ]
+    },
+    {
+      "id": "structure-project-context-draft",
+      "title": "Structure project context draft",
+      "purpose": "Improve a deterministic project-context import draft using extracted source text only.",
+      "file": "structure-project-context-draft.skill.md",
+      "owners": [
+        "ingestion-curator",
+        "workflow-orchestrator"
+      ],
+      "runs": [
+        "npx hippocampus import project-context -- --no-promote",
+        "npx hippocampus promote project-context -- --draft hippocampus/imports/project/[draft-id].json --dry-run"
+      ],
+      "outputs": [
+        "Updated project-context draft JSON",
+        "Dry-run-ready summary of remaining warnings and gaps"
+      ],
+      "acceptance": [
+        "The draft keeps source metadata and extracted text intact.",
+        "Unsupported policy, risk, or milestone claims are left out or called out as gaps.",
+        "npx hippocampus promote project-context -- --dry-run passes."
+      ]
+    },
+    {
+      "id": "structure-research-draft",
+      "title": "Structure research draft",
+      "purpose": "Improve a deterministic research import draft using extracted text only.",
+      "file": "structure-research-draft.skill.md",
+      "owners": [
+        "ingestion-curator",
+        "workflow-orchestrator"
+      ],
+      "runs": [
+        "npx hippocampus research sync -- --no-promote",
+        "npx hippocampus promote research -- --draft hippocampus/imports/research/[draft-id].json --dry-run"
+      ],
+      "outputs": [
+        "Updated research draft JSON",
+        "Dry-run-ready counts and warning summary"
+      ],
+      "acceptance": [
+        "The draft keeps source metadata and extracted text intact.",
+        "Participants, insights, actions, and relationships are source-backed.",
+        "npx hippocampus promote research -- --dry-run passes."
+      ]
+    },
+    {
+      "id": "triage-research-corpus",
+      "title": "Triage research corpus",
+      "purpose": "Rank a large research folder into ingestion contenders before any artefact is imported.",
+      "file": "triage-research-corpus.skill.md",
+      "owners": [
+        "ingestion-curator",
+        "workflow-orchestrator"
+      ],
+      "runs": [
+        "npx hippocampus research triage -- --source \"[folder]\" --topic [topic]"
+      ],
+      "outputs": [
+        "Ranked triage report in artefacts/research-triage/",
+        "Tiered contender list mapped to Hippocampus record types"
+      ],
+      "acceptance": [
+        "Every file in the source folder appears in the report or in the needs-handling list.",
+        "Contenders are tiered and mapped to the records they would become.",
+        "Files the pipeline cannot read today are named explicitly."
+      ],
+      "composes": [
+        "ingest-research-round"
+      ]
+    },
+    {
+      "id": "write-delivery-summary",
+      "title": "Write delivery summary",
+      "purpose": "Capture a durable handover note for multi-step Hippocampus work.",
+      "file": "write-delivery-summary.skill.md",
+      "owners": [
+        "workflow-orchestrator"
+      ],
+      "composes": [
+        "audit-knowledge-source"
+      ],
+      "runs": [
+        "git --no-pager status --short"
+      ],
+      "outputs": [
+        "Dated summary under artefacts/delivery-summaries/",
+        "Reviewable record of commands, outcomes, and follow-up"
+      ],
+      "acceptance": [
+        "The summary includes what changed, what ran, and unresolved risks.",
+        "Failed checks or unrun steps are stated explicitly.",
+        "The summary path is reported."
+      ]
+    },
+    {
+      "id": "write-route-review-summary",
+      "title": "Write route review summary",
+      "purpose": "Combine smoke, screenshot, and accessibility evidence into one route-review handover note.",
+      "file": "write-route-review-summary.skill.md",
+      "owners": [
+        "workflow-orchestrator",
+        "screenshot-runner",
+        "accessibility-tester"
+      ],
+      "composes": [
+        "capture-route-review-pack",
+        "record-accessibility-review",
+        "write-delivery-summary"
+      ],
+      "runs": [
+        "git --no-pager status --short"
+      ],
+      "outputs": [
+        "Dated route-review summary under artefacts/delivery-summaries/",
+        "Linked references to screenshot and accessibility artefacts"
+      ],
+      "acceptance": [
+        "The summary distinguishes screenshots, notes-only evidence, and code-based review.",
+        "Missing artefacts or unresolved blockers stay visible.",
+        "The summary path is reported."
+      ]
+    }
+  ]
+}

package/skills/skills.schema.json

@@ -0,0 +1,111 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://hippo-digital.co.uk/hippocampus/skills.schema.json",
+  "title": "Hippocampus Skill Catalog",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "format",
+    "root",
+    "skills"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "format": {
+      "type": "string"
+    },
+    "root": {
+      "type": "string"
+    },
+    "agentsRoot": {
+      "type": "string"
+    },
+    "skills": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "title",
+          "file",
+          "owners",
+          "runs",
+          "purpose",
+          "outputs",
+          "acceptance"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1
+          },
+          "purpose": {
+            "type": "string",
+            "minLength": 1
+          },
+          "file": {
+            "type": "string",
+            "pattern": "^[^\\0]+\\.skill\\.md$"
+          },
+          "owners": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+            }
+          },
+          "composes": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+            }
+          },
+          "legacyPrompt": {
+            "type": "string",
+            "pattern": "^[^\\0]+\\.prompt\\.md$"
+          },
+          "runs": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "outputs": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "acceptance": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/skills/structure-project-context-draft.skill.md

@@ -0,0 +1,51 @@
+---
+id: structure-project-context-draft
+title: Structure project context draft
+purpose: Improve a deterministic project-context import draft using extracted source text only.
+owners:
+  - ingestion-curator
+  - workflow-orchestrator
+reads:
+  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
+  - node_modules/@hippo-digital/hippocampus/docs/hippocampus-technical.md
+  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
+  - hippocampus/imports/project/[draft-id].review.md
+  - hippocampus/imports/project/[draft-id].json
+edits:
+  - hippocampus/imports/project/[draft-id].json
+runs:
+  - npx hippocampus import project-context -- --no-promote
+  - npx hippocampus promote project-context -- --draft hippocampus/imports/project/[draft-id].json --dry-run
+outputs:
+  - Updated project-context draft JSON
+  - Dry-run-ready summary of remaining warnings and gaps
+guardrails:
+  - Do not edit hippocampus/source/.
+  - Preserve sourceDocument, importedAt, sections, and extracted text.
+  - Do not add generic GDPR, DSPT, policy, risk, or milestone claims unless the source names them.
+acceptance:
+  - The draft keeps source metadata and extracted text intact.
+  - Unsupported policy, risk, or milestone claims are left out or called out as gaps.
+  - npx hippocampus promote project-context -- --dry-run passes.
+---
+
+# Structure project context draft
+
+## Use when
+- A deterministic import has produced a project-context draft that needs better structure before human review.
+
+## Workflow
+1. Run the sync script first if the draft does not exist yet.
+2. Improve only the draft JSON in `hippocampus/imports/project/` using the matching review Markdown as evidence.
+3. Extract complete, source-backed items for purpose, vision, problem statement, service proposition, users, channels, policies, constraints, risks, milestones, facts, and source artefacts.
+4. Leave plausible but weak material out of the draft and report it as a gap.
+
+## Guardrails
+- Do not edit `hippocampus/source/`.
+- Preserve `sourceDocument`, `importedAt`, `sections`, and extracted text.
+- Do not add generic GDPR, DSPT, policy, risk, or milestone claims unless the source names them.
+
+## Finish
+- Run the dry-run promotion command.
+- Report fields changed, claims deliberately left out, remaining warnings, lane fit, and dry-run result.
+

package/skills/structure-research-draft.skill.md

@@ -0,0 +1,51 @@
+---
+id: structure-research-draft
+title: Structure research draft
+purpose: Improve a deterministic research import draft using extracted text only.
+owners:
+  - ingestion-curator
+  - workflow-orchestrator
+reads:
+  - node_modules/@hippo-digital/hippocampus/docs/research-knowledge-graph.md
+  - node_modules/@hippo-digital/hippocampus/docs/hippocampus-technical.md
+  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
+  - hippocampus/imports/research/[draft-id].review.md
+  - hippocampus/imports/research/[draft-id].json
+edits:
+  - hippocampus/imports/research/[draft-id].json
+runs:
+  - npx hippocampus research sync -- --no-promote
+  - npx hippocampus promote research -- --draft hippocampus/imports/research/[draft-id].json --dry-run
+outputs:
+  - Updated research draft JSON
+  - Dry-run-ready counts and warning summary
+guardrails:
+  - Do not edit canonical source files.
+  - Preserve sourceDeck, sourcePath, importedAt, and extracted text.
+  - Leave warnings in place unless the underlying issue is actually resolved.
+acceptance:
+  - The draft keeps source metadata and extracted text intact.
+  - Participants, insights, actions, and relationships are source-backed.
+  - npx hippocampus promote research -- --dry-run passes.
+---
+
+# Structure research draft
+
+## Use when
+- A script-generated research draft needs stronger participants, insights, actions, and supported links before review.
+
+## Workflow
+1. Run the sync script first if the draft does not exist yet.
+2. Improve only the draft JSON in `hippocampus/imports/research/`.
+3. Use the review Markdown and existing JSON draft to extract real participants, genuine findings, concrete design actions, and supported relationships.
+4. Reuse existing evidence IDs from `hippocampus/source/evidence.json` only when the extracted text explicitly supports the link.
+
+## Guardrails
+- Do not edit canonical source files.
+- Preserve `sourceDeck`, `sourcePath`, `importedAt`, and extracted text.
+- Leave warnings in place unless the underlying issue is actually resolved.
+
+## Finish
+- Run the dry-run promotion command.
+- Report participants, insights, actions, relationships, warnings still needing review, and the dry-run result.
+