Templates Reference Guide

This comprehensive reference covers all templates available in the AI Track Down framework, their structure, usage patterns, and customization options.

📋 Template Overview

AI Track Down provides a complete set of markdown templates designed for AI-native project management:

Template	Purpose	Usage	AI-Optimized
Epic Template	High-level business initiatives	Strategic planning	✅
Issue Template	Specific features/problems	Development work	✅
Task Template	Granular implementation steps	Daily development	✅
AI-TRACKDOWN Template	Project dashboard	Status overview	✅
llms.txt Templates	AI context files	Agent integration	✅
Config Templates	Project configuration	Setup and integration	✅

---

🎯 Epic Template

Overview

Epics represent major business initiatives or large features that span multiple sprints and involve multiple team members.

Template Structure

---
id: EPIC-000
type: epic
title: [Epic Title]
status: planning
owner: @teamlead
created: YYYY-MM-DDTHH:mm:ssZ
updated: YYYY-MM-DDTHH:mm:ssZ
target_date: YYYY-MM-DDTHH:mm:ssZ
labels: []
token_budget: 50000
token_usage:
  total: 0
  remaining: 50000
  by_agent: {}
sync:
  github: null
  jira: null
  linear: null
---

Key Sections

Executive Summary

## Executive Summary
High-level overview of what this epic accomplishes for the business.
Focus on value proposition and strategic importance.

Success Metrics

## Success Metrics
Quantifiable measures of epic success:
- User conversion rate: +15%
- Page load time: <200ms
- Customer satisfaction: >4.5/5
- Technical debt reduction: 25%

Token Budget Tracking

## Token Tracking
AI token usage tracking for cost management:

| Date | Agent | Issue/Task | Tokens | Purpose |
|------|-------|------------|--------|----------|
| 2025-07-07 | Claude | Planning | 2,847 | Requirements analysis |
| 2025-07-08 | GPT-4 | Architecture | 1,523 | Technical design |

### Token Budget Status
- Budget: 50,000 tokens ($150 estimated)
- Used: 4,370 tokens (8.7%)
- Remaining: 45,630 tokens
- Alert threshold: 40,000 tokens (80%)

Usage Example

# Copy epic template
cp templates/epic-template.md tasks/epics/EPIC-001-user-authentication-system.md

# Customize for your epic
vim tasks/epics/EPIC-001-user-authentication-system.md

AI Context Optimization

<!-- AI_CONTEXT_START -->
**Epic Scope**: Complete user authentication system
**Business Priority**: Critical for user onboarding
**Technical Stack**: React, Node.js, JWT, OAuth2
**Success Dependencies**: Security audit approval, performance benchmarks
**Integration Points**: User profile service, email service, analytics
<!-- AI_CONTEXT_END -->

---

🔧 Issue Template

Overview

Issues represent specific features, bugs, or requirements within an epic. They are the primary unit of development work.

Template Structure

---
id: ISSUE-000
type: issue
title: [Issue Title]
status: todo
epic: EPIC-000
assignee: @developer
created: YYYY-MM-DDTHH:mm:ssZ
updated: YYYY-MM-DDTHH:mm:ssZ
labels: [feature, backend, frontend]
estimate: 5
priority: medium
token_usage:
  total: 0
  by_agent: {}
sync:
  github: null
  jira: null
  linear: null
---

Key Sections

Problem Statement

## Problem Statement
Clear description of the problem this issue solves or the feature it implements.
Include user impact and business justification.

Acceptance Criteria

## Acceptance Criteria
### Functional Requirements
- [ ] User can log in with email/password
- [ ] OAuth2 integration with Google and GitHub
- [ ] Password reset functionality
- [ ] Session management with JWT tokens

### Non-Functional Requirements
- [ ] Response time < 200ms
- [ ] 99.9% uptime requirement
- [ ] GDPR compliance
- [ ] Accessibility (WCAG 2.1 AA)

### Out of Scope
- Enterprise SSO integration
- Social login beyond Google/GitHub
- Multi-factor authentication (separate issue)

