learning_ai_common_plat/AI.dev/SKILLS/scan-repo-context.md

Scan Repo & Update Context Skill

Description: Scan entire repository and generate comprehensive context documentation for AI assistants.

When to Use

• Onboarding new AI assistants or developers
• After major architectural changes
• Creating project documentation
• Setting up Windsurf/Cursor/other AI tools

Prerequisites

• Full repository access
• Read permissions on all files
• Understanding of project structure

Quick Start

# From repo root
/.windsurf/workflows/scan-repo-and-update-windsurf-context.md

Or run the workflow directly if supported:

/windsurf-workflow scan-repo-and-update-windsurf-context

Scanning Process

Phase 1: Read Key Documentation

Start with high-level understanding:

# Core documentation files
cat AGENTS.md                    # AI agent guide (single per-repo source)
cat README.md                    # Project overview
cat ARCHITECTURE.md              # Technical architecture
cat CONTRIBUTING.md              # Contribution guidelines
cat ../learning_ai_common_plat/AI.dev/SKILLS/agent-behavior-guidelines.md
                                 # Ecosystem-wide agent behavior rules

Phase 2: Understand Project Structure

Scan directory structure:

# Get overview
find . -type d -maxdepth 2 | sort

# Key source directories
find . -name "src" -type d
find . -name "lib" -type d
find . -name "components" -type d
find . -name "modules" -type d

# Configuration files
find . -name "package.json" -o -name "Cargo.toml" -o -name "pom.xml" -o -name "build.gradle*"

Phase 3: Analyze Code Organization

For each major component:

# List key files
ls -la src/
ls -la lib/
ls -la components/

# Find main entry points
find . -name "main.*" -o -name "index.*" -o -name "App.*"

# Find configuration
find . -name "*.config.*" -o -name "*.env*" -o -name "settings.*"

Phase 4: Identify Patterns

Look for common patterns:

# API routes
find . -path "*/api/*" -name "*.js" -o -name "*.ts" -o -name "*.py"

# Database models
find . -name "*model*" -o -name "*schema*" -o -name "*entity*"

# Test files
find . -name "*test*" -o -name "*spec*"

# Documentation
find . -name "*.md" -o -name "*.rst" -o -name "*.txt"

Generating Context Documentation

Structure Template

# [PROJECT_NAME] Context Documentation

> Auto-generated on: YYYY-MM-DD HH:MM
> Regenerate with: /scan-repo-and-update-windsurf-context

## Project Summary

[Brief 1-paragraph description of the project]

## Architecture

[High-level architecture overview]

## Module Map

| Module | Purpose                        | Key Files              |
| ------ | ------------------------------ | ---------------------- |
| auth   | Authentication & authorization | src/auth/, lib/auth.js |
| api    | REST API endpoints             | src/api/, routes/      |
| db     | Database layer                 | src/db/, models/       |

## Technology Stack

- **Frontend**: [Framework], [Language]
- **Backend**: [Framework], [Language]
- **Database**: [Database type]
- **Deployment**: [Platform]

## Key Directories

project-root/ ├── src/ # Main source code ├── tests/ # Test files ├── docs/ # Documentation ├── config/ # Configuration files └── scripts/ # Build/utility scripts

## Important Files
| File | Purpose |
|------|---------|
| package.json | Dependencies and scripts |
| .env.example | Environment variables template |
| docker-compose.yml | Container orchestration |
| README.md | Project documentation |

## Development Workflow
1. Setup: [Setup instructions]
2. Development: [How to run locally]
3. Testing: [How to run tests]
4. Deployment: [How to deploy]

## Common Commands
```bash
# Install dependencies
npm install

# Run development server
npm run dev

# Run tests
npm test

# Build for production
npm run build

Coding Conventions

• File naming: [Pattern]
• Commit messages: [Format]

API Endpoints

Method	Path	Purpose
GET	/api/health	Health check
POST	/api/auth/login	User login

Database Schema

[Key tables/collections and relationships]

Environment Variables

Variable	Required?	Description
API_KEY	Yes	External API key
DB_URL	Yes	Database connection

Troubleshooting

Common Issues

1. Problem: Solution
2. Problem: Solution

Debug Commands

# Check logs
tail -f logs/app.log

# Debug mode
DEBUG=1 npm run dev

## Implementation for Different Project Types

### JavaScript/TypeScript Project

```bash
# Scan package.json for dependencies
cat package.json | jq '.dependencies, .devDependencies'

