adk-architecture

Designs system architecture, from a single service's high-level design to distributed microservices decomposition. Produces architecture diagrams, ADRs, service boundary designs, deployment-topology decisions (VM/IaaS vs. cloud-native vs. hybrid vs. multi-cloud), and - for distributed systems - communication, data-ownership, and resilience strategies, each with explicit trade-offs. Use for new system design, architecture review, pattern selection (monolith/microservices/serverless/event-driven), monolith decomposition, choosing where a system or component runs (VM, cloud, hybrid), or documenting decisions as ADRs.

Generates, formats, and validates technical documentation - inline documentation (docstrings/comments), API specs (OpenAPI/Swagger, JSDoc-style annotations), documentation sites, and user guides - for any language or framework. Use when adding documentation to functions or classes, creating API documentation, building documentation sites, or writing tutorials and user guides.

Two jobs on aging or inherited codebases. UNDERSTAND - reverse-engineer a specification from a system nobody documented: map structure and dependencies, trace data flows and request paths, recover the business rules from the implementation, write them up as EARS requirements, and flag what's still unclear. MIGRATE - turn that understanding into a safe incremental change: service boundaries, dependency maps, migration roadmaps, API facade designs, strangler fig or branch-by-abstraction rollout. Use for legacy or undocumented systems, inherited projects, onboarding to an unfamiliar codebase, figuring out what existing code actually does, monolith decomposition, framework/language upgrades, or reducing technical debt without disrupting operations.

Use when building, debugging, or extending an MCP (Model Context Protocol) server or client - protocol lifecycle and JSON-RPC 2.0 message shapes, version negotiation, choosing and configuring stdio vs Streamable HTTP transport, OAuth 2.1 authorization for remote servers, and debugging protocol-compliance failures. Covers the protocol itself; the SDKs' concrete APIs change too fast to snapshot, so those come from the live SDK docs at implementation time.

Finds vulnerabilities in code or infrastructure that already exists and reports them with CVSS severity and remediation - SAST scans, dependency audits, secrets scanning, penetration testing, cloud/DevSecOps and compliance review. Read-only by design: it locates and rates, it does not fix. Use for any request to audit, scan, or review existing code, dependencies, or infrastructure for vulnerabilities. To write secure code while building a feature, use `security-skill`.

Writes secure code while a feature is being built - authentication/authorization, input validation and sanitization, password hashing (bcrypt/argon2), parameterized queries, CORS/CSP headers, JWT/session handling, OWASP Top 10 prevention. Produces secure CODE. Use when implementing any of those controls, or hardening code being written. To audit existing code or infrastructure for vulnerabilities instead, use `security-audit`.

Provides the foundational engineering principles for designing sound solutions - SOLID and code-design heuristics (DRY/KISS/YAGNI, coupling/cohesion, Law of Demeter, Composed Method/Single Level of Abstraction, Command-Query Separation and TOCTOU-safe re-validation), the Well-Architected operational pillars (reliability, security, cost, performance, operational excellence), 12-Factor/cloud-native application practices, and environment-portability principles for systems that must run across VM and cloud (ports & adapters, config/secrets abstraction, consistent identity and observability). Use to evaluate whether a design or existing code follows sound engineering principles, to establish team design standards, or to audit a solution proposal for principle violations before implementation. Not for choosing an architecture pattern or deployment topology (that's architecture-designer), and not for writing language-specific implementation code.

Writes and structures technical proposal documents (RFCs, đề xuất kỹ thuật, đề xuất giải pháp, đề xuất dự án) that argue for a technical decision to stakeholders or approvers - problem/context, goals, proposed solution, alternatives considered, risks, implementation plan, timeline and resources. Use whenever the user asks to write, draft, or review a technical proposal, RFC, design doc meant for approval, project proposal, or any "đề xuất" document - in Vietnamese or English - especially when it needs to persuade a reader (lead, leadership, another team) to approve a course of action, not just describe how a system works.