Give your coding agent
a real playbook.

Install & initialize

Node.js 20 or newer is required. Run the initializer inside an existing project or a safe empty directory, then choose one or more agent adapters. Windows CMD, PowerShell, and Git Bash are supported; Git is optional and only improves team-mode detection.

$ npm install -g mancode
$ cd your-project
$ mancode init

Non-interactive or targeted initialization

--platform accepts a comma-separated adapter list. In automation, pair it with --yes; use --empty only when you intentionally want generic initialization in an empty directory.

$ mancode init --platform codex,cursor
$ mancode init --yes --platform codex --no-team
$ mancode init --empty --platform claude-code --lang en

Verify the installation

$ mancode status
$ mancode status --json

The human-readable result names the project, current mode, team state, installed adapters, and each adapter's ready or not ready status. JSON is the stable choice for scripts; mancode status --brief --json returns the compact public Continuity view used by coding agents. A ready adapter means its required generated files are present; it does not guarantee that an already-open agent session has reloaded them.

Files & privacy

mancode works locally, scans only the current project, and sends no telemetry. It deliberately does not rewrite your project's .gitignore, so your team—not the installer—decides which generated context belongs in version control.

Continue work across sessions

mancode stores goals, requirements, plans, validation results, and handoff notes under a stable TaskRef. A new chat window or supported CLI can resume the same task and load a purpose-specific Context Pack.

$ mancode status --brief --json
$ mancode context session new --client claude-code
$ mancode context resume <namespace:ULID> --session <id> --client claude-code
$ mancode context show --purpose orient --session <id> --client claude-code

The generated /man, /manba, and /manteam entries use the same records. Use the CLI form for diagnostics, automation, or manual recovery.

Choose the smallest mode

Task length is not the deciding factor. Choose the lightest mode that leaves enough evidence and review for the cost of a wrong decision.

Invoke a mode

Mode names are portable, but invocation follows the extension model of each agent. Run them in the agent chat—not in your operating-system shell. /mansolo or $mansolo explicitly returns to the default solo mode.

/manba
/man
/manteam
/manps
/mansolo

$manba
$man
$manteam
$manps
$mansolo

man.prompt.md
manba.prompt.md
manteam.prompt.md
manps.prompt.md
mansolo.prompt.md

$man
$manba
$manteam

CLI reference

The CLI installs adapters and enforces durable workflow state. Run state-reading commands from an initialized project. Invalid transitions fail safely instead of silently editing workflow metadata.

Study the /man workflow

/man is a progressive nine-step protocol. It first makes the decision inspectable, then lets the user choose between a lightweight handoff, a plan-only result, or governed execution. Every gate is backed by Continuity files under .mancode/<namespace>/workflows/<ULID>/.

The nine steps and their gates

Requirements ledger

The ledger prevents a polished plan from hiding unresolved assumptions. It needs a goal, non-empty confirmed scope, all seven coverage dimensions, and at least one required acceptance criterion. If the technical stack applies, technicalDecisions cannot be empty. Save input outside or inside the workflow directory; finalization writes canonical requirements.json and requirements.md.

{
  "version": 1,
  "goal": "Refactor authentication without changing login behavior",
  "confirmedScope": ["Extract token validation into the existing auth service"],
  "excludedScope": ["Changing the identity provider", "Redesigning login UI"],
  "technicalDecisions": ["Keep the existing TypeScript and session stack"],
  "defaults": ["Preserve current timeout values"],
  "blockingUnknowns": [],
  "coverage": [
    { "dimension": "platform", "status": "confirmed", "rationale": "Node service" },
    { "dimension": "core_scope", "status": "confirmed", "rationale": "Refactor only" },
    { "dimension": "technical_stack", "status": "confirmed", "rationale": "Existing stack retained" },
    { "dimension": "data_and_persistence", "status": "not_applicable", "rationale": "No schema change" },
    { "dimension": "performance", "status": "defaulted", "rationale": "No regression from baseline" },
    { "dimension": "compatibility", "status": "confirmed", "rationale": "Public behavior unchanged" },
    { "dimension": "security", "status": "confirmed", "rationale": "Token checks stay fail-closed" }
  ],
  "acceptanceCriteria": [
    {
      "id": "AC-LOGIN",
      "description": "Valid and expired tokens retain current behavior",
      "required": true,
      "method": "automated"
    }
  ]
}

$ mancode workflow requirements <local:ULID> finalize --file requirements-input.json --expected-revision <revision> --session <session-id>

A successful result says ready. A result of needs_clarification is a hard stop: resolve blockingUnknowns, regenerate the input, and finalize again.

The Step 4 decision

