[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 ATTENTION ask user whether to skip.Prerequisites: MUST ATTENTION READ before executing:
Scan & Update Reference Doc — Surgical updates only, never full rewrite. 1. Read existing doc first — understand current structure and manual annotations 2. Detect mode: Placeholder (only headings, no content) → Init mode. Has content → Sync mode. 3. Scan codebase for current state (grep/glob for patterns, counts, file paths) 4. Diff findings vs doc content — identify stale sections only 5. Update ONLY sections where code diverged from doc. Preserve manual annotations. 6. Update metadata (date, counts, version) in frontmatter or header 7. NEVER rewrite entire doc. NEVER remove sections without evidence they're obsolete.
Output Quality — Token efficiency without sacrificing quality. 1. No inventories/counts — AI cangrep | wc -l. Counts go stale instantly 2. No directory trees — AI canglob/ls. Use 1-line path conventions 3. No TOCs — AI reads linearly. TOC wastes tokens 4. No examples that repeat what rules say — one example only if non-obvious 5. Lead with answer, not reasoning. Skip filler words and preamble 6. Sacrifice grammar for concision in reports 7. Unresolved questions at end, if any
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.jsonfor 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.jsonfor 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.jsondependencies,.csprojPackageReferences, build tool configs
Phase 2: Execute Scan (Parallel Sub-Agents)
Launch 3 Explore agents in parallel:
Agent 1: Backend Services
- Glob for
**/*.csprojand**/Dockerfileto find services - Grep
launchSettings.jsonorappsettings*.jsonfor port numbers - Grep for
[ApiController]orMapControllersto 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 (
servecommands, 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
Closing Reminders
- IMPORTANT MUST ATTENTION break work into small todo tasks using
TaskCreateBEFORE starting - IMPORTANT MUST ATTENTION search codebase for 3+ similar patterns before creating new code
- IMPORTANT MUST ATTENTION cite
file:lineevidence for every claim (confidence >80% to act) - IMPORTANT MUST ATTENTION add a final review todo task to verify work quality MANDATORY IMPORTANT MUST ATTENTION READ the following before starting:
- IMPORTANT MUST ATTENTION read existing doc first, scan codebase, diff, surgical update only. Never rewrite entire doc.
- IMPORTANT MUST ATTENTION follow output quality rules: no counts/trees/TOCs, rules > descriptions, 1 example per pattern, primacy-recency anchoring.