docs: initialize engineering starter kit

2026-06-28 09:40:40 +02:00
commit ed8efda692
23 changed files with 3131 additions and 0 deletions
@@ -0,0 +1,120 @@
 # Operating system
 .DS_Store
 .AppleDouble
 .LSOverride
 Thumbs.db
 Desktop.ini
 # Editor and IDE local state
 .idea/
 .vscode/
 *.swp
 *.swo
 *~
 # Environment and secrets
 .env
 .env.*
 !.env.example
 !.env.template
 *.local
 *.secret
 *.secrets
 *.key
 *.pem
 *.p12
 *.pfx
 # Logs and diagnostics
 *.log
 logs/
 log/
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 pnpm-debug.log*
 # Dependency directories
 node_modules/
 # Build outputs
 dist/
 build/
 out/
 public/build/
 .cache/
 .parcel-cache/
 .turbo/
 .vite/
 .next/
 .nuxt/
 .svelte-kit/
 coverage/
 # .NET
 bin/
 obj/
 TestResults/
 *.user
 *.suo
 # Java and JVM
 target/
 .gradle/
 *.class
 *.jar
 *.war
 *.ear
 # Python
 __pycache__/
 *.py[cod]
 .python-version
 .venv/
 venv/
 env/
 .pytest_cache/
 .mypy_cache/
 .ruff_cache/
 .tox/
 .coverage
 htmlcov/
 # Go
 *.test
 *.out
 # Native and desktop builds
 *.o
 *.obj
 *.dll
 *.dylib
 *.so
 *.exe
 *.app
 *.dmg
 # Archives and generated packages
 *.zip
 *.tar
 *.tar.gz
 *.tgz
 *.rar
 *.7z
 # Databases and local storage
 *.sqlite
 *.sqlite3
 *.db
 *.db-journal
 # Temporary files
 tmp/
 temp/
 .tmp/
 .temp/
 # Tool-specific local files
 .eslintcache
 .stylelintcache
 .phpunit.result.cache
@@ -0,0 +1,203 @@
 # AGENTS.md
 This file defines how AI coding agents should work in this repository.
 It is intended to remain mostly stable across projects.
 ## Core Principles
 1. Correctness comes before speed.
 2. Understand the objective before implementing.
 3. Prefer the repository's existing architecture and style over new patterns.
 4. Make small, reviewable changes with clear validation.
 5. Do not invent missing business logic, APIs, infrastructure, or requirements.
 6. Preserve user work and unrelated local changes.
 7. Explain important trade-offs clearly and concisely.
 ## Confidence Gate
 Before implementation, estimate whether the task is understood with high
 confidence.
 - If confidence is high, proceed and state any minor assumptions.
 - If confidence is below roughly 95%, ask concise clarifying questions.
 - If the ambiguity is isolated and low risk, make the smallest reasonable
  assumption and document it.
 - If the ambiguity affects data loss, security, public behavior, migrations,
  deployment, billing, authentication, authorization, or irreversible changes,
  stop and ask.
 Unknowns are not implementation details. Treat them as risks.
 ## Prompt Improvement
 When the user's request can be made safer or clearer:
 - Restate the objective in engineering terms.
 - Identify missing constraints or acceptance criteria.
 - Recommend a simpler or more maintainable approach when appropriate.
 - Challenge assumptions respectfully when they increase risk or complexity.
 - Keep the final decision with the user when product intent is involved.
 Do not silently change the user's goal. Improve execution, not intent.
 ## Success Criteria
 Every non-trivial task should have explicit success criteria before coding.
 At minimum, identify:
 - Expected behavior.
 - Files or modules likely affected.
 - Validation commands or manual checks.
 - Compatibility constraints.
 - Known risks.
 For documentation-only tasks, success criteria include clarity, consistency,
 link integrity, low duplication, and future maintainability.
 ## Repository Exploration
 Before modifying an existing repository:
 1. Inspect the repository status.
 2. Identify the main languages, frameworks, build tools, and test tools.
 3. Read relevant existing files before editing them.
 4. Search for established patterns before adding new abstractions.
 5. Check recent decisions, conventions, and project documentation.
 6. Understand whether the task is local-only, production-bound, or both.
 Prefer fast search tools such as `rg` and `rg --files` when available.
 ## Read Before Write
 Do not edit a file until you have read enough surrounding context to understand:
 - The file's responsibility.
 - Existing naming and formatting style.
 - Its dependencies and callers.
 - Its tests or validation path.
 - Whether local changes already exist.
 Never overwrite user changes unless explicitly instructed.
 ## Planning
 For non-trivial tasks, create a short plan before editing.
 A good plan includes:
 - Discovery steps.
 - Implementation steps.
 - Validation steps.
 - Review steps.
 Keep plans flexible. Update them when the repository teaches you something new.
 ## Implementation
 During implementation:
 - Keep changes scoped to the request.
 - Prefer simple, explicit code over clever abstractions.
 - Use existing project patterns and helpers.
 - Avoid broad refactors unless they are necessary for correctness or requested.
 - Add abstractions only when they remove meaningful duplication or clarify a
  stable concept.
 - Keep public interfaces backward compatible unless a breaking change is
  intentional and documented.
 - Treat configuration, credentials, and environment behavior as production risks.
 For documentation, prefer one authoritative source per topic and use links for
 related material.
 ## Validation
 Validate every change with the strongest practical signal.
 Examples:
 - Unit tests for isolated logic.
 - Integration tests for cross-module behavior.
 - Build/type checks for compile-time safety.
 - Lint/format checks when the project uses them.
 - Manual browser or API checks for user-facing behavior.
 - Documentation link review for documentation changes.
 If validation cannot be run, explain why and identify the remaining risk.
 ## Self Review
 Before finishing:
 1. Review the diff.
 2. Check for accidental files, secrets, debug code, and unrelated changes.
 3. Re-read changed documentation for clarity and duplication.
 4. Confirm tests or checks match the risk level.
 5. Verify the final state satisfies the original objective.
 ## Failure Analysis
 When something fails:
 - Capture the exact command, error, and context.
 - Identify whether the failure is caused by the change, environment, data, or an
  existing issue.
 - Try the next most direct diagnostic step.
 - Avoid speculative fixes without evidence.
 - Document unresolved failures and their impact.
 Do not hide validation failures.
 ## Communication
 Communicate like a senior engineering partner:
 - Be concise and precise.
 - State important assumptions.
 - Explain material trade-offs.
 - Separate confirmed facts from hypotheses.
 - Say what changed and how it was validated.
 - Call out residual risk.
 Avoid noisy narration. Keep the user oriented.
 ## Interactive vs Autonomous Execution
 Work autonomously when:
 - Requirements are clear.
 - The change is reversible.
 - The validation path is available.
 - The repository patterns are clear.
 Ask before proceeding when:
 - Requirements are materially ambiguous.
 - Multiple reasonable product behaviors exist.
 - The change may destroy data.
 - The change affects security, auth, billing, compliance, or production access.
 - A migration or deployment strategy is unclear.
 ## Efficient Use Of Delegated Agents
 Use delegated agents only when they are available and useful for independent,
 low-risk work such as:
 - Searching a large codebase for references.
 - Reviewing documentation for broken links.
 - Comparing repeated implementation patterns.
 - Running independent validation passes.
 Keep architectural decisions, final trade-offs, and risky implementation choices
 in the primary reasoning process.
 ## Definition Of Done
 A task is done when:
 - The requested behavior or artifact exists.
 - The implementation is consistent with repository architecture and conventions.
 - Relevant tests, builds, checks, or manual validation have been run.
 - Documentation is updated when behavior, setup, or architecture changed.
 - The diff has been reviewed for unrelated changes.
 - Known limitations or remaining risks are clearly communicated.
 - The final response names the changed areas and validation performed.
@@ -0,0 +1,117 @@
 # Engineering Starter Kit
 This repository is a reusable engineering foundation for new software projects.
 It is intentionally language, framework, architecture, and deployment agnostic.
 Use it to bootstrap consistent project documentation, architecture records,
 coding conventions, release practices, and AI-agent working agreements.
 ## What This Kit Provides
 - A universal AI-agent engineering contract in [AGENTS.md](AGENTS.md).
 - Project documentation guides in [docs/](docs/).
 - Copy-ready project templates in [templates/](templates/).
 - Completed examples in [examples/](examples/).
 - A language-agnostic [.gitignore](.gitignore) suitable for most starter repos.
 ## Documentation System
 Each document has one primary responsibility. Avoid duplicating the same policy
 or decision in multiple files; link to the source of truth instead.
 ```mermaid
 flowchart TD
    README["README.md<br/>How to use the kit"]
    AGENTS["AGENTS.md<br/>AI-agent working contract"]
    Project["docs/PROJECT.md<br/>Project intent and runtime facts"]
    Architecture["docs/ARCHITECTURE.md<br/>System structure and rules"]
    Conventions["docs/CONVENTIONS.md<br/>Engineering standards"]
    Decisions["docs/DECISIONS.md<br/>Architecture Decision Records"]
    Prompts["docs/PROMPTS.md<br/>Reusable engineering prompts"]
    Checklists["docs/CHECKLISTS.md<br/>Execution quality gates"]
    Workflow["docs/workflow.md<br/>Day-to-day delivery flow"]
    Branching["docs/branching.md<br/>Git branch strategy"]
    Release["docs/release-process.md<br/>Release governance"]
    Setup["docs/repository-setup.md<br/>Bootstrap instructions"]
    Templates["templates/<br/>Reusable placeholders"]
    Examples["examples/<br/>Completed reference project"]
    README --> AGENTS
    README --> Project
    README --> Architecture
    README --> Conventions
    README --> Decisions
    README --> Prompts
    README --> Checklists
    README --> Workflow
    Workflow --> Branching
    Workflow --> Release
    Setup --> Templates
    Templates --> Examples
    Project --> Architecture
    Architecture --> Decisions
    Conventions --> Checklists
 ```
 ## Document Responsibilities
 | File | Responsibility |
 | --- | --- |
 | [AGENTS.md](AGENTS.md) | Defines how AI coding agents should explore, plan, implement, validate, and communicate. |
 | [docs/PROJECT.md](docs/PROJECT.md) | Captures project-specific facts: vision, requirements, stack, infrastructure, operations, and roadmap. |
 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Describes the system shape, dependency rules, flows, security posture, and scalability model. |
 | [docs/CONVENTIONS.md](docs/CONVENTIONS.md) | Documents coding, testing, review, naming, organization, and collaboration standards. |
 | [docs/DECISIONS.md](docs/DECISIONS.md) | Stores Architecture Decision Records and their consequences. |
 | [docs/PROMPTS.md](docs/PROMPTS.md) | Provides reusable prompts for engineering work with humans and AI agents. |
 | [docs/CHECKLISTS.md](docs/CHECKLISTS.md) | Provides concise quality gates for common engineering tasks. |
 | [docs/workflow.md](docs/workflow.md) | Defines the end-to-end development workflow. |
 | [docs/branching.md](docs/branching.md) | Defines branch naming, merge policy, and release branch expectations. |
 | [docs/release-process.md](docs/release-process.md) | Defines release readiness, deployment, rollback, and post-release review. |
 | [docs/repository-setup.md](docs/repository-setup.md) | Explains how to turn this kit into a new project repository. |
 ## Recommended Bootstrap Workflow
 1. Copy this repository or use it as a template for a new project.
 2. Fill [templates/PROJECT.template.md](templates/PROJECT.template.md) and save it as `docs/PROJECT.md`.
 3. Fill [templates/ARCHITECTURE.template.md](templates/ARCHITECTURE.template.md) and save it as `docs/ARCHITECTURE.md`.
 4. Fill [templates/CONVENTIONS.template.md](templates/CONVENTIONS.template.md) and save it as `docs/CONVENTIONS.md`.
 5. Record material technical decisions with [templates/DECISIONS.template.md](templates/DECISIONS.template.md).
 6. Use [templates/FEATURE.template.md](templates/FEATURE.template.md) for non-trivial feature work.
 7. Keep [AGENTS.md](AGENTS.md) close to the root so AI tools can discover it automatically.
 8. Review [docs/CHECKLISTS.md](docs/CHECKLISTS.md) before opening pull requests or releasing.
 ## How AI Coding Agents Should Use This Repository
 AI agents should read [AGENTS.md](AGENTS.md) first, then inspect the relevant
 project documents before modifying code or documentation. For new projects, the
 minimum context set is:
 - [docs/PROJECT.md](docs/PROJECT.md)
 - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
 - [docs/CONVENTIONS.md](docs/CONVENTIONS.md)
 - [docs/DECISIONS.md](docs/DECISIONS.md)
 - [docs/CHECKLISTS.md](docs/CHECKLISTS.md)
 Agents should treat missing project facts as unknown, not as permission to
 invent business logic or architecture.
 ## Maintaining The Kit
 - Keep the kit generic unless a rule is broadly useful across many project types.
 - Prefer links over duplicated guidance.
 - Keep examples realistic but fictional.
 - Add new templates only when they solve repeated project setup or delivery work.
 - Update checklists when real incidents reveal missing quality gates.
 - Record significant changes to the kit itself as decisions in
  [docs/DECISIONS.md](docs/DECISIONS.md).
 ## Definition Of Ready For A New Project
 A project bootstrapped from this kit is ready for implementation when:
 - The project vision and constraints are documented.
 - The initial architecture style is selected or explicitly deferred.
 - Key conventions are documented.
 - The first delivery workflow is understood.
 - Required environments and secrets are identified.
 - Validation expectations are clear enough to prevent guesswork.
