Gitpulse
Merged
Size
M
Change Breakdown
Docs60%
Maintenance40%
#65241docs(agents): split scoped workflow guidance

Agent guidance reorganized into scoped directories

VI
vincentkoc
·Apr 12, 2026

Documentation rules have been split into focused guides for docs/, ui/, and scripts/ directories, eliminating duplication and fixing a file-size guideline contradiction.

The repository's root agent guidance file had accumulated domain-specific policies that belonged closer to the code they governed. Rules for documentation links, UI internationalization, and script wrappers were scattered across the root level, creating maintenance headaches when guidelines drifted apart.

Scoped agent guides now live alongside the directories they serve. The docs/ directory owns Mintlify rules and i18n pipeline guidance. The ui/ directory owns generated locale bundle rules. The scripts/ directory owns wrapper preferences and heavy-check lock behavior. Each new guide includes a matching CLAUDE.md symlink.

The root AGENTS.md now points to these scoped guides rather than restating their content. A contradictory file-size guideline (previously both ~500 and ~700 LOC limits existed) has been resolved to a single ~700 LOC threshold.

Plugin architecture guidance was also tightened across extensions/, src/plugin-sdk/, and src/plugins/ scoped guides, emphasizing manifest-first control planes and explicit boundaries between control-plane and runtime concerns.

View Original GitHub Description

Summary

  • Problem: the repo root AGENTS.md had grown into a mixed policy file, ops note dump, and duplicated boundary guide, with repeated rules already owned by scoped AGENTS.md files.
  • Why it matters: duplicated instructions drift, and the root file already had a real contradiction on file-size guidance.
  • What changed: added scoped AGENTS.md guides for docs/, ui/, and scripts/, added matching CLAUDE.md symlinks, and trimmed the root file so it points to scoped guides instead of restating them.
  • What did NOT change (scope boundary): no runtime code, tests, CI behavior, or package boundaries changed.

Change Type (select all)

  • Bug fix
  • Feature
  • Refactor required for the fix
  • Docs
  • Security hardening
  • Chore/infra

Scope (select all touched areas)

  • Gateway / orchestration
  • Skills / tool execution
  • Auth / tokens
  • Memory / storage
  • Integrations
  • API / contracts
  • UI / DX
  • CI/CD / infra

Linked Issue/PR

  • Closes #
  • Related #
  • This PR fixes a bug or regression

Root Cause (if applicable)

  • Root cause: the root guide accumulated domain-specific policy that should have lived in scoped files, so the same rules existed in multiple places and one file-size guideline drifted into contradiction.
  • Missing detection / guardrail: no scoped AGENTS.md existed for docs/, ui/, or scripts/, so the root file became the dumping ground.
  • Contributing context (if known): the repo already had a good scoped pattern for extensions/, src/plugin-sdk/, src/channels/, src/plugins/, and shared test helpers, but it was not applied consistently.

Regression Test Plan (if applicable)

  • Coverage level that should have caught this:
    • Unit test
    • Seam / integration test
    • End-to-end test
    • Existing coverage already sufficient
  • Target test or file: AGENTS.md, docs/AGENTS.md, ui/AGENTS.md, scripts/AGENTS.md
  • Scenario the test should lock in: scoped instructions exist where domain-specific policy lives, and the root file no longer carries contradictory LOC guidance.
  • Why this is the smallest reliable guardrail: this is documentation/policy structure, not runtime behavior.
  • Existing test that already covers this (if any): git diff --check
  • If no new test is added, why not: there is no executable behavior change to lock with unit or integration coverage.

User-visible / Behavior Changes

None.

Diagram (if applicable)

Before:
[root AGENTS] -> [repo-global rules + docs rules + UI rules + scripts rules + duplicated boundary rules]

After:
[root AGENTS] -> [repo-global rules + pointers]
              -> [docs/AGENTS]
              -> [ui/AGENTS]
              -> [scripts/AGENTS]

Security Impact (required)

  • New permissions/capabilities? (No)
  • Secrets/tokens handling changed? (No)
  • New/changed network calls? (No)
  • Command/tool execution surface changed? (No)
  • Data access scope changed? (No)
  • If any Yes, explain risk + mitigation:

Repro + Verification

Environment

  • OS: macOS
  • Runtime/container: local repo checkout
  • Model/provider: N/A
  • Integration/channel (if any): N/A
  • Relevant config (redacted): N/A

Steps

  1. Audit repo-local AGENTS.md files and compare scope overlap.
  2. Split docs/UI/scripts guidance into scoped guides and add required CLAUDE.md symlinks.
  3. Trim root AGENTS.md duplication and remove contradictory LOC guidance.

Expected

  • Root guide stays repo-global.
  • Domain-specific rules live in scoped guides.
  • No duplicate numeric LOC guidance remains in the root file.

Actual

  • Matches expected.

Evidence

Attach at least one:

  • Trace/log snippets
  • Failing test/log before + passing after
  • Screenshot/recording
  • Perf numbers (if relevant)

Human Verification (required)

  • Verified scenarios: audited all repo-local AGENTS.md files, confirmed new scoped guides exist, confirmed CLAUDE.md symlinks point at AGENTS.md, confirmed root diff removes duplicated boundary/docs/UI content.
  • Edge cases checked: root no longer contains conflicting 500 vs 700 LOC guidance; no stray numeric LOC text remains in the new scoped guides.
  • What you did not verify: no runtime/test/CI behavior because this PR does not change code paths.

Review Conversations

  • I replied to or resolved every bot review conversation I addressed in this PR.
  • I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

  • Backward compatible? (Yes)
  • Config/env changes? (No)
  • Migration needed? (No)
  • If yes, exact upgrade steps:

Risks and Mitigations

  • Risk: a moved rule could become harder to find if reviewers only read the root file.
    • Mitigation: the root guide now explicitly points at docs/AGENTS.md, ui/AGENTS.md, and scripts/AGENTS.md.

Plugin Architecture Alignment

This PR now also tightens the plugin-related AGENTS guidance around the current architecture direction captured in ~/.spec/2026-04-11_ocplugins.md:

  • manifest-first control plane
  • targeted activation planning
  • narrow runtime resolution instead of broad registry materialization
  • versioned host/kernel seam over ambient host reachability
  • global mutable runtime registry treated as transitional compatibility, not target design
© 2026 · via Gitpulse