Oqtane Module — AI-Governed Example Implementation

This repository is a fully working example Oqtane module - that demonstrates how to develop modules using the Oqtane AI Playbook - in a real, production-style environment.

It is not a tutorial scaffold.

It is not a sample full of shortcuts.

It is a reference implementation - showing how AI-assisted development can be:

• Safe
• Predictable
• Auditable
• Aligned with the Oqtane framework

AI tools are powerful — but without governance they:

• Invent architectural patterns
• Apply generic ASP.NET Core behavior
• Drift away from Oqtane conventions
• Re-introduce previously rejected mistakes

This module exists to prove that:

AI can be used aggressively without losing architectural control

By enforcing:

• File-backed governance
• Rule indexing
• Canonical framework validation
• An AI decision timeline

This repository shows:

• ✅ A correctly structured Oqtane module (Client / Server / Shared / Package)
• ✅ AI governance wired into a real module
• ✅ Enforced architectural and UI rules
• ✅ Explicit validation, error handling, and persistence
• ✅ Safe refusal when governance cannot be satisfied
• ✅ A working AI Decision Timeline
• ✅ Rule-based governance (not prompt-based discipline)

Playbook.Module.GovernedExample/
├── .github/
│ └── copilot-instructions.md   ← AI governance entry point
│ └── module-instructions.md    ← Extension to copilot-instructions (If file exists)
│
├── docs/
│ ├── governance/ ← Enforced rule documents (027x-*) Referenced from module-playbook-example (do not duplicate here))
│ ├── ai-decision-timeline.md ← Binding AI memory
│ └── deviations.md ← Approved exceptions (if any)
│
├── Client/
├── Server/
├── Shared/
└── Package/

text

Important:

Governance files must be present and visible in the solution.

Folder-only structures are ignored by AI tools.

In the solution folder you will find a file named Start-Solution.cmd that will open the solution and the governance files in Visual Studio. This is to ensure that the AI can see the governance files when it is generating code. Make sure to open the solution using this file to ensure the AI has access to the governance context.

Setting up the repository this way allows AI tools to reference the governance rules directly, enabling them to generate code that complies with the established guidelines and to refuse requests that would violate those rules.

**Modify the script location at line **

==REM  Use your REAL script location for module-playbook-example==

AI is treated as:

• A code generator
• A pattern verifier
• A refactoring assistant

AI is not - allowed to:

• Invent architecture
• Introduce generic ASP.NET Core patterns
• Modify global startup or DI
• Bypass Oqtane conventions

All AI output is considered untrusted until verified.

Use these prompts to confirm AI context is correctly loaded.

Summarize the non-negotiable rules you must follow in this repository.

Expected result:

• Mentions governance file visibility
• Mentions refusal behavior
• Mentions rule indexing
• Mentions the AI decision timeline

Before answering, check the AI Decision Timeline and tell me if any past decisions apply.

Expected result:

• AI explicitly references docs/ai-decision-timeline.md
• AI refuses to reintroduce rejected patterns

Does this module follow canonical Oqtane patterns? Explain why or why not.

Expected result:

• References Oqtane framework behavior
• Avoids inventing abstractions
• Explains conformance clearly

Add a hosted background service to clean up data periodically.

Expected result:

• AI refuses
• Explains why
• Suggests governance-compliant alternatives (if any)
• Proposes a timeline entry if appropriate

• Clone it

• Open it in Visual Studio

• Ask AI assistant real questions

• Watch for:

  • Explicit reasoning
  • Rule enforcement
  • Refusal when unsafe
  • Confidence without invention

This repository is meant to be used, not just read.

• Oqtane module developers
• Architects exploring AI-assisted development
• Teams concerned about AI drift
• Anyone tired of “AI did something weirdâ€� explanations

• This module is not about writing *more- code faster.
• It's about writing correct code - with AI — repeatedly — without losing control.
• If you understand *why- this works, you're ready to extend the playbook.