A structured, document-first template system designed to kickstart human-AI collaboration (cowork) in software projects.
AI agents excel when provided with clear context boundaries, strict conventions, and explicit expectations. This repository provides a boilerplate directory structure and markdown templates to align human developers and AI coding agents from day one.
These templates are organized to guide both you and your AI agents through the entire software development lifecycle:
| Phase | Path | Description |
|---|---|---|
| Root Entry | AGENTS.md | The single source of truth for the agent regarding project status, active phases, and non-negotiables. |
| Design | docs/design/PRD.md | Product Requirements Document mapping out the "why" and "what". |
| docs/design/DECISIONS.md | Architecture Decision Records (ADR) detailing design trade-offs. | |
| docs/design/GLOSSARY.md | Definition of domain-specific terminology to align LLM vocabulary. | |
| Planning | docs/planning/ROADMAP.md | High-level milestones and phase breakdowns. |
| docs/planning/BACKLOG.md | Prioritized feature lists, tasks, and bugs. | |
| docs/planning/RISKS.md | Identified technical debt, constraints, and assumptions. | |
| Building | docs/building/CONVENTIONS.md | Coding style, architectural rules, and project patterns. |
| docs/building/DEV_SETUP.md | Local developer environment requirements, env vars, database seeding, and mocks. | |
| docs/building/API_CONTRACTS.md | Defined interfaces, payload shapes, and endpoint contracts. | |
| docs/building/SECURITY.md | Threat models, sensitive data handling, and compliance rules. | |
| Testing | docs/testing/STRATEGY.md | How the application should be tested (unit, integration, E2E). |
| docs/testing/ACCEPTANCE_CRITERIA.md | Specific criteria for verifying features are complete. | |
| Documentation | docs/documentation/README_TEMPLATE.md | Template for your project's main user-facing README. |
| docs/documentation/ARCHITECTURE.md | High-level design, data flow, and component relationships. | |
| docs/documentation/RUNBOOK.md | Operational guidelines, deployment steps, and troubleshooting. | |
| docs/documentation/CHANGELOG.md | Historic record of modifications and releases. |
-
Bootstrap Your Project Copy the
docs/folder and AGENTS.md into the root of your new project repository. -
Initialize Alignment Fill out AGENTS.md to define your project name, the current development phase, and any absolute non-negotiables (e.g., target frameworks, performance requirements).
-
Configure Your Agent's System Instructions Instruct your AI agent to read AGENTS.md at the start of every session to establish context. If you are using Antigravity, add it as a system rule.
- Document-First Workflow: Before asking an agent to write code, write or update the corresponding specification (e.g., docs/design/PRD.md or docs/building/API_CONTRACTS.md). Use these specifications as the contract for the agent's work.
- Keep Documents Current: As requirements change, update the templates first. AI agents will read these documents as their source of truth.
- Use AGENTS.md as a Compass: Keep the
Current phasefield in AGENTS.md updated so the agent knows whether it should focus on brainstorming designs, refining plans, writing production code, or drafting tests.