# mancode puts six questions in front of the agent before it writes code

> A workflow harness that wraps existing coding agents rather than replacing them, with five governance modes from a lightweight solo default to a multi-agent review path. Its own notes are candid about which platform integrations are still unverified on a real host.

**whitelonng/mancode** — AI coding agent harness. Five modes: practice to playoffs. Stop your AI from over-engineering. Code like a man. Elbow out bloat. Score clean.    ... AI 代理调度框架。五种模式：训练到季后赛。 别让你的 AI 过度设计一切。像个man一样，肘开冗余，干净得分。

- Repository: https://github.com/whitelonng/mancode
- Website: https://whitelonng.github.io/mancode/
- Stars: 363 · Forks: 19
- Language: TypeScript
- License: AGPL-3.0
- Published: 2026-09-18 · Updated: 2026-09-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/whitelonng-mancode

## Six questions before any code gets written

The default workflow asks the agent to answer six questions before it edits anything: what problem this change solves, whether an existing implementation can be reused, what the smallest viable change is, whether a new system has to be split out at all, how non-trivial logic gets a minimal runtime check, and what is uncertain, which is self-checked first and raised with the user only if it stays unclear.

The motivation is given as a concrete failure. Without a layer like this, a request as ordinary as adding a logout button can produce a new component, a new stylesheet and a new colour variable. With it, the agent is pointed at the Button component and the design tokens already in the project and reuses them.

Related checks sit alongside. When a UI exists, the project UI dependencies, Tailwind configuration, CSS variables and existing components are inspected so the agent matches the design system rather than inventing one. A separate health scan, mancode manps, looks for stale TODOs, unused dependencies, risky dependencies, mixed icon systems and hardcoded design values.

The stated order of preference is reuse first, meaning existing code, the standard library, an installed dependency or a one-line fix, and only then a new abstraction.

## Five governance modes, and solo is the default

Six workflow modes ship, described as running from daily training to playoff intensity.

solo is the default and is deliberately ceremony-free. It requires no identity, no session, no TaskRef and no formal plan. The model picks the implementation, runs verification proportionate to the risk, and inspects the real diff, with a reviewer added only when there is a reason for one.

/man is the heavy path. It keeps requirement clarification, plan approval, scope, verification, review and commit requirements. It researches the project, guides clarification on requirements that would change the approach, suggests workable options, and produces a persistent plan that can be confirmed. After the plan is confirmed the execution route is a choice: keep only the plan, hand it to a single solo session, or continue the full run.

A managed handoff from /man to solo changes who executes and not the delivery bar. Missing, failed or stale evidence still blocks completion, and the exemptions available to a plain solo session do not apply to a handed-over task.

## The ledger outranks a passing test

The most opinionated rule in the documentation concerns what counts as done. A reviewer process exiting successfully is not the same as the review ledger having passed. A verification command returning zero is not the same as acceptance being met. The final state is the structured ledger and the completion gate.

Findings follow the same discipline: each one needs concrete evidence and a stated user impact. Repairs and rechecks follow the policy the task already had, extra checks are added when a new problem appears, and review is not repeated to a fixed number of rounds.

Delivery artefacts are held to the same standard. Titles, summaries, commits, pull requests and handoffs should be built from accepted goals, the authoritative baseline, the state that was actually read back, and the diff for that task. External state that cannot be read back has to be marked as unverified rather than assumed.

The boundary on the model is stated in one line: it may choose tools and implementation steps freely, but it cannot rewrite approved goals and acceptance criteria.

## Platform support is listed with its unverified parts

Adapters are integrated for Claude Code, Cursor, Codex in the ChatGPT desktop app, Codex CLI, GitHub Copilot, ZCode, Kimi Code, Qoder and DeepSeek Harness. Each platform keeps its own man-style entry point and is connected through a static bootstrap to the shared Context Pack and workflow authority.

The per-platform notes are where this project is unusually candid. Claude Code hides the bootstrap and the original mode skills and does not depend on hooks by default. Cursor gets rules files and command files. Codex, Kimi Code, Qoder and DeepSeek Harness each get a managed AGENTS.md block plus skills in a platform-specific directory.

But the notes also record what is unproven. For ZCode, project-level skill discovery and slash commands still need the workspace path confirmed before any promise is made. Kimi Code and Qoder host discovery paths still need real verification. DeepSeek Harness has a confirmed file discovery contract, yet GUI discovery, dual-window sessions and subagent propagation still need a real host. Windsurf, Cline and Roo Code are listed as planned later rather than shipped.

Installation also does not install every adapter. The interactive init treats detected agents as a hint only.

## Node 22.5 is the hard requirement and Git is optional

The runtime floor is Node.js 22.5.0 or higher, with native support claimed for macOS, Linux, Windows CMD, PowerShell and Git Bash. Claude Code hooks are executed by Node, so neither Bash nor jq is needed.

