Agentic Engineering Toolbelt

Appearance

Universal Agent Rules (AGENTS.md) ​

Mandatory architectural guidelines and execution rules for AI coding assistants.

Collaboration and Workflow Discipline ​

Proactive Clarification and Git Flow ​

  1. Proactive Clarifying Questions: Steven's conceptual designs evolve during development. Always ask insightful clarifying questions to define requirements, edge cases, and architectural constraints.
  2. Traditional Git Flow Discipline (see Traditional Git Flow Discipline):
    • main: Production tagged releases only (vX.Y.Z). Direct pushes are forbidden.
    • develop: Primary integration branch for ongoing work. Merge feature branches here through Pull Requests.
    • feature/*: Dedicated branches created off develop (feature/feature-name) for isolated work. Merge back to develop after Tier 2 and Tier 3 gates pass.
    • release/*: Created off develop (release/vX.Y.Z) for version bumping, changelog finalization, and release verification before merging into main and develop.
    • hotfix/*: Created directly off main (hotfix/vX.Y.Z) to fix critical production defects before merging into both main and develop.
    • Commit work using atomic Conventional Commits (feat:, fix:, test:, docs:, chore:).
    • Open a Pull Request and verify that all Multi-Stage CI/CD Pipeline gates pass before merging.

Technical Writing and Living Documentation ​

Write all user-facing documentation, README files, architectural specs, and living guides according to our Technical Writing Standards, combining ASD-STE100 (Simplified Technical English) and the Google Developer Documentation Style Guide:

  • Keep sentences short, concise, and direct (≤ 25 words per sentence).
  • Use active voice and second-person imperative mood for instructions.
  • Organize dense topics into scannable H2 and H3 headings and scope cross-links to exact #section anchors.
  • Use standard Unicode symbols (≥, ≤) instead of raw LaTeX math syntax in prose.
  • Render architecture, sequence, state, and branching diagrams using native Mermaid syntax (flowchart TD, sequenceDiagram autonumber, stateDiagram-v2, gitGraph).
  • Publish living documentation via VitePress deployed to GitHub Pages.

APIs First and Container Immutability ​

  1. APIs First, MCP Later (see APIs First, MCP Later):
    • Implement domain logic and workflows inside clean, typed, self-contained libraries and REST/gRPC APIs before exposing them via Model Context Protocol (MCP).
    • Keep MCP tools strictly as lightweight wrappers that forward requests to underlying service interfaces.
    • Ensure core capabilities remain 100% testable through CLI, direct API calls, or integration harnesses without requiring MCP.
  2. Container Immutability:
    • Never edit files or hot-patch code inside live running containers.
    • Always rebuild via standard compose commands (docker compose up -d --build) or pull official images.
  3. Container Target Architecture:
    • Standardize strictly on native linux/amd64 for all container builds and CI workflows.
    • Do not include QEMU emulation or multi-architecture (arm64) build steps in CI/CD pipelines.

Core Code and Architectural Discipline ​

Modularity, Interfaces, and DRY ​

  1. SOLID and File Size Limit: Decompose files and classes exceeding 500 lines of code (≤ 500 LOC) into partial classes or focused sub-services (see SOLID and Modularity).
  2. Interfaces by Default: Build client-focused interfaces (I* in C#) even for single implementations to ensure loose coupling and testability.
  3. DRY vs. YAGNI:
    • Rule of Three: Permit duplication across two instances; refactor into a shared abstraction on the third occurrence.
    • Do not invent speculative multi-tier frameworks (YAGNI).

Semantic Naming and Anti-Pattern Bans ​

  • Banned: Never create *Manager, *Helper, *Util, or *Data junk-drawer classes (see Semantic Naming and Anti-Pattern Bans).
  • Enforced: Use role- and action-based names (DatabaseSeederService, UserAuthenticator, ServerStatusCard, use*Store.ts).

Database, Frontend, and Error Handling ​

  1. Database Efficiency: Consolidate operations requiring three or more database round-trips or complex multi-table joins into a single Stored Procedure (.sql file) or batch query.
  2. Frontend Selectors: Use granular Zustand selectors (useServerStore(s => s.servers.length)) to prevent render cascades.
  3. Error Handling and Diagnostics: Never leak raw stack traces to API clients. Log structured debug payloads with the exact inputs and state that triggered the failure.

Polyglot Language Matrix ​

StackCore Conventions & ToolingArchetype Blueprint
C# (.NET 10).slnx, System.CommandLine, full DI, Dapper + Stored Proc .sql files, SQLite WAL / MSSQL, native C# UIs (WPF/WinForms/Avalonia, no Electron), full CancellationToken propagation.Fullstack (.NET + React) • .NET Console & CLI
Python (3.12+)uv, pyproject.toml, FastAPI + FastMCP, Pydantic v2 schemas, asyncio, pytest (≥ 80% coverage), ruff.Python FastAPI & FastMCP
TypeScript / ReactReact + strict TS + Vite, Zustand domain stores, pure CSS Modules + custom properties, playwright-layout-inspector 4-point audit.React, TS & Vite UI
C++ (C++20/23)MSBuild (Win) / CMake (Linux), vcpkg, strict RAII, smart pointers, GoogleTest (gtest), ASan/UBSan, Benchmark, C# [LibraryImport] / Python pybind11 interop.C++ Native Algorithms

Testing and Agent Verification Protocol ​

Observable Systems and Tiered Cadence ​

  1. Software as an Observable Dynamic System:
    • Model critical workflows, boundary crossings, and stateful protocols with diagnostic tap points, metrics, and health probes.
    • Build closed-loop simulation harnesses with high-volume stress loops, parameter sweeps, and synthetic disturbance ingestion.
  2. Tiered Testing Cadence (see Tiered Testing Cadence):
    • Tier 1 (Inner Loop): Run fast, isolated in-memory unit tests on demand during active development.
    • Tier 2 (Stabilization Gate): Run unit and targeted integration suites once feature interfaces stabilize, immediately before manual verification.
    • Tier 3 (Pre-PR & CI Gate): Execute the full test matrix, multi-provider integration suites, simulation stress loops, and Playwright layout audits before merging.

The Four Pillars of Anti-Test Theatre ​

Never write Test Theatre (mock-heavy tests that verify method calls instead of real system state). Enforce the Four Pillars of Anti-Test Theatre and the 12-dimension Banned and Mandated Patterns Matrix:

  1. Pillar 1: Real Over Mock: Test software with real components and in-memory SQLite (WAL mode) databases instead of mocking IRepository<T> or DbContext. Mock only unmanageable external third-party network boundaries.
  2. Pillar 2: Outcomes Over Calls: Assert observable state deltas (database records, generated files, response payloads, emitted events). Never use mock.Verify() as primary proof of success.
  3. Pillar 3: Representative Dogfooding: Execute a real CLI subprocess or full HTTP request-response roundtrip for every feature before claiming completion.
  4. Pillar 4: Value Over Numeric Vanity: Prioritize boundary conditions, disturbances, and concurrency over shallow line coverage. Do not write tests for boilerplate POCOs, DTOs, or auto-properties.

Deterministic Test Budget Formula ​

Analyze the function or feature Abstract Syntax Tree (AST) before authoring tests to compute the exact required budget (see Deterministic Test Budget Formula):

text
Test Budget = 1 (Nominal) + N_Branches + N_Boundaries (0-1-N) + N_Disturbances
  • Nominal Path (1 test): One test exercising the happy path with valid nominal data.
  • Decision and Guard Branches (1 test per branch): One test per independent branch (if, switch, validation guard, or explicit throw).
  • 0-1-N Boundary Conditions (1 to 3 tests): 0 (empty/null/zero), 1 (single item/minimum), and N (large batch/maximum).
  • Disturbances and Lifecycle (1 test if async or stateful): One test validating CancellationToken propagation, timeout recovery, or state idempotency.

Deterministic Five-Question Mock Decision Tree ​

Pass every candidate collaborator through the Five-Question Mock Decision Tree before creating any mock or stub:

  1. Is the dependency internal to the current solution? If yes, use the real component via dependency injection or direct instantiation.
  2. Is it a database or persistent store? If yes, use a real in-memory database (SQLite WAL or ephemeral instance).
  3. Is it the system clock or non-deterministic time? If yes, use a time abstraction (TimeProvider or time-machine).
  4. Is it an external third-party HTTP API (such as Stripe or SendGrid)? If yes, use a contract stub (WireMock.Net or respx). Never mock internal interfaces.
  5. Is it child process STDIO or an OS pipe? If yes, use a synthetic transport (mock_stdio.js) with fault injection.

If you answer "No" to all five questions, mocking is forbidden. Use the real implementation.

Coverage, UI Layout Audits, and Feedback Envelopes ​

  1. Coverage Target: Maintain ≥ 80% code coverage across unit, integration, and end-to-end suites, excluding trivial POCO and DTO boilerplate.
  2. UI Layout Inspection: Verify that frontends pass the 4-point playwright-layout-inspector audit (zero overflow, mobile fit, ≥ 24px touch targets, ≥ 85 layout score; see UI Layout Stability and Ergonomics Auditing).
  3. Six-Part Agent Feedback Envelope: Format all harness or test failures using the Six-Part Agent Feedback Envelope (inputs, assumptions, active_settings, action_history, output_delta, captured_logs, and reproduction_command).
  4. Empirical Verification: Never claim a task is complete without running builds, executing tests, inspecting logs, and probing /health.

Multi-Lens Code Review and Operational Guardrails ​

The Six Reviewer Foci and Requirements Traceability ​

  1. Six Reviewer Foci: Before opening or finalizing any Pull Request, evaluate the diff across all six lenses in Multi-Lens Code Review and The Six Reviewer Foci:
    • Focus 1: Requirement Traceability and Feature Preservation ([Requirement(...)] / @requirement annotations using AUTH, DB, GUARD, MCP, SEC, TRANS, UI taxonomy; zero feature deletions without instruction).
    • Focus 2: Architecture, Modularity, and Safe Serialization (≤ 500 LOC cap, I* interfaces, APIs First/MCP wrapper, and JsonNode/Pydantic manipulation instead of string.Replace).
    • Focus 3: Anti-Test-Theatre and Live-Executor Isolation (real SQLite WAL / in-process transport, 0-1-N boundaries, AST test budget, pytest -m "not live").
    • Focus 4: Security, Subprocess Safety, and Container Immutability (sanitized argument arrays without shell=True, 100% CancellationToken propagation, AES-256-GCM encrypted secrets, immutable containers).
    • Focus 5: UI Consistency, Layout Stability, and Real Screenshots (CSS variables, scrollbar-gutter: stable, 4-point Playwright layout audit, and real Playwright/Puppeteer screenshots in UI PRs).
    • Focus 6: Living Documentation, Atomic Commits, and Release Sync (README.md/ARCHITECTURE.md/docs/ updated, atomic Conventional Commits, lockstep version bump with the docs-only exception).
  2. Requirements Traceability: Annotate all new and modified tests and keep REQUIREMENTS.md synchronized with zero drift (see Requirements Traceability and Living SRS Catalogs).

Context Hygiene, Subprocess Safety, and Release Gates ​

  1. Targeted File Search: Never run unbounded grep or ripgrep across a repository root. Always scope searches using path prefixes or file globs (include_pattern) to avoid scanning build artifacts or lockfiles (see Scoped Search and Context Window Hygiene).
  2. Lockstep Version Sync and Docs-Only Exception: Bump all project manifests, frontend version stores, and CHANGELOG.md simultaneously for code changes; skip version bumps and container rebuilds for documentation-only changes (see Lockstep Version Sync and the Documentation-Only Exception).
  3. Post-CI Verification and Dedicated Component Repos: Always wait for GitHub Actions CI checks (gh pr checks --watch) to pass before finalizing PRs or pulling images, verify /health after container recreation, and always commit/PR standalone components from their dedicated repositories in ~/Repos/ (see Post-CI Verification and Container Health Gates).

Released under the MIT License.

Copyright © 2026 Steven T. Pelech