@@ -0,0 +1,193 @@
 # Architecture
 This document describes the structure, boundaries, flows, and technical rules of
 the system.
 For project intent and runtime facts, see [PROJECT.md](PROJECT.md).
 For coding standards, see [CONVENTIONS.md](CONVENTIONS.md).
 For recorded trade-offs, see [DECISIONS.md](DECISIONS.md).
 ## High-Level Overview
 `{{PROJECT_NAME}}` uses `{{ARCHITECTURE_STYLE}}` to support
 `{{PRIMARY_USE_CASES}}`.
 Replace this section with a concise explanation of the system's major parts,
 their responsibilities, and the constraints that shaped the architecture.
 ```mermaid
 flowchart LR
    User["User or External Client"]
    Interface["Interface Layer<br/>API, UI, CLI, Worker"]
    Application["Application Layer<br/>Use cases and orchestration"]
    Domain["Domain Layer<br/>Rules and invariants"]
    Infrastructure["Infrastructure Layer<br/>Database, queues, files, services"]
    External["External Systems"]
    User --> Interface
    Interface --> Application
    Application --> Domain
    Application --> Infrastructure
    Infrastructure --> External
 ```
 ## Architecture Style
 | Field | Value |
 | --- | --- |
 | Style | `{{ARCHITECTURE_STYLE}}` |
 | Primary reason | `{{ARCHITECTURE_REASON}}` |
 | Main trade-off | `{{ARCHITECTURE_TRADE_OFF}}` |
 | Related decision | [DECISIONS.md](DECISIONS.md) |
 Common examples include layered architecture, modular monolith, microservices,
 event-driven architecture, hexagonal architecture, desktop MVC/MVVM, or
 game-specific entity/component systems.
 ## Folder Structure
 ```text
 {{PROJECT_ROOT}}/
  {{SOURCE_FOLDER}}/
  {{TEST_FOLDER}}/
  {{DOCS_FOLDER}}/
  {{BUILD_FOLDER}}/
 ```
 | Folder | Responsibility |
 | --- | --- |
 | `{{FOLDER}}` | `{{FOLDER_RESPONSIBILITY}}` |
 Keep generated files, build outputs, and framework artifacts out of source
 folders unless the framework requires them.
 ## Module Responsibilities
 | Module | Responsibility | Owned Data | Public Interface |
 | --- | --- | --- | --- |
 | `{{MODULE_NAME}}` | `{{MODULE_RESPONSIBILITY}}` | `{{OWNED_DATA}}` | `{{PUBLIC_INTERFACE}}` |
 Modules should have clear ownership. Shared utilities should remain small and
 generic; domain behavior belongs with the module that owns the domain concept.
 ## Dependency Rules
 Define allowed dependencies explicitly.
 - `{{DEPENDENCY_RULE_1}}`
 - `{{DEPENDENCY_RULE_2}}`
 - `{{DEPENDENCY_RULE_3}}`
 Recommended default:
 ```mermaid
 flowchart TD
    UI["UI, API, CLI, Worker"]
    App["Application"]
    Domain["Domain"]
    Infra["Infrastructure"]
    UI --> App
    App --> Domain
    App --> Infra
    Infra --> Domain
 ```
 Domain code should not depend on delivery mechanisms, databases, network
 clients, or framework-specific runtime concerns unless the project intentionally
 uses an architecture where that trade-off is accepted and recorded.
 ## Request Flow
 ```mermaid
 sequenceDiagram
    participant Client
    participant Interface
    participant Application
    participant Domain
    participant Infrastructure
    Client->>Interface: Request or command
    Interface->>Application: Validate transport shape
    Application->>Domain: Execute business rule
    Application->>Infrastructure: Persist or integrate
    Infrastructure-->>Application: Result
    Application-->>Interface: Response model
    Interface-->>Client: Response
 ```
 Document deviations for async jobs, desktop workflows, games, or event-driven
 flows.
 ## Data Flow
 | Data | Source | Owner | Storage | Consumers |
 | --- | --- | --- | --- | --- |
 | `{{DATA_ENTITY}}` | `{{DATA_SOURCE}}` | `{{DATA_OWNER}}` | `{{DATA_STORAGE}}` | `{{DATA_CONSUMERS}}` |
 Data ownership should be clear before adding shared tables, shared schemas,
 cross-service writes, or replicated state.
 ## Domain Model
 | Concept | Meaning | Invariants |
 | --- | --- | --- |
 | `{{DOMAIN_CONCEPT}}` | `{{DOMAIN_MEANING}}` | `{{DOMAIN_INVARIANTS}}` |
 Use this section for durable business concepts, not framework models or DTOs.
 ## Integration Points
 | Integration | Direction | Protocol | Reliability Expectations |
 | --- | --- | --- | --- |
 | `{{INTEGRATION_NAME}}` | `{{INBOUND_OR_OUTBOUND}}` | `{{PROTOCOL}}` | `{{RELIABILITY_EXPECTATIONS}}` |
 For each integration, document authentication, retry behavior, timeouts,
 idempotency, and failure handling.
 ## Security
 | Area | Policy |
 | --- | --- |
 | Authentication | `{{AUTHENTICATION_POLICY}}` |
 | Authorization | `{{AUTHORIZATION_POLICY}}` |
 | Secrets | `{{SECRETS_POLICY}}` |
 | Input validation | `{{INPUT_VALIDATION_POLICY}}` |
 | Output encoding | `{{OUTPUT_ENCODING_POLICY}}` |
 | Audit logging | `{{AUDIT_LOGGING_POLICY}}` |
 | Dependency security | `{{DEPENDENCY_SECURITY_POLICY}}` |
 Security-sensitive decisions should be recorded in [DECISIONS.md](DECISIONS.md).
 ## Error Handling
 | Error Type | Handling Policy | User/Client Response |
 | --- | --- | --- |
 | Validation error | `{{VALIDATION_ERROR_POLICY}}` | `{{VALIDATION_RESPONSE}}` |
 | Domain error | `{{DOMAIN_ERROR_POLICY}}` | `{{DOMAIN_RESPONSE}}` |
 | Infrastructure error | `{{INFRASTRUCTURE_ERROR_POLICY}}` | `{{INFRASTRUCTURE_RESPONSE}}` |
 | Unexpected error | `{{UNEXPECTED_ERROR_POLICY}}` | `{{UNEXPECTED_RESPONSE}}` |
 Errors should preserve enough diagnostic context for operators without exposing
 secrets or internal implementation details to users.
 ## Performance
 | Concern | Expectation | Measurement |
 | --- | --- | --- |
 | Latency | `{{LATENCY_EXPECTATION}}` | `{{LATENCY_MEASUREMENT}}` |
 | Throughput | `{{THROUGHPUT_EXPECTATION}}` | `{{THROUGHPUT_MEASUREMENT}}` |
 | Resource usage | `{{RESOURCE_EXPECTATION}}` | `{{RESOURCE_MEASUREMENT}}` |
 Document known hot paths and the expected performance test strategy.
 ## Scalability
 | Dimension | Current Strategy | Future Strategy |
 | --- | --- | --- |
 | Traffic | `{{TRAFFIC_STRATEGY}}` | `{{TRAFFIC_FUTURE_STRATEGY}}` |
 | Data volume | `{{DATA_VOLUME_STRATEGY}}` | `{{DATA_VOLUME_FUTURE_STRATEGY}}` |
 | Team size | `{{TEAM_SCALE_STRATEGY}}` | `{{TEAM_SCALE_FUTURE_STRATEGY}}` |
 Scalability work should be driven by measured pressure or clear product
 requirements, not premature complexity.
@@ -0,0 +1,107 @@
 # Checklists
 Use these concise checklists as quality gates. Expand them only when repeated
 project experience proves that more detail is necessary.
 For workflow details, see [workflow.md](workflow.md).
 For code standards, see [CONVENTIONS.md](CONVENTIONS.md).
 For releases, see [release-process.md](release-process.md).
 ## Feature Development
 - [ ] Objective and acceptance criteria are clear.
 - [ ] Relevant docs and existing implementation were read.
 - [ ] Architecture boundaries are respected.
 - [ ] User-facing behavior is implemented.
 - [ ] Edge cases and failure states are handled.
 - [ ] Tests or manual checks cover the main behavior.
 - [ ] Documentation is updated when behavior or setup changed.
 ## Bug Fix
 - [ ] Observed behavior is understood.
 - [ ] Expected behavior is confirmed.
 - [ ] Root cause is identified before changing code.
 - [ ] Fix is scoped to the cause.
 - [ ] Regression coverage is added when practical.
 - [ ] Validation proves the bug is fixed.
 - [ ] Remaining risk is documented.
 ## Refactoring
 - [ ] Behavior-preserving intent is explicit.
 - [ ] Existing tests or checks are identified.
 - [ ] Changes are small and reviewable.
 - [ ] Public contracts remain stable or the break is approved.
 - [ ] Dead code is removed only when safe.
 - [ ] Validation is run before and after meaningful changes.
 ## API Review
 - [ ] Consumer needs are clear.
 - [ ] Request and response contracts are stable.
 - [ ] Validation errors are consistent.
 - [ ] Authorization is explicit.
 - [ ] Pagination, filtering, and sorting are defined where needed.
 - [ ] Idempotency is addressed for retryable writes.
 - [ ] Versioning and compatibility are considered.
 ## Database Review
 - [ ] Data ownership is clear.
 - [ ] Constraints protect important invariants.
 - [ ] Indexes match expected query patterns.
 - [ ] Migration is reversible or rollback-safe.
 - [ ] Backfill and deployment order are documented.
 - [ ] Retention and privacy requirements are addressed.
 - [ ] Backup and restore impact is understood.
 ## Security Review
 - [ ] Authentication is required where expected.
 - [ ] Authorization is enforced server-side or at the trusted boundary.
 - [ ] Inputs are validated.
 - [ ] Outputs are safely encoded or serialized.
 - [ ] Secrets are not logged or committed.
 - [ ] Sensitive data exposure is minimized.
 - [ ] Dependency risk is reviewed.
 - [ ] Abuse cases and rate limits are considered where relevant.
 ## Performance Review
 - [ ] Hot paths are identified.
 - [ ] Database queries are bounded and indexed.
 - [ ] Network calls have timeouts and retry policy where appropriate.
 - [ ] Expensive work is cached, batched, async, or justified.
 - [ ] UI updates avoid unnecessary re-rendering where relevant.
 - [ ] Performance expectations are measurable.
 ## Pull Request
 - [ ] Summary explains what and why.
 - [ ] Scope is focused.
 - [ ] Tests or checks are listed.
 - [ ] Screenshots or recordings are included for UI changes.
 - [ ] Migration and deployment notes are included when relevant.
 - [ ] Risks and follow-ups are documented.
 - [ ] No secrets, debug code, or unrelated files are included.
 ## Release
 - [ ] Release scope is defined.
 - [ ] Required checks passed.
 - [ ] Database migrations are reviewed.
 - [ ] Configuration and secrets are ready.
 - [ ] Rollback plan exists.
 - [ ] Monitoring and alerting are ready.
 - [ ] Stakeholders are informed.
 ## Production Readiness
 - [ ] Runtime environments are documented.
 - [ ] Health checks exist.
 - [ ] Logs include correlation identifiers.
 - [ ] Backups and restore process are tested or scheduled.
 - [ ] Alerts cover availability and critical failures.
 - [ ] Security-critical settings are production-safe.
 - [ ] Operational runbooks exist for common failures.
