docs: add AI agent governance layer (CLAUDE.md files + Workflows SOP) - #42
Merged
Conversation
- Define non-negotiable architectural and workflow rules for AI coding agents - Document package topology, dependency-isolation constraints, and version-family boundaries - Establish structured response formatting, communication standards, and build/test/pack commands - Add index of nested project guidance for sensitive and feature-specific areas
- Add standardized procedures for extending core libraries with tests, docs, and changelog updates - Document end-to-end workflow for creating new pluggable feature packages with dependency isolation and version-family setup - Define release preparation and publishing checklist, including branching, versioning, CI/CD dispatch, and post-release verification
…chitecture - Define high-sensitivity operating constraints for the Features engine and module lifecycle - Document two-tier feature model and strict dependency-direction rules across abstractions, engine, built-in, and pluggable packages - Capture engine internals and invariants for module discovery, flag provider precedence, and module self-gating behavior - Add implementation guardrails for future pluggable features and clarify current Sitecore roadmap status
…nternals - Document locking model across in-process and cross-process paths, including mutex scope and gating - Define atomic write and index persistence invariants to prevent unsafe refactors - Capture known concurrency and durability hazards, including mutex growth and cross-process factory behavior - Add modification guardrails requiring multi-process validation and explicit risk callouts
…amework support - Define high-sensitivity constraints and backward-compatibility expectations for active production consumers - Document framework-specific architecture, language-version pinning, and dependency boundaries unique to this package - Capture CI coverage gap and required manual validation workflow for compatibility changes - Clarify release-versioning path and maintainer decision points for compatibility package publishing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR introduces a structured governance layer for AI coding agents operating in the PowerCSharp repository. It establishes operating principles, architectural constraints, and step-by-step SOPs that any AI agent (Claude, Copilot, or similar) must read and respect before touching code, documentation, or CI/CD configuration.
Changes included:
Root CLAUDE.md: repository-wide baseline covering the agent role, nine non-negotiable operating principles (understand before edit, never commit without approval, dependency-isolation rule, version-family boundaries, etc.), package topology, versioning model, structured output format (XML tags), tone guidelines, build/test/pack commands, and a nested documentation index.
Workflows.md: step-by-step SOPs for the three most common recurring tasks — extending a Core library, building a new pluggable Feature package from scratch, and cutting a release. Each SOP includes pre-flight checks, ordered steps, and explicit confirmation gates before destructive or high-blast-radius actions.
src/Features/CLAUDE.md: Features Framework-specific guidance covering the two-tier model (Built-in vs. Pluggable), the strict dependency direction that must never be inverted, engine internals (assembly scanning, composite flag resolution, DI wiring), Sitecore roadmap constraints, and a checklist for adding a new Feature package.
src/Features/PowerCSharp.Feature.Cache.Disk/CLAUDE.md: high-risk operational notes for the disk-backed cache package, documenting the cross-process file-locking model, hazards (lock starvation, race on eviction, path-length limits on Windows), and the narrow scope of safe changes to that area.
src/PowerCSharp.Compatibility/CLAUDE.md: .NET Framework layer constraints, the CI isolation gap (the Compatibility solution is not wired into the main CI pipeline), safe and unsafe change categories, and a reminder that this package is a live production dependency for real .NET Framework consumers.
No production code, tests, or build configuration is modified by this PR.