template/docs/repository-setup.md

Repository Setup

This document explains how to use the Engineering Starter Kit for a new project.

For the recommended documentation flow, see ../README.md. For the AI-agent contract, see ../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	Vision, requirements, stack, environments, operations, and roadmap.
ARCHITECTURE.md	Architecture style, folder structure, module boundaries, and flows.
CONVENTIONS.md	Language, framework, testing, review, and repository-specific rules.
DECISIONS.md	Accepted project decisions. Remove examples when real ADRs exist.
workflow.md	Delivery steps, required checks, and review expectations.
branching.md	Branch naming and merge policy.
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.
• Do not leave placeholders in public-facing documentation.

AI Agent Setup

For AI-assisted projects:

1. Keep ../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.