@uplift-ds/workflow-skills

Single source of truth for Uplift workflow contracts across Claude Code and Cursor.

What this package contains

• Quick-start / front door: uplift/SKILL.md → /uplift (initialize a repo under the Uplift OS and surface the full capability set)
• Session/hat operating context: uplift-os/SKILL.md (the project-instructions equivalent for Claude Code — governs /session, /hat)
• Canonical workflow commands: commands/{align,prep,plan,build,verdict}.md + session commands commands/{session,hat}.md (first-class /session and /hat)
• Workflow skills: align/, prep/, plan/, build/, verdict/, conventions/, platform/ (review/ removed in 0.4.0 — use verdict/; domain/ removed in 1.0.0 — per-repo defaults live in workflow.config.json)
• Agent definitions: agents/done-checker.md (DoD judge) + agents/bug-hunter.md (correctness lens) + agents/security-reviewer.md (security lens, seated on security-sensitive diffs) — synced to .claude/agents/ AND .cursor/agents/; the plan-cost reviewer panel /verdict spawns. No external review bots required — works in client-owned orgs; Bugbot is an optional accelerant on owned repos (orchestrator-triggered, once per review-ready PR)
• Run conventions: conventions/references/close-out-comment.md (every agent run ends with a structured Linear comment) + conventions/references/hydration-spec.md (the packet that wakes a fresh orchestrator brain)
• Judgment session (the brain, UPLI-11): orchestrator/scripts/judgment-session.mjs + orchestrator/judgment-prompt.md — wakes a fresh, toolless Fable via headless Claude Code with the five-part hydration packet; technical authority only; writes the unblock to Linear and the distilled rule to .ralph/memory.md
• Stuck-helper: verdict/scripts/stuck-check.mjs (deterministic escalation ladder: hint → reset → human) + opt-in hook template templates/repo-adapter/claude-settings-stuck-hooks.json
• Contract schemas: contracts/*.schema.json
• Manager-worker orchestration references: orchestrator/
• Pattern decision matrix: conventions/references/execution-pattern-classification.md
• Repo adapter templates: templates/repo-adapter/
• Sync CLI: uplift-workflow-sync
• Stage runner CLI: uplift-workflow run <stage> <ISSUE_ID> --phase=preflight|postflight

Quick start in a new repo

pnpm add -D @uplift-ds/workflow-skills@latest
pnpm uplift-workflow-sync --force
# then, in Claude Code:
/uplift

/uplift bootstraps the repo's Uplift Repo Scope block in CLAUDE.md (if missing), presents the Session Protocol kickoff menu, and shows the full capability surface — workflow commands, session/hat commands, the eight hats, and MCP status. This is the Claude Code analog of opening a Claude Chat / Cowork project that already has the OS project-instructions installed — except the operating context is delivered by this package and auto-updates on the next sync, instead of being hand-re-pasted.

Two layers, one package

As of 0.2.0 this package carries both layers of the Uplift Operating System and syncs both per-repo. They are distinct concerns but share one distribution + update mechanism:

| | Session/hat layer (uplift-os, uplift) | Workflow pipeline (align/prep/plan/build/verdict) | |---|---|---| | Governs | How work is bounded, hatted, and recorded | How one coding task is executed | | Commands | /uplift, /session, /hat | /align → /prep → /plan → /build → /verdict | | Source of truth | Notion (fetched at activation) | This package | | State it touches | Notion Sessions DB | .ralph/<ISSUE_ID>/ artifacts, workflow.config.json |

Earlier designs kept the session adapter as a hand-placed user-level skill. From 0.2.0 it ships here instead, so a repo gets the operating context the same way it gets the workflow commands — pnpm add + sync — and it version-updates on the next bump (the Claude Chat adapter, by contrast, had no auto-sync and required manual re-paste).

Under the Engineering Architect hat, a session may drive the pipeline for a Linear issue (/align → /prep → /plan → /build) and record the outcome at /session close. The two command sets remain separate — neither is folded into the other — but they now travel together.

Cross-repo update model

1. Update this package once.
2. Publish a new version.
3. In each consumer repo, bump package version and run sync.

No manual copy/paste of .claude/* or .cursor/* across repos.

Sync local wrappers in a consumer repo

Install package, then run:

pnpm add -D @uplift-ds/workflow-skills@latest
pnpm uplift-workflow-sync --force

By default it writes:

• .claude/commands/{align,prep,plan,build,verdict}.md
• .cursor/commands/{align,prep,plan,build,verdict}.md
• .claude/skills/*/SKILL.md generated from package skills
• .cursor/skills/*/SKILL.md generated from package skills
• .cursor/rules/workflow-pipeline.mdc
• workflow.config.json (if missing, or overwrite with --force)

Run deterministic hooks

Use the runner around each LLM phase:

pnpm exec uplift-workflow run align SOC-415 --phase=preflight
# run reasoning using command/spec
pnpm exec uplift-workflow run align SOC-415 --phase=postflight

Optional target directory:

pnpm uplift-workflow-sync --target=/path/to/repo --force

Validation

From repo root:

npm install
npm test

Packaging strategy

• Canonical home: UpliftDS/uplift-os (package at repo root). Extracted from socialite-mono/packages/workflow-skills on 2026-06-11 — the incubation this section used to describe is over.
• socialite-mono (and every other repo) is now a pure consumer: npm i -D @uplift-ds/workflow-skills + uplift-workflow-sync --force.
• This repo runs under the OS it ships — its .claude//.cursor/ kit syncs from local source: node bin/sync.mjs --target=. --force.