@@ -0,0 +1,210 @@
 # Conventions
 This document defines project engineering standards. It should remain practical,
 specific, and enforceable.
 For project facts, see [PROJECT.md](PROJECT.md).
 For architecture boundaries, see [ARCHITECTURE.md](ARCHITECTURE.md).
 For task quality gates, see [CHECKLISTS.md](CHECKLISTS.md).
 ## Naming
 Use names that expose intent and domain meaning.
 - Prefer domain terms over technical shorthand.
 - Avoid abbreviations unless they are widely understood in the project.
 - Name booleans as predicates, such as `isEnabled`, `hasPermission`, or
  `canRetry`.
 - Name commands by action and object, such as `CreateInvoice` or
  `syncCustomer`.
 - Name events in past tense when they represent something that happened.
 Add language-specific naming rules here:
 - `{{LANGUAGE_NAMING_RULE}}`
 ## File Organization
 Files should have one clear responsibility.
 - Keep files small enough to review comfortably.
 - Co-locate tests with the tested module when that matches the stack convention.
 - Separate generated files from hand-written source.
 - Avoid catch-all utility files that collect unrelated behavior.
 Project-specific rules:
 - `{{FILE_ORGANIZATION_RULE}}`
 ## Folder Organization
 Folders should communicate ownership and architecture boundaries.
 - Organize by feature or module when domain ownership matters.
 - Organize by technical layer only when it improves clarity for the project.
 - Keep public interfaces easy to find.
 - Keep infrastructure details out of domain folders unless deliberately chosen.
 Project-specific folder map:
 | Folder | Rule |
 | --- | --- |
 | `{{FOLDER}}` | `{{FOLDER_RULE}}` |
 ## Dependency Injection
 Use dependency injection to make boundaries explicit and tests practical.
 - Inject external resources, clocks, random generators, HTTP clients, file
  systems, queues, and database access.
 - Avoid service locators unless the framework requires them.
 - Keep object lifetimes explicit.
 - Do not inject dependencies that are pure values or local implementation
  details.
 Project-specific DI rules:
 - `{{DEPENDENCY_INJECTION_RULE}}`
 ## Logging
 Logging should support operations and debugging without leaking sensitive data.
 - Use structured logs when the platform supports them.
 - Include correlation or request identifiers.
 - Log decisions and external failures at meaningful boundaries.
 - Do not log secrets, access tokens, passwords, private keys, or full payment
  data.
 - Avoid noisy logs inside tight loops or high-volume paths.
 Project-specific logging rules:
 - `{{LOGGING_RULE}}`
 ## Validation
 Validation should happen at the correct boundary.
 - Validate transport shape at the interface boundary.
 - Validate business invariants in the domain or application layer.
 - Validate persistence constraints before relying on database failures for
  expected user errors.
 - Return actionable validation feedback where appropriate.
 Project-specific validation rules:
 - `{{VALIDATION_RULE}}`
 ## Error Handling
 Errors should be explicit, observable, and safe.
 - Use typed or structured errors where the language supports them.
 - Do not swallow exceptions without a recovery path.
 - Map internal errors to stable user-facing or client-facing responses.
 - Preserve diagnostic context for logs.
 - Avoid exposing stack traces or implementation details to users.
 Project-specific error rules:
 - `{{ERROR_HANDLING_RULE}}`
 ## DTO Rules
 DTOs represent boundary contracts.
 - Keep DTOs separate from domain models when they change for different reasons.
 - Do not put business rules in DTOs.
 - Version public contracts deliberately.
 - Validate DTO shape before mapping to domain commands or queries.
 - Avoid leaking persistence models through public APIs.
 Project-specific DTO rules:
 - `{{DTO_RULE}}`
 ## Repository Rules
 Repositories, gateways, or data access abstractions should express persistence
 intent without hiding important consistency behavior.
 - Keep query methods specific enough to reveal purpose.
 - Avoid generic repositories when they obscure domain behavior.
 - Document transaction boundaries.
 - Make idempotency explicit for write operations where retries are possible.
 Project-specific repository rules:
 - `{{REPOSITORY_RULE}}`
 ## Service Rules
 Services should coordinate use cases, not become unbounded containers.
 - Prefer cohesive application services around use cases.
 - Keep domain rules in domain objects or domain services.
 - Keep infrastructure calls behind clear interfaces.
 - Avoid services named only after technical actions such as `Manager`,
  `Helper`, or `Processor` unless the meaning is precise in context.
 Project-specific service rules:
 - `{{SERVICE_RULE}}`
 ## Testing
 Tests should match risk and behavior.
 - Unit test domain logic and pure transformations.
 - Integration test database, queue, file, network, and framework boundaries.
 - End-to-end test critical user journeys.
 - Regression test bugs before or with the fix.
 - Keep tests deterministic and independent where practical.
 Project-specific testing rules:
 - `{{TESTING_RULE}}`
 ## Git Workflow
 Use [branching.md](branching.md) for branch strategy.
 Default expectations:
 - Keep commits focused and reviewable.
 - Write commit messages that describe the reason and outcome.
 - Rebase or merge according to the project branch policy.
 - Do not mix unrelated refactors with behavior changes.
 ## Pull Requests
 Pull requests should explain what changed, why it changed, and how it was
 validated.
 Recommended PR sections:
 - Summary.
 - Scope.
 - Validation.
 - Risks.
 - Screenshots or recordings for UI changes.
 - Migration or deployment notes when relevant.
 Use [CHECKLISTS.md](CHECKLISTS.md) before requesting review.
 ## Code Reviews
 Reviews should prioritize correctness and maintainability.
 Review for:
 - Behavior and edge cases.
 - Security and authorization.
 - Data integrity.
 - Architecture boundaries.
 - Test quality.
 - Operational impact.
 - Readability.
 Style comments should reference documented conventions or automated tooling
 where possible.
@@ -0,0 +1,247 @@
 # Decisions
 This document contains Architecture Decision Records (ADRs).
 Use ADRs for decisions that materially affect architecture, operations,
 security, team workflow, data ownership, public contracts, or long-term
 maintainability.
 For architecture context, see [ARCHITECTURE.md](ARCHITECTURE.md).
 For project constraints, see [PROJECT.md](PROJECT.md).
 ## Status Values
 - Proposed: under discussion.
 - Accepted: current decision.
 - Superseded: replaced by a newer decision.
 - Deprecated: no longer recommended, but still present.
 - Rejected: considered and intentionally not chosen.
 ## ADR Index
 | ID | Title | Status | Date |
 | --- | --- | --- | --- |
 | ADR-000 | ADR template | Accepted | `{{DATE}}` |
 | ADR-001 | Example: Start with a modular monolith | Example | 2026-06-28 |
 | ADR-002 | Example: Keep project documentation in the repository | Example | 2026-06-28 |
 | ADR-003 | Example: Require explicit validation evidence before merge | Example | 2026-06-28 |
 ## ADR-000: ADR Template
 ### Title
 `{{DECISION_TITLE}}`
 ### Status
 `{{STATUS}}`
 ### Date
 `{{DATE}}`
 ### Context
 `{{CONTEXT}}`
 Describe the environment, constraints, project stage, team needs, and forces
 that make the decision necessary.
 ### Problem
 `{{PROBLEM}}`
 State the specific problem being solved. Avoid combining unrelated decisions.
 ### Alternatives
 | Alternative | Summary |
 | --- | --- |
 | `{{ALTERNATIVE_1}}` | `{{ALTERNATIVE_1_SUMMARY}}` |
 | `{{ALTERNATIVE_2}}` | `{{ALTERNATIVE_2_SUMMARY}}` |
 | `{{ALTERNATIVE_3}}` | `{{ALTERNATIVE_3_SUMMARY}}` |
 ### Pros
 - `{{PRO}}`
 ### Cons
 - `{{CON}}`
 ### Decision
 `{{DECISION}}`
 Write the chosen option and why it best fits the current constraints.
 ### Consequences
 - `{{CONSEQUENCE}}`
 Document expected benefits, costs, operational impacts, migration needs, and
 future review triggers.
 ## ADR-001: Example: Start With A Modular Monolith
 ### Title
 Start with a modular monolith before introducing microservices.
 ### Status
 Example
 ### Date
 2026-06-28
 ### Context
 The fictional project `Atlas Desk` is a new workflow application with one small
 team, one primary database, and requirements that are still evolving.
 ### Problem
 The team needs clear module boundaries without accepting the operational cost of
 distributed services too early.
 ### Alternatives
 | Alternative | Summary |
 | --- | --- |
 | Layered monolith | Simple to build, but feature boundaries may become unclear. |
 | Modular monolith | Strong internal boundaries with one deployable unit. |
 | Microservices | Independent deployments, but higher operational and data consistency cost. |
 ### Pros
 - Preserves deployment simplicity.
 - Supports clear module ownership.
 - Avoids premature distributed transactions and network failure modes.
 - Allows extraction of services later when boundaries are proven.
 ### Cons
 - Requires discipline to maintain module boundaries.
 - Independent scaling by module is limited.
 - Poor internal boundaries can still create a tightly coupled system.
 ### Decision
 Use a modular monolith as the initial architecture.
 ### Consequences
 - Module boundaries must be documented in [ARCHITECTURE.md](ARCHITECTURE.md).
 - Cross-module access must go through public interfaces.
 - Service extraction can be reconsidered when team scale, traffic, or ownership
  pressure justifies it.
 ## ADR-002: Example: Keep Project Documentation In The Repository
 ### Title
 Keep durable engineering documentation in the source repository.
 ### Status
 Example
 ### Date
 2026-06-28
 ### Context
 The project will use issue trackers and chat for coordination, but architecture,
 setup, and operating knowledge must remain discoverable by humans and AI agents.
 ### Problem
 External documentation often drifts from code and is harder for development
 tools to discover during implementation.
 ### Alternatives
 | Alternative | Summary |
 | --- | --- |
 | Repository documentation | Versioned with code and easy for agents to read. |
 | Wiki | Easier non-developer editing, but often drifts from code changes. |
 | Chat-only knowledge | Fast, but not durable or discoverable. |
 ### Pros
 - Documentation changes can be reviewed with code.
 - Agents and developers can discover project context locally.
 - Historical context remains connected to commits.
 ### Cons
 - Non-developers may find editing less convenient.
 - Documentation quality still requires review discipline.
 - Large diagrams or rich media may need external tooling.
 ### Decision
 Keep durable engineering documentation in the repository under `docs/`.
 ### Consequences
 - Pull requests that change architecture or operations should update docs.
 - Temporary planning can live elsewhere, but accepted decisions belong here.
 - Links must be reviewed as part of documentation changes.
 ## ADR-003: Example: Require Explicit Validation Evidence Before Merge
 ### Title
 Require explicit validation evidence before merging changes.
 ### Status
 Example
 ### Date
 2026-06-28
 ### Context
 The project may use AI-assisted development and multiple contributors. Reviewers
 need a reliable way to understand how changes were checked.
 ### Problem
 Pull requests without validation evidence increase review time and regression
 risk.
 ### Alternatives
 | Alternative | Summary |
 | --- | --- |
 | No required evidence | Fastest locally, but makes review less reliable. |
 | Validation summary in PR | Lightweight and visible to reviewers. |
 | Full test report artifact only | Detailed, but harder to scan for small changes. |
 ### Pros
 - Reviewers can evaluate risk quickly.
 - Missing tests or blocked checks are visible.
 - AI-generated changes become easier to trust or challenge.
 ### Cons
 - Contributors must spend time recording checks.
 - Some exploratory changes may need a lighter process before formal review.
 ### Decision
 Every pull request must include a short validation section listing commands,
 manual checks, or reasons validation could not be run.
 ### Consequences
 - PR templates should include validation.
 - Reviewers can block merges when risk is high and evidence is missing.
 - Failed or skipped validation must be explained.
