UISampleSpark: Constitution-Driven Development

Part 3 of the UISampleSpark Series — Governance and AI

From Implicit Rules to Explicit Governance

For nearly seven years, UISampleSpark operated on implicit rules. Experienced contributors knew that all data access went through repository interfaces. They knew that

FromSqlRaw

In early February 2026, that changed. Over the course of roughly 48 hours, the project underwent its most significant transformation since its founding — not in features or framework versions, but in governance, compliance, and development workflow. The catalyst was a new approach called Constitution-Driven Development, powered by AI agents that could analyze a codebase and surface its unwritten rules.

Discovering the Constitution

The transformation began with a fundamental question: "What are the implicit rules governing this codebase?"

Using the

speckit.discover-constitution

• 94 C# source files across 6 projects
• 10 configuration files (

  .csproj

  ,

  global.json

  ,

  .editorconfig

  )
• 5 GitHub Actions workflows
• 4 documentation files (README, CHANGELOG, CONTRIBUTING, SECURITY)

The analysis identified 16 high-confidence patterns — conventions the codebase followed with 100% consistency:

ConfigureAwait(false)

But the analysis also revealed gaps. Two stood out:

• ILogger usage: 0% of service classes used structured logging. They operated silently, with no way to trace execution flow in production.
• XML documentation: Only about 40% of public APIs had XML doc comments, leaving Swagger UI incomplete.

The Educational Scope Decision

One of the most consequential discoveries was what the analysis initially flagged as a deficiency: the project had no authentication or authorization.

Through interactive discussion, this was reframed not as a bug but as a feature. The project's educational mission required that authentication be absent — its presence would obscure the CRUD patterns that were the project's reason for existing. This decision was formalized as Principle IV: Security Posture (Educational Scope):

"This is an educational/reference project demonstrating ASP.NET Core patterns. It intentionally omits authentication, authorization, and other production-hardening features to focus on core CRUD patterns."

The Eleven Principles

From 16 discovered patterns and 10 interactive questions, the team synthesized 11 Core Principles into a formal constitution document:

1. Code Quality and Safety — Nullable types enabled, latest C# language version, strictest analysis level.
2. Architecture and Design Patterns — Repository pattern, dependency injection, async/await,

   ConfigureAwait(false)

   in libraries, no raw SQL.
3. Error Handling and API Contracts — Global exception handler, RFC 7807 ProblemDetails, proper HTTP status codes.
4. Security Posture — Educational scope with explicit limitations documented. HTTPS in non-development environments.
5. Testing Standards — MSTest framework, Arrange-Act-Assert pattern, 25% code coverage baseline.
6. CI/CD and DevOps — Three required GitHub Actions workflows: test-and-build, security scanning, Docker build-and-push.
7. Observability and Health — Structured logging with

   ILogger<T>

   , health checks at

   /health

   , Swagger/OpenAPI documentation.
8. Documentation Standards — README maintained, CHANGELOG updated, XML documentation on public APIs.
9. Dependency Management — Latest .NET version adopted, quarterly package audits,

   global.json

   enforces SDK version.
10. Docker and Containerization — Multi-stage builds, Alpine base images, non-root user, Hadolint compliance.
11. AI-Assisted Development — Session work organized under

    /.documentation/copilot/

    , drafts and audit reports structured.

Each principle was classified by enforcement level: MUST (mandatory, blocking), SHOULD (strongly recommended), or MAY (optional best practice). The constitution contained 30 MUST requirements in total.

The Compliance Gap

With the constitution formalized, an audit revealed the codebase was at 82% compliance. Twenty-seven of 30 MUST requirements were met. Three critical violations were identified:

Violation 1: Missing Test/Build CI Workflow

Despite having Docker and CodeQL workflows, the project had no GitHub Actions workflow that ran

dotnet test

Violation 2: No Global Exception Handler

The project lacked an

IExceptionHandler

Violation 3: Insufficient Security Documentation

The existing

SECURITY.md

The Sprint to 100%

Each fix was implemented with the rigor the constitution demanded:

Fix 1: Test and Build Workflow

A new

.github/workflows/test-build.yml

Fix 2: Global Exception Handler

A new

GlobalExceptionHandler

Fix 3: Security Documentation

The

SECURITY.md

Bonus: Structured Logging

ILogger<T>

GlobalUsings.cs

NullLogger<T>.Instance

All 240 tests passed after the update.

SpecKit Spark: AI Agents for Lifecycle Management

The constitution work revealed gaps in AI-assisted development tooling. Three new agents were created:

The Evolve Constitution Agent

Analyzes pull request review patterns for recurring violations. When multiple PRs show an uncovered pattern, it generates a Constitution Amendment Proposal with change history tracking.

The Quick Fix Agent

Provides a lightweight workflow for small changes that don't justify full specification overhead. Bug fixes and configuration changes receive constitution compliance validation without the full spec/plan/tasks ceremony.

The Release Agent

Archives completed development artifacts, generates Architecture Decision Records from key decisions, creates CHANGELOG entries, and prepares a clean slate for the next development cycle.

These three agents expanded SpecKit Spark from 13 to 16 specialized agents, covering the complete project lifecycle.

The Final Audit

After all fixes were implemented, a final compliance audit confirmed:

Lessons from the Transformation

Constitution First, Implementation Second

Having a formal constitution revealed gaps that would have remained as technical debt indefinitely. The codebase already exhibited 80%+ consistency across most patterns — formalization made implicit rules explicit and exposed the critical gaps.

Educational Scope Is a Feature, Not a Bug

Authentication omission was initially flagged as incomplete. Reframing it as an intentional design decision, prominently documented, transformed a perceived weakness into a governance strength.

ILogger Breaks Tests — Plan for It

Adding

ILogger<T>

AI Agents Need Lifecycle Support

Feature development workflows (spec, plan, tasks) are necessary but insufficient. Projects also need support for quick fixes, constitution evolution, and release management.

What Changed in 48 Hours

• 1 formal constitution with 11 principles and 30 MUST requirements
• 3 critical fixes (CI workflow, exception handler, security docs)
• 4 service classes updated with structured logging
• 3 new AI agents for lifecycle management
• 14 files changed with +12,600 lines added
• 0 regressions — all 240 tests passing throughout

Additional Resources

• UISampleSpark Constitution on GitHub
• SpecKit Spark Documentation
• RFC 7807 — Problem Details for HTTP APIs

UISampleSpark Series

This is part 3 of a five-part series tracing the evolution of UISampleSpark from a simple CRUD tutorial to a comprehensive web UI exploration platform.

1. A Developer's Swiss Army Knife — The founding philosophy and core architecture
2. Seven Years of .NET Modernization — Navigating the annual .NET upgrade cycle
3. Constitution-Driven Development (this article) — How governance and AI transformed project quality
4. Seven UI Paradigms, One Backend — Comparing seven frontend approaches side by side
5. Modern DevOps as a Living Reference — Containerization, CI/CD, and cloud deployment

Project Links: GitHub | Live Demo | Docker Hub