AI Agent Guide for AI Track Down Framework

This comprehensive guide provides AI agents with complete instructions for working with the AI Track Down framework - a documentation-based task management system optimized for AI-human collaboration.

🤖 System Prompt for AI Agents

When working with AI Track Down, use this system context:

You are working with the AI Track Down framework - a documentation-based task management system optimized for AI-human collaboration. This framework uses structured markdown files with YAML frontmatter for task tracking.

## Framework Structure
- **Epics**: High-level initiatives with business goals
- **Issues**: Specific problems or features within epics  
- **Tasks**: Implementation steps within issues
- **AI-TRACKDOWN.md**: Project dashboard and status overview

## Key Files and Templates
- Templates in `/templates/` directory for creating new items
- Examples in `/examples/` directory for reference patterns
- Main project dashboard: `AI-TRACKDOWN.md`
- AI context file: `llms.txt`

## When Working with Tasks

### Creating New Items
1. Copy appropriate template from `/templates/` directory
2. Fill in YAML frontmatter with: id, title, status, assignee, dates
3. Write clear descriptions with acceptance criteria
4. Add AI context markers: `<!-- AI_CONTEXT_START -->` and `<!-- AI_CONTEXT_END -->`
5. Track token usage in frontmatter under `token_usage` section

### Updating Existing Items
1. Update status in YAML frontmatter (pending/in-progress/completed/blocked)
2. Add new findings to description body
3. Update token usage when AI work is performed
4. Maintain relationships (epic/issue/task hierarchy)

### Token Tracking
Always update token usage when you perform work:
```yaml
token_usage:
  total: [cumulative tokens]
  by_agent:
    [agent_name]: [tokens_used]

AI Context Optimization

• Add context markers around technical details AI agents need
• Reference related files, dependencies, and implementation notes
• Include links to related tasks using task IDs

File Organization

• Use clear, descriptive task IDs (EPIC-001, ISSUE-001, TASK-001)
• Store files in appropriate directories: /tasks/epics/, /tasks/issues/, /tasks/tasks/
• Update AI-TRACKDOWN.md dashboard when completing major work
• Generate/update llms.txt for project context

Best Practices

• Be specific in task descriptions and acceptance criteria
• Track all AI token usage for cost analysis
• Use AI context markers for technical implementation details
• Maintain clear relationships between epics, issues, and tasks
• Update project dashboard regularly to reflect current state

This framework is documentation-only - use manual file editing and template copying rather than CLI commands.

## 📚 Essential Documentation Reading Protocol

### Required Reading Order
Before working with any project using AI Track Down, read these files in order:

1. **AI-TRACKDOWN.md** (Project Dashboard)
   - Current project status and active work
   - Sprint goals and completion metrics
   - Token usage and budget status
   - Key achievements and blockers

2. **README.md** (Framework Overview)
   - Project context and revolutionary positioning
   - Key features and value proposition
   - Getting started workflows and examples
   - Integration capabilities and roadmap

3. **llms.txt** (Project Index)
   - Quick project overview and structure
   - Active work items and priorities
   - Quick commands and workflows
   - Documentation file locations

4. **docs/llms-full.txt** (if available)
   - Complete project context and history
   - Detailed task relationships and dependencies
   - Full technical context and implementation notes

### Framework Documentation Structure

#### Core Documentation (/docs/)
- **getting-started.md** - Complete setup and onboarding guide
- **architecture.md** - System design and technical architecture
- **best-practices.md** - Proven strategies and team workflows
- **api-reference.md** - Template usage and configuration reference
- **integrations.md** - Third-party platform integration patterns

#### Templates (/templates/)
- **AI-TRACKDOWN-template.md** - Project dashboard template
- **epic-template.md** - High-level initiative template
- **issue-template.md** - Specific problem/feature template
- **task-template.md** - Implementation step template
- **llms-txt-examples.md** - AI context file examples

#### Examples (/examples/)
- **basic-setup/** - Small team starter configuration
- **enterprise-integration/** - Large organization examples
- **complete-project/** - Full realistic project demonstration
- **sample-project/** - Simple project walkthrough

## 🔄 AI Agent Workflow Patterns

### Context Building Workflow

1. **Project Discovery**
   ```bash
   # Read project overview
   cat AI-TRACKDOWN.md
   
   # Understand framework structure
   cat llms.txt
   
   # Review current work
   find tasks/ -name "*.md" -exec grep "status: in-progress" {} \;

2. Task Analysis

   # Read specific task context
   cat tasks/epics/EPIC-001-*.md
   cat tasks/issues/ISSUE-001-*.md
   
   # Extract AI context blocks
   grep -A 10 "AI_CONTEXT_START" tasks/**/*.md
   

3. Work Planning

   # Identify related tasks
   grep -r "EPIC-001\|ISSUE-001" tasks/
   
   # Check dependencies
   grep -r "blocks\|blocked" tasks/
   

Task Creation Workflow

1. Select Template

   # Copy appropriate template
   cp templates/[type]-template.md tasks/[type]/[ID]-[title].md
   

2. Customize Content

   ---
   id: TASK-001
   type: task
   title: Implement OAuth2 button component
   status: todo
   issue: ISSUE-001
   assignee: @ai-agent
   created: 2025-07-07T15:00:00Z
   labels: [frontend, react, oauth]
   estimate: 3
   token_usage:
     total: 0
     by_agent: {}
   ---
   

3. Add AI Context

   ## AI Context
   <!-- AI_CONTEXT_START -->
   Frontend component for OAuth2 authentication buttons.
   
   **Framework**: React 18 with TypeScript
   **Styling**: CSS Modules with responsive design
   **Testing**: Jest + React Testing Library
   **Dependencies**: passport-oauth2, jsonwebtoken
   
   **Related Files**:
   - src/components/auth/OAuthButton.tsx
   - src/hooks/useOAuth.ts
   - src/types/auth.ts
   
   **Requirements**:
   - Google and GitHub OAuth support
   - Loading, success, and error states
   - Accessibility compliance (WCAG 2.1 AA)
   - Mobile-responsive design
   <!-- AI_CONTEXT_END -->
   

Status Update Workflow

1. Track Work Progress

   # Update status in YAML frontmatter
   status: in-progress
   updated: 2025-07-07T16:30:00Z
   
   # Add token usage
   token_usage:
     total: 542
     by_agent:
       claude: 542
   

2. Document Findings

   ## Implementation Notes
   - OAuth2 PKCE flow implemented successfully
   - Added comprehensive error handling
   - Unit tests passing with 95% coverage
   
   ## Next Steps
   - Integration testing with OAuth providers
   - Cross-browser compatibility testing
   - Performance optimization review
   

3. Update Relationships

   ## Related Tasks
   - Unblocks: TASK-003 (Profile sync), TASK-004 (Settings UI)
   - Related: ISSUE-002 (Password reset flow)
   

🧠 AI Context Management

Context Markers

Use standardized AI context blocks for persistent knowledge:

<!-- AI_CONTEXT_START -->
[Technical implementation details that AI agents need to understand]

**Key Files**: List of relevant source files
**Dependencies**: External libraries and internal modules
**Architecture**: High-level design decisions
**Security**: Security considerations and requirements
**Performance**: Performance requirements and constraints
**Testing**: Testing strategy and requirements
**Integration**: External system integration points
<!-- AI_CONTEXT_END -->

Context Categories

Technical Context

<!-- AI_CONTEXT_START -->
**Framework**: React 18 with TypeScript
**Build Tool**: Vite with hot reload
**State Management**: Zustand for global state
**Styling**: Tailwind CSS with custom components
**Testing**: Vitest + React Testing Library
**Linting**: ESLint + Prettier + TypeScript strict mode
<!-- AI_CONTEXT_END -->

Business Context

<!-- AI_CONTEXT_START -->
**Business Goal**: Increase user conversion by 15%
**User Personas**: B2B SaaS customers, technical and non-technical
**Success Metrics**: Login completion rate, time to authentication
**Constraints**: GDPR compliance, SOC2 requirements
**Timeline**: MVP by Q1 2025, full rollout by Q2 2025
<!-- AI_CONTEXT_END -->

Security Context

<!-- AI_CONTEXT_START -->
**Security Requirements**: OAuth2 with PKCE, secure session management
**Threat Model**: CSRF attacks, token interception, session hijacking
**Compliance**: GDPR, SOC2 Type II, industry best practices
**Audit Requirements**: Comprehensive logging, token rotation
**Penetration Testing**: Required before production deployment
<!-- AI_CONTEXT_END -->

📊 Token Tracking Best Practices

Granular Tracking

Track tokens at multiple levels for cost optimization:

# Epic-level tracking
token_usage:
  total: 15247
  budget: 50000
  remaining: 34753
  by_phase:
    planning: 3500
    implementation: 8247
    review: 2500
    documentation: 1000
  by_agent:
    claude: 9847
    gpt4: 4200
    copilot: 1200

Session Tracking

Maintain detailed session logs:

token_usage:
  total: 1247
  sessions:
    - date: 2025-07-07T10:00:00Z
      agent: claude
      count: 542
      purpose: "Requirements analysis and task breakdown"
      efficiency: high
    - date: 2025-07-07T14:30:00Z
      agent: claude
      count: 705
      purpose: "Code review and optimization suggestions"
      efficiency: medium

Budget Management

Set and monitor budgets proactively:

# Project-level budget
project_budget:
  total: 200000
  allocated:
    epic_001: 50000
    epic_002: 75000
    epic_003: 50000
    overhead: 25000
  alert_thresholds:
    warning: 0.8  # 80% of budget
    critical: 0.95 # 95% of budget

🔧 Integration Workflows

GitHub Issues Integration

When working with GitHub integration:

1. Read GitHub Mapping

   # Check .ai-trackdown/integrations/github.yaml
   repository: owner/repo
   mapping:
     title: title
     body: description + acceptance_criteria
     labels: labels
     assignees: assignee
   

2. Sync Status Updates

   # Update sync status in task frontmatter
   sync:
     github: 123  # GitHub issue number
     last_sync: 2025-07-07T15:00:00Z
     direction: bidirectional
   

3. Handle Conflicts

   ## Sync Conflicts
   - GitHub title differs from AI Track Down title
   - Resolution: Manual review required
   - Action: @team-lead to resolve conflicts
   

Jira Integration

For Jira integration workflows:

1. Map Fields Correctly

   # .ai-trackdown/integrations/jira.yaml
   project: PROJ
   mapping:
     story_points: estimate
     epic_link: epic
     sprint: sprint
     status_mapping:
       todo: "To Do"
       in-progress: "In Progress"
       done: "Done"
   

2. Handle Custom Fields

   sync:
     jira: PROJ-123
     custom_fields:
       team: "Engineering"
       priority: "High"
       security_review: true
   

Linear Integration

For Linear integration:

1. Team Mapping

   # .ai-trackdown/integrations/linear.yaml
   team: engineering
   project: Q1-2025
   mapping:
     priority: priority
     estimate: estimate
     cycle: sprint
   

2. State Synchronization

   sync:
     linear: ENG-123
     state: "In Progress"
     cycle: "Sprint 5"
     last_updated: 2025-07-07T15:00:00Z
   

⚡ AI Agent Commands

Quick Commands for AI Agents

Project Status Check

# Get current project status
grep -A 5 "Project Status" AI-TRACKDOWN.md

# Check active work
grep "status: in-progress" tasks/**/*.md

# Review token usage
grep -A 3 "token_usage:" tasks/**/*.md | head -20

Task Management

# Find tasks by status
find tasks/ -name "*.md" -exec grep -l "status: todo" {} \;

# Get task dependencies
grep -B 2 -A 2 "blocks\|blocked" tasks/**/*.md

# Check AI context
grep -A 20 "AI_CONTEXT_START" tasks/**/*.md

Context Generation

# Generate project context summary
echo "# Project Context Summary" > context.md
cat AI-TRACKDOWN.md | head -20 >> context.md
echo "## Active Tasks" >> context.md
grep -B 1 -A 5 "status: in-progress" tasks/**/*.md >> context.md

Token Analysis

# Analyze token usage patterns
grep -r "by_agent:" tasks/ | cut -d: -f3- | sort | uniq -c

# Find high-token tasks
grep -B 5 -A 1 "total: [5-9][0-9][0-9][0-9]" tasks/**/*.md

# Budget status check
grep -A 10 "Token Budget" AI-TRACKDOWN.md

🎯 AI Agent Specialization

Agent Roles and Responsibilities

Architecture Agent

• Focus: System design, technical decisions
• Token Budget: 8000 per interaction
• Specializations: Architecture, security, performance
• Context Depth: High (5 levels of task hierarchy)

agent_config:
  role: architect
  max_tokens: 8000
  context_depth: 5
  specializations: [architecture, security, performance]
  responsibilities:
    - System design decisions
    - Technology stack recommendations
    - Security architecture review
    - Performance optimization strategies

Implementation Agent

• Focus: Code generation, debugging, testing
• Token Budget: 4000 per interaction
• Specializations: Coding, debugging, testing
• Context Depth: Medium (3 levels)

agent_config:
  role: implementer
  max_tokens: 4000
  context_depth: 3
  specializations: [coding, debugging, testing]
  responsibilities:
    - Code implementation
    - Bug fixes and debugging
    - Test case development
    - Code optimization

Review Agent

• Focus: Code review, quality assurance
• Token Budget: 3000 per interaction
• Specializations: Review, refactoring, best practices
• Context Depth: Low (2 levels)

agent_config:
  role: reviewer
  max_tokens: 3000
  context_depth: 2
  specializations: [review, refactoring, best-practices]
  responsibilities:
    - Code review and feedback
    - Quality assurance
    - Best practice enforcement
    - Refactoring suggestions

Documentation Agent

• Focus: Documentation, knowledge management
• Token Budget: 5000 per interaction
• Specializations: Documentation, examples, tutorials
• Context Depth: High (4 levels)

agent_config:
  role: documenter
  max_tokens: 5000
  context_depth: 4
  specializations: [documentation, examples, tutorials]
  responsibilities:
    - Technical documentation
    - API documentation
    - User guides and tutorials
    - Knowledge base maintenance

🚀 Advanced AI Agent Patterns

Multi-Agent Collaboration

Handoff Protocols

## AI-Human Handoff: ISSUE-001

### Completed by AI (Claude)
- [x] Requirements analysis and breakdown
- [x] Architecture design and component identification
- [x] API contract definition
- [x] Security consideration documentation
- [x] Test case planning

**Token Usage**: 2,847 tokens
**Confidence Level**: High (95%)
**Review Required**: Security architecture

### Handoff to Human (@developer)
**Next Steps**:
1. Review and approve OAuth provider configuration
2. Implement the OAuthButton component per specifications
3. Set up development environment with OAuth credentials
4. Run initial implementation tests

**Context Provided**:
- Complete component specifications in TASK-001
- Security requirements in ISSUE-001 AI Context
- Related work in EPIC-001

**Questions for Human**:
- Should we support additional OAuth providers beyond Google/GitHub?
- Any specific brand guideline requirements for OAuth buttons?
- Preference for CSS-in-JS vs CSS Modules for styling?

### Human Implementation Notes
*[Space for human developer to add notes during implementation]*

### Handoff Back to AI (for review)
*[Human will update when ready for AI code review]*

Collaborative Workflows

## Collaborative Task: ISSUE-003 Two-Factor Authentication

### Phase 1: Architecture (AI Architect)
- [x] Research 2FA best practices and standards
- [x] Design TOTP + backup codes system
- [x] Define security requirements and threat model
- [x] Create API specification

**Token Usage**: 1,847 tokens
**Deliverables**: Architecture document, API specs

### Phase 2: Implementation (Human + AI Implementer)
- [ ] Backend TOTP service implementation
- [ ] Frontend QR code generation and verification
- [ ] Backup code generation and management
- [ ] Recovery flow implementation

**Collaboration Model**: Human writes code, AI provides guidance and reviews
**Token Budget**: 3,000 tokens

### Phase 3: Testing (AI + Human QA)
- [ ] Unit test development (AI assistance)
- [ ] Integration testing (Human execution)
- [ ] Security testing (AI vulnerability analysis)
- [ ] User acceptance testing (Human coordination)

**Token Budget**: 1,500 tokens

### Phase 4: Documentation (AI Documenter)
- [ ] API documentation generation
- [ ] User guide creation
- [ ] Security audit documentation
- [ ] Deployment guide

**Token Budget**: 1,200 tokens

Context Optimization Strategies

Efficient Context Patterns

<!-- AI_CONTEXT_START: OPTIMIZED -->
**Quick Context**: OAuth2 React component with Google/GitHub support
**Files**: src/auth/OAuthButton.tsx, src/hooks/useOAuth.ts
**Stack**: React18+TS, Tailwind, Vitest
**Deps**: passport-oauth2, jsonwebtoken
**Reqs**: PKCE, responsive, accessible, error handling
**Tests**: Unit+integration, 90%+ coverage required
<!-- AI_CONTEXT_END -->

Contextual Inheritance

## Context Inheritance Chain

### Epic Level (EPIC-001)
- Business context: User authentication system
- Architecture: Microservices, JWT tokens, Redis sessions
- Security: OAuth2, PKCE, audit logging
- Timeline: Q1 2025 delivery

### Issue Level (ISSUE-001) - Inherits Epic Context
- Specific feature: Social login integration
- Providers: Google, GitHub OAuth2
- Requirements: Mobile responsive, error handling

### Task Level (TASK-001) - Inherits Issue Context
- Component: OAuthButton React component
- Implementation: TypeScript, CSS Modules
- Testing: Jest + RTL, accessibility tests

This comprehensive guide ensures AI agents can work effectively within the AI Track Down framework while maintaining cost efficiency and high-quality output. The key is balancing context richness with token economy, ensuring every interaction is both informed and cost-effective.