Technical Implementation

## Technical Implementation

### Architecture Overview

Frontend (React) → API Gateway → Auth Service → Database ↓ Session Store (Redis)

### Key Components
1. **Authentication Service**: JWT token generation and validation
2. **OAuth Integration**: Passport.js strategies for social login
3. **Session Management**: Redis-based session storage
4. **Security Layer**: Rate limiting, CSRF protection

### Database Schema
```sql
-- Users table modifications
ALTER TABLE users ADD COLUMN oauth_provider VARCHAR(50);
ALTER TABLE users ADD COLUMN oauth_id VARCHAR(255);
ALTER TABLE users ADD COLUMN last_login TIMESTAMP;

API Endpoints

• POST /auth/login - Email/password authentication
• GET /auth/oauth/google - Google OAuth initiation
• GET /auth/oauth/github - GitHub OAuth initiation
• POST /auth/logout - Session termination
• GET /auth/me - Current user profile

#### AI Context Block
```markdown
## AI Context
<!-- AI_CONTEXT_START -->
**Feature**: OAuth2 social login implementation
**Epic**: EPIC-001 User Authentication System
**Priority**: High - blocking other authentication features

**Key Files**:
- `src/auth/strategies/` - OAuth strategy implementations
- `src/controllers/auth.js` - Authentication API endpoints
- `src/middleware/auth.js` - JWT middleware
- `config/passport.js` - Passport.js configuration

**Dependencies**:
- `passport` - Authentication middleware
- `passport-google-oauth20` - Google OAuth strategy
- `passport-github2` - GitHub OAuth strategy
- `jsonwebtoken` - JWT token handling
- `express-session` - Session management

**Environment Variables**:
- `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`
- `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`
- `JWT_SECRET`, `SESSION_SECRET`

**Security Considerations**:
- Implement PKCE for OAuth2 flows
- Secure session cookies (httpOnly, secure, sameSite)
- Rate limiting on authentication endpoints
- Comprehensive audit logging

**Testing Requirements**:
- Unit tests for all auth strategies
- Integration tests for OAuth flows
- E2E tests for complete user journeys
- Security testing for common attack vectors

**Related Work**:
- TASK-001: JWT middleware implementation (prerequisite)
- TASK-002: OAuth button components (parallel)
- ISSUE-003: Password reset flow (dependent)
<!-- AI_CONTEXT_END -->

Usage Example

# Copy issue template
cp templates/issue-template.md tasks/issues/ISSUE-001-oauth2-social-login.md

# Link to epic and customize
vim tasks/issues/ISSUE-001-oauth2-social-login.md

---

⚙️ Task Template

Overview

Tasks represent granular, actionable work items that can be completed in a day or less. They are the smallest unit of work in AI Track Down.

Template Structure

---
id: TASK-000
type: task
title: [Task Title]
status: todo
issue: ISSUE-000
assignee: @developer
created: YYYY-MM-DDTHH:mm:ssZ
updated: YYYY-MM-DDTHH:mm:ssZ
labels: [implementation, frontend]
estimate: 2
token_usage:
  total: 0
  by_agent: {}
---

Key Sections

Scope Definition

## Scope
Clear, specific description of what needs to be accomplished.
Include boundaries and constraints.

**What's Included**:
- OAuth button component implementation
- Loading, success, and error states
- TypeScript definitions
- Basic unit tests

**What's Not Included**:
- OAuth provider configuration
- Backend integration
- End-to-end testing

Implementation Details

## Implementation Details

