EasyPlatform project-config

[IMPORTANT] Use

TaskCreate

to break ALL work into small tasks BEFORE starting.

Critical Thinking Mindset — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. Anti-hallucination: Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination.

AI Mistake Prevention — Failure modes to avoid on every task:

• Check downstream references before deleting. Deleting components causes documentation and code staleness cascades. Map all referencing files before removal.
• Verify AI-generated content against actual code. AI hallucinates APIs, class names, and method signatures. Always grep to confirm existence before documenting or referencing.
• Trace full dependency chain after edits. Changing a definition misses downstream variables and consumers derived from it. Always trace the full chain.
• Trace ALL code paths when verifying correctness. Confirming code exists is not confirming it executes. Always trace early exits, error branches, and conditional skips — not just happy path.
• When debugging, ask "whose responsibility?" before fixing. Trace whether bug is in caller (wrong data) or callee (wrong handling). Fix at responsible layer — never patch symptom site.
• Assume existing values are intentional — ask WHY before changing. Before changing any constant, limit, flag, or pattern: read comments, check git blame, examine surrounding code.
• Verify ALL affected outputs, not just the first. Changes touching multiple stacks require verifying EVERY output. One green check is not all green checks.
• Holistic-first debugging — resist nearest-attention trap. When investigating any failure, list EVERY precondition first (config, env vars, DB names, endpoints, DI registrations, data preconditions), then verify each against evidence before forming any code-layer hypothesis.
• Surgical changes — apply the diff test. Bug fix: every changed line must trace directly to the bug. Don't restyle or improve adjacent code. Enhancement task: implement improvements AND announce them explicitly.
• Surface ambiguity before coding — don't pick silently. If request has multiple interpretations, present each with effort estimate and ask. Never assume all-records, file-based, or more complex path.

Quick Summary

Goal: Scan the project workspace and update

docs/project-config.json