@@ -0,0 +1,185 @@
 # Project
 This document is the source of truth for project intent, scope, runtime facts,
 and operational expectations.
 For implementation structure, see [ARCHITECTURE.md](ARCHITECTURE.md).
 For engineering standards, see [CONVENTIONS.md](CONVENTIONS.md).
 For delivery workflow, see [workflow.md](workflow.md).
 ## Project Identity
 | Field | Value |
 | --- | --- |
 | Project name | `{{PROJECT_NAME}}` |
 | Repository | `{{REPOSITORY_URL}}` |
 | Primary owner | `{{OWNER}}` |
 | Status | `{{STATUS}}` |
 | Target users | `{{TARGET_USERS}}` |
 ## Vision
 `{{PROJECT_VISION}}`
 Describe the long-term purpose of the project in one or two paragraphs.
 The vision should explain why the project exists, not how it is implemented.
 ## Goals
 - `{{GOAL_1}}`
 - `{{GOAL_2}}`
 - `{{GOAL_3}}`
 Goals should be measurable enough to guide trade-offs.
 ## Non-Goals
 - `{{NON_GOAL_1}}`
 - `{{NON_GOAL_2}}`
 Non-goals prevent accidental scope expansion.
 ## Functional Requirements
 | ID | Requirement | Priority | Status |
 | --- | --- | --- | --- |
 | FR-001 | `{{FUNCTIONAL_REQUIREMENT}}` | Must | Proposed |
 ## Non-Functional Requirements
 | Category | Requirement | Measurement |
 | --- | --- | --- |
 | Availability | `{{AVAILABILITY_REQUIREMENT}}` | `{{AVAILABILITY_MEASURE}}` |
 | Performance | `{{PERFORMANCE_REQUIREMENT}}` | `{{PERFORMANCE_MEASURE}}` |
 | Security | `{{SECURITY_REQUIREMENT}}` | `{{SECURITY_MEASURE}}` |
 | Privacy | `{{PRIVACY_REQUIREMENT}}` | `{{PRIVACY_MEASURE}}` |
 | Maintainability | `{{MAINTAINABILITY_REQUIREMENT}}` | `{{MAINTAINABILITY_MEASURE}}` |
 ## Users And Roles
 | Role | Description | Key Permissions |
 | --- | --- | --- |
 | `{{ROLE_NAME}}` | `{{ROLE_DESCRIPTION}}` | `{{ROLE_PERMISSIONS}}` |
 ## Tech Stack
 | Area | Choice | Notes |
 | --- | --- | --- |
 | Language | `{{LANGUAGE}}` | `{{LANGUAGE_NOTES}}` |
 | Framework | `{{FRAMEWORK}}` | `{{FRAMEWORK_NOTES}}` |
 | Frontend | `{{FRONTEND}}` | `{{FRONTEND_NOTES}}` |
 | Backend | `{{BACKEND}}` | `{{BACKEND_NOTES}}` |
 | Database | `{{DATABASE}}` | `{{DATABASE_NOTES}}` |
 | Messaging | `{{MESSAGING}}` | `{{MESSAGING_NOTES}}` |
 | Search | `{{SEARCH}}` | `{{SEARCH_NOTES}}` |
 | Cache | `{{CACHE}}` | `{{CACHE_NOTES}}` |
 ## Runtime
 | Environment | Purpose | URL or Entry Point | Notes |
 | --- | --- | --- | --- |
 | Local | Development | `{{LOCAL_URL}}` | `{{LOCAL_NOTES}}` |
 | Test | Automated validation | `{{TEST_URL}}` | `{{TEST_NOTES}}` |
 | Staging | Release verification | `{{STAGING_URL}}` | `{{STAGING_NOTES}}` |
 | Production | Live system | `{{PRODUCTION_URL}}` | `{{PRODUCTION_NOTES}}` |
 ## Frameworks
 Document framework-specific expectations here only when they affect how the
 project is built, tested, deployed, or maintained.
 - `{{FRAMEWORK_CONSTRAINT}}`
 - `{{FRAMEWORK_EXTENSION_POINT}}`
 ## Infrastructure
 | Component | Provider | Responsibility | Notes |
 | --- | --- | --- | --- |
 | Hosting | `{{HOSTING_PROVIDER}}` | `{{HOSTING_RESPONSIBILITY}}` | `{{HOSTING_NOTES}}` |
 | Storage | `{{STORAGE_PROVIDER}}` | `{{STORAGE_RESPONSIBILITY}}` | `{{STORAGE_NOTES}}` |
 | Network | `{{NETWORK_PROVIDER}}` | `{{NETWORK_RESPONSIBILITY}}` | `{{NETWORK_NOTES}}` |
 ## Database
 | Field | Value |
 | --- | --- |
 | Database engine | `{{DATABASE}}` |
 | Migration tool | `{{MIGRATION_TOOL}}` |
 | Backup strategy | `{{BACKUP_STRATEGY}}` |
 | Restore strategy | `{{RESTORE_STRATEGY}}` |
 | Data retention | `{{DATA_RETENTION}}` |
 ## CI/CD
 | Pipeline | Trigger | Required Checks | Notes |
 | --- | --- | --- | --- |
 | `{{PIPELINE_NAME}}` | `{{PIPELINE_TRIGGER}}` | `{{PIPELINE_CHECKS}}` | `{{PIPELINE_NOTES}}` |
 ## Deployment
 | Area | Policy |
 | --- | --- |
 | Deployment strategy | `{{DEPLOYMENT}}` |
 | Rollback strategy | `{{ROLLBACK_STRATEGY}}` |
 | Release owner | `{{RELEASE_OWNER}}` |
 | Change window | `{{CHANGE_WINDOW}}` |
 See [release-process.md](release-process.md) for release execution.
 ## Authentication
 | Field | Value |
 | --- | --- |
 | Authentication method | `{{AUTHENTICATION_METHOD}}` |
 | Identity provider | `{{IDENTITY_PROVIDER}}` |
 | Session model | `{{SESSION_MODEL}}` |
 | Token lifetime | `{{TOKEN_LIFETIME}}` |
 ## Authorization
 | Field | Value |
 | --- | --- |
 | Authorization model | `{{AUTHORIZATION_MODEL}}` |
 | Role source | `{{ROLE_SOURCE}}` |
 | Policy location | `{{POLICY_LOCATION}}` |
 | Audit requirements | `{{AUTHORIZATION_AUDIT_REQUIREMENTS}}` |
 ## Logging
 | Field | Value |
 | --- | --- |
 | Logging library | `{{LOGGING_LIBRARY}}` |
 | Log sink | `{{LOG_SINK}}` |
 | Correlation ID | `{{CORRELATION_ID_POLICY}}` |
 | Sensitive data policy | `{{LOG_SENSITIVE_DATA_POLICY}}` |
 ## Monitoring
 | Signal | Tool | Alert Policy |
 | --- | --- | --- |
 | Availability | `{{AVAILABILITY_TOOL}}` | `{{AVAILABILITY_ALERT_POLICY}}` |
 | Errors | `{{ERROR_TOOL}}` | `{{ERROR_ALERT_POLICY}}` |
 | Performance | `{{PERFORMANCE_TOOL}}` | `{{PERFORMANCE_ALERT_POLICY}}` |
 | Business metrics | `{{BUSINESS_METRICS_TOOL}}` | `{{BUSINESS_ALERT_POLICY}}` |
 ## Testing
 | Test Type | Tooling | Required When |
 | --- | --- | --- |
 | Unit | `{{UNIT_TEST_TOOL}}` | `{{UNIT_TEST_POLICY}}` |
 | Integration | `{{INTEGRATION_TEST_TOOL}}` | `{{INTEGRATION_TEST_POLICY}}` |
 | End-to-end | `{{E2E_TEST_TOOL}}` | `{{E2E_TEST_POLICY}}` |
 | Performance | `{{PERFORMANCE_TEST_TOOL}}` | `{{PERFORMANCE_TEST_POLICY}}` |
 | Security | `{{SECURITY_TEST_TOOL}}` | `{{SECURITY_TEST_POLICY}}` |
 ## Roadmap
 | Milestone | Target | Outcome |
 | --- | --- | --- |
 | `{{MILESTONE}}` | `{{TARGET_DATE}}` | `{{OUTCOME}}` |
 ## Open Questions
 | Question | Owner | Needed By | Status |
 | --- | --- | --- | --- |
 | `{{OPEN_QUESTION}}` | `{{QUESTION_OWNER}}` | `{{NEEDED_BY}}` | Open |
