Skip to content

README.md

Latest commit

 

History

History
347 lines (251 loc) · 8.03 KB

README.md

File metadata and controls

347 lines (251 loc) · 8.03 KB
Raw

Project Templates

This directory contains reusable templates for bootstrapping new projects and creating standardized documentation.

Directory Structure

templates/
├── README.md                       # This file
├── new-project/                    # Complete new project structure
│   ├── docs/                       # Documentation templates
│   ├── .gitignore.template
│   ├── README.template.md
│   └── CONTEXT.template.md
├── docs-structure/                 # Documentation file templates
│   ├── product-manager-output.template.md
│   ├── architecture-output.template.md
│   ├── style-guide.template.md
│   └── feature-spec.template.md
├── best-practices/                 # Framework-specific coding guidelines
│   └── coding-guidelines.md        # React Native, NestJS, TypeScript
└── common-files/                   # Reusable configuration files
    ├── .editorconfig
    ├── .gitattributes
    └── framework-config.yaml

How to Use Templates

For New Projects

Templates in new-project/ are automatically used by the initialization script:

# The init script copies these templates
.ai-framework/scripts/init-new-project.sh

For Documentation

Templates in docs-structure/ can be copied manually:

# Copy a template
cp .ai-framework/templates/docs-structure/feature-spec.template.md \
   docs/features/my-feature/spec.md

# Edit the template
# Fill in all [PLACEHOLDER] sections

For Configuration

Templates in common-files/ provide best practices:

# Copy configuration templates
cp .ai-framework/templates/common-files/.editorconfig .

Template Variables

Templates use the following placeholder format:

  • [PROJECT_NAME] - Name of the project
  • [PROJECT_DESC] - Project description
  • [DATE] - Current date
  • [VERSION] - Version number
  • [AUTHOR] - Author name
  • [TECH_STACK_*] - Technology stack details

Example

# [PROJECT_NAME]

Created: [DATE]
Version: [VERSION]

## Description
[PROJECT_DESC]

Becomes:

# Recipe Generator App

Created: 2025-10-14
Version: 0.1.0

## Description
AI-powered app that generates restaurant-quality recipes from photos

Creating Custom Templates

To create a custom template:

  1. Create the template file with .template extension
  2. Add placeholder variables using [VARIABLE_NAME] format
  3. Document required variables in header comment
  4. Add to appropriate directory (new-project, docs-structure, or common-files)
  5. Update this README with usage instructions

Template File Format

<!--
Template: [Template Name]
Description: [What this template is for]
Variables:
  - [VAR1]: Description of variable 1
  - [VAR2]: Description of variable 2
Usage: [How to use this template]
-->

# [TITLE]

[Content with placeholders...]

Available Templates

New Project Templates

new-project/docs/

Complete documentation structure for new projects:

  • project-documentation/
  • design-documentation/
  • features/

Variables: PROJECT_NAME, PROJECT_DESC, DATE

Usage: Automatically used by init-new-project.sh

Documentation Templates

product-manager-output.template.md

Template for product manager specifications

Variables: PROJECT_NAME, PROJECT_DESC, DATE, AUTHOR

Usage:

cp .ai-framework/templates/docs-structure/product-manager-output.template.md \
   docs/project-documentation/product-manager-output.md

architecture-output.template.md

Template for system architecture documentation

Variables: PROJECT_NAME, TECH_STACK_FRONTEND, TECH_STACK_BACKEND, DATE

Usage:

cp .ai-framework/templates/docs-structure/architecture-output.template.md \
   docs/project-documentation/architecture-output.md

style-guide.template.md

Template for design system style guide

Variables: PROJECT_NAME, PRIMARY_COLOR, SECONDARY_COLOR, FONT_PRIMARY

Usage:

cp .ai-framework/templates/docs-structure/style-guide.template.md \
   docs/design-documentation/design-system/style-guide.md

feature-spec.template.md

Template for individual feature specifications

Variables: FEATURE_NAME, FEATURE_DESC, PRIORITY, DATE

Usage:

FEATURE="user-authentication"
cp .ai-framework/templates/docs-structure/feature-spec.template.md \
   docs/features/$FEATURE/spec.md

Best Practices Documentation

coding-guidelines.md

Comprehensive coding standards and best practices for common tech stacks

Includes:

  • React Native & Expo guidelines (code style, performance, navigation, testing)
  • NestJS backend patterns (modular architecture, API design, security)
  • General TypeScript standards (naming, error handling, testing)
  • Project-specific guidelines (Docker, environment variables, Git workflow)

Tech Stacks Covered:

  • Frontend: React Native, Expo, TypeScript
  • Backend: NestJS, Express, TypeScript
  • Testing: Jest, React Native Testing Library, Detox
  • State Management: Context, Zustand, Redux Toolkit
  • Database: TypeORM, MikroORM

Variables: None (reference document)

Usage:

# Reference during implementation
# Implementation agents should follow these guidelines
cat templates/best-practices/coding-guidelines.md

When to Reference:

  • Before starting implementation (Phase 2)
  • During code reviews
  • When setting up new features
  • For onboarding new team members

Customization: Copy to your project and modify for team-specific conventions:

cp templates/best-practices/coding-guidelines.md \
   docs/development/coding-standards.md
# Edit to add project-specific rules

Common Configuration Templates

.editorconfig

Standardized editor configuration for consistent code style

Variables: None

Usage:

cp .ai-framework/templates/common-files/.editorconfig .

.gitattributes

Git attributes for handling different file types

Variables: None

Usage:

cp .ai-framework/templates/common-files/.gitattributes .

framework-config.yaml

AI Framework configuration template

Variables: PROJECT_NAME, TECH_STACK_, PATHS_

Usage: Automatically generated by scripts

Template Best Practices

1. Use Clear Placeholders

Good: [PROJECT_NAME]
Bad: <project>, {{project}}, $PROJECT

2. Provide Context

<!-- Replace [AUTHOR_NAME] with the name of the primary developer -->
Author: [AUTHOR_NAME]

3. Include Examples

<!-- Example: "React Native with Expo" -->
Frontend: [TECH_STACK_FRONTEND]

4. Document Required vs Optional

<!-- REQUIRED -->
Project Name: [PROJECT_NAME]

<!-- OPTIONAL - defaults to current date if not provided -->
Created: [DATE]

5. Use Consistent Formatting

  • Placeholders: [UPPERCASE_WITH_UNDERSCORES]
  • Comments: <!-- HTML-style comments for markdown -->
  • Sections: Use markdown headers consistently

Customization

Project-Specific Templates

You can override framework templates by creating a .templates/ directory in your project:

my-project/
├── .templates/                     # Project-specific overrides
│   └── feature-spec.template.md    # Overrides framework template
└── .ai-framework/                  # Framework (don't modify)
    └── templates/

Scripts will check .templates/ first, then fall back to framework templates.

Adding Variables

To add new template variables:

  1. Update script that processes templates (e.g., init-new-project.sh)
  2. Add variable to template file
  3. Document in template header comment
  4. Update this README

Example:

# In script:
sed "s/\[NEW_VAR\]/$NEW_VAR_VALUE/g" template.md > output.md

# In template:
<!--
Variables:
  - [NEW_VAR]: Description of what this is
-->

Contributing Templates

To contribute a new template:

  1. Create template file with clear placeholders
  2. Add comprehensive header documentation
  3. Test with actual project
  4. Document in this README
  5. Submit PR with example usage

Need Help? See the main framework documentation in .ai-framework/README.md