Files

tegwick 8b6ce5bbc8 docs: add specification, reference docs, workplan, and agent guidance

Adds all Phase 0 content that was created but never committed:
- CLAUDE.md and SCOPE.md — agent and developer orientation
- specs/TailwindForInteractionHubs_v0.2.md — IHF Tailwind coding guide
- docs/ — five IHP v1.5 reference guides (overview, data, controllers, realtime, ihf-mapping)
- workplans/IHUB-WP-0001 — Phase 1 implementation plan (12 tasks, state-hub synced)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-03-27 02:07:13 +01:00

5.1 KiB

Raw Blame History

SCOPE

This file helps you quickly understand what this repository is about, when it is relevant, and when it is not. It is intentionally lightweight and may be incomplete.

One-liner

Specification and reference implementation of the Interaction Hub Framework (IHF) — a governed, observable interaction substrate for hub-based AI-enabled software systems.

Core Idea

IHF treats every meaningful UI element as a governed interaction artifact rather than mere markup. It connects the full traceability chain from rendered widget → user interaction → structured feedback → requirement candidate → decision record → implementation change → observed outcome. This makes interaction observable, frustration actionable, and UI evolution evidence-based.

In Scope

Widget identity, lifecycle governance, and semantic addressability
Interaction event capture and contextual enrichment
Annotation and structured comment threads attached to widgets
Requirements distillation from raw feedback clusters
Governance ledger: decision records linked to requirements and implementations
Outcome observation and pre/post change comparison
AI-assisted distillation (bounded, attributable, reviewer-controlled)
Cross-hub integration of interaction signals
Platform APIs and conventions for framework-agnostic UI integration
IHF specification documents and canonical artifact type definitions

Out of Scope

A complete universal frontend framework or design system
Pixel-level visual design or CSS conventions
Full product management methodology
Replacement for DevOps observability tooling (ops-hub handles that)
Unrestricted autonomous AI decision-making on requirements
Mandatory single UI technology for all hub surfaces

Relevant When

Building or reviewing any hub dashboard or operator surface (dev-hub, ops-hub, fin-hub)
Capturing and triaging user/operator feedback on existing hub UIs
Defining governed widget identity for a new capability surface
Implementing structured requirements distillation from interaction signals
Designing cross-hub feedback routing or policy-linked decisions

Not Relevant When

Backend API development with no interaction surface
Infrastructure provisioning or cluster operations (see railiance-*, ops-bridge)
Data pipeline or SBOM work (see state-hub / dev-hub)
One-off scripts or tooling with no end-user UI

Current State

Status: concept / early spec
Implementation: Phase 0 complete (specification written); Phase 1 (Minimal Interaction Core) not yet started
Stability: spec is draft — artifact model and vocabulary are stable enough for repo creation
Usage: none yet; reference implementation target is IHP + PostgreSQL

How It Fits

Upstream dependencies: hub-core (for base models, domain/capability registration, MCP tools) — see CUST-WP-0025
Downstream consumers: dev-hub, ops-hub, fin-hub — any hub with an operator-facing surface
Often used with: kaizen-agentic (agent-assist module), state-hub (decision records, requirement linkage)

Terminology

Preferred terms: Widget, Widget Envelope, Interaction Event, Annotation, Requirement Candidate, Decision Record, Outcome Signal
Also known as: IHF, inter-hub
Potentially confusing terms: "Hub" here = bounded domain of responsibility (Dev Hub, Ops Hub, etc.) — not the GitHub feature; "Widget" = governed semantic unit, not a visual component library widget

the-custodian — provides state-hub (decision records, workstreams) that IHF governance ledger will integrate with
ops-bridge — tunnel connectivity for remote hub surfaces
kaizen-agentic — agent personas that map to IHF's Agent Integration Module (§9.8)
hub-core — planned shared base package that IHF will depend on for domain/capability plumbing

Getting Oriented

Start with: specs/InteractionHubFrameworkSpecification_v0.1.md — the full IHF spec (19 sections)
Key files / directories: specs/ (specifications), root SCOPE.md (this file)
Entry points: read IHF spec §6 (Key Concepts), §9 (Core Modules), §14 (Phased Implementation Plan)

Provided Capabilities

type: framework
title: Governed interaction substrate
description: Provides widget registry, interaction event capture, annotation, and requirements distillation for hub-based AI systems.
keywords: [widget, interaction, feedback, annotation, requirements, governance, traceability]

type: specification
title: IHF specification and artifact model
description: Canonical artifact types and traceability chain from Widget → InteractionEvent → RequirementCandidate → DecisionRecord → OutcomeSignal.
keywords: [spec, artifact, traceability, widget, decision, outcome]

Notes

Phase 0 is complete (specification foundation). Implementation begins at Phase 1 (widget registry + interaction event capture). The spec is intentionally broader than the first implementation — IHP is the reference technology for Phase 1, but the framework is designed to survive UI technology changes (§12.7, §Phase 6).

5.1 KiB Raw Blame History