docs: initialize engineering starter kit

README.md

@@ -0,0 +1,117 @@
+# Engineering Starter Kit
+
+This repository is a reusable engineering foundation for new software projects.
+It is intentionally language, framework, architecture, and deployment agnostic.
+
+Use it to bootstrap consistent project documentation, architecture records,
+coding conventions, release practices, and AI-agent working agreements.
+
+## What This Kit Provides
+
+- A universal AI-agent engineering contract in [AGENTS.md](AGENTS.md).
+- Project documentation guides in [docs/](docs/).
+- Copy-ready project templates in [templates/](templates/).
+- Completed examples in [examples/](examples/).
+- A language-agnostic [.gitignore](.gitignore) suitable for most starter repos.
+
+## Documentation System
+
+Each document has one primary responsibility. Avoid duplicating the same policy
+or decision in multiple files; link to the source of truth instead.
+
+```mermaid
+flowchart TD
+    README["README.md<br/>How to use the kit"]
+    AGENTS["AGENTS.md<br/>AI-agent working contract"]
+    Project["docs/PROJECT.md<br/>Project intent and runtime facts"]
+    Architecture["docs/ARCHITECTURE.md<br/>System structure and rules"]
+    Conventions["docs/CONVENTIONS.md<br/>Engineering standards"]
+    Decisions["docs/DECISIONS.md<br/>Architecture Decision Records"]
+    Prompts["docs/PROMPTS.md<br/>Reusable engineering prompts"]
+    Checklists["docs/CHECKLISTS.md<br/>Execution quality gates"]
+    Workflow["docs/workflow.md<br/>Day-to-day delivery flow"]
+    Branching["docs/branching.md<br/>Git branch strategy"]
+    Release["docs/release-process.md<br/>Release governance"]
+    Setup["docs/repository-setup.md<br/>Bootstrap instructions"]
+    Templates["templates/<br/>Reusable placeholders"]
+    Examples["examples/<br/>Completed reference project"]
+
+    README --> AGENTS
+    README --> Project
+    README --> Architecture
+    README --> Conventions
+    README --> Decisions
+    README --> Prompts
+    README --> Checklists
+    README --> Workflow
+    Workflow --> Branching
+    Workflow --> Release
+    Setup --> Templates
+    Templates --> Examples
+    Project --> Architecture
+    Architecture --> Decisions
+    Conventions --> Checklists
+```
+
+## Document Responsibilities
+
+| File | Responsibility |
+| --- | --- |
+| [AGENTS.md](AGENTS.md) | Defines how AI coding agents should explore, plan, implement, validate, and communicate. |
+| [docs/PROJECT.md](docs/PROJECT.md) | Captures project-specific facts: vision, requirements, stack, infrastructure, operations, and roadmap. |
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Describes the system shape, dependency rules, flows, security posture, and scalability model. |
+| [docs/CONVENTIONS.md](docs/CONVENTIONS.md) | Documents coding, testing, review, naming, organization, and collaboration standards. |
+| [docs/DECISIONS.md](docs/DECISIONS.md) | Stores Architecture Decision Records and their consequences. |
+| [docs/PROMPTS.md](docs/PROMPTS.md) | Provides reusable prompts for engineering work with humans and AI agents. |
+| [docs/CHECKLISTS.md](docs/CHECKLISTS.md) | Provides concise quality gates for common engineering tasks. |
+| [docs/workflow.md](docs/workflow.md) | Defines the end-to-end development workflow. |
+| [docs/branching.md](docs/branching.md) | Defines branch naming, merge policy, and release branch expectations. |
+| [docs/release-process.md](docs/release-process.md) | Defines release readiness, deployment, rollback, and post-release review. |
+| [docs/repository-setup.md](docs/repository-setup.md) | Explains how to turn this kit into a new project repository. |
+
+## Recommended Bootstrap Workflow
+
+1. Copy this repository or use it as a template for a new project.
+2. Fill [templates/PROJECT.template.md](templates/PROJECT.template.md) and save it as `docs/PROJECT.md`.
+3. Fill [templates/ARCHITECTURE.template.md](templates/ARCHITECTURE.template.md) and save it as `docs/ARCHITECTURE.md`.
+4. Fill [templates/CONVENTIONS.template.md](templates/CONVENTIONS.template.md) and save it as `docs/CONVENTIONS.md`.
+5. Record material technical decisions with [templates/DECISIONS.template.md](templates/DECISIONS.template.md).
+6. Use [templates/FEATURE.template.md](templates/FEATURE.template.md) for non-trivial feature work.
+7. Keep [AGENTS.md](AGENTS.md) close to the root so AI tools can discover it automatically.
+8. Review [docs/CHECKLISTS.md](docs/CHECKLISTS.md) before opening pull requests or releasing.
+
+## How AI Coding Agents Should Use This Repository
+
+AI agents should read [AGENTS.md](AGENTS.md) first, then inspect the relevant
+project documents before modifying code or documentation. For new projects, the
+minimum context set is:
+
+- [docs/PROJECT.md](docs/PROJECT.md)
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- [docs/CONVENTIONS.md](docs/CONVENTIONS.md)
+- [docs/DECISIONS.md](docs/DECISIONS.md)
+- [docs/CHECKLISTS.md](docs/CHECKLISTS.md)
+
+Agents should treat missing project facts as unknown, not as permission to
+invent business logic or architecture.
+
+## Maintaining The Kit
+
+- Keep the kit generic unless a rule is broadly useful across many project types.
+- Prefer links over duplicated guidance.
+- Keep examples realistic but fictional.
+- Add new templates only when they solve repeated project setup or delivery work.
+- Update checklists when real incidents reveal missing quality gates.
+- Record significant changes to the kit itself as decisions in
+  [docs/DECISIONS.md](docs/DECISIONS.md).
+
+## Definition Of Ready For A New Project
+
+A project bootstrapped from this kit is ready for implementation when:
+
+- The project vision and constraints are documented.
+- The initial architecture style is selected or explicitly deferred.
+- Key conventions are documented.
+- The first delivery workflow is understood.
+- Required environments and secrets are identified.
+- Validation expectations are clear enough to prevent guesswork.