architect-document-templates

name	architect-document-templates
description	Contains all document templates the temper-architect agent generates. Includes templates for architecture-decision.md, backend-config.md, frontend-config.md, and architectural-plan.md. Load this skill when the architect needs to generate any of these documents after proposal confirmation.

Architect Document Templates

These templates define the exact structure and format for every document the architect produces. All documents must conform to the Document Scope Constraints table below.

Canonical architecture pattern values for machine-readable architect outputs:

• Clean Architecture
• Hexagonal Architecture
• Vertical Slice Architecture
• Onion Architecture

Document Scope Constraints

Document	What it MUST contain	What it must NEVER contain
backend-config.md	Framework (+version), language, ORM (+version), data access pattern (Repository + UnitOfWork | Direct DbContext, ORM stacks only), architecture pattern, database engine, API docs provider, auth type, health checks, messaging, caching, logging, versioned dependencies (package names + versions)	Skills lists, code patterns, "key conventions", implementation details
frontend-config.md	Framework type, backend URL, backend communication, auth handling, state management	Skills lists, code patterns
DDD-Vocabulary.md	Domain terms with definitions — per ddd/documents skill template	Technical jargon, implementation details
architecture-decision.md	Full reasoning, justification, trade-offs, alternatives, risks	Code snippets, skill names
domain-model.md	Entities, aggregates, events, relationships, Mermaid diagrams — per ddd/documents skill	Code snippets, implementation patterns
system-architecture.md	Component diagram, bounded contexts, integrations — per ddd/documents skill	Code snippets, implementation patterns
architectural-plan.md	Full reasoning, root cause, proposed solution, impact, risks, alternatives, overridden decisions	Code snippets, skill names
api-contracts.md	Endpoint table (method, route, request/response), DTO shapes with domain types, error conditions — extracted from built backend	Code snippets, C# types, implementation patterns

General Document Rules

