Mnemix Workflow

mnemix-workflow is a repo-native spec-driven development methodology and CLI for teams that want a clear path from intent to implementation, with AI as the primary implementation engine and humans staying in control of the plan.

It combines:

• a lightweight spec-driven planning method built around versioned Markdown artifacts
• a command-oriented CLI for scaffolding and status management
• repo-local slash-command installation for supported AI assistants
• an interactive terminal UI for browsing workstreams and patches quickly
• optional repo-canonical GitHub issue mirroring for teams that want GitHub execution visibility
• selective support for machine-readable contract standards where they add real value

The result is a spec-driven workflow that stays readable to humans, operable by agents, and grounded in normal repository files instead of hidden metadata.

At the methodology level, it gives teams a lightweight path from:

• spec.md for problem and intent
• ux.md for experience and behavior
• plan.md for implementation approach
• tasks.md for execution slices
• STATUS.md for current state and PR linkage

It also gives teams a simple planning rule:

• use a workstream for larger, multi-artifact work
• use a patch for smaller tracked changes that still need repo-visible planning
• record durable repo-shaping choices in workflow/decisions/

For the full method, terminology, and repository shape, see the Methodology Naming System.

Why It Exists

AI coding gets much more reliable when requirements, UX intent, execution slices, and status are stored in the repo instead of living only in chat history.

mnemix-workflow gives you a lightweight structure for that:

• workstreams for larger planned work
• patches for smaller tracked fixes and enhancements
• STATUS.md and frontmatter metadata for lightweight machine-readable state
• mnx for fast interactive browsing
• mxw for explicit scaffolding, status, and contract commands
• mxw agent ... for repo-local slash-command installation in supported assistants
• optional mxw github ... commands for mirroring tracked work into GitHub Issues

Install

Packaged install:

pipx install mnemix-workflow

or:

pip install mnemix-workflow

This exposes three entrypoints:

• mnemix-workflow for the canonical CLI
• mxw for the shorter command-oriented alias
• mnx for the direct interactive TUI shortcut

Local development still works through Cargo when you are hacking on the repo:

cargo run --bin mxw -- --help

Quickstart

1. Initialize A Repository

Local development:

cargo run --bin mxw -- init

Installed usage:

mxw init

This creates:

workflow/
  decisions/
    README.md
  patches/
  workstreams/

2. Create Planned Work

For a full workstream:

mxw new "user profile redesign"

This creates:

workflow/workstreams/<id>-user-profile-redesign/
  STATUS.md
  spec.md
  ux.md
  plan.md
  tasks.md
  decisions/
    README.md

For a smaller tracked change:

mxw patch new "fix status copy"

This creates:

workflow/patches/0001-fix-status-copy.md

3. Track Status

Show status:

mxw status 004
mxw patch status 0001

Update status and link a PR:

mxw status set 004 completed --pr 12
mxw patch status set 0001 completed --pr 12

List tracked items by state:

mxw status list --status completed
mxw patch status list --status open

4. Install Optional Slash Commands

Install repo-local slash commands for supported assistants:

mxw agent install

Show the supported assistant integrations:

mxw agent tools

Refresh generated command files after an upgrade:

mxw agent update

This writes command files under the current repository for the initial supported tools:

• .claude/commands/mxw/
• .cursor/commands/mxw/

The installed command set is:

• /mxw:explore
• /mxw:track
• /mxw:implement
• /mxw:close
• /mxw:sync
• /mxw:status

These commands are a convenience layer over the normal repo-native workflow. mxw remains the authoritative workflow engine underneath.

For the full command reference and setup notes, see docs/slash-commands.md.

5. Install Optional Git Hooks

mxw hooks install

This installs:

• a pre-commit hook that refreshes the updated field for touched workstreams and patches
• a pre-push hook that reminds you to review status and PR linkage before opening or updating a PR

5. Validate Tracked Workflow State

Validate the whole repository:

mxw validate

Or validate one tracked item:

mxw validate 008
mxw validate 0001

6. Mirror Tracked Work Into GitHub Issues

Initialize optional GitHub issue support for the repo:

mxw github init --enable-auto-sync

Create or update mirrored issues for one tracked item:

mxw github sync 009
mxw github sync 0005

Backfill existing tracked work or sync a filtered slice:

mxw github sync --all
mxw github sync --status open --all

mnemix-workflow keeps the repo as the source of truth. GitHub issues are mirrors that get refreshed from repo artifacts, and completed tracked items are mirrored as closed issues. In v1, first mirror creation is explicit, while the optional generated GitHub Action uses mxw github sync --changed to refresh already-linked changed items on pushes to main.

When a repo uses mirrored workflow issues, prefer keeping GitHub issue creation/edit permissions narrow where practical, since issue titles and bodies are system-managed and may be overwritten on sync.

7. Launch The Interactive UI

The fastest way into the product experience is:

mnx

You can also launch it explicitly through the main CLI:

mxw ui

mnx is the shortcut app-like entrypoint. mxw is the explicit command surface for scripting, scaffolding, and operational actions.

