Skip to content

docs: clarify rules scope — HCF-only in orchestrative multi-agent systems #4

Description

@unional

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

  1. 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.

  2. rules survives for backward compatibility and simple single-agent use cases where orchestration is not involved. Its scope is intentionally narrow.

  3. 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).

  4. 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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions