mustflow

Languages: English · 한국어 · 中文 · Español · Français · हिन्दी

mustflow tells coding agents what to read and which repository commands they may run. The workflow lives with the project, while the host remains responsible for sandboxing, approvals, checkpoints, models, and tool policies.

Place AGENTS.md at the project root and keep the detailed workflow under .mustflow/. An agent starts with AGENTS.md, then reads the command contract, relevant skills and project context before choosing verification.

• Documentation site: https://0disoft.github.io/mustflow/
• Human-readable project examples: examples/
• Repository: https://github.com/0disoft/mustflow
• Issues: https://github.com/0disoft/mustflow/issues
• Contributing: CONTRIBUTING.md
• Security: SECURITY.md
• Changelog: CHANGELOG.md

Choose your path

• Use mustflow in your repository: start with Quick start, then review how commands are chosen and examples/minimal-js/.
• Contribute to mustflow: read CONTRIBUTING.md, then run only configured command intents from .mustflow/config/commands.toml.
• Build an AI coding tool or agent harness: use AGENTS.md and mf context --json for repository context, then consume JSON output and schemas from mf api, mf classify, mf verify, mf run, mf dashboard, and schemas/.

How commands are chosen

mustflow uses a short decision path:

• Current user instructions define the task goal unless they are unsafe.
• Host safety, sandbox, and approval gates still apply.
• Repository work rules come from the nearest AGENTS.md and .mustflow/config/*.toml.
• Command execution authority comes only from .mustflow/config/commands.toml.
• Skills, context files, preferences, generated maps, search results, cache, and state files guide or explain work. They do not grant command permission.

npm install -D mustflow
npx mf init --yes
npx mf check --strict

After changes to code, templates, schemas, or documentation, classify the changed paths and review the verification plan before running any commands.

npx mf classify --changed --write .mustflow/state/change-classification.json
npx mf verify --from-classification .mustflow/state/change-classification.json --plan-only --json
npx mf verify --from-classification .mustflow/state/change-classification.json --json

The plan is based on change classification and the required_after metadata in .mustflow/config/commands.toml. A command runs only if its declared intent is configured, one-shot, agent-allowed, closed-stdin, bounded by a timeout, and backed by an explicit command source.

Source anchors, maps, and SQLite search results serve as navigation aids only. They do not grant command permission, bypass validation, or override AGENTS.md and .mustflow/config/commands.toml.

Agent Read Flow

flowchart TD
  A["AGENTS.md"] --> B["Workflow"]
  B --> C["Config files"]
  C --> D["Command rules"]
  D --> E{"preferences.toml?"}
  E -->|yes| F["preferences.toml"]
  E -->|no| G["Skills index"]
  F --> G
  G --> H{"Need task context?"}
  H -->|yes| I["Context files, matching skill, or REPO_MAP.md"]
  H -->|no| J["Source, tests, docs"]
  I --> J

Loading

read_order defines the required reading sequence, while optional_read_order and [context] control how task-specific context loads. The [refresh] policy sets when agents reread the same instructions.

The skills index acts as an active routing step: agents compare the task with .mustflow/skills/INDEX.md and read matching SKILL.md files before editing that scope. This step is required before file edits even when mf doctor or mf check passes, because health checks do not decide which task procedure applies. When files are created or modified, the final report should include a concise skill-selection note. Skills guide procedure only; command execution still comes from .mustflow/config/commands.toml.

Quick start

Node.js 20 or newer is required. mustflow is distributed as an npm package with the CLI named mf.

npm install -D mustflow
npx mf init --yes
npx mf check --strict

In an interactive terminal, mf init prompts you to choose the document language, project profile, and agent report language. Use mf init --yes to install English defaults without prompts.

Run mf init --dry-run to preview the installation plan before writing files.

pnpm and Bun can use the same npm package. Bun is an installer/runtime option here, not a separate mustflow dependency:

pnpm add -D mustflow
pnpm exec mf init --yes

bun add -d mustflow
bunx mf init --yes

Project-local installs should use npx mf, pnpm exec mf, or bunx mf. To make mf available as a direct shell command, install mustflow globally:

npm install -g mustflow
mf version --check

bun add -g mustflow@latest
mf version --check

If the shell still prints mf: command not found, mustflow is not installed globally for that shell, or the package manager's global binary directory is not on PATH. With Bun, make sure Bun's global binary directory, commonly ~/.bun/bin, is on PATH.

Deno npm: execution is experimental until separately verified.

What it does

mustflow installs and validates an agent workflow for user projects.

• Installs AGENTS.md and the .mustflow/** workflow files.
• Registers runnable commands in .mustflow/config/commands.toml and runs eligible ones with mf run <intent>.
• Checks installation and configuration health with mf check and mf doctor.
• Classifies changed files and suggests matching checks with mf classify and mf verify --plan-only.
• Runs verification at edit, commit, or release depth while keeping high-risk checks intact.
• Flags suspicious shortcuts in changed code with mf quality check.
• Shows host adapter compatibility with mf adapters status.
• Records command receipts, failed-run replay data, blockers, and remaining verification gaps under .mustflow/state/.
• Builds REPO_MAP.md and REPO_FLOW.md, then indexes workflow files for local search.
• Tracks documentation that still needs prose review and validates restricted handoff records.
• Previews and applies bundled template updates with mf update.
• Exports static dashboard reports and publishes JSON Schemas for automation.
• Builds vendor-neutral Agent Plugins from selected Mustflow skills.

Verification and helper details

mf api diff-risk, mf verify, and dashboard exports report complexity and evidence gaps before broad changes are accepted. mf context --json labels instructions, command contracts, contextual hints, generated evidence, and volatile state so consumers can distinguish their roles.

mf script-pack provides optional read-only helpers for source outlines, import graphs, module boundaries, route maps, change impact, focused snippets, documentation drift, configuration chains, environment contracts, secret-risk checks, generated-file boundaries, and text budgets.

Verification profiles trade speed for breadth: edit favors fast feedback, commit widens related checks, and release keeps every applicable check. Security, privacy, data, migration, package, and release reasons keep their full checks in every profile.

What it does not do

mustflow is not an automatic project editor and is not tied to a single agent product.

• It does not generate or modify application source code.
• It does not change project files just by being installed. Files are created only when mf init runs.
• It does not enforce tool-specific filenames such as CLAUDE.md or GEMINI.md.
• It does not replace a build system, test runner, package manager, or CI/CD setup.
• It does not add platform-specific files for GitHub, GitLab, or similar tools to the default template.
• It does not create a justfile, Makefile, or Taskfile.yml by default.
• mf dashboard inspects status, verification recommendations, command intents, release/version-source status, template update readiness, latest run receipts, skill routes, safe preferences, and documentation review state. It can copy or explain workflow information but does not run commands, apply fixes, start agents, merge branches, push changes, or update files automatically.

Installed files

mf init installs only the agent workflow into the current directory. The exact skill files depend on the selected profile; run mf init --dry-run --profile <profile> to preview the concrete plan for a project before writing files.

your-project/
├─ AGENTS.md
├─ .gitignore
└─ .mustflow/
   ├─ config/
   │  ├─ commands.toml
   │  ├─ manifest.lock.toml
   │  ├─ mustflow.toml
   │  └─ preferences.toml
   ├─ context/
   │  ├─ INDEX.md
   │  └─ PROJECT.md
   ├─ docs/
   │  └─ agent-workflow.md
   └─ skills/
      ├─ INDEX.md
      ├─ routes.toml
      └─ <profile-selected-skill>/
         └─ SKILL.md

Profiles select the installed skill surface. The package can include optional skill files that are not copied into every project profile. Non-English workflow documents are localized when available; skill procedures currently fall back to the canonical English skill files.

The default template does not create project-owned root documents or contract files such as README.md, PROJECT.md, ROADMAP.md, DESIGN.md, GOVERNANCE.md, TESTING.md, API.md, project.contract.json, or openapi.yaml. It also does not create CI configuration, general docs/, or general skills/. User projects may already use those names for their own files.

mf init creates .gitignore if it is missing. If .gitignore exists, mustflow updates only its managed block and preserves user rules.

REPO_MAP.md and REPO_FLOW.md are not copied from the template. Generate them when needed with mf map --write and mf flow --write. .mustflow/cache/mustflow.sqlite is also a regenerable local index created by mf index. .mustflow/review/docs.toml is not copied from the template; mf docs review creates it only when a document is added to the review queue.

If a project already has optional root Markdown files such as README.md, PROJECT.md, ROADMAP.md, DESIGN.md, GOVERNANCE.md, TESTING.md, DEPLOYMENT.md, ARCHITECTURE.md, or API.md, the repository map can use them as navigation anchors. It can also discover purpose-specific machine-readable contracts such as project.contract.json, project.constants.json, design-tokens.json, openapi.yaml, asyncapi.yaml, schema.graphql, and schema.prisma. Generic catch-all names like SSOT.json are not default anchors. mf init does not create or overwrite those project-owned files by default.

Basic workflow

npx mf init --yes
npx mf doctor
npx mf check --strict
npx mf classify --changed --write .mustflow/state/change-classification.json
npx mf verify --from-classification .mustflow/state/change-classification.json --plan-only --json
npx mf verify --from-classification .mustflow/state/change-classification.json --json

Create the optional local search index if search capabilities are needed. Run the normal command when creating the index for the first time.

npx mf index --dry-run --json
npx mf index
npx mf search mustflow_check

On later runs, use incremental mode when you want to reuse a compatible fresh cache without rewriting the SQLite file. If the cache is missing, stale, or incompatible, mustflow falls back to a full rebuild.

npx mf index --incremental --json

Preview template updates before applying them. Files marked as customized in .mustflow/config/manifest.lock.toml remain as repository-specific baselines while their current content matches the lock.

npx mf status
npx mf update --dry-run
npx mf update --apply

After updating the mustflow package, mf upgrade combines the package freshness check with the safe project-file update step. It does not install packages by itself; refresh mustflow with the package manager you used first. When a newer release exists, mf version --check and mf upgrade print update commands for npm, Bun, pnpm, Yarn, and Deno.

bun add -g mustflow@latest
mf upgrade --dry-run
mf upgrade

Agents should prefer the configured update intents so the repository receives a run receipt.

mf run mustflow_update_dry_run
mf run mustflow_update_apply

Common commands

Command	Purpose
mf init	Install AGENTS.md and the .mustflow/** workflow. Add --dry-run to preview or --merge to preserve an existing AGENTS.md.
mf check --strict	Validate the installed workflow and command contract.
mf doctor	Diagnose the current Mustflow root without writing files.
mf status	Show installed, changed, and missing workflow files.
mf classify --changed	Identify changed-file categories and applicable verification reasons.
mf verify --changed --profile edit	Run the smallest sufficient checks for active editing. Use commit or release for broader gates.
mf run <intent>	Run one configured, eligible command intent.
mf update --dry-run	Preview bundled template updates. Use --apply after reviewing an unblocked plan.
mf upgrade	Check package freshness and apply safe bundled workflow updates.
mf dashboard	Open the local status and settings dashboard.
mf help <topic>	Show help for a command or concept.

The documentation site covers the advanced api, workspace, evidence, script-pack, skill, handoff, explain, indexing, dashboard export, and JSON contract commands. Start with the Mustflow documentation instead of treating this README as the complete CLI specification.

Automation and agents should use --json output or mf api serve --stdio JSONL responses instead of parsing human-facing text. Published JSON Schemas for stable outputs live in schemas/.

For script-pack helper selection, start with mf script-pack suggest --changed --json or an explicit --path. The suggestion report is only a ranking aid: it does not run scripts, prove verification, or bypass .mustflow/config/commands.toml. A common source-orientation flow is code/outline first, code/dependency-graph for relative import impact, then code/symbol-read for the chosen symbol line or source anchor. After a local diff exists, use code/change-impact to summarize changed surfaces, likely related files, optional helper scripts, and verification hints. After public-ish TypeScript or JavaScript changes, use code/export-diff to review exported signatures and return metadata against a git base. After docs, schema, CLI, or script-pack surface changes, use docs/reference-drift to catch stale references before treating docs as synchronized. For config-sensitive source or test work, use repo/config-chain before assuming effective inherited rules. For generated or protected paths, use repo/generated-boundary before editing or when reviewing a changed-file set. See the full mf script-pack documentation.

core/text-budget counts line units by splitting text on line breaks; a trailing line break therefore contributes an empty final line.

Command execution policy

Runnable work is declared in .mustflow/config/commands.toml so agents do not guess commands. New projects start with Bun-backed test, test_related, and test_fast intents so agents can run basic verification immediately after mf init. Replace those defaults with narrower project-specific commands when a repository uses another runner or has a faster related-test entrypoint.

For one repository with many independently edited command groups, the root contract may include .mustflow/config/commands.d/*.toml fragments. Use .mustflow/config/commands/*.toml for delegated nested-repository authority and commands.d/*.toml for same-repository ownership slices; intent and resource names must remain unique across the effective contract.

mf run executes only commands that meet all these conditions:

• status = "configured"
• lifecycle = "oneshot"
• run_policy = "agent_allowed"
• stdin = "closed"
• timeout_seconds is a positive integer
• a command is declared with argv, or with mode = "shell" plus cmd and allow_shell = true
• cwd resolves inside the current mustflow root

Development servers, watch modes, browser UIs, interactive commands, and background processes do not run directly. mf run also rejects obvious long-running argv shapes, such as shell-wrapper background payloads, interpreter loops, package-manager development scripts, watchers, and development servers declared as one-shot commands. If a bounded one-shot command has a name that matches a common long-running pattern, the intent can explicitly acknowledge that with allow_long_running_command_patterns = true; background shell patterns remain blocked.

Command environments remove the project-local node_modules/.bin path from PATH by default. If an intent needs a project dependency binary such as eslint, tsc, or vitest, declare it through the package manager, for example npm exec eslint -- ..., pnpm exec tsc -- --noEmit, bun x eslint ..., or yarn exec eslint .... mf check --strict warns when an agent-runnable intent uses a bare executable name that appears under the project-local .bin directory, except for names listed in defaults.allow_project_local_bin_bare_executables. mf run may resolve those allowed names directly from the local .bin directory without exposing every local binary through PATH. The installed template allows mf and mustflow by default. Intent-level allow_env_inheritance_risks = true is available when a command intentionally uses env_policy = "inherit".

Use mf verify --reason <event> --plan-only --json to inspect matching verification intents, command eligibility, evidence requirements, remaining gaps, and missing runnable coverage without executing commands. Use mf run <intent> --dry-run --json to inspect one resolved command intent without spawning a process or writing a run receipt. Plan-only verification includes a decision_graph that connects changed surfaces, classification reasons, command candidates, eligibility checks, effects, and gaps. When .mustflow/cache/mustflow.sqlite is fresh, scheduled entries also include read-only effectGraph metadata for write locks and lock conflicts. These graph rows are marked explanation_only and never grant command authority; .mustflow/config/commands.toml remains the only runnable command source.

mf verify defaults to --profile edit and safe parallelism up to 4 commands, further capped by local CPU limits. Only explicit-effect, non-conflicting entries from the same scheduled batch may overlap. Use --parallel 1 for serial execution. Successful receipts may be reused only when the plan and current-state hash match, the profile is not release, and risk is below high.

mf run waits up to 300 seconds for a conflicting active resource lock by default. Use --wait-timeout <seconds> to change that bound or --no-wait to fail immediately.

Each executed command run writes a run record under .mustflow/state/runs/run-*, atomically updates .mustflow/state/runs/latest.json, and rebuilds .mustflow/state/runs/latest.index.json from retained run-* and verify-* directories. The record includes the intent name, working directory, timeout, exit code, timeout status, and the tail of stdout and stderr. latest.json is a root-scoped convenience pointer, not session-scoped proof; in multi-agent or multi-terminal workflows, use the per-run receipt_path, the retained index, or mf run <intent> --json output as the evidence for a specific run.

Language and profiles

Installed workflow language, agent response language, and product-facing locale are separate settings.

npx mf init --profile product --locale ko --agent-lang ko
npx mf init --product-source-locale en --product-locale ko-KR
npx mf init --set git.auto_commit=true

• --profile: Project profile. The default is minimal. It installs a lean everyday coding set plus explicit authentication, payment, credit, upload, deletion, migration, idempotency, and secret-response guards. Specialist audits, uncommon technology procedures, and broad test methodologies stay in the opt-in patterns, oss, team, product, and library profiles without being removed from the package.
• --locale: Installed mustflow document language. The default template currently supports en, ko, zh, es, fr, and hi. The default template includes localized documents for all these locales.
• --agent-lang: Default language for final agent reports.
• --interactive: Choose init settings via prompts.
• --yes: Use default English init settings without prompts.
• --set: Set an allowed preference during installation. Supported keys include git.auto_stage, git.auto_commit, git.auto_push=false, git.commit_message.style, git.commit_message.language, git.commit_message.max_suggestions, git.commit_message.include_body, git.commit_message.gitmoji.map, git.commit_message.body.template, git.commit_message.body.require_validation_line, git.commit_message.split_when_multiple_concerns, reporting.commit_suggestion.enabled, language.memory.summary, and boolean release.versioning.* fields such as release.versioning.suggest_bump=false, verification.selection.* fields, and testing.authoring.* fields. Versioning preferences do not assume a fixed version file; agents must locate the repository-specific version source before suggesting or editing versions. Repositories needing an explicit version source can add .mustflow/config/versioning.toml; mf init does not install this optional file by default. git.commit_message.style accepts conventional, descriptive, or gitmoji; gitmoji changes the suggested message format, while git.commit_message.gitmoji.map=conventional_default declares the conventional-type-to-Gitmoji mapping (feat=✨, fix=🐛, docs=📝, refactor=♻️, test=✅, chore/build/config=🔧). git.commit_message.body.template=summary_validation asks bodies to summarize the change and validation evidence; git.commit_message.body.require_validation_line accepts true or false. git.commit_message.language accepts preserve_existing, agent_response, docs, or a locale tag such as ja, de, or pt-BR. testing.authoring.new_test_policy accepts evidence_required, manual_approval, or broad.
• --product-source-locale, --product-locale: Source and target locales for user-facing product strings.
• --lang: CLI output language. Current values are en, ko, zh, es, fr, and hi.

Repository structure

The mustflow repository contains the CLI, templates, contract specifications, documentation site, and repository-level translation docs.

mustflow/
├─ README.md
├─ ROADMAP.md
├─ LICENSE
├─ package.json
├─ schemas/
├─ tsconfig.json
├─ docs/
│  ├─ spec/
│  └─ i18n/
├─ docs-site/
├─ src/
│  └─ cli/
├─ templates/
│  └─ default/
└─ tests/

Files copied into user projects come from templates/default/common/ and templates/default/locales/<locale>/.

Versioned contract specifications live in docs/spec/. The documentation site links them under Design -> Contract specifications.

Candidate features

These are ideas not yet officially supported:

• Community skill registry and skill pack installs
• Optional .mustflow/work-items/ writers and lifecycle commands
• mf orient, mf refresh
• Tool-specific adapters

Development

Development commands in this repository use Bun. Users do not need Bun to run mf in their own projects. The mustflow source repository dogfoods the installed workflow files at the repository root: agents should read AGENTS.md, .mustflow/docs/agent-workflow.md, and .mustflow/config/commands.toml before changing code or running verification.

bun install
bun run check
bun run docs:check:fast
bun run docs:check
bun run check:install

When Bun is not available, maintainers can still run the core CLI and package metadata checks with Node/npm:

npm run check:core:node

Agents working in this repository should prefer the configured mustflow intents for routine verification.

mf run build
mf run test_fast
mf run test_related
mf run test
mf run test_coverage
mf run test_release
mf run maintainer_check_node
mf run docs_validate_fast
mf run docs_validate
mf run mustflow_check
mf run mustflow_check_scoped --input repository=projects/example
mf run release_npm_version_available
mf run release_npm_publish
mf run release_npm_published_verify

The Bun scripts remain available for human maintainers and release packaging. test_fast runs the fast CLI regression baseline, test_related selects tests from changed files and falls back to the fast baseline, and both use 8 Node test workers by default. Skill-body changes select only their owning authoring shard plus the lightweight install-surface contract, and test_skill_contracts exposes that seconds-scale contract path directly. Set MUSTFLOW_TEST_CONCURRENCY=1, 2, or another positive integer to tune those workers on local machines. test_release keeps package metadata and packaging checks out of routine local edits. test_coverage runs the fast CLI baseline through Node's built-in coverage report with no enforced threshold; set MUSTFLOW_TEST_COVERAGE_CONCURRENCY=1, 2, or another positive integer to adjust its worker count. lint and test-audit are configured as narrow repository-local gates. docs_validate_fast checks documentation navigation and localized content links without building the entire static site; docs_validate performs the full static documentation build, search index, and sitemap gate for release-sensitive changes. In a dirty delegated workspace, use mustflow_check_scoped for one repository; global mustflow_check remains the aggregate audit and may intentionally fail on another task's unfinished manifest entry.

dist/ is a generated build output and is not committed. npm pack and npm publish run npm run build via prepack, so the npm package contains the built CLI.

Run the full release check before publishing:

bun run release:check

release:check validates the CLI, builds the documentation site, packs the npm tarball, installs it into a temporary project, and runs the public mf workflow. Maintainer npm publishing uses the Publish npm package GitHub Actions workflow from a release tag. The release tag must match the package.json version, with an optional leading v. Run mf run release_npm_version_available before creating the tag, mf run release_npm_publish to push the release tag that triggers trusted publishing and GitHub Release creation, and mf run release_npm_published_verify after the publish workflow completes. npm Trusted Publishing must be configured for the workflow before maintainers publish through it.

Documentation site

The documentation site lives in docs-site/.

bun run docs:dev
bun run docs:build
bun run docs:preview

GitHub Pages builds the docs-site/ source from the main branch using GitHub Actions and deploys docs-site/dist as the Pages artifact. Do not commit docs-site/dist.

Package contents

The npm package includes only:

dist/
templates/
schemas/
examples/
README.md
LICENSE

docs/, docs-site/, tests/, src/, and work notes are not included in the npm package.

License

MIT-0