[IMPORTANT] Use TaskCreate to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ask user whether to skip.

Prerequisites: MUST READ before executing:

• .claude/skills/shared/scan-and-update-reference-doc-protocol.md

• .claude/skills/shared/understand-code-first-protocol.md

Quick Summary

Goal: Scan the project codebase and populate docs/project-reference/project-structure-reference.md with accurate service architecture, API ports, directory tree, tech stack, and module codes.

Workflow:

• Read — Load current target doc, detect init vs sync mode

• Scan — Discover services, apps, ports, tech stack via parallel sub-agents

• Report — Write findings to external report file

• Generate — Build/update the reference doc from report

• Verify — Spot-check paths and ports

Key Rules:

• Generic — discover everything dynamically, never hardcode project-specific values

• Use docs/project-config.json for hints if available, fall back to filesystem scanning

• All examples must reference real files found in this project

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).

Scan Project Structure

Phase 0: Read & Assess

• Read docs/project-reference/project-structure-reference.md

• Detect mode: init (placeholder only) or sync (has real content)

• If sync: note which sections exist and their line counts

Phase 1: Plan Scan Strategy

Check if docs/project-config.json exists for module lists and service maps. Plan these scan areas:

• Backend services — Find .csproj , Dockerfile , Program.cs , launchSettings.json for ports

• Frontend apps — Find angular.json , nx.json , package.json , vite.config , next.config

• Infrastructure — Find docker-compose.yml , Dockerfile , K8s manifests, CI/CD config

• Tech stack — Parse package.json dependencies, .csproj PackageReferences, build tool configs

Phase 2: Execute Scan (Parallel Sub-Agents)

Launch 3 Explore agents in parallel:

Agent 1: Backend Services

• Glob for **/*.csproj and **/Dockerfile to find services

• Grep launchSettings.json or appsettings*.json for port numbers

• Grep for [ApiController] or MapControllers to find API services

• List service directories with their ports

Agent 2: Frontend Apps

• Glob for **/angular.json , **/nx.json , **/package.json (not in node_modules)

• Find app entry points (main.ts , index.tsx , App.vue )

• Extract dev server ports from configs (serve commands, proxy configs)

• Identify framework versions from package.json

Agent 3: Infrastructure & Tech Stack

• Find docker-compose*.yml — extract service definitions and port mappings

• Find CI/CD configs (.github/workflows/*.yml , azure-pipelines.yml , Jenkinsfile )

• Parse primary package managers (package.json , *.csproj ) for key dependencies

• Identify databases, message brokers, caching from connection strings or Docker services

Write all findings to: plans/reports/scan-project-structure-{YYMMDD}-{HHMM}-report.md

Phase 3: Analyze & Generate

Read the report file. Build these sections:

Target Sections

Section Content

Service Architecture Table: Service Name, Type (API/Worker/App), Port, Dockerfile path

Infrastructure Ports Table: Service (DB/MQ/Cache), Port, Credentials (if in docker-compose)

API Service Ports Table: API service name, Port, Dockerfile path

Project Directory Tree Top 2-3 levels of src/ directory structure

Tech Stack Table: Category (Backend/Frontend/Infra), Technology, Version

Module Codes Table: Module code abbreviation, Full name, Service path

Content Rules

• Use tables for structured data (not prose)

• Include actual port numbers found in configs

• Directory tree: show only meaningful structure (skip node_modules, bin, obj)

• Tech stack: include version numbers from package.json/csproj

Phase 4: Write & Verify

• Write updated doc with <!-- Last scanned: YYYY-MM-DD --> at top

• Verify: spot-check 3 service paths exist on filesystem

• Verify: port numbers match actual config files

• Report: sections updated vs unchanged

IMPORTANT Task Planning Notes (MUST FOLLOW)

• Always plan and break work into many small todo tasks using TaskCreate

• Always add a final review todo task to verify work quality and identify fixes/enhancements