$ mancode workflow handoff <local:ULID> --to solo --expected-revision <revision> --session <session-id>
# after solo implements and verifies
$ mancode workflow handoff <local:ULID> --complete --expected-revision <revision> --session <session-id>

$ mancode workflow plan <local:ULID> confirm --plan-decision governed_execution --expected-revision <revision> --session <session-id>

$ mancode workflow plan <local:ULID> confirm --plan-decision plan_only --expected-revision <revision> --session <session-id>

All three choices require an active man workflow, confirmed requirements, and plan.md. Revise the plan with workflow plan ... revise; every successful mutation returns the revision required by the next command.

A valid Continuity sequence

Continuity uses explicit TaskRefs and expected revisions. The CLI owns every durable mutation; do not edit metadata files or use the legacy --step protocol.

# Bootstrap an actor and explicit session
$ mancode team identity create --name "Your name"
$ mancode context session new --client codex --json

# Create, discover, and inspect a task
$ mancode workflow create man "refactor auth module" --session <session-id> --json
$ mancode workflow list --json
$ mancode workflow show <local:ULID> --json

# Requirements and plan gates (use the revision returned by each command)
$ mancode workflow requirements <local:ULID> finalize --file requirements-input.json --expected-revision <revision> --session <session-id>
$ mancode workflow plan <local:ULID> revise --file plan.md --expected-revision <revision> --session <session-id>
$ mancode workflow plan <local:ULID> confirm --plan-decision governed_execution --expected-revision <revision> --session <session-id>

# Record canonical review and verification ledgers
$ mancode workflow review <local:ULID> apply --file review-ledger.json --expected-revision <revision> --session <session-id>
$ mancode workflow verify <local:ULID> apply --file verification-ledger.json --expected-revision <revision> --session <session-id>
$ mancode workflow complete <local:ULID> --expected-revision <revision> --session <session-id>

Verification, manual checks, and remediation

# Update the canonical ledgers after a remediation
$ mancode workflow review <local:ULID> apply --file review-ledger.json --expected-revision <revision> --session <session-id>
$ mancode workflow verify <local:ULID> apply --file verification-ledger.json --expected-revision <revision> --session <session-id>
$ mancode workflow complete <local:ULID> --expected-revision <revision> --session <session-id>

Workflow subcommands

Platforms & adapters

mancode adapts to the extension points each surface actually offers. A platform marked preview is installed, but its runtime discovery or invocation remains dependent on that platform's current release.

Refresh project context

Use refresh-project when the stack or project structure changes. Use refresh-style after a design-system migration, a substantial UI change, or when a non-UI project gains an interface.

$ mancode refresh-project
$ mancode refresh-style
$ mancode install cursor --force

• refresh-project updates detected project facts and installed static adapters.
• Claude Code reads refreshed context through hooks.
• Cursor, Codex, Copilot, and ZCode use static files; reinstall a specific adapter with --force if you need to repair or regenerate it.
• Only UI projects receive design-token-specific guidance.

Uninstall safely

Uninstalling one adapter preserves user-authored rules, instructions, unrelated Claude settings, and Continuity workflow authority. Use context compact --dry-run to inspect eligible runtime retention records.

Remove one adapter

$ mancode uninstall cursor --force

Reinstall one adapter

$ mancode uninstall claude-code --force
$ mancode install claude-code

Remove the CLI

$ npm uninstall -g mancode

Troubleshooting

mancode init rejects the directory

A safely empty directory is supported interactively, or explicitly with --empty. A non-empty directory still needs a recognized project marker or Git metadata so mancode does not initialize an arbitrary folder by accident.

The agent does not see a newly installed mode

Reload or restart the agent so it rereads repository instructions. Run mancode status; if the adapter is not ready, run mancode install <platform> --force. For ZCode and Copilot, also confirm that the installed client release supports repository skills or prompt files.

Claude Code hooks do not run

Restart Claude Code after initialization, then check mancode status for both hook files and registration in .claude/settings.json. Repair with mancode install claude-code --force. The hooks use Node.js and do not require Bash or jq.

Cursor rules do not trigger

Confirm that .cursor/rules/mancode-*.mdc and .cursor/commands/*.md exist. Core context and solo rules are persistent; higher-intensity rules are description-triggered, so invoke the generated mode command explicitly.

A workflow command is rejected

Treat the rejection as a gate, not a file-corruption problem. Use mancode workflow list --json to discover TaskRefs, then mancode workflow show <namespace:ULID> --json to inspect metadata, revision, aggregate, and blockers. Do not edit Continuity metadata manually.

Project facts became stale

After adding Git, a manifest, dependencies, or validation scripts, run mancode refresh-project. Use refresh-style for UI tokens. Then repair a static adapter only if its generated files need regeneration.