docs: initialize engineering starter kit

2026-06-28 09:40:40 +02:00
commit ed8efda692
23 changed files with 3131 additions and 0 deletions
@@ -0,0 +1,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.