OJF Workflow Framework

Portable Claude Code workflow framework: 40+ slash commands for the full development lifecycle, backed by a TypeScript engine for CLI and CI use. Includes /bead for session-handoff across repos, /vault for personal knowledge management, /fleet-onboard for drift reconciliation, and /wayfinder for decision maps.

Part of Frame OS — an AI-native application OS built as both a live product and an engineering portfolio. This repo is the shared development infrastructure that powers all Frame OS projects.

Why this exists

Every repo in the Frame OS ecosystem needs the same development workflows — planning, scaffolding, validating, deploying, investigating. Instead of duplicating scripts or publishing packages, this is a portable framework that installs into any sibling repo via symlink. One install-agents.sh call gives any project the full lifecycle toolkit with zero build step and instant propagation.

Design decisions

• Skill directories over flat scripts — each command is self-contained with its own orchestration prompt, knowledge files, and utility scripts
• Symlink installation over package publishing — zero build step, instant propagation across all ecosystem repos (shared UI components use npm publishing with Vite alias for local dev)
• 100+ ADRs — every significant decision documented with context, alternatives considered, and rationale (see ADR-0036 for the lock-file-rebuild protocol, ADR-0037 for JSONL truncation, ADR-0043 for the AgentBead bridge, ADR-0085/ADR-0070 for vault reachability, ADR-0098 for two-track telemetry, ADR-0102 for OPM inspectability)
• Self-improvement loop — /techdebt proposes patches to the framework itself, never production code

Features

• 40+ slash commands — plan, scaffold, validate, deploy, investigate, harden, sweep, suggest-skills, vault, fleet-onboard, wayfinder, opm, and more
• Skill-directory architecture — each command is a self-contained directory with orchestration prompt, knowledge files, and scripts
• TypeScript CLI — core-workflow binary for CI/CD and terminal use
• VS Code extension — run any slash command from the editor
• Cross-repo installation — install-agents.sh and session-init.sh symlinks skills + domain knowledge into sibling repos (symlinks tracked in git to survive clone and branch-switch)
• Self-improvement loop — /techdebt records patterns and proposes patches to the framework itself
• Architecture Decision Records — 100+ ADRs documenting every significant decision across the ecosystem

Tech Stack

Layer	Technology
Engine	TypeScript, Anthropic SDK
CLI	@core/cli (core-workflow binary)
Editor	VS Code extension (core.runSlashCommand)
Testing	Vitest
Build	pnpm workspaces, TypeScript compiler (tsc --noEmit CI gate)

---

For humans

I want to...	Start here
Understand what this project is and how it's structured	docs/architecture.md
See why decisions were made the way they were	decisions/adr/
Understand current priorities	decisions/okr/2026-q3.md
Set up and start using commands	docs/getting-started.md
Find the right command for a task	docs/commands.md

For Claude Code

I need...	Read
Agent context before cross-repo work	domain-knowledge/frame-os-context.md
Available commands and architecture	CLAUDE.md
Skill reference material	.claude/skills/<name>/knowledge/
ADR for a specific decision	decisions/adr/

---

Quick start

pnpm install && pnpm build

Commands are available immediately in Claude Code — no build step required:

/plan-feature add auth to the API
/validate
/investigate why is the LangGraph node failing
/push-all
/adr new "server-side session storage over JWT"

Install into a sibling repo:

./scripts/install-agents.sh lean-canvas

# user-scope baseline (Pocock skills + ~/.claude/CLAUDE.md):
./scripts/install-agents.sh --user-scope
# ...plus the /vault skill, the ~/selfco knowledge vault, and the opt-in vault-session hook:
./scripts/install-agents.sh --user-scope --with-selfco

---

What's in here

.claude/skills/     slash commands (skill directories with knowledge/ and scripts/; catalog includes suggested_after and layer_affinity fields)
packages/
  workflows/          @core/workflows — TypeScript workflow engine
  cli/                core-workflow binary
  vscode-extension/   VS Code extension
domain-knowledge/     Machine context corpus (loaded by commands at runtime)
decisions/
  adr/                Architecture Decision Records (ADR-0001 through ADR-0102+, including ADR-0037 JSONL truncation, ADR-0043 AgentBead bridge, ADR-0085/0070 vault reachability, ADR-0098 two-track telemetry, ADR-0102 OPM inspectability)
  okr/                Objectives and Key Results
docs/                 Human-readable documentation
personal-knowledge/   Career context (not tracked publicly)

---

The self-improvement loop

/techdebt is the meta-command. Other workflows trigger it when they encounter patterns worth recording. It proposes patches to packages/workflows/**, domain-knowledge/**, or skills/** — never production code.

When a mistake is caught, write it in 3 places:

1. Update or add the ADR in decisions/adr/
2. Update the relevant knowledge/ file in the affected command
3. Update memory/MEMORY.md

See decisions/README.md for the full write-back protocol.

Contributing

All changes go through pull requests — never push directly to main.

git checkout -b feat/my-change
# make changes
git add <files>
git commit -m "feat: description of change"
git push -u origin feat/my-change
gh pr create

License

MIT

Frame OS Ecosystem

Part of Frame OS — an AI-native application OS.

Repo	Description
shell	Module Federation host + frame-agent LLM gateway
core	Workflow framework — 40+ slash commands + TypeScript engine + skill suggestion/telemetry + /vault personal knowledge (this repo)
FrameBus	Event bus with ADR-0013, Playwright e2e
cv-builder	AI-powered resume builder with LangGraph agents
capture-agent	Golf-course capture agent (formerly gcgcca; renamed 2026-07-30) — TX imagery → segmentation model → HF; Pydantic + TypeScript type bridge
blogengine	AI blog content creation platform
TripPlanner	AI trip planner with 11-phase pipeline
core-reader	Documentation viewer for the core framework
lean-canvas	AI-powered lean canvas business model tool
gastown-pilot	Multi-agent coordination dashboard
seh-study	NASA SEH spaced repetition study tool
daily-logger	Automated daily dev blog pipeline (Vercel serverless)
purefoy	Roger Deakins cinematography knowledge base
MrPlug	Chrome extension for AI UI feedback
frame-ui-components	Shared component library (Carbon DS) — published to npm as @ojfbot/frame-ui-components
beaverGame	Terrain-to-dam sandbox loop — water-as-highway game mechanic
asset-foundry	AI-driven Blender asset pipeline
silicon-empires	Claim-system strategy game — stacked-PR development pattern
switchboard	FastAPI proxy — byte-for-byte SSE passthrough
mirrorworld	Real USGS 3DEP terrain rendered as three.js heightfield
virtualLight	Book-to-cinema pipeline — passage extraction + cinematography-styled video prompts
f1-doctrine	RAQG question layer — suggests strategist questions bound to f1-substrate calls
morning-cockpit	Local-first morning dashboard — beads, reading, research pods