@@ -0,0 +1,310 @@
 # Prompts
 This file is a reusable engineering prompt library for humans and AI coding
 agents.
 Use these prompts together with [AGENTS.md](../AGENTS.md),
 [PROJECT.md](PROJECT.md), [ARCHITECTURE.md](ARCHITECTURE.md), and
 [CONVENTIONS.md](CONVENTIONS.md).
 ## Prompt Pattern
 Strong prompts include:
 - Objective.
 - Relevant files, URLs, tickets, or logs.
 - Constraints and non-goals.
 - Expected output.
 - Validation expectations.
 - Whether the agent should implement, plan only, or review only.
 ## Feature Development
 ```text
 Act as a senior software engineer in this repository.
 Objective:
 Implement {{FEATURE_NAME}}.
 Context:
 - Product goal: {{PRODUCT_GOAL}}
 - Relevant docs: docs/PROJECT.md, docs/ARCHITECTURE.md, docs/CONVENTIONS.md
 - Relevant files: {{RELEVANT_FILES}}
 Requirements:
 - {{REQUIREMENT_1}}
 - {{REQUIREMENT_2}}
 Non-goals:
 - {{NON_GOAL_1}}
 Before coding:
 - Inspect the current implementation.
 - Identify ambiguity.
 - Ask concise questions if confidence is below 95%.
 After coding:
 - Run the strongest practical validation.
 - Summarize changed files, validation, and residual risk.
 ```
 ## Bug Investigation
 ```text
 Investigate this bug before changing code.
 Observed behavior:
 {{OBSERVED_BEHAVIOR}}
 Expected behavior:
 {{EXPECTED_BEHAVIOR}}
 Evidence:
 {{LOGS_SCREENSHOTS_OR_STEPS}}
 Task:
 - Reproduce or reason from available evidence.
 - Identify the most likely root cause.
 - Locate the affected code path.
 - Propose the smallest maintainable fix.
 - Implement only after the cause is understood.
 - Add or update regression coverage where practical.
 ```
 ## Root Cause Analysis
 ```text
 Perform a root cause analysis for {{INCIDENT_OR_DEFECT}}.
 Include:
 - Timeline.
 - User impact.
 - Technical trigger.
 - Root cause.
 - Contributing factors.
 - Detection gap.
 - Corrective actions.
 - Preventive actions.
 Separate confirmed facts from hypotheses.
 Do not assign blame to individuals.
 ```
 ## Refactoring
 ```text
 Refactor {{AREA}} to improve {{QUALITY_GOAL}}.
 Constraints:
 - Preserve behavior.
 - Keep public contracts stable unless explicitly approved.
 - Avoid broad unrelated cleanup.
 - Follow docs/ARCHITECTURE.md and docs/CONVENTIONS.md.
 Process:
 - Inspect existing patterns.
 - Identify tests or checks that protect behavior.
 - Make small mechanical changes first.
 - Run validation after meaningful steps.
 - Summarize behavior-preservation evidence.
 ```
 ## Architecture Review
 ```text
 Review the architecture of {{SYSTEM_OR_MODULE}}.
 Use:
 - docs/PROJECT.md
 - docs/ARCHITECTURE.md
 - docs/DECISIONS.md
 - Relevant source files
 Focus on:
 - Boundary clarity.
 - Dependency direction.
 - Data ownership.
 - Failure modes.
 - Security assumptions.
 - Operational complexity.
 - Maintainability over the next {{TIME_HORIZON}}.
 Return:
 - Findings ordered by severity.
 - Trade-offs.
 - Recommended decisions or ADR updates.
 ```
 ## Security Review
 ```text
 Perform a security review of {{SCOPE}}.
 Focus on:
 - Authentication.
 - Authorization.
 - Input validation.
 - Output encoding.
 - Secrets handling.
 - Data exposure.
 - Dependency risk.
 - Logging of sensitive data.
 - SSRF, injection, XSS, CSRF, path traversal, and insecure deserialization where relevant.
 For each finding include:
 - Impact.
 - Exploitability.
 - Evidence.
 - Recommended fix.
 - Validation strategy.
 ```
 ## Performance Review
 ```text
 Review performance risk in {{SCOPE}}.
 Include:
 - Hot paths.
 - Algorithmic complexity.
 - Database query behavior.
 - Caching behavior.
 - Network calls.
 - Rendering or UI bottlenecks.
 - Resource usage.
 - Measurement gaps.
 Recommend improvements only when they are justified by evidence, constraints, or clear risk.
 ```
 ## Documentation
 ```text
 Improve documentation for {{AREA}}.
 Goals:
 - Make setup and maintenance easier.
 - Remove outdated or duplicated information.
 - Add cross links to related docs.
 - Keep one source of truth per topic.
 Validate:
 - Links are correct.
 - Commands are current.
 - Examples are realistic.
 - The document is useful to a new contributor.
 ```
 ## API Design
 ```text
 Design or review the API for {{CAPABILITY}}.
 Include:
 - Consumers.
 - Resource or command model.
 - Request and response shapes.
 - Validation errors.
 - Authorization rules.
 - Idempotency.
 - Pagination or filtering.
 - Versioning.
 - Backward compatibility.
 - Observability.
 Prefer stable contracts over exposing internal persistence models.
 ```
 ## Database Design
 ```text
 Design or review database changes for {{CAPABILITY}}.
 Include:
 - Entities and ownership.
 - Relationships.
 - Constraints.
 - Indexes.
 - Migration strategy.
 - Rollback strategy.
 - Backfill needs.
 - Data retention.
 - Privacy concerns.
 - Query patterns.
 Do not implement destructive migrations without explicit approval.
 ```
 ## Test Generation
 ```text
 Generate tests for {{SCOPE}}.
 Use the repository's existing test patterns.
 Cover:
 - Happy path.
 - Boundary conditions.
 - Authorization or permission behavior when relevant.
 - Error handling.
 - Regression cases.
 Avoid brittle tests that depend on incidental implementation details.
 ```
 ## Code Review
 ```text
 Review the provided changes as a senior engineer.
 Prioritize:
 - Bugs.
 - Security issues.
 - Data loss risk.
 - Behavioral regressions.
 - Missing validation.
 - Maintainability issues.
 Return findings first, ordered by severity, with file and line references where available.
 Keep summary secondary.
 ```
 ## Pull Request Review
 ```text
 Review this pull request.
 Use:
 - PR description.
 - Diff.
 - Linked issue or requirement.
 - Relevant project docs.
 Assess:
 - Whether the change solves the stated problem.
 - Whether the implementation fits the architecture.
 - Whether tests and validation match the risk.
 - Whether rollout or migration notes are missing.
 Return:
 - Blocking findings.
 - Non-blocking suggestions.
 - Questions.
 - Merge readiness.
 ```
 ## Technical Debt Review
 ```text
 Assess technical debt in {{SCOPE}}.
 Classify findings by:
 - User impact.
 - Engineering drag.
 - Risk.
 - Estimated effort.
 - Suggested sequencing.
 Do not recommend rewrites unless incremental improvement is clearly worse.
 Prefer concrete next steps over broad critique.
 ```
