knots

name	knots
description	Use the Knots workflow through `kno` when asked to create a knot, work on a specific knot, claim or execute a knot, advance a knot to its next state, or recover or roll back a knot safely after blocked or failed work.

Knots

Agent identity

Create or receive a lease before writing workflow metadata:

kno lease create --nickname "<session-name>"

Bind that lease to every claim, creation, advance, note, and handoff-capsule command you run for the session. Agent identity for notes, handoff capsules, state transitions, and gate decisions comes from the bound lease.

Do not copy legacy --*-agentname/model/version identity flags from telemetry or command history. They are deprecated, ignored by current kno, and can leave metadata attributed as [unknown <date>] when no lease is bound.

Create a knot

Run:

kno new "<title>" -d "<description>" --lease <lease-id>

Use a short action-oriented title. Write the description with the expected outcome, relevant context, and constraints for the next agent. Add handoff context for the next actor with:

kno update <id> -H "<capsule>" --lease <lease-id>

Execute a knot

Follow this sequence:

kno claim <id> --lease <lease-id>

• If you are working inside a git worktree, run Knots commands as kno -C <path_to_repo> ... because Knots is installed for the repo root, not the worktree path.
• Record the current state from the claim output.
• Use the claim output to determine the current state's completion goals.
• Do the work and validate it.
• If the goals were met, advance with a guarded state check:

kno next <id> --expected-state <current_state> --lease <lease-id>

• If you are blocked, validation fails, or the state's goals were not met, roll back safely:

kno rollback <id> --lease <lease-id>

If the claimed knot lists children, handle the children first:

• Claim each child knot and follow that child prompt to completion.
• When the child knots are handled, evaluate the outcomes.
• If every child advanced, advance the parent.
• If any child rolled back, roll the parent back too.

Do not invent alternate transition workflows. Prefer claim, next, and rollback over manual state mutation unless the user explicitly asks for it.

Session close behavior

• In an interactive session, briefly say what changed and ask what to do next.
• In a non-interactive session, stop cleanly after the knot workflow is complete.