🚨 CRITICAL GUIDELINES

Windows File Path Requirements

MANDATORY: Always Use Backslashes on Windows for File Paths

When using Edit or Write tools on Windows, you MUST use backslashes (
) in file paths, NOT forward slashes (/ ).

Examples:

❌ WRONG: D:/repos/project/file.tsx
✅ CORRECT: D:\repos\project\file.tsx

This applies to:

Edit tool file_path parameter
Write tool file_path parameter
All file operations on Windows systems

Documentation Guidelines

NEVER create new documentation files unless explicitly requested by the user.

Priority: Update existing README.md files rather than creating new documentation
Repository cleanliness: Keep repository root clean - only README.md unless user requests otherwise
Style: Documentation should be concise, direct, and professional - avoid AI-generated tone
User preference: Only create additional .md files when user specifically asks for documentation

GitHub AI Features 2025

Trunk-Based Development (TBD)

Modern workflow used by largest tech companies (Google: 35,000+ developers):

Principles

Short-lived branches: Hours to 1 day maximum
Small, frequent commits: Reduce merge conflicts
Continuous integration: Always deployable main branch
Feature flags: Hide incomplete features

Implementation

Create task branch from main

git checkout main git pull origin main git checkout -b task/add-login-button

Make small changes

git add src/components/LoginButton.tsx git commit -m "feat: add login button component"

Push and create PR (same day)

git push origin task/add-login-button gh pr create --title "Add login button" --body "Implements login UI"

Merge within hours, delete branch

gh pr merge --squash --delete-branch

Benefits

Reduced merge conflicts (75% decrease)
Faster feedback cycles
Easier code reviews (smaller changes)
Always releasable main branch
Simplified CI/CD pipelines

GitHub Secret Protection (AI-Powered)

AI detects secrets before they reach repository:

Push Protection

Attempt to commit secret

git add config.py git commit -m "Add config" git push

GitHub AI detects secret:

""" ⛔ Push blocked by secret scanning

Found: AWS Access Key Pattern: AKIA[0-9A-Z]{16} File: config.py:12

Options:

Remove secret and try again
Mark as false positive (requires justification)
Request review from admin """

Fix: Use environment variables

config.py

import os aws_key = os.environ.get('AWS_ACCESS_KEY')

git add config.py git commit -m "Use env vars for secrets" git push # ✅ Success

Supported Secret Types (AI-Enhanced)

AWS credentials
Azure service principals
Google Cloud keys
GitHub tokens
Database connection strings
API keys (OpenAI, Stripe, etc.)
Private keys (SSH, TLS)
OAuth tokens
Custom patterns (regex-based)

GitHub Code Security

CodeQL Code Scanning

AI-powered static analysis:

.github/workflows/codeql.yml

on: push: branches: [ main ] pull_request: branches: [ main ]

jobs: analyze: runs-on: ubuntu-latest permissions: security-events: write

steps:
- name: Checkout
  uses: actions/checkout@v3

- name: Initialize CodeQL
  uses: github/codeql-action/init@v2
  with:
    languages: javascript, python, java

- name: Autobuild
  uses: github/codeql-action/autobuild@v2

- name: Perform CodeQL Analysis
  uses: github/codeql-action/analyze@v2

Detects:

SQL injection
XSS vulnerabilities
Path traversal
Command injection
Insecure deserialization
Authentication bypass
Logic errors

Copilot Autofix

AI automatically fixes security vulnerabilities:

Vulnerable code detected by CodeQL

def get_user(user_id): query = f"SELECT * FROM users WHERE id = {user_id}" # ❌ SQL injection return db.execute(query)

Copilot Autofix suggests:

def get_user(user_id): query = "SELECT * FROM users WHERE id = ?" return db.execute(query, (user_id,)) # ✅ Parameterized query

One-click to apply fix

GitHub Agents (Automated Workflows)

AI agents for automated bug fixes and PR generation:

Bug Fix Agent

.github/workflows/ai-bugfix.yml

on: issues: types: [labeled]

jobs: autofix: if: contains(github.event.issue.labels.*.name, 'bug') runs-on: ubuntu-latest steps: - uses: actions/checkout@v3

- name: Analyze Bug
  uses: github/ai-agent@v1
  with:
    task: 'analyze-bug'
    issue-number: ${{ github.event.issue.number }}

- name: Generate Fix
  uses: github/ai-agent@v1
  with:
    task: 'generate-fix'
    create-pr: true
    pr-title: "Fix: ${{ github.event.issue.title }}"

Automated PR Generation

GitHub Agent creates PR automatically

When issue is labeled "enhancement":

1. Analyzes issue description

2. Generates implementation code

3. Creates tests

4. Opens PR with explanation

Example: Issue #42 "Add dark mode toggle"

Agent creates PR with:

- DarkModeToggle.tsx component

- ThemeContext.tsx provider

- Tests for theme switching

- Documentation update

Dependency Review (AI-Enhanced)

AI analyzes dependency changes in PRs:

.github/workflows/dependency-review.yml

on: [pull_request]

permissions: contents: read

jobs: dependency-review: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v3

- name: Dependency Review
  uses: actions/dependency-review-action@v3
  with:
    fail-on-severity: high
    fail-on-scopes: runtime

AI Insights:

Known vulnerabilities in new dependencies
License compliance issues
Breaking changes in updates
Alternative safer packages
Dependency freshness score

Trunk-Based Development Workflow

Daily Workflow

Morning: Sync with main

git checkout main git pull origin main

Create task branch

git checkout -b task/user-profile-api

Work in small iterations (2-4 hours)

First iteration: API endpoint

git add src/api/profile.ts git commit -m "feat: add profile API endpoint" git push origin task/user-profile-api gh pr create --title "Add user profile API" --draft

Continue work: Add tests

git add tests/profile.test.ts git commit -m "test: add profile API tests" git push

Mark ready for review

gh pr ready

Get review (should happen within hours)

Merge same day

gh pr merge --squash --delete-branch

Next task: Start fresh from main

git checkout main git pull origin main git checkout -b task/profile-ui

Small, Frequent Commits Pattern

❌ Bad: Large infrequent commit

git add . git commit -m "Add complete user profile feature with API, UI, tests, docs"

50 files changed, 2000 lines

✅ Good: Small frequent commits

git add src/api/profile.ts git commit -m "feat: add profile API endpoint" git push

git add src/components/ProfileCard.tsx git commit -m "feat: add profile card component" git push

git add tests/profile.test.ts git commit -m "test: add profile tests" git push

git add docs/profile.md git commit -m "docs: document profile API" git push

Each commit: 1-3 files, 50-200 lines

Easier reviews, faster merges, less conflicts

Security Best Practices (2025)

Enable Secret Scanning:

Repository Settings → Security → Secret scanning

Enable: Push protection + AI detection

Configure CodeQL:

Add .github/workflows/codeql.yml

Enable for all languages in project

Use Copilot Autofix:

Review security alerts weekly

Apply Copilot-suggested fixes

Test before merging

Implement Trunk-Based Development:

Branch lifespan: <1 day

Commit frequency: Every 2-4 hours

Main branch: Always deployable

Leverage GitHub Agents:

Automate: Bug triage, PR creation, dependency updates

Review: All AI-generated code before merging

Resources

Trunk-Based Development
GitHub Secret Scanning
GitHub Advanced Security
GitHub Copilot for Security