shadow-architect
Skill1 starsChanged yesterdayMITView on GitHub
Single-System Architecture & Design. Use when designing one application architecture, C4 diagrams, ADRs, module boundaries, or deciding Monolith vs Modular Monolith vs Microservices. Do NOT use for multi-app enterprise portfolios or 6-Domain SPBE (/shadow-ea).
In this repository51 other files it gives its agents.
- antislop-codeSkill
- antislop-copywritingSkill
- antislop-humanSkill
- antislop-layoutmobileSkill
- antislopSkill
- antislop-uiSkill
- context7Skill
- handoffSkill
- shadow-accessibilitySkill
- shadow-apiSkill
- shadow-authSkill
- shadow-bootstrapSkill
- shadow-browserSkill
- shadow-cacheSkill
- shadow-compatSkill
- shadow-concurrencySkill
- shadow-dataSkill
- shadow-dbSkill
- shadow-debugSkill
- shadow-designSkill
- shadow-discoverySkill
- shadow-docSkill
- shadow-domainSkill
- shadow-eaSkill
- shadow-evalSkill
- shadow-finopsSkill
- shadow-gitSkill
- shadow-grcSkill
- shadow-handoverSkill
- shadow-integrateSkill
- shadow-maintainSkill
- shadow-mobileSkill
- shadow-modernizeSkill
- shadow-monarchSkill
- shadow-observeSkill
- shadow-opsSkill
- shadow-perfSkill
- shadow-planSkill
- shadow-pmoSkill
- shadow-presalesSkill
- shadow-privacySkill
- shadow-qualitySkill
- shadow-realtimeSkill
- shadow-refactorSkill
- shadow-releaseSkill
- shadow-resilienceSkill
- shadow-searchSkill
- shadow-secSkill
- shadow-supplychainSkill
- shadow-testSkill
- shadow-uatSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 6 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Use this skill after /shadow-discovery (or when evaluating major structural changes) to establish a maintainable, right-sized architecture …
- Distinctive: line 50
When designing or extending an existing application (Brownfield Project):
- Very specific: line 57
Before proposing architectural modifications, inspect the codebase across the 10 Discovery Facets and maintain the Project Convention …
- Distinctive: line 67
Testing & Dependency Conventions: Test runners, mock styles, fixture conventions.
- Distinctive: line 69
Run deterministic discovery and profiling:
- Distinctive: line 73
If patterns conflict across legacy modules, document the ambiguity rather than inventing a global standard.
- Distinctive: line 76
Always resolve architectural decisions using this hierarchy:
- Distinctive: line 84
Always search for the closest existing implementation before architecting new components.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Shadow Architect (/shadow-architect) — System Architecture & ADR Gate (SDLC Stage 2)
Use this skill after /shadow-discovery (or when evaluating major structural changes) to establish a maintainable, right-sized architecture before scaffolding or coding.
1. Core Architectural Philosophy: Right-Sized Engineering
- Default to a Modular Monolith unless independent team scaling, heterogeneous compute (e.g., heavy GPU worker vs CRUD API), or strict regulatory isolation proves that distributed microservices are necessary.
- Enforce Strict Module Boundaries: Modules communicate via explicit public service interfaces or domain events — never by reaching directly into another module's internal tables or private repositories.
- Trace Every NFR to an Architectural Mechanism & Consistency Model:
- Consistency & Distributed Failure Assumptions: State explicitly where strict serializability / ACID is required (money, inventory, auth grants) vs eventual consistency (search index sync, analytics projections); document failure assumptions under network partitions, split-brain locks, and clock skew (
monotonicvs wall clock). - Architectural Fitness Functions: Define measurable automated guardrails (max p95 latency, zero cross-module DB table imports, acyclic dependency graph, max fan-out).
- High read concurrency -> Read replicas +
/shadow-cache(Redis/TanStack Query). - Slow/unreliable external third-party calls -> Asynchronous outbox/queue worker +
/shadow-concurrency+/shadow-integratecircuit breaker. - Multi-client data isolation ->
/shadow-authtenant-scoped queries / PostgreSQL RLS.
- Consistency & Distributed Failure Assumptions: State explicitly where strict serializability / ACID is required (money, inventory, auth grants) vs eventual consistency (search index sync, analytics projections); document failure assumptions under network partitions, split-brain locks, and clock skew (
2. Mandatory Architecture Deliverables
A. C4 Model Diagrams (Strict Mermaid Syntax)
- Level 1 — System Context Diagram: The application, primary user personas, and external third-party systems (Payment Gateway, SSO, SMTP, Government APIs).
- Level 2 — Container Diagram: Web/Mobile clients, API Gateway/Reverse Proxy, Backend API, Background Worker, Primary DB, Cache (
Redis), Object Storage (S3/MinIO), and Data Warehouse. - Level 3 — Component & Data Flow Diagram: Key sequence diagrams (
sequenceDiagram) for critical flows (Authentication, Checkout/Approval, Webhook Ingestion).
B. Capacity & Resource Sizing Estimation
Calculate concrete baseline estimates from /shadow-discovery NFRs:
- Traffic: Daily Active Users (DAU) -> Average RPS -> Peak RPS ($3\times$ average).
- Storage: Row size $\times$ records/day $\times$ 365 days $\times$ retention years + $30%$ index overhead + object storage growth.
- Compute & Memory: vCPU and RAM sizing for App Servers, Database (
shared_buffers= 25% RAM), and Redis cache.
C. Architecture Decision Records (docs/adr/ADR-XXX-*.md)
For every consequential choice (Database engine, Monolith vs Microservices, Auth strategy, Queue broker, Deployment target), record:
- Status:
Proposed | Accepted | Superseded - Context & Problem Statement
- Options Considered (with Pros, Cons, and Cost/Operational Complexity)
- Decision & Rationale
- Consequences & Trade-offs
3. Brownfield Architecture & Convention Preservation
When designing or extending an existing application (Brownfield Project):
A. Brownfield vs Greenfield Project Routing
- Greenfield: Zero/empty repository. Proceed with standard Shadow Army scaffolding (
/shadow-bootstrap) and right-sized Modular Monolith baseline. - Brownfield: Existing codebase present. Preserve existing architectural patterns (Layered MVC, Feature-based, Hexagonal, Clean, Minimalist). Do NOT impose unsolicited architectural migrations (e.g. converting a working MVC into Clean Architecture/DDD) solely because it is perceived as "cleaner" or "more modern".
B. Mandatory Existing-Codebase Discovery & Convention Profile
Before proposing architectural modifications, inspect the codebase across the 10 Discovery Facets and maintain the Project Convention Profile at docs/engineering/CODEBASE_CONVENTIONS.md:
- Framework, Language & Runtime: Exact version, module system (CommonJS vs ESM).
- Project Structure & Module Boundaries: Directory organization, monorepo workspaces.
- Architectural Patterns: Prevailing architectural style and layer boundaries.
- Naming Conventions: File, folder, class, function, and variable casings.
- Code Formatting & Lint Rules: Linter configs, indentation, quotes, trailing commas.
- API & Database Access Patterns: Established ORM, query builders, repository patterns.
- Error Handling & Validation: Centralized error middleware, validation libraries (Zod, Joi, FormRequest).
- Authentication & Authorization: Session/JWT mechanisms, RBAC/ABAC guards.
- State Management & Caching: Frontend stores (Zustand, Redux, Pinia), Redis caching keys.
- Testing & Dependency Conventions: Test runners, mock styles, fixture conventions.
Run deterministic discovery and profiling:
python "shadow-quality/scripts/codebase_intelligence.py" discover --repo-dir . --write-profileIf patterns conflict across legacy modules, document the ambiguity rather than inventing a global standard.
C. Convention Precedence Hierarchy
Always resolve architectural decisions using this hierarchy:
- Level 1: Explicit user requirements & safety/security constraints (SQL injection prevention, data isolation).
- Level 2: Applicable project-level instructions (
AGENTS.md,CLAUDE.md, documented architecture). - Level 3: Established patterns in relevant existing modules.
- Level 4: Shadow Army global conventions.
- Level 5: AI default preferences (never allowed to override established project conventions).
D. Existing Code First Principle
- Always search for the closest existing implementation before architecting new components.
- Reuse existing services, utilities, middleware, and repositories.
- Match equivalent module structure and naming patterns across feature boundaries.
4. Stage 2 Exit Gate Checklist (To Unlock /shadow-plan & /shadow-bootstrap)
- C4 Context and Container diagrams validated in strict Mermaid syntax.
- Core database ERD (
/shadow-db) and API contract strategy (/shadow-api) aligned with functional requirements. - ADRs written for all critical stack and infrastructure choices.
- Capacity sizing confirms infrastructure fits client budget and SLA targets.
- For Brownfield projects: Project Convention Profile (
docs/engineering/CODEBASE_CONVENTIONS.md) inspected and architectural preservation confirmed.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

