template/README.md

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