| 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]