### Component API
```typescript
interface OAuthButtonProps {
  provider: 'google' | 'github';
  onSuccess: (user: User) => void;
  onError: (error: Error) => void;
  disabled?: boolean;
  size?: 'small' | 'medium' | 'large';
  variant?: 'primary' | 'secondary';
  className?: string;
}

File Structure

src/components/auth/
├── OAuthButton.tsx          # Main component
├── OAuthButton.module.css   # Styles
├── OAuthButton.test.tsx     # Unit tests
├── OAuthButton.stories.tsx  # Storybook stories
└── index.ts                 # Export file

Design Requirements

• Follow existing design system patterns
• Support dark/light theme modes
• Responsive design for mobile devices
• Accessibility compliance (WCAG 2.1 AA)

#### Acceptance Criteria
```markdown
## Acceptance Criteria
- [ ] Component renders correctly for both Google and GitHub
- [ ] Properly handles loading, success, and error states
- [ ] Follows TypeScript strict mode requirements
- [ ] Includes comprehensive unit tests (>90% coverage)
- [ ] Accessible via keyboard navigation
- [ ] Screen reader compatible
- [ ] Mobile responsive (320px minimum width)
- [ ] Follows existing code style and conventions

## Definition of Done
- [ ] Code implemented and peer reviewed
- [ ] All unit tests passing
- [ ] Storybook stories added
- [ ] Accessibility audit passed
- [ ] Documentation updated
- [ ] No TypeScript errors or warnings

AI Context for Tasks

## AI Context
<!-- AI_CONTEXT_START -->
**Component**: OAuth authentication button for React
**Issue**: ISSUE-001 OAuth2 social login
**Complexity**: Medium (TypeScript + accessibility requirements)

**Technical Stack**:
- React 18 with TypeScript strict mode
- CSS Modules for styling
- Jest + React Testing Library for testing
- Storybook for component documentation

**Dependencies**:
- No external OAuth libraries (handled by parent components)
- Uses existing design system components
- Integrates with existing auth hooks

**Accessibility Requirements**:
- ARIA labels and descriptions
- Keyboard navigation support
- Screen reader compatibility
- High contrast support
- Focus management

**Browser Support**:
- Modern browsers (ES2020+)
- Mobile Safari iOS 14+
- Chrome/Firefox/Safari latest 2 versions

**Performance Considerations**:
- Lazy load OAuth provider logos
- Minimize bundle size impact
- Efficient re-rendering patterns
<!-- AI_CONTEXT_END -->

Usage Example

# Copy task template
cp templates/task-template.md tasks/tasks/TASK-001-oauth-button-component.md

# Link to issue and customize
vim tasks/tasks/TASK-001-oauth-button-component.md

---

📊 AI-TRACKDOWN Template

Overview

The AI-TRACKDOWN.md file serves as the central project dashboard, providing real-time status, metrics, and navigation for all stakeholders.

Template Structure

# [Project Name]
## AI Trackdown Project Dashboard

**Project Status:** [Active Development/Planning/On Hold]  
**Start Date:** YYYY-MM-DD  
**Target Launch:** YYYY-MM-DD  
**Project Lead:** @username  

---

## Project Overview
Brief description of the project goals, scope, and key objectives.

### Key Objectives
- Objective 1: Specific, measurable goal
- Objective 2: Another key deliverable
- Objective 3: Performance or quality target

---

## Epic Status Summary

| Epic | Title | Status | Progress | Token Budget | Token Used | Completion Target |
|------|-------|--------|----------|--------------|------------|------------------|
| EPIC-001 | [Epic Name] | in-progress | 65% | 40,000 | 22,847 | 2025-MM-DD |
| EPIC-002 | [Epic Name] | planning | 15% | 60,000 | 5,234 | 2025-MM-DD |

---

## Current Sprint Focus (Sprint X: Dates)

### Active Issues
- **ISSUE-001**: [Issue Title] (in-progress, @assignee)
- **ISSUE-002**: [Issue Title] (in-review, @assignee)

### Blocked Items
- **ISSUE-003**: [Issue Title] (blocked by external dependency)

---

## Token Usage Analytics

### This Week (Date Range)

Total Tokens Used: 12,847 Total Cost: $4.23 Average per Issue: 1,605 tokens

Top Consumers:

1. EPIC-001 Analysis: 4,892 tokens (Claude-3.5-Sonnet)
2. ISSUE-003 Code Review: 3,247 tokens (GPT-4)
3. ISSUE-005 UI Generation: 2,847 tokens (Claude-3.5-Sonnet)

### Budget Status
- **Total Project Budget**: 180,000 tokens ($540 estimated)
- **Used to Date**: 49,201 tokens (27.3%)
- **Remaining**: 130,799 tokens
- **Burn Rate**: 7,000 tokens/week (on track)

---

## Team & AI Agent Activity

### Human Contributors
- @username (Role): X commits, Y reviews
- @username (Role): X commits, Y reviews

### AI Agent Contributions
- **Claude-3.5-Sonnet**: X code reviews, Y requirement analyses
- **GPT-4**: X architecture decisions, Y technical designs
- **GitHub Copilot**: X code suggestions accepted

---

## Integration Status

### External Sync Status
- **GitHub Issues**: ✅ Synced (last: timestamp)
- **Jira Project**: ✅ Synced (last: timestamp)
- **Linear Team**: ⚠️ Partial sync (auth issues)

---

## Risk Assessment

### High Priority Risks
1. **Risk Name**: Description and mitigation strategy

### Token Budget Risks
- Current burn rate assessment
- Mitigation strategies

---

## Recent Decisions & Architecture Notes

### Date: Decision Title
- **Decision**: What was decided
- **Rationale**: Why this decision was made
- **AI Analysis**: AI contribution and token usage
- **Impact**: Affected tasks and timeline

---

## Quick Commands

```bash
# Common project commands
git status
npm test
npm run build

---

Last Updated: timestamp by @username
Auto-generated sections: Token analytics, sync status
Next scheduled update: timestamp

### Usage Example
```bash
# Copy dashboard template
cp templates/AI-TRACKDOWN-template.md AI-TRACKDOWN.md

# Customize for your project
vim AI-TRACKDOWN.md

---

🤖 llms.txt Templates

Overview

The llms.txt files provide AI agents with instant project context following the llms.txt standard.

Main llms.txt Template

# [Project Name] - AI Track Down Project
# Generated: YYYY-MM-DDTHH:mm:ssZ

## Project Overview
Brief project description and current status
Active epics: X
Open issues: Y
Current focus: Primary objective

## Key Files
/tasks/epics/: Project epics and major features
/tasks/issues/: Development issues and requirements
/tasks/tasks/: Implementation tasks and subtasks
/AI-TRACKDOWN.md: Project status dashboard
/docs/: Additional documentation

## Current Priorities
1. EPIC-001: [Epic Name] (status, % complete)
   - ISSUE-001: [Issue Name] (status)
   - ISSUE-002: [Issue Name] (status)

2. EPIC-002: [Epic Name] (status, % complete)
   - ISSUE-003: [Issue Name] (status)

## Technology Stack
- Frontend: [Technologies]
- Backend: [Technologies]
- Database: [Technologies]
- Infrastructure: [Technologies]

## Development Workflow
- Git: [Branch strategy]
- Testing: [Test strategy]
- Deployment: [Deployment process]
- Code Review: [Review process]

## AI Integration
- Token Budget: X tokens (Y% used)
- Primary AI Agents: [List of agents and roles]
- Context Files: llms.txt, docs/llms-full.txt
- Integration Status: [External systems]

## Quick Commands
# View current work
find tasks/ -name "*.md" -exec grep "status: in-progress" {} \;

# Check token usage
grep -r "token_usage:" tasks/ | head -10

# Project status
cat AI-TRACKDOWN.md | head -20

## Contact Information
- Project Lead: @username
- Technical Lead: @username
- AI/ML Lead: @username

Extended llms-full.txt Template

# [Project Name] - Complete Project Context
# Generated: YYYY-MM-DDTHH:mm:ssZ

## Complete Project History
[Detailed project background, decisions, and evolution]

## Full Task Hierarchy
[Complete breakdown of all epics, issues, and tasks]

## Technical Architecture
[Comprehensive system architecture documentation]

## AI Agent Context
[Detailed context for AI agents including:]
- Complete codebase structure
- Development patterns and conventions
- Integration points and dependencies
- Security requirements and constraints
- Performance requirements and benchmarks
- Testing strategies and requirements

## Decision History
[Complete log of architectural and technical decisions]

## Integration Details
[Comprehensive integration documentation for external systems]

## Token Usage History
[Complete token usage analytics and optimization notes]

## Knowledge Base
[Accumulated project knowledge and lessons learned]

Usage Examples

# Copy llms.txt templates
cp templates/llms-txt-examples.md .ai-trackdown/llms.txt
cp templates/llms-txt-examples.md docs/llms-full.txt

# Customize for your project
vim .ai-trackdown/llms.txt
vim docs/llms-full.txt

---

⚙️ Configuration Templates

Basic Config Template

# .ai-trackdown/config.yaml
version: 1

project:
  name: "My AI Project"
  id_prefix: "PROJ"
  description: "Project description for AI context"
  
workflow:
  statuses: [todo, in-progress, in-review, done, blocked]
  labels: [feature, bug, enhancement, security, performance]
  
token_management:
  budget: 100000
  alert_thresholds:
    warning: 0.8
    critical: 0.95
  tracking_enabled: true
  
ai_agents:
  enabled: true
  context_depth: 3
  budget_per_interaction: 5000
  
integrations:
  github:
    enabled: false
    repository: ""
  jira:
    enabled: false
    server: ""
    project: ""
  linear:
    enabled: false
    team: ""

GitHub Integration Config

# .ai-trackdown/integrations/github.yaml
repository: "owner/repo"
enabled: true

mapping:
  epic:
    milestone: title
    body: |
      ## Epic Overview
      ${description}
      
      ## Success Metrics
      ${success_metrics}
      
      ## Issues
      ${issues_list}
      
  issue:
    title: title
    body: |
      ${description}
      
      ## Acceptance Criteria
      ${acceptance_criteria}
      
      ## AI Context
      ${ai_context}
    labels: labels
    assignees: 
      - transform: strip_at(assignee)
    projects: ["Project Board Name"]
    
  task:
    title: "[${issue}] ${title}"
    body: |
      **Parent Issue**: ${issue}
      
      ${description}
      
      ## Implementation Details
      ${implementation_details}
    labels: 
      - "task"
      - transform: labels
    assignees:
      - transform: strip_at(assignee)

sync:
  direction: bidirectional
  frequency: hourly
  conflict_resolution: manual
  
webhooks:
  events: [issues, pull_request, issue_comment]
  secret: "${GITHUB_WEBHOOK_SECRET}"

Jira Integration Config

# .ai-trackdown/integrations/jira.yaml
server: "https://company.atlassian.net"
project: "PROJ"
enabled: true

auth:
  type: "token"
  username: "${JIRA_USERNAME}"
  token: "${JIRA_API_TOKEN}"

mapping:
  epic:
    issuetype: "Epic"
    summary: title
    description: |
      {panel:title=Epic Overview}
      ${description}
      {panel}
      
      {panel:title=Success Metrics}
      ${success_metrics}
      {panel}
    epic_name: title
    labels: labels
    
  issue:
    issuetype: "Story"
    summary: title
    description: |
      ${description}
      
      h3. Acceptance Criteria
      ${acceptance_criteria}
      
      h3. Technical Notes
      ${technical_implementation}
    epic_link: epic
    story_points: estimate
    priority: 
      map:
        low: "Low"
        medium: "Medium"
        high: "High"
        critical: "Highest"
    labels: labels
    assignee: 
      transform: strip_at(assignee)
      
  task:
    issuetype: "Sub-task"
    summary: title
    description: |
      *Parent Issue:* ${issue}
      
      ${description}
      
      h4. Implementation Details
      ${implementation_details}
    parent: issue
    assignee:
      transform: strip_at(assignee)

status_mapping:
  todo: "To Do"
  in-progress: "In Progress"
  in-review: "In Review"
  done: "Done"
  blocked: "Blocked"

sync:
  direction: bidirectional
  frequency: "15min"
  custom_fields:
    token_usage: "customfield_10001"
    ai_context: "customfield_10002"

Linear Integration Config

# .ai-trackdown/integrations/linear.yaml
team: "engineering"
enabled: true

