architecture-docs

name	architecture-docs
description	Where architecture documents live, what each contains, and the conformance report format.

Architecture Documents

Canonical location, content contract, and conformance reporting format for the documents an architect produces. Load when writing, updating, or validating any of them.

---

Document Location Rule — CRITICAL

All architecture documents MUST be written to docs/development/ at the project root.

Document	Location
Architecture design	docs/development/architecture.md
Tech stack decisions	docs/development/tech-stack.md
Code standards	docs/development/code-standards.md
Database decisions	docs/development/database.md
API contracts	docs/development/api-contracts.md
ADRs	docs/development/adrs/NNNN-*.md
Conformance reports	docs/development/conformance-report.md

NEVER write architecture documents to:

• .opencode/ — opencode configuration only
• .claude/ — Claude Code configuration only
• .dev-team-agents/ — the framework installation directory
• Any hidden directory (starting with .)

---

Content Contract per Document

Document	Must contain
architecture.md	System design, layers, component boundaries, integration patterns, and the layer depth chosen per domain area. Every significant decision also gets an ADR.
tech-stack.md	Chosen technologies with rationale, including what was considered and rejected.
code-standards.md	Patterns, naming conventions, linting rules, and design patterns — specific to this project's stack, not generic advice.
database.md	Database choice, schema strategy, migration approach, indexing guidelines. Finalize only after database-specialist review.
api-contracts.md	API style (REST/GraphQL/RPC), versioning policy, auth model, response and error envelope.

Spec self-review before handing off — silently check every document for: placeholders and TODOs, contradictions between documents, ambiguous decisions, YAGNI violations, and scope creep. Fix inline before asking the user to review.

---

Conformance Report

Produced or updated after each Quality Gate run. Flag every finding with one tag:

Tag	Meaning
[ARCH-DEVIATION]	The code does not follow the decided architecture
[TECH-DEBT]	Acceptable shortcut, but it must be tracked
[CONFORMANT]	This is correct

Write to docs/development/conformance-report.md. This file accumulates across sprints — append, never overwrite.

## Conformance Report — [Sprint / Date]

### Summary
[Overall conformance posture — 1-2 sentences]

### Deviations
| File / Area | Deviation | Severity | Action |
|---|---|---|---|
| service/OrderService.js | Business logic in controller | HIGH | Refactor before next sprint |

### Tech Debt Tracked
| Item | Introduced | Owner | Target Sprint |
|---|---|---|---|

### Conformant Areas
[List areas that were reviewed and passed]