Gate 3: Technical architecture document - defines HOW/WHERE with technology-agnostic patterns before concrete implementation choices.
Creates technology-agnostic architecture documents defining system patterns before implementation choices.
/plugin marketplace add lerianstudio/ring/plugin install ring-pm-team@ringThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Architecture decisions (HOW/WHERE) must be technology-agnostic patterns before concrete implementation choices.
Specifying technologies in TRD creates:
The TRD answers: HOW we'll architect the solution and WHERE components will live. The TRD never answers: WHAT specific products, frameworks, versions, or packages we'll use.
This is a HARD GATE. Do NOT proceed without defining the tech stack.
Auto-detection: go.mod exists → Go | package.json with react/next → Frontend TS | package.json with express/fastify/nestjs → Backend TS
If ambiguous, AskUserQuestion: "What is the primary technology stack?" Options: Go (Backend), TypeScript (Backend), TypeScript (Frontend), Full-Stack TypeScript
| Standard | URL | Purpose |
|---|---|---|
| golang.md | https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/golang.md | Go patterns, DDD |
| typescript.md | https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/typescript.md | TS patterns, async |
| frontend.md | https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/frontend.md | React, Next.js, a11y |
| devops.md | https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/devops.md | Docker, CI/CD |
| sre.md | https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/sre.md | Health checks, logging |
| Tech Stack | Load |
|---|---|
| Go Backend | golang.md + devops.md + sre.md |
| TypeScript Backend | typescript.md + devops.md + sre.md |
| TypeScript Frontend | frontend.md + devops.md |
| Full-Stack TypeScript | typescript.md + frontend.md + devops.md + sre.md |
Check: docs/PROJECT_RULES.md → docs/STANDARDS.md (legacy) → STOP if not found
Read PRD, extract requirements, suggest technologies that address each, present to user for confirmation. Document in TRD metadata for Gate 6 to create PROJECT_RULES.md.
AskUserQuestion: "What deployment model?" Options: Cloud, On-Premise, Hybrid
TRD header must include: feature, gate: 3, deployment.model, tech_stack.primary, tech_stack.standards_loaded[], project_technologies[] (category, prd_requirement, choice, rationale per technology decision)
This metadata flows to Gates 4-6.
| Pressure | Response |
|---|---|
| "Tech stack doesn't matter for architecture" | "Architecture patterns vary by language. Go patterns ≠ TypeScript patterns. Define stack first." |
| "We'll decide tech stack later" | "Later = Dependency Map. But architecture NOW needs to know capabilities. Define stack." |
| "Just use generic patterns" | "Generic patterns miss stack-specific best practices. 5 min to define saves rework." |
| "Skip to save time" | "Skipping causes Gates 4-6 to ask again. Define once here, inherit everywhere." |
| Phase | Activities |
|---|---|
| 1. Analysis (After Step 0) | PRD (Gate 1) required; Feature Map (Gate 2) optional; identify NFRs (performance, security, scalability); map domains to components |
| 2. Architecture Definition | Choose style (Microservices, Modular Monolith, Serverless); design components with boundaries; define interfaces; model data architecture; plan integration patterns; design security |
| 3. Gate 3 Validation | All domains mapped; component boundaries clear; interfaces technology-agnostic; data ownership explicit; quality attributes achievable; no specific products named |
System architecture style (patterns, not products), component design with responsibilities, data architecture (ownership, flows - conceptual), API design (contracts, not protocols), security architecture (layers, threat model), integration patterns (sync/async, not tools), performance targets, deployment topology (logical)
Technology products (PostgreSQL, Redis, Kafka), framework versions (Fiber v2, React 18), language specifics (Go 1.24, Node.js 20), cloud services (AWS RDS, Azure Functions), packages (bcrypt, zod, prisma), container orchestration (Kubernetes, ECS), CI/CD details, IaC specifics
| Element | Say This (✅) | Not This (❌) |
|---|---|---|
| Database | "Relational Database" | "PostgreSQL 16" |
| Cache | "In-Memory Cache" | "Redis" or "Valkey" |
| Message Queue | "Message Broker" | "RabbitMQ" |
| Object Storage | "Blob Storage" | "MinIO" or "S3" |
| Web Framework | "HTTP Router" | "Fiber" or "Express" |
| Auth | "JWT-based Authentication" | "specific library" |
| Excuse | Reality |
|---|---|
| "Everyone knows we use PostgreSQL" | Assumptions prevent proper evaluation. Stay abstract. |
| "Just mentioning the tech stack for context" | Context belongs in Dependency Map. Keep TRD abstract. |
| "The team needs to know what we're using" | They'll know in Dependency Map. TRD is patterns only. |
| "It's obvious we need Redis here" | Obvious ≠ documented. Abstract to "cache", decide later. |
| "I'll save time by specifying frameworks now" | You'll waste time when better options emerge. Wait. |
| "But our project template requires X" | Templates are implementation. TRD is architecture. Separate. |
| "The dependency is critical to the design" | Then describe the capability needed, not the product. |
| "Stakeholders expect to see technology choices" | Stakeholders see them in Dependency Map. Not here. |
| "Architecture decisions depend on technology X" | Then your architecture is too coupled. Redesign abstractly. |
| "We already decided on the tech stack" | Decisions without analysis are assumptions. Validate later. |
If you catch yourself writing any of these in a TRD, STOP:
When you catch yourself: Replace the product name with the capability it provides. "PostgreSQL 16" → "Relational Database with ACID guarantees"
| Category | Requirements |
|---|---|
| Architecture Completeness | All PRD features mapped; DDD boundaries; single clear responsibilities; stable interfaces |
| Data Design | Ownership explicit; models support PRD; consistency strategy defined; flows documented |
| Quality Attributes | Performance targets set; security addressed; scalability path clear; reliability defined |
| Integration Readiness | External deps identified (by capability); patterns selected (not tools); errors considered; versioning strategy exists |
| Technology Agnostic | Zero product names; capabilities abstract; patterns named not implementations; can swap tech without redesign |
Gate Result: ✅ PASS → API Design | ⚠️ CONDITIONAL (remove product names) | ❌ FAIL (too coupled)
| Violation | Wrong | Correct |
|---|---|---|
| Tech in Architecture | Language: Go 1.24+, Framework: Fiber v2.52+, Database: PostgreSQL 16 | Style: Modular Monolith, Pattern: Hexagonal, Data Tier: Relational DB, Key-value store, Object storage |
| Framework in Components | Fiber middleware for JWT, bcrypt for passwords, passport.js for OAuth2 | Auth Component: Purpose, Inbound (HTTP endpoints), Outbound (persistence, notifications), Security (token-based, industry-standard hashing) |
| Cloud Services in Deployment | Compute: AWS ECS Fargate, Database: AWS RDS, Cache: ElastiCache | Compute: Container-based stateless, Data Tier: Managed DB with backup, Performance: Distributed caching, Traffic: Load balanced with health checks |
If feature includes list/browse, decide during TRD:
| Strategy | Best For | Trade-off | Performance |
|---|---|---|---|
| Cursor-Based | >10k records, infinite scroll, real-time | Can't jump pages | O(1) |
| Page-Based (Offset) | <10k records, admin interfaces | Degrades with large offsets | O(n) |
| Page-Based + Total Count | "Page X of Y" UI | Additional COUNT query | 2 queries |
| No Pagination | Very small bounded datasets (<100) | All data at once | - |
Document in TRD: API Patterns → Pagination → Strategy + Rationale
If feature requires authentication or authorization (as determined in Question 2 of pre-dev command):
| Auth Type | TRD Description (Abstract) | Implementation Reference |
|---|---|---|
| User authentication only | "Token-based authentication with stateless validation" | For Go: golang.md → Access Manager Integration |
| User + permissions | "Token-based authentication with role-based access control (RBAC)" | For Go: golang.md → Access Manager Integration |
| Service-to-service | "Machine-to-machine authentication with client credentials" | For Go: golang.md → Access Manager Integration (GetApplicationToken) |
| Full (user + S2S) | "Dual-layer authentication: user tokens for end-users, client credentials for services" | For Go: golang.md → Access Manager Integration |
Document in TRD: Security Architecture → Authentication/Authorization → Strategy + Implementation Reference
Key Implementation Pattern (for TRD reference):
auth.Authorize(applicationName, resource, action) on each routeNote for Go Services: Lerian's Access Manager (plugin-auth + identity + lib-auth) is the standard authentication system. Reference golang.md → Access Manager Integration section in the TRD so engineers know where to find implementation patterns including route middleware protection.
If feature is a licensed product/plugin (as determined in Question 3 of pre-dev command):
| License Type | TRD Description (Abstract) | Implementation Reference |
|---|---|---|
| Single-org (global) | "Global license validation at service startup with fail-fast behavior" | For Go: golang.md → License Manager Integration |
| Multi-org | "Per-request license validation with organization context" | For Go: golang.md → License Manager Integration |
Document in TRD: Security Architecture → Licensing → Strategy + Implementation Reference
Key Architecture Pattern (for TRD reference):
Note for Go Services: Lerian's License Manager (lib-license-go) is the standard licensing system. Reference golang.md → License Manager Integration section in the TRD so engineers know where to find implementation patterns including global middleware and graceful shutdown.
**ADR-00X: [Pattern Name]**
- **Context**: [Problem needing solution]
- **Options**: [List with trade-offs - no products]
- **Decision**: [Selected pattern]
- **Rationale**: [Why this pattern]
- **Consequences**: [Impact of decision]
| Factor | Points | Criteria |
|---|---|---|
| Pattern Match | 0-40 | Exact before: 40, Similar: 25, Novel: 10 |
| Complexity Management | 0-30 | Simple proven: 30, Moderate: 20, High: 10 |
| Risk Level | 0-30 | Low proven: 30, Moderate mitigated: 20, High accepted: 10 |
Action: 80+ present autonomously | 50-79 present options | <50 request clarification
Output to: docs/pre-dev/{feature-name}/trd.md
pre-dev-api-design)If you wrote a TRD with specific technology products, delete those sections and rewrite abstractly.
The TRD is architecture patterns only. Period. No product names. No versions. No frameworks.
Technology choices go in Dependency Map. That's the next phase. Wait for it.
Stay abstract. Stay flexible. Make technology decisions in the next phase with full analysis.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.