azcodr: Enterprise Architecture & Agentic Engineering Starter Template

Production-ready, battle-tested software architecture governed by problem-first topology alignment, strict systemic atomicity, evolutionary architecture tipping points, 100% open-source standards, true incremental TDD nano-cycles, and zero speculative bloat.

🌟 Architectural Pillars

1. Problem-First & Topology Alignment: Architecture emerges strictly from problem constraints and execution targets (Problem-First; zero preemptive tool bias). Architectural styles match the problem topology: Hexagonal for enterprise backends, Platform Scripting for extensions, Data-Oriented Design for game engines, Command Pipeline for CLIs, and Game Loop for canvas games.
2. Systemic Atomicity: Every rule, skill, database transaction, and code unit adheres to the Single Responsibility Principle (SRP)—indivisible, self-contained, orthogonal, and composable with zero conjunction naming.
3. Evolutionary Architecture & Refactor-Before-Add: To eliminate AI-accelerated architectural drift, code graduates across 5 deterministic tipping points. Refactor structure first under existing green tests before implementing new features. Never append code into rotting files.
4. True Incremental TDD & Nano-Cycles: Prohibit batch-test dumps ("Test-First Waterfall"). Follow Uncle Bob's Three Laws: write one micro-assertion at a time, verify RED failure output, write minimal code to turn GREEN, and refactor under green with Ping-Pong pair programming.
5. 100% Open-Source & Open Standards: Standardized exclusively on open-source solutions and vendor-neutral specifications (OpenTelemetry, OPA, OpenFGA, Protocol Buffers, OpenAPI 3.1, JSON Schema Draft 2020-12, CloudEvents, Semgrep, Trivy, Gitleaks, Cosign).
6. Zero-Assumption Framework: Ground truth is established solely through workspace configurations, code evidence, or direct user confirmation.
7. Hardened Multi-Tenancy (When Applicable): 4 interchangeable isolation models (AST query interceptor filtering, schema-per-tenant, database-per-tenant, transparent storage proxy) backed by transaction-scoped session context.
8. Dynamic Extensibility Without Code Branching:
   • Custom tables and columns via hybrid core relational/document models and validated JSON Schema.
   • Pluggable business logic via Common Expression Language (CEL), GoF Strategy registries, and WebAssembly (Wasm) micro-sandboxes.
   • Tenant lifecycles via durable workflows (Temporal / BPMN 2.0 / statecharts).
   • Server-Driven UI (SDUI) component registries and W3C Design Tokens Community Group (DTCG) theming.
9. Resilient Database Architecture: Full ACID atomicity, Transactional Outbox pattern eliminating dual-writes, declarative expand-contract zero-downtime migrations, and continuous Point-In-Time Recovery (PITR).
10. Workspace Knowledge Hub & Token Economy: In-workspace system knowledge graphs and Lightweight Architectural Decision Records (ADRs) to eliminate repetitive token-expensive discovery loops.

🗂️ Workspace Architecture

.
├── .agents/
│   └── skills/                       # Specialized on-demand agentic workflows
│       ├── agentic-architect/        # Authoring & auditing agent configurations
│       ├── clean-code-refactor/      # Refactoring code smells with GoF & Clean Code
│       ├── compliance-audit/         # SOC 2, ISO 27001 & OWASP open-source audits
│       ├── lets-build/               # Architecture interview & project bootstrapper
│       ├── product-analyst/          # INVEST user stories & Gherkin criteria
│       └── relentless-questioner/    # Context-aware dynamic interrogation loop
├── docs/
│   ├── knowledge/                    # Institutional knowledge & domain contracts
│   │   └── ubiquitous_language.md    # Living Ubiquitous Language glossary template
│   └── rules/                        # 28 cohesive single-responsibility domain rules
├── AGENTS.md                         # Lean root agentic configuration (< 120 lines)
├── CLAUDE.md -> AGENTS.md            # Filesystem symlink for harness parity (Claude Code)
├── agents.md -> AGENTS.md            # Filesystem symlink for harness parity (Codex / Standard)
├── GEMINI.md -> AGENTS.md            # Filesystem symlink for harness parity (Antigravity / Gemini)
├── .cursorrules -> AGENTS.md         # Filesystem symlink for harness parity (Cursor)
├── .windsurfrules -> AGENTS.md       # Filesystem symlink for harness parity (Windsurf)
├── memory.md                         # Master memory hub & Lightweight ADR ledger
└── README.md                         # Project documentation

