workstate-protocol 0.2.1

Typed cross-repo contracts for the Workstate system: handoff state, MCP I/O, hook events, skill manifests, bootstrap install manifest.

workstate-protocol

Single source of truth for cross-repo contracts in the Workstate system. Pydantic v2 is canonical; JSON Schema artifacts under schemas/ are generated from the models so non-Python consumers (hook scripts, future TS/JS tooling) can validate without importing Python.

Schemas (rolled out incrementally per founding implementation note)

Status	Module	Schema
✅ v0.1.0	workstate_protocol.handoff	HandoffState, ActiveTask, TaskRef, TargetWorktree, TaskPlanRef
✅ v0.1.0	workstate_protocol.branch_naming	TASK_REF_RE, derive_task_ref_candidates, format_suggested_branch_name (single source of truth for the feature-branch grammar enforced by the post-checkout / PreToolUse / pre-commit / pre-push gates; cross-package consumers like workstate_handoff_mcp re-export by reference, never by literal copy — identity is the contract)
⏳	workstate_protocol.mcp	MCP tool I/O envelopes
⏳	workstate_protocol.hooks	SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop
⏳	workstate_protocol.skills	SkillManifest (with `scope: harness
⏳	workstate_protocol.bootstrap	Bootstrap install manifest

Generated artifacts

schemas/*.json is regenerated by scripts/generate_schemas.py and committed. Consumers that don't want to import Python can read the JSON Schema directly.

Versioning

Hard-pin major version per consumer. Bootstrap resolves a compatible quartet of (handoff, orchestrator, bootstrap, system) against a single workstate-protocol major.