Mandor

A multi-agent orchestration workflow for product and engineering.

Reusable skills, per-repository adapters, and a knowledge vault that learns. Host-agnostic. Zero dependencies. Windows, macOS, Linux.

npx @fetot/mandor setup

That runs a guided wizard: pick the skills you want, choose the language your agent writes documents in, create a knowledge vault, attach repositories, and confirm before anything is written.

Contents

• Why
• Features
• Install
• Commands
• Skills
• How it works
• Configuration
• Compatibility
• Contributing
• License

Why

Most agent skill collections go stale the same way: a skill names a repository, a tool, or a ticket system, reality moves, and nothing updates the skill. It then confidently instructs an agent to do something that no longer works.

Mandor rests on one rule that prevents this:

Skills hold method. Adapters hold facts.

A skill never names your repository, your tracker, your tools, or your teammates. It reads them from docs/agents/ in the repository it runs in. You fill those five small files in once per repository. The same skill then works in your project and in a stranger's, and it does not rot when your setup changes.

Features

• Two orchestrators. A product owner that decides whether and what, and a tech lead that decides how and in what order. Both plan, delegate to subagents, and verify independently: a subagent's claim of "done" is never accepted as evidence.
• Take only what you need. Install one capability, one scope, or everything. Orchestration comes with any scope you touch, because without it the rest is a pile of playbooks with nothing routing work into them.
• Nothing is required. Every optional tool slot may stay none and every skill still works. A skill that breaks without a tool is treated as a bug.
• A vault that learns. Session records go to an append-only journal, and durable facts are distilled into linked context. History and current truth never share a file.
• Writing standards, enforced. No em dashes, no antithesis constructions, no inflated vocabulary. The rule binds both the documents your agent writes and this repository. CI fails on violations.
• Host and platform agnostic. No agent product is named in any skill. The CLI is dependency-free Node and runs on Windows, macOS and Linux.

Install

Requires Node 18 or newer. Nothing is written outside the destinations you name.

npx @fetot/mandor setup                    # guided wizard, start here
npx @fetot/mandor install --all            # or: everything, no questions
npx @fetot/mandor install --scope product  # or: one scope
npx @fetot/mandor install --capability strategy,design

Every install refuses to overwrite existing files unless you pass --force, and --dry-run prints what would happen without touching anything.

To install from a clone instead of npm:

git clone https://github.com/fetot/mandor.git
cd mandor && ./install.sh --help     # forwards to the same Node entry point

For agents

Everything the interactive wizard asks has a flag, so an agent can run it without a terminal:

npx @fetot/mandor setup --yes --scope engineering --vault ~/knowledge --attach .
npx @fetot/mandor init

Read docs/AGENT-SETUP.md for what each command writes, the questions to ask the user first, and the vault-boundary decision tree. The full reference is also at mandor.ferdisma.web.id/docs. The shared-adopt skill runs this procedure end to end and hands off to shared-setup to fill in the adapters.

Install with the skills CLI

npx skills add fetot/mandor --list
npx skills add fetot/mandor --skill shared-adopt

This copies the named skill files only. It does not scaffold a vault, attach a repository, or fill in an adapter. npx @fetot/mandor remains the way to wire up vaults, repositories, and the capture hook, whichever way the skills were installed.

Commands

| command | what it does | |---|---| | setup | guided wizard: skills, language, vaults, repositories, hook, then confirm | | init [dir] | attach a repository (default: current directory) in one step | | install | install skills; interactive picker, or --all, --scope, --capability | | list | show the catalog and the recommended third-party skills | | check | what is installed; --satellite <repo> reports a repository's wiring; --json for machines | | update | refresh installed skills to the current release; never adds unpicked ones | | vault <dir> | scaffold a knowledge vault | | attach <repo> --vault <dir> | drop the adapter into a repository and link it to a vault | | defaults | record facts shared across your projects so new repos are seeded |

setup and init accept every question as a flag: --all / --scope <s> / --capability <list>, --lang english|indonesian, --vault <dir> (repeatable), --attach <repo> (repeatable or comma-separated), --hook, and --yes to skip the confirmation. init accepts --vault <dir> to link a vault in the same step.

