macalbert/envilder/common-architecture-decisions

Name: common-architecture-decisions
Author: macalbert

Claude Code and agent skill by macalbert/envilder

Trust tier 2

community

LLM review pending

By macalbert
DevOps
macalbert/envilder
.github/skills/common-architecture-decisions/SKILL.md
Updated 22 Sep 2026
Version 1.0.12 versions recorded

Source check pending

Checking that the SKILL.md file is still in the repository.

Index of Architecture Decision Records (ADRs) for cross-cutting technical decisions. Use when making design choices, reviewing proposals for consistency with prior decisions, or onboarding to understand why specific tools or patterns were chosen. Covers test tooling, SDK architecture, code quality, and acceptance test infrastructure.

Install

npx vskill@latest install macalbert/envilder/common-architecture-decisions

SKILL.md

Architecture Decision Records

This skill provides an index of ADRs that document cross-cutting technical decisions in the Envilder project. Load this skill to understand the rationale behind tooling choices and architectural patterns before proposing changes.

When to Use

Before proposing a new library or tool (check if there's an existing decision)
When reviewing code that seems inconsistent with project conventions
When adding a new SDK and need to follow established patterns
When onboarding and need to understand "why" behind technical choices
Before writing tests: check ADR-0002 for the correct tooling per stack

ADR Index

ADR	Title	Scope	Key Decision
ADR-0001	SDK Acceptance Test Infrastructure	All SDKs	TestContainers + LocalStack (AWS and Azure); container wrappers with explicit lifecycle; `envilder.json` as single source for test tokens
ADR-0002	Test Tooling per Stack	All stacks	Vitest (TS), xUnit+NSubstitute+AwesomeAssertions (NET), pytest+unittest.mock (Py)
ADR-0003	SDK Architecture Pattern	All SDKs	Three-layer (Domain→App→Infra), no DI framework, facade as primary API, internal factory
ADR-0004	Code Quality and Formatting	All stacks	Biome (TS), dotnet format (.NET), black+isort (Py); Secretlint for credentials
ADR-0005	SDK Integration Tiers	All SDKs	Three tiers (Facade, Builder, Framework); Tier 3 separate package; .NET exception; community-driven
ADR-0006	Monorepo Structure	All components	Single repo, independent releases per component via version-bump detection, no orchestrator
ADR-0007	Trunk-Based Development	All components	Single main branch, short-lived feature branches, squash merge, feature flags for incomplete work
ADR-0008	Map-File Schema Specification	All components	JSON Schema v1, `$` prefix reserved, `$config` strict fields, `file` provider for testing (planned), `EnvilderOptions.FromFile` (planned)
ADR-0009	SDK Dependency Compatibility Policy	All SDKs	Minimum viable engine + dep versions in published SDKs; devDeps unconstrained; acceptance tests verify minimum
ADR-0013	Verification-First Agent Workflow	AI workflow	Independent verification contracts, intent-specific oracles, isolated implementation, review, and final evaluation
ADR-0014	Azure Key Vault Emulator	All test suites	LocalStack for Azure replaces Lowkey Vault; vault created through ARM; local managed identity token endpoint for `DefaultAzureCredential`

Quick Reference: Test Doubles per Stack

Stack	Mock/Spy	Stub	Fake (data)	Dummy
TypeScript	`vi.fn()` / `vi.mock()`	`vi.fn().mockResolvedValue()`	inline	inline
.NET	NSubstitute (`Received()`)	NSubstitute (`.Returns()`)	Bogus (Mother pattern)	AutoFixture
Python	`unittest.mock.Mock` / `AsyncMock`	`Mock(return_value=...)`	inline / fixtures	inline

Quick Reference: Container Testing

Stack	Package	AWS	Azure
TypeScript	`testcontainers`	`@testcontainers/localstack`	Custom (LocalStack for Azure)
.NET	`Testcontainers`	`Testcontainers.LocalStack`	Custom (LocalStack for Azure)
Python	`testcontainers`	`testcontainers[localstack]`	Custom (LocalStack for Azure)

Rules

Before adding a new testing tool: Check ADR-0002. If not listed, propose

an ADR amendment or new ADR.

Before changing SDK public API surface: Check ADR-0003. All SDKs must

follow the same facade/builder/client pattern.

Before changing formatters or linters: Check ADR-0004. Changes affect CI

and all contributors.

Before changing acceptance test infrastructure: Check ADR-0001. Container

wrappers, token resolution, and CI patterns are standardized.

Creating a New ADR

Use the format in docs/adr/:

markdown

# ADR-NNNN: Title
 
## Status
Proposed | Accepted | Deprecated | Superseded by ADR-XXXX
 
## Context
Why this decision is needed.
 
## Decision
What we chose and the details.
 
## Consequences
### Positive
### Negative
 
## When to Reconsider

Number sequentially. Keep scope focused: one decision per ADR.

Security

Security scanPassed, 93 of 100Pattern checks on the skill's files.
Model reviewNot runA model review is scheduled for the next rescan.

See the full security report

Quality evaluation

Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

SKILL.md in the repositoryChecking.github/skills/common-architecture-decisions/SKILL.md

Popularity

Repository stars: 135
Repository forks: 4
7-day trend score: 25

Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

Claude Code
Cursor
GitHub Copilot
Windsurf
Codex
Gemini CLI
Cline
Amp
Roo Code
Goose
Continue
Kilo Code
Junie
Trae
OpenHands
Qwen Code
AI Agent
Tabnine Chat
Sourcegraph Cody
Amazon Q
Firebase Genkit
Sweep
Devin
Phind
Mentat
Claude Desktop
Aider
GPT Pilot
Plandex
bolt.new
v0
Replit Agent
Anse
TypingMind
BetterChatGPT
LibreChat
Warp AI
Pieces
Fig AI

Embed badge

[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/macalbert/envilder/common-architecture-decisions/badge)](https://verified-skill.com/skills/macalbert/envilder/common-architecture-decisions)

Something wrong with this skill or its page? Tell us.