Skip to content

AGENTS.md

Latest commit

 

History

History
86 lines (65 loc) · 5.11 KB

AGENTS.md

File metadata and controls

86 lines (65 loc) · 5.11 KB

Working with Dani

General Indications

  • YOU MUST ALWAYS address me as "Dani" in all communications.
  • When reporting information to Dani, be extremely concise and sacrifice grammar for the sake of concision.

Code Writing

  • We STRONGLY prefer simple, clean, maintainable solutions over clever or complex ones. Readability and maintainability are PRIMARY CONCERNS, even at the cost of conciseness or performance.
  • YOU MUST make the SMALLEST reasonable changes to achieve the desired outcome.
  • YOU MUST MATCH the style and formatting of surrounding code, even if it differs from standard style guides. Consistency within a file trumps external standards.
  • YOU MUST NEVER make code changes unrelated to your current task. If you notice something that should be fixed but is unrelated, document it rather than fixing it immediately.
  • YOU MUST NEVER remove code comments unless you can PROVE they are actively false. Comments are important documentation and must be preserved.
  • All code files MUST start with a brief 2-line comment explaining what the file does. Each line MUST start with "ABOUTME: " to make them easily greppable.
  • YOU MUST NEVER refer to temporal context in comments (like "recently refactored"). Comments should be evergreen and describe the code as it is.
  • YOU MUST NEVER implement mock modes for testing or any purpose. We always use real data and real APIs.
  • YOU MUST NEVER throw away implementations to rewrite them without EXPLICIT permission. If you're considering this, YOU MUST STOP and ask first.
  • YOU MUST NEVER use temporal naming conventions like 'improved', 'new', or 'enhanced'. All naming should be evergreen.
  • YOU MUST NOT change whitespace unrelated to code you're modifying.
  • YOU MUST preserve backward-compatible API and behavioral contracts unless Dani explicitly asks for a breaking change.
  • YOU MUST prefer targeted fixes over broad refactors, and YOU MUST validate changed behavior with the smallest effective check before proposing broader runs.
  • YOU MUST avoid introducing secrets, credentials, tokens, private keys, or private certificates into the repository.
  • YOU MUST avoid introducing insecure patterns such as injection paths, auth bypasses, unsafe deserialization, or unvalidated file-processing flows.

Version Control

  • For non-trivial edits, all changes MUST be tracked in git.
  • If the project isn't in a git repo, YOU MUST STOP and ask permission to initialize one.
  • If there are uncommitted changes or untracked files when starting work, YOU MUST STOP and ask how to handle them. Suggest committing existing work first.
  • When starting work without a clear branch for the current task, YOU MUST create a WIP branch.
  • YOU MUST commit frequently throughout the development process.

Getting Help

  • YOU MUST ALWAYS ask for clarification rather than making assumptions.
  • If you're having trouble, YOU MUST STOP and ask for help, especially for tasks where human input would be valuable.

Agents Workflow

Analyzer agents are for analysis and exploration only. They write findings to doc/features/<issue_title>/<analyzer_topic>.md and NEVER modify code.

This repo ships a reference example (api-contract-analyzer) and a template. Use the create-agent skill to create agents tailored to this project's architecture and domain. List the available agents here once created.

If analyzer delegation is used, the delegating agent MUST define:

  • target files or scope to inspect
  • expected output artifact
  • explicit forbidden areas
  • verification or reproduction commands when relevant

Analyzer results MUST include:

  • what was inspected
  • findings and reasoning
  • any verification performed
  • open questions or unverified assumptions

Project Documentation

  • For general project information, refer to /doc/general/:
    • API.md - API endpoints reference.
    • ARCHITECTURE.md - Architecture and design decisions.
    • DEPLOYMENT.md - Deployment guide.
    • DEVELOPMENT.md - Development workflow and commands.
  • These files contain essential context about the project structure, technology stack, and workflows.

If those are not created, ask to the user to start creating 1 by 1.

Testing

  • Tests MUST comprehensively cover ALL implemented functionality.
  • YOU MUST NEVER ignore system or test output - logs and messages often contain CRITICAL information.
  • Test output MUST BE PRISTINE TO PASS.
  • If logs are expected to contain errors, these MUST be captured and tested.
  • NO EXCEPTIONS POLICY: ALL projects MUST have unit tests, integration tests, AND end-to-end tests. The only way to skip any test type is if Dani EXPLICITLY states: "I AUTHORIZE YOU TO SKIP WRITING TESTS THIS TIME."
  • For localized edits, YOU SHOULD run targeted checks first before broader suites.
  • When reporting completion, YOU MUST state what was verified and what was not verified.

Compliance Check

Before submitting any work, verify that you have followed ALL guidelines above. If you find yourself considering an exception to ANY rule, YOU MUST STOP and get explicit permission from Dani first.

Final handoff MUST report:

  • files changed
  • behavioral impact
  • checks executed and outcomes
  • residual risks, follow-ups, or unverified areas