generated from coulomb/repo-seed
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>
This commit is contained in:
134
CLAUDE.md
Normal file
134
CLAUDE.md
Normal file
@@ -0,0 +1,134 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
**inter-hub** is the reference implementation of the **Interaction Hub Framework (IHF)** — a governed, observable interaction substrate for hub-based AI-enabled software systems. It treats every UI element as a governed artifact, creating a full traceability chain from rendered widget → user interaction → structured feedback → requirement candidate → decision record → implementation change → observed outcome.
|
||||
|
||||
**Current state:** Phase 0 (specification) is complete. Phase 1 (Minimal Interaction Core) is the active implementation target. No application code exists yet.
|
||||
|
||||
For situational context, read `SCOPE.md`. For architecture depth, read `specs/InteractionHubFrameworkSpecification_v0.1.md`.
|
||||
|
||||
## Stack
|
||||
|
||||
- **IHP** (Integrated Haskell Platform) v1.5 — full-stack Haskell web framework, server-rendered + optional realtime
|
||||
- **Haskell** (GHC 9.10) — strongly typed, functional
|
||||
- **PostgreSQL** — canonical datastore, managed via Nix (no manual DB setup)
|
||||
- **Nix / devenv** — reproducible environment
|
||||
- **Tailwind CSS** — see `specs/TailwindForInteractionHubs_v0.2.md` for IHF-specific conventions
|
||||
|
||||
## Development Setup
|
||||
|
||||
Requires Determinate Nix + direnv:
|
||||
|
||||
```bash
|
||||
# One-time environment setup
|
||||
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh
|
||||
nix profile install nixpkgs#ihp-new
|
||||
nix profile add nixpkgs#direnv
|
||||
|
||||
# Bootstrap IHP project (Phase 1, Task T01)
|
||||
ihp-new inter-hub
|
||||
cd inter-hub
|
||||
devenv up
|
||||
```
|
||||
|
||||
After `devenv up`:
|
||||
- App server: `http://localhost:8000`
|
||||
- IHP IDE + Schema Designer: `http://localhost:8001`
|
||||
|
||||
## Key Commands
|
||||
|
||||
```bash
|
||||
devenv up # Start dev environment (app + postgres + file watchers)
|
||||
migrate # Run pending migrations
|
||||
test # Run tests (auto-creates temp Postgres DB)
|
||||
make static/prod.js static/prod.css # Production asset bundle
|
||||
deploy-to-nixos production # NixOS deploy
|
||||
```
|
||||
|
||||
Schema editing: use the IHP IDE at `localhost:8001` or edit `Application/Schema.sql` directly. Code generation via `localhost:8001/Generators`.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Core Domain Model (Phase 1)
|
||||
|
||||
| Entity | Role |
|
||||
|--------|------|
|
||||
| `Hub` | Bounded domain of responsibility (Dev Hub, Ops Hub, etc.) |
|
||||
| `Widget` | Smallest semantically governable interaction unit with stable ID |
|
||||
| `WidgetVersion` | Version history of widget definitions |
|
||||
| `InteractionEvent` | Recorded user/agent interaction (viewed, clicked, submitted, etc.) — **append-only** (enforced by PostgreSQL trigger) |
|
||||
| `Annotation` | Structured comment attached to a widget with category |
|
||||
| `ViewContext` | Logical location in the UI |
|
||||
| `CapabilityReference` | Link to hub capability |
|
||||
|
||||
### Traceability Chain
|
||||
|
||||
```
|
||||
Widget → InteractionEvent / Annotation
|
||||
→ RequirementCandidate (Phase 2)
|
||||
→ DecisionRecord (Phase 3)
|
||||
→ ImplementationChange → DeploymentRecord → OutcomeSignal
|
||||
```
|
||||
|
||||
### IHP Conventions
|
||||
|
||||
- Controllers live in `Web/Controller/`, views in `Web/View/`, types in `Web/Types.hs`
|
||||
- Schema changes go in `Application/Schema.sql`, then generate with IHP IDE
|
||||
- Use `AutoRefresh` for operator dashboards (server push on DB change) — not DataSync or Server-Side Components in Phase 1
|
||||
- See `docs/ihp-ihf-mapping.md` for how IHP capabilities map to IHF requirements
|
||||
|
||||
### Widget Envelope
|
||||
|
||||
Every rendered widget wraps its HSX in a `widgetEnvelope` helper (Task T08) that injects the stable `widget-id` and `view-context` attributes, enabling client-side event capture without coupling to implementation.
|
||||
|
||||
## UI Conventions
|
||||
|
||||
All hub interfaces follow the Tailwind layer model in `specs/TailwindForInteractionHubs_v0.2.md`:
|
||||
|
||||
```
|
||||
Semantic Role → Visual Primitive → Tailwind Token → Screen Composition
|
||||
```
|
||||
|
||||
Key rules:
|
||||
- Every interactive element belongs to a named semantic role (`action-primary`, `nav-item`, `data-cell`, etc.)
|
||||
- Use spacing rhythm from the spec; do not invent ad-hoc spacing
|
||||
- State cues (hover, active, disabled, error) follow the defined color roles
|
||||
|
||||
## Required Environment Variables
|
||||
|
||||
| Variable | Purpose |
|
||||
|----------|---------|
|
||||
| `IHP_SESSION_SECRET` | Session encryption key |
|
||||
| `DATABASE_URL` | Postgres connection string |
|
||||
| `IHP_BASEURL` | External URL (e.g., `https://example.com`) |
|
||||
|
||||
## Active Workplan
|
||||
|
||||
Phase 1 work is tracked in `workplans/IHUB-WP-0001-ihf-phase1-minimal-interaction-core.md` (12 tasks, T01–T12). Use `/ralph-workplan workplans/IHUB-WP-0001-ihf-phase1-minimal-interaction-core.md` to drive implementation loops.
|
||||
|
||||
Phase 1 exit criteria:
|
||||
- Widgets can be addressed and annotated reliably
|
||||
- Interaction data is captured with actor attribution and view context
|
||||
- Hub-level inspection of interaction signals is possible via a dashboard
|
||||
|
||||
## Key Reference Docs
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `SCOPE.md` | Situational guide — in/out of scope, terminology, entry points |
|
||||
| `specs/InteractionHubFrameworkSpecification_v0.1.md` | Full IHF spec (8 phases, risks, design principles) |
|
||||
| `specs/TailwindForInteractionHubs_v0.2.md` | Agent-optimized Tailwind coding guide |
|
||||
| `docs/ihp-overview.md` | IHP v1.5 fundamentals and dev workflow |
|
||||
| `docs/ihp-data-and-queries.md` | Schema design, auto-generated types, query builder, migrations |
|
||||
| `docs/ihp-controllers-views-forms.md` | Controller patterns, HSX, forms, validation, auth |
|
||||
| `docs/ihp-realtime.md` | AutoRefresh vs DataSync vs HTMX decision guide |
|
||||
| `docs/ihp-ihf-mapping.md` | IHP capability → IHF requirement mapping with schema templates |
|
||||
|
||||
## Related Repositories
|
||||
|
||||
- `hub-core` — planned shared base package for domain/capability registration
|
||||
- `the-custodian` — State Hub (decision records, workstreams) that IHF governance integrates with
|
||||
- Downstream consumers: `dev-hub`, `ops-hub`, `fin-hub`
|
||||
Reference in New Issue
Block a user