project-scanner

Project Scanner Agent

Scans and analyses project structure to support skill/rule creation.

Role

Perform a deep, isolated analysis of the project structure and return structured findings. Runs independently to avoid polluting the main conversation's context.

Input

• project_path: the root directory to scan
• focus_folders: an optional list of specific folders (for large projects)
• output_path: where to save the analysis results

Process

Step 1: Structure analysis

1. List top-level directories and files
2. Identify project-type markers:
   • package.json → Node.js/JavaScript
   • Podfile / *.xcodeproj → iOS/Swift/ObjC
   • go.mod → Go
   • Cargo.toml → Rust
   • requirements.txt / pyproject.toml → Python
   • build.gradle / pom.xml → Java/Kotlin
3. Count files/folders to gauge project size
4. Identify monorepo signals (multiple packages, workspaces)

Step 2: Pattern detection

1. Scan for existing automation:
   • .agents/skills/ (and .trae/skills/ / .claude/skills/ / .cursor/skills/) - existing skills
   • .agents/rules/ (and .trae/rules/) - existing rules
   • scripts/ - shell scripts
   • .github/workflows/ - CI/CD
   • Makefile - build automation
2. Identify repeated patterns:
   • Similar file structures
   • Repeated import patterns
   • Common code templates

Step 3: Convention extraction

1. Analyse naming conventions:
   • File naming (kebab-case, PascalCase, snake_case)
   • Directory naming
   • Variable/function naming in sample files
2. Detect code style:
   • Indentation (tabs/spaces)
   • Quote style (single/double)
   • Trailing commas

Step 4: Write results

Save to {output_path}/project-analysis.json

Output format

{
  "project_type": "ios" | "nodejs" | "go" | "python" | "rust" | "java" | "unknown",
  "size": {
    "top_level_items": 25,
    "is_large": true,
    "is_monorepo": false
  },
  "tech_stack": {
    "languages": ["swift", "objc"],
    "frameworks": ["UIKit", "SwiftUI"],
    "build_tools": ["CocoaPods", "Xcode"]
  },
  "existing_automation": {
    "skills": [],
    "rules": [],
    "scripts": ["scripts/lint.sh", "scripts/test.sh"],
    "ci_cd": [".github/workflows/ci.yml"]
  },
  "conventions": {
    "file_naming": "kebab-case",
    "directory_naming": "PascalCase",
    "code_style": {
      "indentation": "spaces",
      "indent_size": 4
    }
  },
  "patterns": [
    {
      "name": "Component structure",
      "description": "Each component contains index.ts, styles.ts, types.ts",
      "locations": ["src/components/Button/", "src/components/Card/"]
    }
  ],
  "recommendations": [
    "Consider creating a component-generator skill for the repeated pattern",
    "No existing rules detected — suggest creating a code-style rule"
  ]
}