Best Practices - bobmatnyc/ai-trackdown GitHub Wiki

Best Practices Guide

This guide outlines proven strategies for maximizing the benefits of AI Track Down in human-AI collaborative development environments.

🎯 Core Principles

1. AI-First Design

Design your task management workflow with AI agents as first-class citizens, not afterthoughts.

✅ Do:

Write clear, structured task descriptions that AI can understand
Include context blocks with file paths and dependencies
Use consistent terminology across your project
Set realistic token budgets and track usage

❌ Don't:

Write vague or ambiguous task descriptions
Omit context that AI agents need
Ignore token costs until they become a problem
Mix multiple concerns in a single task

2. Local-First Mindset

Treat your markdown files as the authoritative source of truth.

✅ Do:

Edit tasks in your preferred text editor
Use git for version control and collaboration
Keep tasks close to the code they describe
Leverage git branches for experimental work

❌ Don't:

Rely solely on external integrations
Edit tasks exclusively through web UIs
Ignore git best practices for task files
Create complex sync dependencies

3. Token Economics

Manage AI costs proactively with budget-aware development practices.

✅ Do:

Set and monitor token budgets at epic and project levels
Track which AI interactions provide the most value
Optimize context for token efficiency
Use cost reports to guide AI usage decisions

❌ Don't:

Ignore token usage until costs spiral
Provide excessive context that wastes tokens
Use expensive models for simple tasks
Forget to attribute token usage to specific work

📝 Task Writing Excellence

Epic Structure Best Practices

Template for High-Value Epics:

---
id: EPIC-001
type: epic
title: User Authentication System
status: in-progress
owner: @team-lead
created: 2025-07-07T09:00:00Z
target_date: 2025-08-15T00:00:00Z
token_budget: 50000
token_usage:
  total: 12847
  remaining: 37153
labels: [authentication, security, phase-1]
---

# User Authentication System

## Business Context
Why this epic matters: Modern applications require secure, scalable authentication that supports multiple identity providers while maintaining excellent user experience.

## Success Metrics
- Support 100,000 concurrent users
- < 200ms authentication response time
- 99.9% uptime SLA
- Zero security incidents
- < 5% user dropoff during authentication

## User Stories
As a user, I want to...
- Log in with email/password quickly and securely
- Use social login (Google, GitHub) for convenience
- Reset my password when I forget it
- Enable two-factor authentication for security

## Technical Approach
- JWT-based stateless authentication
- OAuth2 with PKCE for social login
- bcrypt for password hashing
- Redis for session storage and rate limiting
- Comprehensive audit logging

## Issues Breakdown
- [x] ISSUE-001: Core login flow implementation
- [ ] ISSUE-002: Social OAuth integration  
- [ ] ISSUE-003: Password reset system
- [ ] ISSUE-004: Two-factor authentication
- [ ] ISSUE-005: Security audit and testing

## Token Budget Allocation
- Requirements analysis: 10,000 tokens (20%)
- Implementation support: 25,000 tokens (50%)
- Code review and optimization: 10,000 tokens (20%)
- Documentation and testing: 5,000 tokens (10%)

## Dependencies
- User profile service (EPIC-002)
- Email service integration
- Security compliance review

## Risks and Mitigations
- **Risk**: OAuth provider changes break integration
  **Mitigation**: Comprehensive testing, provider abstraction layer
- **Risk**: Session management complexity
  **Mitigation**: Use proven Redis patterns, extensive testing

Issue Structure Best Practices

Template for AI-Friendly Issues:

---
id: ISSUE-001
type: issue
title: Implement OAuth2 social login flow
status: in-progress
epic: EPIC-001
assignee: @developer
created: 2025-07-07T10:00:00Z
updated: 2025-07-07T14:30:00Z
labels: [authentication, oauth, frontend, backend]
estimate: 8
priority: high
token_usage:
  total: 1247
  by_agent:
    claude: 892
    copilot: 355
