Steward

Explore enough to choose correctly. Once chosen, build no more than necessary. Harden according to consequence, not code size.

Steward is a phase-aware engineering policy for AI coding agents. It minimizes accidental complexity without reducing required behavior, correctness, verification, or understanding.

It is intentionally distinct from Ponytail. Ponytail remains useful as an aggressive anti-overbuilding specialist; Steward is designed as an engineering operating policy for agents that also discover requirements, choose architectures, delegate work, and integrate results. Both plugins can be installed side by side without sharing commands, state, configuration, or environment variables.

Policy model

• Discovery: preserve materially different options until actual constraints select among them.
• Execution: implement the smallest coherent design that fully satisfies the selected requirements.
• Hardening: never trade security, privacy, data integrity, compatibility, operability, rollback safety, or necessary verification for less code.

Existing helpers, standard-library features, platform primitives, installed dependencies, local code, and new dependencies are candidates—not automatic stopping points. Semantics, clarity, testability, repository fit, and operational risk decide which candidate fits.

AGENTS.md is the concise always-on kernel. STEWARD.md is the complete specification. The main steward skill routes ambiguity and detailed interpretation to that specification.

Modes

Mode	Behavior
normal	Complete phase-aware policy. Default.
build	Stronger scope discipline for bounded implementation whose architecture, scope, and acceptance criteria are settled.
off	Disable automatic Steward instruction injection.

Build mode never reduces hardening and is never inferred merely because a task looks bounded. Select it explicitly after architecture, scope, and acceptance criteria are settled. It is deliberately downshifted to normal when lifecycle hooks inject Steward into a new subagent; a parent prompt can explicitly apply build pressure when the delegated task is itself bounded.

Use /steward normal|build|off; /steward reports the current mode. Persist a default with /steward default <mode>, STEWARD_DEFAULT_MODE, or:

{ "defaultMode": "normal" }

in ~/.config/steward/config.json (Windows: %APPDATA%\steward\config.json). Say stop steward to deactivate the current session.

Claude and Codex modes are isolated by session. Resume and compaction preserve the active mode; /clear starts fresh from the configured default.

Claude status line

Steward can optionally show (STEWARD:NORMAL) or (STEWARD:BUILD) in Claude's status line. Off mode emits no Steward segment. Install it explicitly with /steward-statusline install; inspect it with /steward-statusline status; remove it with /steward-statusline remove.

Claude exposes one shared status-line command. Steward therefore installs a stable, user-owned compositor that replays the same session input to the previous command and appends Steward's segment. Installation never edits the other command or its plugin, and removal restores the exact prior statusLine object. Steward does not take this shared setting automatically.

Specialist skills

• steward-prune is a bounded, post-implementation pressure test. It reports safely removable complexity without reopening requirements or optimizing for line count.
• steward-debt inventories deliberate steward: simplifications, their ceilings, revisit triggers, and upgrade paths.
• steward-help shows the command and configuration reference.

The upstream gain scoreboard is intentionally absent: Ponytail v4's benchmark does not measure Steward's policy.

Supported surfaces

• Claude Code
• Codex CLI and the Codex app
• Pi
• MCP clients
• agents that read AGENTS.md

Other upstream adapters were removed so every supported surface receives the same policy and regression coverage.

Install

Claude

/plugin marketplace add distincthead/steward
/plugin install steward@steward

Start a new session after installation. The plugin activates Steward, tracks mode changes, and injects normal policy into subagents.

Codex

codex plugin marketplace add distincthead/steward
codex plugin add steward@steward

Open /hooks, review and trust the lifecycle hooks, then start a new thread.

Pi

pi install git:github.com/distincthead/steward

The Pi extension registers Steward commands, persists mode in the session, and injects the shared kernel before agent turns.

MCP

cd steward-mcp
npm install
node index.js

The server exposes a steward prompt and read-only steward_instructions tool. See steward-mcp/README.md.

Generic AGENTS.md consumers

Copy AGENTS.md to the project or user-level location your agent reads. This provides normal policy without lifecycle hooks or mode state.

Commands

Command	What it does
/steward [normal | build | off]	Report or change the active mode.
/steward default <mode>	Persist the default for new sessions.
/steward-prune [target]	Report safely removable post-implementation complexity.
/steward-debt [target]	Inventory deliberate simplification markers.
/steward-statusline install | status | remove	Manage Claude's optional (STEWARD:MODE) badge.
/steward-help	Show the compact reference.

Evaluation

Steward does not currently make measured impact claims. The inherited Ponytail benchmarks remain available in Git history, but are not part of this release because they did not evaluate Steward's policy.

Development

npm ci --prefix steward-mcp
npm test

The test suite covers policy alignment, identity and concurrent-session isolation, resume/compaction persistence, Claude/Codex hooks, build-mode subagent downshifting, Pi, MCP, commands, packaging, and uninstall behavior.

License and attribution

MIT. Steward is derived from DietrichGebert/ponytail; the original copyright and license notice are retained.