@@ -0,0 +1,111 @@
 # Branching Strategy
 This document defines the default Git branching strategy.
 For delivery workflow, see [workflow.md](workflow.md).
 For pull request expectations, see [CONVENTIONS.md](CONVENTIONS.md#pull-requests).
 ## Default Model
 Use a simple trunk-based model unless the project has a clear reason to add
 long-lived release branches.
 ```mermaid
 gitGraph
    commit id: "main"
    branch feature
    checkout feature
    commit id: "work"
    commit id: "validate"
    checkout main
    merge feature
    commit id: "release"
 ```
 ## Branch Types
 | Type | Pattern | Purpose |
 | --- | --- | --- |
 | Feature | `feature/{{short-description}}` | New user-facing or system capability. |
 | Bug fix | `fix/{{short-description}}` | Defect correction. |
 | Refactor | `refactor/{{short-description}}` | Behavior-preserving structural improvement. |
 | Documentation | `docs/{{short-description}}` | Documentation-only changes. |
 | Chore | `chore/{{short-description}}` | Maintenance work with no product behavior change. |
 | Release | `release/{{version}}` | Optional stabilization branch for release trains. |
 | Hotfix | `hotfix/{{short-description}}` | Urgent production correction. |
 ## Main Branch
 The `main` branch should remain deployable or releasable according to the
 project's release model.
 Minimum expectations:
 - Required checks pass.
 - Changes are reviewed when the project requires review.
 - Risky migrations and config changes are documented.
 - Direct pushes are limited to repository maintainers or automation.
 ## Feature Branches
 Feature branches should be short lived.
 - Keep scope focused.
 - Rebase or merge from `main` according to project policy.
 - Delete branches after merge.
 - Avoid stacking unrelated changes.
 ## Release Branches
 Use release branches only when needed for stabilization, compliance, or release
 train coordination.
 Release branches should receive:
 - Critical fixes.
 - Release documentation.
 - Version updates.
 - No unrelated refactors.
 ## Hotfixes
 Hotfixes should prioritize production restoration.
 Process:
 1. Create a hotfix branch from the deployed commit or release branch.
 2. Apply the smallest safe fix.
 3. Validate the specific failure path.
 4. Release.
 5. Merge the hotfix back into `main`.
 6. Add follow-up work for broader cleanup if needed.
 ## Commit Messages
 Use meaningful commit messages that explain the outcome.
 Recommended format:
 ```text
 {{type}}: {{short imperative summary}}
 {{optional context, rationale, or validation notes}}
 ```
 Examples:
 - `docs: add starter architecture guide`
 - `fix: prevent duplicate invoice submission`
 - `refactor: isolate payment gateway retries`
 ## Merge Policy
 Choose one policy per project:
 | Policy | Best When |
 | --- | --- |
 | Squash merge | Small teams want clean history and one commit per PR. |
 | Merge commit | Teams want to preserve branch context. |
 | Rebase merge | Teams want linear history with individual commits. |
 Record the selected policy in [PROJECT.md](PROJECT.md) or this file.
@@ -0,0 +1,98 @@
 # Release Process
 This document defines the default release process.
 For daily delivery flow, see [workflow.md](workflow.md).
 For branch policy, see [branching.md](branching.md).
 For release checklist, see [CHECKLISTS.md](CHECKLISTS.md#release).
 ## Release Principles
 - Release small changes when practical.
 - Prefer repeatable automation over manual steps.
 - Validate before and after deployment.
 - Keep rollback or recovery options ready.
 - Record production-impacting decisions.
 ## Release Types
 | Type | Description | Example |
 | --- | --- | --- |
 | Standard | Planned release through the normal pipeline. | Weekly feature release. |
 | Hotfix | Urgent production fix. | Authorization regression fix. |
 | Experimental | Limited rollout or feature flag release. | Beta feature for selected users. |
 | Infrastructure | Runtime, hosting, network, or dependency change. | Database engine upgrade. |
 ## Versioning
 Choose the versioning model that matches the project:
 - Semantic versioning for libraries, APIs, SDKs, and installable packages.
 - Calendar versioning for operational products with frequent releases.
 - Build numbers or commit SHAs for internal services.
 Document the chosen model in [PROJECT.md](PROJECT.md).
 ## Readiness
 Before release:
 - Scope is confirmed.
 - Required checks pass.
 - Migrations are reviewed.
 - Configuration is ready.
 - Secrets are present in the target environment.
 - Rollback or recovery plan exists.
 - Monitoring is available.
 - Stakeholders know the release window when needed.
 ## Deployment
 Deployment steps:
 1. Confirm target environment.
 2. Confirm release version or commit.
 3. Run pre-deploy checks.
 4. Deploy.
 5. Run migrations when required by the release plan.
 6. Run smoke tests.
 7. Monitor health and error signals.
 8. Announce completion or rollback.
 ## Smoke Tests
 Smoke tests should prove that the release is alive and the most important path
 works.
 Examples:
 - Health endpoint returns success.
 - Application loads.
 - Login works.
 - Critical API endpoint succeeds.
 - Background worker starts.
 - Database connectivity is healthy.
 ## Rollback And Recovery
 Rollback planning should address:
 - Application artifact rollback.
 - Database migration rollback or forward fix.
 - Configuration rollback.
 - Feature flag disablement.
 - Queue or job replay behavior.
 - External dependency failure.
 If database changes are not reversible, document the recovery path before
 deployment.
 ## Post-Release Review
 After release:
 - Confirm monitoring is quiet or expected.
 - Record incidents or anomalies.
 - Update docs if release steps drifted.
 - Add follow-up tasks for manual work discovered during release.
 - Capture lessons in checklists or ADRs when they change future behavior.
@@ -0,0 +1,104 @@
 # Repository Setup
 This document explains how to use the Engineering Starter Kit for a new project.
 For the recommended documentation flow, see [../README.md](../README.md).
 For the AI-agent contract, see [../AGENTS.md](../AGENTS.md).
 ## Bootstrap Options
 Choose one:
 | Option | Use When |
 | --- | --- |
 | Copy repository | You want a simple starting point without preserving starter-kit history. |
 | Template repository | Your Git host supports creating repositories from a template. |
 | Subtree or vendor copy | You want to periodically pull updates from this kit. |
 Do not use this starter kit as a runtime dependency. It is project scaffolding
 and documentation architecture.
 ## Initial Setup
 1. Create the new repository.
 2. Copy the starter-kit files.
 3. Replace placeholder values such as `{{PROJECT_NAME}}`, `{{LANGUAGE}}`,
   `{{FRAMEWORK}}`, `{{DATABASE}}`, and `{{DEPLOYMENT}}`.
 4. Delete sections that are not relevant to the project.
 5. Add project-specific setup commands.
 6. Commit the initialized documentation before major implementation work.
 ## Recommended First Commit
 The first commit should establish:
 - `README.md`.
 - `AGENTS.md`.
 - `docs/PROJECT.md`.
 - `docs/ARCHITECTURE.md`.
 - `docs/CONVENTIONS.md`.
 - `docs/DECISIONS.md`.
 - `.gitignore`.
 - Tooling or source skeleton if already known.
 ## Project-Specific Customization
 Update these files first:
 | File | Required Customization |
 | --- | --- |
 | [PROJECT.md](PROJECT.md) | Vision, requirements, stack, environments, operations, and roadmap. |
 | [ARCHITECTURE.md](ARCHITECTURE.md) | Architecture style, folder structure, module boundaries, and flows. |
 | [CONVENTIONS.md](CONVENTIONS.md) | Language, framework, testing, review, and repository-specific rules. |
 | [DECISIONS.md](DECISIONS.md) | Accepted project decisions. Remove examples when real ADRs exist. |
 | [workflow.md](workflow.md) | Delivery steps, required checks, and review expectations. |
 | [branching.md](branching.md) | Branch naming and merge policy. |
 | [release-process.md](release-process.md) | Release, rollback, and monitoring expectations. |
 ## Placeholder Policy
 Before a project is considered initialized:
 - Replace placeholders when the answer is known.
 - Keep placeholders only when the unknown is intentional.
 - Track important unknowns in [PROJECT.md](PROJECT.md#open-questions).
 - Do not leave placeholders in public-facing documentation.
 ## AI Agent Setup
 For AI-assisted projects:
 1. Keep [../AGENTS.md](../AGENTS.md) at the repository root.
 2. Tell agents to read `AGENTS.md` before making changes.
 3. Keep architecture and conventions current enough for agents to follow them.
 4. Require final summaries to include changed files, validation, and risk.
 ## Documentation Review
 After setup:
 - Check every relative link.
 - Remove duplicated guidance.
 - Verify each document has one responsibility.
 - Confirm examples are marked as examples.
 - Confirm project-specific docs do not describe the starter kit itself.
 ## When To Add More Documents
 Add a new document only when:
 - The topic is durable.
 - The topic has a clear owner or responsibility.
 - The content would otherwise make another document unfocused.
 - The document will be maintained.
 Good candidates:
 - `docs/security.md`
 - `docs/operations.md`
 - `docs/api.md`
 - `docs/testing.md`
 - `docs/runbooks/`
 Avoid creating documents for temporary plans that belong in issues or pull
 requests.
@@ -0,0 +1,120 @@
 # Development Workflow
 This document defines the default path from idea to released change.
 For branch policy, see [branching.md](branching.md).
 For release execution, see [release-process.md](release-process.md).
 For task quality gates, see [CHECKLISTS.md](CHECKLISTS.md).
 ## Workflow Overview
 ```mermaid
 flowchart LR
    Idea["Idea or Issue"]
    Clarify["Clarify Scope"]
    Design["Design or Plan"]
    Implement["Implement"]
    Validate["Validate"]
    Review["Review"]
    Merge["Merge"]
    Release["Release"]
    Learn["Review Outcome"]
    Idea --> Clarify
    Clarify --> Design
    Design --> Implement
    Implement --> Validate
    Validate --> Review
    Review --> Merge
    Merge --> Release
    Release --> Learn
 ```
 ## 1. Clarify Scope
 Before implementation:
 - Define the objective.
 - Identify users or systems affected.
 - Confirm acceptance criteria.
 - Identify non-goals.
 - Note security, data, migration, and deployment risk.
 If the task is ambiguous, resolve ambiguity before writing code.
 ## 2. Design Or Plan
 Use a lightweight plan for most changes.
 Create or update an ADR in [DECISIONS.md](DECISIONS.md) when the change affects:
 - Architecture style.
 - Module boundaries.
 - Data ownership.
 - Security model.
 - Deployment strategy.
 - Public contracts.
 - Long-term operating cost.
 ## 3. Implement
 Implementation expectations:
 - Work in a focused branch unless the project policy says otherwise.
 - Read existing code before editing.
 - Follow [CONVENTIONS.md](CONVENTIONS.md).
 - Keep commits logically grouped.
 - Update documentation with behavior, setup, or architecture changes.
 ## 4. Validate
 Use the strongest practical validation for the change:
 - Build or type checks.
 - Unit tests.
 - Integration tests.
 - End-to-end tests.
 - Manual UI or API checks.
 - Documentation link checks.
 Record validation evidence in the pull request or final work summary.
 ## 5. Review
 Review should answer:
 - Does the change solve the stated problem?
 - Is it consistent with [ARCHITECTURE.md](ARCHITECTURE.md)?
 - Does it follow [CONVENTIONS.md](CONVENTIONS.md)?
 - Are risks and rollback needs clear?
 - Is validation sufficient?
 ## 6. Merge
 Before merge:
 - Required checks pass.
 - Review comments are resolved.
 - Branch is up to date according to project policy.
 - Release notes or changelog entries are added when relevant.
 ## 7. Release
 Follow [release-process.md](release-process.md).
 Release work should include:
 - Final readiness check.
 - Deployment.
 - Smoke test.
 - Monitoring.
 - Rollback readiness.
 ## 8. Review Outcome
 After meaningful releases or incidents:
 - Capture what worked.
 - Capture what failed.
 - Update checklists, docs, tests, or runbooks.
 - Add ADRs for decisions that emerged during delivery.
@@ -0,0 +1,158 @@
 # Atlas Desk Architecture
 Atlas Desk uses a modular monolith with a Vue frontend, ASP.NET Core API, and
 PostgreSQL database.
 ## High-Level Overview
 The system is deployed as one backend service and one frontend artifact. The
 backend owns authentication integration, authorization, request workflows, audit
 events, and persistence. The frontend renders queue workflows and calls the API.
 ```mermaid
 flowchart LR
    User["Support User"]
    Browser["Vue SPA"]
    API["ASP.NET Core API"]
    Modules["Application Modules"]
    Domain["Domain Model"]
    Database["PostgreSQL"]
    IdP["Identity Provider"]
    User --> Browser
    Browser --> API
    API --> Modules
    Modules --> Domain
    Modules --> Database
    API --> IdP
 ```
 ## Architecture Style
 | Field | Value |
 | --- | --- |
 | Style | Modular monolith |
 | Primary reason | Small team, shared database, evolving domain boundaries. |
 | Main trade-off | Requires discipline to prevent module coupling. |
 | Related decision | ADR-001 in `DECISIONS.example.md`. |
 ## Folder Structure
 ```text
 atlas-desk/
  backend/
    src/
      Requests/
      Users/
      Reporting/
      Shared/
    tests/
  frontend/
    src/
      features/
      shared/
    tests/
  docs/
 ```
 | Folder | Responsibility |
 | --- | --- |
 | `backend/src/Requests` | Request lifecycle, assignment, notes, and closure. |
 | `backend/src/Users` | User profile and role synchronization. |
 | `backend/src/Reporting` | Queue health and manager dashboards. |
 | `frontend/src/features` | User-facing feature modules. |
 | `frontend/src/shared` | Reusable UI and API utilities. |
 ## Module Responsibilities
 | Module | Responsibility | Owned Data | Public Interface |
 | --- | --- | --- | --- |
 | Requests | Support request workflow. | Requests, notes, assignments, audit events. | Request commands and query endpoints. |
 | Users | Local user profile and role cache. | Users and role snapshots. | User lookup service. |
 | Reporting | Aggregated queue health views. | Read models derived from requests. | Reporting queries. |
 ## Dependency Rules
 - Feature modules may depend on `Shared`.
 - `Reporting` reads request data through query interfaces, not direct mutation.
 - Domain rules do not depend on HTTP, Vue, or database APIs.
 - Infrastructure implementations depend inward on application contracts.
 ## Request Flow
 ```mermaid
 sequenceDiagram
    participant Browser
    participant API
    participant Auth
    participant Requests
    participant Database
    Browser->>API: POST /api/requests/{id}/assign
    API->>Auth: Check Manager or Agent policy
    API->>Requests: AssignRequest command
    Requests->>Database: Save assignment and audit event
    Database-->>Requests: Commit result
    Requests-->>API: Updated request summary
    API-->>Browser: 200 OK
 ```
 ## Data Flow
 | Data | Source | Owner | Storage | Consumers |
 | --- | --- | --- | --- | --- |
 | Support request | Agent or imported email | Requests module | PostgreSQL | Agents, managers, reporting. |
 | User role | Identity provider | Users module | PostgreSQL role snapshot | Authorization policies. |
 | Queue metrics | Request state changes | Reporting module | Materialized query table | Manager dashboard. |
 ## Domain Model
 | Concept | Meaning | Invariants |
 | --- | --- | --- |
 | Request | A customer support item requiring work. | Must have status, priority, creator, and audit history. |
 | Assignment | Ownership of a request by a user. | Only active users can own open requests. |
 | Audit Event | Immutable record of important workflow action. | Cannot be edited after creation. |
 ## Integration Points
 | Integration | Direction | Protocol | Reliability Expectations |
 | --- | --- | --- | --- |
 | Identity provider | Outbound | OpenID Connect | Login must fail closed if identity cannot be verified. |
 | Email notifications | Outbound | SMTP or provider API | Retry transient failures; never block core assignment transaction. |
 ## Security
 | Area | Policy |
 | --- | --- |
 | Authentication | All application routes require authenticated users. |
 | Authorization | Backend policies enforce role and ownership checks. |
 | Secrets | Secrets are environment-provided and never committed. |
 | Input validation | API validates DTO shape before command execution. |
 | Output encoding | Frontend renders user content safely through framework escaping. |
 | Audit logging | Assignment, closure, and role changes create audit events. |
 | Dependency security | CI runs dependency audit before release. |
 ## Error Handling
 | Error Type | Handling Policy | User/Client Response |
 | --- | --- | --- |
 | Validation error | Return field-level errors. | 400 with validation details. |
 | Domain error | Return stable problem code. | 409 or 422 with safe message. |
 | Infrastructure error | Log with correlation ID and retry if safe. | 503 for transient failures. |
 | Unexpected error | Log, alert if elevated, hide details. | 500 with correlation ID. |
 ## Performance
 | Concern | Expectation | Measurement |
 | --- | --- | --- |
 | Latency | P95 below 300 ms for core endpoints. | API metrics. |
 | Throughput | 100 concurrent active users. | Load test before production launch. |
 | Resource usage | Single service fits standard container profile. | Runtime metrics. |
 ## Scalability
 | Dimension | Current Strategy | Future Strategy |
 | --- | --- | --- |
 | Traffic | Single API service with horizontal scaling. | Split reporting read model if dashboards become expensive. |
 | Data volume | PostgreSQL indexes for active queue queries. | Archive closed requests older than retention threshold. |
 | Team size | Module ownership within one repo. | Extract services only after boundaries and ownership stabilize. |
@@ -0,0 +1,93 @@
 # Atlas Desk Conventions
 ## Naming
 - Use support-domain language: request, assignment, note, queue, audit event.
 - Use `Async` suffix for asynchronous backend methods.
 - Name Vue components by feature and purpose, such as `RequestDetailPanel`.
 - Name authorization policies by action, such as `CanAssignRequest`.
 ## File Organization
 - Keep backend files under their owning module.
 - Keep Vue components below 250 lines when practical.
 - Co-locate component tests with feature components.
 - Keep generated API types in `frontend/src/shared/api/generated`.
 ## Folder Organization
 | Folder | Rule |
 | --- | --- |
 | `backend/src/Requests` | Owns request workflow commands, queries, and domain rules. |
 | `backend/src/Shared` | Contains cross-cutting primitives only. |
 | `frontend/src/features/requests` | Owns request screens and feature-specific components. |
 | `frontend/src/shared` | Contains reusable UI primitives and API utilities. |
 ## Dependency Injection
 - Register backend services by module.
 - Inject clocks, email clients, database contexts, and external gateways.
 - Do not inject primitive configuration values directly into domain classes.
 ## Logging
 - Use structured logs with `requestId` and `userId` where available.
 - Log workflow transitions at information level.
 - Log authorization denials at warning level only when they indicate suspicious behavior.
 - Do not log customer message bodies.
 ## Validation
 - Validate API DTO shape at the API boundary.
 - Validate workflow invariants inside request commands.
 - Validate authorization before loading sensitive detail views.
 ## Error Handling
 - Use stable problem codes for client-visible API errors.
 - Return validation errors as field-level responses.
 - Include correlation IDs in error responses.
 - Do not expose stack traces outside local development.
 ## DTO Rules
 - API DTOs are separate from persistence entities.
 - Request detail DTOs must not include internal audit metadata unless the user has manager or auditor access.
 - Public API changes require a changelog entry.
 ## Repository Rules
 - Keep queries explicit, such as `FindOpenRequestsForQueue`.
 - Do not add generic repository abstractions over the database context.
 - Write operations that can be retried must be idempotent or transactionally protected.
 ## Service Rules
 - Application services coordinate commands and queries.
 - Domain services contain request workflow rules only when the rule spans entities.
 - External email delivery is behind an interface.
 ## Testing
 - Unit test request state transitions.
 - Integration test authorization and database persistence.
 - End-to-end test create, assign, comment, and close workflows.
 - Add regression tests for production defects.
 ## Git Workflow
 - Branch names use `feature/`, `fix/`, `refactor/`, `docs/`, or `hotfix/`.
 - Squash merge pull requests into `main`.
 - Commit messages use imperative summaries.
 ## Pull Requests
 - Include summary, validation, risk, and screenshots for UI changes.
 - Include migration notes when database schema changes.
 - Keep unrelated refactors in separate pull requests.
 ## Code Reviews
 - Block on correctness, security, data integrity, missing validation, or unclear ownership.
 - Prefer suggestions for style issues that are not covered by tooling.
 - Ask for ADR updates when a decision changes system structure.
@@ -0,0 +1,150 @@
 # Atlas Desk Decisions
 ## ADR-001: Start With A Modular Monolith
 ### Status
 Accepted
 ### Date
 2026-06-28
 ### Context
 Atlas Desk is new, the team is small, and the request workflow domain is still
 evolving. The system needs clear boundaries, but it does not yet need
 independent service deployments.
 ### Problem
 The team must choose an architecture that supports maintainability without
 adding unnecessary operational complexity.
 ### Alternatives
 | Alternative | Summary |
 | --- | --- |
 | Layered monolith | Simple, but feature ownership can blur over time. |
 | Modular monolith | Clear module boundaries with one deployable unit. |
 | Microservices | Strong service isolation but adds network, deployment, and data consistency cost. |
 ### Pros
 - Keeps deployment simple.
 - Supports explicit module ownership.
 - Allows future service extraction if boundaries prove stable.
 ### Cons
 - Requires discipline to maintain module boundaries.
 - Scaling is initially at the application level, not module level.
 ### Decision
 Use a modular monolith for the first production release.
 ### Consequences
 - Module dependency rules are documented in the architecture guide.
 - Cross-module writes are not allowed without an application-level command.
 - Microservice extraction will be reconsidered only after measured pressure.
 ## ADR-002: Use PostgreSQL As The Primary Data Store
 ### Status
 Accepted
 ### Date
 2026-06-28
 ### Context
 Atlas Desk needs transactional consistency for request state, assignment, notes,
 and audit events.
 ### Problem
 The team needs a reliable primary database that supports relational queries,
 transactions, and reporting-friendly indexes.
 ### Alternatives
 | Alternative | Summary |
 | --- | --- |
 | PostgreSQL | Strong relational database with good operational support. |
 | Document database | Flexible schema but weaker fit for transactional queue workflows. |
 | Embedded database | Simple locally but not suitable for shared production usage. |
 ### Pros
 - Strong transactions.
 - Mature indexing and query capabilities.
 - Good fit for reporting queries.
 - Broad hosting support.
 ### Cons
 - Schema changes require migration discipline.
 - Query performance must be monitored as data grows.
 ### Decision
 Use PostgreSQL as the primary data store.
 ### Consequences
 - Migrations must be reviewed before release.
 - Integration tests should run against PostgreSQL, not an incompatible in-memory substitute.
 - Backup and restore procedures are production readiness requirements.
 ## ADR-003: Require Backend Authorization For All Sensitive Actions
 ### Status
 Accepted
 ### Date
 2026-06-28
 ### Context
 The frontend hides actions based on role, but API clients cannot be trusted to
 enforce authorization.
 ### Problem
 Sensitive actions such as assignment, closure, and audit viewing must be
 protected even if a user bypasses the UI.
 ### Alternatives
 | Alternative | Summary |
 | --- | --- |
 | Frontend-only checks | Better user experience but not a security boundary. |
 | Backend policy checks | Trusted enforcement point. |
 | Database row-level security | Strong but more complex than needed initially. |
 ### Pros
 - Keeps authorization in a trusted boundary.
 - Makes behavior testable through API integration tests.
 - Supports multiple clients later.
 ### Cons
 - Requires explicit policy coverage for each sensitive endpoint.
 - UI and API authorization rules can drift without tests.
 ### Decision
 Enforce authorization in backend policies for all sensitive actions.
 ### Consequences
 - Frontend checks remain usability hints only.
 - Authorization tests are required for each protected workflow.
 - Policy changes must be reviewed as security-sensitive changes.
@@ -0,0 +1,93 @@
 # Feature: Request Assignment
 ## Objective
 Allow agents and managers to assign an open support request to an active agent.
 ## User Or System Value
 Support teams can see clear ownership for every active request and reduce
 duplicate work.
 ## Requirements
 - Agents can assign unowned requests to themselves.
 - Managers can assign requests to any active agent.
 - Assignment creates an audit event.
 - Closed requests cannot be reassigned.
 ## Non-Goals
 - Automated assignment rules.
 - Workload balancing.
 - External notifications beyond a basic assignment event.
 ## Acceptance Criteria
 - [ ] An agent can assign an unowned open request to themselves.
 - [ ] A manager can assign an open request to another active agent.
 - [ ] A non-manager cannot assign a request to another user.
 - [ ] Closed requests return a domain error when assignment is attempted.
 - [ ] Every successful assignment writes an audit event.
 ## Architecture Notes
 - Affected modules: Requests, Users.
 - Dependency concerns: Requests queries Users through a user lookup interface.
 - Data ownership: Requests owns assignments and audit events.
 - Related ADRs: ADR-001, ADR-003.
 ## API Or Interface Changes
 ```http
 POST /api/requests/{requestId}/assignment
 Content-Type: application/json
 {
  "assigneeUserId": "usr_123"
 }
 ```
 Successful response:
 ```json
 {
  "requestId": "req_456",
  "assigneeUserId": "usr_123",
  "status": "open"
 }
 ```
 ## Data Changes
 - Add `assigned_to_user_id` to requests if not already present.
 - Add `RequestAssigned` audit event type.
 - Index active requests by assigned user for queue views.
 ## Security And Authorization
 - Authenticated agents can assign requests to themselves.
 - Managers can assign requests to any active agent.
 - Backend policies enforce assignment permissions.
 - Frontend controls are not considered a security boundary.
 ## Testing Plan
 - Unit: request assignment state transitions and closed-request rejection.
 - Integration: authorization cases and audit event persistence.
 - End-to-end: create request, assign, and confirm queue ownership changes.
 - Manual: verify manager and agent UI states.
 ## Rollout Plan
 Deploy backend and frontend together. Run a smoke test that assigns a staging
 request as an agent and as a manager.
 ## Risks
 - Authorization drift between UI and API.
 - Assignment race when two users assign the same request at the same time.
 ## Open Questions
 - Should assignment notify the assignee immediately in the first release?
@@ -0,0 +1,167 @@
 # Atlas Desk
 Atlas Desk is a fictional internal support workflow system for small operations
 teams.
 ## Vision
 Give support teams one reliable place to triage customer requests, assign work,
 track status, and understand operational bottlenecks without relying on shared
 mailboxes or spreadsheets.
 ## Goals
 - Reduce average request triage time by 40 percent.
 - Make ownership and status visible for every support request.
 - Provide an audit trail for customer-impacting decisions.
 ## Non-Goals
 - Replace the billing system.
 - Provide public customer self-service in the first release.
 - Support multi-region deployment before usage requires it.
 ## Functional Requirements
 | ID | Requirement | Priority | Status |
 | --- | --- | --- | --- |
 | FR-001 | Agents can create, assign, and close support requests. | Must | Accepted |
 | FR-002 | Managers can view queue health and overdue work. | Must | Accepted |
 | FR-003 | Users can add internal notes to requests. | Should | Proposed |
 | FR-004 | The system sends notifications when ownership changes. | Should | Proposed |
 ## Non-Functional Requirements
 | Category | Requirement | Measurement |
 | --- | --- | --- |
 | Availability | Available during support hours. | 99.5 percent monthly uptime. |
 | Performance | Common list and detail views feel immediate. | P95 API latency below 300 ms for core endpoints. |
 | Security | Only authorized users can view or mutate requests. | Authorization tests cover each role. |
 | Privacy | Customer contact data is minimized and auditable. | Sensitive fields are excluded from debug logs. |
 | Maintainability | New queue workflows can be added without rewriting the core model. | Feature modules own their workflows. |
 ## Users And Roles
 | Role | Description | Key Permissions |
 | --- | --- | --- |
 | Agent | Handles support requests. | Create, update, assign, comment, close. |
 | Manager | Oversees queue health. | All agent permissions plus reporting and reassignment. |
 | Auditor | Reviews historical activity. | Read-only access to requests and audit events. |
 ## Tech Stack
 | Area | Choice | Notes |
 | --- | --- | --- |
 | Language | C# and TypeScript | Backend and frontend use separate type systems. |
 | Framework | ASP.NET Core and Vue | Conventional web application stack. |
 | Frontend | Vue 3 | Single-page application. |
 | Backend | ASP.NET Core | Modular monolith API. |
 | Database | PostgreSQL | Primary transactional store. |
 | Messaging | None initially | Reconsider if notification volume grows. |
 | Search | PostgreSQL full-text search | Sufficient for initial request search. |
 | Cache | None initially | Add only after measured pressure. |
 ## Runtime
 | Environment | Purpose | URL or Entry Point | Notes |
 | --- | --- | --- | --- |
 | Local | Development | `https://localhost:5173` | Frontend talks to local API. |
 | Test | Automated validation | CI service containers | Uses ephemeral PostgreSQL. |
 | Staging | Release verification | `https://staging.atlas-desk.example` | Mirrors production config. |
 | Production | Live system | `https://atlas-desk.example` | Single-region deployment. |
 ## Infrastructure
 | Component | Provider | Responsibility | Notes |
 | --- | --- | --- | --- |
 | Hosting | Managed container platform | Run API and frontend assets. | One service initially. |
 | Storage | PostgreSQL managed database | Store requests, users, audit events. | Daily backups. |
 | Network | Managed load balancer | TLS and routing. | Internal admin access restricted. |
 ## Database
 | Field | Value |
 | --- | --- |
 | Database engine | PostgreSQL |
 | Migration tool | Entity Framework Core migrations |
 | Backup strategy | Daily automated backup with 14-day retention |
 | Restore strategy | Restore to staging monthly as a drill |
 | Data retention | Closed requests retained for 3 years |
 ## CI/CD
 | Pipeline | Trigger | Required Checks | Notes |
 | --- | --- | --- | --- |
 | CI | Pull request and push to main | Build, unit tests, integration tests, lint | Blocks merge. |
 | Deploy staging | Push to main | CI success | Automatic. |
 | Deploy production | Manual approval | Staging smoke test | Release owner approves. |
 ## Deployment
 | Area | Policy |
 | --- | --- |
 | Deployment strategy | Rolling container deployment |
 | Rollback strategy | Redeploy previous image and disable feature flags |
 | Release owner | Support platform maintainer |
 | Change window | Weekdays before 15:00 local support time |
 ## Authentication
 | Field | Value |
 | --- | --- |
 | Authentication method | OpenID Connect |
 | Identity provider | Company identity provider |
 | Session model | Secure HTTP-only cookie |
 | Token lifetime | 8-hour workday session |
 ## Authorization
 | Field | Value |
 | --- | --- |
 | Authorization model | Role-based access with policy checks |
 | Role source | Identity provider group claims synchronized at login |
 | Policy location | Backend authorization policies |
 | Audit requirements | Assignment and close actions generate audit events |
 ## Logging
 | Field | Value |
 | --- | --- |
 | Logging library | Structured backend logging |
 | Log sink | Central log service |
 | Correlation ID | Created at API edge and returned in responses |
 | Sensitive data policy | Do not log customer email bodies or tokens |
 ## Monitoring
 | Signal | Tool | Alert Policy |
 | --- | --- | --- |
 | Availability | Health checks | Alert after 3 failed checks. |
 | Errors | Error tracking | Alert on elevated 5xx rate. |
 | Performance | API metrics | Alert when P95 exceeds 500 ms for 15 minutes. |
 | Business metrics | Queue dashboard | Alert managers when overdue work exceeds threshold. |
 ## Testing
 | Test Type | Tooling | Required When |
 | --- | --- | --- |
 | Unit | Backend and frontend test runners | Domain rules, view logic, formatters. |
 | Integration | API tests with PostgreSQL | Persistence, auth, and queue workflows. |
 | End-to-end | Browser automation | Critical request lifecycle. |
 | Performance | Scripted API checks | Before major queue or reporting changes. |
 | Security | Dependency audit and auth tests | Each release candidate. |
 ## Roadmap
 | Milestone | Target | Outcome |
 | --- | --- | --- |
 | M1 | Q1 | Request intake, assignment, and closure. |
 | M2 | Q2 | Reporting dashboard and overdue alerts. |
 | M3 | Q3 | Customer-visible request status page. |
 ## Open Questions
 | Question | Owner | Needed By | Status |
 | --- | --- | --- | --- |
 | Should notification delivery use email only or chat integration too? | Product | M2 planning | Open |
 | Is audit export required for compliance reviews? | Operations | M1 release | Open |
@@ -0,0 +1,84 @@
 # {{PROJECT_NAME}} Architecture
 ## High-Level Overview
 {{ARCHITECTURE_OVERVIEW}}
 ```mermaid
 flowchart LR
    User["User"]
    Interface["{{INTERFACE_LAYER}}"]
    Application["{{APPLICATION_LAYER}}"]
    Domain["{{DOMAIN_LAYER}}"]
    Infrastructure["{{INFRASTRUCTURE_LAYER}}"]
    User --> Interface
    Interface --> Application
    Application --> Domain
    Application --> Infrastructure
 ```
 ## Architecture Style
 - Style: {{ARCHITECTURE_STYLE}}
 - Reason: {{ARCHITECTURE_REASON}}
 - Key trade-off: {{ARCHITECTURE_TRADE_OFF}}
 ## Folder Structure
 ```text
 {{PROJECT_ROOT}}/
  {{SOURCE_FOLDER}}/
  {{TEST_FOLDER}}/
  docs/
 ```
 ## Module Responsibilities
 | Module | Responsibility | Public Interface |
 | --- | --- | --- |
 | {{MODULE_NAME}} | {{MODULE_RESPONSIBILITY}} | {{PUBLIC_INTERFACE}} |
 ## Dependency Rules
 - {{DEPENDENCY_RULE_1}}
 - {{DEPENDENCY_RULE_2}}
 - {{DEPENDENCY_RULE_3}}
 ## Request Flow
 {{REQUEST_FLOW}}
 ## Data Flow
 {{DATA_FLOW}}
 ## Domain Model
 | Concept | Meaning | Invariants |
 | --- | --- | --- |
 | {{DOMAIN_CONCEPT}} | {{DOMAIN_MEANING}} | {{DOMAIN_INVARIANTS}} |
 ## Integration Points
 | Integration | Direction | Protocol | Failure Policy |
 | --- | --- | --- | --- |
 | {{INTEGRATION}} | {{DIRECTION}} | {{PROTOCOL}} | {{FAILURE_POLICY}} |
 ## Security
 - Authentication: {{AUTHENTICATION_POLICY}}
 - Authorization: {{AUTHORIZATION_POLICY}}
 - Secrets: {{SECRETS_POLICY}}
 - Input validation: {{INPUT_VALIDATION_POLICY}}
 - Audit logging: {{AUDIT_LOGGING_POLICY}}
 ## Error Handling
 {{ERROR_HANDLING_POLICY}}
 ## Performance And Scalability
 - Latency target: {{LATENCY_TARGET}}
 - Throughput target: {{THROUGHPUT_TARGET}}
 - Scaling strategy: {{SCALING_STRATEGY}}
@@ -0,0 +1,61 @@
 # {{PROJECT_NAME}} Conventions
 ## Naming
 - {{NAMING_RULE}}
 ## File Organization
 - {{FILE_ORGANIZATION_RULE}}
 ## Folder Organization
 - {{FOLDER_ORGANIZATION_RULE}}
 ## Dependency Injection
 - {{DEPENDENCY_INJECTION_RULE}}
 ## Logging
 - {{LOGGING_RULE}}
 ## Validation
 - {{VALIDATION_RULE}}
 ## Error Handling
 - {{ERROR_HANDLING_RULE}}
 ## DTO Rules
 - {{DTO_RULE}}
 ## Repository Rules
 - {{REPOSITORY_RULE}}
 ## Service Rules
 - {{SERVICE_RULE}}
 ## Testing
 - Unit tests: {{UNIT_TEST_RULE}}
 - Integration tests: {{INTEGRATION_TEST_RULE}}
 - End-to-end tests: {{E2E_TEST_RULE}}
 ## Git Workflow
 - Branch naming: {{BRANCH_NAMING}}
 - Merge policy: {{MERGE_POLICY}}
 - Commit style: {{COMMIT_STYLE}}
 ## Pull Requests
 - {{PULL_REQUEST_RULE}}
 ## Code Reviews
 - {{CODE_REVIEW_RULE}}
@@ -0,0 +1,48 @@
 # ADR-{{ADR_NUMBER}}: {{DECISION_TITLE}}
 ## Status
 {{STATUS}}
 ## Date
 {{DATE}}
 ## Context
 {{CONTEXT}}
 ## Problem
 {{PROBLEM}}
 ## Alternatives
 | Alternative | Summary |
 | --- | --- |
 | {{ALTERNATIVE_1}} | {{ALTERNATIVE_1_SUMMARY}} |
 | {{ALTERNATIVE_2}} | {{ALTERNATIVE_2_SUMMARY}} |
 | {{ALTERNATIVE_3}} | {{ALTERNATIVE_3_SUMMARY}} |
 ## Pros
 - {{PRO_1}}
 - {{PRO_2}}
 ## Cons
 - {{CON_1}}
 - {{CON_2}}
 ## Decision
 {{DECISION}}
 ## Consequences
 - {{CONSEQUENCE_1}}
 - {{CONSEQUENCE_2}}
 ## Review Triggers
 - {{REVIEW_TRIGGER}}
@@ -0,0 +1,62 @@
 # Feature: {{FEATURE_NAME}}
 ## Objective
 {{FEATURE_OBJECTIVE}}
 ## User Or System Value
 {{USER_OR_SYSTEM_VALUE}}
 ## Requirements
 - {{REQUIREMENT_1}}
 - {{REQUIREMENT_2}}
 ## Non-Goals
 - {{NON_GOAL_1}}
 ## Acceptance Criteria
 - [ ] {{ACCEPTANCE_CRITERION_1}}
 - [ ] {{ACCEPTANCE_CRITERION_2}}
 ## Architecture Notes
 - Affected modules: {{AFFECTED_MODULES}}
 - Dependency concerns: {{DEPENDENCY_CONCERNS}}
 - Data ownership: {{DATA_OWNERSHIP}}
 - Related ADRs: {{RELATED_ADRS}}
 ## API Or Interface Changes
 {{API_OR_INTERFACE_CHANGES}}
 ## Data Changes
 {{DATA_CHANGES}}
 ## Security And Authorization
 {{SECURITY_AND_AUTHORIZATION}}
 ## Testing Plan
 - Unit: {{UNIT_TEST_PLAN}}
 - Integration: {{INTEGRATION_TEST_PLAN}}
 - End-to-end: {{E2E_TEST_PLAN}}
 - Manual: {{MANUAL_TEST_PLAN}}
 ## Rollout Plan
 {{ROLLOUT_PLAN}}
 ## Risks
 - {{RISK_1}}
 - {{RISK_2}}
 ## Open Questions
 - {{OPEN_QUESTION}}
@@ -0,0 +1,90 @@
 # {{PROJECT_NAME}}
 ## Vision
 {{PROJECT_VISION}}
 ## Goals
 - {{GOAL_1}}
 - {{GOAL_2}}
 - {{GOAL_3}}
 ## Non-Goals
 - {{NON_GOAL_1}}
 - {{NON_GOAL_2}}
 ## Functional Requirements
 | ID | Requirement | Priority |
 | --- | --- | --- |
 | FR-001 | {{FUNCTIONAL_REQUIREMENT}} | Must |
 ## Non-Functional Requirements
 | Category | Requirement |
 | --- | --- |
 | Performance | {{PERFORMANCE_REQUIREMENT}} |
 | Security | {{SECURITY_REQUIREMENT}} |
 | Availability | {{AVAILABILITY_REQUIREMENT}} |
 | Maintainability | {{MAINTAINABILITY_REQUIREMENT}} |
 ## Tech Stack
 | Area | Choice |
 | --- | --- |
 | Language | {{LANGUAGE}} |
 | Framework | {{FRAMEWORK}} |
 | Database | {{DATABASE}} |
 | Deployment | {{DEPLOYMENT}} |
 ## Runtime
 | Environment | URL or Entry Point | Notes |
 | --- | --- | --- |
 | Local | {{LOCAL_URL}} | {{LOCAL_NOTES}} |
 | Staging | {{STAGING_URL}} | {{STAGING_NOTES}} |
 | Production | {{PRODUCTION_URL}} | {{PRODUCTION_NOTES}} |
 ## Infrastructure
 - Hosting: {{HOSTING}}
 - Storage: {{STORAGE}}
 - Network: {{NETWORK}}
 - Secrets: {{SECRETS}}
 ## Authentication And Authorization
 - Authentication: {{AUTHENTICATION}}
 - Authorization: {{AUTHORIZATION}}
 - Roles or policies: {{ROLES_OR_POLICIES}}
 ## Logging And Monitoring
 - Logging: {{LOGGING}}
 - Monitoring: {{MONITORING}}
 - Alerting: {{ALERTING}}
 ## Testing
 - Unit tests: {{UNIT_TESTS}}
 - Integration tests: {{INTEGRATION_TESTS}}
 - End-to-end tests: {{E2E_TESTS}}
 - Manual checks: {{MANUAL_CHECKS}}
 ## CI/CD
 - CI: {{CI}}
 - CD: {{CD}}
 - Required checks: {{REQUIRED_CHECKS}}
 ## Roadmap
 | Milestone | Outcome |
 | --- | --- |
 | {{MILESTONE}} | {{OUTCOME}} |
 ## Open Questions
 - {{OPEN_QUESTION}}