sync:
  github: 145
  jira: AUTH-234
---

# Implement OAuth2 Social Login Flow

## Business Value
Enable users to sign in with their existing Google and GitHub accounts, reducing friction in the onboarding process and improving conversion rates.

## Problem Statement
Current email/password authentication creates barriers for new users. Social login is expected by modern users and reduces password fatigue.

## Acceptance Criteria
### Functional Requirements
- [ ] Google OAuth2 integration with OpenID Connect
- [ ] GitHub OAuth2 integration  
- [ ] User profile creation from OAuth data
- [ ] Account linking for existing email users
- [ ] Graceful error handling for OAuth failures
- [ ] PKCE implementation for security

### Non-Functional Requirements
- [ ] < 3 second OAuth flow completion
- [ ] Mobile-responsive OAuth buttons
- [ ] Comprehensive error messages
- [ ] Security audit approval
- [ ] GDPR compliance for EU users

### Out of Scope
- LinkedIn, Twitter, or other providers
- Enterprise SSO (SAML/OIDC)
- Account merging conflicts

## Technical Implementation

### Architecture

Frontend → OAuth Provider → Callback Handler → User Service → Database


### Key Components
1. **OAuth Configuration**: Environment-specific client IDs and secrets
2. **OAuth Buttons**: React components with proper UX states
3. **Callback Handler**: Express.js route for OAuth responses
4. **User Service**: Profile creation and account linking logic
5. **Security Layer**: CSRF protection, state validation

### Database Changes
```sql
-- Add OAuth fields to users table
ALTER TABLE users ADD COLUMN google_id VARCHAR(255) UNIQUE;
ALTER TABLE users ADD COLUMN github_id VARCHAR(255) UNIQUE;
ALTER TABLE users ADD COLUMN oauth_provider VARCHAR(50);
ALTER TABLE users ADD COLUMN oauth_profile JSONB;

API Endpoints

POST /auth/oauth/google - Initiate Google OAuth
POST /auth/oauth/github - Initiate GitHub OAuth
GET /auth/oauth/callback - Handle OAuth callbacks
POST /auth/oauth/link - Link OAuth to existing account

AI Context

This issue implements OAuth2 social login for the user authentication system.

Key Files:

src/auth/oauth.js - OAuth2 strategy implementations
src/components/auth/OAuthButtons.tsx - Frontend OAuth UI
src/routes/auth.js - Authentication API routes
config/oauth.json - OAuth provider configurations
migrations/003_add_oauth_fields.sql - Database schema

Dependencies:

passport-google-oauth20 - Google OAuth strategy
passport-github2 - GitHub OAuth strategy
express-session - Session management
connect-redis - Redis session store
jsonwebtoken - JWT token handling

Environment Variables:

GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET
OAUTH_CALLBACK_URL
SESSION_SECRET

Security Considerations:

PKCE flow prevents authorization code interception
State parameter prevents CSRF attacks
Secure session cookies with httpOnly flag
Rate limiting on OAuth endpoints
Input validation for OAuth responses

Related Work:

EPIC-001: Parent authentication epic
ISSUE-002: Password reset (shares user model)
ISSUE-004: Two-factor auth (profile integration)
TASK-001: User model creation (completed dependency)

Testing Requirements:

Unit tests for OAuth strategies
Integration tests for OAuth flows
E2E tests for complete user journeys
Security tests for attack vectors

Implementation Plan

Phase 1: Backend OAuth Setup (3 days)

Configure OAuth providers in environment
Implement Passport.js strategies
Create callback handlers
Add database migrations
Write unit tests

Phase 2: Frontend Integration (2 days)

Create OAuth button components
Implement OAuth flow UI
Add loading and error states
Write frontend tests
Update existing login page

Phase 3: Testing and Security (2 days)

Comprehensive OAuth flow testing
Security audit and penetration testing
Performance testing under load
Cross-browser compatibility testing
Documentation updates

Phase 4: Deployment (1 day)

Staging environment testing
Production deployment
Monitoring and alerting setup
Rollback procedures documented

Notes

Google OAuth requires domain verification for production
GitHub OAuth supports organization restrictions
Consider rate limiting OAuth endpoints
Document OAuth provider setup for other developers

Token Budget

Initial analysis: 500 tokens (completed)
Implementation guidance: 1,500 tokens (budgeted)
Code review: 800 tokens (budgeted)
Total budget: 2,800 tokens


### Task Structure Best Practices

**Template for Granular Tasks:**
```markdown
---
id: TASK-001
type: task
title: Create OAuth2 button component with loading states
status: todo
issue: ISSUE-001
assignee: @frontend-dev
created: 2025-07-07T15:00:00Z
labels: [frontend, react, oauth, component]
estimate: 3
token_usage:
  total: 234
  by_agent:
    copilot: 234
