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