Context
During design discussion for the uni-plugin CLI (issue #3), a conceptual distinction emerged about the rules field and its relationship to governances, disciplines, and orchestrative multi-agent architectures. This should be captured as a governance in the plugin-design governance document.
The Problem with "Always-On"
The rules field (Cursor .mdc files with alwaysApply: true) assumes a single-agent session where injecting context to every interaction is acceptable. In an orchestrative multi-agent model — a team of subagents each with a specific focus — "always-on" means "injected into every subagent regardless of role." That is wasteful and degrades focus.
The correct mental model: always-on context should be the HCF (Highest Common Factor) of all agents — constraints that genuinely apply to every agent regardless of role. In practice, this is very small (e.g. "never commit secrets", "use conventional commits"). Everything beyond that is noise for most subagents.
Decisions to Capture
-
rules = HCF-only. The rules field is for truly universal constraints — content that every agent in every role must always follow. Not the place for governances or disciplines.
-
rules survives for backward compatibility and simple single-agent use cases where orchestration is not involved. Its scope is intentionally narrow.
-
Governances and disciplines are not rules. They are cross-cutting shared content loaded on demand by whichever agent, skill, command, hook, or MCP server needs them. Delivery is via prepare (materialize on install/update) + uni-plugin governance show <name> (stable name-to-content resolution at runtime).
-
Decision tree for always-on guidance:
- Truly universal, every agent, every role →
rules/ (HCF)
- Cross-cutting but role/task-scoped →
governances/ + uni-plugin governance
- Agent-specific → agent definition file
- Skill-specific → SKILL.md body
Action
Add this reasoning to the plugin-design governance (governances/plugin-design.md and .plugin/governances/plugin-design.md) under a new section — "Rules vs Governances" or similar — so plugin authors understand:
- What belongs in
rules/
- What belongs in
governances/
- Why the distinction matters in orchestrative systems
Context
During design discussion for the
uni-pluginCLI (issue #3), a conceptual distinction emerged about therulesfield and its relationship to governances, disciplines, and orchestrative multi-agent architectures. This should be captured as a governance in the plugin-design governance document.The Problem with "Always-On"
The
rulesfield (Cursor.mdcfiles withalwaysApply: true) assumes a single-agent session where injecting context to every interaction is acceptable. In an orchestrative multi-agent model — a team of subagents each with a specific focus — "always-on" means "injected into every subagent regardless of role." That is wasteful and degrades focus.The correct mental model: always-on context should be the HCF (Highest Common Factor) of all agents — constraints that genuinely apply to every agent regardless of role. In practice, this is very small (e.g. "never commit secrets", "use conventional commits"). Everything beyond that is noise for most subagents.
Decisions to Capture
rules= HCF-only. Therulesfield is for truly universal constraints — content that every agent in every role must always follow. Not the place for governances or disciplines.rulessurvives for backward compatibility and simple single-agent use cases where orchestration is not involved. Its scope is intentionally narrow.Governances and disciplines are not
rules. They are cross-cutting shared content loaded on demand by whichever agent, skill, command, hook, or MCP server needs them. Delivery is viaprepare(materialize on install/update) +uni-plugin governance show <name>(stable name-to-content resolution at runtime).Decision tree for always-on guidance:
rules/(HCF)governances/+uni-plugin governanceAction
Add this reasoning to the
plugin-designgovernance (governances/plugin-design.mdand.plugin/governances/plugin-design.md) under a new section — "Rules vs Governances" or similar — so plugin authors understand:rules/governances/