From ed8efda6920b17d0c3eaf9da6025fadbb32d4c1f Mon Sep 17 00:00:00 2001 From: AzuTear Date: Sun, 28 Jun 2026 09:40:40 +0200 Subject: [PATCH] docs: initialize engineering starter kit --- .gitignore | 120 +++++++++++ AGENTS.md | 203 +++++++++++++++++++ README.md | 117 +++++++++++ docs/ARCHITECTURE.md | 193 ++++++++++++++++++ docs/CHECKLISTS.md | 107 ++++++++++ docs/CONVENTIONS.md | 210 +++++++++++++++++++ docs/DECISIONS.md | 247 +++++++++++++++++++++++ docs/PROJECT.md | 185 +++++++++++++++++ docs/PROMPTS.md | 310 +++++++++++++++++++++++++++++ docs/branching.md | 111 +++++++++++ docs/release-process.md | 98 +++++++++ docs/repository-setup.md | 104 ++++++++++ docs/workflow.md | 120 +++++++++++ examples/ARCHITECTURE.example.md | 158 +++++++++++++++ examples/CONVENTIONS.example.md | 93 +++++++++ examples/DECISIONS.example.md | 150 ++++++++++++++ examples/FEATURE.example.md | 93 +++++++++ examples/PROJECT.example.md | 167 ++++++++++++++++ templates/ARCHITECTURE.template.md | 84 ++++++++ templates/CONVENTIONS.template.md | 61 ++++++ templates/DECISIONS.template.md | 48 +++++ templates/FEATURE.template.md | 62 ++++++ templates/PROJECT.template.md | 90 +++++++++ 23 files changed, 3131 insertions(+) create mode 100644 .gitignore create mode 100644 AGENTS.md create mode 100644 README.md create mode 100644 docs/ARCHITECTURE.md create mode 100644 docs/CHECKLISTS.md create mode 100644 docs/CONVENTIONS.md create mode 100644 docs/DECISIONS.md create mode 100644 docs/PROJECT.md create mode 100644 docs/PROMPTS.md create mode 100644 docs/branching.md create mode 100644 docs/release-process.md create mode 100644 docs/repository-setup.md create mode 100644 docs/workflow.md create mode 100644 examples/ARCHITECTURE.example.md create mode 100644 examples/CONVENTIONS.example.md create mode 100644 examples/DECISIONS.example.md create mode 100644 examples/FEATURE.example.md create mode 100644 examples/PROJECT.example.md create mode 100644 templates/ARCHITECTURE.template.md create mode 100644 templates/CONVENTIONS.template.md create mode 100644 templates/DECISIONS.template.md create mode 100644 templates/FEATURE.template.md create mode 100644 templates/PROJECT.template.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..0c0b002 --- /dev/null +++ b/.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 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..eee3c9e --- /dev/null +++ b/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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..95fe2eb --- /dev/null +++ b/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
How to use the kit"] + AGENTS["AGENTS.md
AI-agent working contract"] + Project["docs/PROJECT.md
Project intent and runtime facts"] + Architecture["docs/ARCHITECTURE.md
System structure and rules"] + Conventions["docs/CONVENTIONS.md
Engineering standards"] + Decisions["docs/DECISIONS.md
Architecture Decision Records"] + Prompts["docs/PROMPTS.md
Reusable engineering prompts"] + Checklists["docs/CHECKLISTS.md
Execution quality gates"] + Workflow["docs/workflow.md
Day-to-day delivery flow"] + Branching["docs/branching.md
Git branch strategy"] + Release["docs/release-process.md
Release governance"] + Setup["docs/repository-setup.md
Bootstrap instructions"] + Templates["templates/
Reusable placeholders"] + Examples["examples/
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. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..d8f385c --- /dev/null +++ b/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
API, UI, CLI, Worker"] + Application["Application Layer
Use cases and orchestration"] + Domain["Domain Layer
Rules and invariants"] + Infrastructure["Infrastructure Layer
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. diff --git a/docs/CHECKLISTS.md b/docs/CHECKLISTS.md new file mode 100644 index 0000000..ea82483 --- /dev/null +++ b/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. diff --git a/docs/CONVENTIONS.md b/docs/CONVENTIONS.md new file mode 100644 index 0000000..2d605eb --- /dev/null +++ b/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. diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md new file mode 100644 index 0000000..25e6d64 --- /dev/null +++ b/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. diff --git a/docs/PROJECT.md b/docs/PROJECT.md new file mode 100644 index 0000000..6fd6229 --- /dev/null +++ b/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 | diff --git a/docs/PROMPTS.md b/docs/PROMPTS.md new file mode 100644 index 0000000..1ae84c9 --- /dev/null +++ b/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. +``` diff --git a/docs/branching.md b/docs/branching.md new file mode 100644 index 0000000..3bc675b --- /dev/null +++ b/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. diff --git a/docs/release-process.md b/docs/release-process.md new file mode 100644 index 0000000..1db8b1d --- /dev/null +++ b/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. diff --git a/docs/repository-setup.md b/docs/repository-setup.md new file mode 100644 index 0000000..8499b87 --- /dev/null +++ b/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. diff --git a/docs/workflow.md b/docs/workflow.md new file mode 100644 index 0000000..825d24a --- /dev/null +++ b/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. diff --git a/examples/ARCHITECTURE.example.md b/examples/ARCHITECTURE.example.md new file mode 100644 index 0000000..712ac9a --- /dev/null +++ b/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. | diff --git a/examples/CONVENTIONS.example.md b/examples/CONVENTIONS.example.md new file mode 100644 index 0000000..52114da --- /dev/null +++ b/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. diff --git a/examples/DECISIONS.example.md b/examples/DECISIONS.example.md new file mode 100644 index 0000000..f82ab97 --- /dev/null +++ b/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. diff --git a/examples/FEATURE.example.md b/examples/FEATURE.example.md new file mode 100644 index 0000000..9d33766 --- /dev/null +++ b/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? diff --git a/examples/PROJECT.example.md b/examples/PROJECT.example.md new file mode 100644 index 0000000..312c032 --- /dev/null +++ b/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 | diff --git a/templates/ARCHITECTURE.template.md b/templates/ARCHITECTURE.template.md new file mode 100644 index 0000000..f450de4 --- /dev/null +++ b/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}} diff --git a/templates/CONVENTIONS.template.md b/templates/CONVENTIONS.template.md new file mode 100644 index 0000000..85b6951 --- /dev/null +++ b/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}} diff --git a/templates/DECISIONS.template.md b/templates/DECISIONS.template.md new file mode 100644 index 0000000..a6c2181 --- /dev/null +++ b/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}} diff --git a/templates/FEATURE.template.md b/templates/FEATURE.template.md new file mode 100644 index 0000000..0af5196 --- /dev/null +++ b/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}} diff --git a/templates/PROJECT.template.md b/templates/PROJECT.template.md new file mode 100644 index 0000000..cbd4d76 --- /dev/null +++ b/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}}