# Find TypeScript config
find . -name "tsconfig.json"

# Check for framework-specific files
ls next.config.js webpack.config.js vite.config.js

Python Project

# Check requirements
cat requirements.txt pyproject.toml setup.py

# Find Python modules
find . -name "__init__.py" | head -20

# Check for Django/Flask
ls manage.py app.py wsgi.py

Mobile Project (React Native)

# Check React Native config
cat package.json | jq '.dependencies | keys | map(select(contains("react-native")))'

# Find platform-specific code
ls android/ ios/

# Check for native modules
ls android/app/src/main/java/ ios/YourApp/

Java/Kotlin Project

# Check Gradle configuration
cat build.gradle settings.gradle gradle.properties

# Find main source directory
find . -name "src/main/java"

# Check for Spring Boot
ls src/main/resources/application*.yml

Automation Script

Create scripts/generate-context.sh:

#!/bin/bash
# Generate context documentation

echo "Scanning repository..."
PROJECT_NAME=$(basename $(pwd))
OUTPUT_FILE="WINDSURF_CONTEXT.md"

# Header
cat > $OUTPUT_FILE << EOF
# $PROJECT_NAME Context Documentation

> Auto-generated on: $(date)
> Regenerate with: /scan-repo-and-update-windsurf-context

EOF

# Project summary
if [ -f "README.md" ]; then
    echo "## Project Summary" >> $OUTPUT_FILE
    head -20 README.md >> $OUTPUT_FILE
    echo "" >> $OUTPUT_FILE
fi

# Directory structure
echo "## Directory Structure" >> $OUTPUT_FILE
echo '```' >> $OUTPUT_FILE
tree -L 2 -I 'node_modules|.git|dist|build' >> $OUTPUT_FILE
echo '```' >> $OUTPUT_FILE
echo "" >> $OUTPUT_FILE

# Dependencies
if [ -f "package.json" ]; then
    echo "## Dependencies" >> $OUTPUT_FILE
    echo '```json' >> $OUTPUT_FILE
    cat package.json | jq '.dependencies' >> $OUTPUT_FILE
    echo '```' >> $OUTPUT_FILE
fi

echo "Context documentation generated: $OUTPUT_FILE"

Best Practices

What to Include

1. Project purpose - What does this project do?
2. Architecture - How is it structured?
3. Key components - Main modules and their purpose
4. Development setup - How to get started
5. Common tasks - Frequently used commands
6. Important patterns - Coding conventions
7. Troubleshooting - Common issues and solutions

What to Exclude

1. Sensitive data - Never include real keys/passwords
2. Temporary files - build/, dist/, node_modules/
3. Personal notes - Keep it professional
4. Outdated information - Keep it current

Formatting Tips

1. Use consistent formatting - Markdown tables, code blocks
2. Include examples - Show, don't just tell
3. Cross-reference - Link to related sections
4. Keep it scannable - Use headings, lists, bold text

Integration with AI Tools

Windsurf

The generated WINDSURF_CONTEXT.md is automatically picked up by Windsurf.

Cursor / Windsurf / Claude Code / Codex / Cline

These agents all read AGENTS.md at the repo root. Add references to WINDSURF_CONTEXT.md (or equivalent) inside AGENTS.md so every agent sees it. Do not create per-tool config files (.cursorrules, .windsurfrules, .clinerules, CLAUDE.md) — they are deprecated in favour of the canonical pointer architecture (see learning_ai_common_plat/.windsurf/workflows/repo_update-agent-docs.md).

GitHub Copilot

Include in .github/copilot-instructions.md:

## Project Context

See WINDSURF_CONTEXT.md for full project understanding

Maintenance

When to Update

• After major feature additions
• When architecture changes
• On regular schedule (monthly/quarterly)
• When new developers join

Version Control

# Commit generated context
git add WINDSURF_CONTEXT.md
git commit -m "docs: update AI context documentation"
git push

Notes

• Keep it current - Outdated context is worse than no context
• Be comprehensive - Include everything a new developer would need
• Use examples - Concrete examples are more helpful than abstract descriptions
• Review regularly - Ensure accuracy and completeness

Related Skills

• Agent Behavior Guidelines - Canonical agent rules
• Agent Onboarding - Read-order index for agents
• Architecture Patterns - Understanding architecture
• Local Development Setup - Setting up to work
• Documentation Standards - Writing good docs