Simple Man icon

# Simple Man High-compression professional communication mode for coding agents. Simple Man is not a persona. It is a communication policy: > Minimum user-facing words; same work quality. It is designed for users who work with agents for many hours and want lower cognitive load without making the agent passive, less careful, or less proactive. ## What it changes It compresses user-facing communication: - no preambles - no praise - no filler - no repeated recaps - no generic closing offers - sentence fragments and compact labels when clear - compact status updates - compact final answers - compact review findings - compact explanations and plans ## What it does not change It must not reduce: - repository search - usage search - dependency tracing - impact analysis - validation - test/lint/typecheck effort - proactive detection of related correctness issues ## Examples Same model, same failing mini-project, same task. Only the communication policy changed. These are real captured Codex final answers from [`evals/reports/codex-skill-comparison.md`](./evals/reports/codex-skill-comparison.md). ### Expired-session auth bug Prompt: inspect a Node auth API where expired sessions are still accepted, fix it, run tests, and hand off root cause, files changed, validation, and remaining risk.
No Simple Man With Simple Man

Engineering Handoff

Root cause: authenticate accepted any session returned by store.get(token) and never checked session.expiresAt against the store clock.

Files changed:

  • src/middleware.js: rejects sessions with missing/non-numeric expiresAt or expiresAt <= store.now().
  • test/auth.test.js: added coverage for the expiration boundary where expiresAt === now.

Validation: npm test passed, 3/3 tests.

Remaining risk: This assumes expiresAt and store.now() use the same timestamp unit, and that auth store implementations provide the existing now() API.

Fixed.

  • Root cause: authenticate trusted store.get(token) and never checked session.expiresAt.
  • Files changed: src/middleware.js
  • Validation: npm test -> pass, 2/2 tests.
  • Remaining risk: none identified.
Result: both fixed the bug and passed npm test. Answer length: 601 chars vs 221 chars, 63% shorter.
### Payment idempotency retry bug Prompt: inspect a Python payment ledger where retrying with the same idempotency key creates another local charge, fix it, run tests, and hand off root cause, files changed, validation, and remaining risk.
No Simple Man With Simple Man

Root cause

The charge path was append-only. After a gateway timeout, the fake provider had already accepted a charge, but retrying with the same idempotency key created a new provider charge and the ledger had no local idempotency lookup to return an existing local charge.

Files Changed

  • ledger.py: added idempotency-key indexes in FakeGateway and PaymentLedger.
    • Provider retries now replay the original remote charge.
    • Ledger retries now return the existing local charge instead of appending another.
  • test_ledger.py: extended the retry test to verify no extra gateway call or local charge is created after the local charge exists.

Validation

Command: PYTHONDONTWRITEBYTECODE=1 python3 -m unittest -v

Result: passed, 1 test run.

Remaining Risk

This is still an in-memory implementation. A production version would need persistent idempotency storage with transaction/concurrency protection, and likely validation that reused idempotency keys match the original customer and amount.

Root cause: no idempotency-key lookup; timeout lost the accepted provider charge locally, and retries created new charge records.

Files changed:

  • ledger.py: added provider/local idempotency maps; same key returns existing charge; mismatched reuse raises ValueError.
  • test_ledger.py: added regression for repeated same-key retry.

Validation: PYTHONDONTWRITEBYTECODE=1 python3 -m unittest -v -> passed, 2 tests.

Remaining risk: idempotency state is in-memory only; no durable/concurrent store in this fixture.

Result: both fixed the retry bug and passed python3 -m unittest -v. Answer length: 1022 chars vs 520 chars, 49% shorter.
### Unsafe migration rollout order Prompt: inspect a SQLite rollout where a migration drops legacy_sessions.expires_at before the backup reads it, fix it, run tests, and hand off root cause, files changed, validation, and remaining risk.
No Simple Man With Simple Man

Root Cause

rollout.py applied migrations/001_drop_expires_at.sql before running backup_legacy_sessions.sql. The backup query still selects legacy_sessions.expires_at, so the column was gone before the backup could read it.

Files Changed

rollout.py: moved backup_legacy_sessions(conn) before apply_drop_migration(conn).

Validation

Command: python3 -m unittest test_rollout.py

Result: passed, 1 test ran OK.

Remaining Risk

The focused test now covers the required order: backup reads expires_at, then the migration drops it. Remaining risk is limited to behavior outside this small rollout path, such as real backup storage durability or additional migrations not represented in the current test.

Root cause: rollout() ran apply_drop_migration() before backup_legacy_sessions(), so expires_at was dropped before the backup query selected it.

Files changed: rollout.py

Validation: python3 -m unittest test_rollout.py passed, 1 test.

Remaining risk: none known; only the focused repo test exists and was run.

Result: both fixed the rollout order and passed python3 -m unittest -v. Answer length: 736 chars vs 324 chars, 56% shorter.
## Agent support This repo ships two activation surfaces: - full skill: `skills/simple-man/SKILL.md` - compact always-on runtime policy: `AGENTS.md`, `AGENTS.md.snippet`, `CLAUDE.md`, `GEMINI.md` | Agent/tool | Path | | --- | --- | | OpenAI Codex / Agent Skills | `skills/simple-man/SKILL.md`, `AGENTS.md`, `AGENTS.md.snippet` | | Claude Code | `CLAUDE.md`, optional global skill copy | | Gemini CLI | `GEMINI.md`, or configure Gemini to read `AGENTS.md` | | Qwen Code | `AGENTS.md`, optional global skill copy | | Cursor / Windsurf / Cline / Copilot / Continue / Zed / Junie | `AGENTS.md`, or copy `AGENTS.md.snippet` into that agent's native rule file | | Amp / OpenCode / Kilo / Roo / Aider / other AGENTS.md agents | `AGENTS.md` | Always-on project files do not invoke `$simple-man`; they inline a compact runtime policy to avoid loading full skill overhead on every turn. Agent-specific dotdir rule files are not committed here by default. They are target-project activation files, not the source of the skill. See [INSTALL.md](./INSTALL.md) for per-agent setup notes. ## Benchmark This repo includes two Codex-based token benchmark suites: - `runtime_economics`: coding-agent cost, including instruction overhead and long-session amortized net. - `reference_compression`: Caveman README-style output compression against a verbose normal helpful baseline. ```bash make bench-dry-run make bench-refresh make bench make bench-check make bench-compare-sample make bench-reference-dry-run make bench-reference-refresh make bench-reference make bench-reference-check ``` The benchmark compares `control`, generic `terse`, `simple_man_runtime`, `simple_man_candidate`, `simple_man_skill`, and optional Caveman arms. Runtime headlines use output compression and long-session net; reference headlines use output-only compression vs `normal`. See [evals/README.md](./evals/README.md). ## Install Install Simple Man as an always-on Codex communication policy: ```bash curl -fsSL https://raw.githubusercontent.com/Maksim-Burtsev/simple-man/master/install.sh | bash ``` **Important: Simple Man is always-on after install. This is expected.** The installer copies `skills/simple-man` to `~/.codex/skills/simple-man` and writes the compact runtime policy into `~/.codex/AGENTS.md`. ## Codex plugin package To add the repo-local plugin package to Codex: ```bash codex plugin marketplace add Maksim-Burtsev/simple-man --ref master codex plugin add simple-man@simple-man ``` Plugin install makes the skill available in Codex. Always-on behavior comes from the installer writing global Codex instructions. ## Recommended usage Use it as the default communication layer for Codex when you want minimum user-facing words without reducing search, validation, or implementation effort.