Skip to content

feat(uik): introduce User Intent Kit as an IAK feature#13

Open
ThinkOffApp wants to merge 2 commits into
mainfrom
feat/user-intent-kit
Open

feat(uik): introduce User Intent Kit as an IAK feature#13
ThinkOffApp wants to merge 2 commits into
mainfrom
feat/user-intent-kit

Conversation

@ThinkOffApp
Copy link
Copy Markdown
Owner

Rationale

We talked in the room about whether to spin User Intent Kit out as its own repo and decided against it: launching a zero-star repo for a layer that only makes sense alongside IAK's room I/O, session control, confirmation registry, and receipts log would orphan both halves. Instead, IAK ships UIK as a named feature. Architecture stays modular internally (its own package), marketing leads with "IAK now includes UIK."

What landed

  • docs/UIK.md - concise design doc covering what UIK is, why it lives in IAK, the seven elements of an Intent (goal, constraints, approval gates, ownership, receipts, escalation, done criteria), a raw-chat vs Intent example, and how it composes with existing MCP tools (room_post, room_recent, room_ack, tmux_run, the confirmation registry).
  • packages/uik/ - new @thinkoff/uik TypeScript package. Mirrors packages/core conventions (ESM, tsc build, AGPL-3.0-only, ThinkOff author).
    • src/intent.ts: Intent, Constraint, ApprovalGate, Owner, Receipt, Escalation, DoneCriterion, ValidationResult interfaces plus validateIntent() with required-field and non-empty-handle / non-empty-doneCriteria checks.
    • src/index.ts: re-exports.
    • package.json, tsconfig.json, README.md.
  • README.md - one new section ("User Intent Kit") with a ToC entry, linking to docs/UIK.md. No other changes.

Root package.json has no workspaces array and there is no root tsconfig.json, so nothing to wire there. The package builds standalone against its own devDeps (typescript 5.9.3, matching core).

Out of scope

Intentionally not in this PR, to land once the shape settles:

  • Concrete reference implementation of approval-gate execution against the existing iak-mcp-daemon confirmation registry.
  • New MCP tools intent_create, intent_status, intent_close exposed by bin/iak-mcp.mjs.
  • Receipt-log integration that keys entries by Intent id.
  • Deeper semantic validation (constraint family schemas, approver existence, gate ordering).

Test plan

  • cd packages/uik && npx tsc --noEmit passes (verified locally against typescript 5.9.3, no errors).
  • Existing IAK tests still pass (npm test at the root) - UIK doesn't touch any runtime code paths.
  • docs/UIK.md and packages/uik/README.md render correctly on GitHub.
  • Manually construct the example Intent from the docs and confirm validateIntent() returns { ok: true, errors: [] }; then drop a required field and confirm the matching error fires.

🤖 Generated with Claude Code

Petrus Pennanen and others added 2 commits May 20, 2026 02:20
- docs/UIK.md: design doc for the human-intent contract layer, the seven elements of an Intent, raw chat vs UIK example, composition with existing IAK MCP tools.
- packages/uik: seed TypeScript package (@thinkoff/uik) with Intent / Constraint / ApprovalGate / Owner / Receipt / Escalation / DoneCriterion interfaces and a minimal validateIntent() helper. Mirrors packages/core conventions (tsconfig, exports, license).
- packages/uik/README.md: pointer to docs/UIK.md plus a short example.
- README.md: new "User Intent Kit" section and ToC entry; no other changes.

Ships UIK through IAK rather than as a separate repo, per the room decision: IAK provides the substrate (rooms, sessions, tools, receipts, confirmations); UIK is the contract humans speak in.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…t:uik scripts

Follow-up to PR #13. Per @ether's review note: building UIK from the repo root
should Just Work, not require a cd into packages/uik. Adds:

- "workspaces": ["packages/*"] in root package.json so npm install at root
  installs UIK's devDeps and links @thinkoff/uik into the workspace graph.
- "build:uik" → npm run build -w @thinkoff/uik
- "test:uik" → npm test -w @thinkoff/uik --if-present (no UIK tests yet;
  --if-present keeps this a no-op until tests are added).

Verified locally: `npm install --ignore-scripts && npm run build:uik` from
repo root produces packages/uik/dist/index.js cleanly. No other workspace
side effects: only packages/uik exists under packages/ today.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant