docs: initialize engineering starter kit

.gitignore

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

AGENTS.md

@@ -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.

README.md

@@ -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.

docs/ARCHITECTURE.md

@@ -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.

docs/CHECKLISTS.md

@@ -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.

docs/CONVENTIONS.md

@@ -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.

docs/DECISIONS.md

@@ -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.

docs/PROJECT.md

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

docs/PROMPTS.md

@@ -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.
+```

docs/branching.md

@@ -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.

docs/release-process.md

@@ -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.

docs/repository-setup.md

@@ -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.

docs/workflow.md

@@ -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.

examples/ARCHITECTURE.example.md

@@ -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. |

examples/CONVENTIONS.example.md

@@ -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.

examples/DECISIONS.example.md

@@ -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.

examples/FEATURE.example.md

@@ -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?

examples/PROJECT.example.md

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

templates/ARCHITECTURE.template.md

@@ -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}}

templates/CONVENTIONS.template.md

@@ -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}}

templates/DECISIONS.template.md

@@ -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}}

templates/FEATURE.template.md

@@ -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}}

templates/PROJECT.template.md

@@ -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}}