The mnx UI

mnx is the browse-first terminal experience for Mnemix Workflow.

Today it gives you:

• status buckets for proposed, open, and completed
• a unified tracked-item list for workstreams and patches
• artifact preview for STATUS.md, spec.md, ux.md, plan.md, and tasks.md
• basic Markdown formatting in the preview pane for headings, lists, blockquotes, code fences, and simple emphasis
• direct patch-file preview for patches
• one lightweight operational action: press s to cycle the selected item's status

Key controls:

• Tab / Shift+Tab to move focus
• j / k or arrow keys to move selection
• h / l in preview to switch artifacts
• s to cycle the selected item's status
• q or Esc to quit

Method Overview

The core idea is simple:

A workflow is made of workstreams. Each workstream moves from spec to UX to plan to tasks, with decisions recorded when they become durable.

That methodology is intentionally trying to solve a specific problem:

• humans need a clear narrative of intent, scope, and tradeoffs
• AI agents need explicit artifacts they can read, update, and validate
• teams need progress and status to live in the repo instead of only in chat or PR threads

Every pull request should map to either:

• a full workstream
• a lightweight patch

GitHub issue support is intentionally additive to that model:

• repo artifacts stay canonical
• GitHub issues become optional mirrored execution surfaces
• sync writes GitHub linkage metadata back into repo files

In practice, the methodology is meant to help humans and agents align before implementation starts:

• spec.md captures what should be built and why
• ux.md captures how it should feel and behave
• plan.md captures how the implementation will be approached
• tasks.md captures the execution slices and verification steps
• STATUS.md captures whether the work is proposed, open, or completed

Planning Lanes

• workflow/workstreams/ holds larger planned initiatives with the full artifact set
• workflow/patches/ holds lightweight tracked changes in a single file
• workflow/decisions/ holds durable decisions that outlive any one workstream or patch

This keeps the framework lightweight by default without allowing untracked PRs.

For a fuller explanation of the method, terminology, repository shape, and teaching vocabulary, see the Methodology Naming System.

Core Artifacts

• spec.md
  • problem, users, goals, scope, and success criteria
• ux.md
  • journeys, states, interaction expectations, and Gherkin acceptance scenarios
• plan.md
  • technical approach and implementation strategy
• tasks.md
  • execution slices and validation checkpoints
• STATUS.md
  • machine-readable workstream state and linked PR metadata

Lightweight By Default

The common case stays intentionally small:

workflow/workstreams/001-some-workstream/
  STATUS.md
  spec.md
  ux.md
  plan.md
  tasks.md
  decisions/

workflow/patches/0001-fix-status-copy.md

Contract Standards

mnemix-workflow uses open standards selectively where machine-readable contracts are especially useful:

• OpenAPI for synchronous HTTP interfaces
• AsyncAPI for event-driven interfaces
• JSON Schema for reusable data shapes

Examples:

mxw openapi init 007
mxw openapi validate 007

mxw asyncapi init 007
mxw asyncapi validate 007

mxw schema new 007 "repository event"
mxw schema validate 007

These artifacts live under a workstream's contracts/ folder when needed.

Repository Layout

README.md
Cargo.toml
docs/
  slash-commands.md
  methodology/
src/
tests/
resources/
  commands/
  hooks/
  skills/
    mnemix-workflow/
workflow/
  decisions/
  patches/
  workstreams/

Folder Roles

• docs/
  • explanatory docs about the method and product direction
• docs/slash-commands.md
  • setup and command reference for assistant slash-command integrations
• resources/commands/
  • shared slash-command prompt templates rendered into supported assistants
• resources/skills/
  • reusable agent-facing assets and templates
• resources/hooks/
  • optional local git hook scripts for status nudges
• workflow/
  • active workflow artifacts
• workflow/workstreams/
  • larger planned work
• workflow/patches/
  • lightweight tracked fixes and enhancements
• workflow/decisions/
  • durable framework decisions

Learn More

Start with:

• Methodology Naming System
• Slash Commands
• Product Requirements Document
• Release Checklist
• Bootstrap Workstream 001
• CLI Bootstrap Workstream 003

The repo also includes a real Agent Skills Open Standard skill at:

• resources/skills/mnemix-workflow/SKILL.md

Current Status

The repository is dogfooding the framework on itself.

The current implementation includes:

• repo initialization and scaffolding via mxw
• workstream and patch tracking
• status metadata and PR linkage
• repo-local slash-command installation via mxw agent install
• browse-first TUI access via mnx
• contract scaffolding and validation for OpenAPI, AsyncAPI, and JSON Schema
• packaged install support for pip and pipx
• local hook installation via mxw hooks install
• umbrella repo validation via mxw validate

Numbering Convention

Workstreams use numeric prefixes:

• 001 through 999 use zero-padded 3-digit ids
• after 999, ids continue as 1000, 1001, and so on

Patches use zero-padded 4-digit prefixes:

• 0001, 0002, 0003, and so on