Skip to content

AGENTS.md

Latest commit

 

History

History
64 lines (57 loc) · 5.96 KB

AGENTS.md

File metadata and controls

64 lines (57 loc) · 5.96 KB
Raw

GLOBAL WORKSPACE CONSTITUTION

These rules apply to ALL agents operating in this workspace.

1. Language & Communication

  • Communication: I might speak to you in Polish or English depending on my mood. You MUST understand both perfectly!!!
  • Style: Keep your responses concise, professional, and straight to the point.

2. Code Standards (No Comments Rule)

  • Self-Documenting: Write clean code. ABSOLUTELY NO COMMENTS IN CODE FILES explaining what the code does.
  • If the logic is complex, explain it to me here in the chat, not inside the files.
  • The only exception is official JSDoc/Docstrings for public APIs, but keep them minimal.
  • Formatting: No unnecessary whitespace or "TODO" notes.

3. Persistent Memory (Macrodata)

You are equipped with a persistent memory system (Macrodata). You don't have amnesia between sessions.

  • JOURNALING (MANDATORY): Every time you implement a significant feature, solve a bug, or reach a technical decision, you MUST use macrodata_log_journal to record it (use @general agent).
  • RECALL FIRST: If you lack context or don't remember a decision, ALWAYS use macrodata_search_memory or macrodata_search_conversations (use @general agent) BEFORE asking the user for information.
  • KNOWLEDGE ENTITIES: For complex project architectures or long-term technical topics, create/update dedicated files in ~/.config/macrodata/entities/projects/ (use @general agent).

4. Git Protocol & Environment

  • CRITICAL: Use @developer-experience/git-workflow-manager for git management !!!
  • Work directly in the main terminal.
  • ALWAYS create a new branch for every task using git checkout -b <branch_name>.
  • Merge to main only after the task is fully implemented, tested, and verified.
  • Delete local branches after merging to keep the repository clean, but ask me first if you can do it !!!
  • At the start of a new project, if .git is missing, you MUST run git init, set branch to main, and create an empty initial commit.

5. Web Scraping & External Documentation (Crawl4AI Protocol)

  • TOOLING (CRITICAL): You have native bash access to the crwl CLI (Crawl4AI). Use it PROACTIVELY to read external documentation, scrape data, or check API references. DO NOT HALLUCINATE code syntax or library structures!
  • HOW IT WORKS: crwl spins up a browser, renders JS, bypasses anti-bots, removes UI noise, and extracts pristine, LLM-ready Markdown.
  • THE PIPELINE (MANDATORY): If you need internet data, YOU MUST follow this exact sequence:
    1. Fetch data to a temp file: crwl <URL> [args] > temp_docs.md (or use -o temp_docs.md)
    2. Read the file into your context: cat temp_docs.md
    3. Analyze the actual data and implement the code.
    4. Cleanup immediately: rm -f temp_docs.md
  • COMMAND EXAMPLES:
    • Single Page Docs: crwl https://docs.example.com/guide -o temp_docs.md
    • Deep Crawling (API references): crwl https://docs.example.com/api --deep-crawl bfs --max-pages 5 -o temp_docs.md
    • Structured Data Extraction: crwl https://example.com/pricing -q "Extract all plan names and prices" -o data.json
  • EXECUTION RULE: Do not delegate this if you have bash access. Execute it yourself in the terminal. If a site uses infinite scroll or lazy loading, trust crwl to handle it automatically.

6. Code Intelligence & Architecture (GitNexus Protocol)

  • INITIALIZATION (MANDATORY):
    • If you start on an existing codebase, your FIRST ACTION must be to run: gitnexus analyze . --embeddings --skills ; rm -f AGENTS.md CLAUDE.md. This builds your "architectural brain" and documentation.
    • EMPTY REPOSITORY PROTOCOL: If the repository is empty, you MUST:
      1. Initialize git: git init.
      2. Implement the initial code structure.
      3. Create the first commit: git add . && git commit -m "initial commit".
      4. THEN run: gitnexus analyze . --embeddings --skills ; rm -f AGENTS.md CLAUDE.md.
  • POST-IMPLEMENTATION: After any significant refactor, new feature implementation, or merge, you MUST re-run gitnexus analyze . --embeddings --skills ; rm -f AGENTS.md CLAUDE.md to keep your knowledge graph and skills in sync with the code.
  • TOOLING (CRITICAL): You are connected to the GitNexus MCP, which provides a deep relational knowledge graph of the entire codebase. DO NOT rely on blind grep or file reading to understand architecture or call chains.
  • CLI FALLBACK PROTOCOL (CRITICAL): Your primary method is using MCP tools (gitnexus_impact, gitnexus_query, etc.). However, if the MCP server times out or returns an error (like Connection closed), you MUST immediately fall back to using the gitnexus CLI in the bash terminal.
    • CLI Equivalents:
      • MCP gitnexus_query -> Bash: gitnexus query "search terms"
      • MCP gitnexus_context -> Bash: gitnexus context <symbol_name>
      • MCP gitnexus_impact -> Bash: gitnexus impact <symbol_name> --direction upstream
      • MCP gitnexus_rename -> Bash: gitnexus rename <old_name> <new_name>
    • IMPORTANT: When using CLI in bash, DO NOT use the --repo flag if you are already inside the project directory. Just run the commands directly.
  • MANDATORY IMPACT ANALYSIS: Before modifying ANY existing function, class, or method, you MUST run the gitnexus_impact tool (or CLI fallback). If the blast radius is HIGH or CRITICAL, warn the user before proceeding.
  • EXPLORE BEFORE CODING: When investigating bugs or learning how a feature works, use gitnexus_query to find execution flows, and gitnexus_context to get a 360-degree view of a symbol.
  • PRE-COMMIT VALIDATION: ALWAYS run the gitnexus_detect_changes tool (or gitnexus detect_changes in bash) before committing.
  • SAFE REFACTORING: Never use simple find-and-replace for renaming. ALWAYS use the gitnexus_rename tool (or CLI fallback).
  • INDEX MAINTENANCE (CRITICAL): The graph is NOT real-time. After ANY significant change, merge, or branch switch, you MUST re-run: gitnexus analyze . --embeddings --skills ; rm -f AGENTS.md CLAUDE.md.