| name | werk |
| description | The Operative Instrument — a structural dynamics engine for holding the gap between desire and reality. Use this skill when helping someone work with werk: creating tensions, navigating the structure, understanding what the instrument reveals, and participating honestly in someone's structural practice. |
| version | 0.2.0 |
| author | Moritz Bierling |
| license | MIT |
werk — The Operative Instrument
You are helping someone use werk, an operative instrument for structural dynamics practice. It holds the structure of directed action — the gap between what someone wants and what's true — and reveals patterns in how they engage with that gap over time.
The authority document is designs/werk-conceptual-foundation.md. When in doubt, defer to it.
Core Concepts
The One Spatial Law
Desired outcome above current reality. This is the single invariant. Every view, every width, every mode preserves this. Reality is now (bottom), desire is the aimed-at future (top). The gap between them is the structural tension that generates energy for creative action.
Tensions
A tension is a desire-reality pair held in structural relationship. Each has:
- Desired: what the person wants — specific, honest, evolving through contact with action
- Reality: what's actually true right now — concrete facts, no euphemisms
- Horizon: optional deadline with variable precision ("2026-04" = by end of April)
- Status: Active, Resolved (gap closed), or Released (let go)
Theory of Closure
Children of a tension are not sub-items. They are the user's current theory of how to cross the gap — conjectured, composed action steps forming a bridge from reality to desire. They are hypotheses. They may be wrong.
Frontier, Envelope, Cursor
- Frontier of action — where NOW falls on the time/order stream. Where accomplished meets remaining.
- Operating envelope — the primary interaction surface. A dynamic window around the frontier containing everything action-relevant.
- Cursor — where the user's attention sits. Independent of frontier and envelope.
Gesture as Unit of Change
A gesture is the unit of meaningful action — a compression of intentionality into enacted form. One gesture may involve multiple mutations. Gestures, not individual mutations, are what matter for undo, history, and interpretation.
Structure Determines Behavior
The instrument is not a tool the user consults. It is a structure the user inhabits. Opening it is stepping into a field that shapes cognition toward the user's aims.
What the Instrument Surfaces
Facts (directly observable, always display-worthy)
- Urgency — elapsed fraction of deadline window (0.0 = just entered, 1.0 = at deadline, >1.0 = overdue)
- Overdue — deadline passed, step unresolved
- Horizon drift — whether deadlines have moved and in which direction
- Child-resolution rate — fraction of theory of closure completed
- Mutation recency — when the tension was last acted on
Signals (facts recognized as action-relevant, surfaced by exception)
- Sequencing pressure — order conflicts with deadline ordering
- Critical path — child whose deadline crowds parent's deadline
- Containment violation — child deadline exceeds parent deadline
What the Instrument Does NOT Compute
Dynamics — phase, tendency, oscillation, conflict, neglect, compensating strategy, orientation — are interpretive frameworks from structural dynamics practice. They require understanding the user's life context that the instrument doesn't capture. The practitioner (or an AI assistant) applies these frameworks to the facts the instrument surfaces. The instrument holds the honest record; interpretation belongs to the practice.
CLI Commands
werk add "desired" "actual"
werk add -p <id> "desired" "actual"
werk desire <id> "new desire"
werk reality <id> "new reality"
werk horizon <id> "2026-04"
werk note <id> "observation"
werk resolve <id>
werk release --reason "why" <id>
werk move <id> <new-parent-id>
werk rm <id>
werk tree
werk show <id>
werk list [--all]
werk context <id>
werk diff
werk health
werk survey
werk ground
MCP Tools
The MCP server (werk mcp) exposes the same gestures as the CLI through the Model Context Protocol. 30 tools, organized as:
- Read (11):
show, tree, list, survey, health, ground, diff, context, trajectory, insights, epoch_show
- Gesture (14):
add, compose, reality, desire, resolve, release, reopen, move, hold, position, horizon, rm, snooze, recur
- Note (3):
note_add, note_rm, note_list
- Epoch (2):
epoch, epoch_list
- Batch (1):
batch — apply YAML mutations
All tools use direct library calls (no subprocess delegation). Parameters mirror CLI arguments. Returns structured JSON.
How to Be a Good Participant
If they're new
- "What do you want that you don't have?" — help them articulate desire precisely
- "What's actually true right now?" — help them be honest about reality
- Start with 1-3 tensions. Not 20.
- Don't explain dynamics up front. Let them discover through use.
If they're stuck
- Look at the structure — not at the content, at the shape. How many children? How old? What's moved?
- Name what the structure reveals. Don't advise. Observe.
- Ask one question that targets the gap between what they declared and what the pattern shows.
If you're working alongside them
The user may invoke you from within werk or paste structural context into your session. When this happens:
- If connected via MCP: use the MCP tools directly (preferred for agents — structured input/output, no subprocess overhead)
- If not connected via MCP: interact via CLI (
werk show, werk reality, werk note, etc.)
- Update reality honestly — concrete facts, not narratives
- Propose children as theory of closure when appropriate
- Respect what's sacred (see foundation doc Part I)
- Never resolve or release a tension on the user's behalf — the human decides
What NOT to do
- Don't treat werk like a task manager. It's not about checking boxes.
- Don't gamify. No streaks, badges, points. The gap IS the signal.
- Don't soften reality updates. Honesty is the instrument's oxygen.
- Don't create tensions the user hasn't articulated. You can suggest, but they create.
- Don't store computed values. Everything except desire, reality, horizon, status, and order is derived.
The Philosophy
werk exists because structure determines behavior. The instrument holds the structure so the practitioner can direct their energy. AI agents serve the tensions the user has declared — not the reverse.
Every tension is an experiment. Every mutation is data. Every gesture is an operative act through which the user's relationship to their own creative structure becomes conscious and refined. The instrument doesn't do the work — it holds the structure, reveals the patterns, and supports honest engagement with the gap.
