sass-mohfarawati/AGENTS.md

Agent Instructions

Use documentation selectively.

Always read the minimum relevant documentation before making changes.

Required documentation by task type

Small scoped changes

For small UI fixes, copy updates, styling adjustments, or isolated bug fixes:

• read only the directly relevant files
• do not read project-wide documentation unless needed

Feature-scoped changes

For changes affecting an existing feature:

• read the matching file in specs/
• read docs/ARCHITECTURE.md only if the change affects structure or flow

Large or cross-cutting changes

For new features, architecture changes, domain rule changes, or public behavior changes:

• read:
  • docs/ARCHITECTURE.md
  • docs/DOMAIN_RULES.md
  • docs/FEATURES.md
• also read the matching file in specs/ when applicable

Core rules

• Do not introduce new patterns, abstractions, or frameworks unless explicitly requested.
• Do not refactor unrelated code.
• Do not rename files, folders, database fields, or public interfaces unless explicitly requested.
• Follow the existing folder structure and module boundaries.
• Keep changes minimal, scoped, and consistent with the current codebase.
• Reuse existing primitives, services, validators, helpers, and utilities whenever possible.
• Preserve the current implementation unless the task explicitly requires changing it.

Documentation updates

Update documentation only when implementation changes affect:

• feature scope
• business rules
• architectureڑڑ
• public behavior

Do not update documentation for small isolated fixes or purely visual changes.

Update only the relevant files in:

• docs/
• specs/

Keep documentation aligned with the real implementation, not assumptions.

Git Commit Messages

Use this format:

TYPE - Short summary

- First concrete change
- Second concrete change
- Third concrete change

Allowed types: ADDED, IMPROVED, FIXED, CHANGED, REFACTORED, OPTIMIZED, REMOVED, UPDATED, SECURED, TESTED, DOCUMENTED, STYLED, CONFIGURED, RENAMED, MOVED, CLEANED, REVERTED

Rules:

• Write commit messages in English.
• Use uppercase type names.
• Keep the title concise.
• Add a blank line before the bullet list.
• Describe only the actual changes in the commit.
• Inspect git diff --cached before writing the message.
• Do not add AI attribution or Co-Authored-By.
• Do not create commits unless explicitly requested (see Core Rules above).

graphify (when present)

• For codebase questions, if graphify-out/graph.json exists, run graphify query "<question>" first. Use graphify path "<A>" "<B>" for relationships and graphify explain "<concept>" for focused concepts — these return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
• If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
• Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain don't surface enough context.
• After modifying code, run graphify update . to keep the graph current (AST-only, no API cost).