System Architecture and Documentation Map

This document explains the organization, design principles, consumption topology, and documentation cross-linking map of AgenticEngineeringToolbelt.

---

System Overview and Consumption Topology

---

Subsystem Breakdown

Curated Archetypes

The archetypes/ catalog codifies complete technology stacks, directory layouts, and verification recipes:

• Fullstack (.NET + React + SQL): C# .NET 10 Minimal APIs and Controllers, Dapper with stored procedures, SQLite WAL or MSSQL, and React with TypeScript and Zustand.
• C# Console & CLI: C# .NET 10 command-line utilities using System.CommandLine, dependency injection, and subprocess test harnesses.
• Python FastAPI & FastMCP: Python 3.12+ services following the APIs First, MCP Later pattern with FastAPI, FastMCP, and Pydantic v2.
• React, TypeScript & Vite UI: Standalone React frontends with Zustand domain stores, CSS Modules, and Playwright layout audits.
• Modern C++ Native Systems: High-performance C++20/23 libraries using CMake or MSBuild, vcpkg, GoogleTest boundary sweeps, and C-ABI interop.

Engineering Standards

The standards/ directory provides canonical reference specifications for software design, testing, and delivery:

• Master Engineering Style Guide: Foundational SOLID principles, naming rules, APIs First architecture, and polyglot stack conventions.
• Simulation & Control Harnesses: Observable dynamic system design, the Four Pillars of Anti-Test Theatre, deterministic test budgets, and 6-part feedback envelopes.
• Multi-Stage CI/CD Pipelines: Four-stage GitHub Actions quality gate specification mapped to Git Flow branch triggers.
• Code Review Foci & Operational Guardrails: Six orthogonal reviewer foci, formal requirement-to-test traceability (AUTH, DB, GUARD, MCP, SEC, TRANS, UI), and context/deployment guardrails.
• Technical Writing Standards: Simplified Technical English (ASD-STE100) and Google Developer Documentation Style Guide rules.

Executable Agent Skills

The .agents/skills/ directory provides executable skill manifests for AI agent registries:

• engineering-archetype: Guides agents on architectural standards, proactive clarification, and iterative verification.
• test-harness-builder: Generates stress loops, synthetic STDIO transports, diagnostic tap points, and 6-part feedback envelopes.
• scaffold-project: Automates project scaffolding with Git Flow branches, VitePress docs, and 4-stage CI/CD workflows.
• code-review-foci: Runs a 6-focus read-only code review before opening or finalizing a pull request.

Agent Context Rules

The rules/ directory contains drop-in prompt rule files that enforce engineering discipline:

• AGENTS.md: Universal markdown rules for any repository root.
• CLAUDE.md: Execution and verification context tailored for Claude Code.
• GEMINI.md: Tool orchestration and context rules for Google Antigravity and Gemini CLI.

Project Templates

The templates/ directory supplies reusable configuration boilerplates, documentation starters, workflows, and verification scripts:

• configs/: Directory.Build.props, vite.config.ts, tsconfig.json, eslint.config.js, playwright.config.ts, vcpkg.json, pyproject.toml, and dependabot.yml.
• docs/: Starter ARCHITECTURE.md, REQUIREMENTS.md, CHANGELOG.md, and VitePress configuration.
• workflows/: Four-stage ci.yml, codeql.yml, dependency-review.yml, deploy-docs.yml, and release.yml.
• scripts/: commit.sh, git-flow-release.sh, and verify_release.py.

---

Traditional Git Flow and Release Model

Branch Responsibilities

