Give your coding agent
a real playbook.

Install & initialize

Node.js 22 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. A manifest, top-level source file, or common source root in the current directory also counts as project evidence.

$ 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 session show --session <id> --client claude-code --json
$ 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. When a project-local install exists, prefer ./node_modules/.bin/mancode, check its --version once, and do not mix it with a global CLI during the task.

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.

Set a design policy

The design policy is an explicit, opt-in Continuity feature for UI work. mancode init does not create it. When no valid policy is active, design context fails open to preserve, so ordinary coding and workflow recovery are not blocked. Regardless of policy state, emoji cannot serve as interface icons in navigation, buttons, actions, controls, or status indicators. Emoji remain allowed in user-authored content, chat messages, editorial copy, and domain data.

Choose a direction before implementation

For a new UI surface or aesthetic redesign, if the user has not chosen a visual direction, the agent presents 2–3 distinct, product-appropriate directions with concise tradeoffs and a recommendation, then waits for a choice. Broad adjectives or quality constraints such as enterprise, clean, modern, premium, or not flashy do not count as a selected visual direction. Scoped UI fixes, work inside an established design system, and tasks with an already selected direction continue directly.

Configure and inspect

$ mancode design status --json
$ mancode design configure --expected-revision 0 --preset refine --icons lucide --emoji forbid-as-interface-icon --motion purposeful --browser-validation when-available
$ mancode design context --json
$ mancode design configure --expected-revision 1 --preset experimental --confirm-experimental
$ mancode design disable --expected-revision 2

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

/skill:man
/skill:manba
/skill:manteam

/man
/manba
/manteam

/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.

Complete public command index

This index is checked against the executable Commander tree. Compatibility-only spellings and hidden release plumbing are intentionally excluded.

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.

Newly generated man entries create tasks with --delivery (planning policy 3). This opt-in binds an approved baseline and a separate delivery record in one versionable plan, using the project's directory convention or doc/ by default. Other modes, older tasks, and Solo handoffs keep their existing contracts.

workflow delivery <TaskRef> inspect|verify|confirm|review|sync|check|publication supports one module-level review, real command evidence, manual confirmation, document writeback, and separate commit/publication checks. Mutating actions require the active session and latest expected revision. A relevant command can cover multiple criteria through --acceptance AC-1,AC-2 without repeated runs. Review checks goal coverage, concrete defects, and unnecessary complexity; zero findings is valid. Missing upstreams or failed pushes mean unpublished delivery, not a business blocker. This mechanism does not certify an agent's semantic judgment or production readiness.

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
$ mancode context session show --session <session-id> --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 --scope-file scope.json --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 adapter upgrade --platform cursor --dry-run

• refresh-project updates detected project facts and reports stale adapters.
• Claude Code reads refreshed context through hooks.
• Cursor, Codex, Copilot, ZCode, Kimi Code, Qoder, and DeepSeek Harness use static files; publish a staged repair from an active session with --confirm --operation-id <operationId>.
• 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 adapter upgrade --platform claude-code --dry-run
$ mancode adapter upgrade --platform claude-code --confirm --operation-id <operationId> --session <id> --client <client>

Remove the CLI

$ npm uninstall -g mancode

Troubleshooting

mancode init rejects the directory

Git is not required. A common manifest, top-level source file such as .html, .js, .py, or .go, or source root such as src/, app/, or web/ counts as project evidence. Detection inspects only the current directory's top level, so enter the actual source directory rather than an asset-pack parent. Safe empty directories are supported interactively or explicitly with --empty; non-empty directories containing only assets or documentation are still rejected. Home and filesystem root directories remain protected.

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, preview mancode adapter upgrade --platform <platform> --dry-run, then repair it from an active session with --confirm --operation-id <operationId>. For ZCode, Copilot, Kimi Code, Qoder, and DeepSeek Harness, also confirm that the installed client release supports repository skills, prompt files, or project commands.

Claude Code hooks do not run

Restart Claude Code after initialization, then check mancode status. Repair V3 managed content through the adapter preview and confirmation flow above; the legacy hook architecture uses mancode init --legacy --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, source, 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.