psp_panel/agents.md

AGENT.md

Purpose

• This file defines repository-specific instructions for coding agents.
• Scope is the full repo unless a deeper AGENT.md overrides it.
• Use RTK to reduce token usage, avoid repeated context transfer, and preserve repository knowledge across sessions.

---

⚡ EXECUTION RULES (STRICT)

Minimize reasoning verbosity.

Response Style

Do not:

• narrate thoughts
• speculate
• explain obvious steps
• describe intentions before acting
• write reflective/internal commentary

Avoid messages like:

• "I think I need to..."
• "I should inspect..."
• "I'm going to..."
• "I wonder if..."
• "Let me check..."
• "I'm curious about..."

Instead:

• act immediately
• use short operational updates only when necessary

Good:

Inspecting environment files and Angular configs.

Bad:

I think I should inspect the environment files first to understand how everything is connected before deciding what changes are necessary.

---

🔇 MINIMAL PLANNING MODE

Only create plans when:

• task has multiple independent phases
• task is ambiguous
• task is large/refactor-level

Do not create plans for:

• small fixes
• single-file edits
• obvious tasks

Avoid:

• repeated plan updates
• verbose planning
• unnecessary decomposition

---

✂️ MINIMAL OUTPUT RULES

Keep responses compact.

Do not:

• restate the user request
• explain already-visible edits
• summarize trivial findings
• narrate file discovery
• explain failed reads unless blocking
• describe obvious implementation details

Prefer:

Updated environment files for development, staging, production, and tis.

Avoid:

I found a mismatch and then investigated several files before determining that...

---

📦 FINAL RESPONSE RULES

Final responses must be under 10 lines unless:

• user explicitly asks for explanation
• architectural decisions changed
• validation failed
• multiple systems were affected

Prefer:

Updated:

• file1
• file2

Validation:

• pnpm tsc passed

Avoid:

• long prose summaries
• unnecessary explanations
• repeating repository context

---

🚫 NO TEACHING MODE

Do not explain:

• Angular basics
• TypeScript basics
• RxJS basics
• obvious framework behavior
• standard programming concepts

Assume repository maintainers already understand the stack.

---

🧠 CONTEXT PRESERVATION RULES

Avoid repeating previously established context.

Do not repeatedly mention:

• repository structure
• framework details
• previously inspected files
• known architecture
• already-established conventions

Assume prior context remains valid unless changed.

---

🛑 EXPLORATION STOP RULE

If the likely edit location is identified:

• stop searching
• stop exploring
• implement changes

Do not continue repository exploration after:

• target component found
• target service found
• target config found
• target store found
• target route found

---

🎯 EDIT-FIRST BEHAVIOR

After identifying the target location:

• edit quickly
• avoid excessive inspection
• avoid repeated verification reads
• avoid speculative exploration

Prefer implementation over exploration.

---

✍️ EDIT CONFIDENCE RULES

Prefer direct implementation when:

• existing patterns are obvious
• nearby components establish conventions
• requested change is localized
• existing abstractions already match requirements

Do not over-investigate obvious implementations.

---

⚠️ FAILURE HANDLING RULES

If a file read fails:

• do not retry repeatedly
• verify path once
• continue with nearest valid target

Do not:

• repeatedly attempt missing files
• scan nearby directories unnecessarily
• speculate about missing files
• retry identical commands

---

📏 HARD CONTEXT LIMITS

Do not:

• read more than 2 files before first edit
• read more than 1 sibling file unless required
• reread unchanged files
• inspect unrelated modules

For small tasks:

• maximum 3 repository reads before editing

For medium tasks:

• maximum 8 repository reads before editing

Large/refactor tasks may exceed limits only when necessary.

---

🚫 AVOID MULTI-FILE EAGER READS

Never chain multiple reads in one command unless necessary.

Avoid:

• rtk read a.ts && rtk read b.ts && rtk read c.ts

Prefer sequential targeted reads.

---

✅ RTK-FIRST RULES (STRICT)

Always prefer RTK commands for repository inspection, navigation, and code understanding.

Command Rewrite Rules

Prefer:

• git status -> rtk git status
• git diff -> rtk git diff
• git log -> rtk git log
• ls -> rtk ls
• tree -> rtk ls
• cat -> rtk read
• grep -> rtk grep
• rg -> rtk grep
• find -> rtk find

Avoid raw commands for repository inspection when RTK equivalents exist.

Do not:

• use raw cat for large files
• use raw grep/rg across the repository
• use recursive find blindly
• inspect large diffs with raw git diff
• scan directories manually before searching

Raw commands are allowed only when:

• RTK cannot perform the operation
• executing builds/tests/runtime commands
• debugging environment/runtime issues
• working outside indexed repository scope

---

🧩 FILE READING RULES (IMPORTANT)

Prefer minimal-context reads.

Preferred Order

1. rtk grep
2. rtk smart
3. rtk read
4. aggressive read only if required

Rules

Never immediately read a full file after search.

Before reading:

• identify exact symbol/component/function
• inspect only relevant sections

Prefer:

• rtk smart

before:

• rtk read

For large files:

• rtk read -l aggressive

Only when necessary.

Avoid:

• reading TS + HTML + SCSS together
• opening sibling files preemptively
• rereading files already inspected
• reading generated or unrelated files

---

Angular-Specific Strategy

For Angular components:

1. grep component selector/class
2. smart-read TS file
3. read template only if UI changes required
4. read styles only if styling changes required

Example:

bash rtk grep "invoice-type-card" rtk smart invoice-type-card.component.ts rtk read invoice-type-card.component.html

Avoid:

bash rtk read component.ts rtk read component.html rtk read component.scss

unless all files are actually needed.

📂 CODE NAVIGATION WORKFLOW (MANDATORY)

Follow this order when working in the repository.

1. Discover Structure

bash rtk ls

2. Search Before Opening Files

bash rtk grep <symbol | class | function | DTO | service>

Examples:

bash rtk grep "InputComponent" rtk grep "fieldControl" rtk grep "breadcrumbItems"

3. Read Only Necessary Files

bash rtk read

4. Large File Strategy

For files larger than ~300 lines:

bash rtk read -l aggressive

5. Fast Context Understanding

bash rtk smart

Never:

• open many files blindly
• read entire modules without searching first
• inspect unrelated folders
• load generated directories into context

---

🧠 DIFF INSPECTION RULES

For repository changes use:

bash rtk git diff

For large diffs:

bash rtk git diff -l aggressive

Avoid raw:

bash git diff

unless RTK diff is unavailable.

---

🚫 LOW-VALUE PATHS

Avoid loading:

dist/ .angular/ coverage/ node_modules/ .git/ .cache/ .tmp/

unless explicitly required.

---

RTK Usage Rules

Required RTK Usage

• Always use RTK for:

  • repository indexing
  • semantic code search
  • symbol lookup
  • dependency tracing
  • architectural context
  • change impact analysis

• Prefer RTK context retrieval over:

  • reading large files entirely
  • repeatedly scanning unchanged directories
  • re-sending full file contents
  • broad grep operations

• Retrieve only the minimal relevant context before making changes.

Recommended RTK Workflow

1. Index repository
2. Search related symbols/files/components
3. Retrieve minimal context
4. Apply scoped changes
5. Validate impacted areas only

Example workflow:

bash rtk index rtk search "InputComponent number normalization" rtk search "fieldControl" rtk refs "goodListConfig"

Token Reduction Rules

• Never load entire large files unless required.
• Never inspect generated folders (dist, .angular, coverage, etc.).
• Prefer symbol-level retrieval over file-level retrieval.
• Reuse previously retrieved RTK context whenever possible.
• Avoid duplicate searches for the same symbols within one task.
• Use targeted searches:
  • component name
  • selector
  • signal/store name
  • config constant
  • Angular route
  • injected service
  • form control key

Suggested RTK Queries

Angular Components

bash rtk search "selector: 'field-" rtk search "standalone: true" rtk search "InputComponent"

Forms & Controls

bash rtk search "fieldControl." rtk search "ControlConfig" rtk search "Validators.required"

Stores & Signals

bash rtk search "breadcrumbItems" rtk search "computed(" rtk search "signal("

Tenant / Docker

bash rtk search "DIST_DIR" rtk search "configuration tis" rtk search "prebuild:tis"

List Configs

bash rtk search "IListConfig" rtk search "columns:" rtk search "goodListConfig"

---

Stack Context

• Frontend: Angular 20 standalone app.
• Package manager: pnpm.
• Deployment: Docker / Docker Compose with tenant-specific services.
• AI-assisted repository navigation: RTK.

Current service mapping expectation

• app_default on host port 8090
• app_tis on host port 8091

---

Tenant Build Rules

• default tenant currently builds via ng build and outputs to dist/production.
• tis tenant builds via ng build --configuration tis and outputs to dist/tis.
• prebuild:tis is tenant-scoped and should keep using scripts under scripts/tis/*.
• Keep Docker DIST_DIR aligned with actual Angular output path.
• Do not assume default Angular configuration is usable unless verified (it may reference missing replacements).
• Do not use Angular fileReplacements for static assets (.png, .jpg, etc.); use tenant public assets or prebuild copy scripts.

---

Tenant PWA Rules

• Keep tenant manifest files under tenant public assets (e.g. public-tis/favicon/site.webmanifest).
• Ensure manifest id, start_url, and scope match actual deployment path:
  • root deploy: /
  • subpath deploy example: /tis/
• Keep <link rel="manifest"> path and branding config manifestPath aligned.

---

Input Component Rules

File:

• src/app/shared/components/input/input.component.ts

For:

• type === 'number'
• type === 'price'

Requirements:

• Normalize Persian/Arabic digits to English digits.
• Allow only digits and ..
• Support fixed precision formatting when provided.

Additional rule:

• Keep behavior for identifier fields (mobile, phone, postalCode, nationalId) string-safe.

---

Change Policy

• Keep changes minimal and scoped to user request.
• Prefer root-cause fixes over temporary workarounds.
• Avoid unrelated refactors.
• Reuse existing patterns and naming conventions.
• Use RTK to understand existing patterns before introducing new ones.

---

Do / Don't

Do

• Follow existing field wrapper style in:
  • src/app/shared/components/fields/*.component.ts
• Reuse app-input and set only required props:
  • type
  • label
  • name
  • constraints
• Register every new field in:
  • src/app/shared/components/fields/index.ts
  • src/app/shared/constants/fields/index.ts
• Keep control keys consistent across:
  • form group
  • field component name
  • fieldControl key
• Use RTK searches before creating new abstractions.

Don't

• Don't add one-off field patterns when an existing field component can be reused.
• Don't use invalid Angular file replacements for directories or empty paths.
• Don't change tenant output directories without updating Docker DIST_DIR.
• Don't scan unrelated folders/files when RTK can retrieve exact symbols.
• Don't load full files if RTK symbol extraction is sufficient.

---

How To Create Form Fields

• Create a wrapper component in:
  • src/app/shared/components/fields
• Use the same pattern as existing files like:
  • src/app/shared/components/fields/name.component.ts
  • src/app/shared/components/fields/unit_price.component.ts

Minimal wrapper shape:

ts @Component({ selector: 'field-example', template: <app-input [label]="label" [control]="control" [name]="name" type="simple" />, imports: [ReactiveFormsModule, InputComponent], }) export class ExampleComponent { @Input({ required: true }) control = new FormControl(''); @Input() name = 'example'; @Input() label = 'Example'; }

---

Register New Fields

Export the component from:

• src/app/shared/components/fields/index.ts

Add its form control factory in:

• src/app/shared/constants/fields/index.ts

fieldControl entry shape:

• key must match form control name
• return tuple: [defaultValue, validators]

Example:

ts example: (value = '', isRequired = true): ControlConfig => [ value, isRequired ? [Validators.required] : [], ],

---

Using Fields In Forms

• In form group builders, use:
  • fieldControl.<key>(initialValue, isRequired)
• In templates, render matching wrapper component and pass matching control:
  • <field-example [control]="form.controls.example" />
• For numeric/price behavior:
  • use app-input
  • use type="number" or type="price"
  • optional [fixed]

---

List Component Configs

Centralized list metadata is stored in:

• src/app/shared/constants/list-configs/

Never store configs inside domain modules.

Structure

Structure by data type, not domain:

• good-list.const.ts
• sku-list.const.ts
• category-list.const.ts

Requirements

Each config implements IListConfig:

• pageTitle
• addNewCtaLabel
• emptyPlaceholderTitle
• emptyPlaceholderDescription
• columns

Usage

ts @Input() header: IColumn[] = goodListConfig.columns; listConfig = goodListConfig;

Rules

• Any domain needing a list config imports from:
  • @/shared/constants/list-configs
• No cross-domain dependencies.
• Do not duplicate configs.

---

Breadcrumb Usage in Stores & Views

• Entity stores expose breadcrumbItems as a computed signal.
• Call store.breadcrumbItems() in view components and extend with current page:

ts setBreadcrumb() { this.breadcrumbService.setItems([ ...this.store.breadcrumbItems(), { title: 'Current Page' }, ]); }

• Root page breadcrumbs are set in the store's getData() method once entity is loaded.

---

Validation Checklist

TypeScript-only changes

bash pnpm -s exec tsc -p tsconfig.app.json --noEmit

Docker/build changes

bash docker compose build app_default docker compose build app_tis

Validation Strategy

• Start with targeted validation.
• Run broader checks only if needed.
• Validate only impacted tenants/features when possible.

---

Communication Expectations

• Report exactly which files changed and why.
• Call out assumptions and discovered config mismatches.
• If validation is blocked:
  • explain why
  • provide next command
• Mention RTK searches/symbols used when relevant to implementation decisions.

---

Preferred Investigation Order

Before editing code:

1. RTK symbol search
2. Existing implementation discovery
3. Shared abstraction verification
4. Minimal scoped change
5. Targeted validation

Avoid:

• broad exploratory reads
• repeated file dumping
• unnecessary context expansion

---

Angular Architecture Preferences

• Prefer standalone components.
• Prefer signals/computed over legacy observable-only state when consistent with current architecture.
• Keep forms typed.
• Keep reusable UI in shared.
• Keep domain logic outside presentation components.
• Preserve existing tenant separation model.

---

Performance & AI Efficiency

• Optimize for:
  • minimal token usage
  • minimal file reads
  • scoped context retrieval
  • reusable architectural understanding

Prefer:

• RTK symbol search
• targeted reads
• incremental inspection

Avoid:

• dumping full files

• repeated repository scans

• repeated searches for the same symbols

• unnecessary architectural exploration

• RTK should be the primary repository understanding tool.