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.
Project documentation guides in docs/.
Copy-ready project templates in templates/.
Completed examples in examples/.
A language-agnostic .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.

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	Defines how AI coding agents should explore, plan, implement, validate, and communicate.
docs/PROJECT.md	Captures project-specific facts: vision, requirements, stack, infrastructure, operations, and roadmap.
docs/ARCHITECTURE.md	Describes the system shape, dependency rules, flows, security posture, and scalability model.
docs/CONVENTIONS.md	Documents coding, testing, review, naming, organization, and collaboration standards.
docs/DECISIONS.md	Stores Architecture Decision Records and their consequences.
docs/PROMPTS.md	Provides reusable prompts for engineering work with humans and AI agents.
docs/CHECKLISTS.md	Provides concise quality gates for common engineering tasks.
docs/workflow.md	Defines the end-to-end development workflow.
docs/branching.md	Defines branch naming, merge policy, and release branch expectations.
docs/release-process.md	Defines release readiness, deployment, rollback, and post-release review.
docs/repository-setup.md	Explains how to turn this kit into a new project repository.

Recommended Bootstrap Workflow

Copy this repository or use it as a template for a new project.
Fill templates/PROJECT.template.md and save it as docs/PROJECT.md.
Fill templates/ARCHITECTURE.template.md and save it as docs/ARCHITECTURE.md.
Fill templates/CONVENTIONS.template.md and save it as docs/CONVENTIONS.md.
Record material technical decisions with templates/DECISIONS.template.md.
Use templates/FEATURE.template.md for non-trivial feature work.
Keep AGENTS.md close to the root so AI tools can discover it automatically.
Review docs/CHECKLISTS.md before opening pull requests or releasing.

How AI Coding Agents Should Use This Repository

AI agents should read AGENTS.md first, then inspect the relevant project documents before modifying code or documentation. For new projects, the minimum context set is:

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.

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.

5.7 KiB Raw Blame History