Technical System
Schema, API, and Integration
HAI's technical system turns the methodology into trackable, queryable data. This section describes the database schema, API endpoints, dashboard integration, and AI coding agent integration used in production at serban.eu.com. Adapt the schema and tooling to your own stack.
| Column | Type | Description |
|---|---|---|
| id | UUID | Primary key |
| title | VARCHAR | Work item title |
| description | TEXT | Full description |
| work_mode | ENUM | ai | human_ai | human |
| involvement | ENUM | light | engaged | intensive |
| size | ENUM | s | m | l | xl |
| risk | ENUM | low | medium | high |
| confidence | ENUM | low | medium | high |
| spec_quality | ENUM | low | medium | high |
| phase | ENUM | request | research | specification | implementation | review | complete |
| client_id | UUID FK | Multi-tenant scoping |
| created_at | TIMESTAMP | Creation time |
| updated_at | TIMESTAMP | Last update |
| completed_at | TIMESTAMP | Completion time (nullable) |
Additional tables track assessment history (snapshots at each phase transition), comments (retrospective notes, decision logs), and resource estimates (tokens, sessions, energy). The schema is multi-tenant — every query is scoped by client_id.
/api/v1/work-items
List all work items with filtering by phase, work_mode, size
/api/v1/work-items
Create a new work item with initial HAI assessment
/api/v1/work-items/{id}
Get a single work item with full assessment history
/api/v1/work-items/{id}
Update assessment fields (reassessment)
/api/v1/work-items/{id}/transition
Transition to next phase with assessment snapshot
/api/v1/work-items/{id}/comments
Add retrospective notes, decision logs, or context
Work Item List
Filterable table showing all work items with phase, work mode, size, and spec quality badges. Full-row click opens detail view.
Phase Transitions
One-click phase advancement with automatic assessment snapshot. Each transition records the state at that point.
Assessment Editor
Inline editing of all HAI dimensions. Changes are logged with timestamps for audit trail.
Distribution Charts
Visual breakdown of work by mode, involvement, size, and spec quality. Shows patterns over time.
Agent reads the current task list and checks for existing work items. If no work item exists, creates an initial HAI assessment (work mode, involvement, size, spec quality, risk, confidence).
Agent monitors for reassessment triggers: research completion, scope changes, issues discovered. Updates the assessment when triggers fire, not constantly.
Agent creates a retrospective entry: was the spec quality accurate? Did the work mode match reality? What would improve future assessments?
Coordinator session owns the HAI assessment. Worker sessions execute tracks but do not update shared tracking docs. Admin Development Tracker API is the source of truth.
The technical system described here is the Extended HAI implementation used at serban.eu.com. You don't need this specific stack to use HAI. The core methodology works with any tracking system.
A spreadsheet with columns for work mode, involvement, size, spec quality, risk, confidence. That’s it.
Custom fields in Jira, Linear, Notion, or GitHub Projects. See the Integration guide.
Dedicated database table, API endpoints, dashboard UI. What’s described on this page.
POST /api/v1/work-items
Content-Type: application/json
Authorization: Bearer <token>
{
"title": "Add Spanish language support",
"description": "Enable Spanish voice and text across all channels",
"work_mode": "human_ai",
"involvement": "engaged",
"size": "m",
"spec_quality": "medium",
"risk": "medium",
"confidence": "medium",
"phase": "research"
}Response includes the created work item with id, created_at, and initial assessment snapshot. Use PATCH to update the assessment as the work progresses through phases.