Repository Templates

Available Templates

How to Use Templates

1. Starting a New Repository

When creating a new repository:

# Clone the template you need
cp templates/README.md.tpl my-new-repo/README.md
cp templates/AGENTS.md.tpl my-new-repo/AGENTS.md
cp templates/Taskfile.yaml.tpl my-new-repo/Taskfile.yaml

# Edit each file to customize for your repository
# Replace all {{PLACEHOLDERS}} with actual values

2. Search and Replace Placeholders

All templates use {{PLACEHOLDER}} syntax for values you need to customize:

# Quick search-and-replace
sed -i 's/{{REPO_NAME}}/my-service/g' README.md
sed -i 's/{{REPO_DESCRIPTION}}/User authentication service/g' README.md

3. Validate Your Repository

After creating files from templates:

# Ensure required files exist
ls -1 README.md AGENTS.md Taskfile.yaml .editorconfig CODEOWNERS

# Test Taskfile
task --list

# Validate structure
task validate:structure  # if you've added this task

Template Contents

README.md.tpl

Purpose: Human-oriented documentation explaining what the repository is and why it exists.

Placeholders:

• {{REPO_NAME}} — Repository name
• {{REPO_DESCRIPTION}} — One-sentence description
• {{REPO_PURPOSE}} — Why this repository exists
• {{KEY_FEATURES}} — Main capabilities or features
• {{ARCHITECTURE_SUMMARY}} — High-level system design
• {{RELATED_REPOS}} — Links to related repositories

Customize:

• Remove sections that don't apply
• Add domain-specific sections
• Link to relevant documentation

AGENTS.md.tpl

Purpose: AI agent contract defining how agents should operate in this repository.

Placeholders:

• {{REPO_NAME}} — Repository name
• {{REPO_PURPOSE}} — What this repository does
• {{PRIMARY_LANGUAGE}} — Main programming language
• {{MAIN_TECHNOLOGIES}} — Key frameworks and tools
• {{PATTERN_REFERENCES}} — Links to relevant patterns
• {{CONSTRAINTS}} — Non-negotiable requirements
• {{ESCALATION_RULES}} — When to ask for human help

Customize:

• Add repository-specific patterns
• Define local conventions
• Document critical constraints
• Specify escalation rules

Taskfile.yaml.tpl

Purpose: Operational interface for all repository operations.

Placeholders:

• {{REPO_NAME}} — Repository name
• {{PROJECT_DIR}} — Project directory variable
• {{DEV_COMMANDS}} — Development-specific commands
• {{TEST_COMMANDS}} — Test-specific commands
• {{SANDBOX_SETUP}} — Sandbox initialization steps

Customize:

• Add language-specific tasks
• Define repository-specific operations
• Configure task dependencies
• Add validation checks

CLAUDE.md.tpl (Optional)

Purpose: Claude Code-specific context and instructions.

Use this when:

• You have Claude Code-specific workflows
• You need to provide additional context for Claude
• You want to define Claude-specific patterns or preferences

Placeholders:

• {{REPO_CONTEXT}} — Repository-specific context
• {{CLAUDE_PATTERNS}} — Preferred patterns for Claude
• {{CLAUDE_CONSTRAINTS}} — Claude-specific limitations

cursorrules.tpl (Optional)

Purpose: Cursor-specific rules and patterns.

Use this when:

• Your team uses Cursor as an IDE
• You have Cursor-specific coding patterns
• You want to define Cursor behavior rules

Placeholders:

• {{CODING_STYLE}} — Preferred coding style
• {{PATTERNS}} — Cursor-specific patterns
• {{CONSTRAINTS}} — Cursor-specific limitations

Placeholder Reference

Common placeholders across templates:

Agent-Specific Templates

When to Use CLAUDE.md

Use CLAUDE.md when:

• Your repository has complex Claude Code workflows
• You need to provide extensive context beyond AGENTS.md
• You have Claude-specific patterns or preferences
• You want to separate agent-agnostic (AGENTS.md) from Claude-specific instructions

Do NOT use CLAUDE.md when:

• All instructions fit in AGENTS.md
• You don't have Claude-specific requirements

When to Use .cursorrules

Use .cursorrules when:

• Your team uses Cursor as their primary IDE
• You have Cursor-specific coding patterns
• You want Cursor to follow specific rules

Do NOT use .cursorrules when:

• Your team doesn't use Cursor
• All rules fit in AGENTS.md

Template Maintenance

Keeping Templates Updated

Templates are maintained in this repository and should be updated when:

• Engineering principles change
• New best practices emerge
• Common patterns evolve
• Feedback suggests improvements

Proposing Template Changes

To propose changes to templates:

1. Open a pull request with your proposed changes
2. Explain the rationale in the PR description
3. Update this README if usage changes
4. Consider backward compatibility with existing repositories

Examples

Minimal Python Service

# Create new repository structure
mkdir my-python-service && cd my-python-service

# Copy templates
cp ../engineering-handbook/templates/README.md.tpl README.md
cp ../engineering-handbook/templates/AGENTS.md.tpl AGENTS.md
cp ../engineering-handbook/templates/Taskfile.yaml.tpl Taskfile.yaml

# Customize
sed -i 's/{{REPO_NAME}}/my-python-service/g' *.md Taskfile.yaml
sed -i 's/{{PRIMARY_LANGUAGE}}/Python/g' AGENTS.md
sed -i 's/{{MAIN_TECHNOLOGIES}}/FastAPI, PostgreSQL/g' AGENTS.md

# Add additional required files
cat > .editorconfig << 'EOF'
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

[*.py]
indent_style = space
indent_size = 4
EOF

cat > CODEOWNERS << 'EOF'
* @ontopix/engineering
EOF

# Initialize git
git init
git add .
git commit -m "Initial repository structure"

Monorepo with Multiple Services

For monorepos, use templates at the top level and reference them in sub-projects:

my-monorepo/
├─ README.md              # From template
├─ AGENTS.md              # From template (top-level coordination)
├─ Taskfile.yaml          # From template (orchestration)
├─ .editorconfig
├─ CODEOWNERS
└─ apps/
   ├─ frontend/
   │  ├─ README.md        # Service-specific
   │  ├─ AGENTS.md        # References top-level AGENTS.md
   │  └─ Taskfile.yaml    # Service-specific tasks
   └─ backend/
      ├─ README.md
      ├─ AGENTS.md
      └─ Taskfile.yaml

Related Documentation

• Repository Structure Pattern
• AI Agent Entrypoint Pattern
• Taskfile Contract Pattern
• Infrastructure Layout Pattern
• Core Engineering Principles

Questions?

If you're unsure which template to use or how to customize it:

• Check the principles documentation
• Review existing Ontopix repositories
• Ask in the engineering team channel