Principles

An always-on ruleset for coding agents, shipped as a user-level plugin for Claude Code, Codex, Copilot CLI, and OpenCode.

Every session and every subagent gets one compact set of operating principles injected at start: observable done, existing path first, data shape before control flow, honest surface area, durable raw artifacts, hypothesis debugging, risk gates, the repository as system of record, and mechanical enforcement over prose.

Design

The skill follows progressive disclosure: the always-injected SKILL.md is a short map holding the principles that apply to every task, and depth lives in per-activity references the agent opens only when the task matches.

skills/principles/
├── SKILL.md                     # the map: core loop, universal principles, roadmap
└── references/
    ├── writing-code.md          # designing, planning, implementing changes
    ├── code-review.md           # reviewing code, diffs, PRs
    ├── debugging.md             # bugs, flaky tests, regressions
    └── upstreaming.md           # turning a user-stated principle into an upstream PR
hooks/inject.js                  # session/subagent start: inject the map (stateless)
hooks/learn.js                   # user prompt submit: one-line learning-loop nudge (stateless)
hooks/claude-codex-hooks.json    # SessionStart + SubagentStart + UserPromptSubmit
hooks/copilot-hooks.json         # sessionStart + subagentStart
.opencode/plugins/principles.mjs # OpenCode system-prompt injection

There are no modes, no state files, no commands, and no configuration. The plugin is on when installed and off when disabled or uninstalled through the host's plugin manager. Uninstalling leaves nothing behind.

Learning loop

The plugin improves with use. Every user prompt carries a one-line nudge: if the message states a durable preference, correction, or principle that generalizes beyond the current repository, the agent finishes the task, then offers to upstream it. On the user's yes, the agent follows references/upstreaming.md: clone this repo in a temp directory, land the rule where the editing invariants say it belongs, run the tests, and open a PR the user can review and merge — or reject.

Privacy is a hard boundary of that protocol: nothing from the originating session — repo names, paths, code, error text — may appear in the PR. The agent authors fresh generalized examples instead. The nudge fires on Claude Code and Codex; on OpenCode and Copilot the roadmap entry in the always-injected map covers the same path.

Install

Claude Code:

/plugin marketplace add xingyaoww/principles
/plugin install principles@principles

Codex:

codex plugin marketplace add xingyaoww/principles

Then open /plugins, install Principles, review and trust the lifecycle hooks, and start a new thread.

Copilot CLI: the manifests live in .github/plugin/ (hooks in hooks/copilot-hooks.json). Add this repository through Copilot's plugin marketplace flow and trust the lifecycle hooks.

OpenCode from a checkout:

{ "plugin": ["./.opencode/plugins/principles.mjs"] }

The hooks require node on the non-interactive shell PATH. If Node is missing, the skill files still work; the session-start hook reports the missing dependency once per session, and the subagent hook stays quiet.

Development

npm test

The tests mechanically enforce the design: the roadmap's references must resolve (and every reference must be on the roadmap), the injected context must stay under a size budget, and all host manifests must agree on the plugin name. CI runs on Linux and Windows.

This package derives its lifecycle hook architecture from Ponytail (see NOTICE.md). The harness-tending principles draw on OpenAI's "Harness engineering" post, and the code-review reference shares DNA with OpenHands' code-review skill. The learning loop — nudging the agent to persist generalizable lessons from live sessions — is inspired by NousResearch's hermes-agent and its background memory/skill review.