• main: Stores production tagged releases (vX.Y.Z) only. Direct commits are prohibited.
• develop: Serves as the integration branch for completed feature branches.
• feature/*: Branches off develop for isolated feature work and merges back via Pull Request.
• release/*: Branches off develop for version bumping and stabilization, then merges into main and develop.
• hotfix/*: Branches off main for urgent production fixes, then merges into both main and develop.

See the Git Flow Trigger Matrix for the exact CI stages executed per branch.

---

Simulation and Controls Testing Cadence

See Tiered Testing Cadence for detailed gate criteria across all three tiers.

---

Documentation and Cross-Linking Map

Every guide in the toolbelt organizes topics under dedicated H2 and H3 headers so cross-links resolve to a single, specific section rather than spanning multiple headers.

Standards Topic Map

Document	Section Header	Core Topics Discussed	Primary Incoming Links
Master Style Guide	Collaboration & Iterative Design	Clarifying questions, rapid prototyping, Git Flow discipline.	AGENTS.md, fullstack-dotnet-react
	Foundational Engineering Principles	SOLID (≤ 500 lines), DRY Rule of Three, role-based naming, APIs First.	AGENTS.md, python-fastapi-mcp
	Backend Architecture & Persistence	.NET 10 .slnx, Dapper stored procedures, SQLite WAL pragmas, AES-256-GCM, channels.	fullstack-dotnet-react, console-cli-dotnet
	Frontend Architecture	React, strict TypeScript, Zustand granular selectors, CSS Modules, Playwright audits.	react-ts-vite-ui, fullstack-dotnet-react
	Testing & Simulation Harnesses	Controls mindset, anti-test theatre summary, tap points, 3-tier cadence, ≥ 80% coverage.	CLAUDE.md, GEMINI.md
Simulation & Control Harnesses	The Four Pillars of Anti-Test Theatre	Real Over Mock, Outcomes Over Calls, Representative Dogfooding, Value Over Vanity.	engineering-style-guide, AGENTS.md
	Banned & Mandated Patterns Matrix	12 engineering dimensions grouped into Data/APIs (1–4), Runtime/Faults (5–8), and UI/Edges (9–12).	engineering-style-guide, AGENTS.md
	Deterministic Test Budget Formula	AST-driven formula: 1 (Nominal) + Branches + Boundaries (0-1-N) + Disturbances.	engineering-style-guide, AGENTS.md
	Five-Question Mock Decision Tree	Mechanical 5-step decision tree restricting mocks to external third-party edges.	engineering-style-guide, CLAUDE.md, GEMINI.md
	The Six-Part Agent Feedback Envelope	Standardized JSON diagnostic payload (inputs, assumptions, active_settings, action_history, output_delta, captured_logs).	engineering-style-guide, AGENTS.md
	Polyglot Harness Recipes	Concrete integration harness implementations for C#, Python, React/TS, and C++.	All 5 archetype guides and engineering-style-guide
CI/CD Pipelines	Git Flow Trigger Matrix & Stage Descriptions	Branch-to-stage mapping across Integrity, Build & Test, Smoke, and Release gates.	engineering-style-guide, ARCHITECTURE.md
Code Review & Guardrails	The Six Reviewer Foci	Orthogonal review lenses: Requirements, Architecture/JSON, Anti-Test-Theatre, Security/Subprocess, UI/Screenshots, Docs/Release.	AGENTS.md, code-review-foci
	Requirements Traceability	Category codes (AUTH, DB, GUARD, MCP, SEC, TRANS, UI), polyglot test annotations, zero-drift SRS catalog.	AGENTS.md
	Operational & Deployment Guardrails	Scoped file search, lockstep version bump + docs-only exception, post-CI /health probe, dedicated component repo boundaries.	AGENTS.md, CLAUDE.md, GEMINI.md
Technical Writing Standards	Core Writing Rules & Structural Rules	ASD-STE100 and Google Developer Documentation Style Guide rules, section-scoped links, clean numeric symbols.	engineering-style-guide, AGENTS.md

---

Non-Functional Guarantees

1. Zero External Runtime Dependencies: The toolbelt consists of portable Markdown, YAML, Shell, Python, and JSON configuration files.
2. Submodule Safety: Files use relative paths and template placeholders without hardcoded host filesystem paths.
3. Multi-Agent Interoperability: Manifests work natively across Antigravity, Claude Code, Cursor, Codex, and MCP gateways.
4. Living Documentation Integrity: Automated verification (verify_release.py) validates version synchronization, relative links, and section anchors on every commit.