{"id":49763249,"url":"https://github.com/0disoft/mustflow","last_synced_at":"2026-06-27T07:01:40.402Z","repository":{"id":357050761,"uuid":"1227599677","full_name":"0disoft/mustflow","owner":"0disoft","description":"AGENTS.md, command contracts, skills, and verification rules so agents stop guessing.","archived":false,"fork":false,"pushed_at":"2026-06-27T06:19:21.000Z","size":6157,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-27T06:21:43.520Z","etag":null,"topics":["agent-workflow","agents-md","coding-agents","developer-tools","llm-agents"],"latest_commit_sha":null,"homepage":"https://0disoft.github.io/mustflow/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit-0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0disoft.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-02T22:54:07.000Z","updated_at":"2026-06-27T06:19:24.000Z","dependencies_parsed_at":null,"dependency_job_id":"d32dd635-3580-4410-84bc-dc1b4532b98d","html_url":"https://github.com/0disoft/mustflow","commit_stats":null,"previous_names":["0disoft/mustflow"],"tags_count":88,"template":false,"template_full_name":null,"purl":"pkg:github/0disoft/mustflow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0disoft%2Fmustflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0disoft%2Fmustflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0disoft%2Fmustflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0disoft%2Fmustflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0disoft","download_url":"https://codeload.github.com/0disoft/mustflow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0disoft%2Fmustflow/sbom","scorecard":{"id":1247255,"data":{"date":"2026-05-11T05:27:47Z","repo":{"name":"github.com/0disoft/mustflow","commit":"cab4e3fd89035148f54d5d6de209e62a1b92d25d"},"scorecard":{"version":"v5.3.0","commit":"c22063e786c11f9dd714d777a687ff7c4599b600"},"score":7.6,"checks":[{"name":"Dependency-Update-Tool","score":10,"reason":"update tool detected","details":["Info: detected update tool: RenovateBot: .github/renovate.json:1"],"documentation":{"short":"Determines if the project uses a dependency update tool.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#dependency-update-tool"}},{"name":"Maintained","score":0,"reason":"project was created within the last 90 days. Please review its contents carefully","details":["Warn: Repository was created within the last 90 days."],"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#maintained"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#dangerous-workflow"}},{"name":"CI-Tests","score":-1,"reason":"no pull request found","details":null,"documentation":{"short":"Determines if the project runs tests before pull requests are merged.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#ci-tests"}},{"name":"Code-Review","score":0,"reason":"Found 0/30 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#code-review"}},{"name":"Security-Policy","score":10,"reason":"security policy file detected","details":["Info: security policy file detected: SECURITY.md:1","Info: Found linked content: SECURITY.md:1","Info: Found disclosure, vulnerability, and/or timelines in security policy: SECURITY.md:1","Info: Found text in security policy: SECURITY.md:1"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#security-policy"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#binary-artifacts"}},{"name":"Token-Permissions","score":10,"reason":"GitHub workflow tokens follow principle of least privilege","details":["Info: jobLevel 'contents' permission set to 'read': .github/workflows/actions-hygiene.yml:25","Info: jobLevel 'actions' permission set to 'read': .github/workflows/actions-hygiene.yml:41","Info: jobLevel 'contents' permission set to 'read': .github/workflows/actions-hygiene.yml:42","Info: jobLevel 'actions' permission set to 'read': .github/workflows/codeql.yml:26","Info: jobLevel 'contents' permission set to 'read': .github/workflows/codeql.yml:27","Info: jobLevel 'actions' permission set to 'read': .github/workflows/osv-scanner.yml:37","Info: jobLevel 'contents' permission set to 'read': .github/workflows/osv-scanner.yml:38","Info: jobLevel 'contents' permission set to 'read': .github/workflows/publish-npm.yml:20","Info: jobLevel 'actions' permission set to 'read': .github/workflows/scorecard.yml:22","Info: jobLevel 'contents' permission set to 'read': .github/workflows/scorecard.yml:23","Info: found token with 'none' permissions: .github/workflows/actions-hygiene.yml:1","Info: topLevel 'contents' permission set to 'read': .github/workflows/ci.yml:13","Info: found token with 'none' permissions: .github/workflows/codeql.yml:1","Info: topLevel 'contents' permission set to 'read': .github/workflows/docs-site.yml:13","Info: found token with 'none' permissions: .github/workflows/osv-scanner.yml:1","Info: found token with 'none' permissions: .github/workflows/publish-npm.yml:1","Info: found token with 'none' permissions: .github/workflows/scorecard.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#token-permissions"}},{"name":"SAST","score":10,"reason":"SAST tool detected: CodeQL","details":["Info: SAST configuration detected: CodeQL","Warn: no pull requests merged into dev branch"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#sast"}},{"name":"Pinned-Dependencies","score":10,"reason":"all dependencies are pinned","details":["Info:  18 out of  18 GitHub-owned GitHubAction dependencies pinned","Info:   8 out of   8 third-party GitHubAction dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#pinned-dependencies"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT No Attribution: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#license"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#cii-best-practices"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#vulnerabilities"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#packaging"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: some github tokens can't read classic branch protection rules: https://github.com/ossf/scorecard-action/blob/main/docs/authentication/fine-grained-auth-token.md","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#branch-protection"}},{"name":"Fuzzing","score":10,"reason":"project is fuzzed","details":["Info: JavaScriptPropertyBasedTesting integration found: tests/cli/security-fuzz.test.js:6","Info: JavaScriptPropertyBasedTesting integration found: tests/cli/security-fuzz.test.js:6"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#fuzzing"}},{"name":"Contributors","score":0,"reason":"project has 0 contributing companies or organizations -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project has a set of contributors from multiple organizations (e.g., companies).","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#contributors"}}]},"last_synced_at":"2026-05-11T05:38:23.792Z","repository_id":357050761,"created_at":"2026-05-11T05:38:23.792Z","updated_at":"2026-05-11T05:38:23.792Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34844346,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-workflow","agents-md","coding-agents","developer-tools","llm-agents"],"created_at":"2026-05-11T10:01:39.487Z","updated_at":"2026-06-27T07:01:40.394Z","avatar_url":"https://github.com/0disoft.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mustflow\n\nLanguages: [English](README.md) · [한국어](docs/i18n/ko/README.md) · [中文](docs/i18n/zh/README.md) · [Español](docs/i18n/es/README.md) · [Français](docs/i18n/fr/README.md) · [हिन्दी](docs/i18n/hi/README.md)\n\nmustflow is a repository-local work contract and verification CLI for LLM coding agents. It keeps agents inside explicit read, command, and verification boundaries without replacing the host agent's sandbox, approval, checkpoint, model, or tool policies.\n\nThe core concept is straightforward: place `AGENTS.md` at the project root and keep detailed workflows under `.mustflow/`. Agents start from `AGENTS.md`, then follow the repository command contract, skills, project context, and verification rules in sequence.\n\n- Documentation site: \u003chttps://0disoft.github.io/mustflow/\u003e\n- Human-readable project examples: [`examples/`](examples/)\n- Repository: \u003chttps://github.com/0disoft/mustflow\u003e\n- Issues: \u003chttps://github.com/0disoft/mustflow/issues\u003e\n- Contributing: [CONTRIBUTING.md](https://github.com/0disoft/mustflow/blob/main/CONTRIBUTING.md)\n- Security: [SECURITY.md](https://github.com/0disoft/mustflow/blob/main/SECURITY.md)\n- Changelog: [CHANGELOG.md](https://github.com/0disoft/mustflow/blob/main/CHANGELOG.md)\n\n## Choose your path\n\n- Use mustflow in your repository: start with [Quick start](#quick-start), then review the [no-guessing workflow](#no-guessing-workflow) and [`examples/minimal-js/`](examples/minimal-js/).\n- Contribute to mustflow: read [CONTRIBUTING.md](CONTRIBUTING.md), then run only configured command intents from [`.mustflow/config/commands.toml`](.mustflow/config/commands.toml).\n- 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/`](schemas/).\n\n## No-guessing workflow\n\nThe initial mustflow path is deliberately narrow.\n\nAuthority stays narrow:\n\n- Current user instructions define the task goal unless they are unsafe.\n- Host safety, sandbox, and approval gates still apply.\n- Repository work rules come from the nearest `AGENTS.md` and `.mustflow/config/*.toml`.\n- Command execution authority comes only from `.mustflow/config/commands.toml`.\n- Skills, context files, preferences, generated maps, search results, cache, and state files guide or explain work. They do not grant command permission.\n\n```sh\nnpm install -D mustflow\nnpx mf init --yes\nnpx mf check --strict\n```\n\nAfter changes to code, templates, schemas, or documentation, classify the changed paths and review the verification plan before running any commands.\n\n```sh\nnpx mf classify --changed --write .mustflow/state/change-classification.json\nnpx mf verify --from-classification .mustflow/state/change-classification.json --plan-only --json\nnpx mf verify --from-classification .mustflow/state/change-classification.json --json\n```\n\nThe 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.\n\nSource 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`.\n\n## Agent Read Flow\n\n```mermaid\nflowchart TD\n  A[\"AGENTS.md\"] --\u003e B[\"Workflow\"]\n  B --\u003e C[\"Config files\"]\n  C --\u003e D[\"Command rules\"]\n  D --\u003e E{\"preferences.toml?\"}\n  E --\u003e|yes| F[\"preferences.toml\"]\n  E --\u003e|no| G[\"Skills index\"]\n  F --\u003e G\n  G --\u003e H{\"Need task context?\"}\n  H --\u003e|yes| I[\"Context files, matching skill, or REPO_MAP.md\"]\n  H --\u003e|no| J[\"Source, tests, docs\"]\n  I --\u003e J\n```\n\n`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.\n\nThe 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`.\n\n## Quick start\n\nNode.js 20 or newer is required. mustflow is distributed as an npm package with the CLI named `mf`.\n\n```sh\nnpm install -D mustflow\nnpx mf init --yes\nnpx mf check --strict\n```\n\nIn 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.\n\nRun `mf init --dry-run` to preview the installation plan before writing files.\n\npnpm and Bun can use the same npm package. Bun is an installer/runtime option here,\nnot a separate mustflow dependency:\n\n```sh\npnpm add -D mustflow\npnpm exec mf init --yes\n\nbun add -d mustflow\nbunx mf init --yes\n```\n\nProject-local installs should use `npx mf`, `pnpm exec mf`, or `bunx mf`. To make `mf`\navailable as a direct shell command, install mustflow globally:\n\n```sh\nnpm install -g mustflow\nmf version --check\n\nbun add -g mustflow@latest\nmf version --check\n```\n\nIf the shell still prints `mf: command not found`, mustflow is not installed globally\nfor that shell, or the package manager's global binary directory is not on `PATH`.\nWith Bun, make sure Bun's global binary directory, commonly `~/.bun/bin`, is on `PATH`.\n\nDeno `npm:` execution is experimental until separately verified.\n\n## What it does\n\nmustflow installs and validates an agent workflow for user projects.\n\n- Installs `AGENTS.md` and `.mustflow/**` workflow files.\n- Declares runnable command rules in `.mustflow/config/commands.toml`.\n- Checks installation health and configuration structure with `mf check` and `mf doctor`.\n- Reports host adapter compatibility with `mf adapters status` without generating host-specific files or treating them as command authority.\n- Classifies changed files, public surfaces, and validation reasons with `mf classify`.\n- Inspects changed files for quality-gaming patterns such as line stuffing, suppressions, test bypass markers, type escapes, and placeholder implementations with `mf quality check`.\n- Prints execution-free verification plans with `mf verify --plan-only --json`, including a risk-priced evidence assessment, machine-readable verification decision graph, and read-only local-index lock explanations when available.\n- Reports a read-only complexity budget in `mf api diff-risk --changed --json`, `mf verify`\n  evidence, and dashboard exports so agents justify new dependencies, helper-style surfaces,\n  config/schema churn, and broad structural changes before treating added complexity as free.\n- Lists, suggests, and runs bundled read-only utility scripts through `mf script-pack`, including\n  `code/outline` for source symbol maps, `code/dependency-graph` for bounded relative import graphs,\n  `code/change-impact` for git-diff impact and verification hints, `code/symbol-read` for focused source snippets,\n  `code/route-outline` for Hono, Elysia, Axum, and NestJS route maps, `docs/reference-drift` for stale\n  documentation references, `repo/config-chain` for nearby config inheritance,\n  `repo/env-contract` for environment-variable contract drift,\n  `repo/secret-risk-scan` for plausible hardcoded-secret findings without printing values,\n  `repo/generated-boundary` for candidate path safety checks, and `core/text-budget`\n  for exact file and JSON-field length budgets, so future checks do not sprawl into top-level\n  commands.\n- Prints context trust metadata in `mf context --json` and prompt-cache bundles so agents can distinguish binding instructions, command contracts, contextual hints, generated evidence, and volatile runtime data before using them.\n- Runs only allowed one-shot commands within a timeout via `mf run \u003cintent\u003e` or `mf verify` when the selected intent is runnable.\n- Records blockers, contradictions, verification gaps, and remaining risks as a structured conflict ledger in verify, evidence, and dashboard reports.\n- Stores bounded failure replay capsules for failed `mf verify` runs so future agents can reproduce the intent, receipt, command fingerprint, and changed-file state without copying raw command output.\n- Writes command receipts under `.mustflow/state/runs/run-*` and atomically updates `.mustflow/state/runs/latest.json`.\n- Generates a concise repository navigation map, `REPO_MAP.md`, with `mf map`.\n- Indexes and searches mustflow docs, skills, skill routes, command rules, command-effect locks, file fingerprints, and opt-in source anchor metadata with SQLite via `mf index` and `mf search`. The local SQLite file is a rebuildable lookup cache, not a memory store, audit log, command transcript store, command-authority source, or source-content database.\n- Tracks agent-created or agent-modified documentation needing prose review with `mf docs review`.\n- Validates restricted work-item or handoff JSON records with `mf handoff validate` without creating backlog files, storing transcripts, or granting command authority.\n- Exports bounded static dashboard reports with `mf dashboard --export-json \u003cpath\u003e` or `mf dashboard --export \u003cpath\u003e` for pull requests and continuous integration artifacts. The export includes a `harness_report` summary for install state, changed surfaces, verification decisions, latest receipt metadata, document-review status, and remaining risks without raw command-output tails or mutation controls.\n- Previews and applies bundled template updates safely with `mf update`.\n- Publishes JSON Schemas for automation-facing reports and command contracts in `schemas/`.\n\n## What it does not do\n\nmustflow is not an automatic project editor and is not tied to a single agent product.\n\n- It does not generate or modify application source code.\n- It does not change project files just by being installed. Files are created only when `mf init` runs.\n- It does not enforce tool-specific filenames such as `CLAUDE.md` or `GEMINI.md`.\n- It does not replace a build system, test runner, package manager, or CI/CD setup.\n- It does not add platform-specific files for GitHub, GitLab, or similar tools to the default template.\n- It does not create a `justfile`, `Makefile`, or `Taskfile.yml` by default.\n- `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.\n\n## Installed files\n\n`mf init` installs only the agent workflow into the current directory. The exact skill files depend\non the selected profile; run `mf init --dry-run --profile \u003cprofile\u003e` to preview the concrete plan\nfor a project before writing files.\n\n```text\nyour-project/\n├─ AGENTS.md\n├─ .gitignore\n└─ .mustflow/\n   ├─ config/\n   │  ├─ commands.toml\n   │  ├─ manifest.lock.toml\n   │  ├─ mustflow.toml\n   │  └─ preferences.toml\n   ├─ context/\n   │  ├─ INDEX.md\n   │  └─ PROJECT.md\n   ├─ docs/\n   │  └─ agent-workflow.md\n   └─ skills/\n      ├─ INDEX.md\n      ├─ routes.toml\n      └─ \u003cprofile-selected-skill\u003e/\n         └─ SKILL.md\n```\n\nProfiles select the installed skill surface. The package can include optional skill files that are\nnot copied into every project profile. Non-English workflow documents are localized when available;\nskill procedures currently fall back to the canonical English skill files.\n\nThe 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.\n\n`mf init` creates `.gitignore` if it is missing. If `.gitignore` exists, mustflow updates only its managed block and preserves user rules.\n\n`REPO_MAP.md` is not copied from the template. Generate it when needed with `mf map --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.\n\nIf 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.\n\n## Basic workflow\n\n```sh\nnpx mf init --yes\nnpx mf doctor\nnpx mf check --strict\nnpx mf classify --changed --write .mustflow/state/change-classification.json\nnpx mf verify --from-classification .mustflow/state/change-classification.json --plan-only --json\nnpx mf verify --from-classification .mustflow/state/change-classification.json --json\n```\n\nCreate the optional local search index if search capabilities are needed. Run the normal command\nwhen creating the index for the first time.\n\n```sh\nnpx mf index --dry-run --json\nnpx mf index\nnpx mf search mustflow_check\n```\n\nOn later runs, use incremental mode when you want to reuse a compatible fresh cache without rewriting\nthe SQLite file. If the cache is missing, stale, or incompatible, mustflow falls back to a full rebuild.\n\n```sh\nnpx mf index --incremental --json\n```\n\nPreview 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.\n\n```sh\nnpx mf status\nnpx mf update --dry-run\nnpx mf update --apply\n```\n\nAfter 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.\n\n```sh\nbun add -g mustflow@latest\nmf upgrade --dry-run\nmf upgrade\n```\n\nAgents should prefer the configured update intents so the repository receives a run receipt.\n\n```sh\nmf run mustflow_update_dry_run\nmf run mustflow_update_apply\n```\n\n## Commands\n\n| Command | Purpose |\n| --- | --- |\n| `mf init` | Install `AGENTS.md` and `.mustflow/**`. |\n| `mf init --dry-run` | Show which files would be created without writing files. |\n| `mf init --merge` | Merge the mustflow managed block into an existing `AGENTS.md`. |\n| `mf init --force` | Back up conflicting files, then overwrite them. |\n| `mf check` | Validate mustflow files, TOML configuration, and skill document shape. |\n| `mf check --strict` | Run additional safety checks for document identity, authority/lifecycle metadata, skill index/body alignment, skill metadata, command boundaries, version-source discovery, retention policy, output limits, raw logs, and secret-like context. |\n| `mf adapters status` | Inspect existing host-specific instruction and adapter files without generating adapter files or granting command authority. |\n| `mf classify --changed` | Classify changed paths, public surfaces, and validation reasons. Add `--write \u003cpath\u003e` to save the classification report. |\n| `mf contract-lint` | Inspect `.mustflow/config/commands.toml` for command-contract errors and warnings without running commands. Add `--suggest` to print non-runnable candidate snippets from existing command files. |\n| `mf onboard commands` | Suggest review-only command-intent snippets from package.json, Makefile, or justfile without writing files or granting command authority. |\n| `mf next` | Inspect install state, changed files, verification coverage, and command-contract gaps, then print the next safe mustflow action without running commands. |\n| `mf evidence` | Summarize changed-file verification requirements, risk-priced evidence assessment, latest failure replay capsule, conflict ledger, receipts, remaining risks, and gaps without running commands. |\n| `mf workspace status` | Inspect configured workspace roots and nested repository contract readiness without granting parent-to-child command authority. |\n| `mf workspace command-catalog` | Aggregate per-repository command intent availability with safe `mf run` entrypoints and no raw command strings. |\n| `mf workspace verify --changed --plan-only` | Aggregate per-repository changed-file verification plans without running commands or granting parent-to-child command authority. |\n| `mf doctor` | Inspect the current mustflow root without writing files. |\n| `mf api workspace-summary --json` | Print a stable, read-only JSON summary for coding agents and external harnesses. |\n| `mf api command-catalog --json` | Print command intent availability and safe `mf run` entrypoints without exposing raw command strings. |\n| `mf api verification-plan --changed --json` | Print a stable, read-only verification plan for changed files without executing commands. |\n| `mf api latest-evidence --json` | Print bounded latest run or verify evidence without raw command output. |\n| `mf api diff-risk --changed --json` | Print a compact changed-file risk, verification summary, read-only complexity budget, and residual correction signals. |\n| `mf api health --json` | Print a compact workspace health report for quick agent gating. |\n| `mf api locks --json` | Print active `mf run` locks for multi-session coordination. |\n| `mf api serve --stdio` | Serve the same read-only API reports as newline-delimited JSON responses over stdin/stdout. |\n| `mf docs review list` | Show documents still waiting for prose review after agent edits. |\n| `mf docs review add \u003cpath\u003e` | Add or refresh a document review queue entry. |\n| `mf docs review comment \u003cpath\u003e` | Add multiline review guidance to an existing queue entry. |\n| `mf docs review approve \u003cpath\u003e` | Mark review complete and hide the document from the default queue. |\n| `mf handoff validate \u003cpath\u003e` | Validate a restricted work-item or handoff JSON record without writing files. |\n| `mf context --json` | Print read order, command rules, context trust metadata, available capabilities, prompt-cache bundles, and recent run summary as JSON. |\n| `mf skill route` | Resolve compact skill route candidates from task text, paths, and reasons before reading selected skill documents. |\n| `mf map --stdout` | Print the current mustflow root map to stdout. |\n| `mf map --write` | Create or update `REPO_MAP.md`. |\n| `mf quality check` | Inspect changed files for quality-gaming patterns without writing files. |\n| `mf quality check --all` | Inspect every tracked text file for quality-gaming patterns. |\n| `mf script-pack list` | List bundled script packs, script refs, routing hints, side-effect flags, input/output labels, and JSON schema files. |\n| `mf script-pack suggest --changed --json` | Rank optional read-only helpers for current changed files without running those helpers or granting command authority. |\n| `mf script-pack suggest --path \u003cpath\u003e --phase before_change` | Rank helpers for an explicit path and workflow phase before deciding which script to run. |\n| `mf script-pack run code/outline scan \u003cpath...\u003e --json` | Scan supported source files for symbol headers, line ranges, source anchors, return metadata, and content hashes. |\n| `mf script-pack run code/dependency-graph scan \u003cpath...\u003e --json` | Trace bounded relative import, export, require, and dynamic import edges for TypeScript and JavaScript source files. |\n| `mf script-pack run code/change-impact analyze --base HEAD --json` | Analyze changed files and return bounded impact candidates, script-pack hints, and verification intent hints. |\n| `mf script-pack run code/symbol-read read \u003cpath\u003e --start-line \u003cline\u003e --json` | Read the focused symbol range or bounded source snippet after `code/outline` identifies the relevant location. |\n| `mf script-pack run code/symbol-read read --anchor \u003cid\u003e --json` | Read the conservative target symbol for a structured `mf:anchor` source marker. |\n| `mf script-pack run code/route-outline scan \u003cpath...\u003e --json` | Scan Hono, Elysia, Axum, and NestJS files for route methods, paths, handlers, lifecycle chains, line ranges, and content hashes. |\n| `mf script-pack run code/export-diff compare --base HEAD --json` | Compare exported TypeScript or JavaScript declarations, return metadata, and package surface hints against a git base. |\n| `mf script-pack run docs/reference-drift check [path...] --json` | Check documentation references to `mf` commands, script-pack refs, schema files, and repository paths against current local surfaces. |\n| `mf script-pack run repo/config-chain inspect \u003cpath...\u003e --json` | Inspect nearby package, TypeScript, ESLint, Vite, Tailwind, test, and mustflow config files plus static inheritance edges without executing dynamic config code. |\n| `mf script-pack run repo/env-contract scan [path...] --json` | Scan code, CI, docs, config, and env examples for environment-variable contract drift without reading or printing real secret env values. |\n| `mf script-pack run repo/secret-risk-scan scan [path...] --json` | Scan code, docs, config, CI, and examples for plausible hardcoded secrets while reporting only redacted fingerprints. |\n| `mf script-pack run repo/generated-boundary check \u003cpath...\u003e --json` | Check whether candidate paths cross generated, ignored, protected, vendor, or cache boundaries before or after edits. |\n| `mf script-pack run repo/related-files map \u003cpath...\u003e --json` | Map direct imports, importers, same-basename siblings, and nearby config or package boundaries for source navigation. |\n| `mf script-pack run core/text-budget check \u003cpath...\u003e --max \u003ccount\u003e` | Check exact text length budgets for files using grapheme counts by default. |\n| `mf script-pack run core/text-budget check package.json --json-pointer /description --max \u003ccount\u003e --json` | Check a JSON string field and print the stable report schema. |\n| `mf run \u003cintent\u003e` | Run an allowed one-shot command. |\n| `mf run \u003cintent\u003e --wait` | Wait for conflicting active run locks before executing the command. |\n| `mf run \u003cintent\u003e --dry-run --json` | Preview whether an intent is runnable and what command metadata would be used, without executing it. |\n| `mf index` | Build a SQLite index for mustflow docs, skill routes, command rules, command-effect locks, and file fingerprints. Use `--incremental` to reuse a compatible fresh index without rewriting it. |\n| `mf search \u003cquery\u003e` | Search docs, skills, skill routes, command rules, and command-effect locks in the SQLite index. |\n| `mf status` | Inspect installed state and changed or missing files. |\n| `mf update --dry-run` | Calculate a template update plan without writing files. |\n| `mf update --apply` | Apply template updates when nothing is blocked. |\n| `mf upgrade` | Check package freshness, then apply safe bundled template updates when the package is current. |\n| `mf upgrade --dry-run` | Check package freshness and print the safe project update plan without writing files. |\n| `mf help \u003ctopic\u003e` | Show installed mustflow help. |\n| `mf dashboard` | Start a local inspection dashboard for status, verification recommendations, release/version-source status, template update readiness, latest run receipt, skill routes, safe preferences, and documentation review. Use `--export-json \u003cpath\u003e` or `--export \u003cpath\u003e` for a bounded static report. It does not execute commands or apply fixes. |\n| `mf version` | Print the installed mustflow package version. |\n| `mf version --check` | Compare the installed package version with the latest npm release and print package-manager update commands if a newer version exists. |\n| `mf version-sources` | Inspect detected package, template, and declared version sources without modifying files. |\n| `mf impact --changed` | Report whether changed paths require a package or template version decision. |\n| `mf verify --reason \u003cevent\u003e` | Run configured verification intents selected by `required_after` metadata. |\n| `mf verify --reason \u003cevent\u003e --plan-only --json` | Print the required verification plan without running commands. |\n| `mf explain authority [path]` | Explain managed Markdown authority decisions without modifying files. |\n| `mf explain skill \u003cskill_id\u003e` | Explain the trigger, scope, risk, checks, output contract, and selection evidence for one skill route. |\n| `mf explain skills` | Explain the strict skill index/body alignment summary used by `mf doctor --strict`. |\n| `mf explain surface [path]` | Explain how a path maps to public-surface and validation categories. |\n\nAutomation 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/`.\n\nFor script-pack helper selection, start with `mf script-pack suggest --changed --json` or an\nexplicit `--path`. The suggestion report is only a ranking aid: it does not run scripts, prove\nverification, or bypass `.mustflow/config/commands.toml`. A common source-orientation flow is\n`code/outline` first, `code/dependency-graph` for relative import impact, then `code/symbol-read`\nfor the chosen symbol line or source anchor. After a local diff exists, use `code/change-impact`\nto summarize changed surfaces, likely related files, optional helper scripts, and verification hints. After\npublic-ish TypeScript or JavaScript changes, use `code/export-diff` to review exported signatures\nand return metadata against a git base. After docs, schema, CLI, or script-pack surface changes, use\n`docs/reference-drift` to catch stale references before treating docs as synchronized. For\nconfig-sensitive source or test work, use `repo/config-chain` before assuming effective inherited\nrules. For generated or protected paths, use `repo/generated-boundary` before editing or when\nreviewing a changed-file set. See the full\n[`mf script-pack` documentation](https://0disoft.github.io/mustflow/commands/script-pack/).\n\n`core/text-budget` counts `line` units by splitting text on line breaks; a trailing line break\ntherefore contributes an empty final line.\n\n## Command execution policy\n\nRunnable work is declared in `.mustflow/config/commands.toml` so agents do not guess commands.\nNew projects start with Bun-backed `test`, `test_related`, and `test_fast` intents so agents can run\nbasic verification immediately after `mf init`. Replace those defaults with narrower project-specific\ncommands when a repository uses another runner or has a faster related-test entrypoint.\n\n`mf run` executes only commands that meet all these conditions:\n\n- `status = \"configured\"`\n- `lifecycle = \"oneshot\"`\n- `run_policy = \"agent_allowed\"`\n- `stdin = \"closed\"`\n\nDevelopment 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.\n\nCommand 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\"`.\n\nUse `mf verify --reason \u003cevent\u003e --plan-only --json` to inspect matching verification intents, command eligibility, risk-priced evidence requirements, remaining gaps, and missing runnable coverage without executing commands. Use `mf run \u003cintent\u003e --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.\n\nEach executed command run writes a run record under `.mustflow/state/runs/run-*` and atomically updates `.mustflow/state/runs/latest.json`. 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` or `mf run \u003cintent\u003e --json` output as the evidence for a specific run.\n\n## Language and profiles\n\nInstalled workflow language, agent response language, and product-facing locale are separate settings.\n\n```sh\nnpx mf init --profile product --locale ko --agent-lang ko\nnpx mf init --product-source-locale en --product-locale ko-KR\nnpx mf init --set git.auto_commit=true\n```\n\n- `--profile`: Project profile. The default is `minimal`. Profiles also select the installed skill surface: `minimal` installs core everyday coding skills, `patterns` adds architecture-pattern procedures, and `oss`, `team`, `product`, and `library` add opt-in skill groups without removing optional skill files from the package.\n- `--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.\n- `--agent-lang`: Default language for final agent reports.\n- `--interactive`: Choose init settings via prompts.\n- `--yes`: Use default English init settings without prompts.\n- `--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.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` only changes the suggested message format. `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`.\n- `--product-source-locale`, `--product-locale`: Source and target locales for user-facing product strings.\n- `--lang`: CLI output language. Current values are `en`, `ko`, `zh`, `es`, `fr`, and `hi`.\n\n## Repository structure\n\nThe mustflow repository contains the CLI, templates, contract specifications, documentation site, and repository-level translation docs.\n\n```text\nmustflow/\n├─ README.md\n├─ ROADMAP.md\n├─ LICENSE\n├─ package.json\n├─ schemas/\n├─ tsconfig.json\n├─ docs/\n│  ├─ spec/\n│  └─ i18n/\n├─ docs-site/\n├─ src/\n│  └─ cli/\n├─ templates/\n│  └─ default/\n└─ tests/\n```\n\nFiles copied into user projects come from `templates/default/common/` and `templates/default/locales/\u003clocale\u003e/`.\n\nVersioned contract specifications live in `docs/spec/`. The documentation site links them under Design -\u003e Contract specifications.\n\n## Candidate features\n\nThese are ideas not yet officially supported:\n\n- Community skill registry and skill pack installs\n- Optional `.mustflow/work-items/` writers and lifecycle commands\n- `mf orient`, `mf refresh`\n- Tool-specific adapters\n\n## Development\n\nDevelopment commands in this repository use Bun. Users do not need Bun to run `mf` in their own projects.\nThe mustflow source repository dogfoods the installed workflow files at the repository root: agents\nshould read `AGENTS.md`, `.mustflow/docs/agent-workflow.md`, and `.mustflow/config/commands.toml`\nbefore changing code or running verification.\n\n```sh\nbun install\nbun run check\nbun run docs:check:fast\nbun run docs:check\nbun run check:install\n```\n\nWhen Bun is not available, maintainers can still run the core CLI and package metadata checks with Node/npm:\n\n```sh\nnpm run check:core:node\n```\n\nAgents working in this repository should prefer the configured mustflow intents for routine verification.\n\n```sh\nmf run build\nmf run test_fast\nmf run test_related\nmf run test\nmf run test_coverage\nmf run test_release\nmf run maintainer_check_node\nmf run docs_validate_fast\nmf run docs_validate\nmf run mustflow_check\nmf run release_npm_version_available\nmf run release_npm_published_verify\n```\n\nThe 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. 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.\n\n`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.\n\nRun the full release check before publishing:\n\n```sh\nbun run release:check\n```\n\n`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 published GitHub Release. 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 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.\n\n## Documentation site\n\nThe documentation site lives in `docs-site/`.\n\n```sh\nbun run docs:dev\nbun run docs:build\nbun run docs:preview\n```\n\nGitHub 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`.\n\n## Package contents\n\nThe npm package includes only:\n\n```text\ndist/\ntemplates/\nschemas/\nexamples/\nREADME.md\nLICENSE\n```\n\n`docs/`, `docs-site/`, `tests/`, `src/`, and work notes are not included in the npm package.\n\n## License\n\nMIT-0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0disoft%2Fmustflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0disoft%2Fmustflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0disoft%2Fmustflow/lists"}