auth:
  token: "${LINEAR_API_TOKEN}"

mapping:
  epic:
    title: title
    description: |
      ## Epic Overview
      ${description}
      
      ## Success Metrics
      ${success_metrics}
    priority: 
      map:
        low: 4
        medium: 3
        high: 2
        critical: 1
    labels: labels
    
  issue:
    title: title
    description: |
      ${description}
      
      ## Acceptance Criteria
      ${acceptance_criteria}
    priority:
      map:
        low: 4
        medium: 3
        high: 2
        critical: 1
    estimate: estimate
    labels: labels
    assignee:
      transform: strip_at(assignee)
    project: epic
    
  task:
    title: "[${issue}] ${title}"
    description: |
      **Parent Issue:** ${issue}
      
      ${description}
    assignee:
      transform: strip_at(assignee)
    parent: issue

state_mapping:
  todo: "Backlog"
  in-progress: "In Progress"
  in-review: "In Review" 
  done: "Done"
  blocked: "Blocked"

sync:
  direction: bidirectional
  frequency: "5min"
  webhook_enabled: true

🎨 Template Customization

Creating Custom Templates

Custom Issue Types

# Create custom template for security reviews
cp templates/issue-template.md templates/security-review-template.md

# Customize for security-specific fields
vim templates/security-review-template.md

Team-Specific Templates

# Add team-specific fields to templates
team_fields:
  frontend:
    additional_labels: [ui, ux, responsive]
    required_sections: [design_specs, browser_compatibility]
    
  backend:
    additional_labels: [api, database, performance]
    required_sections: [api_design, database_schema]
    
  devops:
    additional_labels: [infrastructure, deployment, monitoring]
    required_sections: [infrastructure_requirements, deployment_strategy]

AI Agent Specialized Templates

<!-- AI_CONTEXT_START: ARCHITECTURE_REVIEW -->
**Review Type**: Security architecture assessment
**Scope**: Authentication and authorization systems
**Threat Model**: OWASP Top 10, custom threat analysis
**Compliance**: SOC2, GDPR, industry standards
**Tools**: Static analysis, dependency scanning, pen testing
**Deliverables**: Security report, remediation plan
<!-- AI_CONTEXT_END -->

Template Validation

YAML Frontmatter Validation

# Validate YAML syntax
python -c "import yaml; yaml.safe_load(open('task.md').read().split('---')[1])"

# Check required fields
grep -q "^id:" task.md || echo "Missing ID field"
grep -q "^type:" task.md || echo "Missing type field"
grep -q "^title:" task.md || echo "Missing title field"

Content Validation

# Check for AI context blocks
grep -q "AI_CONTEXT_START" task.md || echo "Missing AI context"

# Validate task relationships
grep -q "epic:\|issue:" task.md || echo "Missing parent relationship"

# Check token tracking
grep -q "token_usage:" task.md || echo "Missing token tracking"

🚀 Best Practices

Template Usage Guidelines

1. Always Use Templates: Start with templates rather than creating from scratch
2. Customize Systematically: Adapt templates to your team's specific needs
3. Maintain Consistency: Use the same template structure across all tasks
4. Update Templates: Evolve templates based on lessons learned
5. Validate Content: Check YAML frontmatter and required sections

AI Optimization Tips

1. Rich Context: Include comprehensive AI context blocks
2. Token Budgeting: Set realistic token budgets per template type
3. Context Inheritance: Design templates for context reuse
4. Efficient Patterns: Optimize templates for minimal token consumption
5. Regular Updates: Keep llms.txt files current and accurate

Integration Considerations

1. Field Mapping: Ensure template fields map correctly to external systems
2. Sync Frequency: Balance real-time updates with API rate limits
3. Conflict Resolution: Plan for handling sync conflicts
4. Data Validation: Validate data before syncing to external systems
5. Rollback Strategy: Have plans for handling integration failures

This comprehensive templates reference ensures teams can effectively use and customize AI Track Down for their specific needs while maintaining the AI-native advantages of the framework.