Git is not a prerequisite. A project with an existing manifest, top-level source files or a common source directory can initialise directly, and a brand new empty directory is asked whether to initialise as a generic project, so nobody has to know git init first. Without Git installed, initialisation still works and only the automatic team detection degrades to solo. Adding Git or source later is safe, and mancode refresh-project updates the detected project facts and installed static adapters.

```bash
npm install -g mancode
cd your-project
mancode init                      # interactive platform choice
mancode init --platform cursor    # or name one or more platforms
mancode init --platform codex,cursor
mancode init --platform all
```

There are more flags for non-interactive use: --yes to skip the generic project confirmation, --team and --no-team to force the mode either way, --empty to allow a safe empty directory in a script, --lang to pin the initialisation language, and --platform to accept a comma-separated list or all.

## Workflow artefacts live under .mancode, and teams share through typed entities

Anything worth resuming goes to disk. Research, plans, review reports and summaries are written under a namespace and workflow path keyed by a ULID, and the same tree holds the delivery record, checkpoints, reframes and operation recovery state that keep an interrupted run from being mistaken for a finished one.

Cross-session continuity is the reason for that layout rather than a side benefit. Tasks, decisions and verification evidence have to survive a new conversation, and the framework treats confirmed information as the thing that carries over, with a user-confirmed glossary, shared decisions and TaskRef entries used to cut the semantic drift that otherwise appears when several sessions or several agents discuss the same code.

Team mode works through the same idea. The /manteam mode shares confirmed information through typed entities under a shared directory rather than by having agents read each other's notes.

The privacy side runs alongside. Credentials and personal data can be identified locally to produce a redacted copy before logs, configuration fragments or customer material are shared, and sensitive shared writes can be gated, or original values replaced before supported model request fields are sent upstream.

## Version 0.6.10 retired the gateway and added a Keychain vault

The 0.6.10 release removed the local model proxy gateway entirely, and existing users are pointed at a retirement guide to restore their client connections. In its place is an encrypted secrets vault backed by the macOS Keychain, which injects secrets into approved local actions through structured references and returns only a status rather than the value.

The same release fixed pre-start failure receipts, approval summaries and temporary directory cleanup, and tightened multi-line terminal handling where input is not echoed. Two boundaries are stated plainly: the secrets vault does not intercept other tools or model traffic, and acceptance in dedicated environments, including a real keychain lock and a denied authorisation, is still outstanding.

Version 0.6.9 added a numeric menu for mancode upgrade covering the CLI, project rules and skills, and allowed a re-run of interactive init to update an existing project while preserving project tasks, the original policy and anything outside the managed area.

The package is published under AGPL-3.0-only, and the shipped file list is deliberately small: the build output, both READMEs, the logo, the licence and a set of documents covering privacy, secrets and the gateway retirement.

## Conclusion

mancode fits a team that already has several coding agents in use and wants one shared set of plans, review evidence and completion gates across them, rather than a team choosing an agent. It does not fit anyone wanting more autonomy from the model, since the whole design is constraint. Two things to check on a real machine first: several platform integrations are documented as still awaiting host verification, and the Secrets vault shipped in 0.6.10 has dedicated-environment acceptance still outstanding. If you try it, start with solo, confirm the project facts it detects are right, and only then reach for the heavier modes.

## FAQ

### What does mancode install into a project?

Three groups. Workflow authority data covering explicit sessions, TaskRef, Context Pack, workflows and team coordination; skills and modes named solo, /manba, /man, /manteam, /manps and /mansolo; and a platform bootstrap that hooks the original entry points, with legacy hooks installed only under --legacy.

### Which coding platforms does mancode support?

Claude Code, Cursor, Codex in the ChatGPT desktop app, Codex CLI, GitHub Copilot, ZCode, Kimi Code, Qoder and DeepSeek Harness. Windsurf, Cline and Roo Code are listed as planned for later rather than shipped.

### What does mancode require to install?

Node.js 22.5.0 or higher, with native support for macOS, Linux, Windows CMD, PowerShell and Git Bash. Git is optional: initialisation still works without it and only automatic team detection degrades to solo.

### What does the mancode manps scan look for?

Project health problems: stale TODOs, unused dependencies, risky dependencies, mixed icon systems and hardcoded design values.

### Where does mancode store its workflow artefacts?

Research, plans, review reports and summaries are written to a path under .mancode keyed by namespace and workflow ULID, alongside delivery records and checkpoints. Team mode shares confirmed information through typed entities in a shared directory.

### What changed in mancode 0.6.10?

The local model proxy gateway was retired with a guide for restoring client connections, and an encrypted secrets vault backed by the macOS Keychain was added, injecting secrets into approved local actions through structured references and returning only status.

## Sources

- [License: AGPL-3.0](https://github.com/whitelonng/mancode/blob/main/LICENSE)
- [Project website](https://whitelonng.github.io/mancode/)
- [README](https://github.com/whitelonng/mancode/blob/main/README.md)
- [Releases](https://github.com/whitelonng/mancode/releases)
- [whitelonng/mancode on GitHub](https://github.com/whitelonng/mancode)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/whitelonng-mancode