mighty

name	mighty
description	Use the `mt` tool to work with this repo’s Mighty graph: run `mt prime` at session start; prefer delegated `explore-mighty` lookup for nontrivial graph research, then targeted `mt search`/`mt show`; create specs, decisions, and tasks; and route into nested `mighty/*` skills for planning, delivery, evidence, evals, records, docs, and related workflows.

Mighty (mt)

Session start

• Run mt prime.
• Treat workstream_ref as the mutable current scope for the branch or delivery lane.
• Treat checkpoint IDs as the rewrite-safe lineage anchors beneath restore, publish, and evidence flows.
• After rebase or other history rewrite, re-run mt prime if needed and keep using mt flows instead of relying on old git SHAs.
• If you need the repo prefix for citations, run mt repo show.

Find context first

• If your runtime supports subagents or custom agents, delegate nontrivial Mighty graph research to the installed explore-mighty agent so the main thread only gets a compact digest. The agent is purpose-built to absorb extensive recall and return a synthesized index — use it proactively before editing code or whenever the question is about intent rather than implementation.
• Ask that context agent to return only the relevant IDs, governing guarantees/constraints/decisions, and immediate blockers or follow-ups.
• Otherwise start with targeted mt search <keyword> and then mt show <id>.
• Use mt tree or mt tree <id> only as a focused map when parent/child relationships are still unclear.
• Use citations in descriptions: [Title](cite:<id_prefix>-spec-...) / ...-dec-... / ...-task-... (always include link text).

Route To Sub-skills

• Use planning/ when the task is mostly about specs, decomposition, or shaping new work. That skill carries the current defaults for Guarantees/Constraints structure, semantic child_of edges, nested list usage, and evidence placement.
• Use decisions/ when the main job is to record or revise durable architectural choices.
• Use tasks/ when you are executing implementation work with progress comments and closeout.
• Use docs/ for graph-native guides, ADRs, RFCs, plans, and research.
• Use delivery/ for PR-backed workstreams, mt pr, and artifact-backed handoff.
• Use gates/ when the current thread needs to inspect, add, request, waive, or override delivery gates with mt gate.
• Use get-pr-reviewed/ and merge-pr/ as phrase-targeted pointers into gates/ when the user explicitly asks to get a PR reviewed or merged.
• Use evidence/ for attaching files to specs, tasks, or decisions.
• Use artifacts/ when agent-run screenshots, videos, or logs should render directly in the final message UI.
• Use attachments/ when the user uploaded files or archives that need analysis.
• Use actions/ when defining or updating action_def records.
• Use evals/ for Mighty-native eval records and external-evals/ for framework-specific or Python SDK eval write-back.
• Use records/ when defining or using agent-defined record types.
• Use views/ when authoring persisted view_def payloads and declarative UI surfaces.
• Use integrations/ when setting up dynamic integrations, sending secure setup URLs or secret config links, or citing integration_id setup mentions.
• Use merge/ when resolving .mighty/loro/*.loro conflicts with mt merge.
• Use spec-audit/ when migrating specs to the Guarantees + Constraints format or when auditing tree/evidence semantics.
• Use slack-canvas/ only for Slack-linked runs that need canvas inspection or edits.
• Use video-analysis/ when analyzing a local video via mt watch.

Create and track work

• New spec: mt new --title "..." --type feature --description-file -
• New decision: mt decision new --title "..." --rationale "..."
• New task: mt task new --title "..." --type task --description-file -
• Start work: mt claim <task-id>
• Link evidence/relationships: mt link ...
• Prefer mt link ... -d "..." descriptions that name the specific guarantee or constraint the child/evidence edge covers.

Editing rich text: always mt edit, never mt update --description-file

mt edit is the only safe way to modify an existing entity's rich-text description. It works uniformly across specs, tasks, decisions, and docs — any record-backed entity with a fields.description LoroTree. Always use it for any change — adding a bullet, updating a constraint, fixing a typo, rewriting a section. mt update --description-file (and mt doc update --content-file) is a last resort reserved for exceptional full rewrites where comment anchor loss is explicitly acceptable.

Why full-description rewrites are dangerous: they replace the entire LoroTree. Every text node gets a new TreeID, which destroys:

• Comment anchors pinned to specific phrases or paragraphs by users in the web UI
• Citation instance IDs (the target ID survives, but the cite UUID regenerates)
• CRDT merge compatibility with concurrent edits
• Any revision history tied to node identity

If users are actively commenting on an entity, a full rewrite silently wipes those anchors. Do not use mt update --description-file or mt doc update --content-file for incremental changes.

The mt edit workflow (works for spec / task / dec / doc)

• Inspect: mt show <id> --sections lists sections as JSON with @s:N identifiers
• Drill in: mt show <id> --section @s:N returns the section as YAML with raw counter@peer loro_ids
• Apply: mt edit <id> --section @s:N --content-file /path/to/edit.yaml

The YAML schema:

• loro_id: <counter>@<peer> — keep an existing node (text/metadata may change in place via minimal CRDT diff via LoroText::update())
• Omit loro_id — create a new node
• Omit a loro_id from your submission that was present in the original — delete that node
• markdown: 'inline **bold** and code' — on new nodes only, shorthand for authoring inline formatting (parses into child text nodes with the right format metadata). Rejected on existing nodes to protect comment anchors.

Important: always re-read the section immediately before editing it. Loro tree IDs are stable once assigned, but if you captured IDs from mt show --section and then made another edit in between, those captured IDs may now refer to deleted nodes. Read → edit, read → edit. Don't batch reads ahead of batch edits.

See mt edit --help for the full schema and examples. See planning/references/targeted-edits.md for common patterns (add list item, update code block, cross-section move, etc.).

When mt update / mt doc update is acceptable

• mt update --title, --status, --type (no description change) — safe
• mt update --description-file — last resort only, when:
  • You are fully rewriting an unpublished draft with no user comments
  • OR the entity is being deprecated and the description is being replaced with a tombstone pointer
  • In all other cases, use mt edit section by section

Inbox triage (when user runs mt inbox)

• Fix obvious typos in titles.
• Clarify titles to be concise/actionable.
• Find/link parents via mt search.
• Promote from triage → draft once clarified.

Before you say “done”

• Run mt closeout --quiet and fix any unlinked decisions/tasks/docs it reports.
• Run mt closeout for the advisory changed-file prompt; link files relevant to your work (the list may include unrelated local changes).
• Record any missing decision(s), link evidence, then mt commit.

File uploads and references

• Upload files with mt file upload <path> (or mt upload <path>).
• Use the returned file_id in rich text:
  • Block embed: ![[file <file_id>]]
  • Inline mention: [[file <file_id>]]
• When graph evidence is needed, link the uploaded file artifact:
  • mt link --from <spec-or-task-id> --rel documented_by --to-type file --to-ref mighty-file:<file_id>