📋 Progressive Disclosure Rules Catalog (docs/rules/)

The architecture enforces 28 cohesive, single-responsibility domain rules. Read on demand to prevent prompt context bloat:

| Domain | Rule Reference File | Key Focus & Invariants | |---|---|---| | TDD & Isolation | test_driven_development.md | Outside-In TDD, Uncle Bob's 3 Laws, 100% coverage, test isolation & DB rollback. | | Clean Code | clean_code.md | Naming, small functions, CQS, SLAP, DRY, DbC, zero side-effects. | | Design Patterns | design_patterns.md | Adapter, Factory, Strategy, Result <T, E>, and GoF pattern catalog. | | Type Safety | type_safety.md | Compiler strictness, branded nominal types, type discriminators across polyglot languages. | | Authentication | authentication.md | In-memory access tokens, refresh token rotation (RTR), WebAuthn passkeys. | | Authorization | authorization.md | CASL, OPA Rego policy engines, OpenFGA ReBAC, server guards. | | Multi-Tenancy | multitenancy_architecture.md | Tenant context, 4 isolation models, RLS, dynamic schemas, pluggable logic & YAGNI gates. | | API Architecture | api_architecture.md | HTTP status codes, sync vs async (202), _actions, idempotency keys, cursor pagination, OCC, versioning. | | Server-Driven UI | server_driven_ui.md | Backend-driven layout schemas, multi-renderer component registries, DTCG tokens & YAGNI gate. | | Database Design | database_design.md | Relational integrity, FKs, CHECK constraints, Canonical 6 audit fields, ACID transactions, Outbox CDC. | | Database Operations | database_operations.md | Zero-downtime expand-contract migrations, N+1 elimination, DataLoader, indexing, pooling, PITR. | | Caching | caching.md | Cache Port semantics, Cache-Aside, jittered TTLs, XFetch stampede defense & YAGNI gate. | | Security & Compliance | security_compliance.md | OWASP Top 10 defenses, rate limiting, crypto, SOC 2 Type II, ISO 27001, GDPR data erasure. | | DevOps & CI/CD | devops_ci_cd.md | Shift-left trunk-based CI, OCI distroless containers, Secretlint/Trivy DevSecOps, zero-downtime CD. | | Cloud-Native 12-Factor | cloud_native.md | 12-Factor (2026 Edition), OpenTelemetry (OTel), stateless isolates. | | Error Architecture | error_handling.md | Fail-fast schema validation, structured OTel/Pino tracing, RFC 7807 envelopes. | | Feature Flags | feature_flags.md | OpenFeature standard, Flipt/Unleash backends, targeting, kill switches & YAGNI gate. | | Transactional Email | transactional_email.md | Declarative templates (MJML/JSON), safe interpolation, SMTP integration testing. | | UI/UX Architecture | ui_ux_architecture.md | Design triage gate, persistent app shell, collapsible sidebar, dual-experience portals, dev persona. | | Frontend Architecture | frontend_architecture.md | Accessible headless primitives, WCAG 2.2 AA, server cache sync, form validation, 5-tier state, URL navigation. | | Requirements Engineering | requirements_engineering.md | User stories vs requirements, 3 C's, INVEST vertical cake slicing, Gherkin. | | Product Ownership | product_ownership.md | Product Backlog Management, OKRs, Kano/MoSCoW/RICE, Product Value, empiricism. | | Project Management | project_management.md | Work-In-Progress limits (WIP = 1), SMART developer tasks, Definition of Done. | | Domain-Driven Design | domain_driven_design.md | Ubiquitous Language, Bounded Contexts, Aggregates, Capability Mapping. | | CQRS & Projections | cqrs.md | Evolutionary CQRS spectrum, YAGNI defense, read projections, outbox CDC. | | Workflow State Machines | workflow_state_machines.md | Configurable workflows, in-aggregate invariant FSMs, transition guards & audit logs & YAGNI gate. | | Agentic Governance | agentic_configuration.md | Progressive disclosure, ADR ledger, workspace sovereignty, continuous learning, YAGNI gate triad. | | Relentless Questioning | relentless_questioning.md | Dynamic context-aware interrogation loops, adaptive decision trees. |

