The ulk framework structure

ulk is a monorepo organized around a markdown agents directory, shared packages, and a shell installer. This article maps what lives where, and why.

Root view

ulk/
├─ framework/
│  ├─ agents/                # 90 agents (one .md file per agent)
│  ├─ packages/
│  │  ├─ core/               # shared TS lib (parser, types, GitHub client)
│  │  └─ status-board/       # project tracking dashboard
│  ├─ schemas/               # JSON Schemas (todo, spec, project, dashboard, recettage)
│  ├─ cheatheet/             # Node.js doc generator (zero deps)
│  ├─ community-skills/      # bundled third-party skills (Figma, Swift, Flutter, etc.)
│  └─ tools/                 # check-tools.sh, cli-registry.json
├─ site/                     # GitHub Pages documentation (Astro)
├─ install.sh                # installer (install / uninstall / check / verify)
├─ uninstall.sh
├─ CLAUDE.md                 # repo instructions (loaded at every Claude session)
└─ package.json              # npm workspaces

Source: CLAUDE.md section “Project Overview”.

framework/agents/ — the core

This is where the 90 agents live. Each agent is a standalone markdown file with no dependencies.

Organization by category

framework/agents/
├─ orchestrators/    # Bruce, Tony, Lovecraft, project-decomposer, blackemperor
├─ docs/             # Shuri, Strange, Friday, obsidian-vault
├─ audit/            # Sargeras, Rodin, ED-209, Killbill, context-audit
├─ session/          # Godspeed, 2b3, Robocop, Xavier
├─ mobile/           # iOS / Swift / Flutter agents
├─ sync/             # Linear, Notion, GitHub synchronization
├─ routines/         # cloud routines (Routine 53, CI Guard 54)
├─ analyze/          # static analysis
├─ deploy/           # deployment
├─ test/             # test execution
├─ frontend/         # design / components / a11y
├─ vps/              # VPS ops (opt-in via --with-vps)
└─ specials/         # quarantine (currently empty)

Source: CLAUDE.md section “Agent System” — “Agent folders: orchestrators/ · docs/ · audit/ …”

Numbering

Each agent has a globally preserved number. Agent numbers run from 00 to 67 at time of writing, with the next available slot at 68. The registry framework/agents/registry.json is auto-generated by node framework/cheatheet/generate-registry.cjs.

Phases (frontmatter phase:)

Each agent declares its phase in its frontmatter:

Phase	Role
define	Framing, brief → spec
plan	Decomposition, todo, architecture
build	Implementation
verify	Tests, lint, acceptance
review	Audit, debug, reverse doc
ship	Commit, release, deploy
orchestrator	Multi-agent coordination

Full grid: framework/agents/_shared/phase-grid.md.

Shared protocols

The framework/agents/_shared/ folder contains cross-cutting protocols:

• base-rules.md — rules inherited by all agents.
• context-hygiene-protocol.md — the 4 mandatory rules.
• memory-protocol.md — Obsidian-compatible Knowledge Vault Loop.
• plugins-protocol.md — delegation to official Anthropic plugins.
• figma-protocol.md — Figma skills workflow.
• notion-protocol.md — Notion CLI-first, MCP fallback.
• routines-protocol.md — autonomous sessions without a local machine.
• local-llm-protocol.md — delegation to apfel/ollama for micro-tasks.

framework/packages/

Two shared TypeScript packages:

• core — markdown parser, types, GitHub client. Used by internal tools.
• status-board — project dashboard (HTML + JS).

At the root, package.json is an npm workspace. The agents themselves remain markdown with no dependencies.

framework/schemas/

JSON Schemas shared between JS/TS packages:

• todo.schema.json — Kanban Monoboard.
• spec.schema.json — product spec.
• project.schema.json — project metadata.
• dashboard.schema.json — status-board.
• recettage.schema.json — acceptance checklists.

Guarantees consistency of files generated by agents.

framework/cheatheet/

Node.js doc generator, zero external dependencies:

• generate-registry.cjs — produces agents/registry.json + agents/registry.md from frontmatters.
• generate-commands.cjs — produces commands/ from agents/ (auto-run by install.sh).

framework/tests/

Regression tests. Added in April 2026 (Epic ULK-181→183).

• agents-golden.test.mjs — native Node runner (node --test).
• agents/<agent>.golden.md — golden fixtures, one per agent. Each golden validates: required frontmatter, critical H2 sections, invocation patterns.
• generate-golden-files.cjs — calibrated auto-generation (H2 sections, min_table_rows at 50%).
• cheatheet.test.mjs — doc generator tests.
• install.bats — bats tests for install.sh.

Scope: structural, deterministic, free. Limitation: does not test agent behavior at runtime.

framework/community-skills/

Third-party skills bundled by default, copied to ~/.claude/skills/ on install:

Family	Count	Examples
Figma	7	figma-use, figma-implement-design, figma-code-connect
Swift	7	SwiftUI Pro, SwiftData Pro, Concurrency Pro
Flutter	2	Flutter Tester, OWASP Mobile Security
Nothing design	1	dominikmartn (opt-in)
context-audit	1	health score 0-100
cwb-app-icon	1	native iOS/macOS AppIcon (opt-in)

Source: CLAUDE.md section “Community Skills”.

install.sh

Shell script that:

1. Compiles the packages.
2. Copies agents to ~/.claude/agents/.
3. Generates commands in ~/.claude/commands/.
4. Copies skills to ~/.claude/skills/.
5. Optionally installs the Figma MCP, memory hooks, CLI telemetry.

Modes: --check, --verify, --uninstall, --dry-run + around twenty --with-* options.

site/

Public documentation in Astro, deployed on GitHub Pages. URL: https://izo.github.io/ulk/.

CLAUDE.md (root)

The repo instructions file, automatically loaded at every Claude Code session. Contains:

• Project overview.
• Essential commands.
• List of key agents.
• The 4 context hygiene rules.
• Links to shared protocols.

It’s the only mandatory file to know to collaborate with ulk.

.claude/rules/

Path-specific rules by folder:

• agents-authoring.md — how to create a new agent.
• frontend-agents.md — frontend agent rules.
• cheatheet.md — doc generator rules.
• packages.md — build & test commands.
• native-features.md — /batch, auto memory, /schedule.
• session-practices.md — the 4 hygiene rules.

Go CLI — in progress since v4.3

The native ulk CLI is in active development in framework/cli/. Phases 0-2 are shipped (ULK-265-267):

• Phase 0 — Installable interface + 6 typed module types (refactoring modules.go, ULK-265).
• Phase 1 — 6 missing skills integrated into the catalog (ULK-266).
• Phase 2 — 5 unified hooks + RTK base + cli-telemetry fix (ULK-267).

Upcoming phases:

• Phase 3 — TUI: bubbletea module selector, lipgloss progress bar.
• Phase 4 — distribution: brew install izo/tap/ulk.
• Phase 5 — macOS Wails app (P3): .app + Dashboard.

install.sh remains valid and will become a thin wrapper once Phase 4 ships.

Build locally:

cd framework/cli
make build    # → ./bin/ulk
make test     # 75+ unit tests

How to read the repo in 5 minutes

1. Read CLAUDE.md (root).
2. Open framework/agents/registry.json (complete list).
3. Open framework/agents/_shared/phase-grid.md to understand phases.
4. Read .claude/rules/session-practices.md for hygiene rules.
5. Run ./install.sh --dry-run to see what would be installed.

What’s next

Post #4: deep dive into the major agents (role, invocation, sample output).