• Required documents (backend-config, frontend-config, DDD-Vocabulary) are generated automatically in Mode A after proposal confirmation and after optional document selection is captured
• Optional documents are ONLY generated if the user explicitly selected them
• Mode B has no required documents; architectural-plan.md is optional
• api-contracts.md is generated ONLY when the user explicitly requests it after final OK — extracted from the built backend code
• Do NOT generate extra documents beyond what was confirmed
• NEVER list skill names in any document
• NEVER tell another agent which skills to load
• NEVER include code snippets in any language (C#, SQL, JSON, YAML, etc.)
• NEVER include method signatures, return types, class names with namespaces, or configuration file examples with real structure

Document Responsibility Separation

The architect generates authoritative reference documents under Docs/Application/. The docs agent generates developer guides and business overviews in Docs/. They do NOT overlap:

Architect generates	Docs agent generates
Docs/Application/Architecture/architecture-decision.md — ADR with full reasoning	ARCHITECTURE.md — code conventions, testing, deployment
Docs/Application/Domain/domain-model.md — DDD model with Mermaid	SYSTEM.md — business overview, users, flow
Docs/Application/System/system-architecture.md — bounded contexts, integrations	API.md — endpoint reference
Docs/Application/Architecture/backend-config.md — machine-readable config	CHANGELOG.md — version history
Docs/Application/Architecture/frontend-config.md — machine-readable config	README.md — project setup
Docs/Application/System/api-contracts.md — extracted from built backend

The docs agent links to architect reference docs instead of duplicating their content.

---

Template: architecture-decision.md

Authoritative ADR for humans and auditing. Rich, justified, full reasoning. Implementation agents do NOT read this file. The docs agent links to it from ARCHITECTURE.md. Written to Docs/Application/Architecture/architecture-decision.md.

# Architecture Decision Record — [Project Name]

> Generated by TemperAI — temper-architect
> Date: [YYYY-MM-DD]
> Version: [YYYYMMDD-HHMM]
> Status: Confirmed

---

## 1. Context

[Summary of what was analyzed — PRD signals, existing system, or provided description]

## 2. Architecture Pattern

**Decision:** [pattern]
**Rationale:** [justification tied to domain signals]
**Trade-offs accepted:** [what this pattern costs in this context]
**Alternatives considered:** [what was rejected and why]

## 3. Backend Stack

**Runtime:** [value] — [rationale]
**Database:** [value] — [rationale]
**ORM / data access:** [value] — [rationale]
**Data access pattern:** [Repository + UnitOfWork | Direct DbContext | N/A — no ORM] — [rationale]
**Auth strategy:** [value] — [rationale]
**API documentation:** [value] — [rationale]

**Additional components:**
- Health checks: [Yes/No] — [rationale]
- Messaging: [value] — [rationale]
- Caching: [value] — [rationale]
- Logging: [value] — [rationale]

## 4. External Dependencies

| PRD Requirement | Package | Alternative Considered | Rationale |
|---|---|---|---|
| [e.g. Send email reports] | [e.g. MailKit] | [e.g. SendGrid] | [rationale] |
| [e.g. Generate Excel reports] | [e.g. ClosedXML] | [e.g. EPPlus] | [rationale] |

[If none: "No external dependencies required beyond base stack"]

## 5. Frontend

**Type:** [value] — [rationale]
[If applicable:]
- State management: [value] — [rationale]
- Backend communication: [value] — [rationale]
- Auth handling: [value] — [rationale]

## 6. Risks and Constraints

- [Risk 1]: [mitigation]
- [If none: "No significant architectural risks identified"]

## 7. Decisions Overridden During Confirmation

- [Original] → [Confirmed] — [risk noted if any]
- [If none: "All decisions confirmed as proposed"]

---

Template: backend-config.md

For implementation agents only. Minimal, precise, machine-readable. No justifications. No context. Only the values agents need. Written to Docs/Application/Architecture/backend-config.md.

# Backend Configuration

> Generated by TemperAI — temper-architect
> Version: [YYYYMMDD-HHMM]

Framework: [exact value with version — e.g. .NET 10]
Language: [exact value — e.g. C# 14]
ORM: [exact value with version — e.g. Entity Framework Core 10.0]
Data Access: [Repository + UnitOfWork | Direct DbContext]
Architecture: [Clean Architecture | Hexagonal Architecture | Vertical Slice Architecture | Onion Architecture]
Database: [exact value]
Auth: [exact value]
API Docs: [exact value]
Health Checks: [Yes / No]
Messaging: [exact value or None]
Caching: [exact value or None]
Logging: [exact value]

Dependencies:
  - [Package Name] [version — e.g. MailKit 4.8.0]
  - [Package Name] [version]
  [If none: "None beyond base stack"]

Rules for backend-config.md:

• ALWAYS emit Framework (+version), Language, and ORM (+version) so implementation agents can derive the correct technology root and ORM leaf. Default to .NET / C# / EF Core when the stack is the standard one.
• ALWAYS emit Data Access for ORM-based stacks (e.g. EF Core) as exactly one of Repository + UnitOfWork or Direct DbContext — the backend agent uses it to decide whether to load the repository/UnitOfWork skills or the direct-DbContext skill. The two are mutually exclusive; Repository and UnitOfWork are always adopted together. Omit this field only when the stack has no relational ORM.
• ALWAYS list confirmed dependencies under Dependencies as versioned package names (e.g. MailKit 4.8.0) — implementation agents need this to know what to install. This list is purely technical: no PRD justification text.

Ownership & maintenance:

• The architect owns the decision fields (Framework, Language, ORM, Data Access, Architecture, Database, Auth, API Docs, Health Checks, Messaging, Caching, Logging) and seeds the initial Dependencies list at design time. The architect only revisits these fields through a new design or problem-solving cycle.
• The Dependencies block is kept live by the backend agent: after any task that adds, removes, or upgrades a package, it reconciles the block from the real .csproj so the file never drifts from the actual project. It must not change any decision field. This keeps the file a trustworthy contract for every downstream agent that reads it.

---

Template: frontend-config.md

For frontend implementation agent only. Minimal and machine-readable. Written to Docs/Application/Architecture/frontend-config.md — only generated if the proposal includes a frontend.

# Frontend Configuration

> Generated by TemperAI — temper-architect
> Version: [YYYYMMDD-HHMM]

Framework: [exact value]
Backend URL: https://localhost:5001
Backend communication: [REST | GraphQL | SignalR | combination]
Auth handling: [exact value]
State management: [exact value]

---

Template: architectural-plan.md

For problem solving output. Full reasoning, for humans. Written to Docs/Application/Architecture/architectural-plan.md.

# Architectural Plan — [Problem Title]

> Generated by TemperAI — temper-architect
> Date: [YYYY-MM-DD]
> Version: [YYYYMMDD-HHMM]
> Status: Confirmed

---

## 1. Problem Statement

[Clear description of what is failing or blocking and its observable symptoms]

## 2. Root Cause Analysis

[Architectural or structural cause identified — not code-level]

## 3. Proposed Solution

**Step 1:** [action — what, where, why]
**Step 2:** [action — what, where, why]
**Step N:** [action — what, where, why]

## 4. Impact Assessment

- **Fixes:** [clear outcome]
- **Affects:** [parts of the system touched]
- **Does not change:** [explicit boundaries]

## 5. Risks

- [Risk 1]: [mitigation]
- [If none: "No significant risks identified"]

## 6. Alternatives Considered

- [Alternative 1]: rejected because [reason]
- [If none evaluated: "No alternatives evaluated"]

## 7. Decisions Overridden During Confirmation

- [Original] → [Confirmed] — [risk noted if any]
- [If none: "Plan confirmed as proposed"]

---

Template: api-contracts.md

Shared API contract extracted from the built backend code. Used by the frontend agent to ensure endpoint compatibility. Generated ONLY when user explicitly requests it after all build steps are approved and the backend is complete.

Written to Docs/Application/System/api-contracts.md.

Domain type reference (NOT C# types — use these domain types in DTO shapes):

Domain type	Meaning	Example
identifier	Unique ID	product ID, order ID
text	String value	name, description, email
number	Numeric value (integer or decimal)	price, quantity, stock
boolean	True/false	isActive, isAvailable
date	Date without time	birthDate, createdAt (date only)
datetime	Date and time	createdAt, updatedAt
enum:[TypeName]	Fixed set of values	enum:OrderStatus, enum:PaymentMethod

# API Contracts — [Project Name]

> Generated by TemperAI — temper-architect
> Extracted from: [list of controller files read]
> Version: [YYYYMMDD-HHMM]

## Conventions

- Route prefix: `/api/[entity-name-plural-kebab-case]`
- All errors returned as ProblemDetails
- Successful creation returns 201 with the created resource
- Successful update returns 200 with the updated resource
- Successful deletion returns 204 with no content
- All identifiers are `identifier` type (GUID in implementation)

---

## Endpoints

### [Entity Name]

| Operation | Method | Route | Request DTO | Response DTO |
|---|---|---|---|---|
| Create [entity] | POST | /api/[entities] | Create[Entity]Request | Create[Entity]Response |
| Get all [entities] | GET | /api/[entities] | — | List of [Entity]Response |
| Get [entity] by ID | GET | /api/[entities]/{id} | — | [Entity]Response |
| Update [entity] | PUT | /api/[entities]/{id} | Update[Entity]Request | Update[Entity]Response |
| Delete [entity] | DELETE | /api/[entities]/{id} | — | — |

[Repeat for each entity that has API endpoints]

---

## Data Contracts

### Create[Entity]Request

| Field | Type | Required | Validation | Description |
|---|---|---|---|---|
| [field] | [domain type] | Yes/No | [constraint — e.g. "max 100 chars", "positive"] | [what this field represents] |

### Create[Entity]Response

| Field | Type | Description |
|---|---|---|
| id | identifier | Unique [entity] identifier |
| [field] | [domain type] | [description] |

### [Entity]Response

| Field | Type | Description |
|---|---|---|
| id | identifier | Unique [entity] identifier |
| [field] | [domain type] | [description] |
| createdAt | datetime | When the [entity] was created |

### Update[Entity]Request

| Field | Type | Required | Validation | Description |
|---|---|---|---|---|
| [field] | [domain type] | Yes/No | [constraint] | [description] |

### Update[Entity]Response

| Field | Type | Description |
|---|---|---|
| id | identifier | Unique [entity] identifier |
| [field] | [domain type] | [description] |

[Repeat data contracts for each entity]

---

## Error Conditions

### [Entity Name] Errors

| Endpoint | Condition | Error Type | Detail |
|---|---|---|---|
| Create | [validation failure — e.g. "name exceeds max length"] | Validation | [error detail] |
| Create | [duplicate — e.g. "name already exists"] | Conflict | [error detail] |
| Get by ID | [not found] | Not Found | [error detail] |
| Update | [not found] | Not Found | [error detail] |
| Update | [validation failure] | Validation | [error detail] |
| Update | [no changes detected] | Validation | [error detail] |
| Delete | [not found] | Not Found | [error detail] |

[Repeat for each entity]

---

## Query Parameters

### GET /api/[entities] — Filtering and Pagination

| Parameter | Type | Required | Description |
|---|---|---|---|
| page | number | No | Page number (default: 1) |
| pageSize | number | No | Items per page (default: 20) |
| search | text | No | Search term for [searchable fields] |
| [filterField] | [type] | No | Filter by [field description] |

[Only include if the API actually supports search/filter/pagination]

Rules for generating api-contracts.md:

1. Extract from built backend code — read all controller files in the API project to derive actual endpoints
2. Use domain types, never C# types — identifier not Guid, text not string, number not decimal
3. DTO names follow conventions — Create[Entity]Request, Create[Entity]Response, [Entity]Response, Update[Entity]Request, Update[Entity]Response
4. Error conditions come from the validators — each validation rule maps to an error condition
5. Route names use plural kebab-case — /api/order-items, not /api/OrderItems or /api/orderItem
6. Only include query parameters if the API actually supports them — check the controller methods

---

DDD Documents

For DDD-Vocabulary.md, domain-model.md, and system-architecture.md — load the ddd/documents skill and follow its templates. The skill defines the exact format for each document. Do NOT attempt to generate these without loading the skill first.