IMPORTANT MUST ATTENTION follow Plan → Review → Execute workflow. IMPORTANT MUST ATTENTION use exact schema field names (

--describe

classPattern

keyExtractor

contentPattern

keyGroup

Workflow: Recon →

/plan

/plan-review

/prompt-enhance

Key Rules:

• MUST ATTENTION run

  node .claude/hooks/lib/project-config-schema.cjs --describe

  and use field names verbatim
• MUST ATTENTION create one TaskCreate per config section — NEVER scan everything in one pass
• MUST ATTENTION validate schema after each merge —

  validateConfig(config)

  returns PASSED or errors
• MUST ATTENTION review-and-fix after each phase — read back, spot-check paths, self-review
• Path regexes MUST ATTENTION use

  [\\/]

  for cross-platform separator matching
• Schema enforced by

  .claude/hooks/lib/project-config-schema.cjs

⛔ Plan → Review → Execute Workflow

Step 1: Quick Reconnaissance

find src/ -name "*.csproj" 2>/dev/null | wc -l
find src/ -name "package.json" -not -path "*/node_modules/*" 2>/dev/null | wc -l
find src/ -name "*.cs" 2>/dev/null | wc -l
ls -d src/*/ 2>/dev/null

Step 2: Create Plan (

/plan

)

Create

plans/{date}-project-config-scan.md

1. Assess scale — small (<5), medium (5-20), large (20+)
2. Group config sections into phases (≤5 tasks each)
3. Include review-and-fix cycle after each phase

Phase template:

Phase A: Setup & Metadata — validate config, read schema, scan project metadata
Phase B: Module Discovery — backend projects, frontend apps/libs, framework keywords
Phase C: Context & UI — context groups, design system, styling, component system
Phase D: Testing & Infra — testing, E2E, databases, messaging, API, infrastructure
Phase E: Graph Connectors — API endpoints, implicit connections, referenceDocs
Phase F: Final Review — consolidate, validate, hook tests, create /scan-* tasks
Phase G: Self-Review — re-invoke /project-config to verify all config matches source code

For small projects: Ask user to combine into single pass.

Step 3: Review Plan (

/plan-review

)

Step 4: Execute

Per phase: TaskCreate → scan → merge → validate → spot-check → fix → next phase.

Review-and-Fix Cycle (MANDATORY per phase)

1. Read back updated config sections
2. Spot-check 2-3 paths against actual directories
3. Run schema validation
4. Self-review: "Missing modules? Accurate descriptions? Correct regexes?"
5. Fix before proceeding

Intermediate Workspace

For medium/large projects:

mkdir -p .ai/workspace/project-config

⛔ Schema Protection Rules

DO NOT rename/remove/restructure top-level sections. DO NOT change field types. DO NOT populate deprecated v1 sections for new projects. DO NOT remove v1 data from existing projects.

You MAY add entries to maps/arrays, update values, add optional schema fields, populate v2 sections.

Schema Structure (v2)

docs/project-config.json
├── schemaVersion, project{ name, description, languages[], packageManagers[], monorepoTool }
├── modules[] — { name, kind, pathRegex, description, tags[], meta{} }
├── contextGroups[] — { name, pathRegexes[], fileExtensions[], guideDoc, patternsDoc, stylingDoc, designSystemDoc, rules[] }
├── styling — { technology, guideDoc, appMap{}, patterns[] }
├── designSystem — { docsPath, modernUiNote, appMappings[] }
├── componentSystem — { type, selectorPrefixes[], filePattern, layerClassification{} }
├── framework — { name, backendPatternsDoc, frontendPatternsDoc, codeReviewDoc, integrationTestDoc, searchPatternKeywords[] }
├── testing — { frameworks[], filePatterns{}, commands{}, coverageTool, guideDoc }
├── e2eTesting — { framework, language, configFile, testsPath, pageObjectsPath, fixturesPath, ... }
├── databases{}, messaging{ broker, patterns[], consumerConvention }, api{ style, docsFormat, docsPath, authPattern }
├── infrastructure — { containerization, orchestration, cicd{ tool, configPath } }
├── graphConnectors — apiEndpoints{ enabled, frontend{ framework, paths[] }, backend{ framework, paths[], routePrefix } }
│   └── implicitConnections[] — { name, edgeKind, paths[], source{ filePattern, contentPattern, keyGroup }, target{...}, matchBy }
├── referenceDocs[] — { filename, purpose, sections[] }
├── integrationTestVerify — { guidance, quickRunCommand, testProjectPattern, testProjects[], systemCheckCommand, runScript, startupScript }
├── workflowPatterns — { architectureStyle, codeHierarchy, cssMethodology, stateManagement, crossModuleValidation, featureDocPath, featureDocTemplate, reviewRulesDoc }
└── DEPRECATED: backendServices, frontendApps, scss, componentFinder, sharedNamespace

MUST ATTENTION run

node .claude/hooks/lib/project-config-schema.cjs --describe

for exact field names.

⛔ Common AI Field Name Mistakes

classPattern

pattern

regex

contentPattern

keyExtractor

captureGroup

keyGroup

pathRegex

pathRegexes

designDoc

doc

docFile

name

file

filename

examples

scssExamples

"exact"

"contains"

"key-equals"

"key-contains"

glob

fileGlob

filePattern

Phase 0: Setup

# 0a. Validate current config
node -e "const{validateConfig,formatResult}=require('./.claude/hooks/lib/project-config-schema.cjs');const c=JSON.parse(require('fs').readFileSync('docs/project-config.json','utf-8'));console.log(formatResult(validateConfig(c)))"

# 0b. Read exact schema shapes (MANDATORY)
node .claude/hooks/lib/project-config-schema.cjs --describe

# 0c. Check CLAUDE.md
test -f CLAUDE.md && echo "EXISTS" || echo "MISSING"

# 0d. Create workspace
mkdir -p .ai/workspace/project-config

Phase 1: Read Current Config

Read

docs/project-config.json

Phase 2: Section-by-Section Scans

Each subsection = one TaskCreate. Per task: investigate → report → merge → validate.

2a. Modules — Backend

find src/ -name "*.csproj" -maxdepth 5 | head -50          # .NET
find . -name "pom.xml" -o -name "build.gradle" | head -50  # Java
find src/ -name "package.json" -not -path "*/node_modules/*" -maxdepth 4 | head -50  # Node
find . -name "go.mod" | head -50                            # Go

Build

modules[]

{ name, kind, pathRegex, description, tags[], meta{} }

• kind

  :

  "backend-service"

  ,

  "library"

  ,

  "framework"

2b. Modules — Frontend

find . -name "nx.json" -o -name "angular.json" -o -name "lerna.json" -o -name "turbo.json" 2>/dev/null | head -5
ls -d src/*/apps/*/ */apps/*/ apps/*/ 2>/dev/null | head -20
ls -d src/*/libs/*/ */libs/*/ libs/*/ packages/*/ 2>/dev/null | head -30

Build entries with

kind: "frontend-app"

kind: "library"

2c. Project Metadata

Detect languages (

.cs

.ts

.py

.java

.go

project { name, description, languages[], packageManagers[], monorepoTool }

2d. Framework Patterns

Grep for

abstract class

interface I

framework { name, searchPatternKeywords[] }

2e. Context Groups

Build

contextGroups[]

pathRegexes[]

fileExtensions[]

patternsDoc

rules[]

2f–2h. Design System, Styling, Component System

• designSystem { docsPath, modernUiNote, appMappings[] }

• styling { technology, fileExtensions, guideDoc, appMap{}, patterns[] }

• componentSystem { type, selectorPrefixes[], filePattern, layerClassification{} }

2i–2j. Testing & E2E

• testing { frameworks[], filePatterns{}, commands{}, coverageTool, guideDoc }

• e2eTesting { framework, language, configFile, testsPath, pageObjectsPath, fixturesPath, runCommands{}, tcCodeFormat, entryPoints[] }

2k–2n. Databases, Messaging, API, Infrastructure

• databases {}

  (freeform)

• messaging { broker, patterns[], consumerConvention }

• api { style, docsFormat, docsPath, authPattern }

• infrastructure { containerization, orchestration, cicd{ tool, configPath } }

2o. Graph Connectors — API Endpoints

Only if project has BOTH frontend AND backend.

angular

@angular/core

dotnet

.csproj

Microsoft.AspNetCore

react

react

spring

spring-boot-starter-web

vue

vue

express

express

generic

fastapi

fastapi

Route prefix:

"api"

""

2p. Graph Connectors — Implicit Connections

⛔ How implicitConnections Works (MUST ATTENTION UNDERSTAND)

Algorithm: scan source files → extract keys via

contentPattern

keyGroup

matchBy

edgeKind

Exact Schema Fields

name

edgeKind

"MESSAGE_BUS"

"TRIGGERS_EVENT"

"PRODUCES_EVENT"

paths

source

target

{ filePattern, contentPattern, keyGroup }

matchBy

"key-equals"

"key-contains"

source/target fields:

filePattern

"*.cs"

contentPattern

keyGroup

⛔ NEVER use

classPattern

keyExtractor

pattern

contentPattern

keyGroup

Detection Heuristics

• .NET:

  EntityEventApplicationHandler<

  → entity-to-handler;

  EntityEventBusMessageProducer<

  → producer;

  PlatformApplicationMessageBusConsumer<

  → consumer
• TypeScript: Redux dispatch→reducer, NgRx createAction→ofType, EventEmitter emit→on
• Python: Celery task.delay→@app.task, Django signal.send→@receiver
• Java: publishEvent→@EventListener, KafkaTemplate→@KafkaListener

Example (correct format)

{
    "name": "entity-to-event-handlers",
    "edgeKind": "MESSAGE_BUS",
    "paths": ["src/Backend/MyApp.Domain/", "src/Backend/MyApp.Application/UseCaseEvents/"],
    "source": { "filePattern": "*.cs", "contentPattern": "class\\s+(\\w+)\\s*:.*PlatformEntity<", "keyGroup": 1 },
    "target": { "filePattern": "*.cs", "contentPattern": "EntityEventApplicationHandler<(\\w+)", "keyGroup": 1 },
    "matchBy": "key-contains"
}

IMPORTANT MUST ATTENTION present detected rules to user before writing. IMPORTANT MUST ATTENTION scope

paths

2q. Reference Docs

Build

referenceDocs[]

docs/project-reference/

{ filename, purpose, sections[] }

Phase 3: Consolidate & Write

Merge findings section-by-section. Only overwrite if scan found concrete values. Incremental merge recommended for large projects.

Phase 4: Verify (MANDATORY)

1. Schema validation — MUST ATTENTION pass
2. Spot-check 2-3 service paths
3. Run hook tests:

   node .claude/hooks/tests/test-all-hooks.cjs

Phase 5: Follow-Up Tasks

project-structure-reference.md

/scan-project-structure

backend-patterns-reference.md

/scan-backend-patterns

design-system/

scss-styling-guide.md

frontend-patterns-reference.md

/scan-ui-system

integration-test-reference.md

/scan-integration-tests

feature-docs-reference.md

/scan-feature-docs

code-review-rules.md

/scan-code-review-rules

e2e-test-reference.md

/scan-e2e-tests

domain-entities-reference.md

/scan-domain-entities

Then:

/claude-md-init

/graph-build

Phase 6: Enhance Generated Docs (MANDATORY)

Run

/prompt-enhance

CLAUDE.md

Phase 7: Self-Review Verification (MANDATORY)

Re-invoke this skill to verify everything is correct:

/project-config Self review and verify everything again, ensure all is correct with current source code

This ensures any changes made during earlier phases didn't introduce regressions and catches issues missed in the first pass.

Output

Report: sections updated vs unchanged, new modules discovered, path mismatches, follow-up tasks created.

Closing Reminders (AI Attention Anchor)

IMPORTANT MUST ATTENTION plan first — recon →

/plan

/plan-review

--describe

classPattern

keyExtractor

contentPattern

keyGroup

• MUST ATTENTION apply critical thinking — every claim needs traced proof, confidence >80% to act. Anti-hallucination: never present guess as fact. <!-- /SYNC:critical-thinking-mindset:reminder --> <!-- SYNC:ai-mistake-prevention:reminder -->
• MUST ATTENTION apply AI mistake prevention — holistic-first debugging, fix at responsible layer, surface ambiguity before coding, re-read files after compaction. <!-- /SYNC:ai-mistake-prevention:reminder -->