---

# Create OAuth2 Button Component with Loading States

## Scope
Create reusable React component for OAuth2 authentication buttons with proper UX states.

## Requirements
- Generic OAuth button component accepting provider config
- Loading, success, and error states
- Accessibility compliance (WCAG 2.1 AA)
- Mobile-responsive design
- TypeScript definitions

## 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';
}

States to Handle

Idle: Ready for user interaction
Loading: OAuth flow in progress
Success: Successful authentication
Error: Failed authentication
Disabled: Button cannot be clicked

Files to Create/Modify

src/components/auth/OAuthButton.tsx - Main component
src/components/auth/OAuthButton.module.css - Styles
src/components/auth/OAuthButton.test.tsx - Tests
src/types/auth.ts - TypeScript definitions
src/hooks/useOAuth.ts - OAuth logic hook

AI Context

Frontend component for OAuth2 authentication buttons.

Framework: React 18 with TypeScript Styling: CSS Modules with responsive design Testing: Jest + React Testing Library Accessibility: WCAG 2.1 AA compliance required

Design System: Follow existing button patterns in src/components/ui/Button.tsx State Management: Use built-in React state, no external state library needed Error Handling: Display user-friendly messages, log technical details

Provider Configurations:

Google: Red (#db4437) brand color, proper logo
GitHub: Dark (#333) brand color, proper logo
Both: Official brand guidelines compliance

Acceptance Criteria

Component renders correctly for both providers
Loading state shows spinner and disables interaction
Error state displays user-friendly message
Success state provides visual feedback before redirect
Accessible via keyboard navigation
Screen reader compatible
Mobile responsive (320px+)
Passes all automated tests

Definition of Done

Code implemented and tested
All tests passing
Code review approved
Accessibility audit passed
Storybook stories added
Documentation updated


## 🤖 AI Agent Collaboration

### Establishing AI Agent Personas

**Create distinct roles for different AI agents:**

```yaml
# .ai-trackdown/ai-agents.yaml
agents:
  architect:
    model: claude-3.5-sonnet
    role: "System architecture and design decisions"
    context_depth: 5
    max_tokens_per_interaction: 8000
    specializations: [architecture, security, performance]
    
  implementer:
    model: gpt-4-turbo
    role: "Code implementation and optimization"
    context_depth: 3
    max_tokens_per_interaction: 4000
    specializations: [coding, debugging, testing]
    
  reviewer:
    model: claude-3.5-sonnet
    role: "Code review and quality assurance"
    context_depth: 2
    max_tokens_per_interaction: 3000
    specializations: [review, refactoring, best-practices]
    
  documenter:
    model: gpt-4-turbo
    role: "Documentation and knowledge management"
    context_depth: 4
    max_tokens_per_interaction: 5000
    specializations: [documentation, examples, tutorials]

AI-Human Handoff Protocols

Clear handoff documentation:

## 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]*

Token Budget Strategies

Epic-Level Token Allocation:

## Token Budget: EPIC-001 (User Authentication)

### Total Budget: 50,000 tokens
### Allocation Strategy:

**Phase 1: Analysis & Planning (20% - 10,000 tokens)**
- Requirements analysis: 3,000 tokens
- Architecture design: 4,000 tokens  
- Security planning: 2,000 tokens
- Test planning: 1,000 tokens

**Phase 2: Implementation Support (50% - 25,000 tokens)**
- Code generation assistance: 15,000 tokens
- Debugging and troubleshooting: 8,000 tokens
- Optimization suggestions: 2,000 tokens

**Phase 3: Review & Quality (20% - 10,000 tokens)**
- Code review: 6,000 tokens
- Security audit: 3,000 tokens
- Performance optimization: 1,000 tokens

**Phase 4: Documentation (10% - 5,000 tokens)**
- Technical documentation: 3,000 tokens
- User guides: 1,500 tokens
- Knowledge transfer: 500 tokens

### Current Usage: 12,847 tokens (25.7%)
### Remaining: 37,153 tokens
### Burn Rate: On track for planned completion

🔄 Git Workflow Integration

Branch Naming Conventions

Consistent patterns for AI and human collaboration:

# Feature branches
feature/ISSUE-001-oauth2-login
feature/TASK-042-oauth-button-component

# Bug fixes
bugfix/ISSUE-123-oauth-callback-error
bugfix/TASK-456-button-loading-state

# Epic branches (for major features)
epic/EPIC-001-user-authentication

# AI-specific branches (for AI-generated code)
ai/claude/ISSUE-001-oauth-implementation
ai/gpt4/TASK-042-component-optimization

# Review branches (for human review of AI work)
review/ai-claude-ISSUE-001
review/human-feedback-TASK-042

Commit Message Standards

AI-trackable commit messages:

# Include task references and AI attribution
feat(ISSUE-001): implement OAuth2 Google integration

# AI-generated commits
feat(ISSUE-001): implement OAuth strategies (ai: claude)
refactor(TASK-042): optimize button component (ai: gpt4)

# Human commits  
feat(ISSUE-001): configure OAuth environment variables (human: @developer)
test(TASK-042): add accessibility tests (human: @qa-engineer)

# Collaboration commits
fix(ISSUE-001): resolve OAuth callback bug (ai: claude, human: @developer)

# Token tracking in commits
feat(ISSUE-001): complete OAuth implementation
Token-Usage: claude=1247, gpt4=355
AI-Context: OAuth2 flow implementation, security review completed

Git Hooks for AI Track Down

Automated task management:

#!/bin/bash
# .git/hooks/post-commit

# Extract task references from commit message
COMMIT_MSG=$(git log -1 --pretty=%B)
TASK_REFS=$(echo "$COMMIT_MSG" | grep -oE "(EPIC|ISSUE|TASK)-[0-9]+")

# Update task status based on commit keywords
if echo "$COMMIT_MSG" | grep -q "^feat\|^fix\|^close"; then
    for TASK_REF in $TASK_REFS; do
        echo "Updating $TASK_REF status to in-review"
        # Manual update reminder
        echo "Remember to update $TASK_REF status in task file"
    done
fi

# Track token usage from commit message
if echo "$COMMIT_MSG" | grep -q "Token-Usage:"; then
    TOKEN_INFO=$(echo "$COMMIT_MSG" | grep "Token-Usage:" | sed 's/Token-Usage: //')
    echo "Token usage recorded: $TOKEN_INFO"
    echo "Remember to update token usage in task files"
fi

📊 Monitoring and Analytics

Token Usage Optimization

Weekly token review process:

# Generate comprehensive token report
grep -r "token_usage:" tasks/ > weekly-token-report.txt

# Identify high-cost operations
grep -B 5 -A 5 "total: [5-9][0-9][0-9][0-9]" tasks/**/*.md

# Analyze by agent
grep -r "by_agent:" tasks/ | cut -d: -f3- | sort

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

Token efficiency metrics to track:

Cost per story point: Total tokens ÷ completed story points
Agent efficiency: Value delivered ÷ tokens consumed by agent
Context optimization: Token reduction through better context
Reuse ratio: How often AI context gets reused vs regenerated

Project Health Monitoring

Daily health check:

#!/bin/bash
# scripts/daily-health-check.sh

echo "# AI Track Down Daily Health Report"
echo "Generated: $(date)"
echo

# Overall project status
echo "## Project Status"
head -20 AI-TRACKDOWN.md

# Epic progress
echo "## Epic Progress"
grep -B 2 -A 5 "status.*progress" tasks/epics/*.md

# Token budget status
echo "## Token Budget Status"
grep -A 5 "token_usage:" tasks/epics/*.md

# Blockers and risks
echo "## Blockers and Risks"
grep -B 2 -A 2 "status: blocked" tasks/**/*.md

# AI agent activity
echo "## AI Agent Activity (Last 24h)"
find tasks/ -name "*.md" -mtime -1 -exec grep -l "by_agent:" {} \;

# Quality metrics
echo "## Quality Metrics"
echo "Tasks completed today: $(find tasks/ -name "*.md" -mtime -1 -exec grep -l "status: done" {} \; | wc -l)"
echo "Active issues: $(grep -l "status: in-progress" tasks/issues/*.md | wc -l)"
echo "Blocked items: $(grep -l "status: blocked" tasks/**/*.md | wc -l)"

Performance Tracking

Key metrics to monitor:

# Development velocity
echo "Tasks completed this week:"
find tasks/ -name "*.md" -mtime -7 -exec grep -l "status: done" {} \; | wc -l

# AI assistance impact
echo "AI token usage this week:"
find tasks/ -name "*.md" -mtime -7 -exec grep -A 3 "token_usage:" {} \;

# Context effectiveness
echo "AI context blocks:"
grep -c "AI_CONTEXT_START" tasks/**/*.md

# Integration health
echo "Sync status:"
grep -A 3 "Integration Status" AI-TRACKDOWN.md

🎯 Team Collaboration Patterns

Role-Based Access Patterns

Define clear responsibilities:

# .ai-trackdown/team-roles.yaml
roles:
  product_owner:
    permissions: [create_epic, update_epic, set_priority, manage_budget]
    epic_ownership: true
    token_budget_authority: true
    
  tech_lead:
    permissions: [create_issue, update_issue, assign_tasks, review_architecture]
    ai_agent_permissions: [architect, reviewer]
    code_review_authority: true
    
  developer:
    permissions: [create_task, update_task, self_assign, track_tokens]
    ai_agent_permissions: [implementer, documenter]
    own_work_only: true
    
  ai_agent:
    permissions: [read_all, comment, suggest, track_own_tokens]
    rate_limits: true
    budget_constraints: true
    human_oversight_required: true

Collaboration Workflows

Epic Planning Workshop:

Product Owner creates epic with business context
Tech Lead adds technical analysis using AI architect
Team breaks down epic into issues collaboratively
AI Agent provides implementation suggestions and estimates
Product Owner sets token budgets and priorities

Daily Development Cycle:

Developer selects task and updates status to in-progress
AI Agent provides implementation guidance and code suggestions
Developer implements with AI assistance, tracking tokens
AI Agent reviews code and suggests optimizations
Tech Lead approves and merges, task moves to done

Sprint Review:

Team reviews completed work and AI agent contributions
Product Owner evaluates token ROI and budget efficiency
Tech Lead analyzes AI-human collaboration effectiveness
Team adjusts processes based on lessons learned

Communication Protocols

AI Agent Integration:

## AI Agent Communication Guidelines

### When to Involve AI Agents
✅ **Good use cases:**
- Requirements analysis and breakdown
- Architecture design and review
- Code implementation assistance
- Documentation generation
- Test case planning

❌ **Avoid for:**
- Sensitive business decisions
- Personnel or budget discussions
- Customer communications
- Legal or compliance matters

### AI Agent Interaction Patterns

**Request Pattern:**

@ai-architect Please analyze ISSUE-001 and suggest implementation approach. Context: OAuth2 integration for social login Requirements: Security, performance, maintainability Budget: 2000 tokens


**Response Pattern:**

Analysis: ISSUE-001 OAuth2 Implementation

Approach: Passport.js with provider-specific strategies Security: PKCE flow + state validation + secure sessions Performance: Redis session store + connection pooling Tokens Used: 487 tokens Confidence: High (92%)

Next Steps: Review approach, then proceed to implementation


### Knowledge Management

**Documentation Standards:**
```markdown
## Documentation Hierarchy

### Level 1: Epic Documentation
- Business context and success criteria
- High-level architecture decisions
- Token budget allocation and tracking
- Cross-epic dependencies

### Level 2: Issue Documentation  
- Detailed requirements and acceptance criteria
- Implementation approach and technical decisions
- AI context blocks with file paths and dependencies
- Token usage and optimization notes

### Level 3: Task Documentation
- Specific implementation details
- Code snippets and examples
- Testing requirements
- Definition of done criteria

### Level 4: Decision Records
- Architectural decisions and rationale
- AI vs human task allocation decisions
- Token optimization strategies
- Process improvement decisions

🚀 Continuous Improvement

Regular Process Reviews

Monthly Retrospective Template:

# AI Track Down Monthly Retrospective

## Metrics Review
- **Velocity**: Story points completed vs planned
- **Token Efficiency**: Cost per story point trend
- **AI Effectiveness**: Human time saved vs token cost
- **Quality**: Bug rate, rework percentage

## What Worked Well
- AI-human collaboration patterns that delivered value
- Token optimization strategies that reduced costs
- Process improvements that increased velocity
- Tool integrations that improved workflow

## What Didn't Work
- AI agent failures or ineffective interactions  
- Token budget overruns and their causes
- Process bottlenecks that slowed delivery
- Integration issues that caused problems

## Lessons Learned
- Best practices discovered this month
- Anti-patterns to avoid going forward
- AI agent optimization opportunities
- Team collaboration improvements

## Action Items
- Process changes to implement
- AI agent training or configuration updates
- Token budget adjustments
- Tool or integration improvements

Optimization Strategies

Continuous Improvement Areas:

Token Efficiency: Regular analysis and optimization
Context Quality: Improving AI context for better results
Workflow Integration: Streamlining human-AI handoffs
Tool Integration: Enhancing external platform sync
Team Collaboration: Refining roles and responsibilities

By following these best practices, teams can maximize the revolutionary potential of AI Track Down while maintaining high development velocity and code quality. The key is treating AI agents as valuable team members with specific strengths and limitations, rather than replacement tools.

Best Practices - bobmatnyc/ai-trackdown GitHub Wiki

Best Practices Guide

🎯 Core Principles

1. AI-First Design

2. Local-First Mindset

3. Token Economics

📝 Task Writing Excellence

Epic Structure Best Practices

Issue Structure Best Practices

API Endpoints

AI Context

Implementation Plan

Phase 1: Backend OAuth Setup (3 days)

Phase 2: Frontend Integration (2 days)

Phase 3: Testing and Security (2 days)

Phase 4: Deployment (1 day)

Related Items

Notes

Token Budget

States to Handle

Files to Create/Modify

AI Context

Acceptance Criteria

Definition of Done

AI-Human Handoff Protocols

Token Budget Strategies

🔄 Git Workflow Integration

Branch Naming Conventions

Commit Message Standards

Git Hooks for AI Track Down

📊 Monitoring and Analytics

Token Usage Optimization

Project Health Monitoring

Performance Tracking

🎯 Team Collaboration Patterns

Role-Based Access Patterns

Collaboration Workflows

Communication Protocols

Analysis: ISSUE-001 OAuth2 Implementation

🚀 Continuous Improvement

Regular Process Reviews

Optimization Strategies