🛠️ Specialized Skills Catalog (.agents/skills/)

• agentic-architect: Authoring, auditing, and modularizing agent configurations and skills.
• clean-code-refactor: Refactoring code smells with Clean Code, SOLID, and modern design patterns.
• compliance-audit: Conducting SOC 2, ISO 27001, and OWASP audits using open-source scanners.
• lets-build: Conducting architecture interviews to finalize stack, frameworks, package managers, and bootstrapping projects.
• product-analyst: Aligning OKRs, backlog ordering (Kano/MoSCoW/RICE), INVEST stories, and Gherkin criteria.
• relentless-questioner: Dynamic context-aware interrogation loops before planning and coding.

🚀 Starting a New Project with /lets-build

This repository serves as an enterprise architectural starter template. When beginning a new software project:

Step 1: Initialize Workspace with npx

Pull and scaffold the complete enterprise architectural template into your project directory using npx:

npx azcodr my-new-project
cd my-new-project

(Or run npx azcodr directly inside your target directory).

Step 2: Invoke the /lets-build Skill

In your AI coding assistant (Google Antigravity, Claude Code, Cursor, or OpenHands), trigger the workflow:

/lets-build

(Or simply prompt: "Let's build a new project from this template.")

Step 3: The Problem-First Architectural Interview

The agent will execute a deep research loop and systematically derive your technical stack strictly from problem constraints (with zero preemptive tool bias) across 5 tiered dimensions:

1. Problem Space & Topology Classification: What real-world problem is being solved? What data moves and transforms? Classifies the system topology:
   • Topology A: Web SaaS / Cloud Microservices
   • Topology B: Browser Extension (Manifest V3)
   • Topology C: Game Engine / High-Performance Simulator (Bare metal, GPU)
   • Topology D: Browser / Canvas Game (HTML5 Canvas / WebGL / WebGPU)
   • Topology E: Desktop Application / CLI Utility (Native POSIX/Windows)
   • Topology F: Systems / Embedded / Cryptographic Library
2. Physical & Operational Constraints: Latency budget (hard real-time <16.6ms frame loop vs interactive low-latency vs batch), memory model & GC tolerance (zero-GC pause tolerance vs managed throughput GC vs single-threaded event loop), and concurrency topology.
3. Architectural Style Derivation: Matches style strictly to topology (Hexagonal for enterprise backends, Platform Scripting for extensions, Data-Oriented Design for game engines, Game Loop for canvas games, Command Pipeline for CLIs).
4. Emergent Stack & Toolchain: Derives the optimal language (C, Rust, TypeScript, Go, Java, C#, Python), package manager, and build system strictly from the verified constraints.
5. Targeted Invariants (Strictly Topology-Scoped): Inquires only into the dimensions relevant to the selected topology (e.g. database migrations for web backends, content script isolation for extensions, CLI flags for CLIs; zero Docker, Kubernetes, or OpenAPI bloat for non-backend projects).

Step 4: Blueprint Synthesis & Explicit Approval

The agent consolidates all your choices into a formal Architectural Specification & Technology Blueprint and records a formal ADR in memory.md.
The agent will stop and ask for your explicit confirmation before generating any code.

Step 5: Deterministic Topology Scaffolding (Strict YAGNI)

Once confirmed, the agent automatically executes:

1. Topology-aware directory scaffolding via bootstrap_workspace.sh . <topology> <language>, generating 0 speculative folders (e.g. extensions get no Kubernetes or OpenAPI specs; CLIs get no Dockerfiles).
2. Targeted contract and entrypoint generation matching the derived topology.
3. Build manifests, strict linter/formatter configurations, and boundary smoke test (scripts/smoke_test.sh).
4. Project-Specific README Generation: Completely replaces the starter template README.md with clean, project-specific documentation (mission, stack highlights, quickstart setup, build/test commands, and directory structure), preserving links to docs/rules/.
5. Deterministic validation via validate_agentic_configs.sh and initial smoke test execution.
6. Handover Gate to Domain Analysis: Halts technical scaffolding and instructs the user to invoke product-analyst and relentless-questioner for domain modeling.

🏛️ Workspace Memory & Knowledge Hub

• 📖 Living Ubiquitous Language Glossary: Authoritative domain vocabulary contract.
• 📜 Lightweight ADR Ledger: Formal Architectural Decision Records and governing rules.