plan

Plan

Overview

Create or update Mighty specs and decisions that explain what should change and why, then create linked Mighty tasks for execution.

Progressive disclosure rules

• Assume mt prime has already been run for this session; only run it if you’re missing mt conventions/context.
• Prefer the smallest artifact that preserves intent:
  • Update an existing spec/task/decision if it already captures the intent.
  • Create a new spec only when there isn’t a suitable one.
  • Create a decision only when you’re choosing between alternatives or setting a lasting constraint.
• Keep descriptions short, structured, and link out via citations; avoid walls of text.

1) Pull current context (docs + graph + code)

• If there’s a docs/ tree, run tree docs | head -n 200 and skim the relevant indices before proposing changes.
• Search the Mighty graph before grepping code:
  • mt search <keyword>
  • mt tree / mt tree <spec-id>
  • mt show <id>
• Then inspect code paths with rg and open only the files needed to avoid guessing.

2) Create or update the spec(s)

• Use the unified spec template (references/spec-template.md) for all specs — parent and leaf alike. Detail level is a property of tree depth, not template structure.
• Structure specs with Guarantees (everything the system promises) and Constraints (everything the system prevents).
• Include ALL deliberate choices as guarantees — capabilities, visual treatments, spatial layout, data properties. Specs are the authoring surface; code is the compiled artifact.
• Use citation links when referencing other entities: [Title](cite:<id_prefix>-spec-...) (always include link text).
• For a large effort, create a parent spec and add child specs using --parent. Each level refines the parent's commitments into more specific detail.

Use the template in:

• references/spec-template.md (unified, used at every tree level)
• For examples, open references/examples.md to find the right domain file, then open only that file (e.g., references/examples/spec-ui.md for UI work).

3) Record decisions (ADR-style)

Use mt decision new when you choose between alternatives or set constraints the code must follow.

Template: references/decision-template.md

• For example decision text, open references/examples/decision.md.

4) Spawn execution tasks from the spec(s)

• Create implementation tasks with mt task new --source <spec-or-decision-id> so the graph tracks provenance.
• Each task should have acceptance criteria and clear scope boundaries.

Template: references/task-template.md

• For example task text, open references/examples/task.md.

5) Link structure and evidence

• Link children to parents via mt new --parent <spec-id> (preferred at creation time).
• Add explicit edges when helpful:
  • Parent/child: mt link --from <child-spec> --rel child_of --to-spec <parent-spec>
  • Evidence: mt link --from <spec-or-task> --rel implemented_by --to-type file --to-ref <path>

6) Sync planning artifacts

Run mt commit to commit .mighty changes.

Reference templates

• Spec structure: references/spec-template.md (unified — same template at every tree level)
• Decision structure: references/decision-template.md
• Task structure: references/task-template.md
• mt shell patterns: references/mt-command-patterns.md
• Examples index: references/examples.md (points to domain-specific files in references/examples/)