Global flags: --dest <dir>, --lang english|indonesian, --force, --dry-run, --defaults <file>, --no-defaults, --satellite <repo>.

update is not a download. npx always fetches the latest release; update refreshes the copies already on your machine, only the ones you installed, and never rewrites answers you wrote into a repository's docs/agents/.

Skills

| scope | capability | use when | |---|---|---| | product | orchestration | raw input has to become owned, sequenced work, or should be declined | | product | discovery | a problem or opportunity needs validating before anything is built | | product | strategy | several validated options compete for what comes next | | product | design | a flow or interaction needs product-level shape and quality criteria | | product | delivery | a decision must become a PRD, acceptance criteria, and a handoff | | product | user-story | writing or reviewing a development-ready user story | | engineering | orchestration | an objective becomes a task graph; delegation; independent verification; approval gates | | engineering | development | implementing a feature, fix, refactor, or migration | | engineering | qa | verifying a change against its criteria, independently of whoever built it | | engineering | devsecops | infrastructure, CI/CD, release, secrets, incidents, deployment records | | shared | setup | reading your repositories and filling the adapters from what is actually there | | shared | adopt | an agent installing and wiring up this kit itself, without a terminal | | shared | knowledge-capture | recording what a session did, what resisted, and what comes next | | shared | writing-standards | any prose at all; loaded before writing |

Bold entries are added automatically whenever anything from their scope is installed.

How it works

~/.claude/skills/            the method, installed once, shared by every project
  product-orchestration/
  engineering-qa/ ...

~/code/your-repo/            the facts, one set per repository
  docs/agents/
    issue-tracker.md         where work items live, what a key looks like
    triage-labels.md         the five triage states
    domain.md                vocabulary, decisions, output language
    tools.md                 which optional tools exist here (all default to none)
    knowledge.md             where the vault is, relative to this repo
    .mandor                  which release seeded this, and from where

~/knowledge/                 one vault per context boundary, shared by its repos
  context/                   current, verified facts
  plans/<capability>/<era>/<status>/
  journal/<year>/            append-only session records

A skill that needs a fact reads the adapter. A skill that finishes work writes to the journal. Periodically the journal is distilled into context/, and a distilled fact that contradicts what context/ already says is the most valuable signal in the system: it means reality moved.

Configuration

Adapters are the configuration. Fill in docs/agents/*.md in each repository. The shared-setup skill does most of this for you by reading the repository.

Defaults. mandor defaults writes a small file of answers that repeat across your projects (language, tracker, tools). New repositories are seeded from it. Values are copied at seed time; nothing reads the defaults file afterwards, so every repository stays self-describing.

Environment.

| variable | effect | |---|---| | MANDOR_SKILLS_DIR | where skills are installed when --dest is not given | | MANDOR_PROJECT_DIR | tells the capture hook which project it is in, on any host | | NO_COLOR | plain output, no colour or box-drawing characters |

Capture hook. hooks/capture-reminder.js runs at the end of a session and notes when nothing was journaled. It finds the vault through the adapter, so it behaves per project and stays silent where there is none. Wire it to whatever your host calls "end of session":

{ "type": "command", "command": "node <path>/hooks/capture-reminder.js" }

Your settings file is never edited for you; the wizard prints the snippet.

Compatibility

| | | |---|---| | Operating systems | Windows, macOS, Linux (tested in CI on all three) | | Node | 18, 20, 22 | | Runtime dependencies | none | | Agent hosts | any that reads skill files; no product is named in any skill | | Default skills directory | ~/.claude/skills, override with --dest or MANDOR_SKILLS_DIR |

The per-repository docs/agents/ convention is compatible with mattpocock/skills on purpose: configure once, both work. Recommended third-party skills are listed in vendor.txt and installed from their upstream, never bundled here.

See docs/PLATFORMS.md and docs/MULTI-PROJECT.md for the details, including the vault boundary rule, which is the decision most worth getting right.

Contributing

Read docs/DESIGN.md first. It is short and it is binding: it defines what may never appear inside skills/. The test is one sentence. If a statement is only true in one repository, it is not a skill. Move it to an adapter.

CI enforces the design contract: zero dependencies, zero absolute paths, zero project names in distributable files, requires: [] on every skill, and the writing standards. See CONTRIBUTING.md.

License

MIT